Formbricks 6.1.2 配置参数详解

目标：系统梳理 Formbricks 6.1.2 自托管配置的全部环境变量——必填项、认证开关、邮件、对象存储、OAuth/SSO、集成、观测、后台任务与授权链路，并给出可直接落地的生产配置模板与密钥轮换、SMTP 缺失等实测排障结论。参数清单依据官方 environment-variables 文档（查询日期 2026-10-28）并与 6.1.2 实测环境逐项核对；部署过程见 《Formbricks Docker Compose 部署实战》。

一、环境信息

二、前置条件

1. 已按部署篇完成 6.1.2 全栈部署并能访问管理后台；
2. 明确 Formbricks 的配置只有两个入口：
   • 环境变量（.env 文件）：全部服务端行为（本文主题）；
   • 管理后台（组织设置/问卷设置）：运行时业务配置，落库而非落文件；
3. 准备好密钥生成手段（openssl rand -hex 32，Ubuntu 自带）。

三、参数查看与修改方式

3.1 修改流程

Formbricks 的环境变量在服务启动时读取，修改 .env 后必须重建服务进程才生效：

$ cd /opt/formbricks/docker
$ vi .env
$ docker compose up -d          # 编排引擎按变量归属重建受影响服务
 Container formbricks-6.1.2-app Starting
 Container formbricks-6.1.2-app Started

改完先做校验再应用（缺必填变量会在此处报错而非启动失败）：

$ docker compose config --quiet && echo OK
OK

⚠️ 注意：POSTGRES_PASSWORD 例外——它随数据卷首次初始化固化，之后修改只会导致应用连不上库（详见部署篇 10.2）。

3.2 变量生效范围的三层结构

官方编排把变量分给不同服务消费，改动前先确认归属，避免"改了没生效"：

1. 仅主应用消费：WEBAPP_URL、认证开关、OAuth、邮件等（compose 文件 x-environment 段注入 formbricks 服务）；
2. 主应用 + Hub 共享：DATABASE_URL、HUB_*、TAXONOMY_*；
3. 独立服务自有：SpiceDB 的 SPICEDB_*（由 AUTHZED_* 变量映射）、Cube 的 CUBEJS_*。

编排文件中有一个值得注意的细节：TAXONOMY_SERVICE_TOKEN、HUB_INTERNAL_API_TOKEN 等变量在共享段被显式置空（官方注释：避免共享 .env 把它们泄进 Web 应用进程），它们只通过专用路径注入 Hub/taxonomy 服务。

四、参数总览

下表为 6.1.2 全部配置变量的分组索引（默认值以官方文档与编排文件为准）：

关键差异提示：必填项集中在"核心运行 + 认证基址"两组（部署篇第六章已给全量 12 项）；其余分组都是"不配就关闭对应能力"的开关型配置，可按需渐进启用。

五、核心参数分类详解

5.1 核心运行参数

WEBAPP_URL（默认 http://localhost:3000） 对外的应用基准地址，链接问卷 URL、邮件跳转、Webhook 回调里的链接全部由它生成。必须写成用户浏览器实际能访问的地址（含端口）。实测环境为 http://192.168.146.128:8129。

BETTER_AUTH_URL（与 WEBAPP_URL 保持一致） 认证体系（Better Auth）的基准地址，浏览器会话 Cookie 的域、登录 Origin 校验都依据它。实测结论：浏览器从与该值不符的地址访问时登录返回 403：

{"message":"Invalid origin","code":"INVALID_ORIGIN"}
HTTP:403

legacy 别名：NEXTAUTH_URL 与 NEXTAUTH_SECRET v5 认证体系从 NextAuth 迁移到 Better Auth 后，这两个 v4 时代的老变量被保留为别名（官方编排注释原文：旧实例升级后沿用原值，"nothing rewrites it, so this key stays supported indefinitely"）。新部署直接用 BETTER_AUTH_*；BETTER_AUTH_SECRET 未设置时会回退读取 NEXTAUTH_SECRET。

DATABASE_URL（必填） PostgreSQL 连接串。编排中由 POSTGRES_PASSWORD(_URL_ENCODED) 拼接生成，官方形态：

DATABASE_URL=postgresql://postgres:<口令>@postgres:5432/formbricks?schema=public

外置数据库时把主机名与凭据换成真实值即可；schema=public 参数固定保留。

ENCRYPTION_KEY（必填，openssl rand -hex 32 生成） 数据加密密钥，覆盖三类数据：双因素认证密钥、链接问卷的单次链接签名、审计日志哈希。一旦有数据写入，轮换即意味着旧密文不可解——官方没有提供密钥迁移工具，务必妥善保存。

CRON_SECRET（必填） 内部定时任务的调用口令（响应清理、会话清理等周期任务经 HTTP 触发时校验）。

REDIS_URL（官方文档标注必填，默认 redis://localhost:6379） 缓存/限流/审计/BullMQ 队列的连接地址。官方编排固定 redis://redis:6379（内网服务名）。官方文档明确：未配置 Redis 直接启动会报错退出，不能裸跑无 Redis 的实例。

💡 技术拓展：会话与队列的"Redis 还是数据库"之争——Better Auth 的会话令牌存 Redis（读写快、自动过期），BullMQ 的后台任务队列也依赖 Redis 的列表与阻塞弹出；若只用 PostgreSQL 承载这两类数据，高频轮询会把数据库打满。业界同类平台（如开源电邮列表、任务队列系统）普遍采用"Redis 管热数据 + PostgreSQL 管冷数据"的分工。Formbricks v6 选择了 Redis 必配路线，本文实测沿用编排内置 Valkey（Redis 兼容实现）。

LOG_LEVEL（默认 info，可选 debug/info/warn/error/fatal） 应用日志级别；排障时临时调到 debug，观测噪音大时调 warn。

5.2 注册与访问控制开关

5.3 SMTP 邮件参数

未配 SMTP 时保持 EMAIL_VERIFICATION_DISABLED=1、PASSWORD_RESET_DISABLED=1，否则用户会卡在"验证邮件发不出去"。

5.4 对象存储（S3）参数

💡 技术拓展：对象存储的两种寻址风格——虚拟主机式（bucket.s3.amazonaws.com，DNS 解析桶名）与路径式（endpoint/bucket，桶在路径里）。AWS S3 原生用前者；自建 MinIO 通常没有通配符 DNS，必须用路径式（即 S3_FORCE_PATH_STYLE=1）。本文实测未启用 S3（单机磁盘存储），多副本部署建议外置 S3/MinIO。

5.5 OAuth 与企业 SSO

5.6 第三方集成

5.7 观测、遥测与限流

5.8 后台任务（BullMQ）

5.9 审计日志

5.10 Hub / Cube / SpiceDB 授权链路

5.11 AI 与企业版

• AI_PROVIDER：aws / google / azure / openai-compatible 四选一，配套 AI_MODEL 与各厂商密钥变量（AI_AZURE_*、AI_GOOGLE_CLOUD_*、AI_AWS_*、AI_OPENAI_COMPATIBLE_*），用于响应的 AI 洞察；
• ENTERPRISE_LICENSE_KEY：企业版许可（Beta 期可向官方免费申请），激活需能访问许可证服务器（或配 HTTP(S)_PROXY）；
• DEFAULT_BRAND_COLOR（默认 #64748b）、UNSPLASH_ACCESS_KEY（问卷背景图）、PRIVACY_URL/TERMS_URL/IMPRINT_URL/IMPRINT_ADDRESS（合规页脚）属于界面与合规杂项。

六、生产配置模板

按"小团队内网部署（≤100 人使用，无外发邮件需求）"场景给出精简模板（密钥值请全部重新生成）：

# ---- 基址（两项必须一致，换成真实 IP/域名） ----
WEBAPP_URL=http://192.168.146.128:8129
BETTER_AUTH_URL=http://192.168.146.128:8129
# ---- 数据库（初始化后 PASSWORD 不可改） ----
POSTGRES_PASSWORD=<openssl rand -hex 32 生成>
POSTGRES_PASSWORD_URL_ENCODED=<同上，含特殊字符时 URL 编码>
# ---- 密钥四件套（各自独立生成） ----
BETTER_AUTH_SECRET=<openssl rand -hex 32 生成>
ENCRYPTION_KEY=<openssl rand -hex 32 生成>
CRON_SECRET=<openssl rand -hex 32 生成>
HUB_API_KEY=<openssl rand -hex 32 生成>
# ---- 分析与授权链路 ----
CUBEJS_API_SECRET=<openssl rand -hex 32 生成>
CUBEJS_JWT_ISSUER=formbricks-web
CUBEJS_JWT_AUDIENCE=formbricks-cube
AUTHZED_TOKEN=<openssl rand -hex 32 生成>
AUTHZED_DATABASE_PASSWORD=<openssl rand -hex 32 生成>
# ---- 内网无邮件时保持关闭 ----
EMAIL_VERIFICATION_DISABLED=1
PASSWORD_RESET_DISABLED=1
# ---- 离线内网跳过密码外呼校验 ----
PASSWORD_HIBP_CHECK_DISABLED=1
# ---- 资源与观测 ----
LOG_LEVEL=info
TELEMETRY_DISABLED=1

容量参考（同环境实测基线）：全栈空载内存约 1.3 GB（主应用 665 MB、Cube 253 MB、PostgreSQL 198 MB、SpiceDB 限 512 MB 内实际 121 MB），磁盘需求主要在 PostgreSQL 响应数据与上传文件，建议预留 20 GB 起。启用邮件、SSO 或 S3 时按第五章对应小节追加变量即可。

七、常见问题（实测排障）

7.1 改了 .env 但行为没变化

三层排查：① 变量归属的服务是否被重建（docker compose up -d 只重建配置变化的服务，确认输出里有对应服务名）；② 变量是否属于一次性任务消费（如 AUTHZED_DATABASE_PASSWORD 属 SpiceDB 库账号，应用侧改了无效）；③ 是否撞上"不可变变量"（POSTGRES_PASSWORD 随卷固化）。

7.2 登录 403 INVALID_ORIGIN

浏览器访问地址与 BETTER_AUTH_URL 不一致所致，实测回显与处理见部署篇 10.3：两处地址成对修改后 docker compose up -d formbricks。

7.3 轮换 BETTER_AUTH_SECRET 后全员被登出

预期行为：会话 Cookie 由该密钥签名，更换即全部失效；API Key 不受影响。轮换应选低峰期并提前告知用户重新登录（实测结论，见部署篇 10.4）。

7.4 内网 Webhook 无法保存/不推送

默认 SSRF 防护拦截内网目标；测试环境加 DANGEROUSLY_ALLOW_WEBHOOK_INTERNAL_URLS=1（实测可用），生产环境应改用公网可达的接收端。

7.5 密码登录时卡顿或超时

PASSWORD_HIBP_CHECK_DISABLED 未设置时，密码修改路径会对 pwnedpasswords.com 做外呼校验；离线/内网环境设 1 即可（本文生产模板已含）。

八、参考链接

• 官方环境变量文档：https://formbricks.com/docs/self-hosting/configuration/environment-variables
• 官方编排文件（变量与归属的事实来源）：https://github.com/formbricks/formbricks/tree/main/docker
• 企业版许可说明：https://formbricks.com/docs/self-hosting/enterprise
• 本专栏系列：《Formbricks 介绍与选型指南》、《Formbricks Docker Compose 部署实战》、《Formbricks 常用命令与运维实战》