ocdp-go/backend

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 测试，无需数据库。

# 安装 Air（首次）
go install github.com/air-verse/air@latest

# 启动 Mock 模式
make dev-mock

方式 2: 本地 Backend + Docker 数据库（推荐日常开发）

支持数据持久化和热重载。

# 启动数据库
docker compose up -d postgres

# 启动 Backend
make dev

方式 3: 完全容器化（生产部署）

适合生产环境和 CI/CD。

# 启动完整服务
make prod

# 或
docker compose --profile backend up -d

本地运行

# Mock 模式（快速测试）
make run-mock

# 或
export ADAPTER_MODE=mock
go run cmd/api/main.go

# Production 模式（需要数据库）
make run-prod

验证服务

# 健康检查
curl http://localhost:8080/health

# 查看 API
curl http://localhost:8080/api/v1/registries | jq

# 访问 Swagger UI (交互式 API 文档)
open http://localhost:8080/api/docs

📚 文档

文档	说明
快速开始	快速开始指南 - 3分钟上手 ⭐
命令速查表	Make 命令参考 - 所有命令详解 ⭐
部署指南	完整部署指南 - Mock 和默认模式
架构文档	六边形架构、目录结构、开发指南
OpenAPI 规范	OpenAPI 3.0 规范 - 标准 API 定义
Swagger UI	交互式 API 文档 - 在线测试 API 🚀
API 与测试	REST API 参考文档 + 测试指南

🎯 API 文档使用指南

方式 1: Swagger UI (推荐) ⭐

启动服务后访问：http://localhost:8080/api/docs

特性：

• 📖 交互式文档 - 所有 API 可视化展示
• 🔧 在线测试 - 直接在浏览器中测试 API
• 🔐 认证支持 - 支持 JWT Token 认证
• 📦 Schema 查看 - 查看所有请求/响应模型

方式 2: OpenAPI 规范文件

# 查看规范文件
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 - 完整的 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)  │     │
│  └──────────────┘  └──────────────┘  └──────────────┘     │
└─────────────────────────────────────────────────────────────┘

详见 架构文档

🎯 核心 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

🔧 开发

环境要求

• Go 1.21+
• PostgreSQL 15+ (生产模式)
• Docker & Docker Compose (可选)

常用命令

# 查看所有命令
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/                 # 🛠️ 脚本

详见 架构文档

🔐 安全配置

环境变量

# 必需配置
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 中配置初始数据：

{
  "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 预注入

🌐 服务访问

服务	地址	说明
Backend API	http://localhost:8080/api/v1	REST API
Health Check	http://localhost:8080/health	健康检查
PostgreSQL	localhost:5432	数据库
pgAdmin	http://localhost:5050	数据库管理

🐛 故障排查

常见问题

端口被占用:

# 修改 .env 中的 BACKEND_PORT
BACKEND_PORT=8081

数据库连接失败:

# 检查数据库状态
docker compose ps postgres
docker compose logs postgres

完全重置:

# 停止并删除所有数据
docker compose down -v
docker compose --profile production up -d

更多问题参见 部署文档 - 故障排查

📊 技术栈

组件	技术
语言	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
• OCI Image Specification
• Helm Documentation

使用的库

• Gorilla Mux - HTTP 路由
• ORAS Go SDK - OCI Registry 操作
• Helm SDK - Helm 操作
• 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)