# OCDP - Open Cloud Development Platform

[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Go Version](https://img.shields.io/badge/go-1.24+-00ADD8?logo=go)](https://go.dev/)
[![Node Version](https://img.shields.io/badge/node-20+-339933?logo=node.js)](https://nodejs.org/)
[![Docker](https://img.shields.io/badge/docker-20.10+-2496ED?logo=docker)](https://www.docker.com/)

开源云原生开发平台，用于管理 Kubernetes 集群、OCI Registry 和 Helm Charts 部署。

---

## ✨ 特性

- 🎯 **Registry 管理** - 支持 Harbor、Docker Registry、OCI 标准仓库
- 📦 **Artifact 浏览** - 浏览和管理 Helm Charts、容器镜像
- 🚀 **一键部署** - 可视化部署 Helm Charts 到 Kubernetes 集群
- 🔍 **智能过滤** - 按 MediaType 过滤 artifacts（chart、image、other）
- 🎨 **现代 UI** - 响应式设计，基于 React + TypeScript
- 🔐 **安全认证** - JWT 认证，加密存储敏感信息
- 🐳 **容器化** - 完整的 Docker 支持，多种运行模式
- 🔄 **热重载** - 开发模式支持代码热重载

---

## 🚀 快速开始

### 前置要求

- Docker 20.10+
- Docker Compose 2.0+
- (可选) Make 工具

### 5分钟快速体验

```bash
# 1. 克隆项目
git clone <repository-url>
cd ocdp-go

# 2. 启动开发环境（Mock 模式，无需数据库）
make docker-dev

# 3. 访问应用
# - 前端：http://localhost:5173
# - 后端：http://localhost:8080
# - 默认账号：admin / admin123
```

**详细指南**：查看 [快速开始指南](./QUICK_START.md)

---

## 📚 文档导航

### 📖 核心文档（必读）
- 🚀 [快速开始](./QUICK_START.md) - 5分钟快速上手
- 📋 [使用指南](./USAGE_GUIDE.md) - 详细使用说明（推荐）
- 💡 [命令速查表](./COMMANDS_CHEATSHEET.md) - 常用命令快速参考
- 📚 [文档中心](./docs/README.md) - 完整文档索引

### 🔧 专业文档
- 📐 [开发规范](./docs/development/specification.md) - 代码规范和架构
- 🚢 [部署指南](./docs/deployment/docker-guide.md) - 生产环境部署
- 🔒 [安全实践](./docs/security/security-implementation.md) - 安全配置
- 🎨 [功能文档](./docs/features/) - 详细功能说明

### 🔗 其他资源
- 📋 [OpenAPI 规范](./backend/docs/openapi.yaml) - RESTful API 定义
- 📦 [历史文档](./docs/archive/) - 项目演进历史

---

## 🏗️ 技术架构

### 技术栈

**后端**：
- Go 1.24+ (Hexagonal Architecture)
- PostgreSQL 16
- Redis 7

**前端**：
- React 18
- TypeScript 5
- Vite 6
- TailwindCSS 3

**容器化**：
- Docker
- Docker Compose
- Multi-stage builds

### 架构图

```
┌─────────────────────────────────────────────────────────────┐
│                         Frontend                            │
│              React + TypeScript + Vite                      │
└──────────────────────────┬──────────────────────────────────┘
                           │ HTTP/REST
┌──────────────────────────┼──────────────────────────────────┐
│                          │  Backend API                      │
│                          ▼                                   │
│              ┌─────────────────────┐                        │
│              │   Input Adapters    │                        │
│              │    (REST/GraphQL)   │                        │
│              └──────────┬──────────┘                        │
│                         │                                    │
│              ┌──────────▼──────────┐                        │
│              │   Domain Services   │                        │
│              │  (Business Logic)   │                        │
│              └──────────┬──────────┘                        │
│                         │                                    │
│              ┌──────────▼──────────┐                        │
│              │  Output Adapters    │                        │
│              │  (Repos/Clients)    │                        │
│              └──────────┬──────────┘                        │
└───────────────────────┼─┴────────────────────────────────┘
                         │
         ┌───────────────┼───────────────┐
         │               │               │
    ┌────▼────┐    ┌────▼────┐    ┌────▼────┐
    │  PG DB  │    │  Redis  │    │   OCI   │
    │         │    │         │    │ Registry│
    └─────────┘    └─────────┘    └─────────┘
```

### 运行模式

| 模式 | 特点 | 适用场景 | 命令 |
|------|------|----------|------|
| **开发模式** | Mock 数据，热重载 | 日常开发 | `make docker-dev` |
| **生产模式** | 真实数据库，完整功能 | 生产部署 | `make docker-prod` |
| **Mock 模式** | 独立测试单个服务 | 单元测试 | `make docker-test-backend` |

---

## 🛠️ 开发指南

### 项目结构

```
ocdp-go/
├── backend/                      # Go 后端服务
│   ├── cmd/api/                 # 应用入口
│   ├── internal/                # 内部代码
│   │   ├── adapter/            # 适配器层
│   │   ├── domain/             # 领域层
│   │   └── bootstrap/          # 启动配置
│   ├── Dockerfile              # 生产环境
│   ├── Dockerfile.dev          # 开发环境
│   └── Dockerfile.mock         # Mock 测试
│
├── frontend/                     # React 前端应用
│   ├── src/
│   │   ├── core/               # 核心功能
│   │   ├── features/           # 功能模块
│   │   └── shared/             # 共享组件
│   ├── Dockerfile              # 生产环境
│   ├── Dockerfile.dev          # 开发环境
│   └── Dockerfile.mock         # Mock 测试
│
├── api/                          # API 规范
│   └── openapi.yaml            # OpenAPI 定义
│
├── docs/                         # 项目文档
│   ├── features/               # 功能文档
│   ├── deployment/             # 部署文档
│   └── development/            # 开发文档
│
├── docker-compose.yml           # 统一配置（使用 profiles）
└── Makefile                     # 便捷命令
```

### 常用命令

```bash
# Docker 服务（推荐）
make docker-dev              # 启动开发环境
make docker-prod             # 启动生产环境
make docker-test-backend     # 测试后端
make docker-test-frontend    # 测试前端
make docker-logs             # 查看日志
make docker-down             # 停止服务

# OpenAPI 工作流
make openapi-validate        # 验证 API 规范
make openapi-gen             # 生成代码
make openapi-docs            # 生成文档

# 本地开发（不使用 Docker）
make install                 # 安装依赖
make dev-local               # 启动本地开发
make test                    # 运行测试
```

### 开发工作流

1. **启动开发环境**：
   ```bash
   make docker-dev
   ```

2. **修改代码**（自动热重载）：
   - 后端：编辑 `backend/` 下的 Go 文件
   - 前端：编辑 `frontend/src/` 下的 React 组件

3. **查看日志**：
   ```bash
   make docker-logs
   ```

4. **测试功能**：
   - 前端：http://localhost:5173
   - 后端：http://localhost:8080

5. **提交代码**：
   ```bash
   git add .
   git commit -m "feat: add new feature"
   git push
   ```

---

## 🧪 测试

### 后端测试

```bash
# 启动后端 Mock
make docker-test-backend-bg

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

# 测试登录
curl -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin123"}'

# 测试 API
curl http://localhost:8080/api/v1/registries
curl http://localhost:8080/api/v1/clusters
```

### 前端测试

```bash
# 启动前端 Mock
make docker-test-frontend-bg

# 访问前端
open http://localhost:3000
```

### 集成测试

```bash
# 启动完整环境
make docker-prod

# 运行测试套件
make test
```

---

## 📦 部署

### Docker Compose 部署（推荐）

```bash
# 1. 配置环境变量
export JWT_SECRET="your-production-secret"
export ENCRYPTION_KEY="your-32-byte-encryption-key"

# 2. 启动服务
docker compose up -d

# 3. 查看状态
docker compose ps
```

### Kubernetes 部署

查看 [Kubernetes 部署指南](./docs/deployment/kubernetes-guide.md)

---

## 🤝 贡献

欢迎贡献代码！请遵循以下步骤：

1. Fork 项目
2. 创建功能分支 (`git checkout -b feature/amazing-feature`)
3. 提交更改 (`git commit -m 'feat: add amazing feature'`)
4. 推送分支 (`git push origin feature/amazing-feature`)
5. 创建 Pull Request

### 开发规范

- **代码风格**：Go (gofmt)，TypeScript (ESLint + Prettier)
- **提交规范**：遵循 [Conventional Commits](https://www.conventionalcommits.org/)
- **测试覆盖**：新功能必须包含测试

---

## 📄 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情

---

## 🙏 致谢

- [Go](https://go.dev/) - 后端开发语言
- [React](https://react.dev/) - 前端框架
- [Vite](https://vitejs.dev/) - 构建工具
- [Docker](https://www.docker.com/) - 容器化平台
- [Kubernetes](https://kubernetes.io/) - 容器编排
- [Harbor](https://goharbor.io/) - OCI Registry

---

## 📞 联系方式

- **项目主页**：https://github.com/your-org/ocdp-go
- **问题反馈**：https://github.com/your-org/ocdp-go/issues
- **文档网站**：https://docs.ocdp.example.com

---

<div align="center">
  <sub>Built with ❤️ by the OCDP Team</sub>
</div>