配置说明
配置说明
本页由 README 拆分而来,内容与代码同步维护。返回 README。
环境变量
复制 .env.example 为 .env,按需填写:
# 数据库(必填)
DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5433/agentflow
# Redis(必填)
REDIS_URL=redis://localhost:6379/0
# JWT 认证(必填,生产环境务必更换)
JWT_SECRET_KEY=change-me-in-production
ACCESS_TOKEN_EXPIRE_MINUTES=30
# LLM API Keys(至少填一个)
OPENAI_API_KEY=sk-xxx
ANTHROPIC_API_KEY=sk-ant-xxx
DEEPSEEK_API_KEY=sk-xxx
# CORS
CORS_ORIGINS=http://localhost:3000,http://localhost:5173
邮件与注册验证码
注册默认要求邮箱验证码(REQUIRE_EMAIL_CODE=true)。用标准库 smtplib 发信,
不需要额外安装依赖。
配置 SMTP
MAIL_ENABLED=true
MAIL_HOST=smtp.qq.com # 或 smtp.163.com / 企业邮箱
MAIL_PORT=465 # 465 用 SSL;587 改 MAIL_USE_SSL=false 走 STARTTLS
MAIL_USER=you@qq.com
MAIL_PASSWORD= # 邮箱「授权码」,不是登录密码
MAIL_FROM= # 留空则用 MAIL_USER
MAIL_FROM_NAME=AgentFlow
MAIL_USE_SSL=true
授权码怎么拿 QQ 邮箱:设置 → 账户 → 开启 SMTP 服务 → 生成授权码 163 邮箱:设置 → POP3/SMTP/IMAP → 开启 → 新增授权密码
注意:国内云主机直连 25 端口基本被封,请用 465/587。发信标题也别写得像营销邮件, 否则容易进垃圾箱。
本地开发不配 SMTP
MAIL_ENABLED=false 时邮件不会真的发出,验证码以 WARNING 级别打印到后端日志:
WARNING | app.services.mailer | [MAIL_ENABLED=false] 邮件未发送(仅记录内容)
To: you@example.com
Subject: 【AgentFlow】注册验证码
你的注册验证码是:123456
验证码策略
| 变量 | 默认 | 说明 |
|---|---|---|
CODE_TTL_SECONDS |
300 | 有效期(秒) |
CODE_LENGTH |
6 | 位数 |
CODE_RESEND_INTERVAL |
60 | 同一邮箱重发冷却(秒) |
CODE_HOURLY_LIMIT |
5 | 同一邮箱每小时上限 |
CODE_MAX_ATTEMPTS |
5 | 单个码最多试错次数,超过即作废 |
SEND_CODE_IP_LIMIT |
10 | 每 IP 每窗口的发码次数 |
SEND_CODE_IP_WINDOW |
3600 | IP 限流窗口(秒) |
公司/学校共用出口 IP 时,
SEND_CODE_IP_LIMIT容易误伤,可按需放宽。REQUIRE_EMAIL_CODE=false会关闭注册校验,仅建议用于自动化测试与内网演示。
验证码存储:务必注意多 worker
验证码优先存 Redis,连不上时退回进程内存。内存模式在 uvicorn --workers N
(N > 1)下必然失效——发码落在 worker A、校验落在 B,用户永远提示「验证码已过期」。
启动时会打印告警:
⚠️ 验证码当前使用内存存储:uvicorn 若开启多个 worker,发码与校验可能落在不同进程,导致校验永远失败。
多 worker / 多实例部署必须配好 REDIS_URL。
接口
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | /api/v1/auth/send-code |
发送注册验证码 |
| POST | /api/v1/auth/register |
注册(需带 code 字段) |
大模型 API 配置(支持热切换)
在 设置 → 模型配置 里可以自行填写 API Key 与端点,不用改 .env、也不用重启服务。
| 能力 | 说明 |
|---|---|
| 增删改查 | 别名、服务商、Base URL、模型、温度、最大 tokens、备注 |
| 别名与默认项 | 别名唯一(重复会明确提示);「设为默认」即刻生效 |
| 启用/停用 | 可临时停用某套配置;默认项不允许停用,避免出现无可用配置 |
| 连接测试 | 保存前可先测;先探测 /models(不消耗 token),不可用时退回一次最小对话请求 |
| 错误提示 | 认证失败 / 域名解析失败 / 连接被拒绝 / 路径需要 /v1 / 模型不存在 / 超时,分别给出可操作提示 |
| 密钥安全 | Fernet 加密落库,接口只返回脱敏值(如 sk-l******7890),明文不出后端 |
| 热切换 | 写操作立即让运行时快照失效,下一条请求就用新配置 |
热切换是怎么做到的
全项目的模型凭证只有一个出口:app/services/model_runtime.py 的 resolve_credentials()。
它优先读内存中的「生效配置快照」,快照由 app/services/llm_config.py 维护:
- 启动时预加载一次(
main.py的 lifespan) - 任何增删改都会
invalidate(),立刻刷新快照并清空底层 SDK 客户端缓存 - 请求级中间件只在快照过期时查库,因此多 worker 部署下最迟
LLM_CONFIG_CACHE_TTL_SECONDS(默认 5 秒)对所有进程一致
回退行为:一套配置都没有时,继续使用 .env 里的凭证,原有部署不受影响;
界面会标注「当前来自 .env 回退」。
接口
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /api/v1/llm-configs |
列表(脱敏)+ 当前生效项 |
| POST | /api/v1/llm-configs |
新增 |
| PUT | /api/v1/llm-configs/{id} |
更新(不传 api_key 表示保留原密钥) |
| DELETE | /api/v1/llm-configs/{id} |
删除(删掉默认项会自动补一个) |
| POST | /api/v1/llm-configs/{id}/default |
设为默认并立即生效 |
| POST | /api/v1/llm-configs/{id}/active |
启用 / 停用 |
| POST | /api/v1/llm-configs/{id}/test |
测试已保存配置并记录结果 |
| POST | /api/v1/llm-configs/test |
测试未保存的草稿 |
| GET | /api/v1/llm-configs/active |
当前真正生效的配置 |
| GET | /api/v1/llm-configs/providers |
可选服务商预设与建议模型 |
仅支持 OpenAI 兼容协议 的端点(OpenAI / DeepSeek / Ollama / 百炼 / vLLM / OneAPI 等)。 原生 Anthropic 协议需要额外的适配器,暂不在本系统范围内。
SQLite 轻量模式
只想把后端跑起来、不想装数据库和一堆重型依赖时,用一键脚本:
.\scripts\dev-backend.ps1 # 启动在 http://127.0.0.1:8001
.\scripts\dev-backend.ps1 -Port 8002 # 指定端口
.\scripts\dev-backend.ps1 -SkipServe # 只准备环境,不启动服务
.\scripts\dev-backend.ps1 -Reinstall # 强制重装依赖
脚本会自动完成:探测 Python 3.11+ → 创建 backend/.venv → 安装 backend/requirements-lite.txt → 生成 .env(默认 DATABASE_URL 为 SQLite)→ 启动 uvicorn。
轻量依赖集 vs 完整依赖集
requirements-lite.txt 刻意排除了以下包,以缩短安装时间并避免版本冲突:
| 排除的包 | 影响 |
|---|---|
sentence-transformers |
会拖入 torch(约 2GB)。本地嵌入不可用,知识库改用 OpenAI embeddings 不受影响 |
faiss-cpu |
Python 3.13 常无预编译 wheel。基于 faiss 的本地向量检索不可用 |
playwright / browser-use |
浏览器自动化节点不可用,需另行安装并下载浏览器内核 |
asyncpg / pgvector |
仅 PostgreSQL 需要,SQLite 模式用不到 |
需要完整功能时,改用 pip install -r requirements.txt(注意 langgraph==0.0.20 + langchain==0.1.4 的锁定组合较旧,Python 3.13 下可能需要放宽松版本)。