WddSuperAgent/1-designs/WddSuperAgent-DDS.md

WddSuperAgent DDS（现代化改造草案）

背景与总体目标

• WddSuperAgent 由多个 Go 模块组成：agent-wdd（通用 CLI 工具）、agent-common（工具库/常量/镜像命名转换等）、agent-deploy（K8s 部署模板生成）、agent-operator（运维中枢：镜像同步、K8s 操作、Harbor/MinIO 交互）。目前模块耦合度高、流程以脚本式函数为主，缺少统一 API 与测试保障。
• 目标：以“运维服务化”为方向，引入 Gin 提供标准接口，按领域拆分服务层/适配层，完善配置、安全与测试体系，并为后续 UI/自动化编排提供稳定基础。

现状梳理（按模块）

• agent-common：提供 logger、断言、文件/字符串等工具，镜像命名转换（image 包）、项目镜像列表（real_project/*），缺少接口抽象和错误语义。
• agent-deploy（依赖 agent-common）：生成/应用 CMII 相关的 K8s 资源模板（Dashboard、NFS、Middlewares、App、Ingress、Env Config），通过 CommonEnvironmentConfig 拼装 YAML/Apply 文件；存在大量硬编码路径与全局变量。
• agent-operator（依赖 agent-common、agent-deploy）：运维中枢，职责包含：
  • 镜像同步 DCU/DLTU 流程（CmiiImageSyncOperator）：Download → Compress → Upload/Push；支持从 Demo/RKE/Middle/版本号拉取，MinIO 上传，Harbor 直推（tag + push）。
  • Docker/Harbor/MinIO 适配（image、minio 包），K8s 适配（CmiiK8sOperator，Deployment/Pod/Node 的查询、缩容、重启、打 tag 等），部分函数含硬编码认证信息。
  • main 以交互式模式运行（mode=image/operator），无 HTTP API，流程控制与状态管理零散。
• agent-wdd（独立）：Cobra CLI 瑞士军刀（zsh、proxy、acme、Cloudflare、host info 等），与 CMII 运维解耦。

关键现有流程

• 镜像同步（DCU/DLTU）：ImageSyncEntity 描述 Download/Compress/Upload 条件，A_DownloadCompressUpload 执行拉取→压缩→上传，A_DownloadLoadTagUpload 负责离线包加载+重 tag + 推送；大量文件系统操作与全局路径（OfflineImageGzipFolderPrefix）。
• K8s 操作：CmiiK8sOperator 封装 client-go，基于 namespace 切换进行 Deployment/StatefulSet/Pod/Node 的查询、扩缩容、重启、删 pod/evict 等。
• 部署生成：OctopusDeploy 依靠模板包组合环境，按镜像 map 生成并 apply。

主要痛点

• 架构层次不足：领域逻辑、基础设施操作、流程编排混杂在同一包内；全局变量与硬编码路径/凭据多。
• 可测试性弱：测试多为打印/人工验证，SaveImageListToGzipFile 等函数甚至返回 stub；缺少接口注入、mock 与集成回归。
• 接口形态单一：仅 CLI/交互模式，缺少 HTTP API/任务编排，不利于自动化或 UI 集成。
• 配置与安全：凭据明文/硬编码（Harbor RegistryAuth、kubeconfig 路径等），无统一配置加载与密钥管理。
• 可靠性/可观察性：缺少健康探针、审计日志、指标/追踪；IO/网络无超时控制，错误语义不清晰。

目标架构（分层与模块化）

• 项目结构（示例）

  /cmd/operator (HTTP + CLI 入口)
  /cmd/wdd      (保留独立 CLI)
  /pkg/domain   (实体与用例协议：ImageSyncSpec、DeployPlan、ClusterTarget 等)
  /pkg/service  (应用层：ImageSyncService、DeployService、K8sService、RegistryService、StorageService)
  /pkg/infra    (适配层：Docker/Harbor client、MinIO client、K8s client、Template renderer、Config)
  /pkg/transport/http (Gin handler，DTO 校验，统一响应)
  /pkg/transport/cli  (Cobra 命令适配，复用同一 service)
  /pkg/obs      (日志/指标/追踪/审计)
  /configs      (环境化配置，区分 dev/test/prod)
  

• 依赖关系：transport -> service -> infra，domain 为纯模型；agent-wdd 继续独立，但可共用 pkg/infra 的下载/文件工具。
• 并发/任务模型：对长耗时的镜像同步/压缩/上传采用异步任务（队列或 goroutine + work pool），任务状态持久化（可选 Bolt/SQLite/Redis），Gin 提供查询/取消接口。

组件设计与接口草案

• Domain 模型
  • ImageSyncSpec：源列表（cmiiNameTags/fullNames/projectVersion/sourceAuth）、压缩策略（split/monolithic、目标目录）、上传策略（minio bucket/oss prefix）、推送策略（target harbor/cred）、更新策略（是否更新集群 tag）。
  • DeployPlan：目标集群/namespace、镜像 map、模板参数（NFS/Ingress/SRS 等）。
  • ClusterTarget：kubeconfig/上下文/namespace，执行策略（超时、并发度）。
• Service 层
  • ImageSyncService：封装 Download→Compress→Upload→Push，用接口注入 RegistryClient、StorageClient、Compressor、ImageNamer；支持幂等与断点续跑（跳过已存在 gzip）。
  • DeployService：生成/渲染/Apply K8s 清单；可选 dry-run；依赖 K8sApplier（kubectl/go-client）。
  • K8sService：Deployment/StatefulSet/Pod/Node 读写操作，暴露给 HTTP/CLI；支持批量重启/cordon/evict。
  • ConfigService：集中配置加载（Viper），支持 env 覆盖与 secret 挂载。
  • ObsService：日志封装（zap sugared logger）、Prometheus 指标（请求量/耗时/失败率/队列长度）、OpenTelemetry trace。
• Transport（Gin）
  • /api/v1/images/sync POST：提交 ImageSyncSpec，返回任务 id。
  • /api/v1/images/tasks/:id GET：查询任务状态/日志片段。
  • /api/v1/registry/push POST：源→目标 Harbor 的 tag/push。
  • /api/v1/deploy/apply POST：提交 DeployPlan，可选择 dryRun。
  • /api/v1/k8s/deployments/:ns/:name/tag PUT：更新镜像 tag。
  • /api/v1/healthz、/metrics：健康检查与指标暴露。
• CLI（Cobra）
  • 复用同一 service：wdd image sync ...，wdd deploy apply ...，与 HTTP 行为保持一致。

关键改造点与落地方案

• 解耦与接口化：为 Docker/Harbor/MinIO/K8s 定义接口（RegistryClient, StorageClient, K8sClient），在服务层通过依赖注入；现有实现迁移至 infra，便于 mock。
• 配置/密钥：移除硬编码（RegistryAuth、kubeconfig 路径等），采用 configs/*.yaml + 环境变量覆盖；敏感信息通过文件挂载或 Secret 管理，Gin 层仅传递引用。
• 路径与存储：统一离线镜像根路径（可配置），将 txt/gzip 列表输出迁移到任务上下文目录；为分片压缩/单包压缩提供策略接口。
• 错误与重试：下载/上传/推送增加上下文超时与可配置重试；对局部失败的镜像保留失败列表与诊断信息。
• 并发与资源控制：镜像拉取/压缩采用 worker pool（并发上限可配置），避免当前全局 goroutine + 共享 slice 可能的竞态。
• 可观察性：统一日志格式；Gin middleware 注入 request-id；暴露 Prometheus 指标与 pprof；长任务输出阶段进度。
• 安全：移除代码中的 base64 凭据；K8s 操作增加 RBAC 范围与 kubeconfig 选择；上传/下载校验 hash（md5/sha256）。
• 兼容性：保留现有 DCU/DLTU 能力，通过 CLI 子命令封装新的 service，实现“新 API + 旧脚本可用”。

测试与质量保障

• 单元测试：引入 testify/gomock，对核心服务（ImageSyncService/K8sService/DeployService）做 mock 测试；覆盖命名转换、列表生成、失败分支。
• 集成测试：使用 kind + 本地 registry（或 test Harbor mock）、本地 MinIO 容器，跑镜像下载→压缩→推送→K8s apply 的端到端流程；提供 make test-integration。
• 契约测试：Gin API 使用 httptest 覆盖请求校验/错误码；CLI 使用 golden 测试。
• 静态检查：启用 golangci-lint（vet, ineffassign, errcheck, revive），go test ./... 作为最小门槛。

迁移路线（建议三步）

1. 基础设施抽象：提炼 Registry/K8s/Storage/Compressor 接口，将现有实现迁入 pkg/infra，补齐 SaveImageListToGzipFile 等 stub，清理硬编码凭据/路径。
2. 服务化与测试: 新建 pkg/service，重写 DCU/DLTU 流程为可注入的 ImageSyncService；构建 Gin 入口与 API DTO，补足单元/集成测试与 CI 流水线。
3. 运维增强: 引入任务队列/状态持久化、指标/日志/trace，完善 K8s 操作 API，逐步替换旧 CLI 逻辑为 service 调用，并整理配置与文档。

成功度量

• 关键流程 API 化：镜像同步/推送、部署 apply、K8s tag 更新均有 Gin 接口与 CLI 对应子命令。
• 质量门槛：go test ./... 绿色，集成测试可在本地 one-command 运行；lint 无高危告警。
• 运维可用性：无硬编码密钥，配置可按环境切换；指标可在 Prometheus 抓取，健康检查可被 K8s 探针消费。