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