部署指南
部署指南
两种方式:Docker Compose(推荐) 和 裸机直跑。先读「部署前必须改的配置」。
本文的命令都在 Docker Desktop 29.x / Compose v5 上实际跑通过:两个镜像构建成功、 容器起来后走过一遍完整用户流程(注册 → 收码 → 登录 → 技能广场 → 导入大技能包), 并验证过容器彻底重建后数据仍在。
0. 部署前必须改的配置
cp .env.example .env
⚠️ 文件必须放在项目根目录,不是 backend/.env。两个原因:
docker compose只从项目根目录读.env(用于${VAR}插值和env_file);- 放错位置的话容器拿不到任何配置,
JWT_SECRET_KEY会退回内置的change-me-in-production—— 而它不会报错,看起来一切正常,实际上 任何人都能伪造登录态。
至少改掉这几项:
| 项 | 为什么必须改 |
|---|---|
JWT_SECRET_KEY |
默认值是公开的,不改=任何人可伪造登录态。用 python -c "import secrets;print(secrets.token_urlsafe(48))" 生成 |
ADMIN_EMAILS |
谁是管理员。留空则没有人能进管理后台 |
MAIL_* |
不配则注册验证码发不出去(REQUIRE_EMAIL_CODE=true 时流程走不通) |
CORS_ORIGINS |
换成你的实际域名。Docker 部署下前端 nginx 同源反代,通常可以不管 |
PUBLIC_BASE_URL |
对外域名(协议 + 域名,不带路径)。邮件里的品牌标识只能靠绝对地址引用 |
不要把 .env 提交进版本库,也不要放进镜像 —— 根目录的 .dockerignore 已经把
.env / *.key / *.db 全部排除,但真正的责任在部署者。
不要把 DATABASE_URL 留成空值:空串会被当成一个真的连接串,SQLAlchemy 直接抛
Could not parse SQLAlchemy URL 让进程起不来。不需要改就把整行注释掉。
Stripe 支付(可选)
不接支付可以整段跳过,计费模块未配置时不启用。需要时填这三组:
STRIPE_SECRET_KEY=sk_live_...
STRIPE_WEBHOOK_SECRET=whsec_...
STRIPE_PRICE_PRO=price_xxx
STRIPE_PRICE_TEAM=price_yyy
Webhook 地址指向 https://<你的域名>/api/v1/billing/webhook,并确保反向代理把
该路径原样透传(不要缓存、不要改写 body)。
1. Docker Compose(推荐)
前置:Docker + Docker Compose v2。
# 1) 进项目根目录
cd agentflow
# 2) 准备环境变量(放根目录!)
cp .env.example .env
vi .env
# 3) 构建 + 启动(首次 5~15 分钟,主要是装 Python 依赖)
docker compose up -d --build
# 4) 看启动过程(迁移会自动执行,见下)
docker compose logs -f backend
访问入口:前端 http://服务器IP:3000。后端 8001 端口只为本地调试保留,
生产建议在 compose 里把 ports: 那段注释掉,只经前端 nginx 访问。
数据库迁移是自动的,不需要手工执行
容器入口脚本会先 alembic upgrade head、成功后再起 uvicorn,日志长这样:
[entrypoint] 数据库迁移完成,启动:uvicorn app.main:app --host 0.0.0.0 --port 8000 --proxy-headers ...
Using SQLite database: /data/agentflow.db
Database initialized: File-based (persistent) -> /data/agentflow.db
Templates seeded
LLM config loaded: alias=.env source=env
Uvicorn running on http://0.0.0.0:8000
顺序不能反:应用启动时的 init_db() 用的是 create_all,它只新建缺失的表、
不改已有表的列,而且不写 alembic_version。新库若先被 create_all 建出来,
版本基线就是空的,之后 alembic upgrade 会因为「表已存在」失败,升级链再也接不上。
涉及哪些服务
| 服务 | 端口 | 说明 |
|---|---|---|
frontend |
3000 | nginx 托管静态产物,/api /static /ws 反代到后端 |
backend |
8001→8000 | FastAPI(含迁移入口脚本) |
postgres |
可选 | 只有 --profile postgres 才启动,见下 |
redis |
可选 | 只有 --profile redis 才启动 |
没有 celery-worker:app/celery_app.py 在全项目里没有任何地方引用
(.delay( / apply_async / shared_task 都是 0 命中),原编排里的 worker 只是空转。
数据持久化
| 宿主目录 | 容器内 | 内容 |
|---|---|---|
./data |
/data |
SQLite 数据库(用户、Agent、对话、知识库记录) |
./skills |
/repo/skills |
技能(管理员在后台增删会直接写这里) |
./uploads |
/repo/uploads |
知识库原始文件、PiAgent 工作区 |
./static |
/repo/static |
头像、技能产物(Excel/PDF/PPT 下载) |
./config |
/repo/config(只读) |
静态模型目录 models.json |
备份就是打包这五个目录(data/ 最关键)。
⚠️ compose 里的 DATABASE_URL 刻意不用 ${DATABASE_URL} 插值,而是读
AGENTFLOW_DOCKER_DATABASE_URL。因为 .env 是本地开发和 Docker 共用的一份,
而本地那份通常写着相对路径(sqlite+aiosqlite:///./agentflow.db)—— 插值会把
它原样带进容器,数据库落进容器可写层,接口全正常,直到 docker compose down
之后所有数据一起消失。
改了代码之后
docker compose up -d --build # 有新迁移会自动执行,不用手工跑
docker compose logs --tail=50 backend
用 PostgreSQL(可选,未验证)
# 1) 放开 backend/requirements-docker.txt 末尾的 asyncpg / pgvector 注释
# 2) 在 .env 里加:
# AGENTFLOW_DOCKER_DATABASE_URL=postgresql+asyncpg://agentflow:改密码@postgres:5432/agentflow
# POSTGRES_PASSWORD=改密码
# 3) 启动时带上 profile
docker compose --profile postgres up -d --build
这条路径没有经过验证(默认的 SQLite 组合才是跑通的)。Redis 同理:
docker compose --profile redis up -d,并在 .env 里设
AGENTFLOW_DOCKER_REDIS_URL=redis://redis:6379/0。
单实例部署可以完全不启 Redis —— 验证码会退回进程内存,功能正常(启动日志会
显式警告,属于预期)。
构建时网络不通
Docker Hub 与 PyPI / npm 在国内都可能有连不上的情况,三个参数都可以覆盖。
docker compose build 的 --build-arg 会同时作用于两个镜像(求之不得:两者
都需要 BASE_REGISTRY):
docker compose build --build-arg BASE_REGISTRY=docker.m.daocloud.io
docker compose up -d
pip 源和 npm 源是两个镜像各自用的参数,分别构建时才能分别指定:
docker build \
--build-arg BASE_REGISTRY=docker.m.daocloud.io \
--build-arg PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple \
-f backend/Dockerfile -t agentflow-backend:2.0.2 .
docker build \
--build-arg BASE_REGISTRY=docker.m.daocloud.io \
--build-arg NPM_REGISTRY=https://registry.npmmirror.com \
-t agentflow-frontend:2.0.2 ./frontend
2. 裸机直跑(不用 Docker)
前置:Python 3.13(与 requirements-docker.txt 对齐)、Node 20+、
(可选)PostgreSQL + pgvector、Redis。
# ---- 后端 ----
cd backend
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -r requirements-docker.txt
cp ../.env.example .env && vi .env # 裸机跑时 .env 放在 backend/ 下
alembic upgrade head # 建表 / 升级
uvicorn app.main:app --host 0.0.0.0 --port 8001 --workers 2
# ---- 前端 ----
cd ../frontend
npm ci
npm run build # 产物在 dist/
# 用 nginx 托管 dist/,并把 /api /static /ws 反代到 8001 —— 参考 frontend/nginx.conf
裸机部署的两个坑:
AGENTFLOW_REPO_ROOT必须指向包含skills/、config/、static/的那一层 (默认按backend/的上级推导)。目录结构变了就要在.env里显式设置, 否则技能广场一个技能都加载不到。- 多 worker 下不要用 SQLite。
--workers 2配 SQLite 会锁库;要么用 PostgreSQL,要么把 worker 数降到 1。
3. 部署后自检
# 前端能拿到页面
curl -sI http://localhost:3000 | head -1
# 后端活着(经 nginx 反代)
curl -s http://localhost:3000/api/v1/billing/plans | head -c 200
# 未鉴权接口应当被拒(401 而不是 404/502 —— 后者说明反代没配通)
curl -s -o /dev/null -w "%{http_code}\n" http://localhost:3000/api/v1/skills/plaza
# 数据库落在哪(必须是 /data/agentflow.db,不是 /app/…)
docker compose logs backend | grep "Using SQLite database"
再走一遍真实用户流程:注册 → 收验证码邮件 → 登录 → 建 Agent → 发消息。
MAIL_ENABLED=false 时不会真发信,验证码打印在后端日志里:
docker compose logs backend | grep -A3 "MAIL_ENABLED=false"
4. 常见问题
构建时 failed to resolve source metadata for docker.io/library/...
Docker Hub 连不上。用 --build-arg BASE_REGISTRY=docker.m.daocloud.io,或在
Docker Desktop 的 daemon.json 里配 registry-mirrors。
前端页面白屏、控制台一堆 404
frontend/dist 没构建出来(构建阶段 tsc 失败会直接中断 build),或 nginx 的
try_files 没生效。确认镜像里 /usr/share/nginx/html/index.html 存在。
后端容器反复重启,日志写着 error parsing value for field "XXX"
.env 里某个键的值类型不对。典型是 CORS_ORIGINS 这类列表字段 —— 逗号分隔和
JSON 数组两种写法都支持,但空值不行。
注册时报 500
看 docker compose logs backend。首次部署忘了迁移已经不可能(入口脚本会自动跑),
更可能是数据库目录不可写:./data 的属主/权限不对。
邮件发不出去
MAIL_USE_SSL=true 配 465;587/25 要改成 false(STARTTLS)。
QQ 邮箱 / 163 需要的是授权码而不是登录密码。
管理后台入口看不到
ADMIN_EMAILS 里要有当前登录账号的邮箱,且需要重新登录一次才会被授予角色。
注册/发验证码报 422,说邮箱是「保留域名」
ADMIN_EMAILS 与注册用的邮箱必须落在真实存在的公共域名上。
admin@xxx.local、xxx.test、xxx.invalid 这类保留 TLD 会被 email-validator
直接拒掉(422,提示 “special-use or reserved name”)—— 内网自测时很容易顺手
写成 .local,然后卡在「为什么注册不了」。
上传大文件报 413
nginx 的 client_max_body_size 太小。frontend/nginx.conf 里现在是 300m
(对应后端技能包上限 256MB),反代层如果还叠了云负载均衡,那边也要一起放开。
5. 安全清单(上生产前)
JWT_SECRET_KEY已换成随机值DEBUG=false(否则接口会把内部异常原文返回给调用方)REQUIRE_EMAIL_CODE=true- 后端 8001 端口不对公网开放(compose 里默认映射了,生产请注释掉)
- PostgreSQL / Redis 不对公网开放(compose 默认就不映射它们的端口)
CORS_ORIGINS只含自己的域名- 反向代理层(nginx / 云负载均衡)配了 HTTPS
.env权限收到600- 确认
./data在备份计划里 —— 丢了它等于丢了所有用户和 Agent