# 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*