运维

面向服务器版（Docker Compose）日常运维的常用操作与排障。

服务管理

# 查看各服务状态
docker compose ps

# 启动 / 停止 / 重启
docker compose up -d
docker compose down
docker compose restart backend

# 重建(改了代码 / 配置后)
docker compose up -d --build

日志

# 实时查看
docker compose logs -f backend
docker compose logs -f worker
docker compose logs -f frontend

# 最近 200 行
docker compose logs --tail=200 backend

日志级别由 .env 的 LOG_LEVEL 控制（默认 INFO），排障时可临时设为 DEBUG 并重建容器。

后台任务（Worker）

worker 服务处理异步任务（如导入）。若导入卡在「处理中」，优先检查 worker 日志：

docker compose logs -f worker

确保 worker 与 backend 使用相同的 DB_URL 与 CHROMADB_HOST（默认已在 docker-compose.yml 中对齐）。

升级

git pull
docker compose up -d --build
# 迁移由 migrate 服务自动应用；如需单独重跑
docker compose run --rm migrate

升级前建议先 备份。

升级后的数据整理

表结构迁移完成后，worker 会在后台执行一次性的数据整理（例如把旧版上传在题目中的图片转入媒体库），完成后记入 system_settings 表中以 data_migration. 开头的键（系统内部记录，不在设置页显示，也不能经 API 修改），之后不再执行。可在 worker 日志中查看进度与报告：

docker compose logs worker | grep -i "data migration"

执行失败只记录日志、不影响使用，下次启动 worker 会再试；多个 worker 同时启动时只有一个会执行。也可以手动执行历史媒体迁移（默认只预演）：

docker compose exec backend python scripts/migrate_media_assets.py
docker compose exec backend python scripts/migrate_media_assets.py --apply

常见问题排查

现象	排查方向
前端打不开	docker compose ps 看 frontend/backend 是否 Up；查看 backend 日志
登录报错 / Token 失效	检查 SECRET_KEY 是否被改动（改动会使已签发 Token 失效）
AI 功能报错	检查 AI 供应商与模型 配置与 API Key、网络连通性
知识点检索无结果	确认 chromadb 服务正常、已配置 Embedding 模型
导入不完成	查看 worker 日志；确认 AI 模型可用
数据库连接失败	确认 mysql 健康检查通过、密码与 DB_URL 一致

反向代理与 HTTPS（可选）

如需通过域名 / HTTPS 对外提供服务，可在前面加一层 Nginx / Caddy / Traefik 反向代理，将 80/443 转发到 frontend。请确保：

• 仅暴露必要端口；
• 配置 HTTPS 证书；
• 后端 SECRET_KEY 妥善保管。

安全

将服务暴露到公网前，务必使用强密码、HTTPS，并限制来源。轻量内网协作可优先考虑桌面版 局域网共享。