feat: 重构 Docker 配置结构，添加 compute 模块及新增文档

- 将 Dockerfile 和 docker-compose.yml 迁移至 docker/ 目录下统一管理 - 新增 compute 计算模块（API 入口、依赖配置） - 新增 docker/app 和 docker/compute 部署配置 - 新增 demo-development-plan.md 演示开发计划文档 - 更新后端 API 设计、部署计划、架构需求等文档 - 更新 postgres 数据库 schema Co-Authored-By: Claude <noreply@anthropic.com>
2026-07-20 14:59:31 +08:00
parent ba4059fe3b
commit 2c1e08a271
20 changed files with 1517 additions and 71 deletions
--- a/docker/README.md
+++ b/docker/README.md
@@ -0,0 +1,219 @@
+# Docker 部署说明
+
+本文档对应 `docs/deployment-plan.md`，按应用服务器和算力服务器拆分 Dockerfile 与 Docker Compose 文件。所有业务代码均通过 volume 外挂到容器内，镜像只包含运行时环境和第三方依赖。
+
+## 目录
+
+```text
+docker/
+  app/
+    Dockerfile.backend
+    Dockerfile.frontend
+    docker-compose.yml
+    .env.example
+  compute/
+    Dockerfile.compute
+    docker-compose.yml
+    .env.example
+```
+
+项目根目录不再保留 `Dockerfile` 和 `docker-compose.yml`，避免与应用服务器、算力服务器拆分部署入口混淆。
+
+## 应用服务器部署
+
+应用服务器包含前端 Nginx、Backend API、PostgreSQL、Redis。
+
+开发阶段默认由项目自带 PostgreSQL/Redis：
+
+```env
+USE_BUILTIN_POSTGRES=true
+USE_BUILTIN_REDIS=true
+DATABASE_URL=postgresql+asyncpg://yg_ft:change_me@postgres:5432/yg_ft
+REDIS_URL=redis://redis:6379/0
+```
+
+后续切换企业统一基础设施时，保留应用配置方式，只需要：
+
+- 修改 `DATABASE_URL` 指向企业 PostgreSQL。
+- 修改 `REDIS_URL` 指向企业 Redis。
+- 从 Compose 中移除或禁用 `postgres`、`redis` 服务。
+- 保留 `docs/postgres-schema.sql` 作为数据库初始化或迁移参考。
+
+首次部署前先构建前端产物：
+
+```bash
+cd docker/app
+cp .env.example .env
+docker compose --profile build run --rm frontend-builder
+docker compose up -d --build
+```
+
+默认访问地址：
+
+```text
+http://<app-server-ip>:6801
+```
+
+应用侧代码外挂：
+
+```text
+../../backend -> /app
+../../frontend/dist -> /usr/share/nginx/html
+../../runtime/app/logs/backend -> /opt/yg-ft/logs/backend
+../../runtime/app/data -> /data/yg-ft
+```
+
+如果算力服务独立部署，需要在 `docker/app/.env` 中修改：
+
+```env
+COMPUTE_API_BASE_URL=http://<compute-server-ip>:9100
+FILE_GATEWAY_BASE_URL=http://<compute-server-ip>:9101
+COMPUTE_SERVICE_TOKEN=change_me
+COMPUTE_STATUS_SYNC_MODE=polling
+COMPUTE_POLL_INTERVAL_SECONDS=10
+COMPUTE_POLL_BATCH_SIZE=100
+```
+
+状态同步采用应用侧定时轮询 Compute API 为主，避免算力服务器需要访问应用服务器，从而减少双向网络策略开通。
+
+## 应用服务与算力服务交互
+
+应用服务与算力服务之间只要求应用服务器主动访问算力服务器：
+
+```text
+Frontend
+  -> Backend API
+    -> Compute API
+      -> Compute Agent / LLaMA-Factory
+      -> 本地数据盘 / 模型目录 / 训练产物
+    <- Backend Worker 定时轮询 Compute API
+```
+
+默认交互流程：
+
+- `Backend API` 读取 `COMPUTE_API_BASE_URL`，向 `Compute API` 提交训练、评测、合并、导出等任务。
+- `Compute API` 在算力服务器上调度 `Compute Agent`。
+- `Compute Agent` 通过宿主机挂载目录调用 LLaMA-Factory，并读写 `/data/yg-ft` 下的数据集、模型和训练产物。
+- `Backend Worker` 按 `COMPUTE_POLL_INTERVAL_SECONDS` 定时轮询 Compute API，同步任务状态、训练指标、日志摘要和产物索引。
+- 前端只访问应用服务；文件下载和产物访问由应用服务完成权限校验后，再通过 `FILE_GATEWAY_BASE_URL` 获取受控资源。
+
+当前支持通过环境变量动态配置算力服务地址：
+
+```env
+COMPUTE_API_BASE_URL=http://<compute-server-ip>:9100
+FILE_GATEWAY_BASE_URL=http://<compute-server-ip>:9101
+COMPUTE_SERVICE_TOKEN=change_me
+COMPUTE_STATUS_SYNC_MODE=polling
+COMPUTE_POLL_INTERVAL_SECONDS=10
+COMPUTE_POLL_BATCH_SIZE=100
+```
+
+后续多算力节点阶段建议升级为数据库配置：在 `compute_nodes` 表中维护节点地址、服务 token、启用状态、权重、标签和健康状态，并通过“算力节点管理”页面动态启停节点，避免每次调整地址都重启应用服务。
+
+## 算力服务器部署
+
+算力服务器包含 Compute API、后续 Compute Agent、后续 File Gateway、GPU runtime、本地训练数据目录和宿主机挂载的 LLaMA-Factory。
+
+部署前需要安装：
+
+- NVIDIA Driver。
+- NVIDIA Container Toolkit。
+- Docker Engine 和 Docker Compose Plugin。
+- LLaMA-Factory 宿主机目录，默认 `/opt/LLaMA-Factory`。
+- 本地训练数据盘，默认 `/data/yg-ft`。
+
+算力服务器上的 LLaMA-Factory 使用宿主机挂载方式，不在当前 Compose 中重新构建 LLaMA-Factory 镜像：
+
+```env
+LLAMA_FACTORY_HOME=/opt/LLaMA-Factory
+LLAMA_FACTORY_HOST_PATH=/opt/LLaMA-Factory
+```
+
+启动：
+
+```bash
+cd docker/compute
+cp .env.example .env
+docker compose up -d --build
+```
+
+健康检查：
+
+```text
+GET http://<compute-server-ip>:9100/health
+GET http://<compute-server-ip>:9100/api/v1/compute/health
+```
+
+算力侧代码和数据外挂：
+
+```text
+../../compute -> /app/compute
+${LLAMA_FACTORY_HOST_PATH} -> /opt/LLaMA-Factory
+${YG_FT_DATA_ROOT_HOST} -> /data/yg-ft
+../../runtime/compute/logs -> /opt/yg-ft/logs/compute
+../../runtime/compute/training-logs -> /opt/yg-ft/logs/training
+```
+
+算力侧只需要允许应用服务器访问 Compute API/File Gateway，不要求访问应用服务器：
+
+```env
+ENABLE_APP_CALLBACK=false
+COMPUTE_SERVICE_TOKEN=change_me
+```
+
+## 多算力节点部署
+
+多算力节点仍按“单机多 GPU 节点”部署。每台 GPU 服务器都需要独立部署一套算力服务和宿主机挂载的 LLaMA-Factory：
+
+```text
+gpu-node-01: docker/compute + /opt/LLaMA-Factory + /data/yg-ft
+gpu-node-02: docker/compute + /opt/LLaMA-Factory + /data/yg-ft
+gpu-node-03: docker/compute + /opt/LLaMA-Factory + /data/yg-ft
+```
+
+节点之间默认不互相访问。应用服务器主动访问每个节点的 Compute API/File Gateway，并通过 `compute_nodes` 表或算力节点管理页面维护：
+
+- `api_base_url`
+- `file_gateway_url`
+- `enabled`
+- `scheduler_status`
+- `scheduler_weight`
+- `tags`
+- `data_root`
+- `model_root`
+- `log_root`
+
+长期使用每台算力服务器本地磁盘时，需要由应用平台维护资源副本关系。调度前先检查目标节点是否已有数据集和模型副本；如果没有，应用平台通过目标节点 File Gateway 创建资源同步任务，同步完成后再提交训练任务。
+
+## 单机所有服务部署在算力服务器
+
+在同一台 GPU 服务器上分别启动两套 Compose：
+
+```bash
+cd docker/app
+docker compose --profile build run --rm frontend-builder
+docker compose up -d --build
+
+cd ../compute
+docker compose up -d --build
+```
+
+应用侧 `.env` 中可使用：
+
+```env
+COMPUTE_API_BASE_URL=http://host.docker.internal:9100
+FILE_GATEWAY_BASE_URL=http://host.docker.internal:9101
+COMPUTE_STATUS_SYNC_MODE=polling
+```
+
+Linux 环境如需容器访问宿主机地址，可在应用侧 Compose 中按需增加 `extra_hosts: ["host.docker.internal:host-gateway"]`，或直接配置算力服务器内网 IP。
+
+## 生产注意事项
+
+- 当前 Compose 是工程部署骨架，后续 Backend Worker、Compute Agent、File Gateway 有可运行入口后，再拆分为独立服务。
+- PostgreSQL 和 Redis 开发阶段采用项目自带部署，生产阶段保留切换企业统一基础设施的配置入口。
+- 生产环境请把 `change_me` 替换为强密码或密钥管理系统注入。
+- 当前镜像默认优先保证宿主机外挂日志和数据目录可写；生产环境如需非 root 运行，需要统一宿主机目录 UID/GID 后在 Compose 中增加 `user` 配置。
+- Compute API 不应暴露公网，建议通过防火墙限制只允许应用服务器访问。
+- GPU 容器需要 NVIDIA Container Toolkit，否则 `gpus: all` 无法生效。
+- 前端 Nginx 默认挂载 `frontend/dist`，发布前需要先运行 `frontend-builder` 或由 CI 构建产物。
--- a/docker/app/.env.example
+++ b/docker/app/.env.example
@@ -0,0 +1,34 @@
+APP_ENV=prod
+APP_NAME=YG Fine-Tune Platform API
+API_PREFIX=/api
+
+POSTGRES_DB=yg_ft
+POSTGRES_USER=yg_ft
+POSTGRES_PASSWORD=change_me
+DATABASE_URL=postgresql+asyncpg://yg_ft:change_me@postgres:5432/yg_ft
+
+REDIS_URL=redis://redis:6379/0
+
+# Development uses the built-in PostgreSQL/Redis services in docker-compose.yml.
+# For enterprise infrastructure, replace DATABASE_URL/REDIS_URL and remove or disable those services.
+USE_BUILTIN_POSTGRES=true
+USE_BUILTIN_REDIS=true
+
+LOG_LEVEL=INFO
+LOG_DIR=/opt/yg-ft/logs/backend
+LOG_FILE_PREFIX=backend
+LOG_ERROR_FILE_PREFIX=error
+LOG_MAX_BYTES=20971520
+LOG_RETENTION_DAYS=10
+
+API_PROXY_PASS=http://backend-api:8000
+
+# Split deployment: set these to the compute server address, for example http://10.10.20.31:9100.
+COMPUTE_API_BASE_URL=http://compute-api:9100
+COMPUTE_SERVICE_TOKEN=change_me
+FILE_GATEWAY_BASE_URL=http://compute-api:9101
+
+# The application side polls Compute API for job state to avoid opening reverse network access.
+COMPUTE_STATUS_SYNC_MODE=polling
+COMPUTE_POLL_INTERVAL_SECONDS=10
+COMPUTE_POLL_BATCH_SIZE=100
--- a/docker/app/Dockerfile.backend
+++ b/docker/app/Dockerfile.backend
@@ -0,0 +1,21 @@
+# syntax=docker/dockerfile:1
+
+FROM python:3.11-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1
+
+WORKDIR /app
+
+COPY backend/requirements.txt /tmp/requirements.txt
+RUN pip install --upgrade pip \
+    && pip install -r /tmp/requirements.txt \
+    && rm -f /tmp/requirements.txt
+
+RUN mkdir -p /opt/yg-ft/logs/backend /data/yg-ft \
+    && chmod -R 0775 /opt/yg-ft /data/yg-ft
+
+EXPOSE 8000
+
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
--- a/docker/app/Dockerfile.frontend
+++ b/docker/app/Dockerfile.frontend
@@ -0,0 +1,10 @@
+# syntax=docker/dockerfile:1
+
+FROM nginx:1.27-alpine
+
+RUN mkdir -p /usr/share/nginx/html
+
+EXPOSE 80
+
+HEALTHCHECK --interval=30s --timeout=3s --start-period=10s --retries=3 \
+  CMD wget -qO- http://127.0.0.1/ >/dev/null || exit 1
--- a/docker/app/docker-compose.yml
+++ b/docker/app/docker-compose.yml
@@ -0,0 +1,122 @@
+services:
+  frontend-builder:
+    image: node:20-alpine
+    profiles:
+      - build
+    working_dir: /workspace
+    volumes:
+      - ../../frontend:/workspace
+      - frontend_node_modules:/workspace/node_modules
+    command: sh -c "npm ci && npm run build"
+
+  frontend:
+    build:
+      context: ../..
+      dockerfile: docker/app/Dockerfile.frontend
+    image: yg-ft-frontend-runtime:latest
+    container_name: yg-ft-frontend
+    depends_on:
+      backend-api:
+        condition: service_started
+    ports:
+      - "6801:80"
+    environment:
+      API_PROXY_PASS: ${API_PROXY_PASS:-http://backend-api:8000}
+    volumes:
+      - ../../frontend/dist:/usr/share/nginx/html:ro
+      - ../nginx.conf.template:/etc/nginx/templates/default.conf.template:ro
+    networks:
+      - yg-ft-app
+    restart: unless-stopped
+
+  backend-api:
+    build:
+      context: ../..
+      dockerfile: docker/app/Dockerfile.backend
+    image: yg-ft-backend-api:latest
+    container_name: yg-ft-backend-api
+    depends_on:
+      postgres:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
+    expose:
+      - "8000"
+    environment:
+      APP_ENV: ${APP_ENV:-prod}
+      APP_NAME: ${APP_NAME:-YG Fine-Tune Platform API}
+      API_PREFIX: ${API_PREFIX:-/api}
+      DATABASE_URL: ${DATABASE_URL:-postgresql+asyncpg://yg_ft:change_me@postgres:5432/yg_ft}
+      REDIS_URL: ${REDIS_URL:-redis://redis:6379/0}
+      USE_BUILTIN_POSTGRES: ${USE_BUILTIN_POSTGRES:-true}
+      USE_BUILTIN_REDIS: ${USE_BUILTIN_REDIS:-true}
+      LOG_LEVEL: ${LOG_LEVEL:-INFO}
+      LOG_DIR: ${LOG_DIR:-/opt/yg-ft/logs/backend}
+      LOG_FILE_PREFIX: ${LOG_FILE_PREFIX:-backend}
+      LOG_ERROR_FILE_PREFIX: ${LOG_ERROR_FILE_PREFIX:-error}
+      LOG_MAX_BYTES: ${LOG_MAX_BYTES:-20971520}
+      LOG_RETENTION_DAYS: ${LOG_RETENTION_DAYS:-10}
+      COMPUTE_API_BASE_URL: ${COMPUTE_API_BASE_URL:-http://compute-api:9100}
+      COMPUTE_SERVICE_TOKEN: ${COMPUTE_SERVICE_TOKEN:-change_me}
+      FILE_GATEWAY_BASE_URL: ${FILE_GATEWAY_BASE_URL:-http://compute-api:9101}
+      COMPUTE_STATUS_SYNC_MODE: ${COMPUTE_STATUS_SYNC_MODE:-polling}
+      COMPUTE_POLL_INTERVAL_SECONDS: ${COMPUTE_POLL_INTERVAL_SECONDS:-10}
+      COMPUTE_POLL_BATCH_SIZE: ${COMPUTE_POLL_BATCH_SIZE:-100}
+      PYTHONPATH: /app
+    volumes:
+      - ../../backend:/app:ro
+      - ../../runtime/app/logs/backend:/opt/yg-ft/logs/backend
+      - ../../runtime/app/data:/data/yg-ft
+    networks:
+      - yg-ft-app
+    healthcheck:
+      test: ["CMD-SHELL", "python -c \"import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/api/v1/health', timeout=3).read()\""]
+      interval: 30s
+      timeout: 5s
+      retries: 3
+      start_period: 20s
+    restart: unless-stopped
+
+  postgres:
+    image: postgres:16-alpine
+    container_name: yg-ft-postgres
+    environment:
+      POSTGRES_DB: ${POSTGRES_DB:-yg_ft}
+      POSTGRES_USER: ${POSTGRES_USER:-yg_ft}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-change_me}
+      PGDATA: /var/lib/postgresql/data/pgdata
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+      - ../../docs/postgres-schema.sql:/docker-entrypoint-initdb.d/001-schema.sql:ro
+    networks:
+      - yg-ft-app
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+    restart: unless-stopped
+
+  redis:
+    image: redis:7-alpine
+    container_name: yg-ft-redis
+    command: ["redis-server", "--appendonly", "yes"]
+    volumes:
+      - redis_data:/data
+    networks:
+      - yg-ft-app
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 10s
+      timeout: 3s
+      retries: 5
+    restart: unless-stopped
+
+networks:
+  yg-ft-app:
+    name: yg-ft-app
+
+volumes:
+  frontend_node_modules:
+  postgres_data:
+  redis_data:
--- a/docker/compute/.env.example
+++ b/docker/compute/.env.example
@@ -0,0 +1,19 @@
+COMPUTE_ENV=prod
+COMPUTE_HOST_ID=gpu-node-01
+COMPUTE_API_PORT=9100
+FILE_GATEWAY_PORT=9101
+
+# The application server actively polls Compute API; compute server does not need reverse access.
+COMPUTE_SERVICE_TOKEN=change_me
+ENABLE_APP_CALLBACK=false
+
+LLAMA_FACTORY_HOME=/opt/LLaMA-Factory
+LLAMA_FACTORY_HOST_PATH=/opt/LLaMA-Factory
+
+YG_FT_DATA_ROOT=/data/yg-ft
+YG_FT_DATA_ROOT_HOST=/data/yg-ft
+
+LOG_DIR=/opt/yg-ft/logs/compute
+CUDA_VISIBLE_DEVICES=all
+NVIDIA_VISIBLE_DEVICES=all
+NVIDIA_DRIVER_CAPABILITIES=compute,utility
--- a/docker/compute/Dockerfile.compute
+++ b/docker/compute/Dockerfile.compute
@@ -0,0 +1,37 @@
+# syntax=docker/dockerfile:1
+
+FROM nvidia/cuda:12.4.1-cudnn-runtime-ubuntu22.04
+
+ENV DEBIAN_FRONTEND=noninteractive \
+    PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1
+
+WORKDIR /app
+
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends \
+      python3 \
+      python3-pip \
+      python3-venv \
+      git \
+      curl \
+      ca-certificates \
+      tini \
+    && ln -sf /usr/bin/python3 /usr/local/bin/python \
+    && ln -sf /usr/bin/pip3 /usr/local/bin/pip \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY compute/requirements.txt /tmp/requirements.txt
+RUN pip install --upgrade pip \
+    && pip install -r /tmp/requirements.txt \
+    && rm -f /tmp/requirements.txt
+
+RUN mkdir -p /opt/yg-ft/logs/compute /opt/yg-ft/logs/training /data/yg-ft /opt/LLaMA-Factory \
+    && chmod -R 0775 /opt/yg-ft /data/yg-ft /opt/LLaMA-Factory
+
+ENTRYPOINT ["/usr/bin/tini", "--"]
+
+EXPOSE 9100
+
+CMD ["uvicorn", "compute.api.main:app", "--host", "0.0.0.0", "--port", "9100"]
--- a/docker/compute/docker-compose.yml
+++ b/docker/compute/docker-compose.yml
@@ -0,0 +1,41 @@
+services:
+  compute-api:
+    build:
+      context: ../..
+      dockerfile: docker/compute/Dockerfile.compute
+    image: yg-ft-compute-api:latest
+    container_name: yg-ft-compute-api
+    gpus: all
+    ports:
+      - "${COMPUTE_API_PORT:-9100}:9100"
+    environment:
+      COMPUTE_ENV: ${COMPUTE_ENV:-prod}
+      COMPUTE_HOST_ID: ${COMPUTE_HOST_ID:-gpu-node-01}
+      COMPUTE_SERVICE_TOKEN: ${COMPUTE_SERVICE_TOKEN:-change_me}
+      ENABLE_APP_CALLBACK: ${ENABLE_APP_CALLBACK:-false}
+      LLAMA_FACTORY_HOME: ${LLAMA_FACTORY_HOME:-/opt/LLaMA-Factory}
+      YG_FT_DATA_ROOT: ${YG_FT_DATA_ROOT:-/data/yg-ft}
+      LOG_DIR: ${LOG_DIR:-/opt/yg-ft/logs/compute}
+      CUDA_VISIBLE_DEVICES: ${CUDA_VISIBLE_DEVICES:-all}
+      NVIDIA_VISIBLE_DEVICES: ${NVIDIA_VISIBLE_DEVICES:-all}
+      NVIDIA_DRIVER_CAPABILITIES: ${NVIDIA_DRIVER_CAPABILITIES:-compute,utility}
+      PYTHONPATH: /app
+    volumes:
+      - ../../compute:/app/compute:ro
+      - ${LLAMA_FACTORY_HOST_PATH:-/opt/LLaMA-Factory}:${LLAMA_FACTORY_HOME:-/opt/LLaMA-Factory}
+      - ${YG_FT_DATA_ROOT_HOST:-/data/yg-ft}:${YG_FT_DATA_ROOT:-/data/yg-ft}
+      - ../../runtime/compute/logs:/opt/yg-ft/logs/compute
+      - ../../runtime/compute/training-logs:/opt/yg-ft/logs/training
+    networks:
+      - yg-ft-compute
+    healthcheck:
+      test: ["CMD-SHELL", "python -c \"import urllib.request; urllib.request.urlopen('http://127.0.0.1:9100/health', timeout=3).read()\""]
+      interval: 30s
+      timeout: 5s
+      retries: 3
+      start_period: 20s
+    restart: unless-stopped
+
+networks:
+  yg-ft-compute:
+    name: yg-ft-compute