# OCDP 命令速查表

快速查找常用的 Docker 和 Make 命令。

---

## 🚀 快速启动

```bash
# 开发环境（推荐，Mock 模式）
make docker-dev

# 生产环境（真实数据库）
make docker-prod

# 测试后端（独立）
make docker-test-backend

# 测试前端（独立）
make docker-test-frontend
```

---

## 📋 完整命令列表

### Docker 服务管理

| 命令 | 说明 | 模式 |
|------|------|------|
| `make docker-dev` | 启动开发环境（前台） | Dev |
| `make docker-dev-bg` | 启动开发环境（后台） | Dev |
| `make docker-prod` | 启动生产环境 | Production |
| `make docker-up` | 同 docker-prod | Production |
| `make docker-down` | 停止所有服务 | - |
| `make docker-down-v` | 停止并删除数据卷 | - |

### 服务测试

| 命令 | 说明 | 端口 |
|------|------|------|
| `make docker-test-backend` | 测试后端（前台） | 8080 |
| `make docker-test-backend-bg` | 测试后端（后台） | 8080 |
| `make docker-test-frontend` | 测试前端（前台） | 3000 |
| `make docker-test-frontend-bg` | 测试前端（后台） | 3000 |

### 日志查看

| 命令 | 说明 |
|------|------|
| `make docker-logs` | 查看所有服务日志 |
| `make docker-logs-backend` | 只看后端日志 |
| `make docker-logs-frontend` | 只看前端日志 |
| `make docker-logs-db` | 只看数据库日志 |

### 服务状态

| 命令 | 说明 |
|------|------|
| `make docker-ps` | 查看服务状态 |
| `make docker-status` | 查看详细状态（含健康检查） |

### 镜像管理

| 命令 | 说明 |
|------|------|
| `make docker-build` | 构建所有镜像 |
| `make docker-build-no-cache` | 无缓存构建 |
| `make docker-restart` | 重启所有服务 |
| `make docker-restart-backend` | 只重启后端 |
| `make docker-restart-frontend` | 只重启前端 |

### 工具服务

| 命令 | 说明 | 端口 |
|------|------|------|
| `make docker-tools` | 启动 pgAdmin + Swagger UI | 5050, 8081 |

---

## 🔧 原始 Docker Compose 命令

### 开发模式

```bash
# 启动（前台）
docker compose -f docker-compose.yml -f docker-compose.dev.yml up

# 启动（后台）
docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d

# 停止
docker compose -f docker-compose.yml -f docker-compose.dev.yml down

# 查看日志
docker compose -f docker-compose.yml -f docker-compose.dev.yml logs -f

# 重启服务
docker compose -f docker-compose.yml -f docker-compose.dev.yml restart backend
```

### 生产模式

```bash
# 启动（前台）
docker compose up

# 启动（后台）
docker compose up -d

# 停止
docker compose down

# 查看日志
docker compose logs -f

# 重启服务
docker compose restart backend
```

### Mock 模式

```bash
# 测试后端
docker compose -f docker-compose.mock.yml up backend

# 测试前端
docker compose -f docker-compose.mock.yml up frontend

# 后台运行
docker compose -f docker-compose.mock.yml up -d backend

# 停止
docker compose -f docker-compose.mock.yml down
```

---

## 🛠️ 本地开发命令（不使用 Docker）

### 安装依赖

```bash
make install              # 安装所有依赖
make install-tools        # 安装 OpenAPI 工具
make install-deps         # 安装项目依赖
```

### 启动服务

```bash
make dev-local            # 启动完整环境
make dev-backend-mock     # 只启动后端（Mock）
make dev-backend-prod     # 只启动后端（生产）
make dev-frontend         # 只启动前端
```

### OpenAPI 工作流

```bash
make openapi-validate     # 验证 OpenAPI 规范
make openapi-gen          # 生成前后端代码
make openapi-gen-backend  # 只生成后端代码
make openapi-gen-frontend # 只生成前端代码
make openapi-docs         # 生成 HTML 文档
make openapi-view         # 启动文档服务器
```

### 测试

```bash
make test                 # 运行所有测试
make test-backend         # 运行后端测试
make test-frontend        # 运行前端测试
```

### 清理

```bash
make clean                # 清理构建产物
make clean-generated      # 清理生成的代码
```

---

## 📊 常用 Docker 命令

### 容器操作

```bash
# 进入容器
docker compose exec backend sh
docker compose exec frontend sh
docker compose exec postgres psql -U postgres -d ocdp

# 查看容器列表
docker compose ps

# 查看容器详情
docker compose ps -a

# 删除容器
docker compose rm backend
docker compose rm -f backend  # 强制删除

# 停止特定容器
docker compose stop backend
docker compose stop frontend
```

### 日志操作

```bash
# 实时日志
docker compose logs -f

# 只看特定服务
docker compose logs -f backend

# 显示最后 N 行
docker compose logs --tail=100 backend

# 显示时间戳
docker compose logs -f -t backend

# 不跟随（只显示现有）
docker compose logs backend
```

### 镜像操作

```bash
# 构建镜像
docker compose build

# 无缓存构建
docker compose build --no-cache

# 只构建特定服务
docker compose build backend
docker compose build frontend

# 查看镜像
docker images | grep ocdp

# 删除镜像
docker rmi ocdp-backend
docker rmi ocdp-frontend
```

### 数据卷操作

```bash
# 查看数据卷
docker volume ls

# 删除特定数据卷
docker volume rm ocdp_postgres_data
docker volume rm ocdp_redis_data

# 删除所有未使用的数据卷
docker volume prune

# 备份数据卷
docker run --rm -v ocdp_postgres_data:/data -v $(pwd):/backup alpine tar czf /backup/postgres_backup.tar.gz -C /data .

# 恢复数据卷
docker run --rm -v ocdp_postgres_data:/data -v $(pwd):/backup alpine sh -c "cd /data && tar xzf /backup/postgres_backup.tar.gz"
```

### 网络操作

```bash
# 查看网络
docker network ls

# 查看网络详情
docker network inspect ocdp-network

# 测试网络连通性
docker compose exec backend ping frontend
docker compose exec frontend ping backend
```

---

## 🔍 调试命令

### 健康检查

```bash
# 后端健康检查
curl http://localhost:8080/health

# 前端健康检查
curl http://localhost:5173/    # Dev 模式
curl http://localhost:3000/    # Production 模式

# 数据库健康检查
docker compose exec postgres pg_isready -U postgres
```

### API 测试

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

# 获取 Registries
curl http://localhost:8080/api/v1/registries

# 获取 Clusters
curl http://localhost:8080/api/v1/clusters

# 获取 Repositories
curl http://localhost:8080/api/v1/registries/harbor-prod/repositories

# 获取 Artifacts（带过滤）
curl "http://localhost:8080/api/v1/registries/harbor-prod/repositories/charts%2Fvllm-serve/artifacts?media_type=chart"
```

### 数据库操作

```bash
# 连接数据库
docker compose exec postgres psql -U postgres -d ocdp

# 查看表
docker compose exec postgres psql -U postgres -d ocdp -c "\dt"

# 查询数据
docker compose exec postgres psql -U postgres -d ocdp -c "SELECT * FROM registries;"

# 执行 SQL 文件
docker compose exec -T postgres psql -U postgres -d ocdp < schema.sql
```

### 性能监控

```bash
# 查看资源使用
docker stats

# 只看特定容器
docker stats ocdp-backend ocdp-frontend

# 查看容器进程
docker compose top backend
docker compose top frontend
```

---

## 🎯 常用组合命令

### 完全重置

```bash
# 停止并删除所有内容
docker compose down -v
docker compose -f docker-compose.dev.yml down -v
docker compose -f docker-compose.mock.yml down -v

# 删除镜像
docker rmi $(docker images | grep ocdp | awk '{print $3}')

# 重新构建
make docker-build

# 重新启动
make docker-dev
```

### 更新代码后重新部署

```bash
# 停止服务
make docker-down

# 拉取最新代码
git pull

# 重新构建
make docker-build

# 启动服务
make docker-dev
```

### 查看完整系统状态

```bash
# 查看所有容器
docker compose ps

# 查看所有日志
make docker-logs

# 查看健康状态
make docker-status

# 测试所有服务
curl http://localhost:8080/health
curl http://localhost:5173/
curl http://localhost:5432  # 数据库端口
```

---

## 📝 环境变量

### 后端环境变量

```bash
# Mock 模式
export ADAPTER_MODE=mock
export JWT_SECRET=dev-secret
export ENCRYPTION_KEY=dev-encryption-key-32-bytes-long

# Production 模式
export ADAPTER_MODE=production
export DATABASE_URL=postgresql://postgres:postgres@postgres:5432/ocdp?sslmode=disable
export JWT_SECRET=your-production-secret
export ENCRYPTION_KEY=your-production-encryption-key-32-bytes
```

### 前端环境变量

```bash
export VITE_API_BASE_URL=http://localhost:8080/api/v1
export VITE_USE_MOCK=false
```

---

## 🆘 故障排查命令

### 问题诊断

```bash
# 查看完整日志
docker compose logs --tail=1000 > debug.log

# 查看特定时间段日志
docker compose logs --since 10m backend

# 查看容器详细信息
docker compose exec backend env

# 检查配置
docker compose config

# 验证 docker-compose.yml
docker compose -f docker-compose.yml config
docker compose -f docker-compose.dev.yml config
```

### 端口冲突检查

```bash
# 查看端口占用
sudo lsof -i :8080
sudo lsof -i :5173
sudo lsof -i :3000
sudo lsof -i :5432

# 杀死进程
sudo kill -9 <PID>
```

### 磁盘空间清理

```bash
# 删除未使用的容器
docker container prune

# 删除未使用的镜像
docker image prune

# 删除未使用的数据卷
docker volume prune

# 删除所有未使用的资源
docker system prune -a --volumes
```

---

## 💡 实用技巧

### 1. 后台运行并查看日志

```bash
make docker-dev-bg && make docker-logs
```

### 2. 重启并查看日志

```bash
docker compose restart backend && docker compose logs -f backend
```

### 3. 构建并启动

```bash
make docker-build && make docker-dev
```

### 4. 清理并重新开始

```bash
make docker-down && docker system prune -f && make docker-dev
```

### 5. 快速测试 API

```bash
# 保存 token
TOKEN=$(curl -s -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin123"}' | jq -r '.token')

# 使用 token
curl -H "Authorization: Bearer $TOKEN" http://localhost:8080/api/v1/registries
```

---

## 📚 更多资源

- [快速开始](./QUICK_START.md)
- [Docker 服务架构](./DOCKER_SERVICES.md)
- [项目重构总结](./PROJECT_RESTRUCTURE_SUMMARY.md)
- [README](./README.md)

---

<div align="center">
  <sub>命令速查表 - 最后更新：2025-11-09</sub>
</div>