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