261 lines
5.3 KiB
Markdown
261 lines
5.3 KiB
Markdown
# OCDP Frontend
|
||
|
||
OCDP (Open Cloud Development Platform) Frontend - **Helm Chart 管理平台**
|
||
|
||
> 🎯 **专注于 Helm Charts**: 基于后端 OpenAPI 的前端应用，用于浏览、部署和管理 Helm Charts
|
||
|
||
---
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 1. 安装依赖
|
||
|
||
```bash
|
||
npm install
|
||
```
|
||
|
||
### 2. 选择开发模式
|
||
|
||
本项目支持三种运行模式，通过 `Makefile` 命令启动：
|
||
|
||
#### **Mode 0** - Mock API，热重载（推荐快速开发）
|
||
|
||
```bash
|
||
make run-0
|
||
```
|
||
|
||
- ✅ 前端：`localhost:5173`（Vite 热重载）
|
||
- ✅ 后端：Mock/Stub 数据（不需要真实后端）
|
||
- ✅ 适用：快速 UI 开发和调试
|
||
|
||
#### **Mode 1** - Real API，热重载（集成测试）
|
||
|
||
```bash
|
||
make run-1
|
||
```
|
||
|
||
- ✅ 前端：`localhost:5173`（Vite 热重载）
|
||
- ✅ 后端：真实 API（`http://localhost:8080`）
|
||
- ⚠️ 需要后端服务运行
|
||
|
||
#### **Mode 2** - Docker Compose 部署（生产测试）
|
||
|
||
```bash
|
||
make run-2
|
||
```
|
||
|
||
- ✅ 前端：`localhost:3000`（Nginx + Docker 容器）
|
||
- ✅ 后端：容器化部署
|
||
- ✅ 适用：生产环境测试
|
||
|
||
### 3. 清理（Mode 2）
|
||
|
||
```bash
|
||
make clean-2
|
||
```
|
||
|
||
---
|
||
|
||
## 📋 命令列表
|
||
|
||
| 命令 | 说明 |
|
||
|------|------|
|
||
| `make run-0` | Mode 0 - Mock API，热重载前端 |
|
||
| `make run-1` | Mode 1 - Real API，热重载前端 |
|
||
| `make run-2` | Mode 2 - Docker Compose 部署 |
|
||
| `make clean-2` | 清理 Mode 2 容器 |
|
||
|
||
---
|
||
|
||
## 🔌 Backend OpenAPI 集成
|
||
|
||
### 架构
|
||
|
||
```
|
||
backend/docs/openapi.yaml
|
||
↓
|
||
OpenAPI Generator
|
||
↓
|
||
src/api/generated/ (自动生成的 API 客户端)
|
||
↓
|
||
src/api/client.ts (封装层，支持 Mode 切换)
|
||
↓
|
||
React Components
|
||
```
|
||
|
||
### API 客户端使用
|
||
|
||
项目使用 OpenAPI Generator 生成的 TypeScript 客户端，根据运行模式自动切换：
|
||
|
||
- **Mode 0**: 使用 Mock 数据
|
||
- **Mode 1**: 调用真实后端 API（`localhost:8080`）
|
||
- **Mode 2**: Docker 环境，通过 Nginx 反向代理
|
||
|
||
### 使用示例
|
||
|
||
```typescript
|
||
import { api } from '@/api/client';
|
||
|
||
// 获取 Registries
|
||
const registries = await api.registries.list();
|
||
|
||
// 获取 Helm Chart 列表（自动过滤，只返回 Charts）
|
||
const charts = await api.artifacts.list('registry-id', 'repo-name');
|
||
|
||
// 获取 Chart 详情
|
||
const chart = await api.artifacts.get('registry-id', 'repo-name', 'version');
|
||
|
||
// 获取 Chart 的 values schema（用于部署配置）
|
||
const schema = await api.artifacts.getValuesSchema('registry-id', 'repo-name', 'version');
|
||
|
||
// 部署 Helm Chart
|
||
const instance = await api.instances.create({
|
||
name: 'my-app',
|
||
namespace: 'default',
|
||
registry_id: 'registry-id',
|
||
artifact_id: 'repo-name',
|
||
version: '1.0.0',
|
||
cluster_id: 'cluster-id'
|
||
});
|
||
```
|
||
|
||
### 重新生成 API Client
|
||
|
||
当后端 OpenAPI 规范更新时：
|
||
|
||
```bash
|
||
cd ..
|
||
make openapi-gen-frontend
|
||
```
|
||
|
||
---
|
||
|
||
## 🛠 技术栈
|
||
|
||
- **React 19** + **TypeScript** - UI 框架
|
||
- **Vite 7** - 构建工具和开发服务器
|
||
- **Tailwind CSS** - 样式框架
|
||
- **OpenAPI Generator** - API 客户端生成
|
||
- **Axios** - HTTP 客户端
|
||
- **React Router v7** - 路由管理
|
||
|
||
---
|
||
|
||
## 🎯 核心功能
|
||
|
||
- ✅ **Helm Chart 浏览**: 从 OCI Registry 浏览 Helm Charts（自动过滤）
|
||
- ✅ **Chart 部署**: 部署 Helm Chart 到 Kubernetes 集群
|
||
- ✅ **实例管理**: 管理已部署的 Helm Chart 实例
|
||
- ✅ **集群管理**: 管理 Kubernetes 集群连接
|
||
- ✅ **Registry 管理**: 管理 OCI Registry 配置
|
||
- ❌ **不支持**: 容器镜像管理（仅 Helm Charts）
|
||
|
||
---
|
||
|
||
## 📁 项目结构
|
||
|
||
```
|
||
frontend/
|
||
├── src/
|
||
│ ├── api/
|
||
│ │ ├── generated/ # 🤖 OpenAPI 自动生成的客户端
|
||
│ │ └── client.ts # API 客户端封装（Mode 切换）
|
||
│ ├── features/ # 功能模块
|
||
│ │ ├── auth/ # 认证
|
||
│ │ ├── artifact/ # Helm Charts
|
||
│ │ ├── configuration/ # 配置管理
|
||
│ │ └── monitoring/ # 监控
|
||
│ ├── shared/ # 共享组件
|
||
│ ├── app/ # 应用配置
|
||
│ └── main.tsx # 入口文件
|
||
├── Makefile # 开发命令（三种模式）
|
||
├── package.json # 依赖配置
|
||
├── vite.config.ts # Vite 配置
|
||
├── docker-compose.dev.yml # Docker Compose 配置
|
||
├── Dockerfile # 生产构建
|
||
└── nginx.conf # Nginx 配置
|
||
```
|
||
|
||
---
|
||
|
||
## 💡 开发工作流
|
||
|
||
### 日常开发（Mode 0）
|
||
|
||
```bash
|
||
make run-0
|
||
# 修改代码 → 自动热重载
|
||
```
|
||
|
||
### 集成测试（Mode 1）
|
||
|
||
```bash
|
||
# 1. 确保后端运行在 localhost:8080
|
||
cd ../backend
|
||
make run
|
||
|
||
# 2. 启动前端（Mode 1）
|
||
cd ../frontend
|
||
make run-1
|
||
```
|
||
|
||
### 生产测试（Mode 2）
|
||
|
||
```bash
|
||
make run-2
|
||
# 测试生产构建
|
||
# 完成后清理：
|
||
make clean-2
|
||
```
|
||
|
||
---
|
||
|
||
## 🐛 常见问题
|
||
|
||
### Mode 0 - 端口占用
|
||
|
||
```bash
|
||
lsof -ti:5173 | xargs kill -9
|
||
```
|
||
|
||
### Mode 1 - 后端连接失败
|
||
|
||
确保后端服务运行：
|
||
|
||
```bash
|
||
curl http://localhost:8080/health
|
||
```
|
||
|
||
### Mode 2 - 容器问题
|
||
|
||
```bash
|
||
# 查看日志
|
||
docker compose -f docker-compose.dev.yml logs -f
|
||
|
||
# 清理并重建
|
||
make clean-2
|
||
make run-2
|
||
```
|
||
|
||
### OpenAPI 客户端更新
|
||
|
||
```bash
|
||
# 在项目根目录执行
|
||
cd ..
|
||
make openapi-gen-frontend
|
||
```
|
||
|
||
---
|
||
|
||
## 📚 更多信息
|
||
|
||
- **后端项目**: `../backend`
|
||
- **OpenAPI 规范**: `../backend/docs/openapi.yaml`
|
||
- **查看所有命令**: `make help`
|
||
|
||
---
|
||
|
||
## 📄 License
|
||
|
||
MIT
|