ocdp-go/backend/docs/architecture.md

🏗️ 架构文档

目录

• 2.1.1 需求描述
  • 项目背景
  • 核心需求
  • 功能需求
  • 非功能需求
• 2.1.2 业务建模
  • 业务领域
  • 核心实体
  • 业务流程
  • 用例场景
• 2.1.3 技术建模
  • 2.1.3.1 六边形架构
  • 2.1.3.2 技术选型

---

2.1.1 需求描述

项目背景

问题陈述

在云原生时代，Kubernetes 已成为容器编排的事实标准，Helm 是 Kubernetes 的包管理工具。然而，当前企业在使用 Helm 进行应用部署时面临以下挑战：

1. 多集群管理复杂 - 企业通常有多个 Kubernetes 集群（开发、测试、生产），需要统一的管理界面
2. 制品仓库分散 - Helm Chart 可能分布在多个 OCI Registry（Harbor、Docker Hub、GHCR）中，难以统一浏览
3. 部署流程繁琐 - 需要手动编写 helm install 命令，配置复杂的 values.yaml
4. 缺乏可视化 - 命令行操作对非技术人员不友好，缺少直观的 UI
5. 版本管理困难 - 应用升级需要记住历史版本，容易出错
6. 监控信息分散 - 需要单独访问 Kubernetes Dashboard 查看应用状态

解决方案

OCDP Backend 提供统一的后端 API 服务，实现：

• ✅ 统一管理 - 集中管理多个 Kubernetes 集群和 OCI Registry
• ✅ 可视化部署 - 通过 API 简化 Helm Chart 的浏览和部署流程
• ✅ 版本控制 - 完整的应用生命周期管理（安装、升级、卸载）
• ✅ 实时监控 - 集成 Kubernetes API，实时获取应用状态和资源使用情况
• ✅ 安全认证 - 支持用户认证和敏感数据加密存储

---

核心需求

业务需求

需求 ID	需求描述	优先级
BR-001	支持管理多个 Kubernetes 集群	P0
BR-002	支持管理多个 OCI Registry	P0
BR-003	浏览和搜索 Helm Chart 制品	P0
BR-004	部署 Helm Chart 到 Kubernetes 集群	P0
BR-005	升级已部署的应用	P0
BR-006	查看应用实时状态和资源使用	P1
BR-007	用户认证和权限管理	P1
BR-008	审计日志记录	P2

用户角色

1. 平台管理员 - 管理集群、Registry、用户
2. 开发者 - 部署和管理自己的应用
3. 运维人员 - 监控和维护应用状态
4. 访客 - 只读查看应用列表和状态

---

功能需求

F1. 集群管理

描述: 管理多个 Kubernetes 集群的连接配置

功能点:

• 添加集群（配置 API Server 地址、证书）
• 查看集群列表和详情
• 测试集群连接健康状态
• 更新和删除集群配置
• 查看集群资源使用情况（CPU、内存、节点数）

验收标准:

• ✅ 支持证书认证和 Token 认证
• ✅ 敏感信息（证书、密钥）加密存储
• ✅ 连接失败时给出清晰的错误提示
• ✅ 支持测试连接功能

---

F2. Registry 管理

描述: 管理多个 OCI Registry 的连接配置

功能点:

• 添加 Registry（Harbor、Docker Hub、GHCR 等）
• 配置认证信息（用户名/密码）
• 查看 Registry 列表和详情
• 测试 Registry 连接健康状态
• 更新和删除 Registry 配置

验收标准:

• ✅ 支持 Basic Auth 和 Bearer Token
• ✅ 密码加密存储
• ✅ 支持 HTTP/HTTPS 和自签名证书
• ✅ 连接测试返回响应时间

---

F3. Artifact 浏览

描述: 浏览和搜索 OCI Registry 中的 Helm Chart

功能点:

• 列出 Registry 中的所有仓库
• 列出仓库中的所有制品（tags）
• 查看制品详情（大小、创建时间、annotations）
• 自动识别制品类型（Helm Chart、Docker Image）
• 获取 Helm Chart 的 values schema

验收标准:

• ✅ 符合 OCI Distribution Specification
• ✅ 支持 URL 编码的仓库名称（如 charts/app）
• ✅ 正确解析 manifest 和 config
• ✅ 计算制品总大小（包含所有 layers）

---

F4. 应用部署

描述: 部署 Helm Chart 到 Kubernetes 集群

功能点:

• 选择集群、Registry、Chart 和版本
• 配置 values（JSON 或 YAML）
• 安装应用到指定 namespace
• 查看安装进度和状态
• 获取应用访问端点

验收标准:

• ✅ 支持自定义 Release 名称
• ✅ 支持 JSON 和 YAML 格式的 values
• ✅ 记录部署历史

---

F5. 应用生命周期管理

描述: 管理已部署应用的完整生命周期

功能点:

• 查看应用列表和详情
• 升级应用到新版本
• 查看部署历史
• 卸载应用

验收标准:

• ✅ 升级时保留配置
• ✅ 卸载时可选保留历史
• ✅ 显示每次部署的描述信息

---

F6. 监控和状态

描述: 实时监控应用和集群状态

功能点:

• 查看应用实时状态（Running、Failed 等）
• 查看应用资源使用（CPU、内存）
• 查看集群整体监控
• 查看节点资源使用
• 监控摘要统计

验收标准:

• ✅ 实时获取 Kubernetes 资源状态
• ✅ 支持 Prometheus 指标集成
• ✅ 显示 Pod 状态和事件
• ✅ 资源使用百分比显示

---

F7. 认证和授权

描述: 用户身份认证和访问控制

功能点:

• 用户注册和登录
• JWT Token 认证
• Token 刷新机制
• 密码加密存储

验收标准:

• ✅ 使用 bcrypt 哈希密码
• ✅ JWT Token 有效期配置
• ✅ Refresh Token 支持
• ✅ 密码强度验证

---

非功能需求

NFR1. 性能要求

指标	要求
API 响应时间	P95 < 500ms
并发用户数	支持 100+ 并发
数据库连接池	25 个连接
Helm 操作超时	5 分钟

NFR2. 可用性

• 系统可用性: 99.5%
• 故障恢复时间: < 5 分钟
• 数据备份: 每日备份
• 健康检查: 提供 /health 端点

NFR3. 安全性

• 数据加密: AES-256 加密敏感数据
• 传输安全: 支持 HTTPS
• 认证方式: JWT Token
• 密码策略: 最小长度 8 位
• 审计日志: 记录所有操作（未来）

NFR4. 可扩展性

• 水平扩展: 支持多实例部署
• 数据库: PostgreSQL 支持主从复制
• 无状态设计: API 服务无状态
• 缓存策略: 支持 Redis（未来）

NFR5. 可维护性

• 代码质量: 遵循 Go 最佳实践
• 测试覆盖: > 70%
• 文档完整: API 文档、架构文档、部署文档
• 日志记录: 结构化日志
• 监控指标: Prometheus 指标（未来）

NFR6. 兼容性

• Kubernetes 版本: 1.24+
• Helm 版本: 3.x
• OCI Registry: 符合 OCI Distribution Spec
• 数据库: PostgreSQL 15+
• Go 版本: 1.21+

---

2.1.2 业务建模

业务领域

OCDP Backend 属于云原生应用管理领域，主要涉及以下子域：

1. 制品管理域 - OCI Registry、Helm Chart、Docker Image
2. 集群管理域 - Kubernetes Cluster、Node、Namespace
3. 应用部署域 - Helm Release、Application Instance
4. 监控运维域 - Metrics、Logs、Events

---

核心实体

领域模型图

┌─────────────────────────────────────────────────────────────┐
│                     Core Domain Entities                     │
└─────────────────────────────────────────────────────────────┘

┌──────────┐         ┌──────────┐         ┌──────────┐
│   User   │─────────│ Cluster  │─────────│ Instance │
└──────────┘         └──────────┘         └──────────┘
     │                    │                     │
     │                    │                     │
     ▼                    ▼                     ▼
┌──────────┐         ┌──────────┐         ┌──────────┐
│   Auth   │         │  Health  │         │  Status  │
│  Token   │         │  Check   │         │ Resource │
└──────────┘         └──────────┘         └──────────┘

┌──────────┐         ┌──────────┐         ┌──────────┐
│ Registry │─────────│Artifact  │─────────│  Chart   │
└──────────┘         └──────────┘         └──────────┘
     │                    │                     │
     │                    │                     │
     ▼                    ▼                     ▼
┌──────────┐         ┌──────────┐         ┌──────────┐
│  Health  │         │Repository│         │  Values  │
│  Check   │         │          │         │  Schema  │
└──────────┘         └──────────┘         └──────────┘

实体详解

1. User（用户）

职责: 表示系统用户，负责身份认证

属性:

• ID: 唯一标识符
• Username: 用户名（唯一）
• Email: 邮箱
• PasswordHash: 密码哈希（bcrypt）
• CreatedAt: 创建时间
• UpdatedAt: 更新时间

业务规则:

• 用户名唯一
• 邮箱格式验证
• 密码最小长度 8 位

---

2. Cluster（集群）

职责: 表示 Kubernetes 集群连接配置

属性:

• ID: 唯一标识符
• Name: 集群名称
• Host: API Server 地址
• Description: 描述
• CAData: CA 证书（加密存储）
• CertData: 客户端证书（加密存储）
• KeyData: 客户端密钥（加密存储）
• Token: Bearer Token（可选）
• CreatedAt: 创建时间
• UpdatedAt: 更新时间

业务规则:

• 集群名称唯一
• 必须提供证书或 Token
• Host 必须是有效的 HTTPS URL

---

3. Registry（镜像仓库）

职责: 表示 OCI Registry 连接配置

属性:

• ID: 唯一标识符
• Name: Registry 名称
• URL: Registry URL
• Description: 描述
• Username: 用户名
• Password: 密码（加密存储）
• Insecure: 是否跳过 SSL 验证
• CreatedAt: 创建时间
• UpdatedAt: 更新时间

业务规则:

• Registry 名称唯一
• URL 必须是有效的 HTTP/HTTPS URL
• 密码加密存储

---

4. Instance（应用实例）

职责: 表示部署在 Kubernetes 中的 Helm Release

属性:

• ID: 唯一标识符
• Name: Release 名称
• Namespace: Kubernetes namespace
• ClusterID: 所属集群
• RegistryID: Chart 来源 Registry
• Repository: Chart 仓库名
• Chart: Chart 名称
• Version: Chart 版本
• Status: 部署状态
• Revision: 当前版本号
• Values: 配置值（JSON）
• Description: 描述
• CreatedAt: 创建时间
• UpdatedAt: 更新时间

业务规则:

• 同一集群和 namespace 下 Release 名称唯一
• 必须关联有效的 Cluster 和 Registry
• Values 必须是有效的 JSON 或 YAML

---

5. Artifact（制品）

职责: 表示 OCI Registry 中的制品（Helm Chart、Docker Image 等）

属性:

• RepositoryName: 仓库名称
• Tag: 标签
• Digest: SHA256 摘要
• Type: 制品类型（helm、docker、oci）
• Size: 总大小
• MediaType: 媒体类型
• Annotations: 元数据
• CreatedAt: 创建时间

业务规则:

• Tag 或 Digest 至少提供一个
• 自动识别制品类型
• 计算所有 layers 的总大小

---

业务流程

流程 1: 用户注册和登录

┌──────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
│ User │    │ Handler  │    │ Service  │    │   Repo   │
└──┬───┘    └────┬─────┘    └────┬─────┘    └────┬─────┘
   │             │               │               │
   │ Register    │               │               │
   ├────────────>│               │               │
   │             │ Create User   │               │
   │             ├──────────────>│               │
   │             │               │ Hash Password │
   │             │               ├──────┐        │
   │             │               │<─────┘        │
   │             │               │ Save User     │
   │             │               ├──────────────>│
   │             │               │<──────────────┤
   │             │<──────────────┤               │
   │<────────────┤               │               │
   │             │               │               │
   │ Login       │               │               │
   ├────────────>│               │               │
   │             │ Authenticate  │               │
   │             ├──────────────>│               │
   │             │               │ Verify Pwd    │
   │             │               ├──────┐        │
   │             │               │<─────┘        │
   │             │               │ Gen JWT       │
   │             │               ├──────┐        │
   │             │               │<─────┘        │
   │             │<──────────────┤               │
   │<────────────┤ Return Token  │               │
   │             │               │               │

---

流程 2: 部署应用

┌──────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
│ User │    │ Handler  │    │ Service  │    │HelmClient│    │Kubernetes│
└──┬───┘    └────┬─────┘    └────┬─────┘    └────┬─────┘    └────┬─────┘
   │             │               │               │               │
   │ Deploy App  │               │               │               │
   ├────────────>│               │               │               │
   │             │ Create Inst   │               │               │
   │             ├──────────────>│               │               │
   │             │               │ Validate      │               │
   │             │               ├──────┐        │               │
   │             │               │<─────┘        │               │
   │             │               │ Pull Chart    │               │
   │             │               ├──────────────>│               │
   │             │               │<──────────────┤               │
   │             │               │ Install Chart │               │
   │             │               ├──────────────>│               │
   │             │               │               │ Apply K8s     │
   │             │               │               ├──────────────>│
   │             │               │               │<──────────────┤
   │             │               │<──────────────┤               │
   │             │               │ Save Instance │               │
   │             │               ├──────┐        │               │
   │             │               │<─────┘        │               │
   │             │<──────────────┤               │               │
   │<────────────┤ Return Status │               │               │
   │             │               │               │               │

---

流程 3: 浏览制品

┌──────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
│ User │    │ Handler  │    │ Service  │    │OCIClient │    │ Registry │
└──┬───┘    └────┬─────┘    └────┬─────┘    └────┬─────┘    └────┬─────┘
   │             │               │               │               │
   │List Repos   │               │               │               │
   ├────────────>│               │               │               │
   │             │ Get Repos     │               │               │
   │             ├──────────────>│               │               │
   │             │               │ List Catalog  │               │
   │             │               ├──────────────>│               │
   │             │               │               │ GET _catalog  │
   │             │               │               ├──────────────>│
   │             │               │               │<──────────────┤
   │             │               │<──────────────┤               │
   │             │<──────────────┤               │               │
   │<────────────┤               │               │               │
   │             │               │               │               │
   │List Tags    │               │               │               │
   ├────────────>│               │               │               │
   │             │ Get Artifacts │               │               │
   │             ├──────────────>│               │               │
   │             │               │ List Tags     │               │
   │             │               ├──────────────>│               │
   │             │               │               │ GET tags/list │
   │             │               │               ├──────────────>│
   │             │               │               │<──────────────┤
   │             │               │ Get Manifest  │               │
   │             │               ├──────────────>│               │
   │             │               │               │ GET manifest  │
   │             │               │               ├──────────────>│
   │             │               │               │<──────────────┤
   │             │               │<──────────────┤               │
   │             │<──────────────┤               │               │
   │<────────────┤               │               │               │
   │             │               │               │               │

---

用例场景

UC1: 开发者部署测试应用

主角: 开发者 Alice

前置条件:

• Alice 已登录系统
• 系统中已配置开发环境集群
• 系统中已配置 Harbor Registry

基本流程:

1. Alice 选择"开发集群"
2. Alice 浏览 Harbor 中的"charts/nginx"仓库
3. Alice 选择 nginx 1.0.0 版本
4. Alice 配置 values: {"replicaCount": 2}
5. Alice 点击"部署"
6. 系统显示部署进度
7. 部署成功，显示应用访问地址

后置条件:

• nginx 应用成功部署到开发集群
• 应用状态为 "deployed"
• Alice 可以访问应用

异常流程:

• 3a. Chart 版本不存在 → 显示错误提示
• 5a. 部署失败 → 显示错误日志

---

UC2: 运维人员升级生产应用

主角: 运维 Bob

前置条件:

• Bob 已登录系统
• 生产环境有运行中的 nginx 应用（版本 1.0.0）

基本流程:

1. Bob 进入"生产集群"应用列表
2. Bob 选择 nginx 应用
3. Bob 查看当前版本和配置
4. Bob 点击"升级"
5. Bob 选择新版本 1.1.0
6. Bob 更新配置: {"replicaCount": 3}
7. Bob 添加升级说明
8. Bob 确认升级
9. 系统执行滚动升级
10. 升级成功，Revision 增加到 2

后置条件:

• nginx 应用升级到 1.1.0
• 副本数增加到 3
• 历史记录中保留了 Revision 1

异常流程:

• 9a. 升级失败 → 显示错误信息，保持原状态
• 9b. 超时 → 取消升级，保持原状态

---

UC3: 管理员添加新集群

主角: 管理员 Charlie

前置条件:

• Charlie 已登录系统
• Charlie 有集群的 kubeconfig 文件

基本流程:

1. Charlie 进入"集群管理"页面
2. Charlie 点击"添加集群"
3. Charlie 填写集群信息:
   • 名称: "Production Cluster"
   • API Server: "https://k8s.prod.com:6443"
   • 描述: "生产环境集群"
4. Charlie 从 kubeconfig 提取证书数据
5. Charlie 粘贴 CA、Cert、Key 数据
6. Charlie 点击"测试连接"
7. 系统显示"连接成功"
8. Charlie 保存配置

后置条件:

• 新集群添加到系统
• 集群证书加密存储
• 其他用户可以使用此集群

异常流程:

• 6a. 连接失败 → 显示具体错误信息
• 6b. 证书格式错误 → 提示正确的格式

---

2.1.3 技术建模

2.1.3.1 六边形架构

架构概述

OCDP Backend 采用六边形架构（Hexagonal Architecture，也称为端口和适配器架构），这是一种分层架构模式，强调业务逻辑与外部依赖的分离。

核心原则

1. 依赖倒置 - 所有层依赖 Domain，Domain 无外部依赖
2. 端口和适配器 - 通过接口（Port）定义交互协议，通过适配器（Adapter）实现具体技术
3. 可测试性 - 业务逻辑可独立测试，无需外部依赖
4. 可替换性 - 适配器可轻松替换（Mock ↔ Production）

架构分层图

┌─────────────────────────────────────────────────────────────┐
│                     Input Adapters                          │
│                   (HTTP REST API)                           │
│                                                              │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │ Auth Handler │  │Cluster Handl │  │Instance Handl│     │
│  └──────────────┘  └──────────────┘  └──────────────┘     │
│                                                              │
└──────────────────────┬──────────────────────────────────────┘
                       │ DTO / Request
                       ↓
┌─────────────────────────────────────────────────────────────┐
│                    Domain Layer                             │
│                   (Business Logic)                          │
│                                                              │
│  ┌──────────────────────────────────────────────────────┐  │
│  │                    Entities                          │  │
│  │  User | Cluster | Registry | Instance | Artifact    │  │
│  └──────────────────────────────────────────────────────┘  │
│                                                              │
│  ┌──────────────────────────────────────────────────────┐  │
│  │                    Services                          │  │
│  │  AuthService | ClusterService | InstanceService     │  │
│  └──────────────────────────────────────────────────────┘  │
│                                                              │
│  ┌──────────────────────────────────────────────────────┐  │
│  │             Repository Interfaces (Ports)            │  │
│  │  UserRepo | ClusterRepo | OCIClient | HelmClient    │  │
│  └──────────────────────────────────────────────────────┘  │
│                                                              │
└──────────────────────┬──────────────────────────────────────┘
                       │ Interface Contract
                       ↓
┌─────────────────────────────────────────────────────────────┐
│                   Output Adapters                           │
│            (Infrastructure Implementations)                 │
│                                                              │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │   Database   │  │  OCI Client  │  │ Helm Client  │     │
│  │              │  │              │  │              │     │
│  ├──────────────┤  ├──────────────┤  ├──────────────┤     │
│  │ Mock: Memory │  │ Mock: Static │  │ Mock: Fake   │     │
│  │ Prod:Postgres│  │ Prod: ORAS   │  │ Prod: Helm   │     │
│  └──────────────┘  └──────────────┘  └──────────────┘     │
│                                                              │
└─────────────────────────────────────────────────────────────┘

目录结构

internal/
├── domain/                    # 🎯 领域层（核心）
│   ├── entity/                # 领域实体
│   │   ├── user.go
│   │   ├── cluster.go
│   │   ├── registry.go
│   │   ├── instance.go
│   │   └── artifact.go
│   │
│   ├── service/               # 业务逻辑服务
│   │   ├── auth_service.go
│   │   ├── cluster_service.go
│   │   ├── registry_service.go
│   │   ├── artifact_service.go
│   │   ├── instance_service.go
│   │   └── monitoring_service.go
│   │
│   └── repository/            # 接口定义（Output Ports）
│       ├── user_repository.go
│       ├── cluster_repository.go
│       ├── registry_repository.go
│       ├── instance_repository.go
│       ├── oci_client.go
│       ├── helm_client.go
│       └── metrics_client.go
│
├── adapter/
│   ├── input/                 # 📥 输入适配器
│   │   └── http/
│   │       ├── rest/          # REST API Handlers
│   │       │   ├── auth_handler.go
│   │       │   ├── cluster_handler.go
│   │       │   ├── registry_handler.go
│   │       │   ├── artifact_handler.go
│   │       │   ├── instance_handler.go
│   │       │   ├── monitoring_handler.go
│   │       │   └── utils.go
│   │       │
│   │       └── dto/           # 数据传输对象
│   │           ├── auth_dto.go
│   │           ├── cluster_dto.go
│   │           ├── registry_dto.go
│   │           └── instance_dto.go
│   │
│   └── output/                # 📤 输出适配器
│       ├── persistence/
│       │   ├── mock/          # ✅ Mock 实现
│       │   │   ├── user_repository_mock.go
│       │   │   ├── cluster_repository_mock.go
│       │   │   ├── registry_repository_mock.go
│       │   │   └── instance_repository_mock.go
│       │   │
│       │   └── postgres/      # 🐘 PostgreSQL 实现
│       │       ├── user_repository.go
│       │       ├── cluster_repository.go
│       │       ├── registry_repository.go
│       │       └── instance_repository.go
│       │
│       ├── oci/
│       │   ├── mock/          # ✅ Mock OCI Client
│       │   │   └── oci_client_mock.go
│       │   └── oras_client.go # ORAS SDK 实现
│       │
│       ├── helm/
│       │   ├── mock/          # ✅ Mock Helm Client
│       │   │   └── helm_client_mock.go
│       │   └── helm_client.go # Helm SDK 实现
│       │
│       ├── metrics/
│       │   ├── mock/          # ✅ Mock Metrics Client
│       │   │   └── metrics_client_mock.go
│       │   └── prometheus_client.go
│       │
│       └── factory.go         # 🏭 适配器工厂
│
├── bootstrap/                 # Bootstrap 预注入模块
│   ├── config.go
│   └── seeder.go
│
└── pkg/                       # 🔧 工具包
    ├── jwt/                   # JWT 工具
    ├── password/              # 密码哈希
    └── encryption/            # AES 加密

数据流

1. HTTP Request
      ↓
2. [REST Handler] (Input Adapter)
   - 验证请求参数
   - 转换为 Domain 对象（Entity）
      ↓
3. [Domain Service] (Business Logic)
   - 执行业务逻辑
   - 调用 Repository 接口（Port）
      ↓
4. [Repository Implementation] (Output Adapter)
   - Mock: 操作内存数据
   - PostgreSQL: 操作数据库
   - ORAS: 与 OCI Registry 交互
   - Helm: 与 Kubernetes 交互
      ↓
5. Response
   - 返回结果到 Service
   - Service 返回到 Handler
   - Handler 转换为 HTTP 响应

依赖注入

在 cmd/api/main.go 中组装所有组件：

func main() {
    // 1. 加载配置
    config := loadConfig()
    
    // 2. 创建适配器工厂
    factory := output.NewAdapterFactory(
        config.AdapterMode,
        config.DatabaseURL,
    )
    
    // 3. 创建 Output Adapters
    repos, _ := factory.CreateAllRepositories()
    ociClient, _ := factory.CreateOCIClient()
    helmClient, _ := factory.CreateHelmClient()
    
    // 4. 创建工具类
    hasher := password.NewBcryptHasher()
    jwtGen := jwt.NewJWTGenerator(config.JWTSecret)
    
    // 5. 创建 Domain Services
    authService := service.NewAuthService(repos.UserRepo, hasher, jwtGen)
    clusterService := service.NewClusterService(repos.ClusterRepo)
    registryService := service.NewRegistryService(repos.RegistryRepo)
    instanceService := service.NewInstanceService(
        repos.InstanceRepo,
        repos.ClusterRepo,
        repos.RegistryRepo,
        helmClient,
    )
    
    // 6. 创建 Input Adapters (REST Handlers)
    authHandler := rest.NewAuthHandler(authService)
    clusterHandler := rest.NewClusterHandler(clusterService)
    instanceHandler := rest.NewInstanceHandler(instanceService)
    
    // 7. 设置路由
    router := setupRouter(
        authHandler,
        clusterHandler,
        instanceHandler,
    )
    
    // 8. 启动服务器
    http.ListenAndServe(":8080", router)
}

适配器模式

适配器工厂

// internal/adapter/output/factory.go
type AdapterMode string

const (
    ModeMock       AdapterMode = "mock"
    ModeProduction AdapterMode = "production"
)

type AdapterFactory struct {
    mode         AdapterMode
    dbConnString string
}

func (f *AdapterFactory) CreateUserRepository() (repository.UserRepository, error) {
    switch f.mode {
    case ModeMock:
        return mock.NewUserRepositoryMock(), nil
    case ModeProduction:
        return postgres.NewUserRepository(f.dbConnString)
    default:
        return nil, fmt.Errorf("unknown adapter mode: %s", f.mode)
    }
}

Mock vs Production

接口	Mock 模式	Production 模式
UserRepository	✅ 内存 map	🐘 PostgreSQL
ClusterRepository	✅ 内存 map	🐘 PostgreSQL
RegistryRepository	✅ 内存 map	🐘 PostgreSQL
InstanceRepository	✅ 内存 map	🐘 PostgreSQL
OCIClient	✅ 静态数据	🌐 ORAS SDK v2
HelmClient	✅ 模拟部署	☸️ Helm SDK
MetricsClient	✅ 假数据	📊 Prometheus

---

2.1.3.2 技术选型

编程语言

Go 1.21+

选型理由:

• ✅ 高性能，原生并发支持
• ✅ 静态类型，编译时检查
• ✅ 丰富的云原生生态（Kubernetes client-go、Helm SDK、ORAS）
• ✅ 简单易维护，部署方便（单一二进制文件）
• ✅ 广泛应用于云原生领域

替代方案: Java/Spring Boot, Python/FastAPI

---

Web 框架

gorilla/mux

选型理由:

• ✅ 轻量级，性能好
• ✅ 灵活的路由匹配（支持正则表达式）
• ✅ 与标准库 net/http 完美兼容
• ✅ 活跃的社区支持

使用示例:

router := mux.NewRouter()
api := router.PathPrefix("/api/v1").Subrouter()
api.HandleFunc("/clusters", handler.CreateCluster).Methods(http.MethodPost)
api.HandleFunc("/clusters/{clusterId}", handler.GetCluster).Methods(http.MethodGet)

替代方案: Gin, Echo, Fiber

---

数据库

PostgreSQL 15+

选型理由:

• ✅ 开源、成熟、可靠
• ✅ 支持复杂查询和事务
• ✅ JSONB 类型适合存储动态配置
• ✅ 主从复制、高可用支持
• ✅ 与 Go 生态集成良好

数据库驱动: lib/pq 或 pgx

替代方案: MySQL, MongoDB

---

OCI Registry 客户端

ORAS Go SDK v2

选型理由:

• ✅ 符合 OCI Distribution Specification
• ✅ 官方维护，质量可靠
• ✅ 支持所有 OCI 兼容的 Registry
• ✅ 完整的 manifest、blob 操作

使用示例:

repo, err := remote.NewRepository("harbor.example.com/charts/nginx")
repo.Client = &auth.Client{
    Credential: auth.StaticCredential("username", "password"),
}

tags, err := repo.Tags(ctx)
manifest, err := repo.FetchReference(ctx, "1.0.0")

官网: https://oras.land/

替代方案: containerd, go-containerregistry

---

Kubernetes 客户端

client-go

选型理由:

• ✅ Kubernetes 官方 Go 客户端
• ✅ 完整的 API 支持
• ✅ 动态客户端支持
• ✅ 与 Helm SDK 集成

使用示例:

config, err := clientcmd.BuildConfigFromFlags("", kubeconfig)
clientset, err := kubernetes.NewForConfig(config)

pods, err := clientset.CoreV1().Pods("default").List(ctx, metav1.ListOptions{})

替代方案: 无（标准库）

---

Helm 客户端

Helm SDK (helm.sh/helm/v3)

选型理由:

• ✅ Helm 官方 SDK
• ✅ 完整的 Helm 操作支持
• ✅ Chart 解析和渲染
• ✅ Release 生命周期管理

使用示例:

actionConfig := new(action.Configuration)
actionConfig.Init(settings.RESTClientGetter(), namespace, os.Getenv("HELM_DRIVER"), log.Printf)

install := action.NewInstall(actionConfig)
install.ReleaseName = "my-release"
install.Namespace = "default"

chart, err := loader.Load(chartPath)
release, err := install.Run(chart, values)

替代方案: 命令行调用 helm（不推荐）

---

认证和授权

JWT (golang-jwt/jwt)

选型理由:

• ✅ 无状态，易扩展
• ✅ 标准化（RFC 7519）
• ✅ 支持过期时间和刷新
• ✅ 广泛应用

使用示例:

token := jwt.NewWithClaims(jwt.SigningMethodHS256, jwt.MapClaims{
    "user_id": user.ID,
    "exp":     time.Now().Add(time.Hour * 24).Unix(),
})

tokenString, err := token.SignedString([]byte(jwtSecret))

替代方案: OAuth 2.0, Session

---

密码哈希

bcrypt (golang.org/x/crypto/bcrypt)

选型理由:

• ✅ 安全、抗暴力破解
• ✅ 自动加盐
• ✅ 计算成本可调
• ✅ Go 标准扩展库

使用示例:

hash, err := bcrypt.GenerateFromPassword([]byte(password), bcrypt.DefaultCost)
err = bcrypt.CompareHashAndPassword(hash, []byte(password))

替代方案: argon2, scrypt

---

数据加密

AES-256 (crypto/aes + crypto/cipher)

选型理由:

• ✅ 对称加密，性能好
• ✅ 256 位密钥，安全性高
• ✅ Go 标准库支持
• ✅ 适合敏感数据加密（证书、密码）

使用模式: GCM（Galois/Counter Mode）

使用示例:

block, err := aes.NewCipher(key) // 32 bytes key
gcm, err := cipher.NewGCM(block)
nonce := make([]byte, gcm.NonceSize())
ciphertext := gcm.Seal(nonce, nonce, plaintext, nil)

替代方案: RSA (非对称加密，性能较差)

---

容器化

Docker + Docker Compose

选型理由:

• ✅ 标准化容器技术
• ✅ 简化部署和环境一致性
• ✅ 丰富的镜像生态
• ✅ Docker Compose 简化多容器编排

Dockerfile 示例:

FROM golang:1.21-alpine AS builder
WORKDIR /app
COPY . .
RUN go build -o ocdp-backend cmd/api/main.go

FROM alpine:latest
RUN apk --no-cache add ca-certificates
WORKDIR /root/
COPY --from=builder /app/ocdp-backend .
EXPOSE 8080
CMD ["./ocdp-backend"]

替代方案: Podman, containerd

---

日志记录

标准库 log + 结构化日志（未来：zerolog/zap）

当前实现:

log.Printf("✅ User created: %s", user.Username)
log.Printf("⚠️  Warning: %v", err)
log.Printf("❌ Error: %v", err)

未来优化:

logger.Info().
    Str("user_id", user.ID).
    Str("username", user.Username).
    Msg("User created")

---

测试框架

testify

选型理由:

• ✅ 丰富的断言函数
• ✅ Mock 支持
• ✅ 测试套件支持
• ✅ 活跃的社区

使用示例:

import (
    "testing"
    "github.com/stretchr/testify/assert"
    "github.com/stretchr/testify/require"
)

func TestCreateUser(t *testing.T) {
    user, err := service.CreateUser(ctx, "test", "password")
    require.NoError(t, err)
    assert.NotEmpty(t, user.ID)
    assert.Equal(t, "test", user.Username)
}

---

热重载（开发）

Air

选型理由:

• ✅ Go 项目热重载
• ✅ 监听文件变化自动重启
• ✅ 配置简单

配置文件: .air.toml

[build]
  cmd = "go build -o ./tmp/main cmd/api/main.go"
  bin = "./tmp/main"
  include_ext = ["go", "yaml", "json"]
  exclude_dir = ["tmp", "vendor"]

启动: air -c .air.toml

---

技术栈总结表

组件	技术	版本	用途
语言	Go	1.21+	主要编程语言
Web 框架	gorilla/mux	latest	HTTP 路由
数据库	PostgreSQL	15+	持久化存储
数据库驱动	lib/pq 或 pgx	latest	Go 数据库驱动
OCI 客户端	ORAS Go SDK	v2	OCI Registry 操作
Kubernetes	client-go	latest	K8s API 交互
Helm	Helm SDK	v3	Helm 操作
JWT	golang-jwt/jwt	v5	认证 Token
密码哈希	bcrypt	latest	密码加密
数据加密	AES-256	stdlib	敏感数据加密
容器化	Docker	latest	应用容器化
编排	Docker Compose	latest	多容器编排
测试	testify	latest	单元测试
热重载	Air	latest	开发环境

---

Bootstrap 预注入

概述: 在应用启动时自动初始化用户、Registry、Cluster 等数据。

配置文件: config/bootstrap.json

{
  "enabled": true,
  "users": [
    {
      "username": "admin",
      "password": "admin123",
      "email": "admin@example.com"
    }
  ],
  "registries": [
    {
      "name": "Harbor Production",
      "url": "https://harbor.example.com",
      "username": "admin",
      "password": "secret"
    }
  ],
  "clusters": [
    {
      "name": "Production Cluster",
      "host": "https://k8s.example.com:6443",
      "caData": "LS0tLS...",
      "certData": "LS0tLS...",
      "keyData": "LS0tLS..."
    }
  ]
}

特性:

• ✅ 自动加密敏感数据
• ✅ 幂等性（重复启动不会重复创建）
• ✅ 可通过环境变量配置
• ✅ 支持禁用

从 kubeconfig 提取证书:

kubectl config view --raw -o jsonpath='{.clusters[0].cluster.certificate-authority-data}'
kubectl config view --raw -o jsonpath='{.users[0].user.client-certificate-data}'
kubectl config view --raw -o jsonpath='{.users[0].user.client-key-data}'

---

开发指南

添加新功能的步骤

1. 定义 Entity (internal/domain/entity/)
2. 定义 Repository 接口 (internal/domain/repository/)
3. 实现 Domain Service (internal/domain/service/)
4. 实现 Mock Adapter (internal/adapter/output/persistence/mock/)
5. 实现 Production Adapter (internal/adapter/output/persistence/postgres/)
6. 添加到 Factory (internal/adapter/output/factory.go)
7. 创建 REST Handler (internal/adapter/input/http/rest/)
8. 注册路由 (cmd/api/main.go)

依赖方向规则

• ✅ Input Adapters → Domain Layer
• ✅ Domain Layer → Repository Interfaces
• ✅ Output Adapters → Domain Layer (实现接口)
• ❌ Domain Layer → Output Adapters（禁止）

测试策略

• 单元测试: 测试 Domain Service，使用 Mock Repository
• 集成测试: 测试 Handler + Service，使用 Mock Adapters
• E2E 测试: 完整流程测试，使用真实环境

---

相关文档

• API 与测试
• 部署文档
• 主 README

---

Last Updated: 2025-11-09