OCDP/ocdp-go
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

feat(frontend): add Helm chart browser, monitoring, chart-references and values templates pages

Browse Source 
Add new frontend pages for the multi-tenant OCDP platform:

- Charts page (/charts): Browse Harbor OCI registries to list Helm chart repositories
  and versions, with deploy modal to launch charts on selected clusters
- Monitoring page (/monitoring): Display cluster metrics (CPU/Memory/GPU usage)
  and per-node details with resource utilization bars
- Chart References page (/chart-references): CRUD for chart metadata references
- Values Templates page (/templates): CRUD for Helm values templates with version
  history and rollback support
- Sidebar: Add Charts navigation, update Storage and Templates links
- api.ts: Add all API client functions (clusterApi, registryApi, instanceApi,
  monitoringApi, storageApi, chartReferenceApi, valuesTemplateApi,
  workspaceApi, userApi) with full TypeScript types

Note: deploy flow and values template rollback not yet end-to-end tested.
This commit is contained in:
Ivan087
2026-04-15 16:59:31 +08:00
parent c5e51ed069
commit 29d0310f03
283 changed files with 24658 additions and 36038 deletions
Download Patch File Download Diff File Expand all files Collapse all files

396
backend/README.md
View File

@ -1,343 +1,89 @@
# OCDP Backend
基于 Go 的 Kubernetes Helm Chart 管理服务后端，提供完整的制品浏览和应用部署能力。
Go 后端服务，提供 Kubernetes Helm Chart 部署能力。
## ✨ 特性
- 🎪 **Helm Chart 管理** - 完整的 Helm 生命周期支持
- 📦 **多 Registry 支持** - Harbor、Docker Hub、GHCR 等
- 🔍 **Artifact 浏览** - 自动识别类型、大小、metadata
- 🚀 **OCI 标准兼容** - 使用 ORAS Go SDK v2
- 🖥️ **多集群支持** - 管理多个 Kubernetes 集群
- 🔐 **认证支持** - JWT + 密码加密
- 📊 **实时状态** - Helm Release 状态监控
- 🏗️ **六边形架构** - 清晰的分层设计，易于测试和扩展
- 🔄 **双模式支持** - Mock 模式（开发调试）+ 默认模式（真实 PostgreSQL）
## 🚀 快速开始
### 方式 1: Mock 模式（最快）
适合快速功能开发和 API 测试，无需数据库。
```bash
# 安装 Air（首次）
go install github.com/air-verse/air@latest
# 启动 Mock 模式
make dev-mock
```
### 方式 2: 本地 Backend + Docker 数据库（推荐日常开发）
支持数据持久化和热重载。
```bash
# 启动数据库
docker compose up -d postgres
# 启动 Backend
make dev
```
### 方式 3: 完全容器化（生产部署）
适合生产环境和 CI/CD。
```bash
# 启动完整服务
make prod
# 或
docker compose --profile backend up -d
```
### 本地运行
```bash
# Mock 模式（快速测试）
make run-mock
# 或
export ADAPTER_MODE=mock
go run cmd/api/main.go
# Production 模式（需要数据库）
make run-prod
```
### 验证服务
```bash
# 健康检查
curl http://localhost:8080/health
# 查看 API
curl http://localhost:8080/api/v1/registries | jq
# 访问 Swagger UI (交互式 API 文档)
open http://localhost:8080/api/docs
```
## 📚 文档
| 文档 | 说明 |
|------|------|
| [快速开始](QUICK-START.md) | **快速开始指南** - 3分钟上手 ⭐ |
| [命令速查表](COMMANDS.md) | **Make 命令参考** - 所有命令详解 ⭐ |
| [部署指南](DEPLOYMENT-GUIDE.md) | **完整部署指南** - Mock 和默认模式 |
| [架构文档](docs/architecture.md) | 六边形架构、目录结构、开发指南 |
| [OpenAPI 规范](docs/openapi.yaml) | **OpenAPI 3.0 规范** - 标准 API 定义 |
| [Swagger UI](http://localhost:8080/api/docs) | **交互式 API 文档** - 在线测试 API 🚀 |
| [API 与测试](docs/api-and-test.md) | REST API 参考文档 + 测试指南 |
### 🎯 API 文档使用指南
**方式 1: Swagger UI (推荐)** ⭐
启动服务后访问：[http://localhost:8080/api/docs](http://localhost:8080/api/docs)
特性：
- 📖 交互式文档 - 所有 API 可视化展示
- 🔧 在线测试 - 直接在浏览器中测试 API
- 🔐 认证支持 - 支持 JWT Token 认证
- 📦 Schema 查看 - 查看所有请求/响应模型
**方式 2: OpenAPI 规范文件**
```bash
# 查看规范文件
cat docs/openapi.yaml
# 使用 OpenAPI 工具生成客户端
openapi-generator-cli generate -i docs/openapi.yaml -g go -o ./client
# 在线验证
curl http://localhost:8080/api/docs/openapi.yaml
```
**方式 3: Markdown 文档**
查看 [docs/api-and-test.md](docs/api-and-test.md) - 完整的 API 参考文档
## 🏗️ 架构概览
采用**六边形架构**（Hexagonal Architecture），实现清晰的分层和依赖倒置：
```
┌─────────────────────────────────────────────────────────────┐
│ Input Adapters │
│ (HTTP REST API) │
└──────────────────────┬──────────────────────────────────────┘
│
↓
┌─────────────────────────────────────────────────────────────┐
│ Domain Layer │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Entities │ │ Services │ │ Interfaces │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└──────────────────────┬──────────────────────────────────────┘
│
↓
┌─────────────────────────────────────────────────────────────┐
│ Output Adapters │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Database │ │ OCI Client │ │ Helm Client │ │
│ │ (Mock/Prod) │ │ (Mock/ORAS) │ │ (Mock/Real) │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
详见 [架构文档](docs/architecture.md)
## 🎯 核心 API
| 分类 | 端点 | 说明 |
|------|------|------|
| **认证** | `POST /api/v1/auth/login` | 用户登录 |
| **集群** | `GET /api/v1/clusters` | 列出集群 |
| | `POST /api/v1/clusters` | 创建集群 |
| **Registry** | `GET /api/v1/registries` | 列出 Registry |
| | `POST /api/v1/registries` | 创建 Registry |
| **Artifact** | `GET /api/v1/registries/{id}/repositories` | 列出仓库 |
| | `GET /api/v1/registries/{id}/repositories/{repo}/artifacts` | 列出制品 |
| **实例** | `POST /api/v1/clusters/{id}/instances` | 安装应用 |
| | `GET /api/v1/clusters/{id}/instances` | 列出实例 |
| | `PUT /api/v1/clusters/{id}/instances/{instanceId}` | 升级应用 |
| | `DELETE /api/v1/clusters/{id}/instances/{instanceId}` | 卸载应用 |
| | `GET /api/v1/clusters/{id}/instances/{instanceId}/entries` | 查看实例入口 |
| **监控** | `GET /api/v1/monitoring/summary` | 监控摘要 |
完整 API 文档: [docs/api.md](docs/api.md)
## 🔧 开发
### 环境要求
## 技术栈
- Go 1.21+
- PostgreSQL 15+ (生产模式)
- Docker & Docker Compose (可选)
- gorilla/mux (HTTP 路由)
- ORAS Go SDK v2 (OCI 操作)
- Helm SDK (Helm 操作)
- Kubernetes client-go
- PostgreSQL
### 常用命令
## 启动
```bash
# 查看所有命令
make help
# Mock 模式（无需数据库，无需外部服务）
ADAPTER_MODE=mock go run cmd/api/main.go
# 开发
make dev # 开发模式（热重载）
make build # 构建
make run-mock # Mock 模式运行
make run-prod # Production 模式运行
# 生产模式（需要 PostgreSQL + K8s/Harbor 连接验证）
# 启动 PostgreSQL
docker compose up -d postgres
# Docker Compose
make mock # Mock 模式
make prod # 生产模式
make logs # 查看日志
make status # 查看状态
make stop # 停止服务
# 启动后端（生产模式）
cd backend
export DATABASE_URL="postgres://postgres:postgres@localhost:5432/ocdp?sslmode=disable"
export JWT_SECRET="your-jwt-secret"
export ENCRYPTION_KEY="your-32-byte-encryption-key"
export PORT=8081
export ADAPTER_MODE=production
export KUBECONFIG=/home/ivanwu/.kube/config # 或你的 kubeconfig 路径
# 数据库
make db-up # 启动数据库
make db-psql # 连接数据库
make db-backup # 备份数据库
make pgadmin # 启动 pgAdmin
# Harbor 凭证（可选，用于验证 Registry 连接）
export HARBOR_URL="https://harbor.bwgdi.com"
export HARBOR_USERNAME="your-harbor-user"
export HARBOR_PASSWORD="your-harbor-password"
# NFS 配置（可选）
export NFS_SERVER="10.6.80.11"
export NFS_SHARE="/volume1/NFS"
go run cmd/api/main.go
```
### 项目结构
## 环境变量说明
| 变量 | 必需 | 说明 |
|------|------|------|
| DATABASE_URL | 是 | PostgreSQL 连接字符串 |
| JWT_SECRET | 是 | JWT 签名密钥 |
| ENCRYPTION_KEY | 是 | 32位加密密钥 |
| PORT | 否 | 服务端口，默认 8080 |
| ADAPTER_MODE | 否 | `mock` 或 `production`，默认 production |
| KUBECONFIG | 生产模式 | Kubernetes kubeconfig 文件路径 |
| HARBOR_URL | 否 | Harbor URL，用于 Registry 验证 |
| HARBOR_USERNAME | 否 | Harbor 用户名 |
| HARBOR_PASSWORD | 否 | Harbor 密码 |
## 连接验证
在生产模式下，创建 Cluster 或 Registry 时会自动验证连接：
- **Cluster**: 尝试使用提供的凭证连接 K8s API Server
- **Registry**: 尝试使用提供的凭证登录 Harbor
如果验证失败，创建会返回错误信息。
## API 访问
- API: http://localhost:8081/api/v1
- Health: http://localhost:8081/health
- Swagger: http://localhost:8081/api/docs
## 项目结构
```
backend/
├── cmd/api/ # 程序入口
├── cmd/api/ # 入口
├── internal/
│ ├── domain/ # 🎯 领域层（核心）
│ │ ├── entity/ # 实体
│ │ ├── service/ # 业务逻辑
│ │ └── repository/ # 接口定义
│ ├── domain/ # 领域层
│ │ ├── entity/ # 实体
│ │ ├── service/ # 业务逻辑
│ │ └── repository/ # 接口
│ ├── adapter/
│ │ ├── input/http/ # 📥 REST API
│ │ └── output/ # 📤 数据库、OCI、Helm
│ ├── bootstrap/ # Bootstrap 预注入
│ └── pkg/ # 🔧 工具包
├── docs/ # 📚 文档
├── config/ # ⚙️ 配置
└── scripts/ # 🛠️ 脚本
```
详见 [架构文档](docs/architecture.md)
## 🔐 安全配置
### 环境变量
```bash
# 必需配置
ADAPTER_MODE=production
JWT_SECRET=your-jwt-secret
ENCRYPTION_KEY=your-32-character-encryption-key
DATABASE_URL=postgresql://user:pass@host:5432/ocdp
# 生成安全密钥
openssl rand -base64 32
```
### Bootstrap 预注入
在 `config/bootstrap.json` 中配置初始数据：
```json
{
"enabled": true,
"users": [
{"username": "admin", "password": "admin123", "email": "admin@example.com"}
],
"registries": [
{"name": "harbor", "url": "https://harbor.example.com", "username": "admin", "password": "secret"}
],
"clusters": [
{"name": "prod", "host": "https://k8s.example.com:6443", "caData": "...", "certData": "...", "keyData": "..."}
]
}
```
详见 [架构文档 - Bootstrap 预注入](docs/architecture.md#bootstrap-预注入)
## 🌐 服务访问
| 服务 | 地址 | 说明 |
|------|------|------|
| Backend API | http://localhost:8080/api/v1 | REST API |
| Health Check | http://localhost:8080/health | 健康检查 |
| PostgreSQL | localhost:5432 | 数据库 |
| pgAdmin | http://localhost:5050 | 数据库管理 |
## 🐛 故障排查
### 常见问题
**端口被占用**:
```bash
# 修改 .env 中的 BACKEND_PORT
BACKEND_PORT=8081
```
**数据库连接失败**:
```bash
# 检查数据库状态
docker compose ps postgres
docker compose logs postgres
```
**完全重置**:
```bash
# 停止并删除所有数据
docker compose down -v
docker compose --profile production up -d
```
更多问题参见 [部署文档 - 故障排查](docs/deployment.md#故障排查)
## 📊 技术栈
| 组件 | 技术 |
|------|------|
| **语言** | Go 1.21+ |
| **Web 框架** | gorilla/mux |
| **OCI 客户端** | ORAS Go SDK v2 |
| **Helm 集成** | Helm SDK |
| **Kubernetes** | client-go |
| **数据库** | PostgreSQL 15+ |
| **容器化** | Docker, Docker Compose |
| **热重载** | Air |
## 🔗 相关资源
### 规范和文档
- [OCI Distribution Specification](https://github.com/opencontainers/distribution-spec)
- [OCI Image Specification](https://github.com/opencontainers/image-spec)
- [Helm Documentation](https://helm.sh/docs/)
### 使用的库
- [Gorilla Mux](https://github.com/gorilla/mux) - HTTP 路由
- [ORAS Go SDK](https://oras.land/docs/category/go-library) - OCI Registry 操作
- [Helm SDK](https://helm.sh/docs/topics/advanced/) - Helm 操作
- [Kubernetes Client-Go](https://github.com/kubernetes/client-go) - K8s API 客户端
## 📝 待办事项
- [ ] 添加单元测试和集成测试
- [ ] 实现 Rate Limiting
- [ ] 添加审计日志
- [ ] 实现 Webhook 通知
- [ ] 支持更多 OCI Registry 类型
- [ ] 添加 Metrics 和 Tracing
## 📄 License
MIT License
---
**Version**: 2.2.0
**Last Updated**: 2025-11-09
**Port**: 8080 (default)
│ │ ├── input/http/ # REST API
│ │ └── output/ # 数据库、OCI、Helm
│ └── bootstrap/ # 启动配置
└── docs/ # OpenAPI 规范
```