YG_FT/docker

Docker 部署说明

本目录按应用服务器和算力服务器拆分 Dockerfile 与 Docker Compose 文件。Compose 文件不包含 build:，不会在 docker compose up 时自动构建业务镜像。所有业务镜像需要先通过手动 docker build 构建，再由 Compose 启动。

基础镜像

镜像	用途
python:3.12-slim	应用后端基础镜像，后端运行环境要求 Python 3.12 及以上
nginx:1.27-alpine	前端静态资源与 /modelTF 反向代理运行镜像
hiyouga/llamafactory:latest	算力服务基础镜像，基于 LLaMA-Factory 官方镜像扩展 Compute API
postgres:16-alpine	开发阶段内置 PostgreSQL
redis:7-alpine	开发阶段内置 Redis

一键拉取基础镜像：

docker pull python:3.12-slim && \
docker pull nginx:1.27-alpine && \
docker pull hiyouga/llamafactory:latest && \
docker pull postgres:16-alpine && \
docker pull redis:7-alpine

Windows PowerShell：

$images = @(
  "python:3.12-slim",
  "nginx:1.27-alpine",
  "hiyouga/llamafactory:latest",
  "postgres:16-alpine",
  "redis:7-alpine"
)
$images | ForEach-Object { docker pull $_ }

如果部署环境不能访问外网，需要提前在可联网环境执行上述拉取命令，再用 docker save / docker load 导出导入。

业务镜像

镜像	Dockerfile	构建命令
yg-ft-backend-api:latest	docker/app/Dockerfile.backend	docker build -f docker/app/Dockerfile.backend -t yg-ft-backend-api:latest .
yg-ft-frontend-runtime:latest	docker/app/Dockerfile.frontend	docker build -f docker/app/Dockerfile.frontend -t yg-ft-frontend-runtime:latest .
yg-ft-compute-api:latest	docker/compute/Dockerfile.compute	docker build -f docker/compute/Dockerfile.compute -t yg-ft-compute-api:latest .

对外端口

所有宿主机对外端口统一使用 5 位端口。容器内部端口保持镜像默认端口，便于容器内服务和健康检查稳定。

服务	宿主机对外端口	容器内部端口	说明
前端 Nginx	16801	80	前端页面入口
后端 API	17861	8000	FastAPI 服务
PostgreSQL	15432	5432	开发阶段内置数据库
Redis	16379	6379	开发阶段内置缓存
Compute API	19100	9100	算力服务器 API
File Gateway	19101	9100	当前由 Compute API 暴露文件网关契约，后续可拆为独立服务

注意：8000 是后端容器内部端口，不作为宿主机对外访问端口。宿主机或浏览器应访问 http://<app-server-ip>:17861/modelTF/health；前端 Nginx 容器在 Docker 网络内部访问 http://backend-api:8000/modelTF/...。

对应配置文件：

• docker/app/.env.example
  • FRONTEND_PORT=16801
  • BACKEND_API_PORT=17861
  • POSTGRES_PORT=15432
  • REDIS_PORT=16379
• docker/compute/.env.example
  • COMPUTE_API_PORT=19100
  • FILE_GATEWAY_PORT=19101

运行模式

• 应用侧默认 COMPUTE_MODE=real，任务状态必须由真实算力同步逻辑更新。
• 算力侧默认 COMPUTE_EXECUTION_MODE=real，真实执行器未完成前不会伪造训练作业。
• 仅隔离联调时可显式设置 COMPUTE_MODE=simulator 或 COMPUTE_EXECUTION_MODE=simulator，该模式不得用于测试环境、生产环境或生产升级基线。

应用服务器部署

应用服务器包含前端 Nginx、Backend API、PostgreSQL、Redis。

当前 Compose 内置 PostgreSQL 使用 backend/app/db/sql/001_platform_runtime.sql 初始化运行库。docs/postgres-schema.sql 是完整目标架构设计，不应直接挂载为当前运行库初始化脚本，否则会与当前后端代码的运行表结构不兼容。

首次部署：

cd <repo-root>

# 1. 使用当前 Windows/宿主机 npm 构建前端静态产物
cd frontend
npm ci
npm run build
cd ..

# 2. 手动构建业务镜像
docker build -f docker/app/Dockerfile.backend -t yg-ft-backend-api:latest .
docker build -f docker/app/Dockerfile.frontend -t yg-ft-frontend-runtime:latest .

# 3. 启动应用服务
cd docker/app
cp .env.example .env
docker compose up -d

后端镜像构建过程中会执行依赖导入自检，确认 fastapi、uvicorn、psycopg、sqlalchemy、redis 等运行依赖已安装。构建后也可以手动检查：

docker run --rm yg-ft-backend-api:latest python -c "import psycopg; print(psycopg.__version__)"

默认访问地址：

http://<app-server-ip>:16801

应用侧代码和数据外挂：

../../backend -> /app
../../frontend/dist -> /usr/share/nginx/html
../../runtime/app/logs/backend -> /opt/yg-ft/logs/backend
../../runtime/app/data -> /data/yg-ft

前端容器启动前必须确保 ../../frontend/dist/index.html 已存在。若前端 Nginx 日志出现 directory index of "/usr/share/nginx/html/" is forbidden 或 rewrite or internal redirection cycle while internally redirecting to "/index.html"，通常表示当前执行 docker compose 的项目目录下没有构建好的 frontend/dist，或挂载路径不是同一份代码目录。

# 在执行 docker compose 的同一份代码目录中检查
cd <repo-root>/frontend
npm run build
test -f dist/index.html && ls -lh dist/index.html

cd ../docker/app
docker compose up -d --force-recreate frontend
docker compose logs --tail=80 frontend

如果使用 Windows npm 构建、WSL 中运行 Docker Compose，需要确认 Windows 路径和 WSL 路径指向同一份仓库。例如在 D:\...\YG_FT\frontend 构建不会自动生成 /mnt/d/wuyongtao/Code/YG_FT/frontend/dist 下的产物，除非二者本就是同一个目录。

如果使用企业统一 PostgreSQL/Redis，修改 docker/app/.env：

如果前端 Nginx 日志出现 open() "/usr/share/nginx/html/modelTF/login" failed 或 open() "/usr/share/nginx/html/login" failed，说明当前容器没有加载项目的 Nginx 代理配置，/modelTF/* 被当成静态文件查找。处理方式：

cd <repo-root>/docker/app
docker compose up -d --force-recreate frontend
docker compose exec frontend nginx -T | grep -n "location.*modelTF" -A12

正常配置中应存在 location ^~ /modelTF/，并代理到 BACKEND_PROXY_PASS，默认是 http://backend-api:8000。

DATABASE_URL=postgresql+psycopg://<user>:<password>@<postgres-host>:15432/<db>
REDIS_URL=redis://<redis-host>:16379/0
USE_BUILTIN_POSTGRES=false
USE_BUILTIN_REDIS=false

生产环境如完全使用外部基础设施，可以删除或注释 Compose 中的 postgres、redis 服务及 backend-api.depends_on 中对应依赖。

算力服务器部署

算力服务器包含 Compute API、后续 Compute Agent、File Gateway、GPU runtime、本地训练数据目录和 LLaMA-Factory。Dockerfile.compute 基于 LLaMA-Factory 官方镜像：

FROM hiyouga/llamafactory:latest

部署前需要安装：

• NVIDIA Driver
• NVIDIA Container Toolkit
• Docker Engine 和 Docker Compose Plugin
• 本地训练数据目录，默认 /data/yg-ft

首次部署：

cd <repo-root>

# 手动构建算力业务镜像
docker build -f docker/compute/Dockerfile.compute -t yg-ft-compute-api:latest .

# 启动算力服务
cd docker/compute
cp .env.example .env
docker compose up -d

健康检查：

GET http://<compute-server-ip>:19100/modelTF/health
GET http://<compute-server-ip>:19100/modelTF/v1/compute/health

算力侧代码和数据外挂：

../../compute -> /app/compute
${YG_FT_DATA_ROOT_HOST} -> /data/yg-ft
${YG_FT_MODEL_ROOT_HOST} -> /data/yg-ft/models
${YG_FT_DATASET_ROOT_HOST} -> /data/yg-ft/datasets
${YG_FT_OUTPUT_ROOT_HOST} -> /data/yg-ft/outputs
${COMPUTE_LOG_ROOT_HOST} -> /opt/yg-ft/logs/compute
${TRAINING_LOG_ROOT_HOST} -> /opt/yg-ft/logs/training

算力服务器启动前必须先在宿主机创建持久化目录，基座模型、训练数据、训练产物和训练日志都应落在宿主机磁盘上，不能只写入容器层。推荐默认目录：

cd <repo-root>/docker/compute
mkdir -p data/yg-ft/models \
  data/yg-ft/datasets \
  data/yg-ft/outputs \
  data/yg-ft/logs/compute \
  data/yg-ft/logs/training

默认 docker/compute/.env.example 使用 ./data/yg-ft，该相对路径以 docker/compute/docker-compose.yml 所在目录为基准，因此实际宿主机目录是 <repo-root>/docker/compute/data/yg-ft。如企业环境模型盘、数据盘、产物盘分盘挂载，可在 docker/compute/.env 中分别调整 YG_FT_MODEL_ROOT_HOST、YG_FT_DATASET_ROOT_HOST、YG_FT_OUTPUT_ROOT_HOST、COMPUTE_LOG_ROOT_HOST、TRAINING_LOG_ROOT_HOST，容器内路径建议保持 /data/yg-ft/models、/data/yg-ft/datasets、/data/yg-ft/outputs，避免训练参数和节点配置复杂化。

页面上传数据集时，文件先进入 Backend API，再由 Backend API 调用目标算力节点的 POST /modelTF/compute/files/upload，写入容器内 /data/yg-ft/datasets/{dataset_id}/。在默认开发配置下，宿主机可在 <repo-root>/docker/compute/data/yg-ft/datasets/{dataset_id}/ 看到对应文件。仅创建 bind mount 不会自动让应用侧上传文件出现在算力目录，必须通过这条 File Gateway 链路同步。

应用与算力分离部署

应用服务器只需要主动访问算力服务器，不要求算力服务器回调应用服务器。

在 docker/app/.env 中配置：

COMPUTE_API_BASE_URL=http://<compute-server-ip>:19100
FILE_GATEWAY_BASE_URL=http://<compute-server-ip>:19101
COMPUTE_SERVICE_TOKEN=change_me
COMPUTE_STATUS_SYNC_MODE=polling
COMPUTE_POLL_INTERVAL_SECONDS=3
COMPUTE_POLL_BATCH_SIZE=100

交互链路：

Frontend
  -> Backend API
    -> Compute API
      -> Compute Agent / LLaMA-Factory
      -> 本地数据目录 / 模型目录 / 训练产物
    <- Backend Worker 定时轮询 Compute API

算力服务默认开启服务间鉴权。docker/compute/.env 中保持 COMPUTE_AUTH_ENABLED=true，并确保 COMPUTE_SERVICE_TOKEN 与 docker/app/.env 一致；健康检查路径仍可用于容器探活。

多算力节点部署

多算力节点仍按“单机多 GPU 节点”部署。每台 GPU 服务器都独立部署一套 docker/compute：

gpu-node-01: docker/compute + /data/yg-ft + 19100/19101
gpu-node-02: docker/compute + /data/yg-ft + 19100/19101
gpu-node-03: docker/compute + /data/yg-ft + 19100/19101

节点之间默认不互访。应用平台主动访问每个节点的 Compute API/File Gateway，并通过 compute_nodes、resource_replicas、resource_sync_jobs 统一调度和同步。

节点地址、权重、标签、启用状态和本地路径在前端“算力节点”页面动态维护。新增或编辑节点后，点击“测试”会由 Backend API 主动访问该节点的 GET /modelTF/v1/compute/health 和 GET /modelTF/compute/resources/gpus，并把健康信息与 GPU 清单同步到 PostgreSQL。

常用命令

重新构建应用镜像：

docker build -f docker/app/Dockerfile.backend -t yg-ft-backend-api:latest .
docker build -f docker/app/Dockerfile.frontend -t yg-ft-frontend-runtime:latest .

重新构建算力镜像：

docker build -f docker/compute/Dockerfile.compute -t yg-ft-compute-api:latest .

启动服务：

cd docker/app
docker compose up -d

cd ../compute
docker compose up -d

查看服务：

docker compose ps
docker compose logs -f