YG_FT/backend/README.md

Backend Service

后端工程使用 FastAPI，定位为模型微调平台的应用平台服务，负责用户中心、多租户、权限隔离、项目、数据集、模型、训练任务、审批、审计和算力平台编排。

目录结构

backend/
  app/
    main.py                  # FastAPI 应用入口
    api/v1/                  # 对前端暴露的 接口路由
    core/                    # 配置、日志、中间件、权限等基础能力
    db/                      # 数据库连接、迁移集成、事务工具
    modules/                 # 业务模块
      auth/
      tenant/
      project/
      model/
      dataset/
      data_process/
      fine_tune/
      eval/
      inference/
      approval/
      audit/
      compute_gateway/
      file_gateway/
      engine_registry/
      retention/
      system/
    schemas/                 # Pydantic 入参/出参模型
    services/                # 跨模块应用服务
    workers/                 # 后台任务入口
  requirements.txt           # 后端第三方依赖
  config.example.yaml        # 可提交的脱敏配置模板
  config.yaml                # 本地配置，已忽略，环境变量可覆盖
  logs/                      # 本地开发日志目录，生产环境建议挂载到独立日志盘

配置

先复制本地配置并填写数据库凭据：

cp config.example.yaml config.yaml

后端默认读取 config.yaml，配置优先级为：

环境变量 > BACKEND_CONFIG_FILE 指定的 YAML > backend/config.yaml > 代码默认值

前后端端口、数据库地址、跨域来源、日志路径和计算状态轮询参数均可在 YAML 中 配置。敏感信息或不同环境的差异建议通过环境变量覆盖，不要写入仓库。YAML 中的 相对日志路径以该 YAML 文件所在目录为基准。使用其他配置文件时：

BACKEND_CONFIG_FILE=./config.prod.yaml uvicorn app.main:app --reload --port 17861

本机直连 PostgreSQL 时，数据库配置拆分为地址、用户名和密码：

server:
  frontend_port: 16801
  backend_port: 17861

database:
  url: postgresql+psycopg://localhost:5432/yg_ft
  username: yg_ft
  password: "change_me"

服务启动时会安全拼装完整连接串；用户名或密码中的特殊字符会自动编码。Docker 和生产环境仍可用完整的 DATABASE_URL 环境变量覆盖以上三项。

这里的 5432 是宿主机 PostgreSQL 默认端口；如果数据库容器映射到 15432， 将 YAML 中的端口改为 15432 即可。

server.frontend_port 和 server.backend_port 由根目录的 scripts/start-dev.sh 读取，并分别传给 Vite 和 Uvicorn。未配置 app.cors_allow_origins 时，本机 CORS 来源会跟随前端端口。直接手工执行 uvicorn 时仍需通过 --port 指定监听端口。

本地启动

cd backend
/opt/miniconda3/bin/python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload --port 17861

健康检查：

GET /modelTF/health

日志

日志模块位于 app/core/logging.py，使用说明见 ../docs/backend-logging.md。

默认日志文件：

logs/backend-YYYY-MM-DD.log
logs/error-YYYY-MM-DD.log

文件日志为 JSON Lines 格式，单个文件不超过 20MB，只保存最近 10 天，错误日志按 ERROR 级别独立拆分，便于 ELK/日志平台采集。