planet/docs/technical/zh/manual.md

Planet 使用手册

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

• planet.sh：本地启动、停止、重启、健康检查和日志入口
• Earth：公开 3D 地球态势页面
• 控制台：登录后的管理后台
• Docs：后端 Gatekeeper 受控的文档站，基础使用文档公开，开发/运维文档按权限组开放

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

入口总览

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

名称	地址	是否需要登录	说明
Earth	http://localhost:3000/earth	否	3D 地球、图层、BGP、卫星、海缆、新闻态势
Docs	http://localhost:3000/docs	部分需要	使用手册公开；开发、后端、运维文档按 Gatekeeper 权限组开放
控制台	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，优先查看对应日志。

日志

最近日志：

./planet.sh log

持续跟随日志：

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

参数	日志来源
-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
• 局域网其他机器访问同一个开发实例

--allow-lan 只负责让前端和后端监听 0.0.0.0。如果服务运行在 WSL 中，Windows 本机通常可以通过 localhost 访问，但手机或其他电脑访问 http://<Windows局域网IP>:3000 还依赖 Windows 端口转发和防火墙放行。

推荐按顺序判断：

# 在 WSL 或运行 Planet 的 shell 中
curl http://localhost:3000
curl http://localhost:8000/health
ss -ltnp | grep -E ':3000|:8000'

如果这里能看到 0.0.0.0:3000 和 0.0.0.0:8000，但局域网 IP 访问失败，请在管理员 PowerShell 中配置：

netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=3000 connectaddress=127.0.0.1 connectport=3000
netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=8000 connectaddress=127.0.0.1 connectport=8000

New-NetFirewallRule -DisplayName "WSL Planet 3000" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 3000
New-NetFirewallRule -DisplayName "WSL Planet 8000" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 8000

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 观测站详情卡支持自动采集坐标候选。点击对象后，使用详情卡中的 自动采集坐标候选 或 重新自动采集坐标 按钮，后端会从源坐标、开放组织注册 API 和在线地理编码中整理候选位置。BGP 观测站的已存储位置只用于补齐查询上下文，不会作为候选直接返回。

候选可以直接在 Earth 上预览。算力中心候选点击 保存 后会写入 compute_center_locations 维表，并立即刷新图层。算力中心图层左上角的通知气泡显示无法渲染的待定位数量；点击后可查看列表，单条采集候选，或用 一键采用 从上到下保存最高置信候选。没有可用候选的记录会留在列表中，不会被国家中心点或硬编码 hint 伪造位置。详细流程见 Earth 位置候选采集使用手册。

设置

设置面板包含：

• 旋转模式 / 巡航模式
• 巡航模块：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 当前显示为“采集器设置”。这里统一维护所有采集器的连接配置，而不是只维护凭证。

使用方式：

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

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

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

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

BarentsWatch AIS 凭证

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

配置项：

• Client ID
• Client Secret
• Endpoint

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

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

1. 控制台采集器设置中保存的凭证。
2. 后端环境变量：
   • BARENTSWATCH_CLIENT_ID
   • BARENTSWATCH_CLIENT_SECRET
   • 兼容历史拼写：BARRENTSWATCH_CLIENT_ID、BARRENTSWATCH_CLIENT_SECRET
3. ~/.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 正文由后端 API 按权限读取，不再把全部 Markdown 直接打进前端构建产物。当前文档源文件仍位于：

docs/technical/zh/*.md
docs/technical/en/*.md

未登录访客默认只能看到 public 文档，例如首页、快速开始和使用手册。登录用户如果被分配 Gatekeeper 权限组，可以看到更多技术文档：

• docs_user：用户操作类文档。
• docs_developer：Earth、前端、后端、采集器和 AI Provider 等开发文档。
• docs_admin：服务控制、运维、环境变量和敏感操作文档。

admin 默认拥有管理文档权限，super_admin 拥有全部 Docs 权限。Gatekeeper 权限组在控制台“用户管理”中配置。

Docs 支持：

• 分类导航
• Markdown 渲染
• 表格和代码块
• 文档内目录
• 对当前可见文档搜索
• technical 文档之间的内部链接跳转

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

• 是否有清晰的一级标题
• 是否需要加入后端 Docs metadata 的人工分类和排序
• 应归入 public、docs_user、docs_developer 还是 docs_admin

开发命令约定

前端命令必须使用 Bun：

cd frontend
bun install
bun run dev
bun run build

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

验证前端构建：

source ~/.zshrc && bun run build

故障排查顺序

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

1. 看服务状态：

./planet.sh health

2. 看最近日志：

./planet.sh log

3. 按模块查看日志：

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

4. 只重启有问题的模块：

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

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

./planet.sh restart -d

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

./planet.sh restart

相关文档

• 快速开始
• 控制台前端结构
• Earth 前端结构
• Earth 图层样式属性索引
• Earth 位置候选采集使用手册
• 系统服务控制
• 数据采集系统
• 数据源、采集器设置与连接验证