planet/docs/technical/zh/manual.md

# Planet 使用手册

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

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

快速启动路径见 [快速开始](/home/ray/dev/linkong/planet/docs/technical/zh/quickstart.md)。常见排障见 [常见问题](/home/ray/dev/linkong/planet/docs/technical/zh/faq.md)。

## 入口总览

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

| 名称 | 地址 | 是否需要登录 | 说明 |
| --- | --- | --- | --- |
| Earth | `http://localhost:3000/earth` | 否 | 3D 地球、图层、BGP、卫星、海缆、新闻态势 |
| Docs | `http://localhost:3000/docs` | 部分需要 | 使用手册公开；开发、后端、运维文档按 Gatekeeper 权限组开放 |
| FAQ | `http://localhost:3000/docs/faq` | 否 | Windows / WSL、端口、依赖、动捕、凭证和权限排障 |
| 控制台 | `http://localhost:3000/admin` | 是 | 数据、配置、告警、日志和专题观测 |
| AI | `http://localhost:3000/ai` | 是 | 模型供应商、AI 工具和测试台 |
| 后端 API 文档 | `http://localhost:8000/docs` | 视接口而定 | FastAPI / OpenAPI 文档 |

## planet.sh

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

### 启动

```bash
./planet.sh start
```

默认行为：

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

可指定端口：

```bash
./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`、代理变量 |

推荐写法：

```bash
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 模式：

```bash
PLANET_LOAD_ZSHRC_ENV=source ./planet.sh start -a
```

如需完全忽略 `~/.zshrc`：

```bash
PLANET_LOAD_ZSHRC_ENV=0 ./planet.sh start -a
```

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

```bash
./planet.sh restart -a
```

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

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

### 停止

```bash
./planet.sh stop
```

会停止：

- 后端
- AI Provider
- 前端
- PostgreSQL
- Redis

### 重启

全量重启：

```bash
./planet.sh restart
```

按模块重启：

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

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

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

### 创建用户

```bash
./planet.sh createuser
```

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

### 健康检查

```bash
./planet.sh health
```

会检查：

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

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

### 日志

最近日志：

```bash
./planet.sh log
```

持续跟随日志：

```bash
./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` 容器日志 |

### 局域网访问

```bash
./planet.sh start --allow-lan
```

适合：

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

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

推荐按顺序判断：

```bash
# 在 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 中配置：

```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 态势页面，入口：

```text
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 和在线地理编码中整理候选位置；这些常规来源没有候选时，会使用当前默认 AI Provider 做一次 LLM factcheck 兜底。BGP 观测站的已存储位置只用于补齐查询上下文，不会作为候选直接返回。

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

### 设置

设置面板包含：

- 旋转模式 / 巡航模式 / 动捕模式
- 巡航模块：BGP、新闻、算力中心、船只、海缆、卫星
- 视图设置：卫星显示风格、日夜模式、面板显示开关
- 动捕调试模式、动捕输入源、只显示骨骼
- 地球默认大小
- 地形透明度
- 重置设置

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

### 视角控制

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

常用控制方式：

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

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

拖动灵敏度会根据当前缩放自动调整。默认视角附近保持常规旋转速度；放大后拖动会逐步变细，适合检查某个区域、船只、卫星或 BGP 事件；缩小后拖动会略快，方便快速浏览全球态势。

### 动作捕捉控制

Earth 预留了动作捕捉控制入口，面向大屏和未来 3D 展示。实时链路有两种输入源：默认的 `浏览器摄像头` 会直接用网页 `getUserMedia` 在本机浏览器识别；高级的 `Motion Agent` 会走 `摄像头/RTSP/HTTP -> 本地 Agent -> 本地 WebSocket -> Earth 页面`。两种模式都不会把摄像头帧或实时手势发到云端，也不会复用新闻/RSS 聚合接口。

默认不自动启用。打开设置里的 `动捕调试模式`，或用 `?motion=1` 打开 Earth 动捕连接后，系统会启动当前选择的输入源。输入源默认是 `浏览器摄像头`，无需安装应用，但页面必须运行在 HTTPS 或 localhost，且用户需要允许浏览器摄像头权限。需要双摄、USB index、手机/网络摄像头流或客户端/边缘设备时，可在设置中切到 `Motion Agent`。默认 Agent 地址是 `ws://127.0.0.1:8765/ws/gestures`，也可用 URL 参数 `motionAgent` 覆盖。

URL 参数也可以直接指定输入源：`?motion=1&motionProvider=browser` 使用浏览器摄像头；`?motion=1&motionProvider=agent` 使用 Motion Agent；传入 `motionAgent=ws://...` 时会自动选择 Motion Agent。

当前手势语义：

| 手势事件 | 作用 |
| --- | --- |
| `rotate_left` | 地球向左旋转 |
| `rotate_right` | 地球向右旋转 |
| `rotate_up` | 地球向上旋转 |
| `rotate_down` | 地球向下旋转 |
| `zoom_in` | 放大视角 |
| `zoom_out` | 缩小视角 |
| `focus_prev` / `focus_next` | 在当前动捕图层内切换可交互目标 |
| `layer_prev` / `layer_next` | 切换动捕候选图层，并巡航到新图层最近目标 |
| `confirm` | 确认当前已选目标；当前浏览器识别暂未启用双手上举确认 |

设置面板中的 `动捕调试模式` 会打开调试面板。浏览器摄像头输入源会在面板内显示本机实时预览，并在其上绘制关节点和连线；`Motion Agent` 输入源只发送归一化骨架事件，不发送原始视频帧。面板里的 `只显示骨骼` 会隐藏视频预览、只保留深色背景和骨架；`停止匹配动作` 会暂停手势触发，但摄像头预览和骨架绘制仍可继续用于调试。未匹配动作时骨架为红色，匹配后变绿并显示当前动作名称。该入口和 `动捕输入源` 控件都已预留 Gatekeeper 权限标记，后续可接入鉴权控制。

### 巡航模式

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

当前巡航模块包括：

- BGP
- 新闻
- 算力中心
- 船只
- 海缆
- 卫星

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

### 移动端

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

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

### 常见问题

#### Earth 打不开

先检查前端是否在线：

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

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

#### 图层没有数据

检查后端和数据源：

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

然后进入控制台查看：

- `/datasources`
- `/data`
- `/bgp`

#### 卫星、BGP 或海缆加载慢

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

## 控制台

控制台入口：

```text
http://localhost:3000/admin
```

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

```bash
./planet.sh createuser
```

### 页面结构

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

常见入口：

| 页面 | 路由 | 用途 |
| --- | --- | --- |
| 仪表盘 | `/admin` | 系统概览 |
| Earth | `/earth` | 打开公开 Earth 页面 |
| 数据源 | `/datasources` | 查看数据源和触发采集 |
| 采集数据 | `/data` | 查看采集后的数据 |
| BGP 观测 | `/bgp` | 查看 BGP 专题数据 |
| 系统告警 | `/alerts/system` | 系统级告警 |
| BGP 告警 | `/alerts/bgp` | BGP 相关告警 |
| 态势告警 | `/alerts/situational` | 态势研判告警 |
| AI | `/ai` | 模型供应商、WebSearch 等工具和测试台 |
| 系统日志 | `/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

`/ai` 用于管理 AI 运行链路，已经从系统配置中独立出来。旧链接 `/playground` 会跳转到 `/ai?tab=playground`。

当前包含：

- `模型供应商`：默认 LLM provider、模型、Base URL、API Key、本地 `aiprovider` 代理和连接测试
- `工具`：WebSearch provider、搜索 API Key、Base URL、最大结果数、超时和高级 provider 参数
- `测试台`：AI Provider 状态、预设请求和真实分析链路调试

旧链接 `/settings?tab=ai` 会跳转到 `/ai?tab=providers`。

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

#### 采集器设置

`/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` 用于查看系统日志。若菜单中不可见，通常是当前用户角色没有权限。

排查问题时常用组合：

```bash
./planet.sh health
./planet.sh log
```

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

## Docs

文档站入口：

```text
http://localhost:3000/docs
```

Docs 正文由后端 API 按权限读取，不再把全部 Markdown 直接打进前端构建产物。当前文档源文件仍位于：

```text
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：

```bash
cd frontend
bun install
bun run dev
bun run build
```

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

验证前端构建：

```bash
source ~/.zshrc && bun run build
```

## 故障排查顺序

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

1. 看服务状态：

```bash
./planet.sh health
```

2. 看最近日志：

```bash
./planet.sh log
```

3. 按模块查看日志：

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

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

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

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

```bash
./planet.sh restart -d
```

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

```bash
./planet.sh restart
```

## 相关文档

- [快速开始](/home/ray/dev/linkong/planet/docs/technical/zh/quickstart.md)
- [控制台前端结构](/home/ray/dev/linkong/planet/docs/technical/zh/frontend-admin-frontend-context.md)
- [Earth 前端结构](/home/ray/dev/linkong/planet/docs/technical/zh/earth-frontend-context.md)
- [Earth 图层样式属性索引](/home/ray/dev/linkong/planet/docs/technical/zh/earth-layer-style-reference.md)
- [Earth 位置候选采集使用手册](/home/ray/dev/linkong/planet/docs/technical/zh/location-pipeline-user.md)
- [系统服务控制](/home/ray/dev/linkong/planet/docs/technical/zh/backend-system-service-control.md)
- [数据采集系统](/home/ray/dev/linkong/planet/docs/technical/zh/backend-collectors.md)
- [数据源、采集器设置与连接验证](/home/ray/dev/linkong/planet/docs/technical/zh/datasource-collector-settings-connectivity.md)