planet/docs/technical/zh/manual.md

智能星球使用手册

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

如果你是负责部署或值班的运维，请改读 智能星球运维手册，里面是 shell 命令、日志位置、SMTP 兜底创建用户等内容。

入口总览

名称	地址	是否需要登录	说明
智能星球	http://<域名>/earth	否	公开 3D 态势页面
文档	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，用新密码登录即可。

账户区与退出

控制台左侧底部的账户区会显示当前用户名、版本号和主题切换。当前版本还没有登录后的自助账户设置页：

• 忘记密码或需要重置密码时，使用 /forgot-password 邮件验证码流程
• 邮箱、角色和 Gatekeeper 权限组由管理员在 /users 维护
• 点击账户区的退出图标会清除当前会话并返回登录页

控制台总览

控制台 http://localhost:3000/admin 使用 React + Tactile UI / Radix 基础组件和 lucide 图标，左侧菜单按工作域组织。

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

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

配置数据采集器

/collection-management?section=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 与 BarentsWatch 的后续位置会自动更新。更新时会保留已选中的船只；短暂断线重连后会自动校准，无需反复关闭、开启图层。

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

操作步骤：

1. /collection-management?section=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?section=integrations 是 AI 模型管理入口。主要分区包括：

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

模型供应商

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 输入框尾端的插头图标会触发轻量连接测试：检查代理和模型目录，并确认当前模型出现在目录中。通过后可到 Playground 发起实际生成，核对账号权限和模型回复；目录检查本身不执行生成调用。

点击右上角的刷新图标可更新“可选模型”。成功后目录会保存，重新打开页面仍可使用；有发布日期的目录按新到旧排列。刷新保留当前模型、密钥、地址和未保存的修改。点击一个可选模型后，再点“保存”才会改变实际使用的模型。刷新失败时会显示错误并保留上次目录。

刷新使用当前表单中的基础地址、协议和 API Key，因此可以先填写新配置再刷新，无需提前保存。需要凭证的供应商必须填写对应地域的 Key；Ollama 的空目录表示尚未安装模型。选择已知协议的模型时，协议适配会同步到表单；自定义 OpenAI 网关保留手动选择的协议。

工具

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

提示词

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

旧的 AI 配置入口不再放在系统设置里；/playground 会跳到 /ai?section=playground。

系统设置

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

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

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

智能星球内容

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

• 品牌资源：维护智能星球 HUD 使用的 logo、标题图、标题文本、副标题和描述。Logo 地址 和 标题图地址 字段内各有独立的“上传”按钮，也可以把图片直接拖到对应字段；上传成功后字段会写入新的资产地址，保存品牌配置后供智能星球页面读取。
• 关于：维护智能星球设置面板里的关于卡片，包括 logo、眉标、标题、版本、描述和元信息。
• 电视直播：维护智能星球媒体面板里的直播源。
• 新闻内容：按 RSS 来源和手动新闻组查看新闻。RSS 新闻保持只读；手动新闻组可以新增、批量导入 JSON、编辑、删除和重新处理。
• 国界精度：查看当前国界 provider、低精 fallback、高精 PMTiles/manifest 状态，编辑本机源配置并手动构建。
• 地球底图、图层资源、三维素材、新闻锚点策略：目前是待接入占位页，不展示假数据。

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

如果后端判断智能星球尚未初始化，首次进入 /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，影响文档站可见文档范围
• 禁用 / 启用账号

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

数据探索

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

AI 测试台

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

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

旧链接 /playground 会跳到这里。

智能星球公开页面

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

主要用途

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

图层控制

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

依赖关系：

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

图例

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

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

搜索

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

新闻直播源选择

打开媒体面板的直播页，点击当前频道可展开搜索菜单。搜索会检索完整频道库；列表每次加载 50 个频道，滚动到底部自动追加。底部固定显示已加载数量和搜索结果总数，加载失败时可在列表下方重试。默认新闻直播源为 Al Jazeera Mubasher（半岛电视台），使用 HLS 播放地址；其他频道仍取决于各自的播放服务是否可用。

位置候选采集

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

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

单个对象的推荐流程：

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

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

在当前智能星球页面内，关闭候选面板、查看其他对象或切换浏览器标签页不会取消队列；返回候选列表后可继续查看进度和结果。已保存条目不会再次采集，全部完成后仍可通过图层旁的 ✓ 入口查看结果。刷新、关闭页面或跳转离开智能星球会中断尚未完成的队列，已经保存的坐标会保留。

设置

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

新闻类型使用与巡航模块一致的标签选择器，只筛选当前浏览器里的新闻面板和新闻巡航条目，不影响图层、TV、数据点、底图、边界、采集任务或后台新闻源配置。

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

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

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

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

视角控制

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

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

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

动作捕捉控制

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

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

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

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

“识别动作”可以单独关闭旋转、缩放、焦点切换、图层切换或确认手势。浏览器端会忽略未勾选动作；使用 Motion Agent 时，同一白名单也会通过控制协议同步给 Agent。

手势语义：

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

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

巡航模式

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

移动端

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

常见问题

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

文档站

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

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

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

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

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

相关文档

• 快速开始
• 常见问题
• 智能星球运维手册