Doni/safesight-control
6
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
96e689fec0
safesight-control/docs/superpowers/specs/2026-04-29-third-party-services-design.md

8.9 KiB
Raw Blame History

第三方服务结构化设计

背景

当前后台已经将配置相关能力拆分为两层：

  • 场景配置：定义一个最终要运行的业务场景
  • 基础配置：承载场景配置引用的公共配置

在现有项目中，第三方服务相关配置仍然散落在模板参数中，没有独立的结构和复用关系。当前已确认存在的第三方服务参数包括：

  • 对象存储：minio_endpoint、minio_bucket、minio_access_key、minio_secret_key
  • 认证服务：external_get_token_url
  • 告警服务：external_put_message_url
  • 租户字段：tenant_code

这些配置本质上不是某个单独场景私有的内容，而是会被多个场景反复引用的基础服务配置。继续把它们直接放在模板或场景参数里，会带来几个问题：

  • 相同服务地址和密钥在多个场景中重复填写
  • 修改服务地址或凭据时，需要逐个场景同步修改
  • 难以判断某个第三方服务被哪些场景使用
  • 服务配置与识别模板逻辑混在一起，页面职责不清楚

因此，这一轮设计的目标是把“第三方服务”独立为一类可复用的基础配置。

目标

本次设计只解决下面这些问题：

  1. 为第三方服务建立统一、结构化的数据模型
  2. 在 基础配置 中提供独立的 第三方服务 管理入口
  3. 让 场景配置 通过引用第三方服务完成配置，而不是直接填写服务参数
  4. 在生成最终 agent 配置时，将服务引用展开为现有模板参数

非目标

本次不包含以下内容：

  • 不引入多环境字段，如 prod / test
  • 不引入适用范围字段，如客户 / 项目 / 站点
  • 不做复杂权限模型
  • 不做服务连通性探测
  • 不做密码加密存储方案升级
  • 不支持自定义服务类型

第一版只覆盖项目中已经真实存在的三类第三方服务。

服务类型

第一版支持以下三种服务类型：

  1. object_storage：对象存储
  2. token_service：认证服务
  3. alarm_service：告警服务

页面文案使用中文：

  • 对象存储
  • 认证服务
  • 告警服务

数据模型

顶层公共字段

所有第三方服务共享以下字段：

  • name：服务名称，唯一标识
  • type：服务类型
  • description：描述
  • enabled：是否启用
  • config：按服务类型存储的结构化字段

推荐的数据结构如下：

{
  "name": "minio_prod_main",
  "type": "object_storage",
  "description": "主对象存储",
  "enabled": true,
  "config": {
    "endpoint": "http://10.0.0.49:9000",
    "bucket": "myminio",
    "access_key": "admin",
    "secret_key": "password"
  }
}

这种设计的关键点是：

  • 顶层字段保持简单，便于列表展示和统一管理
  • 类型差异收纳在 config 中，避免一张平表容纳所有服务字段
  • 后续增加新服务类型时，不需要推翻已有结构

类型字段

对象存储

字段：

  • endpoint
  • bucket
  • access_key
  • secret_key

认证服务

字段：

  • get_token_url
  • username
  • password
  • tenant_code

告警服务

字段：

  • put_message_url
  • username
  • password
  • tenant_code

与现有模板参数的映射

为了兼容当前 agent 模板，第三方服务字段需要在预览和下发阶段映射回模板参数。

映射关系如下：

对象存储

  • config.endpoint -> minio_endpoint
  • config.bucket -> minio_bucket
  • config.access_key -> minio_access_key
  • config.secret_key -> minio_secret_key

认证服务

  • config.get_token_url -> external_get_token_url
  • config.tenant_code -> tenant_code

告警服务

  • config.put_message_url -> external_put_message_url
  • config.tenant_code -> tenant_code

说明：

  • username 和 password 在第一版中先作为结构化存储字段保留
  • 是否映射到模板参数，取决于具体模板是否已经定义对应参数
  • 如果当前模板没有用到用户名和密码，这两个字段暂时只在后台维护，不强制写入模板参数

场景配置中的引用方式

场景配置不再直接保存第三方服务的 URL、密钥和租户字段，而是保存服务引用。

建议增加以下引用字段：

  • object_storage_ref
  • token_service_ref
  • alarm_service_ref

示例：

{
  "object_storage_ref": "minio_prod_main",
  "token_service_ref": "token_service_prod",
  "alarm_service_ref": "alarm_center_prod"
}

这样做的好处是：

  • 多个场景可以复用同一组基础服务
  • 修改服务地址或凭据时，无需逐个调整场景
  • 后台可以反查“某个服务被哪些场景引用”
  • 场景配置页面更聚焦于业务场景本身，而不是堆满连接参数

预览与下发的数据流

生成最终 agent 配置时，数据流按以下顺序处理：

  1. 读取场景配置
  2. 解析场景中引用的第三方服务名称
  3. 加载对应第三方服务配置
  4. 按服务类型展开为模板参数
  5. 合并模板默认参数、场景参数、调试参数和第三方服务参数
  6. 生成最终配置预览或下发内容

参数优先级建议保持清晰：

  1. 模板默认参数
  2. 场景配置显式参数
  3. 第三方服务展开参数
  4. 调试参数覆盖

如果同名字段冲突，后面的层级覆盖前面的层级。

存储设计

后台当前 assets_repo 已经持久化模板、场景配置和调试参数。第一版建议延续这个模式，为第三方服务新增独立存储。

建议新增一类持久化对象：

  • 表名可使用 integration_services

每条记录至少包含：

  • name
  • type
  • description
  • enabled
  • config_json
  • created_at
  • updated_at

其中 config_json 保存类型字段。

这样可以避免在数据库层为三类服务各建一张表，保持实现简单，同时保留后续扩展空间。

后端结构建议

建议在服务层新增一个明确模型，例如：

type ThirdPartyServiceAsset struct {
    Name        string
    Type        string
    Description string
    Enabled     bool
    Config      map[string]any
}

如果后续需要更强约束，可以进一步拆出按类型的辅助结构，但第一版不必过度设计。

建议新增以下能力：

  • 列表读取
  • 单项读取
  • 新建 / 编辑 / 删除
  • 引用计数查询
  • 按场景展开为模板参数

UI 设计

入口位置

主入口保持在：

  • 基础配置 -> 第三方服务

列表页

列表页先展示最重要的信息，字段建议如下：

  • 服务名称
  • 服务类型
  • 描述
  • 地址摘要
  • 启用状态
  • 引用数量

地址摘要按类型生成：

  • 对象存储：显示 endpoint / bucket
  • 认证服务：显示 get_token_url
  • 告警服务：显示 put_message_url

这样用户可以快速判断服务是做什么的，以及是否大致配置正确。

详情 / 编辑页

详情和编辑页分为两块：

  1. 基本信息

    • 名称
    • 类型
    • 描述
    • 启用状态

  2. 服务配置

    • 根据服务类型显示不同字段

字段展示规则：

  • 密码和 secret_key 默认掩码显示
  • 列表页不展示敏感字段
  • 类型切换时动态切换表单字段

校验规则

通用校验

  • 名称不能为空
  • 名称必须唯一
  • 类型不能为空

对象存储校验

  • endpoint 必填
  • bucket 必填
  • access_key 必填
  • secret_key 必填

认证服务校验

  • get_token_url 必填
  • tenant_code 可选
  • username、password 可选

告警服务校验

  • put_message_url 必填
  • tenant_code 可选
  • username、password 可选

删除与引用约束

第三方服务被场景配置引用时，不应允许直接删除。

删除前需要检查：

  • 是否有场景配置正在引用该服务

如果存在引用，应提示：

  • 当前服务已被某些场景配置使用，不能删除

这与模板删除前检查引用的现有交互保持一致。

第一阶段实施范围

第一阶段只实现以下能力：

  1. 第三方服务的数据结构和存储
  2. 基础配置 -> 第三方服务 列表与详情编辑
  3. 场景配置对第三方服务的引用
  4. 配置预览与下发时的参数展开
  5. 删除前引用检查

后续扩展方向

本设计为后续扩展保留空间，但不在第一阶段实现：

  • 新增更多服务类型，如 MQTT、Kafka、Webhook
  • 服务连通性测试按钮
  • 敏感字段加密存储
  • 按客户或项目进行服务分组
  • 服务变更审计

结论

第三方服务应当被视为一类可复用的基础配置，而不是模板参数的零散集合。

通过引入独立的第三方服务结构：

  • 可以降低场景配置的重复录入
  • 可以集中管理 URL、租户和凭据
  • 可以让模板、场景和服务的职责分离
  • 可以为后续更完整的配置治理打下基础

第一版只支持对象存储、认证服务、告警服务三类，已经足够覆盖当前项目里的真实需求，并且能与现有 agent 模板参数平滑兼容。