diff --git a/PROJECT_SUMMARY.md b/PROJECT_SUMMARY.md new file mode 100644 index 0000000..e68126b --- /dev/null +++ b/PROJECT_SUMMARY.md @@ -0,0 +1,669 @@ +# OCDP 项目总结文档 + +> 创建时间: 2026-04-16 +> 最后更新: 2026-04-16 + +--- + +## 一、项目概述 + +### 1.1 项目定位 + +**OCDP (One Click Deployment Platform)** — 开源云原生一键部署平台 + +**核心理念**: 让用户能够通过简单的操作，从 OCI Registry（如 Harbor）拉取 Helm Charts 并一键部署到指定 Kubernetes 集群，同时支持多租户隔离和配置模板化管理。 + +### 1.2 解决的问题 + +1. **部署复杂性**: 传统 K8s 部署需要编写复杂的 YAML、手动管理 Helm Values +2. **配置一致性**: 不同环境（dev/staging/prod）需要不同的配置，但配置复用困难 +3. **多集群管理**: 维护多个 K8s 集群的部署一致性和状态同步 +4. **多租户隔离**: 不同团队/项目需要资源隔离和权限控制 +5. **配置版本管理**: 配置变更需要可追溯、可回滚 + +### 1.3 目标用户 + +- **DevOps 工程师**: 需要快速部署应用到多个集群 +- **开发团队**: 需要自助式部署，无需深入了解 K8s +- **平台团队**: 需要管理多租户、quotas、和资源隔离 + +--- + +## 二、技术架构 + +### 2.1 技术栈 + +| 层级 | 技术 | 说明 | +|------|------|------| +| 后端 | Go 1.21+ | Hexagonal Architecture | +| 前端 | React 18, TypeScript, Next.js | App Router | +| 数据库 | PostgreSQL 15+ | 多租户数据存储 | +| 网关 | Nginx | 反向代理、SSL 终止 | +| 容器 | Docker Compose | 本地开发/部署 | + +### 2.2 架构设计 — Hexagonal Architecture + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ Frontend (Next.js) │ +│ http://localhost │ +└─────────────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────────┐ +│ Nginx Reverse Proxy │ +│ http://localhost:200 │ +└─────────────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────────┐ +│ Backend API (Go) │ +│ http://localhost:8080 │ +│ ┌─────────────────────────────────────────────────────────────┐ │ +│ │ Input Adapters (Ports) │ │ +│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────────────┐ │ │ +│ │ │ REST │ │ Auth │ │ Swagger │ │ CORS │ │ │ +│ │ │ Handler │ │ Handler │ │ Handler│ │ Middleware │ │ │ +│ │ └────┬────┘ └────┬────┘ └─────────┘ └─────────────────┘ │ │ +│ └───────┼────────────┼────────────────────────────────────────┘ │ +│ │ │ │ +│ ┌───────▼────────────▼────────────────────────────────────────┐ │ +│ │ Domain Layer │ │ +│ │ ┌─────────────────┐ ┌─────────────────────────────┐ │ │ +│ │ │ Services │ │ Entities │ │ │ +│ │ │ - AuthService │ │ - User, Workspace, Cluster │ │ │ +│ │ │ - ClusterService │ │ - Registry, Storage │ │ │ +│ │ │ - InstanceService│ │ - ValuesTemplate, Instance │ │ │ +│ │ │ - ... │ └─────────────────────────────┘ │ │ +│ │ └────────┬─────────┘ │ │ +│ │ │ │ │ +│ │ ┌────────▼─────────────────────────────────────────────┐ │ │ +│ │ │ Repository Interfaces │ │ │ +│ │ │ (Ports - 定义数据访问契约) │ │ │ +│ │ └────────────────────────┬────────────────────────────┘ │ │ +│ └───────────────────────────┼────────────────────────────────┘ │ +│ │ │ +│ ┌───────────────────────────▼────────────────────────────────┐ │ +│ │ Output Adapters │ │ +│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │ │ +│ │ │ PostgreSQL │ │ OCI │ │ Kubernetes │ │ │ +│ │ │ Repository │ │ Client │ │ (Helm, Metrics) │ │ │ +│ │ └─────────────┘ └─────────────┘ └─────────────────────┘ │ │ +│ └─────────────────────────────────────────────────────────────┘ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +### 2.3 项目结构 + +``` +ocdp-go/ +├── backend/ # Go 后端 (Hexagonal Architecture) +│ ├── cmd/api/ # 入口点 +│ │ └── main.go # 主程序，路由配置，依赖注入 +│ ├── internal/ +│ │ ├── adapter/ # 适配器层 +│ │ │ ├── input/http/ # 输入适配器（HTTP 接口） +│ │ │ │ ├── rest/ # REST Handlers +│ │ │ │ ├── dto/ # Data Transfer Objects +│ │ │ │ └── middleware/ # 中间件（认证、授权） +│ │ │ └── output/ # 输出适配器（外部服务） +│ │ │ ├── persistence/ # 数据库实现 +│ │ │ ├── oci/ # OCI Registry 客户端 +│ │ │ ├── helm/ # Helm 客户端 +│ │ │ └── k8s/ # K8s 客户端 +│ │ ├── domain/ # 领域层（核心业务逻辑） +│ │ │ ├── entity/ # 实体定义 +│ │ │ ├── service/ # 领域服务 +│ │ │ └── repository/ # 仓储接口 +│ │ └── pkg/ # 公共工具包 +│ └── scripts/ # 数据库脚本 +│ ├── init-db.sql # 初始数据库结构 +│ └── migrations/ # 增量迁移脚本 +├── frontend/ # Next.js 前端 +│ ├── src/ +│ │ ├── app/ # App Router 页面 +│ │ │ ├── login/ # 登录页面 +│ │ │ ├── clusters/ # 集群管理 +│ │ │ ├── registries/ # Registry 管理 +│ │ │ ├── charts/ # Charts 浏览器（从 Harbor 直接拉取） +│ │ │ ├── templates/ # Values 模板管理 +│ │ │ ├── storage/ # Storage Backends 管理 +│ │ │ ├── monitoring/ # 监控页面 +│ │ │ └── admin/ # 管理后台 +│ │ ├── lib/ # 工具库 +│ │ │ ├── api.ts # API 客户端 +│ │ │ ├── types.ts # TypeScript 类型 +│ │ │ └── auth-context.tsx # 认证上下文 +│ │ └── components/ # 共享组件 +│ └── public/ # 静态资源 +└── infra/nginx/ # Nginx 配置 +``` + +--- + +## 三、核心功能模块 + +### 3.1 认证与多租户 + +**用户体系**: +- **Admin**: 管理员，可管理所有资源、用户、Workspace +- **User**: 普通用户，仅能访问自己 Workspace 的资源 +- 通过 Bootstrap Process 初始化用户账号 + +**Workspace 隔离 (Rancher Project 风格)**: +``` +K8s Cluster: k8s-prod +│ +├── Workspace: team-alpha (一个用户属于一个 Workspace) +│ ├── Namespaces: [app-a, app-b] (1+ 个 Namespace) +│ ├── User: alice +│ │ └── KubeConfig: ocdp-team-alpha-alice +│ │ └── 权限: 限制在 namespace: team-alpha-* +│ ├── ResourceQuota: CPU 10核, GPU 2卡 +│ └── Instances: nginx-prod, redis-prod +│ +├── Workspace: team-beta +│ ├── Namespaces: [app-x] +│ ├── User: bob +│ │ └── KubeConfig: ocdp-team-beta-bob +│ │ └── 权限: 限制在 namespace: team-beta-* +│ └── ResourceQuota: CPU 5核, GPU 1卡 +``` + +**Rancher Project 隔离模型说明**: +- **1 用户 = 1 Workspace**: 用户只能属于一个 Workspace +- **Workspace 包含多 Namespace**: 一个 Workspace 可创建多个 Namespace +- **KubeConfig 权限隔离**: Admin 创建用户时自动生成 KubeConfig，限制在 `workspace-*` 范围内 +- **资源配额限制**: 每个 Workspace 有独立的 CPU/GPU 配额 + +**KubeConfig 自动生成流程**: +``` +Admin 创建用户 "alice" in Workspace "team-alpha" + ↓ +Backend: 在 K8s 中创建 ServiceAccount + └── name: ocdp-team-alpha-alice + └── namespace: ocdp-system + ↓ +Backend: 创建 Role (限制 namespace 范围) + └── rules: [get,list,watch,create,update,delete] on pod, deployment, service, etc. + └── resourceNames: [team-alpha-*] (限制只能操作 workspace 的资源) + ↓ +Backend: 创建 RoleBinding + └── subjects: [ServiceAccount: ocdp-team-alpha-alice] + └── roleRef: Role [ocdp-team-alpha-alice] + ↓ +Backend: 生成 KubeConfig + └── clusters: [k8s-prod] + └── users: [ocdp-team-alpha-alice] + └── contexts: [ocdp-team-alpha-alice@k8s-prod] + ↓ +Backend: 将 KubeConfig 注入用户账户 + └── 存储在 users.kubeconfig 字段 + └── 或通过 API 返回给用户下载 + ↓ +Alice 登录后: + └── 可下载自己的 KubeConfig + └── 可使用 kubectl 操作: team-alpha-* 命名空间 + └── 无法访问其他 Workspace 的资源 +``` + +### 3.2 集群管理 + +**功能**: +- 添加/编辑/删除 Kubernetes 集群 +- 支持多种认证方式: kubeconfig, CA + Cert + Key, Token +- 健康检查和状态监控 +- 支持两种隔离模式: + - `namespace`: 共享集群，不同 Workspace 使用不同 Namespace（**推荐**） + - `cluster`: 独立集群模式，每个 Workspace 有独立集群凭证 + +### 3.3 Registry 管理 + +**功能**: +- 添加 OCI Registry (Harbor, Docker Hub 等) +- 健康检查和连接验证 +- 支持认证（用户名/密码） +- 支持 HTTPS/HTTP (insecure 模式) + +**使用方式**: 用户在 Charts 页面直接浏览 Registry 中的 Repositories 和 Chart 版本 + +### 3.4 Storage Backends（分层存储配置） + +**背景**: 有状态应用（数据库、消息队列）需要持久化存储。不同集群、不同用户可能使用不同的存储后端。 + +**分层配置架构**: +``` +┌─────────────────────────────────────────────────────────────┐ +│ Layer 1: Cluster Level (最低优先级) │ +│ Admin 为集群配置默认存储（如集群共享 NFS） │ +│ 例: { server: "10.6.80.11", path: "/shared/data" } │ +└─────────────────────────────────────────────────────────────┘ + ↓ (覆盖) +┌─────────────────────────────────────────────────────────────┐ +│ Layer 2: Workspace Level (中等优先级) │ +│ Workspace 管理员配置的存储路径覆盖 │ +│ 例: { server: "10.6.80.12", path: "/workspace/data" } │ +└─────────────────────────────────────────────────────────────┘ + ↓ (覆盖) +┌─────────────────────────────────────────────────────────────┐ +│ Layer 3: User Override (最高优先级) │ +│ 用户在部署时可选择/覆盖存储配置 │ +│ 例: { server: "10.6.80.13", path: "/my-app/data" } │ +└─────────────────────────────────────────────────────────────┘ +``` + +**存储类型支持**: +| 类型 | 配置参数 | +|------|----------| +| NFS | server, path | +| PV | storageClassName, capacity, accessModes | +| HostPath | path | + +**使用方式**: +- **默认 merge**: Storage 配置默认会 merge 到 values.yaml +- **用户可覆盖**: 用户可以在 Workspace 范围内选择可用的存储后端，或手动覆盖路径 +- **非强制**: Admin 配置的 Cluster-level storage 仅作为默认值，不强制使用 + +**使用场景**: +```yaml +# 1. Admin 为集群配置默认存储 +Cluster: k8s-prod +└── StorageBackend: "cluster-nfs" (server: "10.6.80.11", path: "/shared") + +# 2. Workspace 管理员覆盖为自己的存储 +Workspace: team-alpha +└── StorageBackend: "team-alpha-nfs" (server: "10.6.80.12", path: "/team-alpha") + +# 3. 用户 Alice 在部署时选择 Workspace 的存储（或再次覆盖） +Deployment Form: +├── Storage Reference: "team-alpha-nfs" ✓ +└── Path Override: "/alice-app" (可选) + +# 4. 最终 values.yaml (默认 merge 结果) +persistence: + enabled: true + storage: + nfs: + server: "10.6.80.12" # 来自 Workspace 覆盖 + path: "/team-alpha/alice-app" # 用户选择的路径 +``` + +### 3.5 Values Templates（版本化配置模板） + +**背景**: Helm 部署需要填写 Values YAML，不同环境需要不同配置，且配置需要可追溯、可回滚。 + +**功能**: +- 创建可复用的配置模板 +- 版本化管理（每次更新创建新版本） +- 保留历史版本，支持回滚 +- 部署时选择模板，自动填充 Values + +**实体设计**: +```go +type ValuesTemplate struct { + ID string // 唯一标识 + WorkspaceID string // 属于哪个 Workspace + OwnerID string // 创建者 + Name string // 模板名称 (e.g., "production", "development") + Description string // 描述 + ValuesYAML string // Helm Values YAML 内容 + Version int // 版本号（递增） + IsDefault bool // 是否为默认模板 +} +``` + +**版本管理机制**: +- 每次更新模板都会创建新版本 (Version++) +- 保留历史版本，可查看变更记录 +- 支持回滚到任意历史版本 + +### 3.6 一键部署流程 + +**完整工作流**: +``` +┌──────────────┐ ┌───────────────────┐ ┌─────────────────┐ +│ User │ │ OCDP Backend │ │ Target K8s │ +│ (Web UI) │────▶│ │────▶│ Cluster │ +└──────────────┘ └───────────────────┘ └─────────────────┘ + │ + ┌─────────────────┼─────────────────┐ + ▼ ▼ ▼ + ┌────────────┐ ┌────────────┐ ┌────────────┐ + │ Registry │ │ Template │ │ Helm │ + │ (Harbor) │ │ + Global │ │ Client │ + │ │ │ Config │ │ │ + └────────────┘ └────────────┘ └────────────┘ +``` + +**部署步骤**: +1. **选择 Registry**: 从已配置的 Harbor 中选择 +2. **浏览 Charts**: 直接浏览 Repositories 和 Chart 版本 +3. **选择 Values Template**: 或使用空白 Values（官方模板） +4. **可选: 添加 User Override**: 覆盖模板中的部分配置 +5. **可选: 选择 Storage Backend**: 使用 Cluster/Workspace 默认或手动选择/覆盖 +6. **选择 Target Cluster 和 Namespace**: 系统自动分配 Workspace 隔离的 Namespace +7. **点击 Deploy** +8. **Backend 合并配置**: Template + User Override + Storage Backend（默认 merge，可覆盖） +9. **Backend 调用 Helm**: 从 Registry 拉取 Chart 并安装到目标集群 +10. **Backend 同步状态**: 显示部署结果和 Helm Release 状态 + +### 3.7 资源配额与审计 + +**配额系统**: +- Workspace 可设置 CPU、GPU、GPU Memory 的软/硬限制 +- Workspace 创建时自动在集群中创建 ResourceQuota/LimitRange +- 部署时检查配额，超限拒绝 +- 实例删除时释放配额 + +**Namespace 隔离**: +- 共享集群模式下，每个 Workspace 有独立的 Namespace 前缀 +- 用户只能看到和操作自己 Workspace 的 Namespace +- 不同 Workspace 之间资源完全隔离 + +**审计日志**: +- 记录所有创建、更新、删除、部署操作 +- 包含操作者、时间、IP、详情 + +--- + +## 四、数据库设计 + +### 4.1 ER 图 + +``` +┌─────────────┐ ┌─────────────┐ ┌─────────────┐ +│ workspaces │ │ users │ │ clusters │ +├─────────────┤ ├─────────────┤ ├─────────────┤ +│ id (PK) │◀──┐ │ id (PK) │ │ id (PK) │ +│ name │ │ │ username │ │ name │ +│ description │ │ │ password │ │ host │ +│ created_by │───┘ │ role │ │ workspace_id│◀─┤ +│ created_at │ │ workspace_id│──┐ │ is_shared │ +└─────────────┘ │ is_active │ │ │ isolation │ + └─────────────┘ │ └─────────────┘ + │ │ │ + │ │ │ + ▼ │ ▼ + ┌─────────────┐ │ ┌─────────────┐ + │user_config_ │ │ │ registries │ + │overrides │ │ ├─────────────┤ + ├─────────────┤ │ │ id (PK) │ + │ id (PK) │ │ │ name │ + │ workspace_id│──┘ │ url │ + │ user_id │ │ workspace_id│◀─┤ + │ target_type │ │ is_shared │ + │ target_id │ └─────────────┘ + └─────────────┘ │ + │ + ┌───────────────────┤ + ▼ ▼ + ┌─────────────┐ ┌─────────────┐ + │ storage_ │ │ instances │ + │ backends │ ├─────────────┤ + ├─────────────┤ │ id (PK) │ + │ id (PK) │ │ workspace_id│ + │ name │ │ cluster_id │ + │ type │ │ registry_id │ + │ workspace_id│◀─┘ │ name │ + │ config │ │ namespace │ + └─────────────┘ │ status │ + │ values_yaml │ + ┌────────────│ user_override│ + ▼ └─────────────┘ + ┌─────────────┐ + │values_ │ + │templates │ + ├─────────────┤ + │ id (PK) │ + │ name │ + │ values_yaml │ + │ version │ + │ is_default │ + └─────────────┘ +``` + +### 4.2 核心表说明 + +| 表名 | 用途 | 关键字段 | +|------|------|----------| +| `users` | 用户账户 | role (admin/user), workspace_id | +| `workspaces` | 工作空间 | name, description | +| `workspace_quotas` | 资源配额 | workspace_id, resource_type, hard_limit, soft_limit, used | +| `clusters` | K8s 集群 | host, kubeconfig, workspace_id, isolation_mode | +| `registries` | OCI 仓库 | url, credentials, workspace_id | +| `storage_backends` | Storage 全局配置 | name, type (nfs/pv/hostPath), config (JSON) | +| `values_templates` | 值模板 | name, values_yaml, version, is_default | +| `instances` | 部署实例 | cluster_id, release name, namespace, status, values | +| `audit_logs` | 审计日志 | user_id, action, resource_type, details | + +--- + +## 五、设计理念 + +### 5.1 为什么需要 Storage Backends 分层配置？ + +**问题**: +- 一个 Admin 可能管理多个集群，每个集群有不同的存储配置 +- 同一集群中，不同用户/workspace 可能需要使用不同的存储路径 +- 存储配置需要集中管理，但也要允许灵活覆盖 + +**解决方案**: +- **分层配置**: Cluster → Workspace → User Override，优先级递增 +- **默认 merge**: Storage 配置默认会 merge 到 values.yaml，用户可选择覆盖 +- **集中管理**: Admin 在 Cluster 层面配置默认值，Workspace 和 User 逐层覆盖 +- **灵活选择**: 用户可以在可用列表中选择存储后端，或手动调整路径 + +### 5.2 为什么需要 Values Templates？ + +**问题**: +- Helm 部署需要填写复杂的 Values YAML +- 不同环境（dev/staging/prod）需要不同配置 +- 配置变更后无法追溯历史 +- 相同的配置需要反复填写 + +**解决方案**: +- 创建模板，定义标准配置 +- 支持多版本（像 Git 一样） +- 部署时选择模板 + 可选 User Override +- 支持回滚到历史版本 + +### 5.3 为什么需要 Workspace + Namespace 隔离？ + +**问题**: +- 多个团队共享 K8s 集群 +- 需要资源隔离，防止相互影响 +- 需要资源配额，防止资源抢占 + +**解决方案**: +- Workspace 对应一个或多个 Namespace +- 共享集群模式下：`{workspace-id}-{instance-name}` +- 自动创建 ResourceQuota/LimitRange +- 用户只能看到自己 Workspace 的资源 + +--- + +## 六、当前状态与待完成功能 + +### 6.1 已完成 ✅ + +| 模块 | 状态 | 说明 | +|------|------|------| +| 用户认证 | ✅ | JWT + 首次登录改密 | +| Workspace 多租户 | ✅ | Admin/User 角色隔离 | +| 集群管理 | ✅ | CRUD + 健康检查 | +| Registry 管理 | ✅ | CRUD + Harbor 连接验证 | +| Charts 浏览器 | ✅ | 从 Harbor 直接浏览 Repositories 和 Chart 版本 | +| 实例部署 | ✅ | 创建/升级/回滚/删除（后端状态管理） | +| 状态同步 | ✅ | 从 K8s 同步 Helm Release 状态 | +| 监控页面 | ✅ | 集群状态、Node 指标 | +| 配额系统 | ✅ | 数据库结构已创建 | +| 审计日志 | ✅ | 数据库结构已创建 | +| Storage Backends | ✅ | CRUD 管理 + 分层配置（cluster/workspace/shared 优先级解析） | +| Values Templates | ✅ | CRUD + 版本历史 + 回滚（行式版本化，每次更新 INSERT 新行） | + +### 6.2 待完成功能 ⏳ + +#### 高优先级 (P0) + +| 功能 | 描述 | +|------|------| +| **KubeConfig 自动生成** | Admin 创建用户时自动创建 SA + Role + RoleBinding 并注入 KubeConfig | +| **部署表单集成 Values Template** | 在 Deploy Modal 中选择预定义的 Values Template | +| **Storage Backends 分层配置** | Cluster → Workspace → User Override 分层配置 + 默认 merge | +| **Namespace 隔离** | 每个 Workspace 有独立的 Namespace 前缀，用户不可见其他 Workspace 的资源 | +| **K8s ResourceQuota 联动** | Workspace 创建时自动在集群中创建 ResourceQuota/LimitRange | + +#### 中优先级 (P1) + +| 功能 | 描述 | +|------|------| +| **配额强制执行** | 部署时检查 CPU/GPU 配额，超限拒绝并提示 | +| **配额使用情况 UI** | 在 Workspace 详情页显示 CPU/GPU/Memory 使用率和限制 | +| **User Config Override** | 部署时可额外覆盖 Template 中的部分配置 | + +### P2 已完成 + +| 功能 | 描述 | +|------|------| +| **Values Templates 版本管理** | 创建/历史/回滚，已 E2E 验证通过 | +| **Storage 分层配置解析** | ResolveStorageConfig 优先级 (cluster > workspace > shared)，已集成到 InstanceService | +| **Helm 实际安装到 K8s** | 验证 Helm Client 实际工作，不仅仅是状态管理 | +| **Namespace 隔离** | 每个 Workspace 有独立的 Namespace 前缀，用户不可见其他 Workspace 的资源 | + +#### 低优先级 (P2) + +| 功能 | 描述 | +|------|------| +| 完整的 E2E 测试 | 覆盖所有核心流程的自动化测试 | +| 审计日志查看页面 | Admin 查看所有操作记录 | + +### 实施路线图 — 当前进度 (2026-04-17) + +``` +Phase 1: 核心部署体验 (已完成) +├── [x] 部署表单添加 Values Template 选择器 +├── [x] Storage Backend 配置自动 merge 到 values.yaml +└── [x] Namespace 隔离实现（Workspace → ns prefix） + +Phase 2: 配额系统 (部分完成) +├── [ ] 部署时配额检查 +├── [ ] K8s ResourceQuota 自动创建 +└── [ ] 配额使用 UI 展示 + +Phase 3: 完善功能 (部分完成) +├── [ ] User Config Override +└── [ ] 审计日志页面 +``` + +### 6.3 实施路线图 + +``` +Phase 1: 核心部署体验 (1-2 周) +├── [ ] 部署表单添加 Values Template 选择器 +├── [ ] Storage Backend 配置自动 merge 到 values.yaml +└── [ ] Namespace 隔离实现（Workspace → ns prefix） + +Phase 2: 配额系统 (1 周) +├── [ ] 部署时配额检查 +├── [ ] K8s ResourceQuota 自动创建 +└── [ ] 配额使用 UI 展示 + +Phase 3: 完善功能 (1 周) +├── [ ] User Config Override +└── [ ] 审计日志页面 +``` + +--- + +## 七、完整的部署工作流（示例） + +``` +1. Admin 初始化平台 + ├── 添加 Harbor Registry: "harbor.company.com" + ├── 配置 Kubernetes Cluster: "k8s-prod" + └── 配置 Cluster-level Storage Backend: NFS (10.6.80.11:/shared) + +2. Admin 创建 Workspace "team-alpha" + └── 设置资源配额: CPU 10核, GPU 2卡 + └── 系统自动在集群创建 ns: team-alpha-* + └── 系统自动创建 ResourceQuota: team-alpha-quota + └── 配置 Workspace-level Storage: NFS (10.6.80.12:/team-alpha) + +3. Admin 创建用户 "alice"，分配到 team-alpha + └── 系统自动创建 KubeConfig (SA + Role + RoleBinding) + └── 权限范围: namespace team-alpha-* + └── 发送初始密码 + KubeConfig 下载链接 + +4. Alice 登录（首次需改密） + ├── 下载 KubeConfig + │ └── 使用 kubectl 操作: team-alpha-* 命名空间 + ├── 创建 Values Template: "production" (v1) + │ └── 定义 replicaCount=3, 引用 storage 配置 + ├── 部署 Instance: "my-nginx" + │ ├── 选择 Chart: harbor.company.com/charts/nginx:1.0.0 + │ ├── 选择 Template: production + │ ├── 选择 Storage: team-alpha-nfs (或覆盖路径) + │ ├── 选择 Cluster: k8s-prod + │ └── Namespace: team-alpha-my-nginx (自动分配) + └── 查看 Instance 状态: deployed ✓ + +5. Alice 查看集群中实际资源 + ├── Namespace: team-alpha-my-nginx + ├── Pods: nginx-xxx + └── ResourceQuota: team-alpha-quota (已生效) + +6. Alice 更新 Template (v2) + └── replicaCount 改为 5 + +7. Alice 升级 Instance + └── Helm upgrade my-nginx → 新配置自动应用 + +8. Admin 查看审计日志 + └── 了解所有操作记录 +``` + +--- + +## 八、快速开始 + +### 8.1 启动服务 + +```bash +# 使用一键脚本 +./start.sh + +# 或手动启动 +docker compose -f docker-compose.yml -f backend/docker-compose.yml up -d +``` + +### 8.2 访问 + +| 服务 | 地址 | 默认账号 | +|------|------|----------| +| 前端 | http://localhost | admin / admin123 | +| API | http://localhost:8080/api/v1 | - | +| Swagger | http://localhost:8080/api/docs | - | + +### 8.3 创建第一个部署 + +1. **登录**: 使用 admin/admin123 +2. **添加 Registry**: Harbor 地址 + 凭证 +3. **添加 Cluster**: Kubeconfig +4. **配置 Storage Backend**: NFS 服务器地址 +5. **创建 Workspace**: 设置配额 +6. **创建 Values Template**: 填写 Values YAML +7. **部署**: Charts 页面 → 选择 Registry → 浏览 Chart → Deploy → 选择 Template +8. **查看状态**: Monitoring 页面 + +--- + +## 九、参考文档 + +- [后端 README](backend/README.md) +- [前端 README](frontend/README.md) +- [数据库 Schema](backend/scripts/init-db.sql) +- [API 文档](http://localhost:8080/api/docs) + +--- + +*本文档由 Claude Code 生成，2026-04-16* \ No newline at end of file