release: bump version to 0.74.4
This commit is contained in:
rayd1o
@@ -95,12 +95,15 @@ AI 配置页使用的接口：
|
||||
- `POST /api/v1/settings/integrations/ai-provider/connect`
|
||||
- `GET /api/v1/settings/integrations/ai-provider/secrets`
|
||||
- `GET /api/v1/settings/integrations/ai-provider/presets`
|
||||
- `POST /api/v1/settings/integrations/ai-provider/presets/{provider}/refresh`
|
||||
- `GET /api/v1/settings/ai-prompts`
|
||||
- `PUT /api/v1/settings/ai-prompts/{task_key}`
|
||||
- `POST /api/v1/settings/ai-prompts/{task_key}/reset`
|
||||
|
||||
这些接口都需要用户登录。`secrets` 接口只用于配置页点击显示 key/token 时取回明文，隐藏时前端恢复为脱敏预览。
|
||||
|
||||
模型目录刷新由 `backend/app/services/llm_provider_catalog.py` 获取上游目录；多数供应商读取 models.dev，OpenCode Go 使用自己的模型接口。models.dev 条目按发布日期倒序排列，缺少日期的条目排在后面。成功结果和 `refreshed_at` 按供应商保存在 `system_settings` 的 `llm_provider_preset:<provider>` 分类中，列表接口优先返回已保存目录，未刷新过的供应商使用内置预设。刷新只更新目录，不写入 `external_integrations` 中的当前模型、协议、地址或凭证。失败返回 502 并保留上次目录；上游异常原文不返回客户端。前端重新加载目录，可选模型读取目录状态，表单草稿独立保留。
|
||||
|
||||
Admin 的 AI 页面按业务信息架构组织为：
|
||||
|
||||
- `模型供应商`
|
||||
|
||||
@@ -102,6 +102,12 @@ AIS 船只类采集器和其它 `CollectedData` 采集器的落库路径不同
|
||||
|
||||
TOP500 和 Epoch AI 算力数据的公开源不总是提供可用经纬度。Earth 统一算力中心接口在主地图启动链路中只使用源数据自带坐标或 `compute_center_locations` 维表坐标；缺少坐标的记录会进入 `unresolved`，不会通过本地注册表、国家质心或猜测城市自动渲染。用户手动采集候选时，后端会用源字段调用 ROR 组织注册 API 和 Nominatim/OpenStreetMap 在线搜索；候选经前端保存后写入 `compute_center_locations`，后续地图刷新再从维表渲染。
|
||||
|
||||
### 新闻直播频道目录
|
||||
|
||||
`news_live_streams` 的 IPTV-org 适配器保留现有新闻分类筛选，`max_sources` 默认值为 `0`，表示不截断匹配频道；显式正数仍限制采集数量。已有配置若保留旧的 `120`，需要改为 `0` 并重新采集才能补齐目录。
|
||||
|
||||
`GET /api/v1/tv/streams` 由 `tv_catalog.py` 提供数据库分页：`offset` 默认 `0`，`limit` 默认 `50`、最大 `100`，`q` 按空白拆词并匹配频道名、来源、地区和语言。内置及配置源优先，采集源按频道标识去重并排除配置覆盖项，再在数据库中搜索、计数、排序和分页，避免全表读取后切片。响应的 `total` 是匹配总数，`source_count` 是完整可用目录数量；后续页使用 `next_offset` 和 `has_more`。`selected_id` 可额外取得不在当前页的已选频道，不占本页配额。默认和兜底源继续由 `tv_streams.py` 统一管理。
|
||||
|
||||
## 四、数据格式 (统一存储到 CollectedData 表)
|
||||
|
||||
```python
|
||||
@@ -382,7 +388,11 @@ GET /api/v1/visualization/vessels/{mmsi}/conflicts
|
||||
|
||||
`/api/v1/vessels/snapshot` 必须携带 `bbox` 和 `zoom`，后端最大 `limit=5000`。Earth 前端使用全球 bbox 读取当前状态，不随相机视口变化反复请求。接口消费 `vessel_current_state`，并在 `diagnostics.source` 返回 `vessel_current_state`；旧 `/api/v1/visualization/geo/vessels` 路由已移除。
|
||||
|
||||
高频 AIS 更新不要直接推送成每条 delta 的整层重建。`/ws` 的 `vessels` channel 如用于 Earth，应广播低频 reload/dirty 提示，由前端合并刷新 snapshot；轨迹和冲突详情仍按单船接口读取历史事实。
|
||||
AISStream 与 BarentsWatch 共用 `/ws` 的 `vessels` 增量通道。Earth 使用现有 WebSocket 连接订阅 `scope: "global"`，不跟随镜头改变订阅范围。后端按 MMSI 合并一秒内的通知，再读取 `vessel_current_state` 的已确认状态；单帧最多 1000 项，超过时继续发送后续帧，不截断不同船只。原始源消息不能直接覆盖客户端的确认位置。当前状态删除也会产生按 MMSI 的 remove 通知。
|
||||
|
||||
前端将短时间内同一 MMSI 的变更合并为最新值，通过 `Interactable.updateItems()` 原位修改位置和颜色缓冲。航向分桶变更只更新受影响的桶，容量不足才扩容；保留已有 marker 身份、锁定状态和材质。首次进入、重连、删除提示及每分钟巡检仍用 snapshot 校准，但不先清空整个图层。收到有数量上限的快照时，不能把被截断的船只当成删除；快照返回期间到达的较新更新和删除也不能被旧响应覆盖。快照携带查询开始时的 `generated_at`，与实时帧时间一起用于识别缓存旧快照，避免新船或删除状态被回滚。
|
||||
|
||||
`earth_updates` 中船舶普通写入的策略是 `delta`；专用通道连通时不再触发整层重拉。删除或断连后的校准使用 `reload`，并复用现有对象。关闭图层会取消船舶订阅并清空待应用变更。轨迹、冲突详情和审计继续按单船接口读取历史事实。
|
||||
|
||||
### 图层接口与全量统计分离
|
||||
|
||||
|
||||
@@ -70,7 +70,10 @@ DB 变化不再默认创建 `earth_refresh` 任务，因此不会被同 source
|
||||
| --- | --- |
|
||||
| `clear_then_reload` | 先清前端本地图层对象，再强制重拉接口。删除数据时优先使用。 |
|
||||
| `reload` | 保留旧对象直到新数据返回，适合定位、元数据或非破坏性更新。 |
|
||||
| `delta` | 只用于 `earth_interactables`，按 id upsert 或 remove。 |
|
||||
| `delta` | `earth_interactables` 按 id upsert/remove；船舶普通写入由专用 `vessels` 通道按 MMSI 更新确认状态，不触发整层清空。 |
|
||||
|
||||
船舶删除仍发出 `reload` 校准提示，`vessel_current_state` 的逐项删除同时进入船舶 remove 通道。源通知只决定哪些 MMSI 需要更新，推送值以当前状态表为准。全局订阅使用 `scope: "global"`；消息大小上限用于拆包，不用于丢弃其余船只。
|
||||
|
||||
|
||||
接口在真实 0 数据时必须返回 200 和空集合；只有真实接口异常才返回 5xx。前端收到删除事件后，如果重拉失败，应保持已清空状态并显示轻量错误，不恢复旧对象。
|
||||
|
||||
|
||||
@@ -323,7 +323,7 @@ AISStream 使用 WebSocket 实时流，采集器只写入 `ais_raw_observations`
|
||||
GET /api/v1/vessels/snapshot?bbox=-180,-85.05112878,180,85.05112878&zoom=12&limit=3000
|
||||
```
|
||||
|
||||
该接口查询 `vessel_current_state` 当前状态表，只返回有效窗口内每个 MMSI 的最新点；原始 `ais_raw_observations` 继续保留给轨迹、审计和态势分析，但不再由展示接口临时扫描聚合。Earth 前端统一传全球 bbox，不随当前镜头视口反复请求。实时更新如接入 `/ws` 的 `vessels` channel，应作为 reload/dirty 提示触发合并刷新，不能把每条 AIS delta 直接变成整层重建。
|
||||
该接口查询 `vessel_current_state` 当前状态表，只返回有效窗口内每个 MMSI 的最新点；原始 `ais_raw_observations` 继续保留给轨迹、审计和态势分析，但不再由展示接口临时扫描聚合。Earth 前端统一传全球 bbox，不随当前镜头视口反复请求。实时更新使用 `/ws` 的 `vessels` 全局订阅，按 MMSI 推送确认状态并原位更新；超出单帧上限时拆包，保留所有更新。首次加载、重连和删除校准仍使用快照，详见[采集器架构](backend-collectors.md)。
|
||||
|
||||
## 自定义 REST / WebSocket 映射运行时
|
||||
|
||||
|
||||
@@ -56,7 +56,7 @@ React 路由入口：
|
||||
- 各图层集成
|
||||
- Earth 级别状态同步
|
||||
|
||||
Earth 收到 `/ws` 的 `earth_updates` 时只把它当作刷新提示，真实数据仍通过 `/api/v1/visualization/...` 接口重新 GET。数据库驱动的刷新由后端 listener 直接清理缓存再广播，不再默认经过 `earth_refresh` 作业队列；前端收到 `database_changed` 后会按 layer 读取 `clear_then_reload`、`reload` 或 `delta` 策略。`clear_then_reload` 必须先清 Three.js 对象再 no-store 重拉，summary 只做一致性校验，不能用 `0` 作为跳过图层重拉的理由。技术链路见 [数据作业与 Outbox 技术架构](/home/ray/dev/linkong/planet/docs/technical/zh/data-job-earth-sync-architecture.md)，业务数据流见 [业务架构与数据流转](/home/ray/dev/linkong/planet/docs/technical/zh/platform-data-flows.md)。
|
||||
Earth 收到 `/ws` 的 `earth_updates` 时只把它当作刷新提示，普通图层仍通过 `/api/v1/visualization/...` 接口重新 GET；船舶使用下文的 `vessels` 专用确认状态增量通道。数据库驱动的刷新由后端 listener 直接清理缓存再广播，不再默认经过 `earth_refresh` 作业队列；前端收到 `database_changed` 后会按 layer 读取 `clear_then_reload`、`reload` 或 `delta` 策略。`clear_then_reload` 必须先清 Three.js 对象再 no-store 重拉，summary 只做一致性校验，不能用 `0` 作为跳过图层重拉的理由。技术链路见 [数据作业与 Outbox 技术架构](/home/ray/dev/linkong/planet/docs/technical/zh/data-job-earth-sync-architecture.md)，业务数据流见 [业务架构与数据流转](/home/ray/dev/linkong/planet/docs/technical/zh/platform-data-flows.md)。
|
||||
|
||||
### 3. 地球控制层
|
||||
|
||||
@@ -170,6 +170,8 @@ Browser Camera provider 的手势识别管线在 [motion-browser-provider.js](/h
|
||||
|
||||
`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`，不会覆盖用户偏好。
|
||||
|
||||
`tv-source-menu.js` 复用 HUD 面板与图例列表样式，使用 popover 显示搜索、滚动列表和固定计数栏。`tv.js` 按 50 条请求 `/api/v1/tv/streams`，维护当前频道缓存；搜索交给后端完整目录，翻页用 `next_offset`。菜单通过取消请求和请求代数屏蔽过期响应，不能让旧搜索覆盖新输入。刷新目录时通过 `selected_id` 恢复不在第一页的频道。
|
||||
|
||||
`brand.js` 管理智能星球 HUD 品牌资源。默认品牌来自静态资源，运行时覆盖值来自 `/api/v1/earth/brand`，上传的图片通过 `/earth-brand-assets/...` 读取。前端必须把 logo/title 图片和文本 fallback 分开处理：图片加载失败时显示文本标题，文本字段为空时使用后端默认值，避免 HUD 品牌区空白。控制台的智能星球内容页负责保存和重置品牌配置，智能星球前端只消费结果。
|
||||
|
||||
`about.js` 管理智能星球设置里的“关于”卡片。默认内容仍保留在前端作为兜底，运行时优先读取 `/api/v1/earth/about`。接口失败或字段缺失时必须回退默认值，避免设置页出现空白。控制台的智能星球内容页提供“关于”tab，保存走 `PUT /api/v1/earth/about`，恢复默认走 `DELETE /api/v1/earth/about`。
|
||||
@@ -209,6 +211,14 @@ TV 预览需要尽量复用 Earth 运行时的直播卡片结构和状态标签
|
||||
|
||||
新闻巡航摘要的未来计划保存在仓库路径 `docs/plans/earth-news-cruise-summary-plan.md`，不作为公开 Docs 页面入口。
|
||||
|
||||
## 渲染热路径
|
||||
|
||||
`cable-batches.js` 将全部海缆线段与全部登陆点分别合批绘制；`cables.js` 继续拥有原始业务对象、拾取、遮挡和选择状态。避免在后续功能中把这些代理对象重新加入逐对象绘制，或把绘制批次当作业务对象返回给详情卡。
|
||||
|
||||
卫星的逐点呼吸在 GPU 中计算。全量 SGP4 位置和初始轨迹计算通过 `satellite-position-worker.js` 离开主线程；主线程只接收位置快照、更新共享交互坐标及绘制缓冲。轨道数学由 `satellite-propagation.js` 同时供 Worker、预测轨道和同步降级路径使用，避免多套公式漂移。数据重载、清空和高度切换必须同步终止旧计算，不能让旧快照恢复已清空的图层。
|
||||
|
||||
`i18n.js` 的 MutationObserver 只翻译新增子树、变动文本或变动属性。局部时钟、状态和下载进度更新不能触发整页语言控件同步；全局语言同步只属于初始化、语言切换或包含新语言控件的子树。
|
||||
|
||||
## 当前样式分层
|
||||
|
||||
Earth 的 CSS 不是一份大样式表，而是分层管理：
|
||||
@@ -344,7 +354,13 @@ AIS 船只图层入口：
|
||||
|
||||
AISStream 的 `PositionReport` 常带实时位置和 `MetaData.ShipName`，但船型通常来自低频 `ShipStaticData.Type`。后端会把 `MetaData.ShipName` 补进船名，并将类型码映射为 Cargo / Tanker / Passenger / Fishing / Military；仍缺失的船型需要等待静态 AIS 消息或后续船舶资料 enrichment，不能在前端凭颜色之外的信息臆造细分类。
|
||||
|
||||
旧 `/api/v1/visualization/geo/vessels` 路由已移除。前端打开船只图层时只应拉取一次全局 `/api/v1/vessels/snapshot`；API 参数里的 bbox 是后端接口约束，Earth 运行时传全球范围，不表示当前镜头视口。`/ws` 的 `vessels` channel 如启用，只作为低频 reload/dirty 提示，不能把每条 AIS delta 直接变成整层重建。后端通过 `diagnostics.source == "vessel_current_state"` 暴露当前状态链路。
|
||||
旧 `/api/v1/visualization/geo/vessels` 路由已移除；初始数据仍通过全球 bbox 的 `/api/v1/vessels/snapshot` 读取。
|
||||
|
||||
AISStream 与 BarentsWatch 共用 `/ws` 的 `vessels` 增量通道。Earth 使用现有 WebSocket 连接订阅 `scope: "global"`，不跟随镜头改变订阅范围。后端按 MMSI 合并一秒内的通知，再读取 `vessel_current_state` 的已确认状态；单帧最多 1000 项，超过时继续发送后续帧，不截断不同船只。原始源消息不能直接覆盖客户端的确认位置。当前状态删除也会产生按 MMSI 的 remove 通知。
|
||||
|
||||
前端将短时间内同一 MMSI 的变更合并为最新值，通过 `Interactable.updateItems()` 原位修改位置和颜色缓冲。航向分桶变更只更新受影响的桶，容量不足才扩容；保留已有 marker 身份、锁定状态和材质。首次进入、重连、删除提示及每分钟巡检仍用 snapshot 校准，但不先清空整个图层。收到有数量上限的快照时，不能把被截断的船只当成删除；快照返回期间到达的较新更新和删除也不能被旧响应覆盖。快照携带查询开始时的 `generated_at`，与实时帧时间一起用于识别缓存旧快照，避免新船或删除状态被回滚。
|
||||
|
||||
`earth_updates` 中船舶普通写入的策略是 `delta`；专用通道连通时不再触发整层重拉。删除或断连后的校准使用 `reload`，并复用现有对象。关闭图层会取消船舶订阅并清空待应用变更。轨迹、冲突详情和审计继续按单船接口读取历史事实。
|
||||
|
||||
新的图层接口族是 `/api/v1/layers/*`，用于把地图渲染数据和聚合面板统计分开。地图层请求必须带 `bbox`、`zoom` 和受控 `limit`，响应会返回 `visible_count`、`returned_count` 和 `diagnostics`，其中 `degraded/truncated/limit_clamped` 用于前端提示降级。右侧聚合统计不要从图层响应累加，应读取 `/api/v1/data-products` 或 `/api/v1/data-products/{product_id}/status`，因为这些统计保持全量/全局口径，不随当前视口变化。
|
||||
|
||||
@@ -380,6 +396,8 @@ AISStream 的 `PositionReport` 常带实时位置和 `MetaData.ShipName`，但
|
||||
|
||||
详情卡里的坐标候选状态由 [info-card.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/info-card.js) 按 `entityType:entityId` 缓存在模块内存中。用户关闭详情卡或待定位列表后再次打开同一个算力中心 / BGP 观测站，已经采集到的候选和状态文案会恢复；`一键采用` 会优先使用缓存候选，避免重复调用在线地理编码或 LLM factcheck。保存成功后该实体的候选列表会清空为“正在刷新图层”状态，避免旧候选在刷新后继续误导用户。
|
||||
|
||||
批量定位由 `runUnresolvedComputeCenterBatch()` 持有实体上下文队列，不持有面板 DOM；`locationCollectStateCache` 保存候选、进度和保存结果，重建卡片时重新 hydrate。`earth:compute-center-location-batch-change` 同步任务状态与气泡入口，成功条目根据 `savedCandidate` 排除，全部完成后保留 ✓ 入口。状态只存在当前 Earth 页面内存中，刷新、关闭或路由离开会终止未完成队列；已保存坐标仍以后端为准。
|
||||
|
||||
候选行的 `预览 / 保存` 按钮采用单一的事件委托模型：每个候选根（详情卡里的 `[data-collect-cache-key]` 块，或待定位列表里的 `[data-unresolved-item]`）只挂一个 `click` 监听，由 `data-candidate-actions-bound` 幂等标记，不再混用 `pointerup` / `click` 直绑或重复委托。候选对象不再以 JSON 字符串塞进 HTML 属性后再 `JSON.parse`，按钮只携带 `data-candidate-index`，handler 通过 cache-key 在模块内存的 `Map` 里取出原对象，避开 HTML 实体转义对 `&` / `<` / `"` 的破坏。点击 `预览` 会派发 `earth:preview-location-candidate`，由 `main.js` 的 `previewLocationCandidate()` 调用 `showComputeCenterLocationPreview()`：在候选经纬度上挂双层空心呼吸 sprite（视觉参考 BGP 事件 ring），并把视角聚焦到候选坐标；切换到另一个候选会替换为新呼吸圈，保存时立即清除并由 `spawnSavedComputeCenterLocation()` 即时生成正式算力中心交互图标。注意 `main.js` 没有模块级 `earth` 变量，所有 location-save / preview 处理函数必须先 `const earth = getEarth();`，否则会在事件 handler 里抛 `ReferenceError` 被 `.catch` 静默掉，外观上等同于按钮“没有反应”。
|
||||
|
||||
`earth:compute-center-location-saved` 之后的图层校准链路对后台刷新失败保持沉默：`spawnComputeCenterAfterLocationSave()` 已经把 toast 和 locked 状态都给了用户，`refreshComputeCentersAfterLocationSave()` 只在场景就绪时重新拉取后端数据，本身不再吐 `已保存` toast；`handleComputeCenterLocationSaved()` 在 spawn 成功路径让 refresh 静默后台运行，只在 spawn 返回 `null`（场景未就绪）或抛错时才让 refresh 接管成功 toast，refresh 自身报错只走 `console.warn`，绝不冒泡成 `保存失败` 文案——保存请求本身已经成功，刷新失败属于后续同步问题。
|
||||
@@ -392,7 +410,7 @@ asset 图标大小由 `Interactable` 的 `icon.fitSize` 控制。SVG / 图片文
|
||||
|
||||
跨 Interactable 的同坐标关系也在公共层记录，但真实位置必须始终以 `icon_base_position` 为准。缩放、避让、聚合和后续 spiderfy 展开都只能改变屏幕表现，不能写回 `marker.position` 或 `THREE.Points` 里的业务锚点；巡航定位、详情卡、搜索定位和 picking 返回对象都必须落回真实经纬度。多个图标归入同一个经纬度 key 时，公共层只写 `icon_avoidance_*` 元数据，供业务层弱化 halo 或显示聚合提示；真正的低缩放聚合应通过独立 cluster glyph / screen layout 层实现，而不是把对象沿地表切平面挪开。
|
||||
|
||||
`Interactable` 的单点显示只由全局地图缩放决定：170% 及以下强制显示小圆点，超过 170% 显示原图标。cluster 现在由 `cluster.strategy` 决定：`stable-spherical` 使用离散 zoom band 和 3D 球面分桶，BGP、算力中心和 Earth interactable 在同一 band 内旋转或细微缩放时不会重新计算聚合拓扑；`dynamic-screen` 保留屏幕空间聚类，适合船只这类实时高频图层；`none` 关闭聚类。稳定球面聚类的 cluster 圆点刚性落在成员 3D 质心投影上，不参与 2D 避让，避免缩放时被推离真实地理位置。cluster 圆点大小随包含对象数量增长，数量过多时按稳定地理顺序拆成多个较小圆点；数量默认只在 hover tooltip 中显示。这个过程只设置 `icon_cluster_*` 展示元数据和重建渲染 Points，不改变每个 marker 的真实经纬度。
|
||||
`Interactable` 的单点显示只由全局地图缩放决定：170% 及以下强制显示小圆点，超过 170% 显示原图标。cluster 现在由 `cluster.strategy` 决定：`stable-spherical` 使用离散 zoom band 和 3D 球面分桶，BGP、算力中心和 Earth interactable 在同一 band 内旋转或细微缩放时不会重新计算聚合拓扑；`dynamic-screen` 保留屏幕空间聚类；`none` 关闭聚类。船只显式关闭聚类与避让，保证增量更新时不重建聚类拓扑。稳定球面聚类的 cluster 圆点刚性落在成员 3D 质心投影上，不参与 2D 避让，避免缩放时被推离真实地理位置。cluster 圆点大小随包含对象数量增长，数量过多时按稳定地理顺序拆成多个较小圆点；数量默认只在 hover tooltip 中显示。这个过程只设置 `icon_cluster_*` 展示元数据和重建渲染 Points，不改变每个 marker 的真实经纬度。
|
||||
|
||||
接口细节、生命周期和接入示例见：
|
||||
|
||||
|
||||
@@ -149,6 +149,8 @@
|
||||
|
||||
## 海缆与登陆点
|
||||
|
||||
`cable-batches.js` 将海缆线与登陆点分别合批绘制。下表的 Sprite 材质和尺寸仍属于 `cables.js` 中的拾取、选择代理；每帧把颜色、透明度、缩放和可见性同步到样式纹理或实例属性。实际绘制使用 `LineSegments` 和实例化 billboard，沿用原纹理、色彩、层级与球体遮挡规则。
|
||||
|
||||
| 正式名称 | 变量名 | 当前值 | 使用位置 / 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| 默认海缆颜色 | `CABLE_COLORS.default` | `0xffff44` | 无数据颜色时使用 |
|
||||
|
||||
@@ -21,7 +21,7 @@
|
||||
| 0.86 | 海陆基座填充 | `country-boundaries.js` | `landAltitudeOffset = 0.32`; 海洋 `#010609`，陆地 `#080f1b` | 禁用 raycast | 即使国界线关闭，基座地图仍保持可用；半径与基座球拉开以避免远距 z-fighting。 |
|
||||
| 0.96 | 高清 Earth 材质 | `earth.js` | `textureOverlayAltitudeOffset = EARTH_SURFACE_TEXTURE_ALTITUDE_OFFSET = 0.48` | 可见时作为地表拾取目标 | 高清材质始终压过海陆基座填充；半径必须高于海陆基座并与基座球保持足够间距。 |
|
||||
| 1 | 大气辉光和云图 | `earth.js` | 大气 / 云层球 | 不走普通对象选择路径 | 云图由“大气云图”图层开关控制。 |
|
||||
| 1 | 海缆 / 登陆点 | `cables.js` | 海缆线和登陆点都使用 `renderOrder = 1`；半径偏移都为 `0.2`；登陆点是专用 `THREE.Sprite` 黄色扁平球 | 海缆走海缆拾取路径；登陆点 `depthTest: false` 保持球体完整，并用相机到球心的球体遮挡判断避免背面穿透 | 登陆点和海缆同层贴地，避免地表设施层的凌空感。 |
|
||||
| 1 | 海缆 / 登陆点 | `cables.js`, `cable-batches.js` | 海缆全量线段合并为一个 `LineSegments`；登陆点全量使用实例化 billboard；`renderOrder = 1`、半径偏移 `0.2` 保持不变 | 原始 `Line` / `Sprite` 仅作为逐项拾取和选择状态对象，材质不再单独绘制；登陆点仍按球体遮挡判断背面可见性，批量材质 `depthTest: false` | 样式通过线缆样式纹理和登陆点实例属性同步；保留颜色、脉冲、尺寸、显隐与点击语义。 |
|
||||
| 1.2 | 真实地形 | `earth.js`, `terrain.js` | `TERRAIN_CONFIG.baseRadiusOffset` 加地形位移 | 禁用 raycast | 地形压过高清材质；高清材质关闭时临时隐藏，重新开启后恢复原状态。 |
|
||||
| 2.05 | 经纬线 | `earth.js` | `CONFIG.earthRadius + 0.14` | 禁用 raycast | 低透明度显示在高清材质上。 |
|
||||
| 2.2 | 国界线 | `country-boundaries.js` | `lineAltitudeOffset = EARTH_SURFACE_TEXTURE_ALTITUDE_OFFSET = 0.48`；claim 线不再额外抬高 | `depthTest: true`，禁用 raycast | 线层使用独立 line geometry 与 `renderOrder` 控制，但半径与高清材质壳完全一致，避免转动地球时与高清贴图出现视差。 |
|
||||
@@ -37,6 +37,14 @@
|
||||
| 12+ | 卫星锁定 ring、halo、预测轨道 | `satellites.js` | `SATELLITE_CONFIG.overlayRenderOrder` 及偏移；预测轨道使用同一真实高度开关，并固定锁定时刻的地球姿态来绘制闭合惯性轨道；关闭真实高度时回到同层球面 | 卫星覆盖层路径 | 用于选中 / 锁定卫星强调。 |
|
||||
| 98-100 | 太阳 / 月亮 halo 和 sprite | `celestial.js` | 固定 renderOrder | 天体拾取禁用 | 前景天体 sprite。 |
|
||||
|
||||
## 全量绘制与更新约束
|
||||
|
||||
- 合批只改变 GPU 提交方式，不减少卫星、线段或登陆点数量，也不按相机半球裁剪数据。海缆每对相邻顶点都保留，拾取仍返回原始业务对象。
|
||||
- 卫星普通点与背景点保持两个 `Points` 绘制；呼吸动画由顶点着色器使用静态逐点参数和每帧统一时间计算。hover / locked 的隐藏标记仍由原有选择状态控制。
|
||||
- `satellite-position-worker.js` 使用与主线程相同的 Three.js / SGP4 版本，通过 `satellite-propagation.js` 共享轨道、显示高度和 fallback 计算；全量位置及初始轨迹以可转移数组交给主线程。主线程维持一个在途计算，不堆积过期帧；重载、清空和高度模式变更会终止旧 Worker。
|
||||
- Worker 启动失败或超过 `SATELLITE_CONFIG.workerStartupTimeoutMs` 时退回共享的同步计算，避免图层无限等待。计数、数据接口、原有更新周期和轨迹长度不变。
|
||||
- 验证时同时检查全量 draw range、逐项拾取、锁定覆盖层、轨迹、背面遮挡、开关及清空后的资源释放；比较帧耗时必须使用相同数据、相同视角和分辨率。
|
||||
|
||||
## 开关联动
|
||||
|
||||
| 开关 | 行为 |
|
||||
|
||||
@@ -126,6 +126,9 @@
|
||||
|
||||
### AISStream 实时船舶
|
||||
|
||||
在智能星球打开船只图层后，AISStream 与 BarentsWatch 的后续位置会自动更新。更新时会保留已选中的船只；短暂断线重连后会自动校准，无需反复关闭、开启图层。
|
||||
|
||||
|
||||
`AISStream 实时船舶` 是全球 AIS WebSocket 采集器。连接测试通过只说明 API Key 和 endpoint 格式可用；真正的全球船只数据来自后台 `aisstream_vessels` collector 长连接运行并写入 `ais_raw_observations`。
|
||||
|
||||
操作步骤：
|
||||
@@ -165,6 +168,8 @@ provider 和模型既可选预设也可直接输入自定义 id/name。常用字
|
||||
|
||||
Base URL 输入框尾端的插头图标会触发连接测试。测试通过会显示当前模型返回的简短回复。
|
||||
|
||||
点击右上角的刷新图标可更新“可选模型”。成功后目录会保存，重新打开页面仍可使用；有发布日期的目录按新到旧排列。刷新保留当前模型、密钥、地址和未保存的修改。点击一个可选模型后，再点“保存”才会改变实际使用的模型。刷新失败时会显示错误并保留上次目录。
|
||||
|
||||
### 工具
|
||||
|
||||
- **WebSearch**：provider、API Key、Base URL、最大结果数、超时、高级 provider 参数。未启用时除"启用"开关外其它配置项和连接测试都会置灰
|
||||
@@ -281,6 +286,10 @@ AIS 船只图例按船型显示颜色：货轮、油轮、客船、渔船、军
|
||||
|
||||
支持查找海缆、登陆点、卫星、算力中心、BGP 事件、BGP 观测站。结果可快速定位并打开详情。
|
||||
|
||||
### 新闻直播源选择
|
||||
|
||||
打开媒体面板的直播页，点击当前频道可展开搜索菜单。搜索会检索完整频道库；列表每次加载 50 个频道，滚动到底部自动追加。底部固定显示已加载数量和搜索结果总数，加载失败时可在列表下方重试。默认新闻直播源为 Al Jazeera Mubasher（半岛电视台），使用 HLS 播放地址；其他频道仍取决于各自的播放服务是否可用。
|
||||
|
||||
### 位置候选采集
|
||||
|
||||
算力中心和 BGP 观测站详情卡支持自动采集坐标候选。点击对象后用"自动采集坐标候选"或"重新自动采集坐标"按钮，后端会从源坐标、开放组织注册 API 和在线地理编码中整理候选；常规来源没有候选时使用当前默认 AI Provider 做 LLM factcheck 兜底。BGP 观测站的已存储位置只用于补齐查询上下文，不会作为候选直接返回。
|
||||
@@ -297,6 +306,8 @@ AIS 船只图例按船型显示颜色：货轮、油轮、客船、渔船、军
|
||||
|
||||
一键定位用于批量处理算力中心待定位队列。它会从列表顶部开始采用最高置信候选；仍没有事实依据的记录会保留在队列中。未开启 WebSearch 时，单个定位和一键定位会置灰，因为位置核验依赖事实查询。
|
||||
|
||||
在当前智能星球页面内，关闭候选面板、查看其他对象或切换浏览器标签页不会取消队列；返回候选列表后可继续查看进度和结果。已保存条目不会再次采集，全部完成后仍可通过图层旁的 ✓ 入口查看结果。刷新、关闭页面或跳转离开智能星球会中断尚未完成的队列，已经保存的坐标会保留。
|
||||
|
||||
### 设置
|
||||
|
||||
设置面板按分类组织：运行、显示、面板、动捕、快捷键、系统。里面包含旋转模式 / 巡航模式 / 动捕模式、巡航模块（BGP/新闻/算力中心/船只/海缆/卫星）、视图设置（卫星显示风格、悬停提示、卫星呼吸闪烁、真实卫星高度、轨迹显示、低缩放圆点、日夜模式、面板显示开关）、动捕调试模式 / 输入源 / 只显示骨骼 / 识别动作白名单、快捷键启用与改键、地球默认大小、地形透明度、重置设置。
|
||||
|
||||
@@ -2,6 +2,10 @@
|
||||
|
||||
## 背景
|
||||
|
||||
日常启动使用 `zsh ./planet.sh start --non-motion-agent`；新环境首次准备才需要 `init`。排查耗时时，应区分首次依赖下载、容器就绪和应用初始化，结合阶段日志时间判断。
|
||||
|
||||
当前启动流程在准备 AI Provider 镜像前验证后端实际数据库连接，端口映射缺失时保留数据卷重建一次。后端进程退出，或 Uvicorn 日志出现应用初始化失败、ASGI 加载失败、导入或语法错误时，会立即停止等待和重复启动；正常的慢启动仍保留原有等待预算。AI Provider 直接探测宿主机 `/health`，无需再等待 Docker 周期性健康检查首次运行。
|
||||
|
||||
`planet.sh` 管理所有服务的启动/停止/重启。原有实现存在以下问题：
|
||||
|
||||
1. AI Provider 每次都重新构建（即使代码未变）
|
||||
@@ -37,27 +41,9 @@ write_ai_provider_build_stamp() {
|
||||
}
|
||||
```
|
||||
|
||||
### fingerprint 计算提速
|
||||
### fingerprint 检查范围
|
||||
|
||||
原实现对整个 `aiprovider/` 打 tar 包再算 SHA，大目录下耗时可达数秒。改为 `find + stat`（只读文件元信息，不读内容）：
|
||||
|
||||
```bash
|
||||
compute_ai_provider_build_fingerprint() {
|
||||
find aiprovider \
|
||||
-type f \
|
||||
! -path '*/__pycache__/*' \
|
||||
! -name '.env' \
|
||||
! -name '.env.*' \
|
||||
! -name '*.pyc' \
|
||||
! -name '*.pyo' \
|
||||
| LC_ALL=C sort \
|
||||
| xargs -r stat --format="%Y %s %n" 2>/dev/null
|
||||
sha256sum docker-compose.yml docker-compose.simple.yml 2>/dev/null
|
||||
python3 "$SCRIPT_DIR/scripts/compute_aiprovider_dependency_fingerprint.py" 2>/dev/null
|
||||
}
|
||||
```
|
||||
|
||||
速度提升约 10 倍（大量小文件场景），误报率相同（mtime+size 变化 ≡ 文件被修改）。
|
||||
当前指纹使用内容 SHA，覆盖 `aiprovider/`、Dockerfile、根依赖清单与锁文件，以及代理服务相关依赖信息；不会遍历前端资源或下载数据。`.env` 配置不参与镜像内容指纹。构建标记只用于判断是否需要构建，Dockerfile 中的指纹标签位于依赖安装之后，以保留前置依赖层缓存。
|
||||
|
||||
`.env` 和 `.env.*` 被排除在 fingerprint 外。它们属于运行期配置，不应该因为修改模型、密钥或 Base URL 触发镜像重建。
|
||||
|
||||
@@ -85,13 +71,15 @@ Dockerfile 也从全仓复制改为只复制 AI Provider 代码：
|
||||
```dockerfile
|
||||
COPY pyproject.toml uv.lock /app/
|
||||
RUN --mount=type=cache,target=/root/.cache/uv \
|
||||
uv sync --frozen --no-dev
|
||||
uv sync --frozen --only-group aiprovider
|
||||
|
||||
COPY aiprovider /app/aiprovider
|
||||
```
|
||||
|
||||
`uv sync` 使用 BuildKit cache mount 后，首次构建仍可能受网络影响；后续构建会复用 `/root/.cache/uv`，依赖下载不再重复从零开始。
|
||||
|
||||
`aiprovider` 依赖组在根 `pyproject.toml` 定义，并由同一份 `uv.lock` 锁定，只安装 FastAPI、HTTP 客户端、配置读取和 ASGI 服务所需依赖。镜像不安装后端采集或 OpenCV / MediaPipe 动捕依赖。构建指纹标签放在依赖安装和代码复制之后，指纹改变不会单独使依赖层缓存失效。容器直接启动已安装的 `.venv/bin/python`，运行时不再执行 `uv sync`。修改代理服务的依赖时，应同步更新该依赖组和锁文件，并验证镜像导入及 `/health`。
|
||||
|
||||
### 运行期配置来源
|
||||
|
||||
`planet.sh` 启动 AI Provider 前会生成受当前用户保护的运行期 env-file，并把它传给 Compose 或手动 `docker run` fallback。默认路径位于 `${XDG_STATE_HOME:-$HOME/.local/state}/planet/aiprovider_runtime.env`。配置优先来自：
|
||||
@@ -119,7 +107,7 @@ fingerprint 一致时不执行 `docker compose build`，而是：
|
||||
docker start planet_aiprovider # 启动已存在的容器，几秒内完成
|
||||
```
|
||||
|
||||
`docker stop` 停容器，不删镜像；`cleanup_exit_containers` 删已退出容器，不删镜像。下次 `docker start` 会从现有镜像直接创建并启动容器。
|
||||
`docker stop` 停容器，不删镜像。`start` 和 `restart` 保留已停止的容器，不再扫描删除全机已退出容器；未变化的 AI Provider 可直接复用，数据库仍由 Compose 同步配置。只有需要更新镜像或容器配置时才按原有流程重建。
|
||||
|
||||
## 问题二：杀端口速度慢
|
||||
|
||||
|
||||
@@ -33,9 +33,9 @@ docker buildx version
|
||||
|
||||
## 数据库初始化与连接检查
|
||||
|
||||
`init` 会先通过 Compose 同步 PostgreSQL / Redis 容器配置，包括已有容器的端口映射；仅执行 `docker start` 无法应用配置变化。Compose 同步失败时会保留具体错误，例如端口被占用，不会继续复用旧容器并报告成功。
|
||||
`init` 和 `start` 会先通过 Compose 同步 PostgreSQL / Redis 容器配置，包括已有容器的端口映射；仅执行 `docker start` 无法应用配置变化。Compose 同步失败时会保留具体错误，例如端口被占用，不会继续复用旧容器并报告成功。
|
||||
|
||||
容器内部的 `pg_isready` 只检查服务是否接受连接，不能证明宿主机上的后端使用正确地址和密码。容器健康后，`init` 通过 `scripts/check_database_connection.py` 读取与后端相同的有效 `DATABASE_URL`，检查本地 PostgreSQL 的实际发布端口并执行只读 `SELECT 1`；通过后才显示“数据库服务已就绪”并创建表和默认数据。
|
||||
容器内部的 `pg_isready` 只检查服务是否接受连接，不能证明宿主机上的后端使用正确地址和密码。容器健康后，`init` 和后端启动流程通过 `scripts/check_database_connection.py` 读取与后端相同的有效 `DATABASE_URL`，检查本地 PostgreSQL 的实际发布端口并执行只读 `SELECT 1`。启动流程在准备 AI Provider 镜像之前完成此检查；失败会立即停止。`init` 通过检查后才创建表和默认数据。
|
||||
|
||||
- 如果本地实际端口映射仍缺失或不匹配，脚本会保留数据卷，按 Compose 配置重建一次 PostgreSQL 并重新检查；再次失败就停止。
|
||||
- 认证、库名或网络错误会在建表前停止，诊断只显示目标主机、端口和库名，不输出密码、完整连接串或驱动异常原文。
|
||||
|
||||
@@ -33,7 +33,7 @@
|
||||
进入 `/admin` 仪表盘后，建议按这个顺序熟悉控制台：
|
||||
|
||||
1. `/collection-management?section=collector_credentials`：选一个采集器，点插头图标做连接测试。免费 collector（开源 BGP 等）通常直接可用；像 `AISStream`、`BarentsWatch` 这类需要凭证的，需要先填 API Key/Client Secret
|
||||
2. `/ai?section=integrations`：填一个 LLM provider（例如 `minimax` / `openai`）、模型名、Base URL、API Key，点 Base URL 末端的插头测试连接。WebSearch / OCR 工具可选
|
||||
2. `/ai?section=integrations`：填一个 LLM provider（例如 `minimax` / `openai`）、模型名、Base URL、API Key，点 Base URL 末端的插头测试连接。右上角刷新图标会更新并保存可选模型目录，同时保留当前表单；选中新模型后点“保存”生效。WebSearch / OCR 工具可选
|
||||
3. `/earth-content?section=brand`：在“品牌标识”里维护智能星球的 Logo 和标题图；对应地址字段内的“上传”按钮支持选择文件，也支持把图片直接拖到字段上，保存后会应用到智能星球 HUD
|
||||
4. `/datasources` 或 `/data`：看采集器是否已经产出数据。有限采集器看 `/datasources -> 内置源`，不勾选时点“触发全部”，勾选后主按钮会变成“触发已选 N”；右上角队列按钮可查看进度。AISStream / WebSocket 长连接看 `/datasources -> 实时源` 的健康状态和计数
|
||||
5. `/alerts/system`：看系统告警是否正常
|
||||
@@ -50,6 +50,9 @@
|
||||
- 地球正常显示，右侧图层面板可以打开/关闭
|
||||
- 搜索可以查找海缆、卫星、算力中心、BGP 事件
|
||||
- 算力中心和 BGP 观测站详情卡可以自动采集坐标候选，并能在智能星球上预览
|
||||
- 一键定位期间关闭候选面板或切换浏览器标签页，再返回可查看进度；刷新或离开智能星球页面会中断未完成队列
|
||||
- 船只图层持续接收 AISStream / BarentsWatch 位置，断线重连后自动校准
|
||||
- 直播菜单可搜索完整频道库，滚到底部继续加载；默认频道为半岛电视台
|
||||
- 鼠标拖动、滚轮缩放、缩放百分比提示工作正常
|
||||
- 设置面板的旋转 / 巡航 / 动捕模式可以切换；动捕设置可以选择输入源和允许识别的动作；视图设置里可以切换悬停提示，卫星相关设置里可以打开或关闭真实高度分层和轨迹显示
|
||||
|
||||
|
||||
Reference in New Issue
Block a user