337 lines
18 KiB
Markdown
337 lines
18 KiB
Markdown
# 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` | 模型供应商、工具、测试台 |
|
||
| 系统日志 | `/logs` | 通常仅 super admin 可见 |
|
||
| 用户管理 | `/users` | 创建/删除/改角色/调权限组 |
|
||
| 系统配置 | `/settings` | 系统、SMTP、TV、采集器设置 |
|
||
|
||
权限不足时菜单项会自动隐藏。如果发现某个菜单看不到，先确认自己的角色和 Gatekeeper 权限组。
|
||
|
||
## 配置数据采集器
|
||
|
||
`/settings?tab=collector_credentials` 是"采集器设置"页。这里统一维护所有采集器的连接配置，不仅是凭证。
|
||
|
||
操作步骤：
|
||
|
||
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. `/settings?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
|
||
|
||
### 模型供应商
|
||
|
||
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、识别语言、超时、最大文件大小、输出格式
|
||
|
||
旧链接 `/settings?tab=ai` 会跳到 `/ai?tab=providers`。
|
||
|
||
## 系统设置
|
||
|
||
`/settings` 用于管理系统级配置，常用子 tab：
|
||
|
||
- **系统显示**：系统名称、刷新间隔、数据保留天数、最大并发任务
|
||
- **通知策略**：告警邮件开关、收件邮箱、严重/警告/每日摘要通知
|
||
- **安全策略**：会话超时、最大登录尝试、密码策略
|
||
- **SMTP 邮件**：注册和找回密码所需的发件配置（仅 `admin` / `super_admin` 可见）
|
||
- **电视直播**：电视直播源管理
|
||
- **AI / WebSearch / OCR**：见上节
|
||
|
||
### 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`：数据源目录。`采集任务` tab 面向一次性/定时采集器，可以按产品域、层级、启用状态、最近执行状态、是否已有采集数据和关键词筛选；勾选多行后可批量采集选中项，未勾选时“一键采集”触发当前筛选范围。`实时流` tab 面向 AISStream / WebSocket 长连接，展示连接健康、累计入库、时间窗统计和启动 / 停止 / 重连操作。点击名称打开信息抽屉查看 endpoint、请求头、基础配置和是否内置；接口、凭证、请求头的编辑统一在 `/settings` 的"采集器设置"。总体进度下方的 `采集中 N` 标签可点击，展开当前采集任务列表
|
||
- `/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 伪造位置。详细流程见 [Earth 位置候选采集使用手册](/home/ray/dev/linkong/planet/docs/technical/zh/location-pipeline-user.md)。
|
||
|
||
### 设置
|
||
|
||
设置面板包含：旋转模式 / 巡航模式 / 动捕模式、巡航模块（BGP/新闻/算力中心/船只/海缆/卫星）、视图设置（卫星显示风格、日夜模式、面板显示开关）、动捕调试模式 / 输入源 / 只显示骨骼、地球默认大小、地形透明度、重置设置。
|
||
|
||
这些设置保存在浏览器本地存储，换浏览器或清理站点数据后会恢复默认值。
|
||
|
||
### 视角控制
|
||
|
||
| 操作 | 作用 |
|
||
| --- | --- |
|
||
| 鼠标左键拖动 | 旋转地球 |
|
||
| 手指单指拖动 | 触屏旋转地球 |
|
||
| 鼠标滚轮 | 放大或缩小 |
|
||
| 双指捏合 | 触屏放大或缩小 |
|
||
| 缩放按钮 | 固定步长调整缩放 |
|
||
| 点击缩放百分比 | 重置到默认缩放 |
|
||
|
||
缩放时顶部胶囊会短暂显示当前缩放比例。这个提示不代表数据加载进度；如果页面正在加载数据，加载提示优先显示。
|
||
|
||
拖动灵敏度会根据当前缩放自动调整：默认视角附近保持常规旋转速度；放大后拖动会逐步变细，缩小后拖动会略快。
|
||
|
||
### 动作捕捉控制
|
||
|
||
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` 文档：首页、快速开始、使用手册、常见问题、Earth 位置候选采集使用手册。登录用户被分配 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)
|
||
- [Earth 位置候选采集使用手册](/home/ray/dev/linkong/planet/docs/technical/zh/location-pipeline-user.md)
|
||
- [Planet 运维手册](/home/ray/dev/linkong/planet/docs/technical/zh/ops-runbook.md)
|