fix: resolve deployment API errors and enable E2E deployment flow

Backend fixes: - instance_dto: add Version field with Normalize() to support both 'version' and 'tag' field names from frontend - instance_handler: add version empty validation before creating instance - authz.go: fix unused variable compilation error - registry_repository: fix GetByID/GetByName to use correct DB schema (add workspace_id, owner_id, is_shared fields); decrypt password gracefully when encryption key mismatches instead of returning error Frontend: - charts/page: add Template and Storage dropdown selectors to Deploy Modal Testing: - add e2e_test.py: 5-step Playwright E2E test (admin login → create workspace → create user → user login → deploy chart) - add tasks/lesson.md: document 4 bug root causes and fixes - add tasks/todo.md: track implementation progress - add PLAN_E2E_DEPLOYMENT.md: comprehensive implementation plan Verification: confirmed deployment creates instance with status=deployed, chart downloads from Harbor OCI to /tmp/charts/, Helm release deploys to K8s
2026-04-16 18:39:23 +08:00
parent ef961d4ade
commit 985369d40f
9 changed files with 813 additions and 17 deletions
--- a/PLAN_E2E_DEPLOYMENT.md
+++ b/PLAN_E2E_DEPLOYMENT.md
@ -0,0 +1,311 @@
+# 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
+
+**诊断步骤**：
+```bash
+# 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)
+
+**目标**：验证整个流程端到端可用
+
+**手动测试流程**：
+```bash
+# 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 日志检查
+
+部署成功后，检查：
+```bash
+# 后端日志
+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` | 登录调试脚本 |