planet/docs/technical/zh/datasource-collector-settings-connectivity.md

采集器设置与连接验证

背景

控制台现在把“数据源目录”和“采集器配置”拆开：

• /datasources
  • 展示所有数据源，包括内置和自定义。
  • 点击名称只打开信息抽屉。
  • 负责查看状态、触发采集和查看采集中任务。
• /collection-management?tab=collector_credentials
  • 显示为“采集器”。
  • 负责 endpoint、请求头、基础参数和凭证配置。
  • 所有采集器都提供连接按钮，用于健康检查。

这样做是为了减少首次使用时的认知分裂：接口地址、请求头、凭证和自定义源配置都属于“采集器”，而不是散落在数据源列表和系统设置多个入口里。

用户侧规则

连接状态不是前端样式状态，而是由后端根据配置 checksum 和已验证记录判断。

一个内置采集器被视为“已连接”需要满足任一条件：

• 当前配置已经成功采集过数据。
• 当前配置点击过连接按钮，并且后端验证成功。

如果 endpoint、请求头、基础配置或凭证指纹相对上次验证成功时发生变化，状态会回到“需要重新连接”。

前端入口

数据源目录

文件：

• PlainResourcePages.tsx
• AdminRoutes.tsx

当前行为：

• 内置数据源和自定义数据源合并为 UnifiedDataSource 列表。
• 表格只保留查看、采集和状态类操作。
• 名称点击打开只读抽屉。
• 抽屉中展示：
  • 是否内置
  • 是否启用
  • 模块、优先级、频率
  • endpoint
  • 请求头
  • 基础配置
  • 是否需要凭证
• 有任务运行时，顶部进度区显示 采集中 N 可点击标签。
• 点击 采集中 N 打开任务列表弹窗，显示各任务进度。

data-source-bulk-toolbar__running-pill 是“采集中”标签的样式入口。它和其他状态标签同排，但通过 hover、箭头和蓝色描边表达可交互性。

采集管理

文件：

• PlainResourcePages.tsx

当前行为：

• /collection-management 按业务层级收敛为 采集器、采集调度、采集历史 / 快照。
• 采集器 是配置页，左侧列表展示采集器配置；右侧表单编辑 endpoint、认证、请求头、采集参数和启用状态。
• 新增采集器和目标 Schema 使用草稿详情页，不再用透明 JSON 弹窗；保存后才固化到列表，取消会销毁草稿。
• 连接按钮只做连通性测试，不保存配置；保存按钮只持久化表单。
• 凭证教程以可拖拽 Markdown 弹窗展示。没有教程时仍打开弹窗并提供生成入口；生成时显示中心等待状态；重置确认层级必须高于教程弹窗。
• 采集历史 / 快照 按采集器聚合。列表不再重复展示同一数据源的所有快照；详情页内部用 Time Capsule / Time Machine 式选择器切换快照版本。
• AISStream 采集器使用 WebSocket 语义，状态会显示为连接中、实时接收、重连或停止，不使用固定百分比表达完成度。
• 自定义源入口放在采集器设置内，不在数据源目录里重复提供编辑入口；数据源目录只保留总览、运行和只读抽屉。

连接按钮使用内联 Tabler 风格插头图标，来源语义对应 plug-connected，避免继续使用刷新图标表达连接动作。

映射模板和目标 Schema

映射能力仍属于采集管理，但不是采集器主 tab：

• 映射模板 承担 sample payload、AI propose、preview、create/update、activate。
• 目标 Schema 维护可写入目标结构。
• run-mapped、stop-mapped、stream-status 负责运行映射后的自定义采集器。

这些入口在 Admin 中需要表单化，只有高级字段才折叠为 JSON。不要把模板、Schema、运行状态和采集器配置拍平成同一张表。

后端接口

数据源配置列表

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 返回前会移除内部连接验证字段，避免前端把校验元数据当成用户配置展示。

内置采集器连接状态

POST /api/v1/datasources/configs/builtin/connection-status

用途：

• 给定一份候选配置。
• 计算 checksum。
• 判断当前配置是否已经连接。

当前前端主要通过连接按钮即时检查，不强依赖这个接口，但它是后续保存按钮置灰、页面初始化状态恢复的后端依据。

内置采集器连接验证

POST /api/v1/datasources/configs/builtin/connect

用途：

• 免费采集器直接请求 endpoint。
• 需要凭证的采集器走对应 credential provider。
• 验证成功后写入系统级连接记录。

成功返回中会带：

• success
• connected
• checksum
• stage
• message
• response_time_ms
• credential_provider
• credential_source

凭证教程

GET  /api/v1/datasources/credential-guides/{provider}
POST /api/v1/datasources/credential-guides/{provider}/generate
POST /api/v1/datasources/credential-guides/{provider}/reset

用途：

• 读取当前 provider 的 Markdown 凭证教程。
• 没有教程时，由 AI 根据采集器元数据生成教程。
• 重置时恢复后端默认教程。

前端展示规则：

• 展示渲染后的 Markdown，不展示后端 prompt 或元数据。
• 生成/重置是教程弹窗内部动作，不放在采集器配置主工具栏。
• 没有教程也要打开弹窗，让用户能从弹窗里生成教程。

BarentsWatch AIS 连接验证

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

核心职责：

• 计算内置采集器配置 checksum。
• 读取环境变量和 ~/.zshrc 中的凭证。
• 判断当前配置是否已连接。
• 执行 endpoint 健康检查。
• 保存连接成功记录。

checksum 组成

checksum 包含：

• 采集器名称
• endpoint
• auth type
• headers
• 去掉内部校验字段后的 config
• credential provider
• 凭证指纹

凭证指纹使用凭证内容 hash，不把明文凭证写入连接记录。

连接记录

连接成功记录写入 SystemSetting：

category = datasource_connectivity_validations

payload 以采集器 source 为 key：

{
  "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

这样已有数据的采集器不会要求用户重复验证。只有当配置 checksum 变化时，才需要重新点击连接。

BarentsWatch AIS 凭证链路

文件：

• barentswatch.py
• vessel_ais.py

解析优先级：

1. DataSourceConfig.auth_config
2. DataSourceConfig.config
3. 环境变量
4. ~/.zshrc

支持的环境变量：

export BARENTSWATCH_CLIENT_ID="..."
export BARENTSWATCH_CLIENT_SECRET="..."

也兼容历史拼写：

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()，避免设置页、连接验证和采集器三套凭证逻辑分叉。

AISStream 采集器链路

文件：

• aisstream.py
• vessel_ais_aggregation.py

AISStream 使用 WebSocket 实时流，采集器只写入 ais_raw_observations 原始观测层，不直接覆盖最终船只展示表。聚合接口负责多源去重、字段选择和冲突记录。

配置项：

• api_key：保存在 DataSourceConfig.auth_config，也可用环境变量 AISSTREAM_API_KEY。
• endpoint：默认 wss://stream.aisstream.io/v0/stream。
• message_types：默认 PositionReport 和 ShipStaticData。
• bounding_boxes：AISStream 格式为 [[[lat_min, lon_min], [lat_max, lon_max]]]，设置页提供全球、挪威 / 北海、欧洲近海、东亚、北美东西海岸 preset。
• max_messages 和 receive_timeout_seconds：控制单次批次式 WebSocket 采集窗口。

标准化规则：

• PositionReport 主要提供位置、速度、航向和状态。
• 船名可以从 MetaData.ShipName 补入，即使消息体本身没有 name。
• 船型通常来自低频 ShipStaticData.Type；后端会把 AIS 数字类型码映射为 Cargo / Tanker / Passenger / Fishing / Military。
• 如果某艘船尚未收到静态消息，聚合结果的船型仍可能是 Other，后续由 v5 船舶资料 enrichment 补齐。

连接验证会读取保存配置、环境变量和 ~/.zshrc 中的 AISSTREAM_API_KEY。正式采集时，推荐把 API Key 保存到采集器设置；如果只写在 ~/.zshrc，需要确认后端进程实际继承了该变量，否则连接验证可能可用但 collector 运行时拿不到 key。

连接验证和正式采集是两个不同动作。设置页出现 AISStream 凭证已配置，WebSocket endpoint 格式有效 只说明配置可以用于连接；运行状态仍可能是 disconnected。只有 aisstream_vessels 处于 streaming / connected，并且实时流计数、last_seen_at 持续更新时，全球 AIS 数据才会不断写入本地库。启动、停止、重连、健康状态和计数统一从 /datasources -> 实时流 和 /api/v1/realtime-sources 查看；AISStream 不再参与普通一键采集进度。

新版本不再使用 legacy /api/v1/visualization/geo/vessels 作为船只列表入口。Earth 初始状态应调用：

GET /api/v1/vessels/snapshot?bbox=lon_min,lat_min,lon_max,lat_max&zoom=12&limit=1000

该接口优先查询本地 ais_raw_observations 聚合结果；当当前 raw 窗口为空时，会受控回退到 legacy vessel_position / vessel_static 最新点，并通过 diagnostics.legacy_fallback_used 暴露。实时更新走 /ws 的 vessels channel，订阅时必须提供 bbox、zoom 和 limit。服务端按连接过滤 bbox，并对 collector 广播做 1 秒合并，同一 MMSI 只推送最新位置。

自定义 REST / WebSocket 映射运行时

文件：

• custom_datasource_runtime.py
• datasource_mapping.py

自定义源现在不是独立的新数据孤岛，而是作为内置数据源的补充源写入目标 schema。当前最完整的目标是 vessel_ais：自定义 REST 或 WebSocket 源经过确定性 mapping 后写入 AIS raw observations，再通过 vessels WebSocket channel 推送给 Earth。

智能星球高精度边界不再使用自定义源目标 schema。国界是智能星球静态资产，由控制台 运维与配置 -> 智能星球内容 -> 国界精度 保存本机源配置并触发 PMTiles 构建，不写入 CollectedData。

配置语义

关键字段：

• source_type：rest / http / websocket / ws。
• endpoint：REST 使用 http(s)://，WebSocket 使用 ws(s)://。
• auth_type：none、bearer、api_key、basic。
• headers：静态请求头。
• auth_config：token、API key、basic 用户名密码，API key 支持 header 或 query。
• config.target_schema：例如 vessel_ais、geo_points 或 generic_records。
• config.delivery_mode：REST 默认 polling，WebSocket 默认 realtime_stream。
• config.merge_target_source：记录该自定义源补充哪个内置数据，例如 barentswatch_vessels。

REST runner 支持：

• GET / POST
• query params
• JSON body
• headers 和 auth 注入
• active mapping 写入目标 schema

WebSocket runner 支持：

• endpoint 格式校验
• headers 和 auth 注入
• 可选 ws_subscribe_message
• ws_message_path / ws_items_path 提取消息主体或数组
• 断线重连
• debug_max_messages 调试上限
• 后台 stream start / stop / status

相关 API：

POST /api/v1/datasources/custom/sample
GET  /api/v1/datasources/target-schemas
POST /api/v1/datasources/{config_id}/run-mapped
POST /api/v1/datasources/{config_id}/stop-mapped
GET  /api/v1/datasources/{config_id}/mapped-status
DELETE /api/v1/datasources/configs/{config_id}?delete_mappings=true&delete_source_data=true

run-mapped?background=true 只对 WebSocket 源有意义，会启动后台 stream。REST 源仍是一次性采集。

删除与数据清理

删除自定义源时有三种层级：

• 只删除配置：保留 mapping 和历史数据。
• 删除配置和 mapping：同时删除该配置的 mapping 模板。
• 删除配置、mapping 和该源数据：删除该源写入的 collected_data、ais_raw_observations 和 ais_source_health。

如果删除的是 vessel_ais 自定义源数据，后端会向 vessels channel 广播 reload_required，提示 Earth 重新拉取船只聚合结果。legacy vessel_position 不按自定义源直接删除，因为它没有可靠的 source 归因。

本地 AIS mock WebSocket

文件：

• mock-ais-ws-server.ts

运行方式：

bun run mock:ais-ws

mock 服务持续发送 AIS-like JSON，用于验证“WebSocket 自定义源 -> mapping -> AIS raw observation -> vessels channel -> Earth 船只 upsert”链路。典型配置：

{
  "source_type": "websocket",
  "endpoint": "ws://localhost:8787",
  "config": {
    "target_schema": "vessel_ais",
    "delivery_mode": "realtime_stream",
    "merge_target_source": "barentswatch_vessels",
    "ws_message_path": "$.data",
    "ws_items_path": "$.vessels[*]",
    "ws_reconnect": true
  }
}

凭证教程

文件：

• credential_guides.py

接口：

GET  /api/v1/settings/credential-guides/{provider}
POST /api/v1/settings/credential-guides/{provider}/generate
POST /api/v1/settings/credential-guides/{provider}/reset

当前支持：

• barentswatch
• aisstream

默认教程包含 BarentsWatch 官方 tutorial 地址：

https://developer.barentswatch.no/docs/tutorial

如果用户点击“教程不好用”，后端会把默认 prompt 发给 AI Provider 生成新的中文教程，并保存到 SystemSetting：

category = collector_credential_guides

“重置”会删除自定义教程，恢复默认教程。

保存规则

内置采集器配置保存时会移除内部 connectivity_validation 字段，避免校验状态跟用户配置混在一起。

BarentsWatch client_secret 保存时有特殊处理：

• 输入框显示脱敏预览。
• 如果提交值仍等于脱敏预览，后端保留原 secret。
• 如果输入新值，才替换 secret。
• 不再提供单独“清除当前 secret”复选框。

测试覆盖

相关测试：

• test_vessels.py

新增覆盖：

• 能从 ~/.zshrc 解析 BarentsWatch 凭证。
• 环境变量为空时，resolve_barentswatch_config() 能回退到 ~/.zshrc。
• 船只数据转换和 GeoJSON 输出保持兼容。

当前 Provider 覆盖

当前已经支持的凭证 provider：

• barentswatch
• aisstream
• spacetrack

其他 requires_credentials=true 的采集器如果还没有 provider，会返回“凭证链路尚未接入”，前端显示 不可用。