planet/docs/technical/zh/manual.md

Planet 使用手册

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

如果你是负责部署或值班的运维，请改读 Planet 运维手册，里面是 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. 到采集调度入口运行 aisstream_vessels collector
7. 在 AISStream 运行状态 中观察：
   • streaming / connected 表示正在接收实时流
   • 本轮消息数 应持续增长
   • 如果显示 disconnected 且错误为 ConnectionResetError，需要重新触发或等待重连

配置 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：数据源目录。可以按产品域、层级、启用状态、最近执行状态、是否已有采集数据和关键词筛选；勾选多行后可批量采集选中项，未勾选时“采集当前筛选”只触发当前筛选范围。点击名称打开信息抽屉查看 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 位置候选采集使用手册。

设置

设置面板包含：旋转模式 / 巡航模式 / 动捕模式、巡航模块（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 文档间内部链接跳转。

相关文档

• 快速开始
• 常见问题
• Earth 位置候选采集使用手册
• Planet 运维手册