# 🚀 部署文档

## 目录

- [快速开始](#快速开始)
- [2.4.1 Mock 模式](#241-mock-模式)
- [2.4.2 Dev 模式](#242-dev-模式)
- [2.4.3 Up 模式](#243-up-模式)
- [环境变量配置](#环境变量配置)
- [故障排查](#故障排查)

---

## 快速开始

### 三种部署模式

| 模式 | 命令 | Backend | 数据库 | 热重载 | 适用场景 |
|------|------|---------|--------|--------|----------|
| **Mock** | `make mock` | 本地 | 内存 | ✅ | 快速开发、API 测试 |
| **Dev** | `make db-up`<br>`make dev` | 本地 | Docker | ✅ | 日常开发 ⭐ 推荐 |
| **Up** | `make up` | Docker | Docker | ❌ | 集成测试、生产预演 |

### 使用 Makefile

```bash
# 查看所有命令
make help

# Mock 模式（零依赖，最快启动）
make mock

# Dev 模式（推荐日常开发）
make db-up   # 启动数据库
make dev     # 启动 Backend（热重载）

# Up 模式（完全容器化）
make up

# 管理服务
make logs    # 查看日志
make stop    # 停止服务
```

### 验证服务

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

# 测试 API
curl http://localhost:8080/api/v1/registries | jq

# 访问 Swagger UI
open http://localhost:8080/api/docs
```

---

# 2.4.1 Mock 模式

## 概述

Mock 模式使用内存存储，无需任何外部依赖，适合快速开发和测试。

**特点**:
- ✅ **零依赖** - 无需数据库、Docker 等
- ✅ **快速启动** - 3 秒内启动
- ✅ **热重载** - 支持 Air 自动重载
- ✅ **自带测试数据** - Bootstrap 预注入
- ✅ **无需容器** - 本地直接运行
- ❌ **数据不持久** - 重启后数据丢失

**适用场景**:
- 🚀 快速功能开发
- 🧪 API 接口测试
- 🎨 前端开发联调
- 📝 编写单元测试

**架构**:

```
┌─────────────────────────────────────────┐
│     Mock 模式（本地直接运行）            │
│                                         │
│  ┌──────────────────────────────────┐  │
│  │   OCDP Backend (Go Process)      │  │
│  │   Port: 8080                     │  │
│  │                                  │  │
│  │   ┌─────────────────────────┐   │  │
│  │   │  Air (Hot Reload)       │   │  │
│  │   │  监听文件变化自动重载     │   │  │
│  │   └─────────────────────────┘   │  │
│  │                                  │  │
│  │   Adapter: Mock                 │  │
│  │   Storage: Memory               │  │
│  └──────────────────────────────────┘  │
│                                         │
│  无外部依赖 ✨                          │
└─────────────────────────────────────────┘
```

---

## 环境准备

```bash
# 1. 确保已安装 Go
go version  # 需要 Go 1.21+

# 2. 安装 Air（热重载工具）
go install github.com/air-verse/air@latest

# 3. 验证安装
air -v
```

---

## 运行方式

### 方式 1: 使用 Makefile（推荐）

```bash
make mock
```

### 方式 2: 使用 Air

```bash
# 1. 设置环境变量
export ADAPTER_MODE=mock
export PORT=8080
export JWT_SECRET=dev-secret-key

# 2. 启动 Air
air -c .air.toml

# 输出示例:
#   __    _   ___
#  / /\  | | | |_)
# /_/--\ |_| |_| \_ v1.49.0
# 
# watching .
# building...
# running...
# 🚀 Starting OCDP Backend (mode=mock)
# 🌐 Server starting on :8080
```

### 方式 3: 直接运行 Go

```bash
# 设置环境变量
export ADAPTER_MODE=mock
export PORT=8080
export JWT_SECRET=dev-secret-key

# 运行
go run cmd/api/main.go
```

---

## 热重载演示

修改任何 `.go` 文件后，Air 会自动检测并重启：

```
main.go has changed
building...
running...
🚀 Starting OCDP Backend (mode=mock)
🌐 Server starting on :8080
```

**支持的文件类型**:
- `.go` - Go 源文件
- `.yaml`, `.json` - 配置文件
- `.toml` - Air 配置文件

---

## 配置文件

Air 配置文件 `.air.toml` 已包含在项目中：

```toml
root = "."
testdata_dir = "testdata"
tmp_dir = "tmp"

[build]
  cmd = "go build -o ./tmp/main cmd/api/main.go"
  bin = "./tmp/main"
  include_ext = ["go", "tpl", "tmpl", "html", "yaml", "json"]
  exclude_dir = ["assets", "tmp", "vendor", "testdata"]
  exclude_regex = ["_test.go"]
  delay = 1000
```

---

## 测试数据

Mock 模式自动加载 `config/bootstrap.json` 中的测试数据：

```json
{
  "enabled": true,
  "users": [
    {
      "username": "admin",
      "password": "admin123",
      "email": "admin@example.com"
    }
  ],
  "registries": [
    {
      "name": "Harbor Production",
      "url": "https://harbor.example.com",
      "username": "admin",
      "password": "secret"
    }
  ],
  "clusters": [
    {
      "name": "Production Cluster",
      "host": "https://k8s.example.com:6443",
      "description": "生产环境集群"
    }
  ]
}
```

---

## 测试 API

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

# 响应:
# {
#   "accessToken": "eyJhbGciOiJIUzI1NiIs...",
#   "userId": "user-123",
#   "username": "admin"
# }

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

# 查看 Clusters
curl http://localhost:8080/api/v1/clusters | jq
```

---

## 环境变量

| 变量 | 说明 | 默认值 | 必需 |
|------|------|--------|------|
| `ADAPTER_MODE` | 适配器模式 | `mock` | ✅ |
| `PORT` | 服务端口 | `8080` | ❌ |
| `JWT_SECRET` | JWT 密钥 | - | ✅ |

---

## 优势与限制

### ✅ 优势

1. **启动极快** - 3 秒内启动，无需等待数据库
2. **零配置** - 无需配置数据库连接、证书等
3. **自带数据** - Bootstrap 自动注入测试数据
4. **热重载** - 代码修改立即生效
5. **易于调试** - 本地运行，支持 IDE 断点调试
6. **完美测试** - 适合 API 测试和前端联调

### ❌ 限制

1. **数据不持久** - 重启后数据丢失
2. **功能简化** - 某些功能（如真实 K8s 操作）被模拟
3. **不适合生产** - 仅用于开发调试

---

# 2.4.2 Dev 模式

## 概述

Dev 模式使用 Docker 运行 PostgreSQL 数据库，Backend 在本地热重载运行，适合日常开发。

**特点**:
- ✅ **隔离的依赖服务** - 数据库在容器中，避免污染本地环境
- ✅ **本地热重载** - Backend 支持 Air 自动重载
- ✅ **完整的 IDE 支持** - 断点调试、代码补全、性能分析
- ✅ **快速迭代** - 代码修改立即生效，无需重新构建镜像
- ✅ **数据持久化** - PostgreSQL 数据持久保存
- ✅ **最佳开发体验** - 兼顾隔离性和开发效率

**适用场景**:
- 📝 **日常功能开发** ⭐ 最推荐
- 🐛 **代码调试** - 支持 IDE 断点
- 🔄 **快速迭代** - 热重载提升效率
- 🧪 **数据持久化测试** - 验证数据库操作

**架构**:

```
┌──────────────────────────────────────────────────────────┐
│       Dev 模式（部分容器化，推荐日常开发）                 │
│                                                          │
│  ┌────────────────────────┐    ┌────────────────────┐  │
│  │  OCDP Backend          │    │   PostgreSQL       │  │
│  │  (本地进程)             │───▶│   (Docker 容器)     │  │
│  │  Port: 8080            │    │   Port: 5432       │  │
│  │                        │    │                    │  │
│  │  ┌─────────────────┐  │    │  Volume:           │  │
│  │  │  Air (Hot Reload) │  │    │  postgres_data     │  │
│  │  └─────────────────┘  │    └────────────────────┘  │
│  └────────────────────────┘                            │
│                                                          │
│  Backend: 本地运行（热重载）                              │
│  Database: Docker 容器（隔离环境）                        │
└──────────────────────────────────────────────────────────┘
```

---

## 环境准备

```bash
# 1. 确保已安装 Docker 和 Docker Compose
docker --version
docker compose version

# 2. 安装 Air（热重载工具）
go install github.com/air-verse/air@latest

# 3. 验证安装
air -v
```

---

## 运行步骤

### 步骤 1: 启动数据库

```bash
# 使用 Makefile（推荐）
make db-up

# 或手动启动
docker compose up -d postgres

# 等待数据库启动（查看健康状态）
docker compose ps

# 预期输出:
# NAME              IMAGE                  STATUS                    PORTS
# ocdp-postgres     postgres:17-alpine     Up 10s (healthy)          0.0.0.0:5432->5432/tcp
```

**验证数据库连接**:

```bash
# 方式 1: 使用 psql
psql -h localhost -U postgres -d ocdp

# 方式 2: 使用 Docker
docker exec -it ocdp-postgres psql -U postgres -d ocdp

# 测试查询
SELECT current_database();
\q
```

---

### 步骤 2: 启动 Backend（热重载）

**选项 A: 使用 Makefile（推荐）**

```bash
# 设置环境变量（首次）
export DATABASE_URL="postgresql://postgres:postgres@localhost:5432/ocdp?sslmode=disable"
export ENCRYPTION_KEY="12345678901234567890123456789012"

# 启动 Backend
make dev

# 输出:
# 🚀 启动 Dev 模式 - Backend（本地热重载）...
# 🔌 Connecting to database...
# ✅ Database connected
# 🌱 Bootstrap seeding...
# 🌐 Server starting on :8080
```

**选项 B: 使用 Air**

```bash
# 设置环境变量
export ADAPTER_MODE=production
export PORT=8080
export JWT_SECRET=dev-secret-key
export ENCRYPTION_KEY=12345678901234567890123456789012
export DATABASE_URL="postgresql://postgres:postgres@localhost:5432/ocdp?sslmode=disable"

# 启动 Air
air -c .air.toml
```

**选项 C: 直接运行 Go**

```bash
export ADAPTER_MODE=production
export DATABASE_URL="postgresql://postgres:postgres@localhost:5432/ocdp?sslmode=disable"
export JWT_SECRET=dev-secret-key
export ENCRYPTION_KEY=12345678901234567890123456789012

go run cmd/api/main.go
```

---

## 验证服务

```bash
# 健康检查
curl http://localhost:8080/health
# 输出: {"status":"healthy"}

# 注册用户
curl -X POST http://localhost:8080/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "testuser",
    "password": "test123",
    "email": "test@example.com"
  }'

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

---

## 热重载演示

修改代码后，Air 会自动检测并重启：

```bash
# 终端 1: Air 运行中
# 修改文件: internal/domain/service/cluster_service.go

# Air 输出:
# cluster_service.go has changed
# building...
# running...
# 🚀 Starting OCDP Backend (mode=production)
# 🔌 Connecting to database...
# ✅ Database connected
# 🌐 Server starting on :8080

# 终端 2: 测试
curl http://localhost:8080/api/v1/clusters | jq
```

---

## 开发工作流

```bash
# 1. 启动数据库（首次或停止后）
make db-up

# 2. 启动 Backend（热重载）
make dev

# 3. 修改代码
vim internal/domain/service/cluster_service.go
# Air 自动检测并重启

# 4. 测试 API
curl http://localhost:8080/api/v1/clusters | jq

# 5. 查看数据库
make db
SELECT * FROM users;
\q

# 6. 停止服务
# - Backend: Ctrl+C
# - Database: make stop
```

---

## 管理服务

**查看服务状态**:

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

# 查看 PostgreSQL 日志
docker compose logs -f postgres

# 查看 Backend 日志（在 Air 终端中）
```

**停止服务**:

```bash
# 停止 Backend: 在 Air 终端按 Ctrl+C

# 停止数据库
docker compose stop postgres

# 停止并删除容器（数据保留）
docker compose down

# 停止并删除容器和数据卷（⚠️ 数据丢失）
docker compose down -v
```

**重启服务**:

```bash
# 重启数据库
docker compose restart postgres

# 重启 Backend: 在 Air 终端按 Ctrl+C 后重新运行 make dev
```

---

## 数据库管理

**连接数据库**:

```bash
# 使用 Makefile
make db

# 使用 psql
psql -h localhost -U postgres -d ocdp

# 或使用 Docker
docker exec -it ocdp-postgres psql -U postgres -d ocdp
```

**常用查询**:

```sql
-- 查看所有表
\dt

-- 查看用户
SELECT id, username, email, created_at FROM users;

-- 查看 Registry
SELECT id, name, url, created_at FROM registries;

-- 查看集群
SELECT id, name, host, created_at FROM clusters;

-- 清空测试数据
TRUNCATE users, registries, clusters, instances CASCADE;

-- 退出
\q
```

**数据库备份与恢复**:

```bash
# 备份
docker exec ocdp-postgres pg_dump -U postgres ocdp > backup-$(date +%Y%m%d).sql

# 恢复
docker exec -i ocdp-postgres psql -U postgres ocdp < backup.sql

# 压缩备份
docker exec ocdp-postgres pg_dump -U postgres ocdp | gzip > backup.sql.gz

# 从压缩文件恢复
gunzip -c backup.sql.gz | docker exec -i ocdp-postgres psql -U postgres ocdp
```

---

## IDE 调试配置

### VS Code (launch.json)

```json
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Launch OCDP Backend (Dev Mode)",
      "type": "go",
      "request": "launch",
      "mode": "auto",
      "program": "${workspaceFolder}/cmd/api/main.go",
      "env": {
        "ADAPTER_MODE": "production",
        "PORT": "8080",
        "JWT_SECRET": "dev-secret-key",
        "ENCRYPTION_KEY": "12345678901234567890123456789012",
        "DATABASE_URL": "postgresql://postgres:postgres@localhost:5432/ocdp?sslmode=disable"
      },
      "args": []
    }
  ]
}
```

### GoLand / IntelliJ IDEA

1. Run → Edit Configurations
2. Add New → Go Build
3. 配置：
   - **Files**: `cmd/api/main.go`
   - **Working directory**: 项目根目录
   - **Environment**:
     ```
     ADAPTER_MODE=production
     PORT=8080
     JWT_SECRET=dev-secret-key
     ENCRYPTION_KEY=12345678901234567890123456789012
     DATABASE_URL=postgresql://postgres:postgres@localhost:5432/ocdp?sslmode=disable
     ```

---

## 环境变量

| 变量 | 说明 | 示例 | 必需 |
|------|------|------|------|
| `ADAPTER_MODE` | 适配器模式 | `production` | ✅ |
| `PORT` | 服务端口 | `8080` | ❌ |
| `JWT_SECRET` | JWT 密钥 | `dev-secret` | ✅ |
| `ENCRYPTION_KEY` | 加密密钥（32字节） | `12345678901234567890123456789012` | ✅ |
| `DATABASE_URL` | 数据库连接 | `postgresql://postgres:postgres@localhost:5432/ocdp?sslmode=disable` | ✅ |

**生成密钥**:

```bash
# JWT Secret
openssl rand -base64 32

# Encryption Key（32 字节）
openssl rand -base64 32
```

---

## 故障排查

**问题 1: 数据库连接失败**

```bash
# 错误: connection refused

# 检查数据库是否启动
docker compose ps postgres

# 检查端口
netstat -tuln | grep 5432
# 或
lsof -i :5432

# 测试连接
psql -h localhost -U postgres -d ocdp -c "SELECT 1;"
```

**问题 2: 数据库未初始化**

```bash
# 重新初始化数据库
docker compose down postgres
docker compose up -d postgres

# 等待健康检查通过
docker compose ps postgres
```

**问题 3: 端口冲突**

```bash
# 修改 docker-compose.yml 中的端口映射
# ports:
#   - "5433:5432"  # 使用 5433 而不是 5432

# 更新 DATABASE_URL
export DATABASE_URL="postgresql://postgres:postgres@localhost:5433/ocdp?sslmode=disable"
```

---

# 2.4.3 Up 模式

## 概述

Up 模式使用 Docker Compose 完全容器化部署，PostgreSQL 和 Backend 都在容器中运行。

**特点**:
- ✅ **完全容器化** - 一致的运行环境
- ✅ **一键部署** - 简单快速
- ✅ **接近生产** - 与生产环境高度一致
- ✅ **易于分享** - 团队成员快速启动相同环境
- ❌ **无热重载** - 代码修改需重新构建镜像
- ❌ **调试受限** - 需要通过日志调试

**适用场景**:
- 🧪 **集成测试** - 测试完整系统
- 🎯 **生产预演** - 验证部署流程
- 👥 **团队协作** - 快速搭建统一环境
- 📦 **交付演示** - 向客户展示系统

**架构**:

```
┌──────────────────────────────────────────────────────────┐
│           Up 模式（完全容器化）                           │
│                                                          │
│  ┌────────────────────────────────────────────────────┐ │
│  │         Docker Compose Network                     │ │
│  │                                                    │ │
│  │  ┌──────────────────┐    ┌──────────────────┐   │ │
│  │  │  OCDP Backend    │    │   PostgreSQL     │   │ │
│  │  │  (Docker 容器)    │───▶│   (Docker 容器)   │   │ │
│  │  │  Port: 8080      │    │   Port: 5432     │   │ │
│  │  └──────────────────┘    └──────────────────┘   │ │
│  │                                                    │ │
│  └────────────────────────────────────────────────────┘ │
│                                                          │
│  ┌────────────────────────────────────────────────────┐ │
│  │         Persistent Volumes                         │ │
│  │         postgres_data: /var/lib/postgresql/data    │ │
│  └────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────┘
```

---

## 环境准备

```bash
# 确保已安装 Docker 和 Docker Compose
docker --version
docker compose version
```

---

## 目录结构

```
backend/
├── docker-compose.yml       # Docker Compose 配置
├── Dockerfile              # Backend 镜像
├── .env                    # 环境变量
├── env.example             # 环境变量示例
└── config/
    └── bootstrap.json      # 初始数据（可选）
```

---

## 部署步骤

### 步骤 1: 准备环境变量

```bash
# 复制示例文件
cp env.example .env

# 编辑环境变量
nano .env
```

**.env 文件内容**:

```bash
# 适配器模式
ADAPTER_MODE=production

# 端口配置
BACKEND_PORT=8080
POSTGRES_PORT=5432

# 安全密钥（⚠️ 生产环境必须修改）
JWT_SECRET=your-jwt-secret-change-in-production
ENCRYPTION_KEY=your-32-character-encryption-key-here

# 数据库配置
POSTGRES_DB=ocdp
POSTGRES_USER=postgres
POSTGRES_PASSWORD=your-postgres-password-change-it

# 数据库连接 URL（容器内部使用）
DATABASE_URL=postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}?sslmode=disable
```

**生成安全密钥**:

```bash
# 生成随机 JWT Secret
openssl rand -base64 32

# 生成随机 Encryption Key（32 字节）
openssl rand -base64 32

# 生成随机数据库密码
openssl rand -base64 16
```

---

### 步骤 2: 启动服务

**使用 Makefile（推荐）**:

```bash
make up

# 查看服务状态
docker compose ps

# 预期输出:
# NAME              IMAGE                  STATUS              PORTS
# ocdp-backend      backend:latest         Up 30s (healthy)    0.0.0.0:8080->8080/tcp
# ocdp-postgres     postgres:17-alpine     Up 40s (healthy)    0.0.0.0:5432->5432/tcp
```

**手动启动**:

```bash
# 使用 profile 启动完整服务
docker compose --profile backend up -d

# 查看日志
docker compose logs -f backend postgres
```

---

### 步骤 3: 验证部署

```bash
# 健康检查
curl http://localhost:8080/health
# 输出: {"status":"healthy"}

# 测试 API
curl http://localhost:8080/api/v1/registries | jq

# 访问 Swagger UI
open http://localhost:8080/api/docs

# 查看容器状态
docker compose ps

# 进入 Backend 容器
docker compose exec backend sh

# 连接数据库
make db
```

---

## 管理服务

**停止服务**:

```bash
# 停止所有服务
make stop

# 或
docker compose down

# 停止并删除数据卷（⚠️ 会删除数据）
docker compose down -v

# 仅停止 Backend
docker compose stop backend
```

**重启服务**:

```bash
# 重启所有服务
make restart

# 或
docker compose restart

# 重启 Backend
docker compose restart backend

# 重启数据库
docker compose restart postgres
```

**查看日志**:

```bash
# 查看所有日志
make logs

# 或
docker compose logs -f

# 查看 Backend 日志
docker compose logs -f backend

# 查看最近 100 行
docker compose logs --tail=100 backend
```

---

## 重新构建镜像

**代码修改后需要重新构建**:

```bash
# 方式 1: 使用 Makefile
make up-build

# 方式 2: 手动构建
docker compose build backend
docker compose --profile backend up -d

# 方式 3: 强制重新构建（不使用缓存）
make up-rebuild

# 或
docker compose build --no-cache backend
docker compose --profile backend up -d
```

---

## 数据备份和恢复

```bash
# 备份数据库
docker compose exec postgres pg_dump -U postgres ocdp > backup-$(date +%Y%m%d).sql

# 恢复数据库
docker compose exec -T postgres psql -U postgres ocdp < backup.sql

# 导出为压缩文件
docker compose exec postgres pg_dump -U postgres ocdp | gzip > backup-$(date +%Y%m%d).sql.gz

# 从压缩文件恢复
gunzip -c backup.sql.gz | docker compose exec -T postgres psql -U postgres ocdp
```

---

## docker-compose.yml 配置

```yaml
version: '3.8'

services:
  # PostgreSQL 数据库
  postgres:
    image: postgres:17-alpine
    container_name: ocdp-postgres
    environment:
      - POSTGRES_DB=${POSTGRES_DB:-ocdp}
      - POSTGRES_USER=${POSTGRES_USER:-postgres}
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
    ports:
      - "${POSTGRES_PORT:-5432}:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data
      - ${INIT_DB_SQL_PATH:-./scripts/init-db.sql}:/docker-entrypoint-initdb.d/01-init.sql:ro
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-postgres} -d ${POSTGRES_DB:-ocdp}"]
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped
    networks:
      - ocdp-network

  # Backend 服务（需要 --profile backend 才启动）
  backend:
    profiles: ["backend"]
    build:
      context: .
      dockerfile: Dockerfile
    container_name: ocdp-backend
    ports:
      - "${BACKEND_PORT:-8080}:8080"
    environment:
      - ADAPTER_MODE=${ADAPTER_MODE:-production}
      - PORT=8080
      - JWT_SECRET=${JWT_SECRET}
      - ENCRYPTION_KEY=${ENCRYPTION_KEY}
      - DATABASE_URL=postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}?sslmode=disable
    depends_on:
      postgres:
        condition: service_healthy
    restart: unless-stopped
    networks:
      - ocdp-network
    healthcheck:
      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:8080/health"]
      interval: 30s
      timeout: 3s
      retries: 3
      start_period: 40s

networks:
  ocdp-network:
    driver: bridge

volumes:
  postgres_data:
    driver: local
```

> 💡 **提示**  
> 如果与仓库根目录下的 `docker-compose.yml` 联合使用（例如通过 `docker compose -f docker-compose.yml -f backend/docker-compose.yml --profile backend ...`），请确保设置环境变量 `INIT_DB_SQL_PATH=./backend/scripts/init-db.sql`（或绝对路径），以便 PostgreSQL 容器挂载到正确的初始化脚本。

---

## Dockerfile 配置

```dockerfile
# 多阶段构建，优化镜像大小

# 构建阶段
FROM golang:1.21-alpine AS builder

WORKDIR /app

# 复制依赖文件
COPY go.mod go.sum ./
RUN go mod download

# 复制源代码
COPY . .

# 编译（静态链接）
RUN CGO_ENABLED=0 GOOS=linux go build -a -installsuffix cgo -ldflags '-w -s' -o ocdp-backend cmd/api/main.go

# 运行阶段
FROM alpine:latest

# 安装 CA 证书
RUN apk --no-cache add ca-certificates tzdata wget

# 设置时区
ENV TZ=Asia/Shanghai

WORKDIR /root/

# 复制二进制文件
COPY --from=builder /app/ocdp-backend .

# 复制配置文件（如果有）
COPY config/ config/

# 暴露端口
EXPOSE 8080

# 健康检查
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:8080/health || exit 1

# 运行
CMD ["./ocdp-backend"]
```

---

## 环境变量

| 变量 | 说明 | 示例 | 必需 |
|------|------|------|------|
| `ADAPTER_MODE` | 适配器模式 | `production` | ✅ |
| `BACKEND_PORT` | Backend 端口 | `8080` | ❌ |
| `POSTGRES_PORT` | PostgreSQL 端口 | `5432` | ❌ |
| `JWT_SECRET` | JWT 密钥 | `随机字符串` | ✅ |
| `ENCRYPTION_KEY` | 加密密钥（32字节） | `随机字符串` | ✅ |
| `POSTGRES_DB` | 数据库名 | `ocdp` | ✅ |
| `POSTGRES_USER` | 数据库用户 | `postgres` | ✅ |
| `POSTGRES_PASSWORD` | 数据库密码 | `随机字符串` | ✅ |
| `DATABASE_URL` | 数据库连接 | `postgresql://...` | ✅ |

---

## 故障排查

**问题 1: Backend 容器无法启动**

```bash
# 查看容器日志
docker compose logs backend

# 查看容器状态
docker compose ps

# 重新构建镜像
docker compose build --no-cache backend
docker compose --profile backend up -d
```

**问题 2: 数据库连接失败**

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

# 查看数据库日志
docker compose logs postgres

# 检查网络连接
docker compose exec backend ping postgres

# 等待数据库完全启动后重启 Backend
sleep 10
docker compose restart backend
```

**问题 3: 端口冲突**

```bash
# 修改 .env 文件中的端口
BACKEND_PORT=8081
POSTGRES_PORT=5433

# 重新启动
docker compose down
docker compose --profile backend up -d
```

**问题 4: 完全重置**

```bash
# 停止所有服务
docker compose down

# 删除数据卷（⚠️ 会删除数据）
docker compose down -v

# 清理 Docker 系统
docker system prune -a --volumes

# 重新部署
make up
```

---

# 环境变量配置

## 环境变量对比

| 变量 | Mock | Dev | Up | 说明 |
|------|------|-----|-----|------|
| `ADAPTER_MODE` | `mock` | `production` | `production` | 适配器模式 |
| `PORT` | `8080` | `8080` | `8080` | 服务端口 |
| `JWT_SECRET` | 简单值 | 开发值 | 强随机值 | JWT 密钥 |
| `ENCRYPTION_KEY` | - | 开发值 | 强随机值 | 加密密钥 |
| `DATABASE_URL` | - | 本地 PostgreSQL | 容器内 PostgreSQL | 数据库连接 |

---

## 模式对比

| 特性 | Mock | Dev | Up |
|------|------|-----|-----|
| **Backend 运行位置** | 本地进程 | 本地进程 | Docker 容器 |
| **依赖服务** | 无 | Docker (PostgreSQL) | Docker (PostgreSQL) |
| **热重载** | ✅ Air | ✅ Air | ❌ 需重新构建 |
| **数据库** | ❌ 内存 | ✅ PostgreSQL | ✅ PostgreSQL |
| **数据持久化** | ❌ | ✅ | ✅ |
| **启动时间** | 3 秒 | 5-8 秒 | 15-30 秒 |
| **调试能力** | ✅ IDE 断点 | ✅ IDE 断点 | ⚠️ 日志调试 |
| **适用场景** | 快速开发、API 测试 | 日常开发 ⭐ 推荐 | 集成测试、生产预演 |
| **环境隔离** | ✅ 完全隔离 | ⚠️ 部分隔离 | ✅ 完全隔离 |
| **生产一致性** | ❌ 低 | ⚠️ 中 | ✅ 高 |

---

## 推荐使用场景

### 🚀 Mock 模式
- ✅ 快速功能开发
- ✅ API 接口测试
- ✅ 前端联调
- ✅ 单元测试

### ⭐ Dev 模式（推荐日常开发）
- ✅ 日常功能开发
- ✅ 代码调试
- ✅ 数据持久化测试
- ✅ 快速迭代

### 🎯 Up 模式
- ✅ 集成测试
- ✅ 生产环境预演
- ✅ 团队协作环境搭建
- ✅ 交付演示

---

# 故障排查

## 通用问题

### 1. 端口被占用

```bash
# 查找占用端口的进程
lsof -i :8080
# 或
netstat -tuln | grep 8080

# 关闭进程
kill -9 <PID>

# 或使用其他端口
export PORT=8081
```

### 2. Go 环境问题

```bash
# 检查 Go 版本
go version  # 需要 Go 1.21+

# 更新 Go 模块
go mod download
go mod tidy

# 清理 Go 缓存
go clean -cache -modcache
```

### 3. Air 找不到命令

```bash
# 确保 GOPATH/bin 在 PATH 中
export PATH=$PATH:$(go env GOPATH)/bin

# 重新安装 Air
go install github.com/air-verse/air@latest

# 验证安装
air -v
```

---

## Mock 模式问题

### 1. 服务无法启动

```bash
# 检查环境变量
echo $ADAPTER_MODE  # 应该是 mock
echo $PORT          # 应该是 8080
echo $JWT_SECRET    # 不应为空

# 手动运行查看详细错误
export ADAPTER_MODE=mock
export JWT_SECRET=test-secret
go run cmd/api/main.go
```

### 2. Bootstrap 数据未加载

```bash
# 检查 bootstrap.json 文件
cat config/bootstrap.json

# 确保 enabled 为 true
# {
#   "enabled": true,
#   ...
# }
```

---

## Dev 模式问题

### 1. 数据库连接失败

```bash
# 检查 PostgreSQL 是否运行
docker compose ps postgres

# 检查端口
lsof -i :5432

# 测试连接
psql -h localhost -U postgres -d ocdp -c "SELECT 1;"

# 重启数据库
docker compose restart postgres
```

### 2. 数据库未初始化

```bash
# 重新初始化数据库
docker compose down postgres
docker compose up -d postgres

# 等待健康检查通过
docker compose ps postgres
```

### 3. Air 热重载失败

```bash
# 清理临时文件
rm -rf tmp/

# 重新启动 Air
air -c .air.toml

# 检查 .air.toml 配置
cat .air.toml
```

---

## Up 模式问题

### 1. Backend 容器无法启动

```bash
# 查看容器日志
docker compose logs backend

# 查看容器状态
docker compose ps

# 重新构建镜像
make up-rebuild
```

### 2. 镜像构建失败

```bash
# 清理 Docker 缓存
docker builder prune -a

# 重新构建
docker compose build --no-cache backend

# 检查 Dockerfile
cat Dockerfile
```

### 3. 容器健康检查失败

```bash
# 查看容器日志
docker compose logs backend

# 手动执行健康检查
docker compose exec backend wget --no-verbose --tries=1 --spider http://localhost:8080/health

# 检查 healthcheck 配置
docker compose config | grep -A 5 healthcheck
```

---

## 数据库问题

### 1. 数据库连接超时

```bash
# 检查数据库是否启动完成
docker compose ps postgres

# 查看数据库日志
docker compose logs postgres

# 手动测试连接
docker compose exec postgres pg_isready -U postgres

# 等待更长时间
sleep 10
docker compose restart backend
```

### 2. 数据丢失

```bash
# 检查数据卷
docker volume ls | grep postgres

# 备份当前数据
docker compose exec postgres pg_dump -U postgres ocdp > backup.sql

# 恢复数据
docker compose exec -T postgres psql -U postgres ocdp < backup.sql
```

### 3. 权限问题

```bash
# 检查数据卷权限
docker volume inspect ocdp_postgres_data

# 重新创建数据卷
docker compose down -v
docker compose up -d postgres
```

---

## 健康检查

```bash
# 服务健康检查
curl http://localhost:8080/health
# 预期: {"status":"healthy"}

# 数据库健康检查
# Docker 方式
docker compose exec postgres pg_isready -U postgres

# 本地方式
pg_isready -h localhost -p 5432 -U postgres

# 检查所有服务状态
docker compose ps
```

---

## 资源监控

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

# 查看磁盘使用
docker system df

# 查看日志大小
du -sh $(docker inspect --format='{{.LogPath}}' ocdp-backend)
du -sh $(docker inspect --format='{{.LogPath}}' ocdp-postgres)

# 清理 Docker 资源
docker system prune -a --volumes
```

---

## 完全重置

### Mock 模式

```bash
# 清理临时文件
rm -rf tmp/

# 重新启动
make mock
```

### Dev 模式

```bash
# 停止服务
docker compose down

# 删除数据卷（⚠️ 数据丢失）
docker compose down -v

# 重新启动
make db-up
make dev
```

### Up 模式

```bash
# 停止所有服务
docker compose down

# 删除数据卷（⚠️ 数据丢失）
docker compose down -v

# 清理 Docker 系统
docker system prune -a --volumes

# 重新部署
make up
```

---

## 服务访问地址

| 服务 | Mock | Dev | Up | 说明 |
|------|------|-----|-----|------|
| **Backend API** | http://localhost:8080/api/v1 | http://localhost:8080/api/v1 | http://localhost:8080/api/v1 | REST API |
| **Health Check** | http://localhost:8080/health | http://localhost:8080/health | http://localhost:8080/health | 健康检查 |
| **Swagger UI** | http://localhost:8080/api/docs | http://localhost:8080/api/docs | http://localhost:8080/api/docs | API 文档 |
| **PostgreSQL** | - | localhost:5432 | localhost:5432 | 数据库 |

---

## 相关文档

- [架构文档](architecture.md) - 六边形架构、技术选型
- [API 与测试](api-and-test.md) - API 文档、测试指南
- [主 README](../README.md) - 项目概览

---

**Last Updated**: 2025-11-09  
**Version**: v3.0.0