release: bump version to 0.66.2
Some checks failed
ci / backend (push) Has been cancelled
ci / frontend (push) Has been cancelled
ci / delivery (push) Has been cancelled
release / images (push) Has been cancelled

This commit is contained in:
rayd1o
2026-05-26 08:45:33 +08:00
parent 887fec972e
commit eb4c4b7904
46 changed files with 250 additions and 235 deletions

View File

@@ -1,27 +1,27 @@
# 技术文档
这里是 Planet 当前文档入口。文档按读者和问题类型分层:先看业务架构理解数据产品,再进入使用手册或技术实现文档。
这里是智能星球当前文档入口。文档按读者和问题类型分层:先看业务架构理解数据产品,再进入使用手册或技术实现文档。
## 业务架构
- [业务架构与数据流转](/home/ray/dev/linkong/planet/docs/technical/zh/platform-data-flows.md):每类 Earth 数据的用途、采集链路、事实表、派生表、缓存和 WebSocket 广播链路
- [命名与术语对照](/home/ray/dev/linkong/planet/docs/technical/zh/naming-glossary.md):控制台、Earth、后端和文档常见名词的中英对照
- [业务架构与数据流转](/home/ray/dev/linkong/planet/docs/technical/zh/platform-data-flows.md):每类智能星球数据的用途、采集链路、事实表、派生表、缓存和 WebSocket 广播链路
- [命名与术语对照](/home/ray/dev/linkong/planet/docs/technical/zh/naming-glossary.md)智能星球、控制台、后端和文档常见名词的中英对照
## 使用手册
- [快速开始](/home/ray/dev/linkong/planet/docs/technical/zh/quickstart.md):从零启动 Planet 的最短路径
- [Planet 使用手册](/home/ray/dev/linkong/planet/docs/technical/zh/manual.md):控制台、Earth、Docs 和常用功能的用户操作说明
- [常见问题](/home/ray/dev/linkong/planet/docs/technical/zh/faq.md)Windows / WSL、端口、依赖、动捕、凭证和 Docs 权限排障
- [快速开始](/home/ray/dev/linkong/planet/docs/technical/zh/quickstart.md):从零启动智能星球的最短路径
- [智能星球使用手册](/home/ray/dev/linkong/planet/docs/technical/zh/manual.md):控制台、智能星球、文档和常用功能的用户操作说明
- [常见问题](/home/ray/dev/linkong/planet/docs/technical/zh/faq.md)Windows / WSL、端口、依赖、动捕、凭证和文档权限排障
## Earth 技术实现
## 智能星球技术实现
- [Earth 前端结构](/home/ray/dev/linkong/planet/docs/technical/zh/earth-frontend-context.md)Earth 页面模块、状态、WebSocket 刷新和图层生命周期
- [Earth 图层样式属性索引](/home/ray/dev/linkong/planet/docs/technical/zh/earth-layer-style-reference.md):图层颜色、符号、材质和视觉参数
- [Earth 渲染图层顺序](/home/ray/dev/linkong/planet/docs/technical/zh/earth-render-layer-order.md)renderOrder、深度策略、拾取和同坐标避让
- [Earth 卫星覆盖策略](/home/ray/dev/linkong/planet/docs/technical/zh/earth-satellite-footprint-policy.md):卫星 footprint 的显示边界和策略
- [BGP 态势上下文](/home/ray/dev/linkong/planet/docs/technical/zh/earth-bgp-context.md)BGP 在 Earth 中的渲染、聚合和观测站实现
- [Earth 可交互图标接入](/home/ray/dev/linkong/planet/docs/technical/zh/earth-interactable-usage.md)`Interactable` 的接口、生命周期和接入示例
- [Earth 工具栏与浮层协同](/home/ray/dev/linkong/planet/docs/technical/zh/earth-toolbar-overlay-coordination.md):工具栏按钮与搜索、设置、新闻、图层浮层的关闭矩阵
- [智能星球前端结构](/home/ray/dev/linkong/planet/docs/technical/zh/earth-frontend-context.md)智能星球页面模块、状态、WebSocket 刷新和图层生命周期
- [智能星球图层样式属性索引](/home/ray/dev/linkong/planet/docs/technical/zh/earth-layer-style-reference.md):图层颜色、符号、材质和视觉参数
- [智能星球渲染图层顺序](/home/ray/dev/linkong/planet/docs/technical/zh/earth-render-layer-order.md)renderOrder、深度策略、拾取和同坐标避让
- [智能星球卫星覆盖策略](/home/ray/dev/linkong/planet/docs/technical/zh/earth-satellite-footprint-policy.md):卫星 footprint 的显示边界和策略
- [BGP 态势上下文](/home/ray/dev/linkong/planet/docs/technical/zh/earth-bgp-context.md)BGP 在智能星球中的渲染、聚合和观测站实现
- [智能星球可交互图标接入](/home/ray/dev/linkong/planet/docs/technical/zh/earth-interactable-usage.md)`Interactable` 的接口、生命周期和接入示例
- [智能星球工具栏与浮层协同](/home/ray/dev/linkong/planet/docs/technical/zh/earth-toolbar-overlay-coordination.md):工具栏按钮与搜索、设置、新闻、图层浮层的关闭矩阵
## 前端技术实现
@@ -38,12 +38,12 @@
- [数据作业与 Outbox 技术架构](/home/ray/dev/linkong/planet/docs/technical/zh/data-job-earth-sync-architecture.md)PostgreSQL 作业队列、outbox、listener 和 Kafka / Spark 演进边界
- [通用位置估算管线开发说明](/home/ray/dev/linkong/planet/docs/technical/zh/location-pipeline-development.md)location resolver / pipeline 的接口、注册表和扩展方式
- [新闻直播采集格式](/home/ray/dev/linkong/planet/docs/technical/zh/earth-news-live-streams-collector-format.md):新闻、直播和媒体采集 payload 约定
- [Docs Gatekeeper 开发说明](/home/ray/dev/linkong/planet/docs/technical/zh/docs-gatekeeper-development.md):后端 Docs 目录、正文读取和 Gatekeeper 权限组实现
- [Docs Gatekeeper 开发说明](/home/ray/dev/linkong/planet/docs/technical/zh/docs-gatekeeper-development.md):后端文档目录、正文读取和 Gatekeeper 权限组实现
## 智能体与运维
- [AI Provider 指南](/home/ray/dev/linkong/planet/docs/technical/zh/agents-aiprovider.md):模型供应商适配、任务 prompt 和调用边界
- [Planet 运维手册](/home/ray/dev/linkong/planet/docs/technical/zh/ops-runbook.md):部署、启动、排障和敏感操作
- [智能星球运维手册](/home/ray/dev/linkong/planet/docs/technical/zh/ops-runbook.md):部署、启动、排障和敏感操作
- [Docker + Compose + Buildx 升级](/home/ray/dev/linkong/planet/docs/technical/zh/ops-docker-compose-buildx-upgrade.md)Docker 工具链升级步骤
- [planet.sh 启动机制](/home/ray/dev/linkong/planet/docs/technical/zh/ops-planet-sh-startup.md):启动脚本、健康检查和性能优化

View File

@@ -92,7 +92,7 @@ async def run(self, db):
AIS 船只类采集器和其它 `CollectedData` 采集器的落库路径不同。BarentsWatch、AISStream 和自定义 `vessel_ais` 源都会进入 AIS 原始观测层,随后由聚合服务合并成 Earth 船只图层使用的 GeoJSON 和详情数据。这样做可以保留来源、传输方式、字段冲突和观测时间,避免某个实时源直接覆盖最终展示表。
Earth 国界不再属于采集器体系。它是 Earth 静态渲染资产,由控制台 `运维与配置 -> Earth 内容 -> 国界精度` 维护源配置,并由 `/api/v1/earth/boundaries/*` 构建 `frontend/public/earth/data/boundaries/earth-boundaries-china-pov-v1.pmtiles`。本地没有高精 PMTiles 时,前端会使用仓库内置的低精度 GeoJSON 作为 fallback不会向 `CollectedData` 写入国界记录。
智能星球国界不再属于采集器体系。它是智能星球静态渲染资产,由控制台 `运维与配置 -> 智能星球内容 -> 国界精度` 维护源配置,并由 `/api/v1/earth/boundaries/*` 构建 `frontend/public/earth/data/boundaries/earth-boundaries-china-pov-v1.pmtiles`。本地没有高精 PMTiles 时,前端会使用仓库内置的低精度 GeoJSON 作为 fallback不会向 `CollectedData` 写入国界记录。
TOP500 和 Epoch AI 算力数据的公开源不总是提供可用经纬度。Earth 统一算力中心接口在主地图启动链路中只使用源数据自带坐标或 `compute_center_locations` 维表坐标;缺少坐标的记录会进入 `unresolved`,不会通过本地注册表、国家质心或猜测城市自动渲染。用户手动采集候选时,后端会用源字段调用 ROR 组织注册 API 和 Nominatim/OpenStreetMap 在线搜索;候选经前端保存后写入 `compute_center_locations`,后续地图刷新再从维表渲染。

View File

@@ -42,7 +42,7 @@ DB 变化不再默认创建 `earth_refresh` 任务,因此不会被同 source
| `collect` | 执行内置 datasource 采集 |
| `clear_data` | 删除该 source 的采集数据和声明过的派生数据 |
| `clear_cache` | 删除该 source 对应的 Earth / dashboard 缓存 |
| `earth_refresh` | 非 DB 变化场景下失效 Earth 图层缓存并广播刷新提示 |
| `earth_refresh` | 非 DB 变化场景下失效智能星球图层缓存并广播刷新提示 |
接口只创建任务并返回 `task_id`。任务执行、进度、取消和终态由 worker 写回 `collection_tasks`,并通过 `datasource_tasks` channel 通知前端。
@@ -138,4 +138,3 @@ ORDER BY 2, 1;
- 原始数据进入 Parquet / Iceberg / Delta 等湖仓,并开始生产离线派生数据产品。
若目标是秒级连续流计算,优先评估 FlinkSpark 更适合批量或微批分析。

View File

@@ -334,7 +334,7 @@ GET /api/v1/vessels/snapshot?bbox=lon_min,lat_min,lon_max,lat_max&zoom=12&limit=
自定义源现在不是独立的新数据孤岛,而是作为内置数据源的补充源写入目标 schema。当前最完整的目标是 `vessel_ais`:自定义 REST 或 WebSocket 源经过确定性 mapping 后写入 AIS raw observations再通过 `vessels` WebSocket channel 推送给 Earth。
Earth 高精度边界不再使用自定义源目标 schema。国界是 Earth 静态资产,由控制台 `运维与配置 -> Earth 内容 -> 国界精度` 保存本机源配置并触发 PMTiles 构建,不写入 `CollectedData`
智能星球高精度边界不再使用自定义源目标 schema。国界是智能星球静态资产,由控制台 `运维与配置 -> 智能星球内容 -> 国界精度` 保存本机源配置并触发 PMTiles 构建,不写入 `CollectedData`
### 配置语义

View File

@@ -2,7 +2,7 @@
Docs Gatekeeper 把 `/docs` 从“前端构建时打包所有 Markdown”改成“后端按权限返回目录和正文”。它的目标是让公开使用手册、用户文档、开发文档和管理/运维文档在同一个 Docs 页面内可检索,但正文读取必须经过服务端白名单和用户权限检查。
用户侧说明见 [Planet 使用手册](/home/ray/dev/linkong/planet/docs/technical/zh/manual.md) 的 Docs 章节。
用户侧说明见 [智能星球使用手册](/home/ray/dev/linkong/planet/docs/technical/zh/manual.md) 的文档章节。
## 鉴权模型
@@ -16,7 +16,7 @@ Docs 使用两层权限:
| 组 | 用途 |
| --- | --- |
| `docs_user` | 用户操作类文档 |
| `docs_developer` | Earth、前端、后端、采集器和 AI Provider 开发文档 |
| `docs_developer` | 智能星球、前端、后端、采集器和 AI Provider 开发文档 |
| `docs_admin` | 服务控制、运维、环境变量和敏感操作文档 |
继承规则:
@@ -24,7 +24,7 @@ Docs 使用两层权限:
- 未登录用户只能读 `public`
- `docs_developer` 隐含 `docs_user`
- `docs_admin` 隐含 `docs_developer``docs_user`
- `admin``super_admin` 默认拥有全部 Docs 权限。
- `admin``super_admin` 默认拥有全部文档权限。
## 后端入口
@@ -61,8 +61,8 @@ DocsMetadata(
"public",
"Manual",
2,
"Planet 使用手册",
"Planet Manual",
"智能星球使用手册",
"Intelligent Planet Manual",
)
```

View File

@@ -1,6 +1,6 @@
# Earth 前端结构
# 智能星球前端结构
本文件描述当前 Earth 大屏前端的真实结构,重点是帮助后续继续改 HUD、图层、媒体面板、真实地形、BGP 可视化时,不再重复踩结构和状态同步上的坑。
本文件描述当前智能星球前端的真实结构,重点是帮助后续继续改 HUD、图层、媒体面板、真实地形、BGP 可视化时,不再重复踩结构和状态同步上的坑。
相关规则建议一起参考:
@@ -138,7 +138,7 @@ Browser Camera provider 的手势识别管线在 [motion-browser-provider.js](/h
- terrain tile 拉取、解码、位移、着色
- 海陆基座与国界底图的整球 overlay
Earth 地表是多层近似同心球,不是单一 mesh。`earth.js` 的基座球、高清材质 overlay、云层/大气,以及 `country-boundaries.js` 的海陆基座都需要明确半径间距。远距视图下 GPU 深度精度会下降,相邻 shell 过近会 z-fighting表现为黑色闪烁块或雪花。当前稳定策略是让海陆基座使用 `landAltitudeOffset = 0.32`,高清材质使用 `textureOverlayAltitudeOffset = 0.48`;后续新增或调整整球地表 overlay 时,必须同步检查 [Earth 渲染图层顺序](/home/ray/dev/linkong/planet/docs/technical/zh/earth-render-layer-order.md),并在 50% 缩放视图验证。
智能星球地表是多层近似同心球,不是单一 mesh。`earth.js` 的基座球、高清材质 overlay、云层/大气,以及 `country-boundaries.js` 的海陆基座都需要明确半径间距。远距视图下 GPU 深度精度会下降,相邻 shell 过近会 z-fighting表现为黑色闪烁块或雪花。当前稳定策略是让海陆基座使用 `landAltitudeOffset = 0.32`,高清材质使用 `textureOverlayAltitudeOffset = 0.48`;后续新增或调整整球地表 overlay 时,必须同步检查 [智能星球渲染图层顺序](/home/ray/dev/linkong/planet/docs/technical/zh/earth-render-layer-order.md),并在 50% 缩放视图验证。
### 7. 图层模块
@@ -162,13 +162,13 @@ Earth 地表是多层近似同心球,不是单一 mesh。`earth.js` 的基座
`tv.js` 管理 `media-panel` 里的直播 / 态势新闻 tab。toolbar 打开或切换 TV/新闻时,会通过 `earth:tv-visibility-change``earth:tv-tab-change` 回写 Earth 设置:面板可见性仍按 desktop/mobile viewport 存在 `views.<scope>.panelVisibility.media-panel`,当前 tab 存在 `shared.mediaPanelActiveTab`,因此刷新页面后能恢复用户上次打开的直播或新闻状态。`closeTransientMobileOverlays()` 这类临时收起会带 `persist:false`,不会覆盖用户偏好。
`brand.js` 管理 Earth HUD 品牌资源。默认品牌来自静态资源,运行时覆盖值来自 `/api/v1/earth/brand`,上传的图片通过 `/earth-brand-assets/...` 读取。前端必须把 logo/title 图片和文本 fallback 分开处理:图片加载失败时显示文本标题,文本字段为空时使用后端默认值,避免 HUD 品牌区空白。控制台的 Earth 内容页负责保存和重置品牌配置,Earth 前端只消费结果。
`brand.js` 管理智能星球 HUD 品牌资源。默认品牌来自静态资源,运行时覆盖值来自 `/api/v1/earth/brand`,上传的图片通过 `/earth-brand-assets/...` 读取。前端必须把 logo/title 图片和文本 fallback 分开处理:图片加载失败时显示文本标题,文本字段为空时使用后端默认值,避免 HUD 品牌区空白。控制台的智能星球内容页负责保存和重置品牌配置,智能星球前端只消费结果。
`about.js` 管理 Earth 设置里的“关于”卡片。默认内容仍保留在前端作为兜底,运行时优先读取 `/api/v1/earth/about`。接口失败或字段缺失时必须回退默认值,避免设置页出现空白。Admin 的 Earth 内容页提供“关于”tab保存走 `PUT /api/v1/earth/about`,恢复默认走 `DELETE /api/v1/earth/about`
`about.js` 管理智能星球设置里的“关于”卡片。默认内容仍保留在前端作为兜底,运行时优先读取 `/api/v1/earth/about`。接口失败或字段缺失时必须回退默认值,避免设置页出现空白。控制台的智能星球内容页提供“关于”tab保存走 `PUT /api/v1/earth/about`,恢复默认走 `DELETE /api/v1/earth/about`
`oobe.js` 管理 Earth 首次初始化引导。是否显示 OOBE 必须由 `/api/v1/earth/oobe-status``ready` 字段决定,不能依赖 `localStorage` 判断系统是否初始化。`localStorage` 只允许记录“本浏览器暂时跳过”的短时状态;如果后端已经认为 `ready: true`,退出登录、清空本地缓存或换浏览器都不应再次弹出 OOBE。桌面端使用深色星空遮罩和毛玻璃启动面板移动端改为底部 sheet并尊重 `prefers-reduced-motion`
Admin 的 Earth 内容页必须按运行时语义组织这些配置:
控制台的智能星球内容页必须按运行时语义组织这些配置:
- `品牌标识`:品牌预览应使用与 Earth HUD 左上角一致的深色星空背景、尺寸、间距、logo/title 渲染和文本 fallback而不是普通表单预览。
- `关于`:配置 Earth 设置里的 About 卡片,包括 logo、眉标、标题、版本、描述和元信息条目Earth 运行时从 `/earth/about` 读取,失败时回退默认内容。
@@ -385,7 +385,7 @@ asset 图标大小由 `Interactable` 的 `icon.fitSize` 控制。SVG / 图片文
接口细节、生命周期和接入示例见:
- [Earth 可交互图标接入](/home/ray/dev/linkong/planet/docs/technical/zh/earth-interactable-usage.md)
- [智能星球可交互图标接入](/home/ray/dev/linkong/planet/docs/technical/zh/earth-interactable-usage.md)
### 视角控制反馈
@@ -457,7 +457,7 @@ Earth 设置面板当前由 [controls.js](/home/ray/dev/linkong/planet/frontend/
SGP4 传播输出是惯性系位置,不能直接当成 Earth 的经纬度固定坐标使用。`satellites.js` 会用当前时间的 `gstime` 把 ECI/TEME 位置转换到 ECF再映射到 `latLonToVector3()` 使用的 Three.js 坐标轴。卫星点和短尾迹使用随采样时间变化的地固坐标,表示相对当前地球表面的实际位置;锁定后的预测轨道线使用锁定时刻固定的 `gstime`把未来一圈惯性轨道投到当前地球姿态上显示因此会闭合并且轨道面倾角应与详情卡一致。fallback 预测轨道也必须使用真正的 RAAN + inclination 轨道平面公式,不能把 inclination 当成恒定纬度。
国界精度偏好独立存储在 `country-boundaries.js``planet.earth.boundaries.highPrecisionEnabled`。未开启高精时,即使本机已经有高精 manifest/PMTiles也继续加载低精 `countries-admin0.min.geojson` fallback开启高精但高精产物缺失时Earth 工具栏设置会调用 `/api/v1/earth/boundaries/build` 启动后台构建并轮询进度。构建成功后调用 `reloadCountryBoundaries()` 热切换,不再刷新整个页面。国界 hover 与 tooltip 解耦:只要地表坐标落在国界 polygon 内就保持高亮如果鼠标同时命中卫星、船只、BGP 等 interactabletooltip 显示 interactable 信息,但国界高亮不应闪烁。
国界精度偏好独立存储在 `country-boundaries.js``planet.earth.boundaries.highPrecisionEnabled`。未开启高精时,即使本机已经有高精 manifest/PMTiles也继续加载低精 `countries-admin0.min.geojson` fallback开启高精但高精产物缺失时智能星球工具栏设置会调用 `/api/v1/earth/boundaries/build` 启动后台构建并轮询进度。构建成功后调用 `reloadCountryBoundaries()` 热切换,不再刷新整个页面。国界 hover 与 tooltip 解耦:只要地表坐标落在国界 polygon 内就保持高亮如果鼠标同时命中卫星、船只、BGP 等 interactabletooltip 显示 interactable 信息,但国界高亮不应闪烁。
## 当前地形链路

View File

@@ -1,6 +1,6 @@
# Earth Interactable 使用说明
# 智能星球 Interactable 使用说明
`Interactable` Earth 地表“图标类可交互元素”的通用渲染入口。它把船只图层验证过的模式抽成公共能力:普通态用批量 `THREE.Points`hover / locked 用少量 overlay拾取走屏幕空间命中图标资源统一转进 canvas texture并在公共层处理 glow、状态、尺寸、贴地渲染和同坐标避让。
`Interactable`智能星球地表“图标类可交互元素”的通用渲染入口。它把船只图层验证过的模式抽成公共能力:普通态用批量 `THREE.Points`hover / locked 用少量 overlay拾取走屏幕空间命中图标资源统一转进 canvas texture并在公共层处理 glow、状态、尺寸、贴地渲染和同坐标避让。
当前已接入:

View File

@@ -1,8 +1,8 @@
# Earth 图层样式属性索引
# 智能星球图层样式属性索引
本文记录当前 Earth 前端各图层的材质、颜色、透明度、线宽、半径偏移和
`renderOrder` 等样式属性。层级关系请配合
[Earth 渲染图层顺序](/home/ray/dev/linkong/planet/docs/technical/zh/earth-render-layer-order.md)
[智能星球渲染图层顺序](/home/ray/dev/linkong/planet/docs/technical/zh/earth-render-layer-order.md)
查看。
## 命名约定
@@ -20,12 +20,12 @@
| 正式名称 | 变量名 | 当前值 | 使用位置 / 说明 |
| --- | --- | --- | --- |
| Earth 基座半径 | `CONFIG.earthRadius` | `100` | `earth.js:createEarth()` |
| Earth 基座颜色 | `EARTH_MATERIAL_CONFIG.color` | `0x010609` | `MeshPhongMaterial.color` |
| Earth 基座 emissive | `EARTH_MATERIAL_CONFIG.emissive` | `0x010609` | `MeshPhongMaterial.emissive` |
| Earth 基座 specular | `EARTH_MATERIAL_CONFIG.specular` | `0x1a2d45` | `MeshPhongMaterial.specular` |
| Earth 基座 shininess | `EARTH_MATERIAL_CONFIG.shininess` | `12` | `MeshPhongMaterial.shininess` |
| Earth 基座 opacity | `EARTH_MATERIAL_CONFIG.opacity` | `1` | `MeshPhongMaterial.opacity` |
| 智能星球基座半径 | `CONFIG.earthRadius` | `100` | `earth.js:createEarth()` |
| 智能星球基座颜色 | `EARTH_MATERIAL_CONFIG.color` | `0x010609` | `MeshPhongMaterial.color` |
| 智能星球基座 emissive | `EARTH_MATERIAL_CONFIG.emissive` | `0x010609` | `MeshPhongMaterial.emissive` |
| 智能星球基座 specular | `EARTH_MATERIAL_CONFIG.specular` | `0x1a2d45` | `MeshPhongMaterial.specular` |
| 智能星球基座 shininess | `EARTH_MATERIAL_CONFIG.shininess` | `12` | `MeshPhongMaterial.shininess` |
| 智能星球基座 opacity | `EARTH_MATERIAL_CONFIG.opacity` | `1` | `MeshPhongMaterial.opacity` |
| 高清材质半径偏移 | `EARTH_MATERIAL_CONFIG.textureOverlayAltitudeOffset` | `0.48` | 独立高清材质球半径;必须与海陆基座和地球基座保持足够深度间距,避免远距 z-fighting |
| 高清材质透明度 | `EARTH_MATERIAL_CONFIG.textureOverlayOpacity` | `0.88` | 高清材质 `MeshPhongMaterial.opacity` |
| 高清材质 renderOrder | `EARTH_MATERIAL_CONFIG.textureOverlayRenderOrder` | `0.96` | `_earthTextureOverlay.renderOrder` |

View File

@@ -1,4 +1,4 @@
# Earth 渲染图层顺序
# 智能星球渲染图层顺序
本文记录当前 Earth 渲染器的图层顺序和每层意图。后续调整
`renderOrder`、半径偏移、深度策略或指针交互时,需要同步更新这里。
@@ -14,9 +14,9 @@
| 顺序 | 图层 | 来源 | 渲染 / 半径策略 | 深度 / 交互策略 | 备注 |
| --- | --- | --- | --- | --- | --- |
| -1000 | 天体背景 mesh | `celestial.js` | 背景球 | 不参与地表拾取 | 位于所有 Earth 内容之后。 |
| -1 | Earth 遮挡球 | `earth.js` | 地球内侧不可见球 | 写入深度 | 遮挡地球背面的对象。 |
| 0 | Earth 基座球 | `earth.js` | `CONFIG.earthRadius` | 地表拾取兜底目标 | 深色基座,所有可选地图层关闭时仍可见。 |
| -1000 | 天体背景 mesh | `celestial.js` | 背景球 | 不参与地表拾取 | 位于所有智能星球内容之后。 |
| -1 | 智能星球遮挡球 | `earth.js` | 地球内侧不可见球 | 写入深度 | 遮挡地球背面的对象。 |
| 0 | 智能星球基座球 | `earth.js` | `CONFIG.earthRadius` | 地表拾取兜底目标 | 深色基座,所有可选地图层关闭时仍可见。 |
| 0.2 | 国界暗色 tint | `country-boundaries.js` | `tintAltitudeOffset` | 禁用 raycast | 高清材质关闭时使用。 |
| 0.86 | 海陆基座填充 | `country-boundaries.js` | `landAltitudeOffset = 0.32`; 海洋 `#010609`,陆地 `#080f1b` | 禁用 raycast | 即使国界线关闭,基座地图仍保持可用;半径与基座球拉开以避免远距 z-fighting。 |
| 0.96 | 高清 Earth 材质 | `earth.js` | `textureOverlayAltitudeOffset = 0.48` | 可见时作为地表拾取目标 | 高清材质始终压过海陆基座填充;半径必须高于海陆基座并与基座球保持足够间距。 |
@@ -63,7 +63,7 @@ Earth 的地表不是单一 mesh而是多层近似同心球基座球、海
| 交互 | 当前规则 |
| --- | --- |
| Earth 坐标 hover | 高清材质可见时使用高清材质 overlay 作为地表拾取目标,否则使用 Earth 基座球。 |
| 智能星球坐标 hover | 高清材质可见时使用高清材质 overlay 作为地表拾取目标,否则使用智能星球基座球。 |
| 国界 hover | 先把地表拾取坐标转成经纬度,再用 GeoJSON 点面判断;国界 hover 线本身不接收 raycast。 |
| 国界 hover 视觉 | hover 时压暗普通国界线,并绘制无深度测试的光晕和实线。 |
| 中国 / 台湾 hover | `CHN``TWN` 被归到同一个 hover 高亮组tooltip 仍显示鼠标实际命中的 feature。 |

View File

@@ -1,10 +1,10 @@
# Earth 卫星覆盖策略
# 智能星球卫星覆盖策略
本文件记录 Earth 卫星图层当前关于 `footprint` 的产品边界、资料依据和已落地实现,目标是避免把 Starlink 这套专用地表覆盖模型误用到其它星座上。
相关上下文:
- [Earth 前端结构](/home/ray/dev/linkong/planet/docs/technical/zh/earth-frontend-context.md)
- [智能星球前端结构](/home/ray/dev/linkong/planet/docs/technical/zh/earth-frontend-context.md)
- [数据采集系统](/home/ray/dev/linkong/planet/docs/technical/zh/backend-collectors.md)
- [backend/app/services/collectors/celestrak.py](/home/ray/dev/linkong/planet/backend/app/services/collectors/celestrak.py)
- [frontend/public/earth/js/satellites.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/satellites.js)

View File

@@ -1,10 +1,10 @@
# Earth 工具栏与浮层协同
# 智能星球工具栏与浮层协同
本文件描述 Earth 大屏右侧工具栏按钮,以及搜索面板、设置弹窗、新闻直播面板、图层面板这几个浮层之间当前的协同规则。改交互、加按钮、调整面板时按这个表对齐,避免出现「点 A 把不该关的 B 也关了」之类的协同冲突。
相关入口:
- [Earth 前端结构](/home/ray/dev/linkong/planet/docs/technical/zh/earth-frontend-context.md)
- [智能星球前端结构](/home/ray/dev/linkong/planet/docs/technical/zh/earth-frontend-context.md)
- [前端布局指南](/home/ray/dev/linkong/planet/docs/technical/zh/frontend-layout-guidelines.md)
## 工具栏按钮目录

View File

@@ -1,6 +1,6 @@
# 常见问题
这页集中收录本地启动、Windows / WSL、依赖、动捕、凭证和 Docs 权限相关的常见排障路径。更完整的背景说明仍在对应专题文档中,这里只保留最常用的判断顺序和命令。
这页集中收录本地启动、Windows / WSL、依赖、动捕、凭证和文档权限相关的常见排障路径。更完整的背景说明仍在对应专题文档中,这里只保留最常用的判断顺序和命令。
## 启动与端口
@@ -321,7 +321,7 @@ Docs 按 Gatekeeper 权限组控制可见性:
- 快速开始、使用手册、FAQ 等基础文档公开可见。
- 开发文档通常需要 `docs_developer`
- 运维和服务控制文档通常需要 `docs_admin`
- `admin``super_admin` 默认具备 Docs 权限;普通用户需要在控制台“用户管理”中分配权限组。
- `admin``super_admin` 默认具备文档权限;普通用户需要在控制台“用户管理”中分配权限组。
## Earth 常见操作
@@ -332,9 +332,9 @@ Docs 按 Gatekeeper 权限组控制可见性:
要启用高精国界,有两条入口:
- Earth 页面齿轮设置里的“国界精度”:切到“高精”会启动首次后台下载/构建,并显示百分比,完成后自动应用。
- 控制台 `运维与配置 -> Earth 内容 -> 国界精度`:适合查看 provider、manifest、PMTiles、fallback 状态,编辑源配置 JSON或手动重建。
- 控制台 `运维与配置 -> 智能星球内容 -> 国界精度`:适合查看 provider、manifest、PMTiles、fallback 状态,编辑源配置 JSON或手动重建。
如果看到“更新源未配置完整”,先到 `Earth 内容 -> 国界精度` 保存源配置;本机私有配置写入 `config/earth-boundary-sources.local.json`,不要提交到仓库。没有高精产物时,使用低精 fallback 是正常行为。
如果看到“更新源未配置完整”,先到 `智能星球内容 -> 国界精度` 保存源配置;本机私有配置写入 `config/earth-boundary-sources.local.json`,不要提交到仓库。没有高精产物时,使用低精 fallback 是正常行为。
### Earth 位置候选采集后没有写入怎么办?
@@ -342,9 +342,9 @@ Docs 按 Gatekeeper 权限组控制可见性:
算力中心候选保存后会写入 `compute_center_locations`。没有可用候选的记录会保留在待定位列表中,系统不会用国家中心点或硬编码 hint 伪造位置。
### Earth 品牌 logo 或标题改完后为什么没恢复默认?
### 智能星球品牌 logo 或标题改完后为什么没恢复默认?
Earth 品牌资源在控制台 `运维与配置 -> Earth 内容 -> 品牌资源` 中维护。上传图片后页面会使用返回的 Earth 品牌资产地址如果只是清空标题、ARIA 文案等文本字段,系统会回退到默认标题,避免出现空白品牌。
智能星球品牌资源在控制台 `运维与配置 -> 智能星球内容 -> 品牌资源` 中维护。上传图片后页面会使用返回的智能星球品牌资产地址如果只是清空标题、ARIA 文案等文本字段,系统会回退到默认标题,避免出现空白品牌。
要恢复发布包自带的默认 logo、标题图和文案使用“重置品牌资源”。只刷新 Earth 页面不会删除已经保存的运行时品牌配置。

View File

@@ -22,7 +22,7 @@
- [App.tsx](/home/ray/dev/linkong/planet/frontend/src/App.tsx)
当前正式后台路由已经由 Admin 接管:
当前正式后台路由已经由控制台接管:
- `/admin`
- `/users`
@@ -37,7 +37,7 @@
- `/collection-management`
- `/settings`
这些路径渲染 [AdminRoutes.tsx](/home/ray/dev/linkong/planet/frontend/src/admin/AdminRoutes.tsx),页面清单和菜单元信息来自 [manifest.tsx](/home/ray/dev/linkong/planet/frontend/src/admin/routes/manifest.tsx)。Admin 是唯一后台控制台入口,不再维护并行控制台或回退路由。
这些路径渲染 [AdminRoutes.tsx](/home/ray/dev/linkong/planet/frontend/src/admin/AdminRoutes.tsx),页面清单和菜单元信息来自 [manifest.tsx](/home/ray/dev/linkong/planet/frontend/src/admin/routes/manifest.tsx)。控制台是唯一后台入口,不再维护并行控制台或回退路由。
`/earth` 是独立展示页,不属于控制台骨架。
@@ -53,11 +53,11 @@
- 当前账号、版本、退出登录和主题切换
- 顶部搜索、面包屑和页面快捷入口
- 内容区单屏高度闭合
- Admin 内部滚动、表格、详情面板和移动端详情视图协调
- 控制台内部滚动、表格、详情面板和移动端详情视图协调
后续正式控制台页面应适配 `AdminLayout` Admin 页面模式;不要重新引入并行后台壳层。
后续正式控制台页面应适配 `AdminLayout`控制台页面模式;不要重新引入并行后台壳层。
## Admin 分区加载策略
## 控制台分区加载策略
多 tab 页面由 [PlainResourcePages.tsx](/home/ray/dev/linkong/planet/frontend/src/admin/pages/PlainResourcePages.tsx) 统一承载当前的管理型和信息型工作台。分区加载规则是:
@@ -84,7 +84,7 @@ Admin 的数据源页把单源触发、表格勾选触发和触发全部统一
这个队列是用户感知层,不替代后端调度状态。后端仍然是任务是否运行、完成、失败或跳过的唯一事实来源。
## Admin 主题滑块
## 控制台主题滑块
Admin 侧栏底部主题切换继续复用共享 [SegmentedControl.tsx](/home/ray/dev/linkong/planet/frontend/src/components/SegmentedControl/SegmentedControl.tsx),但主题变量在 [styles.css](/home/ray/dev/linkong/planet/frontend/src/admin/styles.css) 内跟随 `data-theme` 覆盖:
@@ -125,7 +125,7 @@ Admin 侧栏底部主题切换继续复用共享 [SegmentedControl.tsx](/home/ra
当前使用场景:
- Admin 数据源、采集数据、采集管理、日志、告警和 BGP 页面
- 控制台数据源、采集数据、采集管理、日志、告警和 BGP 页面
### 3. `TableScrollRegion`
@@ -148,10 +148,10 @@ Admin 侧栏底部主题切换继续复用共享 [SegmentedControl.tsx](/home/ra
用途:
- Admin 全局工具按钮和详情页工具按钮
- 控制台全局工具按钮和详情页工具按钮
- icon-only + tooltip 的普通操作
- 保存、创建、确认、删除、停止等强意图操作
- Docs 主题滑块一致的紧凑开关
-文档主题滑块一致的紧凑开关
当前约束:
@@ -198,7 +198,7 @@ Admin 侧栏底部主题切换继续复用共享 [SegmentedControl.tsx](/home/ra
- 渲染 `/docs` 的 Markdown 正文
- 支持标题、列表、引用、代码块、表格和基础行内格式
- 代码块和表格内部复用 `Scrollbar`,避免横向内容撑爆文档页
- Docs 正文由后端 `/api/v1/docs/...` 按 Gatekeeper 权限返回;前端只渲染当前用户可见内容
- 文档正文由后端 `/api/v1/docs/...` 按 Gatekeeper 权限返回;前端只渲染当前用户可见内容
当前约束:
@@ -206,7 +206,7 @@ Admin 侧栏底部主题切换继续复用共享 [SegmentedControl.tsx](/home/ra
- 文档内部链接应通过 `transformLink` 转成 `/docs/:slug`
- 标题锚点由 `getHeadingId` 注入,避免渲染器自己理解路由状态
### 7. Admin UI primitives
### 7. 控制台 UI primitives
文件:
@@ -217,7 +217,7 @@ Admin 侧栏底部主题切换继续复用共享 [SegmentedControl.tsx](/home/ra
用途:
- 全局工具按钮、详情页动作、确认弹窗和二元设置。
- 与 Tactile UI token 对齐,保持 Admin 内部控件尺寸、hover、disabled 和 dark mode 一致。
- 与 Tactile UI token 对齐,保持控制台内部控件尺寸、hover、disabled 和 dark mode 一致。
- 表格行内动作优先使用 icon button + tooltip/title不重新引入独立操作菜单组件。
## 当前状态来源
@@ -326,9 +326,9 @@ Admin 侧栏底部主题切换继续复用共享 [SegmentedControl.tsx](/home/ra
### 采集器设置页
[Settings.tsx](/home/ray/dev/linkong/planet/frontend/src/admin/pages/PlainResourcePages.tsx) 会按路由进入三种模式:`/settings` 是系统设置,`/earth-content` Earth 内容,`/collection-management` 是采集管理。`collector_credentials` tab 当前在 `/collection-management` 下显示为“采集器”。
[Settings.tsx](/home/ray/dev/linkong/planet/frontend/src/admin/pages/PlainResourcePages.tsx) 会按路由进入三种模式:`/settings` 是系统设置,`/earth-content`智能星球内容,`/collection-management` 是采集管理。`collector_credentials` tab 当前在 `/collection-management` 下显示为“采集器”。
`/settings` 的“系统显示”分区包含 `演示模式` 开关。开启后,Earth 的 OOBE 会忽略“已有当前采集数据”和本地“先浏览”临时跳过状态,直接展示初始化引导;该开关仅用于演示/验收流程,不改变数据源、采集队列或 Earth 内容资源配置。
`/settings` 的“系统显示”分区包含 `演示模式` 开关。开启后,智能星球的 OOBE 会忽略“已有当前采集数据”和本地“先浏览”临时跳过状态,直接展示初始化引导;该开关仅用于演示/验收流程,不改变数据源、采集队列或智能星球内容资源配置。
当前页面边界:
@@ -359,7 +359,7 @@ Admin 侧栏底部主题切换继续复用共享 [SegmentedControl.tsx](/home/ra
- [数据源、采集器设置与连接验证](/home/ray/dev/linkong/planet/docs/technical/zh/datasource-collector-settings-connectivity.md)
### Earth 内容页
### 智能星球内容页
`/earth-content` 复用 [Settings.tsx](/home/ray/dev/linkong/planet/frontend/src/admin/pages/PlainResourcePages.tsx) 的单屏 tab 容器,但页面责任与系统设置分离:

View File

@@ -2,7 +2,7 @@
`backend/app/services/location/` 是所有“给定一条记录,决定它的 lat/lon”业务的共享抽象。算力中心、BGP 观测站、BGP 事件目前都跑在这条管线上。未来需要位置估算的实体例如卫星地面站、用户认领点位、IXP 设施,也应接入这里,而不是各自再写地理解析逻辑。
用户侧流程见 [Planet 使用手册](/home/ray/dev/linkong/planet/docs/technical/zh/manual.md) 的 Earth 位置候选采集章节。
用户侧流程见 [智能星球使用手册](/home/ray/dev/linkong/planet/docs/technical/zh/manual.md) 的 Earth 位置候选采集章节。
## 设计目标

View File

@@ -1,15 +1,15 @@
# Planet 使用手册
# 智能星球使用手册
这份手册面向 Planet 的最终用户。从打开浏览器开始,覆盖注册账号、登录、配置数据采集器、配置 AI、使用 Earth 和控制台、阅读文档站。所有操作都在浏览器里完成。
这份手册面向智能星球的最终用户。从打开浏览器开始,覆盖注册账号、登录、配置数据采集器、配置 AI、使用智能星球和控制台、阅读文档站。所有操作都在浏览器里完成。
如果你是负责部署或值班的运维,请改读 [Planet 运维手册](/home/ray/dev/linkong/planet/docs/technical/zh/ops-runbook.md),里面是 shell 命令、日志位置、SMTP 兜底创建用户等内容。
如果你是负责部署或值班的运维,请改读 [智能星球运维手册](/home/ray/dev/linkong/planet/docs/technical/zh/ops-runbook.md),里面是 shell 命令、日志位置、SMTP 兜底创建用户等内容。
## 入口总览
| 名称 | 地址 | 是否需要登录 | 说明 |
| --- | --- | --- | --- |
| Earth | `http://<域名>/earth` | 否 | 公开 3D 地球态势页面 |
| Docs | `http://<域名>/docs` | 部分需要 | 公共文档免登录,开发/运维文档按 Gatekeeper 权限组开放 |
| 智能星球 | `http://<域名>/earth` | 否 | 公开 3D 态势页面 |
| 文档 | `http://<域名>/docs` | 部分需要 | 公共文档免登录,开发/运维文档按 Gatekeeper 权限组开放 |
| 注册 / 登录 / 找回密码 | `/register``/login``/forgot-password` | 否 | 自助开通和恢复账号 |
| 控制台 | `http://<域名>/admin` | 是 | 数据、采集器、告警、AI、用户、设置 |
| AI | `http://<域名>/ai` | 是 | 模型供应商、工具和测试台 |
@@ -68,7 +68,7 @@
| 页面 | 路由 | 用途 |
| --- | --- | --- |
| 仪表盘 | `/admin` | 系统概览 |
| Earth | `/earth` | 跳到公开 Earth 页面 |
| 智能星球 | `/earth` | 跳到公开智能星球页面 |
| 数据源 | `/datasources` | 数据源目录、触发采集 |
| 采集数据 | `/data` | 已落库的数据 |
| BGP 观测 | `/bgp` | BGP 专题观测 |
@@ -76,7 +76,7 @@
| BGP 告警 | `/alerts/bgp` | BGP 相关告警 |
| 态势告警 | `/alerts/situational` | 态势研判告警 |
| AI | `/ai` | 模型供应商、工具、测试台 |
| Earth 内容 | `/earth-content` | 电视直播、国界精度、底图和图层资源入口 |
| 智能星球内容 | `/earth-content` | 电视直播、国界精度、底图和图层资源入口 |
| 采集管理 | `/collection-management` | 采集器、采集调度、采集历史入口 |
| 系统日志 | `/logs` | 通常仅 super admin 可见 |
| 用户管理 | `/users` | 创建/删除/改角色/调权限组 |
@@ -186,19 +186,19 @@ Base URL 输入框尾端的插头图标会触发连接测试。测试通过会
电视直播和国界精度已经移到 `/earth-content`,采集器和采集调度已经移到 `/collection-management`AI Provider / WebSearch / OCR 在 `/ai`
### Earth 内容
### 智能星球内容
`/earth-content` 位于控制台“运维与配置”下,面向 Earth 前端体验资源:
`/earth-content` 位于控制台“运维与配置”下,面向智能星球前端体验资源:
- **品牌资源**:维护 Earth HUD 使用的 logo、标题图、标题文本、副标题和描述上传的图片会保存为 Earth 品牌资产并立即供 Earth 页面读取。
- **关于**:维护 Earth 设置面板里的关于卡片,包括 logo、眉标、标题、版本、描述和元信息。
- **电视直播**:维护 Earth 媒体面板里的直播源。
- **品牌资源**:维护智能星球 HUD 使用的 logo、标题图、标题文本、副标题和描述上传的图片会保存为智能星球品牌资产并立即供智能星球页面读取。
- **关于**:维护智能星球设置面板里的关于卡片,包括 logo、眉标、标题、版本、描述和元信息。
- **电视直播**:维护智能星球媒体面板里的直播源。
- **国界精度**:查看当前国界 provider、低精 fallback、高精 PMTiles/manifest 状态,编辑本机源配置并手动构建。
- **地球底图**、**图层资源**、**三维素材**、**新闻锚点策略**:目前是待接入占位页,不展示假数据。
Earth 页面工具栏齿轮中也有“国界精度”。切到“高精”时,如果本机尚未构建高精资产,会像游戏更新包一样启动后台下载/构建并显示百分比;构建成功后自动应用,无需刷新。切回“低精”只切换本机显示偏好,不重新下载。
智能星球页面工具栏齿轮中也有“国界精度”。切到“高精”时,如果本机尚未构建高精资产,会像游戏更新包一样启动后台下载/构建并显示百分比;构建成功后自动应用,无需刷新。切回“低精”只切换本机显示偏好,不重新下载。
如果后端判断 Earth 尚未初始化,首次进入 `/earth` 会出现毛玻璃引导,提示登录控制台并采集数据。这个判断来自后端真实数据状态;如果系统已经有已采集数据,清空浏览器缓存也不会重新弹出。
如果后端判断智能星球尚未初始化,首次进入 `/earth` 会出现毛玻璃引导,提示登录控制台并采集数据。这个判断来自后端真实数据状态;如果系统已经有已采集数据,清空浏览器缓存也不会重新弹出。
### 采集管理
@@ -229,7 +229,7 @@ Earth 页面工具栏齿轮中也有“国界精度”。切到“高精”时
- 查看用户列表(用户名、邮箱、角色、是否激活、邮箱是否已验证)
- 创建用户:与公开注册等价,但跳过邮箱验证(管理员认账)
- 修改角色:`viewer` / `operator` / `admin` / `super_admin`
- 调整 Gatekeeper 权限组:`docs_user` / `docs_developer` / `docs_admin`,影响 Docs 站可见文档范围
- 调整 Gatekeeper 权限组:`docs_user` / `docs_developer` / `docs_admin`,影响文档站可见文档范围
- 禁用 / 启用账号
要让普通用户能看开发或运维文档,进 `/users` 给他加 `docs_developer``docs_admin`
@@ -238,7 +238,7 @@ Earth 页面工具栏齿轮中也有“国界精度”。切到“高精”时
- `/datasources`:数据源目录。`内置源` 支持按产品域、层级、启用状态、最近执行状态、是否已有采集数据和关键词筛选;未勾选时主按钮显示“触发全部”,勾选多行后会变成“触发已选 N”并只提交所选数据源。右上角队列按钮空态显示队列图标有任务时显示纯圆环总进度点击后打开队列浮层按运行中、完成、失败和跳过分组失败项可重试完成项可跳到详情。`实时源` 面向 AISStream / WebSocket 长连接,展示连接健康、累计入库、时间窗统计和启动 / 停止 / 重连操作。接口、凭证、请求头的编辑统一在 `/collection-management` 的"采集器"。
- `/data`:采集后数据表,适合排查"数据是否已经进入系统"、"更新时间是否符合预期"、"某个数据源是否产出有效记录"
- `/bgp`BGP 专题页面,列表 + 详情 + 研判,与 Earth 的 BGP 图层互补
- `/bgp`BGP 专题页面,列表 + 详情 + 研判,与智能星球的 BGP 图层互补
- `/alerts/system``/alerts/bgp``/alerts/situational`系统、BGP、态势告警
## AI 测试台
@@ -251,9 +251,9 @@ Earth 页面工具栏齿轮中也有“国界精度”。切到“高精”时
旧链接 `/playground` 会跳到这里。
## Earth 公开页面
## 智能星球公开页面
Earth `http://localhost:3000/earth` 是公开 3D 态势页面不需要登录。React 路由中的 `/earth` 用 iframe 承载独立前端(位于 `frontend/public/earth/`)。
智能星球 `http://localhost:3000/earth` 是公开 3D 态势页面不需要登录。React 路由中的 `/earth` 用 iframe 承载独立前端(位于 `frontend/public/earth/`)。
### 主要用途
@@ -283,14 +283,14 @@ AIS 船只图例按船型显示颜色:货轮、油轮、客船、渔船、军
算力中心和 BGP 观测站详情卡支持自动采集坐标候选。点击对象后用"自动采集坐标候选"或"重新自动采集坐标"按钮,后端会从源坐标、开放组织注册 API 和在线地理编码中整理候选;常规来源没有候选时使用当前默认 AI Provider 做 LLM factcheck 兜底。BGP 观测站的已存储位置只用于补齐查询上下文,不会作为候选直接返回。
候选可以直接在 Earth 预览。算力中心候选点击"保存"后写入 `compute_center_locations` 维表并刷新图层。算力中心图层左上角的通知气泡显示无法渲染的待定位数量;点击查看列表,单条采集候选,或用"一键采用"从上到下保存最高置信候选。没有可用候选的记录会留在列表中,不会被国家中心点或硬编码 hint 伪造位置。
候选可以直接在智能星球预览。算力中心候选点击"保存"后写入 `compute_center_locations` 维表并刷新图层。算力中心图层左上角的通知气泡显示无法渲染的待定位数量;点击查看列表,单条采集候选,或用"一键采用"从上到下保存最高置信候选。没有可用候选的记录会留在列表中,不会被国家中心点或硬编码 hint 伪造位置。
单个对象的推荐流程:
1. 打开算力中心或 BGP 观测站详情卡。
2. 点击"自动采集坐标候选"。
3. 等待候选列表返回;有 WebSearch / AI factcheck 依赖的候选会显示采集中状态。
4. Earth 上预览候选位置。
4.智能星球上预览候选位置。
5. 确认可用候选后点击"保存";不确定时关闭卡片不会丢失当前任务状态。
一键定位用于批量处理算力中心待定位队列。它会从列表顶部开始采用最高置信候选;仍没有事实依据的记录会保留在队列中。未开启 WebSearch 时,单个定位和一键定位会置灰,因为位置核验依赖事实查询。
@@ -324,12 +324,12 @@ AIS 船只图例按船型显示颜色:货轮、油轮、客船、渔船、军
### 动作捕捉控制
Earth 预留了动作捕捉控制入口。实时链路两种输入源:
智能星球预留了动作捕捉控制入口。实时链路两种输入源:
- **浏览器摄像头**(默认):直接用网页 `getUserMedia` 在本机浏览器识别;无需安装应用,但页面必须运行在 HTTPS 或 localhost且需允许浏览器摄像头权限
- **Motion Agent**:摄像头/RTSP/HTTP → 本地 Agent → 本地 WebSocket → Earth 页面用于双摄、USB index、手机/网络摄像头流
- **Motion Agent**:摄像头/RTSP/HTTP → 本地 Agent → 本地 WebSocket → 智能星球页面用于双摄、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`
打开方式:设置中开启"动捕调试模式",或加 URL 参数 `?motion=1` 打开智能星球动捕连接。Motion Agent 默认地址 `ws://127.0.0.1:8765/ws/gestures`,可用 `motionAgent` URL 参数覆盖。也可以直接 `?motion=1&motionProvider=browser``?motion=1&motionProvider=agent`
两种模式都不会把摄像头帧或实时手势发到云端,也不会复用新闻/RSS 聚合接口。
@@ -347,7 +347,7 @@ Earth 预留了动作捕捉控制入口。实时链路两种输入源:
### 巡航模式
巡航模式让 Earth 自动轮播聚焦目标。当前巡航模块BGP、新闻、算力中心、船只、海缆、卫星。适合演示、监控大屏或无人值守。
巡航模式让智能星球自动轮播聚焦目标。当前巡航模块BGP、新闻、算力中心、船只、海缆、卫星。适合演示、监控大屏或无人值守。
### 移动端
@@ -355,27 +355,27 @@ Earth 预留了动作捕捉控制入口。实时链路两种输入源:
### 常见问题
- **Earth 打不开**:先确认前端服务是否在线;如果端口不是 `3000`,使用启动输出的实际端口
- **智能星球打不开**:先确认前端服务是否在线;如果端口不是 `3000`,使用启动输出的实际端口
- **图层没有数据**:进 `/datasources` 看数据源状态、是否已采集和最近执行结果,再到 `/data``/bgp` 看是否有记录
- **卫星 / BGP / 海缆加载慢**:这些图层依赖后端接口和外部数据源,首次加载需要等启动任务完成
- **卫星看起来不在同一层**:这是默认的真实高度压缩显示。想回到旧版同层球面,可在设置中关闭“真实卫星高度”
## Docs 文档站
## 文档站
文档站 `http://localhost:3000/docs` 由后端按权限读取,不再把全部 Markdown 直接打进前端构建产物。
未登录访客默认只能看到 `public` 文档:首页、快速开始、使用手册、常见问题。登录用户被分配 Gatekeeper 权限组后可以看到更多技术文档:
- `docs_user`:用户操作类文档
- `docs_developer`Earth、前端、后端、采集器和 AI Provider 等开发文档
- `docs_developer`智能星球、前端、后端、采集器和 AI Provider 等开发文档
- `docs_admin`:服务控制、运维、环境变量和敏感操作文档(包括运维手册)
`admin` 默认拥有 `docs_admin``super_admin` 拥有全部 Docs 权限。Gatekeeper 权限组在"用户管理"中配置。
`admin` 默认拥有 `docs_admin``super_admin` 拥有全部文档权限。Gatekeeper 权限组在"用户管理"中配置。
Docs 支持分类导航、Markdown 渲染、表格和代码块、文档内目录、对当前可见文档搜索、technical 文档间内部链接跳转。
文档站支持分类导航、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)
- [智能星球运维手册](/home/ray/dev/linkong/planet/docs/technical/zh/ops-runbook.md)

View File

@@ -1,6 +1,6 @@
# 命名与术语对照
本文约定 Planet 控制台、Earth、后端 API 和文档中的常见名词。新增 UI 文案、接口字段展示、图表标签和文档说明时,优先使用这里的中文名,避免同一页面中出现不必要的中英混合。
本文约定智能星球、控制台、后端 API 和文档中的常见名词。新增 UI 文案、接口字段展示、图表标签和文档说明时,优先使用这里的中文名,避免同一页面中出现不必要的中英混合。
## 使用规则
@@ -14,9 +14,9 @@
| English / Key | 中文显示名 | 使用场景 |
| --- | --- | --- |
| Planet | Planet | 产品名,保留英文 |
| Planet | 智能星球 | 产品名和主体验入口 |
| Admin | 控制台 | 管理端上下文 |
| Earth | Earth | 地球可视化产品名,保留英文 |
| Earth | 智能星球 | 可视化产品名`/earth` 入口 |
| datasource | 数据源 | API、列表、筛选 |
| collector | 采集器 | 采集任务、凭证配置 |
| collected data | 采集数据 | 数据列表、统计 |
@@ -56,7 +56,7 @@
| `device_stats` | 设备统计 | Cloudflare Radar 设备统计 |
| `traffic_stats` | 流量统计 | Cloudflare Radar 流量统计 |
| `as_stats` | 自治系统统计 | Cloudflare Radar AS 统计 |
| `compute_center` | 算力中心 | Earth 聚合展示对象 |
| `compute_center` | 算力中心 | 智能星球聚合展示对象 |
| `generic` | 通用数据 | 通用采集输出 |
| `generic_records` | 通用记录 | 通用映射输出 |

View File

@@ -334,7 +334,7 @@ MOTION_AGENT_DRY_RUN=1 PLANET_START_MOTION_AGENT=1 ./planet.sh start
./planet.sh start --allow-lan --motion-agent
```
此时 Motion Agent 会绑定 `0.0.0.0`,启动输出会同时显示本机 WebSocket 地址和推荐局域网 WebSocket 地址。局域网浏览器访问 Earth 时,需要把 `motionAgent` 参数指向这台大屏主机,例如:
此时 Motion Agent 会绑定 `0.0.0.0`,启动输出会同时显示本机 WebSocket 地址和推荐局域网 WebSocket 地址。局域网浏览器访问智能星球时,需要把 `motionAgent` 参数指向这台大屏主机,例如:
```text
http://<LAN_IP>:3000/earth?motion=1&motionAgent=ws://<LAN_IP>:8765/ws/gestures

View File

@@ -1,6 +1,6 @@
# Planet 运维手册
# 智能星球运维手册
这份手册面向部署、值班和二次开发的运维人员。客户面向的 UI 使用流程见 [Planet 使用手册](/home/ray/dev/linkong/planet/docs/technical/zh/manual.md),本手册只覆盖 shell、Docker、日志、环境变量和故障排查。
这份手册面向部署、值班和二次开发的运维人员。客户面向的 UI 使用流程见 [智能星球使用手册](/home/ray/dev/linkong/planet/docs/technical/zh/manual.md),本手册只覆盖 shell、Docker、日志、环境变量和故障排查。
## 首次启动
@@ -315,11 +315,11 @@ uv run pytest backend/tests/test_otp_service.py
## Earth 国界 PMTiles 操作步骤
1. 在控制台 `运维与配置 -> Earth 内容 -> 国界精度` 保存国界源配置;本机配置写入 `config/earth-boundary-sources.local.json`,不要提交。
1. 在控制台 `运维与配置 -> 智能星球内容 -> 国界精度` 保存国界源配置;本机配置写入 `config/earth-boundary-sources.local.json`,不要提交。
2. 点击“构建高精国界”,或在 Earth 页面工具栏齿轮中切到“高精”触发首次构建。后端会下载三类源到 `data/earth-boundary-sources/`,生成 source manifest并调用 PMTiles 构建脚本。
3. 构建器需要本机 PATH 里有 `tippecanoe``pmtiles`。缺工具时接口返回明确错误,不会写入数据源采集记录。
4. 构建成功后应输出 `frontend/public/earth/data/boundaries/earth-boundaries-china-pov-v1.pmtiles` 和对应 manifest。
5. 部署后打开 Earth,开启“国界线”,放大中国东南海岸、台湾、海南、南海、藏南、科索沃、加沙等区域验证 hover 和边界口径。
5. 部署后打开智能星球,开启“国界线”,放大中国东南海岸、台湾、海南、南海、藏南、科索沃、加沙等区域验证 hover 和边界口径。
6. 如果本地没有高精 manifest/PMTilesEarth 会使用 `frontend/public/earth/data/countries-admin0.min.geojson` 低精度 fallback如果高精产物存在但瓦片请求失败按 PMTiles range 请求、manifest provider、Nginx `.pmtiles` 静态返回和 sha256 一致性排查。
## 相关文档

View File

@@ -1,10 +1,10 @@
# 业务架构与数据流转
本文是 Planet 数据产品的业务入口。它解释每类 Earth 数据为什么存在、从哪里采集、落到哪些事实表或派生表、如何通过缓存和 WebSocket 反映到 Earth。前端、后端和 Earth 技术文档只记录实现细节;跨端理解数据链路时优先从这里开始。
本文是智能星球数据产品的业务入口。它解释每类 Earth 数据为什么存在、从哪里采集、落到哪些事实表或派生表、如何通过缓存和 WebSocket 反映到 Earth。前端、后端和 Earth 技术文档只记录实现细节;跨端理解数据链路时优先从这里开始。
## 总览
Planet 的核心数据链路分三段:
智能星球的核心数据链路分三段:
1. **采集与整理**:内置采集器、后台操作或定位管线写入 PostgreSQL。通用原始结果进入 `collected_data`,图层需要的二次结果进入派生表。
2. **投影与广播**:数据库触发器把事实变化写入 `earth_data_change_events` outbox并用 `LISTEN/NOTIFY` 唤醒后端 listener。listener 通过 layer adapter 找到 Earth 图层,失效缓存并广播 `earth_updates`
@@ -43,7 +43,7 @@ flowchart TB
NewsItems --> NewsLayer["news / media 图层"]
```
| 数据产品 | 业务用途 | 事实来源 | 派生 / 维表 | Earth 图层 | 刷新策略 |
| 数据产品 | 业务用途 | 事实来源 | 派生 / 维表 | 智能星球图层 | 刷新策略 |
| --- | --- | --- | --- | --- | --- |
| 卫星 | 展示在轨目标、轨迹、覆盖和巡航目标 | `celestrak_tle``spacetrack_tle` | 无稳定独立派生表TLE 由接口实时转换 | `satellites` | `clear_then_reload` |
| 海缆与登陆点 | 展示跨洋连接、登陆点和 cable 详情 | `arcgis_cables``arcgis_landing_points`、TeleGeography / FAO landing sources | 海缆关系和登陆点聚合数据 | `cables` | `clear_then_reload` |

View File

@@ -1,8 +1,8 @@
# 快速开始
这份快速开始面向 Planet 的最终用户:你拿到了管理员给的访问地址,要从打开浏览器到第一次完成配置之间的最短路径。所有操作都在浏览器里完成。
这份快速开始面向智能星球的最终用户:你拿到了管理员给的访问地址,要从打开浏览器到第一次完成配置之间的最短路径。所有操作都在浏览器里完成。
如果你是负责部署或运维的同事,请改读 [Planet 运维手册](/home/ray/dev/linkong/planet/docs/technical/zh/ops-runbook.md)。
如果你是负责部署或运维的同事,请改读 [智能星球运维手册](/home/ray/dev/linkong/planet/docs/technical/zh/ops-runbook.md)。
## 1. 打开访问地址
@@ -11,7 +11,7 @@
入口分两类:
- 公开页:`/earth`3D 态势)、`/docs`(公共文档)
- 登录后:`/admin`(控制台)、`/ai`AI`/settings`(系统设置)、`/earth-content`Earth 内容)、`/collection-management`(采集管理)
- 登录后:`/admin`(控制台)、`/ai`AI`/settings`(系统设置)、`/earth-content`智能星球内容)、`/collection-management`(采集管理)
## 2. 注册账号
@@ -38,17 +38,17 @@
4. `/alerts/system`:看系统告警是否正常
5. `/users`(仅 `super_admin`):根据需要给同事开账号或调权限组
## 4. 打开 Earth
## 4. 打开智能星球
访问 `/earth`,公开页面,不需要登录。
如果系统还没有已采集数据,Earth 会显示初始化引导,提示登录控制台并触发采集。这个引导由后端状态决定,不会因为清空浏览器缓存而误判。
如果系统还没有已采集数据,智能星球会显示初始化引导,提示登录控制台并触发采集。这个引导由后端状态决定,不会因为清空浏览器缓存而误判。
进入后建议确认:
- 地球正常显示,右侧图层面板可以打开/关闭
- 搜索可以查找海缆、卫星、算力中心、BGP 事件
- 算力中心和 BGP 观测站详情卡可以自动采集坐标候选,并能在 Earth 上预览
- 算力中心和 BGP 观测站详情卡可以自动采集坐标候选,并能在智能星球上预览
- 鼠标拖动、滚轮缩放、缩放百分比提示工作正常
- 设置面板的旋转 / 巡航 / 动捕模式可以切换;视图设置里可以切换悬停提示,卫星相关设置里可以打开或关闭真实高度分层和轨迹显示
@@ -62,7 +62,7 @@
## 下一步
- 完整 UI 操作说明:[Planet 使用手册](/home/ray/dev/linkong/planet/docs/technical/zh/manual.md)
- 完整 UI 操作说明:[智能星球使用手册](/home/ray/dev/linkong/planet/docs/technical/zh/manual.md)
- 排障与配置疑问:[常见问题](/home/ray/dev/linkong/planet/docs/technical/zh/faq.md)
- Earth 坐标候选采集流程见 [Planet 使用手册](/home/ray/dev/linkong/planet/docs/technical/zh/manual.md) 的 Earth 章节
- 部署 / 运维相关命令:[Planet 运维手册](/home/ray/dev/linkong/planet/docs/technical/zh/ops-runbook.md)
- 智能星球坐标候选采集流程见 [智能星球使用手册](/home/ray/dev/linkong/planet/docs/technical/zh/manual.md) 的智能星球章节
- 部署 / 运维相关命令:[智能星球运维手册](/home/ray/dev/linkong/planet/docs/technical/zh/ops-runbook.md)

View File

@@ -4,7 +4,7 @@ Tactile UI 是 Planet 内部抽出的可移植 React 控件层。它来自 Admin
## 设计目标
- **轻触感**:默认控件使用白色或主题表面、细边框和外部投影,接近 Docs 主题滑块的轻微立体感,不使用大色块或发光效果。
- **轻触感**:默认控件使用白色或主题表面、细边框和外部投影,接近文档主题滑块的轻微立体感,不使用大色块或发光效果。
- **可移植**:组件 class 使用 `tui-*` 前缀,样式集中在 `frontend/src/components/tactile-ui/styles.css`
- **低依赖**:组件只假设 React/React DOM图标预设当前使用 `lucide-react`,调用方也可以传自定义 React 节点。
- **主题友好**:默认样式通过 CSS variables 暴露Planet 可以在 Admin 或其它页面按主题覆盖 token。
@@ -122,7 +122,7 @@ body[data-admin-theme='dark'] .tui-button {
## `TactileSwitch`
开关组件用于二元设置。它不是 iOS 风格大开关,而是与 Docs 主题滑块一致的小型轻触感控件。
开关组件用于二元设置。它不是 iOS 风格大开关,而是与文档主题滑块一致的小型轻触感控件。
```tsx
<TactileSwitch