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

**诊断步骤**：
```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` | 登录调试脚本 |