344 lines
11 KiB
Markdown
344 lines
11 KiB
Markdown
# OCDP Backend
|
||
|
||
基于 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 (可选)
|
||
|
||
### 常用命令
|
||
|
||
```bash
|
||
# 查看所有命令
|
||
make help
|
||
|
||
# 开发
|
||
make dev # 开发模式（热重载）
|
||
make build # 构建
|
||
make run-mock # Mock 模式运行
|
||
make run-prod # Production 模式运行
|
||
|
||
# Docker Compose
|
||
make mock # Mock 模式
|
||
make prod # 生产模式
|
||
make logs # 查看日志
|
||
make status # 查看状态
|
||
make stop # 停止服务
|
||
|
||
# 数据库
|
||
make db-up # 启动数据库
|
||
make db-psql # 连接数据库
|
||
make db-backup # 备份数据库
|
||
make pgadmin # 启动 pgAdmin
|
||
```
|
||
|
||
### 项目结构
|
||
|
||
```
|
||
backend/
|
||
├── cmd/api/ # 程序入口
|
||
├── internal/
|
||
│ ├── 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)
|