Docker 部署文档

环境要求

Docker >= 20.10
Docker Compose >= 2.0
外部 PostgreSQL 数据库（生产环境）

一、配置文件说明

文件	用途
`Dockerfile`	应用镜像构建，基于 `python:3.12-slim`，使用 `uv` 管理依赖
`docker-compose.yml`	生产环境配置，连接外部 PostgreSQL，容器启动自动执行数据库迁移
`docker-compose.dev.yml`	开发环境覆盖配置，含本地 PostgreSQL + 代码热重载
`.env`	环境变量（数据库、SSO、密钥等），不会被打包进镜像
`.dockerignore`	构建排除项（`venv/`、`__pycache__/`、`.env` 等）

二、环境配置

构建前确保项目根目录下 .env 文件已配置，参考 .env.example：

# PostgreSQL 数据库配置（必填）
DB_HOST=47.109.147.74
DB_PORT=5432
DB_USER=maas_collect
DB_PASSWORD=your_db_password
DB_NAME=maas_collect

# Flask 密钥（生产环境请更换为随机字符串）
SECRET_KEY=change-me-to-a-random-secret

# JWT 密钥（生产环境请更换为随机字符串）
JWT_SECRET_KEY=jwt-secret-change-me-to-random-string

# SSO 统一认证配置
SSO_BASE_URL=http://192.168.92.61:8200
SSO_CLIENT_ID=your_client_id
SSO_CLIENT_SECRET=your_client_secret
SSO_REDIRECT_URI=http://localhost:5000/auth/callback
SSO_FRONTEND_URL=http://localhost:5000
SSO_SCOPE=email
SSO_LOGOUT_REDIRECT_URL=http://192.168.92.61:9200/login

# 样本中心配置
SAMPLE_CENTER_BASE_URL=http://192.168.92.61
SAMPLE_CENTER_APP_ID=your-app-id
SAMPLE_CENTER_APP_SECRET=your-app-secret

注意：生产部署时 DB_HOST、DB_USER、DB_PASSWORD、DB_NAME 为必填项，docker-compose.yml 中无默认回退值。

三、生产部署

3.1 构建并启动

docker compose up -d --build

启动流程：

Docker 构建镜像（安装系统依赖 + Python 依赖 + Playwright）
从 .env 读取环境变量注入容器
容器启动时 entrypoint.sh 自动执行 migrate_db.py（同步数据库表结构）
启动 Flask 应用，监听 0.0.0.0:5000

3.2 验证服务

# 查看容器状态
docker compose ps

# 查看应用日志
docker compose logs -f web

# 健康检查
curl -f http://localhost:5000

3.3 常用运维命令

# 停止服务
docker compose down

# 停止并清理数据卷（会删除本地 PostgreSQL 数据，生产慎用）
docker compose down -v

# 重新构建并启动（代码更新后）
docker compose up -d --build

# 仅重启服务（不重建镜像）
docker compose restart web

# 进入容器执行命令
docker compose exec web uv run python -c "from app import create_app; print(create_app().config['SQLALCHEMY_DATABASE_URI'])"

# 查看数据库迁移状态
docker compose exec web uv run flask db heads

四、开发模式

docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d --build

开发模式与生产模式的区别：

差异	生产模式	开发模式
数据库	外部 PostgreSQL（`.env` 配置）	本地 `postgres:16-alpine` 容器
代码热重载	否	是（挂载 `.` 到 `/app`）
FLASK_DEBUG	false	true
健康检查	开启（30s 间隔）	关闭

五、架构说明

5.1 容器启动流程

docker compose up
  → Dockerfile 构建镜像
  → entrypoint.sh 执行
    → migrate_db.py（自动添加/更新数据库表字段）
    → run.py（启动 Flask 应用）

5.2 数据库迁移

entrypoint.sh 会在每次容器启动时执行 migrate_db.py，该脚本使用幂等逻辑（先检查字段是否存在再添加），重复执行不会产生错误。

新增字段包括：

sso_sub — SSO 用户标识（唯一索引）
real_name — 真实姓名
roles — 角色列表（JSON 文本）
email / phone / avatar_url — 用户信息

5.3 SSO 登录流程

用户点击 SSO 登录
  → 前端 GET /auth/sso/authorize?redirect=true
  → 302 跳转至 SSO_BASE_URL/oauth/authorize
  → 用户授权后回调 /auth/callback?code=xxx
  → 前端 POST /api/oauth/exchange-code {"code": "xxx"}
  → 后端：
    1. 用 code 向 SSO 换 access_token
    2. 用 token 获取用户信息
    3. 同步用户到本地数据库
    4. 签发 JWT（access + refresh）
  → 返回 token + user info 给前端

5.4 样本中心集成

样本中心模块（/knowledge）提供知识库管理和批量入库功能：

用户访问 /knowledge
  → 侧边栏「样本中心」进入页面
  → Tab 1: 知识库列表（GET /api/v1/knowledge/bases）
  → Tab 2: 知识库详情 + 批量入库按钮
  → Tab 3: 入库任务列表（自动刷新 + 手动刷新）

后端流程：

提交入库 → POST /api/v1/knowledge/bases/{kb_id}/batch-import
创建本地 KnowledgeImportTask 记录
后台轮询器每 5 秒检查待处理任务，指数退避轮询样本中心
样本中心回调推送 → POST /api/v1/callback/knowledge-import

Token 管理：

SampleCenterClient 内部缓存 access_token
过期前 5 分钟自动刷新
线程安全（threading.Lock）

DEPLOY.md 5.1 KB Bezpośredni odnośnik Historia Czysty