# Planet 使用手册

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

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

快速启动路径见 [快速开始](/home/ray/dev/linkong/planet/docs/technical/zh/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。

### 启动

```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
- 局域网其他机器访问同一个开发实例

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

## 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、新闻
- 卫星显示风格：自身发光、真实地表覆盖
- 日夜模式
- 面板显示开关
- 地球默认大小
- 地形透明度
- 重置设置

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

### 视角控制

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

常用控制方式：

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

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

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

### 巡航模式

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

排查问题时常用组合：

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

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

## Docs

公开文档站入口：

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

当前公开内容来自：

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

Docs 支持：

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

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

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

## 开发命令约定

前端命令必须使用 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)
- [系统服务控制](/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)