linkong/planet

Fork 0

Files

linkong 7418ce2fc1 release: bump version to 0.46.1

2026-04-30 09:41:08 +08:00

16 KiB

Raw Blame History

Planet 使用手册

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

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

快速启动路径见快速开始。

入口总览

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

名称	地址	是否需要登录	说明
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`	在执行过程中显示更多命令输出

AI Provider 环境变量和构建

AI Provider 的运行期配置可以放在两处：

位置	适合内容	说明
`aiprovider/.env`	团队约定的本地默认配置	Docker Compose 会作为 `env_file` 读取
`~/.zshrc`	个人机器上的 provider、模型、密钥和代理变量	`planet.sh` 启动时会读取常见的 `AI_`、`SERVICE_`、`PYTHON_IMAGE`、`UV_IMAGE`、代理变量

推荐写法：

export AI_PROVIDER=minimax
export AI_PROVIDER_API=anthropic-messages
export AI_BASE_URL=https://api.example.com/anthropic
export AI_API_KEY=sk-change-me
export AI_MODEL=MiniMax-M2.7
export AI_PROVIDER_SERVICE_TOKEN=change_me

默认情况下，planet.sh 只静态解析 ~/.zshrc 中简单的 export KEY=value 或 KEY=value 行，避免 shell 主题、插件或交互初始化拖慢启动。如果变量依赖复杂 shell 展开，可以显式启用 source 模式：

PLANET_LOAD_ZSHRC_ENV=source ./planet.sh start -a

如需完全忽略 ~/.zshrc：

PLANET_LOAD_ZSHRC_ENV=0 ./planet.sh start -a

AI Provider 镜像只在代码、Dockerfile、Compose 配置或相关 Python 依赖变化时重建。修改 aiprovider/.env 或 ~/.zshrc 中的模型、密钥、Base URL 不会触发镜像重建；重启 AI Provider 即可让容器读取新配置：

./planet.sh restart -a

构建较慢时，优先判断当前卡在哪一层：

现象	常见原因	处理方式
`transferring context` 很大	Docker build context 包含前端资源、PDF、数据目录等无关文件	当前仓库通过 `.dockerignore` 只发送 AI Provider 必需文件
`uv sync` 下载依赖较慢	首次构建或缓存为空，网络访问 Python 包较慢	等待首次构建完成；后续会复用 BuildKit 的 uv 下载缓存
改密钥后仍显示旧配置	容器尚未重启	执行 `./planet.sh restart -a`

停止

./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 观测
卫星
AIS 船只
轨迹
地形

部分图层存在依赖关系：

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

图例

左下角图例会跟随当前聚焦或启用的图层切换。

当前已覆盖：

海缆
卫星
国界
算力中心
BGP
AIS 船只

AIS 船只图例按船型显示颜色：

货轮
油轮
客船
渔船
军舰
停泊/低速
其他船只

船只图例中的三角形对应地图上的航行船只标记，圆点对应停泊或低速状态。

搜索

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

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

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

设置

设置面板包含：

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

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

视角控制

Earth 支持鼠标、触控板和触屏操作。

常用控制方式：

操作	作用
鼠标左键拖动	旋转地球
手指单指拖动	在触屏设备上旋转地球
鼠标滚轮	放大或缩小视角
双指捏合	在触屏设备上放大或缩小视角
缩放按钮	按固定步长调整缩放
点击缩放百分比	重置到默认缩放

缩放时，顶部胶囊会短暂显示当前缩放比例，例如 缩放 180%。这个提示只表示当前视角缩放，不代表数据加载进度；如果页面正在加载数据，加载提示优先显示，缩放提示不会打断加载状态。

拖动灵敏度会根据当前缩放自动调整。默认视角附近保持常规旋转速度；放大后拖动会逐步变细，适合检查某个区域、船只、卫星或 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 用于查看采集来源和触发采集。当前页面是“数据源目录”，会把内置数据源和自定义数据源放在同一张列表里展示。

常见操作：

查看数据源状态
触发采集
查看最近采集任务
打开详情抽屉查看 endpoint、请求头、基础配置和是否为内置数据源

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

数据源列表中的名称点击后只打开信息抽屉，不再承担编辑入口。接口地址、凭证、请求头和自定义数据源配置统一到 /settings 的“采集器设置”里维护。

当有采集任务正在运行时，总体进度下方会出现 采集中 N 标签。这个标签和其他状态标签放在同一排，但带有可点击样式；点击后会弹出当前采集中任务列表，显示每个任务的阶段、进度和处理数量。

采集数据

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

适合排查：

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

BGP 观测

/bgp 是 BGP 专题页面。

它和 Earth 的 BGP 图层互补：

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

告警

告警入口包括：

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

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

系统配置

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

当前常见用途包括：

系统设置
电视直播源配置
采集器设置
外部集成和 AI Provider 配置

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

采集器设置

/settings?tab=collector_credentials 当前显示为“采集器设置”。这里统一维护所有采集器的连接配置，而不是只维护凭证。

使用方式：

在下拉框选择采集器。
查看状态标签：
- 无需凭证 / 需要凭证
- 所属模块
- 启用 / 禁用
- 未检查 / 可用 / 不可用
点击下拉框右侧的插头图标执行健康检查。
如果检查通过，状态会变为 可用。
修改 endpoint、请求头、超时或重试次数后保存。

对于免费且不需要凭证的采集器，连接检查会直接请求对应 endpoint。对于需要凭证的采集器，连接检查会走对应凭证链路；如果凭证或 endpoint 相比上次验证成功时发生变化，需要重新点击连接。

系统判断“已连接”的条件是：

当前配置已经成功采集过数据；或
当前配置已经点击过连接按钮并验证成功。

BarentsWatch AIS 凭证

BarentsWatch AIS 是需要凭证的内置采集器。选择该采集器后，凭证区域会显示在基础配置上方。

配置项：

Client ID
Client Secret
Endpoint

如果已经配置过 secret，输入框会显示脱敏预览。保存时如果保持这个脱敏预览不变，系统会保留原 secret；只有输入新的 secret 才会替换。

BarentsWatch AIS 支持从以下位置读取凭证：

控制台采集器设置中保存的凭证。
后端环境变量：
- BARENTSWATCH_CLIENT_ID
- BARENTSWATCH_CLIENT_SECRET
- 兼容历史拼写：BARRENTSWATCH_CLIENT_ID、BARRENTSWATCH_CLIENT_SECRET
~/.zshrc 中的同名 export。

如果连接失败，页面会弹出凭证获取教程。教程支持：

查看默认教程。
点击“教程不好用”让 AI Provider 根据默认 prompt 重新生成教程。
点击“重置”恢复默认教程。

默认教程以 BarentsWatch 官方 tutorial 为准，并提醒 Live AIS 应选择 AIS - API，不是普通 BarentsWatch - API。

系统日志

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

排查问题时常用组合：

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

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

Docs

公开文档站入口：

http://localhost:3000/docs

当前公开内容来自：

docs/technical/zh/*.md
docs/technical/en/*.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

16 KiB Raw Blame History Unescape Escape