ocdp-go/PLAN_E2E_DEPLOYMENT.md

OCDP 端到端部署流程 - 实现计划

Context

OCDP (One Click Deployment Platform) 是一个云原生一键部署平台，核心目标：让用户能够通过简单的操作，从 OCI Registry（如 Harbor）拉取 Helm Charts 并一键部署到 Kubernetes 集群。

当前状态：

• 后端 Helm 部署链路已实现（使用 helm.sh/helm/v3 SDK）
• Charts 浏览器可以拉取并显示 OCI Registry 中的 Helm Charts
• 但部署到 K8s 时报错

本文档聚焦于：完整打通 Admin 创建用户到 User 一键部署的整个流程，并验证端到端可用。

---

一、当前代码库状态

1.1 后端架构（已实现）

层级	组件	状态
输入适配器	REST Handlers (user, workspace, registry, instance, chart, storage, template)	✅ 全部实现
领域层	Services (auth, cluster, registry, instance, storage, template, workspace)	✅ 全部实现
输出适配器	PostgreSQL Repository	✅ 实现
	OCI Client (ORAS)	✅ 实现，从 Harbor 拉取 Charts
	Helm Client (helm.sh/helm/v3)	✅ 实现，真实调用 Helm 命令
	K8s Client	✅ 实现，查询 Services/Ingresses

部署链路：

InstanceService.CreateInstance()
    ├── 保存 instance 到 DB (status=pending)
    ├── 下载 Chart (OCI → /tmp/charts/)
    └── 异步 goroutine: executeAndSyncInstall()
            ├── 生成 kubeconfig (from cluster.Credentials)
            ├── helm install (Helm SDK)
            └── 每 10s 轮询状态，更新 DB

1.2 前端页面（已实现）

页面	路由	状态
登录	/login	✅
Charts 浏览器 + Deploy Modal	/charts	✅
Templates 管理	/templates	✅
Storage 管理	/storage	✅
Chart References	/chart-references	✅
Clusters 管理	/clusters	✅
Registries 管理	/registries	✅
Admin Workspaces	/admin/workspaces	✅
Admin Users	/admin/users	❓ 需确认
Monitoring	/monitoring	✅

1.3 数据库表（已创建）

• users - 用户账户 (role: admin/user, workspace_id)
• workspaces - 工作空间
• clusters - K8s 集群配置 (CA/Cert/Key)
• registries - OCI Registries (Harbor)
• instances - 部署实例记录
• storage_backends - 存储后端配置
• chart_references - Chart 引用
• values_templates - Values 模板（版本化）

---

二、待解决问题

2.1 部署报错（核心阻塞）

现象：Charts 可以拉取，但部署到 K8s 时报错

可能原因：

1. 没有 Cluster 记录：数据库 clusters 表为空
2. Cluster 不可达：K8s API Server 无法访问
3. Credentials 无效：存储的 CA/Cert/Key 数据格式错误
4. Namespace 无权限：Helm 尝试创建 namespace 时 RBAC 不足
5. Registry 认证失败：无法拉取 Helm Chart

诊断步骤：

# 1. 启动服务
./start.sh

# 2. 检查 Clusters 表
docker compose exec postgres psql -U ocdp -d ocdp -c "SELECT id, name, host FROM clusters;"

# 3. 查看后端日志
docker compose logs -f backend | grep -i error

# 4. 检查 Instances 表状态
docker compose exec postgres psql -U ocdp -d ocdp -c "SELECT id, name, status, last_error FROM instances;"

2.2 Admin 用户管理 UI

问题：/admin/users 页面是否存在？功能是否完整？

需要验证：

• 是否可以列出所有用户？
• 是否可以创建新用户（指定 workspace, role）？
• 是否有编辑/禁用/删除用户功能？

2.3 Deploy Modal 功能不完整

问题：当前 Deploy Modal 只有手动填写 values.yaml，没有 Template/Storage 选择器

需要增强：

• 添加 Values Template 下拉选择器
• 选择 Template 后自动填充 values.yaml
• 添加 Storage Backend 选择器
• 选择 Storage 后自动 merge 到 values

---

三、实施计划

Phase 1: 诊断与修复部署问题 (P0)

目标：确保部署链路能够正常工作

步骤：

1. 启动服务 ./start.sh
2. 检查 clusters 表是否有有效的 K8s Cluster 记录
3. 查看后端日志定位具体错误
4. 根据错误类型修复：
   • 无 Cluster → Admin 添加 Cluster 或插入测试数据
   • 不可达 → 检查集群配置和网络
   • Credentials 错误 → 修复 kubeconfig 生成逻辑
   • 无权限 → 配置正确的 RBAC

关键文件：

• backend/internal/domain/service/instance_service.go - 部署逻辑
• backend/internal/adapter/output/helm/real/helm_client.go - Helm 调用
• backend/internal/domain/repository/cluster_repository.go - Cluster 数据访问

Phase 2: 完善 Admin 用户管理 UI (P0)

目标：Admin 可以完整管理用户

步骤：

1. 检查 frontend/src/app/admin/users/page.tsx 是否存在

2. 如不存在，创建用户管理页面：

   • 用户列表（调用 adminApi.listUsers()）
   • 创建用户表单（username, password, role, workspace_id 选择）
   • 编辑用户角色/状态
   • 重置用户密码
   • 删除用户

3. 更新 frontend/src/components/sidebar.tsx 添加导航项

关键文件：

• frontend/src/app/admin/users/page.tsx
• frontend/src/components/sidebar.tsx
• frontend/src/lib/api.ts (adminApi)

Phase 3: 增强 Deploy Modal (P1)

目标：让用户可以方便地选择 Template 和 Storage

步骤：

1. 修改 frontend/src/app/charts/page.tsx 中的 Deploy Modal
2. 添加 Values Template 选择器：
   • 加载当前 chart 关联的 templates
   • 选择后自动填充 values.yaml
3. 添加 Storage Backend 选择器：
   • 加载可用的 storage 配置
   • 选择后自动 merge 到 values
4. 添加 loading 状态和错误处理

关键文件：

• frontend/src/app/charts/page.tsx
• frontend/src/lib/api.ts (valuesTemplateApi, storageApi)

Phase 4: E2E 端到端验证 (P0)

目标：验证整个流程端到端可用

手动测试流程：

# 1. Admin 登录 (admin/admin123)
# 2. 添加 K8s Cluster（指向真实或测试集群）
# 3. 添加 Harbor Registry
# 4. 创建 Workspace "test-ws"
# 5. 创建用户 "testuser" 分配到 test-ws
# 6. 登出，用 testuser 登录
# 7. 浏览 Charts（选择 Registry，查看 Repositories）
# 8. 创建 Values Template
# 9. 部署 Chart（选择 Template）
# 10. 查看实例状态
# 11. 验证 Helm Release 实际部署到 K8s

自动化 E2E 测试： 更新 e2e_test.py 覆盖完整流程：

• Admin 创建用户流程
• User 登录后部署流程
• 验证实例创建成功

Phase 5: 完善 Values Template 功能 (P2)

目标：Values Template 版本管理和回滚

功能：

• 每次更新创建新版本
• 查看版本历史
• 回滚到历史版本

关键文件：

• backend/internal/domain/service/values_template_service.go
• frontend/src/app/templates/page.tsx

Phase 6: Storage 分层配置 (P2)

目标：实现分层存储配置

功能：

• Cluster-level 默认存储
• Workspace-level 存储覆盖
• User Override 最高优先级
• 默认 merge 到 values.yaml

---

四、验证方式

4.1 手动验证清单

• Admin 登录成功
• Admin 可以添加 K8s Cluster
• Admin 可以添加 Harbor Registry
• Admin 可以创建 Workspace
• Admin 可以创建 User
• User 登录成功
• User 可以浏览 Charts（从 Registry）
• User 可以创建 Values Template
• User 可以部署 Chart（选择 Template）
• User 可以查看实例状态
• Helm Release 实际部署到 K8s
• User 可以查看 K8s 中的 Pods/Services

4.2 日志检查

部署成功后，检查：

# 后端日志
docker compose logs -f backend | grep -i "install\|deploy\|helm"

# K8s 中的 Helm Releases
kubectl get releases -A  # 或 helm list -A

# 实例状态
curl http://localhost:8080/api/v1/instances | jq

---

五、技术决策

5.1 Helm Client 模式

生产环境：使用真实 Helm Client (ADAPTER_MODE=real) 测试环境：使用 Mock Client (ADAPTER_MODE=mock)

5.2 Cluster Credentials

存储方式：直接在 clusters 表存储 CA/Cert/Key 生成 kubeconfig：在运行时拼接 kubeconfig YAML 文件

5.3 Namespace 隔离

当前实现：用户指定 namespace 规划：Workspace 自动分配 namespace 前缀（如 ws-{workspace}-{instance}）

---

六、关键文件索引

后端

文件	用途
backend/cmd/api/main.go	入口，路由注册，依赖注入
backend/internal/adapter/input/http/rest/instance_handler.go	实例部署 API
backend/internal/adapter/input/http/rest/user_management_handler.go	用户管理 API
backend/internal/domain/service/instance_service.go	实例部署逻辑
backend/internal/adapter/output/helm/real/helm_client.go	真实 Helm Client
backend/internal/adapter/output/oci/real/oci_client.go	OCI Registry 客户端
backend/internal/adapter/output/persistence/postgres/instance_repository.go	实例数据访问
backend/scripts/init-db.sql	数据库初始化

前端

文件	用途
frontend/src/app/charts/page.tsx	Charts 浏览器 + Deploy Modal
frontend/src/app/admin/users/page.tsx	Admin 用户管理
frontend/src/app/admin/workspaces/page.tsx	Admin Workspace 管理
frontend/src/app/templates/page.tsx	Values Template 管理
frontend/src/app/storage/page.tsx	Storage Backend 管理
frontend/src/app/login/page.tsx	登录页面
frontend/src/lib/api.ts	API 客户端
frontend/src/components/sidebar.tsx	侧边栏导航

测试

文件	用途
e2e_test.py	Playwright E2E 测试
debug_login.py	登录调试脚本