QueryWeaver生产部署避坑清单：环境变量、OAuth回调与HTTPS会话安全配置指南

QueryWeaver 是一款开源 Text2SQL 工具，能把自然语言问题转成 SQL 查询。生产部署前，环境变量、OAuth 回调地址与 HTTPS 会话安全是三大高频翻车点。这份清单逐一说明如何正确配置APP_ENV、FASTAPI_SECRET_KEY、OAUTH_BASE_URL等关键项，让你的部署一次通过：登录不掉、Cookie 不丢、回调不乱跳。

一、先搞清楚：QueryWeaver 的三层凭证体系

在调配置之前，理解 QueryWeaver 的凭证模型能帮你避开一半的坑。它把三种"登录"完全隔离开，互不牵连：

关键设计：浏览器登录是一个签名 Cookie，验证它只需校验签名和过期时间，不查数据库。所以即使 FalkorDB 短暂宕机，已登录用户也不会被"踢下线"，只有真正需要图谱的接口会返回503提示重试——而不是让你误以为登录坏了。

💡 相关实现：浏览器会话逻辑见 api/auth/browser_session.py

二、环境变量配置：生产最小清单

QueryWeaver 的所有配置都走环境变量，仓库提供了完整的模板文件 .env.example，官方推荐做法是：

cp .env.example .env # 编辑 .env 填入真实值，然后启动 Docker docker run -p 5000:5000 --env-file .env falkordb/queryweaver

生产环境必配的变量只有两个，其余按需开启：

几个容易忽略的坑：

1）AI 提供商按优先级自动选择

优先级顺序为：OLLAMA_MODEL>OPENAI_API_KEY>GEMINI_API_KEY>ANTHROPIC_API_KEY>COHERE_API_KEY> Azure（默认兜底）。注意Anthropic 没有原生 Embedding，若只用ANTHROPIC_API_KEY还必须配VOYAGE_API_KEY或EMBEDDING_MODEL，否则启动直接报错。逻辑在 api/config.py 中。

2）超时变量"配 0"等于自卸保险

LLM_TIMEOUT、DB_CONNECT_TIMEOUT、DB_STATEMENT_TIMEOUT等超时类变量都经过_positive_env校验：传0、负数、nan、inf都会在启动时直接失败并给出清晰报错——因为 0 在 PostgreSQL 里语义是"无限制"，会彻底拆掉保护。想放宽就传大数值，不要传 0。

3）密钥轮换的副作用

FASTAPI_SECRET_KEY同时签名浏览器登录 Cookie。一旦轮换，所有在线用户的登录会立即全部失效。这是签名 Cookie 的取舍：它无法在服务端单独吊销，靠 TTL 限制暴露窗口，靠换钥"一键全灭"。需要更紧的窗口可缩短BROWSER_SESSION_TTL_HOURS（默认 24 小时）。

三、OAuth 回调配置：redirect_uri 是最常见的坑

QueryWeaver 支持 Google 和 GitHub 两种 OAuth 登录，各自需要四个环境变量（配齐 ID + Secret 才启用）：

• GOOGLE_CLIENT_ID/GOOGLE_CLIENT_SECRET
• GITHUB_CLIENT_ID/GITHUB_CLIENT_SECRET

在对应提供商后台注册 OAuth 应用时，回调地址必须精确填写为：

注意是/authorized结尾的路径，别填成/callback（兼容路径虽存在，但那是 307 转跳，不推荐作为注册回调）。路由实现见 api/routes/auth.py。

坑 1：localhost与127.0.0.1不一致

本地开发时，如果你的 OAuth 应用注册的是http://localhost:5000/...，而浏览器实际从http://127.0.0.1:5000发起请求，redirect_uri 就会对不上，登录直接失败。QueryWeaver 对此专门做了检测并打印告警日志，解法是设置：

OAUTH_BASE_URL=http://localhost:5000

该变量会覆盖由请求推导出的基础 URL，专门用于构造回调地址（见_build_callback_url函数）。生产环境同理：如果外部访问域名和容器实际看到的 base URL 不一致（比如挂了反代），就用OAUTH_BASE_URL固定成对外域名。

坑 2：mismatching_state: CSRF Warning!报错

这个看起来像 CSRF 漏洞的报错，真实原因几乎都是：纯 HTTP 环境下忘了设APP_ENV=development，浏览器丢弃了带Secure标志的 Cookie，OAuth 回跳时 state 对不上。下一节细讲。

四、HTTPS 会话安全：APP_ENV 与 Secure Cookie 的默认行为

这是生产部署最容易翻车也最隐蔽的一处。QueryWeaver 的策略是失败即安全（fail-secure）：

• 会话 Cookie默认强制Secure（仅 HTTPS 传输）；
• 只有APP_ENV的值在去除空白、转小写后恰好等于development时才会关闭Secure标志；
• APP_ENV未设置、设为production、staging或其他任何值，Cookie 都是Secure。

对应代码在 api/app_factory.py 的_session_cookie_https_only函数，启动时也会打印明确日志：

Session cookie is Secure (HTTPS-only); set APP_ENV=development to serve over plain HTTP

由此推出部署铁律：

⚠️ 生产环境若 Cookie 不带Secure，意味着明文 HTTP 请求即可携带登录态，任何中间链路都能偷走会话。

反代场景下，HTTPS 是如何被识别的？

生产部署中 TLS 通常在 Nginx 等反向代理终结，应用本身收到的是 HTTP。QueryWeaver 的判断逻辑是：优先读X-Forwarded-Proto请求头（取第一个 hop，容忍https, http这种追加形式和大小写差异），没有该头才回退到请求自身的 scheme。实现见 api/helpers/request_security.py。

所以你的反代配置必须正确转发X-Forwarded-Proto（Nginx 用proxy_set_header X-Forwarded-Proto $scheme;），否则 CSRF Cookie 的Secure标记、以及代理头中间件的行为都会基于错误的协议判断。应用侧已启用ProxyHeadersMiddleware（trusted_hosts="*"），前提是代理链可信。

顺带的好消息：安全响应头已全部内置，无需自己配。每个响应都会带上 HSTS（max-age=31536000; includeSubDomains; preload）、X-Content-Type-Options: nosniff、X-Frame-Options: DENY、严格的 CSP 和Referrer-Policy，CSRF 防护采用双提交 Cookie 模式（csrf_tokenCookie +x-csrf-token请求头，Bearer Token 请求豁免）。这些都定义在 api/app_factory.py 的SecurityMiddleware与CSRFMiddleware中。

五、邮件注册与 SMTP：别把开发模式带上线

如果只配了邮箱密码登录（没配任何 OAuth 时邮箱认证自动开启），注册流程会发六位验证码，账号在验证码回填后才真正创建——地址不受注册者控制就永远成不了账号。

这里有个环境相关的大坑：

• APP_ENV=development且未配置MAIL_SERVER：验证码邮件不发送，而是写进应用日志，方便本地开发时手动复制。
• 其他任何环境（含 production）：未配置 SMTP 的进程会拒绝发送并明确报错，而不是假装成功。

生产必须配齐 SMTP 变量（任何提供商都支持，只要暴露 SMTP 端点）：

MAIL_SERVER=smtp.yourprovider.com MAIL_PORT=587 MAIL_USERNAME=your_mail_username MAIL_PASSWORD=your_mail_password MAIL_DEFAULT_SENDER=noreply@yourdomain.com

可调参数：EMAIL_VERIFICATION_TTL_MINUTES（默认 15 分钟）、EMAIL_VERIFICATION_MAX_ATTEMPTS（错误尝试上限）、EMAIL_VERIFICATION_RESEND_SECONDS、EMAIL_VERIFICATION_MAX_SENDS。完整说明见 .env.example 的 Email 小节。

六、启动链路：容器内发生了什么

如果你用官方镜像（见 Dockerfile），启动流程由 start.sh 完成：先拉起容器内自带的 FalkorDB（Redis 加载 Falkor 模块），nc探活成功后再exec uvicorn api.index:app启动服务，端口取PORT（默认 5000），HOST默认0.0.0.0。FASTAPI_DEBUG=true会加上--reload——生产环境务必保持关闭，reload 模式是多进程 + 文件监视，既浪费资源又可能双份进程竞争。

另外确认两点：

1. 前端 React 应用已在镜像内构建完成（app/dist目录存在）。若从源码裸跑，先执行cd app && npm run build，否则页面 503 并提示 "Frontend Not Built"。
2. 不需要暴露 MCP 能力时可设DISABLE_MCP=true关闭内置 MCP HTTP 端点（默认开启，挂载在/mcp）。

七、上线前 5 分钟自检清单

逐项打勾再发版：

• FASTAPI_SECRET_KEY已设置且不是示例值，并纳入密钥管理（改它 = 全员掉线）
• FALKORDB_URL指向真实 FalkorDB，启动日志无连接错误
• 生产走 HTTPS，反代正确转发X-Forwarded-Proto；未设置APP_ENV=development
• OAuth 回调注册的 URL 与实际完全一致（含协议、端口、/login/google/authorized路径）；对外域名与内部 base URL 不一致时已设OAUTH_BASE_URL
• 浏览器登录成功后 Cookie 检查：session应带Secure与SameSite=Lax
• 邮箱注册可收到验证码（SMTP 已配置），非开发环境不应看到"写入日志"行为
• FASTAPI_DEBUG未启用，DISABLE_MCP按需设置
• 抽查任一响应的安全头：Strict-Transport-Security、Content-Security-Policy均存在

对照官方 README 的 OAuth 配置与故障排查章节（README.md）复核一遍，基本就稳了。QueryWeaver 的默认姿态是"漏配就往安全侧倒"——理解了这条设计哲学，上面这些坑你都会提前绕开。