OCDP/ocdp-go

Fork 0

Files

mangomqy c5e51ed069 ocdp v1

2025-11-13 02:54:06 +00:00

33 KiB

Raw Blame History

🚀 部署文档

快速开始

三种部署模式

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

使用 Makefile

# 查看所有命令
make help

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

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

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

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

验证服务

# 健康检查
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               │  │
│  └──────────────────────────────────┘  │
│                                         │
│  无外部依赖 ✨                          │
└─────────────────────────────────────────┘

环境准备

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

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

# 3. 验证安装
air -v

运行方式

方式 1: 使用 Makefile（推荐）

make mock

方式 2: 使用 Air

# 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

# 设置环境变量
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 已包含在项目中：

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 中的测试数据：

{
  "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

# 登录
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 密钥	-	✅

优势与限制

✅ 优势

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

❌ 限制

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

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 容器（隔离环境）                        │
└──────────────────────────────────────────────────────────┘

环境准备

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

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

# 3. 验证安装
air -v

运行步骤

步骤 1: 启动数据库

# 使用 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

验证数据库连接:

# 方式 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（推荐）

# 设置环境变量（首次）
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

# 设置环境变量
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

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

验证服务

# 健康检查
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 会自动检测并重启：

# 终端 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

开发工作流

# 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

管理服务

查看服务状态:

# 查看所有容器
docker compose ps

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

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

停止服务:

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

# 停止数据库
docker compose stop postgres

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

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

重启服务:

# 重启数据库
docker compose restart postgres

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

数据库管理

连接数据库:

# 使用 Makefile
make db

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

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

常用查询:

-- 查看所有表
\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

数据库备份与恢复:

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

{
  "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

Run → Edit Configurations
Add New → Go Build

配置：

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`	✅

生成密钥:

# JWT Secret
openssl rand -base64 32

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

故障排查

问题 1: 数据库连接失败

# 错误: connection refused

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

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

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

问题 2: 数据库未初始化

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

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

问题 3: 端口冲突

# 修改 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    │ │
│  └────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────┘

环境准备

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

目录结构

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

部署步骤

步骤 1: 准备环境变量

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

# 编辑环境变量
nano .env

.env 文件内容:

# 适配器模式
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

生成安全密钥:

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

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

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

步骤 2: 启动服务

使用 Makefile（推荐）:

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

手动启动:

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

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

步骤 3: 验证部署

# 健康检查
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

管理服务

停止服务:

# 停止所有服务
make stop

# 或
docker compose down

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

# 仅停止 Backend
docker compose stop backend

重启服务:

# 重启所有服务
make restart

# 或
docker compose restart

# 重启 Backend
docker compose restart backend

# 重启数据库
docker compose restart postgres

查看日志:

# 查看所有日志
make logs

# 或
docker compose logs -f

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

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

重新构建镜像

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

# 方式 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

数据备份和恢复

# 备份数据库
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 配置

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 配置

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

# 构建阶段
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 容器无法启动

# 查看容器日志
docker compose logs backend

# 查看容器状态
docker compose ps

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

问题 2: 数据库连接失败

# 检查数据库健康状态
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: 端口冲突

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

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

问题 4: 完全重置

# 停止所有服务
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 测试	日常开发 ⭐ 推荐	集成测试、生产预演
环境隔离	✅ 完全隔离	⚠️ 部分隔离	✅ 完全隔离
生产一致性	❌ 低	⚠️ 中	✅ 高

故障排查

通用问题

1. 端口被占用

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

# 关闭进程
kill -9 <PID>

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

2. Go 环境问题

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

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

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

3. Air 找不到命令

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

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

# 验证安装
air -v

Mock 模式问题

1. 服务无法启动

# 检查环境变量
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 数据未加载

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

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

Dev 模式问题

1. 数据库连接失败

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

# 检查端口
lsof -i :5432

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

# 重启数据库
docker compose restart postgres

2. 数据库未初始化

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

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

3. Air 热重载失败

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

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

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

Up 模式问题

1. Backend 容器无法启动

# 查看容器日志
docker compose logs backend

# 查看容器状态
docker compose ps

# 重新构建镜像
make up-rebuild

2. 镜像构建失败

# 清理 Docker 缓存
docker builder prune -a

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

# 检查 Dockerfile
cat Dockerfile

3. 容器健康检查失败

# 查看容器日志
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. 数据库连接超时

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

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

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

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

2. 数据丢失

# 检查数据卷
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. 权限问题

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

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

健康检查

# 服务健康检查
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

资源监控

# 查看容器资源使用
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 模式

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

# 重新启动
make mock

Dev 模式

# 停止服务
docker compose down

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

# 重新启动
make db-up
make dev

Up 模式

# 停止所有服务
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	数据库

33 KiB Raw Blame History Unescape Escape

🚀 部署文档

目录

快速开始

三种部署模式

使用 Makefile

验证服务

2.4.1 Mock 模式

概述

环境准备

运行方式

方式 1: 使用 Makefile（推荐）

方式 2: 使用 Air

方式 3: 直接运行 Go

热重载演示

配置文件

测试数据

测试 API

环境变量

优势与限制

✅ 优势

❌ 限制

2.4.2 Dev 模式

概述

环境准备

运行步骤

步骤 1: 启动数据库

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

验证服务

热重载演示

开发工作流

管理服务

数据库管理

IDE 调试配置

VS Code (launch.json)

GoLand / IntelliJ IDEA

环境变量

故障排查

2.4.3 Up 模式

概述

环境准备

目录结构

部署步骤

步骤 1: 准备环境变量

步骤 2: 启动服务

步骤 3: 验证部署

管理服务

重新构建镜像

数据备份和恢复

docker-compose.yml 配置

Dockerfile 配置

环境变量

故障排查

环境变量配置

环境变量对比

模式对比

推荐使用场景

🚀 Mock 模式

⭐ Dev 模式（推荐日常开发）

🎯 Up 模式

故障排查

通用问题

1. 端口被占用

2. Go 环境问题

3. Air 找不到命令

Mock 模式问题

1. 服务无法启动

2. Bootstrap 数据未加载

Dev 模式问题

1. 数据库连接失败

2. 数据库未初始化

3. Air 热重载失败

Up 模式问题

1. Backend 容器无法启动

2. 镜像构建失败

3. 容器健康检查失败

数据库问题

1. 数据库连接超时

2. 数据丢失

3. 权限问题

33 KiB

Raw Blame History