release: bump version to 0.44.0

2026-04-29 17:27:44 +08:00
parent 2da25376bd
commit 87594a95ff
54 changed files with 3665 additions and 2154 deletions
--- a/docs/technical/en/earth-news-live-streams-collector-format.md
+++ b/docs/technical/en/earth-news-live-streams-collector-format.md
@@ -103,7 +103,7 @@ Goals:

 ## Collector Configuration

-`news_live_streams` does not need a separate new page; it reuses the existing data source configuration:
+`news_live_streams` does not need a separate new page; it reuses Collector Settings under `/settings`:

 - `endpoint`
  - Channel directory JSON API URL
--- a/docs/technical/en/manual.md
+++ b/docs/technical/en/manual.md
@@ -178,6 +178,7 @@ Earth is used to observe in a single globe view:
 - Satellites and orbital trails
 - Submarine cables and landing points
 - Compute centers
+- AIS vessels
 - Country borders, grid lines, HD texture, cloud layer, terrain
 - Live news streams and situational news
 - Search and focused object details
@@ -195,6 +196,7 @@ Common layers include:
 - Submarine cables
 - Compute centers
 - BGP observation
+- AIS vessels
 - Satellites
 - Orbital trails
 - Terrain
@@ -205,6 +207,21 @@ Some layers have dependencies:
 - Trails require Satellites
 - When HD texture is off, the globe shows the base map and edge glow effect

+### Legend
+
+The lower-left legend follows the currently focused or enabled layer.
+
+Current legend modes include:
+
+- Cables
+- Satellites
+- Country borders
+- Compute centers
+- BGP
+- AIS vessels
+
+AIS vessel legend entries are grouped by vessel type: cargo, tanker, passenger, fishing, military, anchored/slow, and other. Triangle markers represent moving vessels; dots represent anchored or slow vessels.
+
 ### Search

 Earth search finds current globe objects, such as:
@@ -233,6 +250,25 @@ The settings panel contains:

 These settings are stored in browser local storage. They revert to defaults if you switch browsers or clear site data.

+### View Controls
+
+Earth supports mouse, touchpad, and touchscreen interaction.
+
+Common controls:
+
+| Action | Result |
+| --- | --- |
+| Left-button drag | Rotates the globe |
+| One-finger drag | Rotates the globe on touch devices |
+| Mouse wheel | Zooms the view in or out |
+| Two-finger pinch | Zooms the view on touch devices |
+| Zoom buttons | Adjust zoom in fixed steps |
+| Click the zoom percent | Resets to the default zoom |
+
+When zooming, the top capsule briefly shows the current zoom level, for example `Zoom 180%`. This indicates view zoom only, not data loading progress. Loading status takes priority and will not be interrupted by zoom feedback.
+
+Drag sensitivity adjusts automatically based on the current zoom. Around the default view it keeps the normal rotation feel; when zoomed in, dragging becomes progressively finer for inspecting a region, vessel, satellite, or BGP event; when zoomed out, dragging is slightly faster for global browsing.
+
 ### Cruise Mode

 Cruise mode makes Earth automatically cycle through focus targets.
@@ -308,7 +344,7 @@ Common pages:
 | --- | --- | --- |
 | Dashboard | `/admin` | System overview |
 | Earth | `/earth` | Opens the public Earth page |
-| Data Sources | `/datasources` | Manage data sources and trigger collection |
+| Data Sources | `/datasources` | View data sources and trigger collection |
 | Collected Data | `/data` | View collected data |
 | BGP Observation | `/bgp` | BGP situational data |
 | System Alerts | `/alerts/system` | System-level alerts |
@@ -321,17 +357,21 @@ Common pages:

 ### Data Sources

-`/datasources` shows and manages collection sources.
+`/datasources` shows collection sources and triggers collection. It is now a data source directory that lists built-in and custom sources in one table.

 Common operations:

 - View data source status
 - Trigger collection
 - View recent collection tasks
- Adjust configuration
+- Open the read-only detail drawer for endpoint, headers, runtime config, and built-in/custom source type

 If a category of objects is missing on Earth, start here to confirm the data source is available.

+The data source name opens an information drawer only. Endpoint, credentials, headers, and custom source configuration are maintained under `/settings` collector settings.
+
+When collection tasks are running, the progress area shows a clickable `Collecting N` pill. Clicking it opens a modal with each running task's phase, progress, and processed count.
+
 ### Collected Data

 `/data` shows the collected data table.
@@ -369,10 +409,50 @@ Current common uses:

 - System settings
 - TV live stream source configuration
- Data source configuration entry points
+- Collector settings
+- External integrations and AI Provider configuration

 Available configuration depends on the current user's role.

+#### Collector Settings
+
+`/settings?tab=collector_credentials` is currently displayed as Collector Settings. It manages connection settings for all collectors, not only credentials.
+
+Use it to:
+
+1. Select a collector from the dropdown.
+2. Review tags such as `Requires credentials`, module, enabled state, and `Unchecked` / `Available` / `Unavailable`.
+3. Click the plug icon next to the selector to run a health check.
+4. Edit endpoint, request headers, timeout, and retry settings.
+5. Save the collector settings.
+
+Free collectors are checked by requesting their endpoint directly. Credentialed collectors use their credential provider. If endpoint or credential fingerprint changes after the last successful validation, the collector must be checked again.
+
+The system treats a collector as connected when the current configuration has either collected data successfully or passed the manual connection check.
+
+#### BarentsWatch AIS Credentials
+
+`BarentsWatch AIS` is a credentialed built-in collector. Its credential card appears above the basic configuration card.
+
+Configured fields:
+
+- `Client ID`
+- `Client Secret`
+- `Endpoint`
+
+If a secret is already configured, the input shows a masked preview. Keeping that preview unchanged preserves the stored secret; entering a new value replaces it.
+
+BarentsWatch AIS credentials can be read from:
+
+1. Collector settings saved in the console.
+2. Backend environment variables:
+   - `BARENTSWATCH_CLIENT_ID`
+   - `BARENTSWATCH_CLIENT_SECRET`
+   - historical spellings: `BARRENTSWATCH_CLIENT_ID`, `BARRENTSWATCH_CLIENT_SECRET`
+3. matching `export` lines in `~/.zshrc`.
+
+If connection fails, the page opens the credential guide. The guide can be regenerated through AI Provider or reset to the default guide. The default guide points users to the official BarentsWatch tutorial and emphasizes selecting `AIS - API`, not the regular `BarentsWatch - API`.
+
 ### System Logs

 `/logs` views system logs. If the menu item is not visible, the current user likely lacks the required role.
--- a/docs/technical/en/quickstart.md
+++ b/docs/technical/en/quickstart.md
@@ -73,6 +73,7 @@ Once in, verify:
 - The globe renders correctly
 - The right-side layer panel can toggle layers on/off
 - Search can find cables, satellites, compute centers, BGP events
+- Mouse drag, wheel zoom, and zoom percent feedback work correctly
 - Settings panel can switch cruise mode, day/night mode, satellite display style

 ## 4. Open the Console
@@ -87,7 +88,7 @@ The console manages data sources, collected data, situational observation, alert

 First-time inspection checklist:

- `/datasources`: data source configuration and collection status
+- `/datasources`: data source directory and collection triggers; endpoint, headers, and credentials are configured under `/settings` collector settings
 - `/data`: collected data
 - `/bgp`: BGP situational view
 - `/alerts/system`: system alerts
--- a/docs/technical/zh/README.md
+++ b/docs/technical/zh/README.md
@@ -5,7 +5,6 @@
 - 现在代码是怎么组织的
 - 当前入口在哪
 - 状态和组件如何工作
- 后续改动应该沿着哪条实现边界继续走

 适合放入这里的内容：

@@ -17,12 +16,14 @@
 - Earth 图层样式属性索引
 - 后端运行控制
 - 采集器现状
+- 采集器设置与连接验证
 - 采集格式约定

 ## 使用入口

 - [quickstart.md](/home/ray/dev/linkong/planet/docs/technical/zh/quickstart.md)：从零启动 Planet 的最短路径
 - [manual.md](/home/ray/dev/linkong/planet/docs/technical/zh/manual.md)：控制台、`planet.sh`、Earth 和 Docs 的完整使用手册
+- [datasource-collector-settings-connectivity.md](/home/ray/dev/linkong/planet/docs/technical/zh/datasource-collector-settings-connectivity.md)：数据源目录、采集器设置、连接验证、BarentsWatch 凭证链路

 不适合放入这里的内容：

--- a/docs/technical/zh/backend-collectors.md
+++ b/docs/technical/zh/backend-collectors.md
@@ -84,6 +84,8 @@ async def run(self, db):
 | HuggingFace Spaces | space | Demo应用 | 1天 |
 | PeeringDB | ixp/network/facility | 互联网交换点/网络/机房 | 1-2天 |
 | TeleGeography | submarine_cable | 海底光缆信息 | 7天 |
+| Space-Track TLE | satellite_tle | 卫星轨道 TLE 数据 | 依采集器配置 |
+| BarentsWatch AIS | vessel | 船只位置、航速、航向、MMSI 等 AIS 数据 | 依采集器配置 |

 ## 四、数据格式 (统一存储到 CollectedData 表)

@@ -200,6 +202,30 @@ def start_scheduler():

 **核心文件**: `backend/app/services/scheduler.py`

+### 成功采集与连接状态
+
+内置采集器成功采集后，调度器会记录当前有效配置已通过连接验证：
+
+```python
+if datasource.last_status == "success":
+    effective_candidate = await get_builtin_effective_candidate(db, datasource.source)
+    checksum, _ = await build_builtin_connectivity_checksum(...)
+    await save_connectivity_success(
+        db,
+        datasource.source,
+        checksum,
+        {"status_code": None},
+        connected_by="collection",
+    )
+```
+
+这个记录用于控制台“采集器设置”中的连接状态判断：如果当前配置和成功采集时的 checksum 一致，就视为已连接，不要求用户再手动点击连接按钮。只有 endpoint、请求头、基础配置或凭证指纹变化时，才需要重新验证。
+
+相关实现见：
+
+- [datasource_connectivity.py](/home/ray/dev/linkong/planet/backend/app/services/datasource_connectivity.py)
+- [datasource-collector-settings-connectivity.md](/home/ray/dev/linkong/planet/docs/technical/zh/datasource-collector-settings-connectivity.md)
+
 ## 八、相关代码文件

 ```
@@ -211,13 +237,86 @@ backend/app/services/collectors/
 ├── epoch_ai.py          # Epoch AI采集器
 ├── huggingface.py       # HuggingFace采集器
 ├── peeringdb.py         # PeeringDB采集器
-└── telegeraphy.py      # TeleGeography海底光缆采集器
+├── telegeraphy.py       # TeleGeography海底光缆采集器
+└── vessel_ais.py        # BarentsWatch AIS 船只采集器

 backend/app/models/
 └── collected_data.py    # 统一数据模型
 ```

-## 九、数据使用场景
+## 九、凭证型采集器
+
+部分采集器需要外部服务凭证，例如：
+
+| 采集器 | credential provider | 凭证来源 |
+| --- | --- | --- |
+| `barentswatch_vessels` | `barentswatch` | 控制台采集器设置、环境变量、`~/.zshrc` |
+| `spacetrack_tle` | `spacetrack` | 环境变量、`~/.zshrc` |
+
+### BarentsWatch AIS
+
+BarentsWatch AIS 的凭证解析统一在：
+
+- [barentswatch.py](/home/ray/dev/linkong/planet/backend/app/services/barentswatch.py)
+
+`VesselAISCollector` 只负责采集和转换 AIS 数据，不再自己读取环境变量或拼 token 请求。它通过：
+
+- `resolve_barentswatch_config()`
+- `fetch_barentswatch_access_token()`
+
+获取运行时配置。
+
+解析优先级：
+
+1. `DataSourceConfig.auth_config`
+2. `DataSourceConfig.config`
+3. 环境变量
+4. `~/.zshrc`
+
+支持变量：
+
+```bash
+export BARENTSWATCH_CLIENT_ID="..."
+export BARENTSWATCH_CLIENT_SECRET="..."
+```
+
+并兼容历史拼写：
+
+```bash
+export BARRENTSWATCH_CLIENT_ID="..."
+export BARRENTSWATCH_CLIENT_SECRET="..."
+```
+
+连接验证会先请求 `https://id.barentswatch.no/connect/token` 获取 `scope=ais` 的 access token，再用 `Authorization: Bearer <token>` 请求 AIS endpoint。
+
+## 十、采集器设置与连接验证
+
+控制台的“采集器设置”页提供所有内置采集器的 endpoint、请求头、超时、重试和凭证配置。连接验证不是只看前端按钮状态，而是由后端计算 checksum：
+
+- endpoint
+- auth type
+- headers
+- config
+- credential provider
+- 凭证指纹
+
+相关 API：
+
+```http
+GET  /api/v1/datasources/configs/all
+POST /api/v1/datasources/configs/builtin/connection-status
+POST /api/v1/datasources/configs/builtin/connect
+POST /api/v1/settings/integrations/barentswatch/connect
+GET  /api/v1/settings/credential-guides/{provider}
+POST /api/v1/settings/credential-guides/{provider}/generate
+POST /api/v1/settings/credential-guides/{provider}/reset
+```
+
+更多细节见：
+
+- [datasource-collector-settings-connectivity.md](/home/ray/dev/linkong/planet/docs/technical/zh/datasource-collector-settings-connectivity.md)
+
+## 十一、数据使用场景

 采集的数据最终会：

@@ -225,7 +324,7 @@ backend/app/models/
 2. **态势分析** - 统计全球算力分布、增长趋势
 3. **告警系统** - 检测重要节点变化

-## 十、采集器注册机制
+## 十二、采集器注册机制

 采集器在应用启动时自动注册：

@@ -247,7 +346,7 @@ collector_registry.register(TeleGeographyCableSystemCollector())

 **核心文件**: `backend/app/services/collectors/registry.py`

-## 十一、触发采集
+## 十三、触发采集

 ### 方式一：定时触发
 系统启动时，APScheduler会自动根据各采集器的`frequency_hours`设置定时任务。
--- a/docs/technical/zh/backend-datasources-api-performance.md
+++ b/docs/technical/zh/backend-datasources-api-performance.md
@@ -69,7 +69,7 @@ last_status = datasource.last_status
 ```
 datasources SELECT          → 主数据，必须
 _load_latest_running_tasks  → 必须（进行中状态 + stale check）
-_load_datasource_endpoint_overrides → 必须（endpoint 覆盖，编辑内置 collector 时需要默认值）
+_load_datasource_endpoint_overrides → 必须（endpoint 覆盖，列表详情和采集器设置需要显示当前有效地址）
 ```

 3 个查询（原来 5 个），后两个顺序执行（running tasks 先完成用于 stale check，endpoint overrides 轻量）。
@@ -87,7 +87,6 @@ fetchData()  // 总是立即刷 → 与上面的延迟刷重叠

 // 修复后（二者互斥）
 if (res.data.task_id) {
-    setTaskProgress(...)
    fetchData()           // 有 task_id：立即刷一次
 } else {
    window.setTimeout(fetchData, 800)  // 无 task_id：等 800ms 再刷一次
--- a/docs/technical/zh/backend-system-service-control.md
+++ b/docs/technical/zh/backend-system-service-control.md
@@ -22,10 +22,10 @@

 | Action 名称 | 用途 | `planet.sh` 命令 | 备注 |
 | --- | --- | --- | --- |
-| `restart-backend` | 只重启后端 API | `./planet.sh restart -b` | 推荐作为 UI 触发重启流程的第一阶段实现。 |
+| `restart-backend` | 只重启后端 API | `./planet.sh restart -b` | 页面通常短暂失联后由 `/health` 轮询恢复。 |
+| `restart-frontend` | 只重启前端开发服务器 | `./planet.sh restart -f` | 页面入口会短暂不可用；UI 通过前端入口探测恢复后刷新。 |
 | `restart-database` | 重启 PostgreSQL 和 Redis 容器 | `./planet.sh restart -d` | 适合数据库/缓存需要受控重启但不希望重启 UI 的场景。 |
 | `restart-system` | 重启整个应用栈 | `./planet.sh restart` | 前端会短暂中断；UI 应进入引导恢复模式。 |
-| `restart-frontend` | 只重启前端开发服务器 | `./planet.sh restart -f` | 谨慎使用；UI 连续性弱于只重启后端。 |
 | `restart-backend-port` | 在指定端口重启后端 | `./planet.sh restart -b <port>` | 执行前必须由后端校验端口。 |
 | `restart-frontend-port` | 在指定端口重启前端 | `./planet.sh restart -f <port>` | 执行前必须由后端校验端口。 |
 | `health-check` | 读取当前服务健康状态 | `./planet.sh health` | 安全的只读运维动作。 |
@@ -269,21 +269,25 @@ health-check         -> ["./planet.sh", "health"]
 - `服务已恢复，正在刷新页面`
 - `恢复超时，请手动检查服务状态`

-## 第一阶段建议
+## 当前 Dashboard 实现

-第一阶段只实现：
+Dashboard 当前已实现：

 - `restart-backend`
+- `restart-frontend`
+- `restart-ai-provider`
+- `restart-database`
+- `restart-system`
 - `super_admin` 权限门禁
 - 任务创建接口
 - Redis 任务状态
 - 前端确认 modal
- 前端 `/health` 轮询
+- 后端 `/health` 轮询
+- 前端入口轮询
 - 恢复后自动刷新页面

-第一阶段不要实现：
+暂不实现：

- 完整 `./planet.sh restart`
 - 原始 shell 命令透传
 - 任意服务控制
 - 完整终端 stdout 流式输出
@@ -305,17 +309,18 @@ health-check         -> ["./planet.sh", "health"]

 ### 前端

-1. 在 dashboard 为 `super_admin` 增加 `重启后端` 控件
+1. 在 dashboard 为 `super_admin` 增加 `重启服务` 控件
 2. 发送前展示确认 modal
 3. 提交后将 modal 切换为阻塞式重启状态
-4. 轮询 `/health` 直到确认后端恢复
-5. 连续健康检查成功后自动刷新页面
-6. 展示简短阶段日志，而不是原始终端流
+4. 后端重启使用 `/health` 轮询确认恢复
+5. 前端重启和完全重启使用前端入口探测确认恢复
+6. 连续健康检查成功后自动刷新页面
+7. 展示简短阶段日志，而不是原始终端流

 ### 运维说明

-1. 第一阶段目标应限定为只重启后端
-2. 前端重启初期保持在范围外
+1. 优先使用局部重启，只有确实需要时才执行完全重启
+2. 前端重启会打断当前页面入口，必须进入恢复等待状态
 3. 命令执行必须始终从仓库根目录发起
 4. API 边界只能传递固定 action 名称

@@ -324,10 +329,5 @@ health-check         -> ["./planet.sh", "health"]
 - 拒绝任何不在白名单中的 action。
 - 如果增加带端口 action，端口必须校验为 `1..65535` 的整数。
 - 从仓库根目录解析命令，确保 `planet.sh` 的工作目录稳定。
+- detached runner 使用 `zsh -ic` 执行白名单命令，确保 `~/.zshrc` 中的本地环境变量进入重启流程。
 - 记录请求 action、操作者身份、执行开始时间和结果。
-
-## 实现建议
-
- UI 触发重启流程时，优先实现 `restart-backend`。
- 不要依赖当前 API 请求进程在触发自身重启后继续输出完整日志。
- 主 UX 使用任务记录加轮询/健康检查恢复流程，而不是原始终端流。
--- a/docs/technical/zh/datasource-collector-settings-connectivity.md
+++ b/docs/technical/zh/datasource-collector-settings-connectivity.md
@@ -0,0 +1,327 @@
+# 采集器设置与连接验证
+
+## 背景
+
+控制台现在把“数据源目录”和“采集器配置”拆开：
+
+- `/datasources`
+  - 展示所有数据源，包括内置和自定义。
+  - 点击名称只打开信息抽屉。
+  - 负责查看状态、触发采集和查看采集中任务。
+- `/settings?tab=collector_credentials`
+  - 显示为“采集器设置”。
+  - 负责 endpoint、请求头、基础参数和凭证配置。
+  - 所有采集器都提供连接按钮，用于健康检查。
+
+这样做是为了减少首次使用时的认知分裂：接口地址、请求头、凭证和自定义源配置都属于“采集器设置”，而不是散落在数据源列表和系统设置多个入口里。
+
+## 用户侧规则
+
+连接状态不是前端样式状态，而是由后端根据配置 checksum 和已验证记录判断。
+
+一个内置采集器被视为“已连接”需要满足任一条件：
+
+- 当前配置已经成功采集过数据。
+- 当前配置点击过连接按钮，并且后端验证成功。
+
+如果 endpoint、请求头、基础配置或凭证指纹相对上次验证成功时发生变化，状态会回到“需要重新连接”。
+
+## 前端入口
+
+### 数据源目录
+
+文件：
+
+- [DataSources.tsx](/home/ray/dev/linkong/planet/frontend/src/pages/DataSources/DataSources.tsx)
+- [index.css](/home/ray/dev/linkong/planet/frontend/src/index.css)
+
+当前行为：
+
+- 内置数据源和自定义数据源合并为 `UnifiedDataSource` 列表。
+- 表格只保留查看、采集和状态类操作。
+- 名称点击打开只读抽屉。
+- 抽屉中展示：
+  - 是否内置
+  - 是否启用
+  - 模块、优先级、频率
+  - endpoint
+  - 请求头
+  - 基础配置
+  - 是否需要凭证
+- 有任务运行时，顶部进度区显示 `采集中 N` 可点击标签。
+- 点击 `采集中 N` 打开任务列表弹窗，显示各任务进度。
+
+`data-source-bulk-toolbar__running-pill` 是“采集中”标签的样式入口。它和其他状态标签同排，但通过 hover、箭头和蓝色描边表达可交互性。
+
+### 采集器设置
+
+文件：
+
+- [Settings.tsx](/home/ray/dev/linkong/planet/frontend/src/pages/Settings/Settings.tsx)
+
+当前行为：
+
+- `collector_credentials` tab 展示为“采集器设置”。
+- 下拉框列出所有内置采集器。
+- 下拉框右侧只有一个插头图标按钮，用于健康检查。
+- 下拉框下方用状态标签展示：
+  - `需要凭证` / `无需凭证`
+  - 模块
+  - `启用` / `禁用`
+  - `未检查` / `可用` / `不可用`
+  - 是否覆盖 endpoint
+- 需要凭证的采集器把凭证卡片放在基础配置上方。
+- 不需要凭证的采集器只显示基础配置。
+
+连接按钮使用内联 Tabler 风格插头图标，来源语义对应 `plug-connected`，避免继续使用刷新图标表达连接动作。
+
+## 后端接口
+
+### 数据源配置列表
+
+```http
+GET /api/v1/datasources/configs/all
+```
+
+返回 YAML 默认数据源和数据库覆盖配置的合并结果。该路由必须定义在 `/configs/{config_id}` 之前，否则 `all` 会被 FastAPI 当成路径参数并触发 422。
+
+返回字段包括：
+
+- `name`
+- `default_url`
+- `endpoint`
+- `is_overridden`
+- `is_active`
+- `source_type`
+- `auth_type`
+- `headers`
+- `config`
+- `config_id`
+- `description`
+
+`config` 返回前会移除内部连接验证字段，避免前端把校验元数据当成用户配置展示。
+
+### 内置采集器连接状态
+
+```http
+POST /api/v1/datasources/configs/builtin/connection-status
+```
+
+用途：
+
+- 给定一份候选配置。
+- 计算 checksum。
+- 判断当前配置是否已经连接。
+
+当前前端主要通过连接按钮即时检查，不强依赖这个接口，但它是后续保存按钮置灰、页面初始化状态恢复的后端依据。
+
+### 内置采集器连接验证
+
+```http
+POST /api/v1/datasources/configs/builtin/connect
+```
+
+用途：
+
+- 免费采集器直接请求 endpoint。
+- 需要凭证的采集器走对应 credential provider。
+- 验证成功后写入系统级连接记录。
+
+成功返回中会带：
+
+- `success`
+- `connected`
+- `checksum`
+- `stage`
+- `message`
+- `response_time_ms`
+- `credential_provider`
+- `credential_source`
+
+### BarentsWatch AIS 连接验证
+
+```http
+POST /api/v1/settings/integrations/barentswatch/connect
+GET  /api/v1/settings/integrations/barentswatch/connectivity
+```
+
+BarentsWatch 使用独立接口，是因为它需要在保存前验证草稿凭证：
+
+- 使用草稿 `client_id` / `client_secret` 获取 token。
+- 使用 token 请求 AIS endpoint。
+- 连接成功后用草稿凭证指纹写入内置采集器连接记录。
+
+## 连接校验服务
+
+文件：
+
+- [datasource_connectivity.py](/home/ray/dev/linkong/planet/backend/app/services/datasource_connectivity.py)
+
+核心职责：
+
+- 计算内置采集器配置 checksum。
+- 读取环境变量和 `~/.zshrc` 中的凭证。
+- 判断当前配置是否已连接。
+- 执行 endpoint 健康检查。
+- 保存连接成功记录。
+
+### checksum 组成
+
+checksum 包含：
+
+- 采集器名称
+- endpoint
+- auth type
+- headers
+- 去掉内部校验字段后的 config
+- credential provider
+- 凭证指纹
+
+凭证指纹使用凭证内容 hash，不把明文凭证写入连接记录。
+
+### 连接记录
+
+连接成功记录写入 `SystemSetting`：
+
+```text
+category = datasource_connectivity_validations
+```
+
+payload 以采集器 source 为 key：
+
+```json
+{
+  "barentswatch_vessels": {
+    "checksum": "...",
+    "status": "success",
+    "validated_at": "2026-04-29T00:00:00+00:00",
+    "status_code": 200,
+    "credential_source": "datasource_config",
+    "connected_by": "connection_button"
+  }
+}
+```
+
+`connected_by` 当前有两个来源：
+
+- `connection_button`
+  - 用户手动点击连接按钮。
+- `collection`
+  - 采集任务成功完成，系统自动记录当前有效配置已连通。
+
+### 成功采集即连接
+
+调度器在采集成功后会调用连接记录写入逻辑：
+
+- [scheduler.py](/home/ray/dev/linkong/planet/backend/app/services/scheduler.py)
+
+这样已有数据的采集器不会要求用户重复验证。只有当配置 checksum 变化时，才需要重新点击连接。
+
+## BarentsWatch AIS 凭证链路
+
+文件：
+
+- [barentswatch.py](/home/ray/dev/linkong/planet/backend/app/services/barentswatch.py)
+- [vessel_ais.py](/home/ray/dev/linkong/planet/backend/app/services/collectors/vessel_ais.py)
+
+解析优先级：
+
+1. `DataSourceConfig.auth_config`
+2. `DataSourceConfig.config`
+3. 环境变量
+4. `~/.zshrc`
+
+支持的环境变量：
+
+```bash
+export BARENTSWATCH_CLIENT_ID="..."
+export BARENTSWATCH_CLIENT_SECRET="..."
+```
+
+也兼容历史拼写：
+
+```bash
+export BARRENTSWATCH_CLIENT_ID="..."
+export BARRENTSWATCH_CLIENT_SECRET="..."
+```
+
+Token 请求规则：
+
+- Token URL：`https://id.barentswatch.no/connect/token`
+- `Content-Type`: `application/x-www-form-urlencoded`
+- Body:
+  - `grant_type=client_credentials`
+  - `client_id`
+  - `client_secret`
+  - `scope=ais`
+
+AIS 请求规则：
+
+- Endpoint 默认：`https://live.ais.barentswatch.no/v1/latest/combined`
+- Header：`Authorization: Bearer <access_token>`
+
+`VesselAISCollector` 不再自己读取环境变量，而是统一走 `resolve_barentswatch_config()` 和 `fetch_barentswatch_access_token()`，避免设置页、连接验证和采集器三套凭证逻辑分叉。
+
+## 凭证教程
+
+文件：
+
+- [credential_guides.py](/home/ray/dev/linkong/planet/backend/app/services/credential_guides.py)
+
+接口：
+
+```http
+GET  /api/v1/settings/credential-guides/{provider}
+POST /api/v1/settings/credential-guides/{provider}/generate
+POST /api/v1/settings/credential-guides/{provider}/reset
+```
+
+当前支持：
+
+- `barentswatch`
+
+默认教程包含 BarentsWatch 官方 tutorial 地址：
+
+```text
+https://developer.barentswatch.no/docs/tutorial
+```
+
+如果用户点击“教程不好用”，后端会把默认 prompt 发给 AI Provider 生成新的中文教程，并保存到 `SystemSetting`：
+
+```text
+category = collector_credential_guides
+```
+
+“重置”会删除自定义教程，恢复默认教程。
+
+## 保存规则
+
+内置采集器配置保存时会移除内部 `connectivity_validation` 字段，避免校验状态跟用户配置混在一起。
+
+BarentsWatch `client_secret` 保存时有特殊处理：
+
+- 输入框显示脱敏预览。
+- 如果提交值仍等于脱敏预览，后端保留原 secret。
+- 如果输入新值，才替换 secret。
+- 不再提供单独“清除当前 secret”复选框。
+
+## 测试覆盖
+
+相关测试：
+
+- [test_vessels.py](/home/ray/dev/linkong/planet/backend/tests/test_vessels.py)
+
+新增覆盖：
+
+- 能从 `~/.zshrc` 解析 BarentsWatch 凭证。
+- 环境变量为空时，`resolve_barentswatch_config()` 能回退到 `~/.zshrc`。
+- 船只数据转换和 GeoJSON 输出保持兼容。
+
+## 当前 Provider 覆盖
+
+当前已经支持的凭证 provider：
+
+- `barentswatch`
+- `spacetrack`
+
+其他 `requires_credentials=true` 的采集器如果还没有 provider，会返回“凭证链路尚未接入”，前端显示 `不可用`。
--- a/docs/technical/zh/earth-frontend-context.md
+++ b/docs/technical/zh/earth-frontend-context.md
@@ -81,6 +81,13 @@ React 路由入口：
 - status message
 - tooltip / error / 清理逻辑

+当前 status message 有两类短提示：
+
+- 普通业务提示：通过 `showStatusMessage()` 入队显示。
+- 手势提示：通过 `showGestureStatusMessage()` 直接短暂显示，用于缩放视角时的 `缩放 N%`。
+
+手势提示不会抢占 loading 状态。对应样式是 [hud.css](/home/ray/dev/linkong/planet/frontend/public/earth/css/hud.css) 中的 `.earth-status-message.gesture`。
+
 ### 5. 地球与地形

 - [earth.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/earth.js)
@@ -98,6 +105,7 @@ React 路由入口：
 - [cables.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/cables.js)
 - [bgp.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/bgp.js)
 - [bgp-cruise-adapter.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/bgp-cruise-adapter.js)
+- [vessels.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/vessels.js)
 - [news.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/news.js)
 - [tv.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/tv.js)
 - [layer-startup-tasks.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/layer-startup-tasks.js)
@@ -132,6 +140,10 @@ React 路由入口：

 当前 BGP 巡航只是这套能力的一个调用方，不应再把“按队列巡航”和“BGP 事件展示”混写在同一个状态机里。

+新闻巡航摘要计划见：
+
+- [earth-news-cruise-summary-plan.md](/home/ray/dev/linkong/planet/docs/plans/earth-news-cruise-summary-plan.md)
+
 ## 当前样式分层

 Earth 的 CSS 不是一份大样式表，而是分层管理：
@@ -232,6 +244,56 @@ Earth 图层按钮现在不应再只有“开/关”两态，而应支持：

 这样后续新增会参与启动加载的图层时，顺序、模式和提示文案都在同一处定义，不需要再去 `main.js` 里补第二套常量。

+### 船只图层与图例
+
+AIS 船只图层入口：
+
+- [vessels.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/vessels.js)
+
+船只图层当前负责：
+
+- 请求 `/api/v1/visualization/geo/vessels`
+- 将 BarentsWatch AIS GeoJSON 转为 Three.js sprite
+- 按船型映射颜色
+- 根据航行/停泊状态绘制三角形或圆点纹理
+- 支持 hover、lock、轨迹加载和视觉聚焦
+
+图例系统已经注册 `vessels` 模式：
+
+- [legend.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/legend.js)
+- [legend.css](/home/ray/dev/linkong/planet/frontend/public/earth/css/legend.css)
+
+`getVesselLegendItems()` 返回带 `shape` 的图例项：
+
+- `shape: "vessel"`：三角形，表示航行船只。
+- `shape: "dot"`：圆点，表示停泊或低速状态。
+
+图例项颜色来自 `VESSEL_CONFIG.colors`，不要在 `legend.css` 里重新定义业务颜色。新增船型时，应优先改 `vessels.js` 和 `constants.js` 的船型映射，再同步图例项。
+
+### 视角控制反馈
+
+[controls.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/controls.js) 统一维护 Earth 缩放状态。滚轮缩放、缩放按钮和触屏双指捏合最终都会更新 `zoomLevel`，并通过 `showZoomStatusCapsule()` 显示当前缩放比例：
+
+```javascript
+showGestureStatusMessage(`缩放 ${Math.round(zoomLevel * 100)}%`, "info");
+```
+
+该提示每 90ms 最多更新一次，显示 760ms 后淡出。它是视角反馈，不是数据加载进度，也不应该写进图层 loading 状态。
+
+[main.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/main.js) 只负责在双指捏合缩放时调用 `setZoomLevel()` 和 `showZoomStatusCapsule()`。鼠标滚轮与缩放按钮的胶囊提示应继续放在 `controls.js`，避免同一种缩放反馈散落在多个模块。
+
+拖拽地球的旋转灵敏度会根据当前缩放连续衰减，而不是按某个缩放阈值分段：
+
+```javascript
+const scale = THREE.MathUtils.clamp(
+  Math.pow(zoom, -CONFIG.dragRotationZoomExponent),
+  CONFIG.dragRotationScaleMin,
+  CONFIG.dragRotationScaleMax,
+);
+```
+
+调参入口在 [constants.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/constants.js)：`dragRotationFactorBase` 控制基础速度，`dragRotationZoomExponent` 控制放大后的衰减曲线，`dragRotationScaleMin` / `dragRotationScaleMax` 控制上下限。
+
 ### `data-status-target`

 图层按钮可以通过：
@@ -284,98 +346,23 @@ Earth 设置面板当前由 [controls.js](/home/ray/dev/linkong/planet/frontend/
 1. 图层开关 loading 状态持续可见
 2. 页面空闲时会预热 `ensureTerrainReady()`

-也就是说，后续再继续优化 terrain 时，优先顺序应该是：
+## 当前巡航链路

-1. 先保证用户感知正确
-2. 再压缩首次等待
-3. 最后才做更激进的几何/瓦片优化
+当前巡航边界：

-## 当前高频风险点
-
-### 1. 视觉状态和业务状态不同步
-
-Earth 里最常见的 bug 不是“没渲染”，而是：
-
- 图层关了，tooltip 还在
- 锁定对象隐藏了，info card 还在
- legend 没跟图层切换
- loading 已结束，但按钮还像没开
-
-后续改动必须优先检查状态同步。
-
-### 2. HUD 布局问题先查结构，不要先打 CSS 补丁
-
-Earth HUD 历史上反复出现：
-
- 面板只剩一条缝
- markdown 被裁掉
- tabs/iframe 被 `overflow: hidden` 吃掉
-
-优先检查：
-
-1. 谁负责高度
-2. 谁负责滚动
-3. 哪一层在裁剪
-
-不要上来先加 `overflow: hidden` 或额外包装层。
-
-### 3. Transitional path 必须收口
-
-Earth 已经经历过多轮 HUD、toolbar、media panel 重构，所以最容易积累：
-
- 旧 helper
- 旧 class
- 旧 fallback 逻辑
- 已废弃变体
-
-每次大功能完成后，都要做一次 cleanup pass。
-
-### 4. 巡航与业务事件不要再深度耦合
-
-当前正确边界应该是：
-
- 通用巡航层只知道：
+- 通用巡航层包含：
  - 当前目标
  - 队列顺序
  - 相机 focus
  - 停留 / 隐藏 / 切换
- 业务模块只负责：
+- 业务模块提供：
  - 提供目标队列
  - 提供 focus 坐标
  - 提供卡片内容
  - 提供高亮/图层副作用

-如果以后再给海缆、卫星或新闻做巡航，不应复制一套新的 `main.js` 状态变量，而应复用：
+巡航模块的结构文件：

 - [cruise-sequencer.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/cruise-sequencer.js)
 - [callout-connector.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/callout-connector.js)
- [bgp-cruise-adapter.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/bgp-cruise-adapter.js) 这种业务适配层模式
-
-## 当前推荐改动方式
-
-如果后续继续改 Earth，建议按这个顺序：
-
-1. 先确认改的是：
-   - Three.js 渲染层
-   - HUD 结构层
-   - 图层状态层
-   - 面板内容层
-2. 如果涉及图层按钮，优先接入统一状态机
-3. 如果涉及可见性切换，检查 tooltip / legend / info-card / lock 是否一起收口
-4. 如果涉及面板布局，先查结构再动 CSS
-
-## 当前与控制台前端的边界
-
-Earth 前端和控制台前端不是同一套 UI 系统：
-
- 控制台前端：React + Ant Design 工作台
- Earth 前端：`public/earth` 原生 HUD + Three.js 展示面
-
-因此：
-
- Earth 不应该直接复用 Ant Table / AppLayout 语义
- 控制台也不应该照搬 Earth HUD 动画和玻璃层语言
-
-控制台相关结构见：
-
- [admin-frontend-context.md](/home/ray/dev/linkong/planet/docs/technical/zh/frontend-admin-frontend-context.md)
+- [bgp-cruise-adapter.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/bgp-cruise-adapter.js)
--- a/docs/technical/zh/earth-layer-style-reference.md
+++ b/docs/technical/zh/earth-layer-style-reference.md
@@ -95,11 +95,11 @@
 | 国界线颜色 | `COUNTRY_BOUNDARY_CONFIG.lineColor` | `0x7fc7ff` | 普通国界线 |
 | 国界线透明度 | `COUNTRY_BOUNDARY_CONFIG.lineOpacity` | `0.58` | 普通国界线 opacity |
 | 国界线 hover 时压暗透明度 | `COUNTRY_BOUNDARY_CONFIG.dimmedLineOpacity` | `0.18` | hover 时普通国界线 opacity |
-| 国界线半径偏移 | `COUNTRY_BOUNDARY_CONFIG.lineAltitudeOffset` | `0.24` | 普通国界线半径 |
+| 国界线半径偏移 | `COUNTRY_BOUNDARY_CONFIG.lineAltitudeOffset` | `0.115` | 普通国界线半径；略高于高清材质 `0.10`，低于地形基准 `0.16`，减少悬浮感 |
 | 国界线 renderOrder | `COUNTRY_BOUNDARY_CONFIG.lineRenderOrder` | `2.2` | 普通国界线层级 |
 | 国界 hover 颜色 | `COUNTRY_BOUNDARY_CONFIG.hoverLineColor` | `0xff3b1f` | 霓虹红橘 |
 | 国界 hover 透明度 | `COUNTRY_BOUNDARY_CONFIG.hoverLineOpacity` | `1.0` | hover 实线 opacity |
-| 国界 hover 半径偏移 | `COUNTRY_BOUNDARY_CONFIG.hoverAltitudeOffset` | `0.32` | hover 实线半径 |
+| 国界 hover 半径偏移 | `COUNTRY_BOUNDARY_CONFIG.hoverAltitudeOffset` | `0.14` | hover 实线半径；贴近地表但高于普通国界线 |
 | 国界 hover renderOrder | `COUNTRY_BOUNDARY_CONFIG.hoverLineRenderOrder` | `2.3` | hover 实线层级 |
 | 国界 hover glow 透明度 | `COUNTRY_BOUNDARY_CONFIG.hoverGlowOpacity` | `0.38` | glow 线 opacity |
 | 国界 hover glow 线宽 | `COUNTRY_BOUNDARY_CONFIG.hoverGlowLineWidth` | `3` | glow `LineBasicMaterial.linewidth` |
--- a/docs/technical/zh/earth-news-live-streams-collector-format.md
+++ b/docs/technical/zh/earth-news-live-streams-collector-format.md
@@ -103,7 +103,7 @@

 ## 采集器配置方式

-`news_live_streams` 不需要单独新页面，直接复用现有数据源配置：
+`news_live_streams` 不需要单独新页面，直接复用控制台 `/settings` 的“采集器设置”：

 - `endpoint`
  - 频道目录 JSON API 地址
--- a/docs/technical/zh/earth-render-layer-order.md
+++ b/docs/technical/zh/earth-render-layer-order.md
@@ -7,8 +7,8 @@

 | 顺序类型 | 当前顺序 | 说明 |
 | --- | --- | --- |
-| 控制面板顺序 | 海缆 → 轨迹 → 卫星 → 算力中心 → BGP → 地形 → 高清材质 → 大气云图 → 国界 → 经纬线 | 由 `displayOrder` 控制，按操作关注度排列。 |
-| 注册 / 启动加载顺序 | 经纬线 → 国界 → 高清材质 → 大气云图 → 海缆 → 算力中心 → BGP → 卫星 | 由注册顺序和 `startupPriority` 控制，按地表到天空排列；轨迹和地形是依赖/可选显示层，不参与常规启动数据加载。 |
+| 控制面板顺序 | 海缆 → 轨迹 → 卫星 → 算力中心 → 船只 → BGP → 地形 → 高清材质 → 大气云图 → 国界 → 经纬线 | 由 `displayOrder` 控制，按操作关注度排列。 |
+| 注册 / 启动加载顺序 | 经纬线 → 国界 → 高清材质 → 大气云图 → 海缆 → 算力中心 → 船只 → BGP → 卫星 | 由注册顺序和 `startupPriority` 控制，按地表到天空排列；船只和卫星默认关闭，只有可见时参与启动加载；轨迹和地形是依赖/可选显示层，不参与常规启动数据加载。 |

 ## 地表图层栈

@@ -24,11 +24,13 @@
 | 1 | 海缆 | `cables.js` | `CABLE_CONFIG.line.renderOrder` | 海缆拾取路径 | 保持现有海缆层级。 |
 | 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` | 禁用 raycast | 只保证压过高清材质。 |
+| 2.2 | 国界线 | `country-boundaries.js` | `lineAltitudeOffset = 0.115` | `depthTest: true`，禁用 raycast | 略高于高清材质 `0.10`，低于地形基准 `0.16`，减少悬浮感；地形 `depthWrite: false`，所以地形开启时仍可见。 |
 | 2.29 | 国界 hover 光晕 | `country-boundaries.js` | hover 半径加 glow 偏移 | `depthTest: false`，禁用 raycast | 用 additive 光晕增强交界边和地形开启时的 hover 可见性。 |
-| 2.3 | 国界 hover 实线 | `country-boundaries.js` | `hoverAltitudeOffset` | `depthTest: false`，禁用 raycast | 霓虹红橘 hover 线；中国和中国（台湾）共享高亮组。 |
+| 2.3 | 国界 hover 实线 | `country-boundaries.js` | `hoverAltitudeOffset = 0.14` | `depthTest: false`，禁用 raycast | 霓虹红橘 hover 线；中国和中国（台湾）共享高亮组。 |
 | 3 | 卫星 footprint 填充 | `satellites.js` | `GROUND_FOOTPRINT_RENDER_ORDER` | depth-tested，Group renderOrder 保持 0 | Footprint 在国界线之上，但在算力中心和卫星之下。 |
 | 3-5 | BGP 标记和覆盖层 | `bgp.js` | 各 marker 自身 renderOrder | BGP 拾取路径 | 保持现有 BGP 视觉层级。 |
+| 4.3 | AIS 船只轨迹线 | `vessels.js` | `VESSEL_RENDER_ORDER - 0.1`；`CONFIG.earthRadius + VESSEL_CONFIG.track.altitudeOffset` | 跟随船只显隐，不单独参与拾取 | 选中船只后显示最近轨迹，低于船只 marker。 |
+| 4.4 | AIS 船只 marker | `vessels.js` | `VESSEL_RENDER_ORDER`；`CONFIG.earthRadius + VESSEL_CONFIG.altitudeOffset` | 船只拾取路径；只取正面 marker | 航行船只用三角 sprite，停泊/低速用圆点；低于算力中心 `4.5`。 |
 | 4.5 | 算力中心 | `compute-centers.js` | `COMPUTE_CENTER_RENDER_ORDER` | 算力中心拾取路径 | 地表设施，保持在卫星下方。 |
 | 5 | 卫星背景点 | `satellites.js` | 固定 renderOrder | 屏幕空间卫星拾取 | 位于卫星点下方。 |
 | 6 | 卫星点 | `satellites.js` | 固定 renderOrder | 屏幕空间卫星拾取 | 卫星点压过 footprint 和算力中心。 |
@@ -55,3 +57,4 @@
 | 中国 / 台湾 hover | `CHN` 和 `TWN` 被归到同一个 hover 高亮组；tooltip 仍显示鼠标实际命中的 feature。 |
 | 地形 | 只作为视觉层参与，`terrain.raycast` 已禁用。 |
 | 卫星 | 使用屏幕空间卫星拾取，避免 footprint 或地表层挡住卫星点击。 |
+| 船只 | 使用 sprite marker 拾取，并在 `main.js` 中先过滤正面船只；点击后可加载轨迹线。 |
--- a/docs/technical/zh/earth-satellite-footprint-policy.md
+++ b/docs/technical/zh/earth-satellite-footprint-policy.md
@@ -188,11 +188,3 @@
 - 非 Starlink 的能力判断属于“策略层 / 适配层”
 - 不要把不同星座的覆盖模型再混写进同一套参数里
 - `iridium-next` 已经切成独立 adapter，应继续沿这条边界演进，而不是给现有 Starlink bowtie 增加更多 if/else
-
-## 后续建议
-
-如果继续往前做，推荐顺序是：
-
-1. 为 `iridium-next` 新建独立 footprint adapter
-2. 在 UI 上补一个只读提示，让用户知道当前卫星是否支持 footprint
-3. 如果未来拿到 GEO beam contour / operator metadata，再为 GEO 开 operator-specific footprint
--- a/docs/technical/zh/frontend-admin-frontend-context.md
+++ b/docs/technical/zh/frontend-admin-frontend-context.md
@@ -208,7 +208,7 @@
 - 先通过 port/types 定义边界
 - 再由 http/mock gateway 实现

-## 当前页面分层建议
+## 当前页面分层

 ### 1. 仪表盘和摘要型页面

@@ -237,6 +237,63 @@
 - 不要让表格撑爆整页
 - 新表格区域优先复用 `TableScrollRegion` / `ScrollbarOverlay`

+### 数据源目录页
+
+[DataSources.tsx](/home/ray/dev/linkong/planet/frontend/src/pages/DataSources/DataSources.tsx) 当前不再承担配置编辑职责，而是数据源目录和采集操作页。
+
+当前页面边界：
+
+- 内置数据源和自定义数据源合并为 `UnifiedDataSource`。
+- 列表展示类型、状态、最近运行、采集进度和操作。
+- 点击名称打开只读抽屉。
+- 抽屉中明确显示“内置数据源”或“自定义数据源”。
+- endpoint、headers、config 只展示，不在这里编辑。
+- 需要凭证的采集器提示用户到“设置 -> 采集器设置”维护。
+
+这个边界很重要：后续不要把自定义数据源编辑、内置 endpoint 覆盖或凭证表单再塞回 `/datasources`。这些配置入口统一放在 `/settings?tab=collector_credentials`。
+
+页面顶部的总进度区域新增 `采集中 N` 标签：
+
+- 仅在存在运行中采集任务时显示。
+- 样式定义在 [index.css](/home/ray/dev/linkong/planet/frontend/src/index.css) 的 `data-source-bulk-toolbar__running-pill`。
+- 点击后打开 `采集中任务` Modal。
+- Modal 内展示每个运行任务的阶段、进度、已处理/总数。
+
+这个标签和其他状态标签同排，但通过 hover、蓝色描边和箭头表示可交互，不应改成普通 Tag。
+
+### 采集器设置页
+
+[Settings.tsx](/home/ray/dev/linkong/planet/frontend/src/pages/Settings/Settings.tsx) 中的 `collector_credentials` tab 当前显示为“采集器设置”。
+
+当前页面边界：
+
+- 下拉框选择所有内置采集器。
+- 下拉框右侧只有一个插头图标按钮，用于健康检查。
+- 状态标签在选择器下方展示 `未检查` / `可用` / `不可用`。
+- 需要凭证的采集器将凭证卡片放在基础配置上方。
+- 不需要凭证的采集器只显示基础配置：endpoint、默认 endpoint、请求头、timeout、retry。
+- `BarentsWatch AIS` 使用专用凭证表单。
+
+连接图标使用内联 `PlugConnectIcon`，视觉语义来自 Tabler `plug-connected`。后续如果控制台重写图标体系，应迁移到 Tabler Icons，而不是继续使用 Ant Design 刷新图标表达连接。
+
+`Client Secret` 的表单语义：
+
+- 已配置时，输入框显示脱敏 preview。
+- 聚焦且当前值等于 preview 时清空，方便输入新 secret。
+- 保存时如果值仍等于 preview，提交空值表示保留原 secret。
+- 不再提供单独的“清除当前 secret”复选框。
+
+凭证教程 Modal：
+
+- `GET /api/v1/settings/credential-guides/{provider}` 读取教程。
+- `POST /generate` 调用 AI Provider 重新生成教程。
+- `POST /reset` 恢复默认教程。
+- Modal 使用 `MarkdownRenderer` 渲染教程正文。
+
+相关后端设计见：
+
+- [datasource-collector-settings-connectivity.md](/home/ray/dev/linkong/planet/docs/technical/zh/datasource-collector-settings-connectivity.md)
+
 ### 3. 复杂工作区页面

 例如：
@@ -264,30 +321,3 @@
 详细经验见：

 - [frontend-layout-guidelines.md](/home/ray/dev/linkong/planet/docs/technical/zh/frontend-layout-guidelines.md)
-
-## 当前推荐改动方式
-
-如果后续继续改后台页面，建议按这个顺序：
-
-1. 先确认页面属于摘要页、表格页还是复杂工作区
-2. 先接入现有壳层和滚动语义
-3. 优先复用共享滚动组件
-4. 最后再改视觉和细节交互
-
-不要先写局部 CSS 补丁，再回头补结构。
-
-## 当前明显边界
-
-控制台前端和 Earth 前端不是一套系统：
-
- 控制台前端是 React + Ant Design 工作台
- Earth 前端是 `public/earth` 下的独立原生 HUD 系统
-
-因此：
-
- 不要把 Earth 的 HUD/动画/状态机直接挪进控制台
- 不要把控制台表格/滚动策略硬套到 Earth HUD
-
-Earth 相关结构见：
-
- [earth-frontend-context.md](/home/ray/dev/linkong/planet/docs/technical/zh/earth-frontend-context.md)
--- a/docs/technical/zh/manual.md
+++ b/docs/technical/zh/manual.md
@@ -196,6 +196,7 @@ Earth 用于在一个地球视图中观察：
 - 算力中心
 - BGP 观测
 - 卫星
+- AIS 船只
 - 轨迹
 - 地形

@@ -205,6 +206,31 @@ Earth 用于在一个地球视图中观察：
 - 轨迹依赖卫星
 - 高清材质关闭时，地球会显示基座地图和边缘识别效果

+### 图例
+
+左下角图例会跟随当前聚焦或启用的图层切换。
+
+当前已覆盖：
+
+- 海缆
+- 卫星
+- 国界
+- 算力中心
+- BGP
+- AIS 船只
+
+AIS 船只图例按船型显示颜色：
+
+- 货轮
+- 油轮
+- 客船
+- 渔船
+- 军舰
+- 停泊/低速
+- 其他船只
+
+船只图例中的三角形对应地图上的航行船只标记，圆点对应停泊或低速状态。
+
 ### 搜索

 Earth 搜索支持查找当前地球对象，例如：
@@ -233,6 +259,25 @@ Earth 搜索支持查找当前地球对象，例如：

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

+### 视角控制
+
+Earth 支持鼠标、触控板和触屏操作。
+
+常用控制方式：
+
+| 操作 | 作用 |
+| --- | --- |
+| 鼠标左键拖动 | 旋转地球 |
+| 手指单指拖动 | 在触屏设备上旋转地球 |
+| 鼠标滚轮 | 放大或缩小视角 |
+| 双指捏合 | 在触屏设备上放大或缩小视角 |
+| 缩放按钮 | 按固定步长调整缩放 |
+| 点击缩放百分比 | 重置到默认缩放 |
+
+缩放时，顶部胶囊会短暂显示当前缩放比例，例如 `缩放 180%`。这个提示只表示当前视角缩放，不代表数据加载进度；如果页面正在加载数据，加载提示优先显示，缩放提示不会打断加载状态。
+
+拖动灵敏度会根据当前缩放自动调整。默认视角附近保持常规旋转速度；放大后拖动会逐步变细，适合检查某个区域、船只、卫星或 BGP 事件；缩小后拖动会略快，方便快速浏览全球态势。
+
 ### 巡航模式

 巡航模式会让 Earth 自动轮播聚焦目标。
@@ -308,7 +353,7 @@ http://localhost:3000/admin
 | --- | --- | --- |
 | 仪表盘 | `/admin` | 系统概览 |
 | Earth | `/earth` | 打开公开 Earth 页面 |
-| 数据源 | `/datasources` | 管理数据源和触发采集 |
+| 数据源 | `/datasources` | 查看数据源和触发采集 |
 | 采集数据 | `/data` | 查看采集后的数据 |
 | BGP 观测 | `/bgp` | 查看 BGP 专题数据 |
 | 系统告警 | `/alerts/system` | 系统级告警 |
@@ -321,17 +366,21 @@ http://localhost:3000/admin

 ### 数据源

-`/datasources` 用于查看和管理采集来源。
+`/datasources` 用于查看采集来源和触发采集。当前页面是“数据源目录”，会把内置数据源和自定义数据源放在同一张列表里展示。

 常见操作：

 - 查看数据源状态
 - 触发采集
 - 查看最近采集任务
- 调整配置项
+- 打开详情抽屉查看 endpoint、请求头、基础配置和是否为内置数据源

 如果 Earth 上某类对象缺失，通常先到这里确认数据源是否可用。

+数据源列表中的名称点击后只打开信息抽屉，不再承担编辑入口。接口地址、凭证、请求头和自定义数据源配置统一到 `/settings` 的“采集器设置”里维护。
+
+当有采集任务正在运行时，总体进度下方会出现 `采集中 N` 标签。这个标签和其他状态标签放在同一排，但带有可点击样式；点击后会弹出当前采集中任务列表，显示每个任务的阶段、进度和处理数量。
+
 ### 采集数据

 `/data` 用于查看采集后的数据表。
@@ -369,10 +418,63 @@ http://localhost:3000/admin

 - 系统设置
 - 电视直播源配置
- 数据源相关配置入口
+- 采集器设置
+- 外部集成和 AI Provider 配置

 具体可用配置取决于当前登录用户权限。

+#### 采集器设置
+
+`/settings?tab=collector_credentials` 当前显示为“采集器设置”。这里统一维护所有采集器的连接配置，而不是只维护凭证。
+
+使用方式：
+
+1. 在下拉框选择采集器。
+2. 查看状态标签：
+   - `无需凭证` / `需要凭证`
+   - 所属模块
+   - `启用` / `禁用`
+   - `未检查` / `可用` / `不可用`
+3. 点击下拉框右侧的插头图标执行健康检查。
+4. 如果检查通过，状态会变为 `可用`。
+5. 修改 endpoint、请求头、超时或重试次数后保存。
+
+对于免费且不需要凭证的采集器，连接检查会直接请求对应 endpoint。对于需要凭证的采集器，连接检查会走对应凭证链路；如果凭证或 endpoint 相比上次验证成功时发生变化，需要重新点击连接。
+
+系统判断“已连接”的条件是：
+
+- 当前配置已经成功采集过数据；或
+- 当前配置已经点击过连接按钮并验证成功。
+
+#### BarentsWatch AIS 凭证
+
+`BarentsWatch AIS` 是需要凭证的内置采集器。选择该采集器后，凭证区域会显示在基础配置上方。
+
+配置项：
+
+- `Client ID`
+- `Client Secret`
+- `Endpoint`
+
+如果已经配置过 secret，输入框会显示脱敏预览。保存时如果保持这个脱敏预览不变，系统会保留原 secret；只有输入新的 secret 才会替换。
+
+BarentsWatch AIS 支持从以下位置读取凭证：
+
+1. 控制台采集器设置中保存的凭证。
+2. 后端环境变量：
+   - `BARENTSWATCH_CLIENT_ID`
+   - `BARENTSWATCH_CLIENT_SECRET`
+   - 兼容历史拼写：`BARRENTSWATCH_CLIENT_ID`、`BARRENTSWATCH_CLIENT_SECRET`
+3. `~/.zshrc` 中的同名 `export`。
+
+如果连接失败，页面会弹出凭证获取教程。教程支持：
+
+- 查看默认教程。
+- 点击“教程不好用”让 AI Provider 根据默认 prompt 重新生成教程。
+- 点击“重置”恢复默认教程。
+
+默认教程以 BarentsWatch 官方 tutorial 为准，并提醒 Live AIS 应选择 `AIS - API`，不是普通 `BarentsWatch - API`。
+
 ### 系统日志

 `/logs` 用于查看系统日志。若菜单中不可见，通常是当前用户角色没有权限。
@@ -397,7 +499,8 @@ http://localhost:3000/docs
 当前公开内容来自：

 ```text
-docs/technical/*.md
+docs/technical/zh/*.md
+docs/technical/en/*.md
 ```

 Docs 支持：
@@ -486,3 +589,4 @@ source ~/.zshrc && bun run build
 - [earth-layer-style-reference.md](/home/ray/dev/linkong/planet/docs/technical/zh/earth-layer-style-reference.md)
 - [backend-system-service-control.md](/home/ray/dev/linkong/planet/docs/technical/zh/backend-system-service-control.md)
 - [backend-collectors.md](/home/ray/dev/linkong/planet/docs/technical/zh/backend-collectors.md)
+- [datasource-collector-settings-connectivity.md](/home/ray/dev/linkong/planet/docs/technical/zh/datasource-collector-settings-connectivity.md)
--- a/docs/technical/zh/quickstart.md
+++ b/docs/technical/zh/quickstart.md
@@ -73,6 +73,7 @@ Earth 是公开页面，不需要登录。
 - 地球正常显示
 - 右侧图层控制可打开/关闭图层
 - 搜索可以查找海缆、卫星、算力中心、BGP 事件
+- 鼠标拖动、滚轮缩放和缩放百分比提示正常工作
 - 设置面板可以切换巡航模式、日夜模式、卫星显示风格

 ## 4. 打开控制台
@@ -87,7 +88,7 @@ http://localhost:3000/admin

 首次排查建议查看：

- `/datasources`：数据源配置和采集状态
+- `/datasources`：数据源目录和采集触发；接口、请求头和凭证配置在 `/settings` 的“采集器设置”
 - `/data`：已采集数据
 - `/bgp`：BGP 专题观测
 - `/alerts/system`：系统告警