linkong/planet

Fork 0

Files

linkong ac69d5d354 release: bump version to 0.43.0

2026-04-28 16:10:17 +08:00

9.8 KiB

Raw Blame History

Planet 使用手册

这份手册面向日常使用、演示、开发联调和本地运维。它覆盖四个核心入口：

planet.sh：本地启动、停止、重启、健康检查和日志入口
Earth：公开 3D 地球态势页面
控制台：登录后的管理后台
Docs：公开开发文档与使用手册

快速启动路径见 quickstart.md。

入口总览

默认启动后，常用地址如下：

名称	地址	是否需要登录	说明
Earth	`http://localhost:3000/earth`	否	3D 地球、图层、BGP、卫星、海缆、新闻态势
Docs	`http://localhost:3000/docs`	否	开发文档、技术说明、使用手册
控制台	`http://localhost:3000/admin`	是	数据、配置、告警、日志和专题观测
AI Playground	`http://localhost:3000/playground`	是	AI Provider 状态和调试
后端 API 文档	`http://localhost:8000/docs`	视接口而定	FastAPI / OpenAPI 文档

planet.sh

planet.sh 是本地开发和演示的主控脚本。优先使用它管理服务，而不是手动分别启动前端、后端、数据库和 AI Provider。

启动

./planet.sh start

默认行为：

启动 PostgreSQL 和 Redis
启动 AI Provider
启动后端 API
启动前端 Vite dev server
输出 Earth、控制台、Playground 和后端 API 文档入口

可指定端口：

./planet.sh start -b 8001 -f 3001 -a 8101

参数含义：

参数	含义
`-b <port>`	后端端口
`-f <port>`	前端端口
`-a <port>`	AI Provider 端口
`--allow-lan`	允许局域网访问
`--verbose`	在执行过程中显示更多命令输出

停止

./planet.sh stop

会停止：

后端
AI Provider
前端
PostgreSQL
Redis

重启

全量重启：

./planet.sh restart

按模块重启：

./planet.sh restart -b
./planet.sh restart -f
./planet.sh restart -a
./planet.sh restart -d

参数	作用
`-b`	只重启后端
`-f`	只重启前端
`-a`	只重启 AI Provider
`-d`	只重启数据库

按模块重启适合日常开发，能避免无关服务被打断。

创建用户

./planet.sh createuser

用于首次进入控制台前创建登录账号。脚本会交互式提示用户名、密码和角色。

健康检查

./planet.sh health

会检查：

planet_* 容器状态
后端 /health
AI Provider /health
前端页面可达性

如果某项显示 offline，优先查看对应日志。

日志

参数	日志来源
`-f` / `--frontend`	`/tmp/planet_frontend.log`
`-b` / `--backend`	`/tmp/planet_backend.log`
`-a` / `--ai-provider`	`planet_aiprovider` 容器日志

局域网访问

./planet.sh start --allow-lan

适合：

WSL 中启动，Windows 浏览器访问
手机或平板演示 Earth
局域网其他机器访问同一个开发实例

启动后注意检查防火墙和 WSL 网络转发。

Earth

Earth 是公开的 3D 态势页面，入口：

http://localhost:3000/earth

它是独立前端，实际页面位于：

frontend/public/earth/index.html
frontend/public/earth/js/
frontend/public/earth/css/

React 路由中的 /earth 只是用 iframe 承载它。

主要用途

Earth 用于在一个地球视图中观察：

BGP 事件、异常和观测态势
卫星和轨迹
海缆与登陆点
算力中心
国界、经纬线、高清材质、云图、地形
新闻直播和态势新闻
搜索和聚焦对象详情

图层控制

右侧图层面板用于打开或关闭可视图层。

常见图层包括：

经纬线
国界
高清材质
大气云图
海缆
算力中心
BGP 观测
卫星
轨迹
地形

部分图层存在依赖关系：

地形依赖高清材质
轨迹依赖卫星
高清材质关闭时，地球会显示基座地图和边缘识别效果

搜索

Earth 搜索支持查找当前地球对象，例如：

海缆
登陆点
卫星
算力中心
BGP 事件
BGP 观测站

搜索结果可以用于快速定位对象，并打开对应详情。

设置

设置面板包含：

旋转模式 / 巡航模式
巡航模块：BGP、新闻
卫星显示风格：自身发光、真实地表覆盖
日夜模式
面板显示开关
地球默认大小
地形透明度
重置设置

这些设置会保存在浏览器本地存储中。换浏览器或清理站点数据后会恢复默认值。

巡航模式

巡航模式会让 Earth 自动轮播聚焦目标。

当前巡航模块包括：

BGP
新闻

适合演示、监控大屏或无人值守展示。

移动端

Earth 有移动端抽屉布局。小屏下：

图层控制进入移动抽屉
搜索、设置、详情会使用移动端面板
主要交互仍围绕地球对象点击、搜索和图层开关

常见问题

Earth 打不开

先检查前端是否在线：

./planet.sh health
./planet.sh log -f

如果前端端口不是 3000，使用启动时输出的实际端口。

图层没有数据

检查后端和数据源：

./planet.sh health
./planet.sh log -b

然后进入控制台查看：

/datasources
/data
/bgp

卫星、BGP 或海缆加载慢

这些图层可能依赖后端接口、外部数据源或首次加载任务。先等待启动任务完成，再查看日志和控制台数据源状态。

控制台

控制台入口：

http://localhost:3000/admin

控制台需要登录。首次使用先创建用户：

./planet.sh createuser

页面结构

控制台使用 React + Ant Design，左侧菜单按工作域组织。

常见入口：

页面	路由	用途
仪表盘	`/admin`	系统概览
Earth	`/earth`	打开公开 Earth 页面
数据源	`/datasources`	管理数据源和触发采集
采集数据	`/data`	查看采集后的数据
BGP 观测	`/bgp`	查看 BGP 专题数据
系统告警	`/alerts/system`	系统级告警
BGP 告警	`/alerts/bgp`	BGP 相关告警
态势告警	`/alerts/situational`	态势研判告警
AI Playground	`/playground`	AI Provider 调试
系统日志	`/logs`	查看系统日志，通常仅 super admin 可见
用户管理	`/users`	管理用户
系统配置	`/settings`	系统配置和电视直播源等设置

数据源

/datasources 用于查看和管理采集来源。

常见操作：

查看数据源状态
触发采集
查看最近采集任务
调整配置项

如果 Earth 上某类对象缺失，通常先到这里确认数据源是否可用。

采集数据

/data 用于查看采集后的数据表。

适合排查：

数据是否已经进入系统
数据更新时间是否符合预期
某个数据源是否产出了有效记录

BGP 观测

/bgp 是 BGP 专题页面。

它和 Earth 的 BGP 图层互补：

Earth 强调空间态势和可视聚焦
控制台 BGP 页面强调列表、状态、详情和研判

告警

告警入口包括：

/alerts/system
/alerts/bgp
/alerts/situational

用于查看系统、网络和态势相关告警。

系统配置

/settings 用于管理系统级配置。

当前常见用途包括：

系统设置
电视直播源配置
数据源相关配置入口

具体可用配置取决于当前登录用户权限。

系统日志

/logs 用于查看系统日志。若菜单中不可见，通常是当前用户角色没有权限。

排查问题时常用组合：

./planet.sh health
./planet.sh log

再进入 /logs 查看更结构化的运行信息。

Docs

公开文档站入口：

http://localhost:3000/docs

当前公开内容来自：

docs/technical/*.md

Docs 支持：

分类导航
Markdown 渲染
表格和代码块
文档内目录
本地搜索
technical 文档之间的内部链接跳转

如果新增 technical 文档，应同步检查：

是否有清晰的一级标题
是否需要加入 /docs 的人工分类和排序
是否包含不适合公开展示的信息

开发命令约定

前端命令必须使用 Bun：

cd frontend
bun install
bun run dev
bun run build

不要使用 npm run ...。项目在 WSL / Windows 混合环境中优先依赖 Bun，避免 Node/npm 路径差异带来的兼容问题。

验证前端构建：

source ~/.zshrc && bun run build

故障排查顺序

遇到问题时，建议按这个顺序排查：

看服务状态：

./planet.sh health

看最近日志：

./planet.sh log

按模块查看日志：

./planet.sh log -f
./planet.sh log -b
./planet.sh log -a

只重启有问题的模块：

./planet.sh restart -f
./planet.sh restart -b
./planet.sh restart -a

如果数据库或缓存异常，再重启数据库：

./planet.sh restart -d

仍无法恢复时，执行全量重启：

./planet.sh restart

9.8 KiB Raw Blame History Unescape Escape