大量的更新工作

1-designs/1-改造计划.md

@@ -0,0 +1,11 @@
+
+agent-deploy的核心定位是
+1. 自己实现的的HELM工具 用于管理CMII的部署YAML文件
+2. 生成完整的部署 YAML 文件
+    1. 中间件
+    2. k8s-dashboard
+    3. CMII业务部署的YAML文件
+3. 提供API接口
+    1. 提供特定YAML的生成接口
+4. 业务部署参数
+    1. 所有部署的中间件参数应该被提取出来，统一管理

1-designs/WddSuperAgent-DDS.md

@@ -0,0 +1,90 @@
+# 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 探针消费。
+