# Planet 使用手册

这份手册面向 Planet 的最终用户。从打开浏览器开始，覆盖注册账号、登录、配置数据采集器、配置 AI、使用 Earth 和控制台、阅读文档站。所有操作都在浏览器里完成。

如果你是负责部署或值班的运维，请改读 [Planet 运维手册](/home/ray/dev/linkong/planet/docs/technical/zh/ops-runbook.md)，里面是 shell 命令、日志位置、SMTP 兜底创建用户等内容。

## 入口总览

| 名称 | 地址 | 是否需要登录 | 说明 |
| --- | --- | --- | --- |
| Earth | `http://<域名>/earth` | 否 | 公开 3D 地球态势页面 |
| Docs | `http://<域名>/docs` | 部分需要 | 公共文档免登录，开发/运维文档按 Gatekeeper 权限组开放 |
| 注册 / 登录 / 找回密码 | `/register`、`/login`、`/forgot-password` | 否 | 自助开通和恢复账号 |
| 控制台 | `http://<域名>/admin` | 是 | 数据、采集器、告警、AI、用户、设置 |
| AI | `http://<域名>/ai` | 是 | 模型供应商、工具和测试台 |
| 后端 API 文档 | `http://<域名>:8000/docs` | 视接口而定 | FastAPI / OpenAPI |

下面所有 URL 都基于本机演示的默认地址 `http://localhost:3000`，部署到正式环境时把前缀换成你们的访问域名即可。

## 注册账号

1. 打开 `http://localhost:3000/login`，点击表单下方"注册账户"。
2. 在 `/register` 填写：
   - **用户名**：3–50 位字符，登录时使用
   - **邮箱**：用于接收验证码，可在账户设置中修改
   - **密码**：至少 8 位
3. 提交后会跳到验证页，已将 6 位验证码发到你的邮箱。10 分钟内有效。
4. 输入验证码，点击"验证并登录"。验证通过后系统会自动写入登录态并跳到控制台。

如果 60 秒内没收到邮件：

- 检查垃圾邮件、订阅推广、企业邮件网关
- 验证页右下角的"重新发送验证码"会显示 60 秒倒计时，倒计时结束后可重发
- 连续输错 5 次后该验证码会失效，需要重发新码

如果系统提示"邮件服务尚未配置"，说明管理员还没填 SMTP，请联系管理员开通 SMTP 或在控制台 `/settings -> SMTP 邮件` 完成配置。

默认注册角色为 `viewer`，可以登录控制台浏览公共内容。要看采集器、用户管理、系统设置等管理类页面，需要 `admin` 或 `super_admin` 在 `/users` 给你升角色。

## 登录与找回密码

### 登录

打开 `/login`，输入用户名和密码即可。登录成功后跳到 `/admin`。

如果提示"邮箱未验证"，页面会自动跳到 `/verify-email`，按提示输入验证码完成验证。

### 忘记密码

1. 在 `/login` 点击"忘记密码？"，或直接打开 `/forgot-password`。
2. 输入注册邮箱，点击"发送验证码"。无论邮箱是否注册，页面都会显示同一句提示（避免账号枚举）。
3. 收到验证码后，在下一步填入验证码 + 新密码（至少 8 位），点击"重置密码"。
4. 系统会跳回 `/login`，用新密码登录即可。

## 账户设置

控制台右上角点击你的用户名进入账户设置，可以：

- 修改密码：输入当前密码 + 新密码
- 修改邮箱：输入新邮箱后系统会发验证码到新地址，验证通过后才生效
- 查看权限组：列出你目前拥有的 Gatekeeper 权限组（`docs_user` / `docs_developer` / `docs_admin`）
- 登出：清除当前会话

## 控制台总览

控制台 `http://localhost:3000/admin` 使用 React + Ant Design，左侧菜单按工作域组织。

| 页面 | 路由 | 用途 |
| --- | --- | --- |
| 仪表盘 | `/admin` | 系统概览 |
| Earth | `/earth` | 跳到公开 Earth 页面 |
| 数据源 | `/datasources` | 数据源目录、触发采集 |
| 采集数据 | `/data` | 已落库的数据 |
| BGP 观测 | `/bgp` | BGP 专题观测 |
| 系统告警 | `/alerts/system` | 系统级告警 |
| BGP 告警 | `/alerts/bgp` | BGP 相关告警 |
| 态势告警 | `/alerts/situational` | 态势研判告警 |
| AI | `/ai` | 模型供应商、工具、测试台 |
| Earth 内容 | `/earth-content` | 电视直播、国界精度、底图和图层资源入口 |
| 采集管理 | `/collection-management` | 采集器、采集调度、采集历史入口 |
| 系统日志 | `/logs` | 通常仅 super admin 可见 |
| 用户管理 | `/users` | 创建/删除/改角色/调权限组 |
| 系统设置 | `/settings` | 系统显示、通知、安全、SMTP |

权限不足时菜单项会自动隐藏。如果发现某个菜单看不到，先确认自己的角色和 Gatekeeper 权限组。

## 配置数据采集器

`/collection-management?tab=collector_credentials` 是"采集器"页。这里统一维护所有采集器的连接配置，不仅是凭证。旧链接 `/settings?tab=collector_credentials` 会自动跳转到这个入口；数据源目录仍保留在 `/datasources`。

操作步骤：

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

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

系统判断"已连接"的条件：

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

### BarentsWatch AIS 凭证

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

- `Client ID`
- `Client Secret`
- `Endpoint`

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

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

- 查看默认教程
- 点击"教程不好用"让 AI Provider 用默认 prompt 重新生成
- 点击"重置"恢复默认教程

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

### AISStream 实时船舶

`AISStream 实时船舶` 是全球 AIS WebSocket 采集器。连接测试通过只说明 API Key 和 endpoint 格式可用；真正的全球船只数据来自后台 `aisstream_vessels` collector 长连接运行并写入 `ais_raw_observations`。

操作步骤：

1. `/collection-management?tab=collector_credentials` 选择 `AISStream 实时船舶 : aisstream_vessels`
2. 在 `AISStream 凭证` 填入 API Key
3. Endpoint 保持默认 `wss://stream.aisstream.io/v0/stream`
4. 点击插头图标进行连接测试，确认显示 `可用`
5. 保存采集器设置
6. 打开 `/datasources` 的 `实时流` tab，找到 `AISStream 实时船舶`
7. 点击 `启动`、`停止` 或 `重连` 管理长连接；这里不显示百分比进度
8. 在实时流卡片中观察：
   - `connected` 表示正在接收实时流
   - `累计入库`、`近 24h`、`近 1h` 和 `唯一 MMSI` 用于判断历史采集量
   - 如果显示 `disconnected` 且有最近错误，可以点击 `重连`

## 配置 AI 凭证

`/ai?tab=providers` 是 AI 模型管理入口。包含三个核心子 tab：

- `模型供应商`：默认 LLM provider、模型、Base URL、API Key、本地 `aiprovider` 代理和连接测试
- `工具`：通过下拉菜单选择具体工具，当前支持 WebSearch 和 OCR
- `提示词`：通过功能入口下拉菜单选择新闻汉化、告警研判、BGP 简报等 LLM 任务，手动调整提示词或重置为缺省

### 模型供应商

provider 和模型既可选预设也可直接输入自定义 id/name。常用字段：

- Provider：例如 `minimax`、`openai`、`anthropic`、`ollama`
- 协议适配：`OpenAI Chat Completions` / `Anthropic Messages` / `Ollama Generate`
- Base URL：模型 API 地址
- 默认模型：例如 `gpt-5.1`、`MiniMax-M2.7`
- API Key：填入后保存；保存的 Key 在 UI 中显示为脱敏预览
- Max Tokens、Anthropic Version：可保持默认
- Timeout / Retry：超时和重试次数

Base URL 输入框尾端的插头图标会触发连接测试。测试通过会显示当前模型返回的简短回复。

### 工具

- **WebSearch**：provider、API Key、Base URL、最大结果数、超时、高级 provider 参数。未启用时除"启用"开关外其它配置项和连接测试都会置灰
- **OCR**：provider、Base URL、API Key、模型/engine、识别语言、超时、最大文件大小、输出格式

### 提示词

选择功能入口后，页面会显示当前提示词、是否已自定义、缺省版本和重置按钮。保存只影响该功能入口；重置会恢复当前发布包中的缺省提示词。业务事实、上下文和输出 schema 仍由后端按功能入口自动传入。

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

## 系统设置

`/settings` 用于管理系统级配置，常用子 tab：

- **系统显示**：系统名称、刷新间隔、数据保留天数、最大并发任务
- **通知策略**：告警邮件开关、收件邮箱、严重/警告/每日摘要通知
- **安全策略**：会话超时、最大登录尝试、密码策略
- **SMTP 邮件**：注册和找回密码所需的发件配置（仅 `admin` / `super_admin` 可见）

电视直播和国界精度已经移到 `/earth-content`，采集器和采集调度已经移到 `/collection-management`，AI Provider / WebSearch / OCR 在 `/ai`。

### Earth 内容

`/earth-content` 位于控制台“运维与配置”下，面向 Earth 前端体验资源：

- **品牌资源**：维护 Earth HUD 使用的 logo、标题图、标题文本、副标题和描述；上传的图片会保存为 Earth 品牌资产并立即供 Earth 页面读取。
- **关于**：维护 Earth 设置面板里的关于卡片，包括 logo、眉标、标题、版本、描述和元信息。
- **电视直播**：维护 Earth 媒体面板里的直播源。
- **国界精度**：查看当前国界 provider、低精 fallback、高精 PMTiles/manifest 状态，编辑本机源配置并手动构建。
- **地球底图**、**图层资源**、**三维素材**、**新闻锚点策略**：目前是待接入占位页，不展示假数据。

Earth 页面工具栏齿轮中也有“国界精度”。切到“高精”时，如果本机尚未构建高精资产，会像游戏更新包一样启动后台下载/构建并显示百分比；构建成功后自动应用，无需刷新。切回“低精”只切换本机显示偏好，不重新下载。

如果后端判断 Earth 尚未初始化，首次进入 `/earth` 会出现毛玻璃引导，提示登录控制台并采集数据。这个判断来自后端真实数据状态；如果系统已经有已采集数据，清空浏览器缓存也不会重新弹出。

### 采集管理

`/collection-management` 位于控制台“运维与配置”下，面向采集生命周期：

- **采集器**：维护 endpoint、请求头、凭证、timeout、retry，并运行连接检查。
- **采集调度**：维护原有调度相关设置。
- **采集历史 / 快照**：按数据源聚合历史快照，详情页可用 Time Capsule 下拉切换不同版本。

### SMTP 邮件设置

公开注册和验证码功能依赖这一项。`admin` 或 `super_admin` 用户在 `/settings` 进入 `SMTP 邮件` 子 tab，填：

- SMTP 主机、端口
- 账号、密码
- 发件地址（必填）、发件人名称
- STARTTLS（端口 587 常用） 或 隐式 TLS（端口 465）
- 超时秒数

填完保存，再点"发送测试邮件"按钮，输入收件人地址试发一封。测试通过后即可让普通用户走 `/register` 自助注册。

如果保留密码字段中的脱敏预览不动，保存时不会覆盖原密码；要换密码就输入新值。

## 用户管理（管理员）

`/users` 仅 `super_admin` 可创建/删除用户。该页支持：

- 查看用户列表（用户名、邮箱、角色、是否激活、邮箱是否已验证）
- 创建用户：与公开注册等价，但跳过邮箱验证（管理员认账）
- 修改角色：`viewer` / `operator` / `admin` / `super_admin`
- 调整 Gatekeeper 权限组：`docs_user` / `docs_developer` / `docs_admin`，影响 Docs 站可见文档范围
- 禁用 / 启用账号

要让普通用户能看开发或运维文档，进 `/users` 给他加 `docs_developer` 或 `docs_admin`。

## 数据探索

- `/datasources`：数据源目录。`内置源` 支持按产品域、层级、启用状态、最近执行状态、是否已有采集数据和关键词筛选；未勾选时主按钮显示“触发全部”，勾选多行后会变成“触发已选 N”，并只提交所选数据源。右上角队列按钮空态显示队列图标，有任务时显示纯圆环总进度；点击后打开队列浮层，按运行中、完成、失败和跳过分组，失败项可重试，完成项可跳到详情。`实时源` 面向 AISStream / WebSocket 长连接，展示连接健康、累计入库、时间窗统计和启动 / 停止 / 重连操作。接口、凭证、请求头的编辑统一在 `/collection-management` 的"采集器"。
- `/data`：采集后数据表，适合排查"数据是否已经进入系统"、"更新时间是否符合预期"、"某个数据源是否产出有效记录"
- `/bgp`：BGP 专题页面，列表 + 详情 + 研判，与 Earth 的 BGP 图层互补
- `/alerts/system`、`/alerts/bgp`、`/alerts/situational`：系统、BGP、态势告警

## AI 测试台

`/ai?tab=playground` 用于真实分析链路调试。可以：

- 选择当前 provider
- 用预设请求或自定义 prompt 触发分析
- 观察 AI Provider 状态和返回内容

旧链接 `/playground` 会跳到这里。

## Earth 公开页面

Earth `http://localhost:3000/earth` 是公开 3D 态势页面，不需要登录。React 路由中的 `/earth` 用 iframe 承载独立前端（位于 `frontend/public/earth/`）。

### 主要用途

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

### 图层控制

右侧图层面板用于打开或关闭图层。常见图层：经纬线、国界线、高清材质、大气云图、海缆、算力中心、BGP 观测、卫星、AIS 船只、地形。卫星轨迹不再作为单独图层出现在图层列表中，改在设置面板里控制。

依赖关系：

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

### 图例

左下角图例会跟随当前聚焦或启用的图层切换。已覆盖：海缆、卫星、国界线、算力中心、BGP、AIS 船只。

AIS 船只图例按船型显示颜色：货轮、油轮、客船、渔船、军舰、停泊/低速、其他船只。三角形对应航行船只标记，圆点对应停泊或低速状态。

### 搜索

支持查找海缆、登陆点、卫星、算力中心、BGP 事件、BGP 观测站。结果可快速定位并打开详情。

### 位置候选采集

算力中心和 BGP 观测站详情卡支持自动采集坐标候选。点击对象后用"自动采集坐标候选"或"重新自动采集坐标"按钮，后端会从源坐标、开放组织注册 API 和在线地理编码中整理候选；常规来源没有候选时使用当前默认 AI Provider 做 LLM factcheck 兜底。BGP 观测站的已存储位置只用于补齐查询上下文，不会作为候选直接返回。

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

单个对象的推荐流程：

1. 打开算力中心或 BGP 观测站详情卡。
2. 点击"自动采集坐标候选"。
3. 等待候选列表返回；有 WebSearch / AI factcheck 依赖的候选会显示采集中状态。
4. 在 Earth 上预览候选位置。
5. 确认可用候选后点击"保存"；不确定时关闭卡片不会丢失当前任务状态。

一键定位用于批量处理算力中心待定位队列。它会从列表顶部开始采用最高置信候选；仍没有事实依据的记录会保留在队列中。未开启 WebSearch 时，单个定位和一键定位会置灰，因为位置核验依赖事实查询。

### 设置

设置面板按分类组织：运行、显示、面板、动捕、快捷键、系统。里面包含旋转模式 / 巡航模式 / 动捕模式、巡航模块（BGP/新闻/算力中心/船只/海缆/卫星）、视图设置（卫星显示风格、悬停提示、卫星呼吸闪烁、真实卫星高度、轨迹显示、低缩放圆点、日夜模式、面板显示开关）、动捕调试模式 / 输入源 / 只显示骨骼、快捷键启用与改键、地球默认大小、地形透明度、重置设置。

“真实卫星高度”默认开启：卫星会按 TLE/SGP4 算出的真实轨道高度做压缩分层显示，低轨仍靠近地球，高轨会更远但不会脱离当前视图。高轨显示高度会被压到地球半径外约四分之一以内，这样 GEO / MEO 仍能和 LEO 分层，但不会把视线、轨迹和选择操作拉得过散；关闭后恢复旧版所有卫星位于同一显示球面的效果。“轨迹显示”控制卫星轨迹线显隐，卫星图层关闭时轨迹也不可见。

“悬停提示”控制鼠标悬停地表时的 tooltip 内容：`国家` 只在陆地命中国家时显示国家信息，太平洋等海洋区域不弹出地表提示；`位置` 在陆地和海洋都显示纬度、经度和海拔；`完整` 是默认模式，陆地显示国家 + 位置，海洋显示位置。

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

快捷键也保存在浏览器本地。可以在设置里的“快捷键”分类中单独禁用、重设某个快捷键，或恢复默认键位；这只影响当前浏览器。

### 视角控制

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

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

拖动灵敏度会根据当前缩放自动调整：默认视角附近保持常规旋转速度；放大后拖动会逐步变细，缩小后拖动会略快。

### 动作捕捉控制

Earth 预留了动作捕捉控制入口。实时链路两种输入源：

- **浏览器摄像头**（默认）：直接用网页 `getUserMedia` 在本机浏览器识别；无需安装应用，但页面必须运行在 HTTPS 或 localhost，且需允许浏览器摄像头权限
- **Motion Agent**：摄像头/RTSP/HTTP → 本地 Agent → 本地 WebSocket → Earth 页面；用于双摄、USB index、手机/网络摄像头流

打开方式：设置中开启"动捕调试模式"，或加 URL 参数 `?motion=1` 打开 Earth 动捕连接。Motion Agent 默认地址 `ws://127.0.0.1:8765/ws/gestures`，可用 `motionAgent` URL 参数覆盖。也可以直接 `?motion=1&motionProvider=browser` 或 `?motion=1&motionProvider=agent`。

两种模式都不会把摄像头帧或实时手势发到云端，也不会复用新闻/RSS 聚合接口。

手势语义：

| 手势事件 | 作用 |
| --- | --- |
| `rotate_left/right/up/down` | 地球向对应方向旋转 |
| `zoom_in/out` | 放大或缩小视角 |
| `focus_prev/next` | 在当前动捕图层内切换可交互目标 |
| `layer_prev/next` | 切换动捕候选图层并巡航到新图层最近目标 |
| `confirm` | 确认当前已选目标 |

调试面板中：浏览器摄像头输入会显示本机实时预览并绘制关节点和连线；Motion Agent 只发归一化骨架事件，不发原始帧。"只显示骨骼"会隐藏视频预览只保留骨架；"停止匹配动作"会暂停手势触发但保留预览和骨架。未匹配时骨架红色，匹配后变绿并显示动作名称。

### 巡航模式

巡航模式让 Earth 自动轮播聚焦目标。当前巡航模块：BGP、新闻、算力中心、船只、海缆、卫星。适合演示、监控大屏或无人值守。

### 移动端

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

### 常见问题

- **Earth 打不开**：先确认前端服务是否在线；如果端口不是 `3000`，使用启动输出的实际端口
- **图层没有数据**：进 `/datasources` 看数据源状态、是否已采集和最近执行结果，再到 `/data` 或 `/bgp` 看是否有记录
- **卫星 / BGP / 海缆加载慢**：这些图层依赖后端接口和外部数据源，首次加载需要等启动任务完成
- **卫星看起来不在同一层**：这是默认的真实高度压缩显示。想回到旧版同层球面，可在设置中关闭“真实卫星高度”

## Docs 文档站

文档站 `http://localhost:3000/docs` 由后端按权限读取，不再把全部 Markdown 直接打进前端构建产物。

未登录访客默认只能看到 `public` 文档：首页、快速开始、使用手册、常见问题。登录用户被分配 Gatekeeper 权限组后可以看到更多技术文档：

- `docs_user`：用户操作类文档
- `docs_developer`：Earth、前端、后端、采集器和 AI Provider 等开发文档
- `docs_admin`：服务控制、运维、环境变量和敏感操作文档（包括运维手册）

`admin` 默认拥有 `docs_admin`，`super_admin` 拥有全部 Docs 权限。Gatekeeper 权限组在"用户管理"中配置。

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

## 相关文档

- [快速开始](/home/ray/dev/linkong/planet/docs/technical/zh/quickstart.md)
- [常见问题](/home/ray/dev/linkong/planet/docs/technical/zh/faq.md)
- [Planet 运维手册](/home/ray/dev/linkong/planet/docs/technical/zh/ops-runbook.md)