Flagsmith 配置参数详解
Flagsmith v2.287.0 环境变量体系详解：数据库、核心应用、访问控制、安全反代、邮件、任务处理器、观测与前端面板九大类参数的取值/默认值/生产建议，附参数速查表与误配排障，依据 2026-10-28 官方文档清单实查。
Flagsmith 配置参数详解
目标：系统梳理 Flagsmith v2.287.0 自托管部署的环境变量体系——数据库、应用核心、访问控制、安全反代、邮件、任务处理器、可观测与前端面板九大类参数的取值、默认值与生产建议，并给出参数速查表与典型误配排障。核心结论依据官方文档 API 侧环境变量清单（docs.flagsmith.com/deployment/hosting/locally-api）与官方 Compose 编排实查（2026-10-28），部分行为结合本系列部署/运维篇实测交叉验证。
一、环境信息
| 项 | 值 |
|---|---|
| 取证版本 | Flagsmith v2.287.0（官方统一镜像） |
| 参数清单来源 | 官方文档「Deployment → Hosting → API」环境变量章节（2026-10-28 实查） |
| 编排事实来源 | 官方仓库 main 分支 docker-compose.yml / docker-compose.flags-only.yml（2026-10-28 实查） |
| 交叉验证 | 本系列《Flagsmith Docker Compose 部署实战》实测环境（PostgreSQL 15.5 + 统一镜像三服务） |
| 适用形态 | Docker Compose / 裸统一镜像 / Helm Chart（K8s 场景同一变量经 values 注入） |
本篇为参数与配置篇：环境变量在 Compose 中属官方编排事实，正文按此边界表述；运行行为类结论凡涉及实测均在文中注明「实测」。
二、配置体系概览
Flagsmith 的配置入口有三层，优先级从高到低：
- 环境变量（推荐主通道）：官方镜像完全经环境变量注入配置，无内置配置文件；Compose/Helm 的本质都是组织这批变量。
- Django settings 模块：变量最终落到
app/settings/<env>.py，可用DJANGO_SETTINGS_MODULE指定（如app.settings.production），仅深度定制场景才动。 - Django Admin / 控制台：运行期业务数据（开关、分段、成员）走 API/控制台，不属于部署配置范畴。
变量组织方式（官方 Compose 做法）：用 YAML 锚点 x-flagsmith-env 定义一份变量集，三个 Flagsmith 服务（API、迁移任务、任务处理器）共用 <<: *flagsmith-env 合并注入，避免漂移。统一镜像中 API 与前端控制台同服务，API 变量与前端变量在同一处注入；若采用 DISABLE_FLAGSMITH_UI 只跑 API，前端变量不再需要。
💡 技术拓展：环境变量生效的三种机制值得区分——
机制 代表变量 修改后生效方式 进程启动读取 DATABASE_URL、DJANGO_SECRET_KEY重启服务进程 Django 运行时 settings DJANGO_ALLOWED_HOSTS、DJANGO_SECURE_SSL_REDIRECT重启（settings 在进程启动时装载） 数据库列结构 SEGMENT_CONDITION_VALUE_LIMIT官方明确仅限新装实例设置，运行中实例禁改 排障时先判断变量属于哪类，能省掉大量「改了不生效」的无效重启。
三、数据库参数
数据库是唯一强依赖（PostgreSQL），连接配置两条路线二选一：
路线一：URL 整串（推荐，官方 Compose 默认）
| 变量 | 必设性 | 说明 |
|---|---|---|
DATABASE_URL | 必需 | 标准格式连接串 postgresql://user:password@host:port/db_name；官方文档示例为 postgres:// scheme |
REPLICA_DATABASE_URLS | 可选 | 逗号分隔的只读副本列表，读流量分发用 |
REPLICA_DATABASE_URLS_DELIMITER | 可选 | 副本列表分隔符，默认 ,（密码含逗号时换其他字符） |
路线二：分量式（仅在未提供 DATABASE_URL 时生效，有 URL 则整串优先）
| 变量 | 说明 |
|---|---|
DJANGO_DB_HOST / DJANGO_DB_PORT | 主机与端口 |
DJANGO_DB_NAME / DJANGO_DB_USER / DJANGO_DB_PASSWORD | 库名/用户/密码 |
配套的分析数据落库参数：
| 变量 | 默认 | 说明 |
|---|---|---|
USE_POSTGRES_FOR_ANALYTICS | 'true'（官方 Compose 显式设置） | API 调用与开关分析数据写 PostgreSQL；官方 Compose 注释原话「Store API and Flag Analytics data in Postgres」 |
ENABLE_API_USAGE_TRACKING | True | 关闭后组织设置的 Usage 页无数据；高流量场景为控制库膨胀可关 |
USE_CACHE_FOR_USAGE_DATA | true | 用量统计走进程内缓存 |
API_USAGE_CACHE_SECONDS | 60 | 用量缓存刷写周期（秒） |
INFLUXDB_URL / INFLUXDB_TOKEN / INFLUXDB_ORG | 无 | 可选：分析数据改发 InfluxDB 时三件套齐配 |
GA_TABLE_ID | 无 | 从 Google Analytics 视图查组织用量（SaaS 遗留通道，自托管一般不用） |
生产建议：连接串与 POSTGRES_PASSWORD（数据库镜像初始化）必须一致，这是部署篇 Q 类问题的高发点；数据库凭据不要与 DJANGO_SECRET_KEY 混用同一强度策略——前者换库要同步编排，后者只求长随机。
四、核心应用参数
| 变量 | 默认 | 说明与建议 |
|---|---|---|
DJANGO_SECRET_KEY | 未设时随机生成 | Django 会话/加密基钥。官方 WARNING 原话：多实例部署必须共享同一固定值，否则会话互不识别。生产用 50 位以上随机串，经 Secret 注入 |
ENVIRONMENT | 'local' | 运行环境标记（local/dev/staging/production），官方 Compose 设 production；影响日志与部分行为分支 |
DJANGO_SETTINGS_MODULE | 镜像默认 | settings 模块路径，如 app.settings.production；仅深度定制需要 |
LOG_LEVEL | 平台默认 | DEBUG/INFO/WARNING/ERROR/CRITICAL |
LOG_FORMAT | generic | generic（纯文本）或 json（采集器友好） |
GUNICORN_WORKERS / GUNICORN_THREADS / GUNICORN_TIMEOUT | 镜像默认（2 worker + 2 thread 基线） | Web 工作进程数/每 worker 线程数/请求超时秒数（官方 Docker 文档「Environment Variables」章节列明） |
GUNICORN_CMD_ARGS | 无 | Gunicorn 原生命令行参数，覆盖平台默认值（配 --worker-class 等高级项时用） |
ACCESS_LOG_LOCATION | 未设（默认丢弃访问日志） | 设 - 输出到 stdout，或文件路径落盘 |
ACCESS_LOG_FORMAT | Gunicorn 默认 | 访问日志格式串 |
FLAGSMITH_DOMAIN | 无 | 实例对外域名/端口（如 flagsmith.example.com），用于构造邮件链接等绝对地址；官方 Compose 示例 localhost:8000 |
DISABLE_FLAGSMITH_UI | False | 设 True 关闭统一镜像内的控制台渲染，纯 API 实例用 |
ENABLE_GZIP_COMPRESSION | False | Django 层 gzip 压缩开关 |
REQUIRE_AUTHENTICATION_FOR_API_DOCS | 未设 | 设 True 后 API 文档页需账号认证访问 |
GOOGLE_ANALYTICS_KEY | 无 | 控制台 GA 埋点（自托管一般不需要） |
APPLICATION_INSIGHTS_CONNECTION_STRING / OPENCENSUS_SAMPLING_RATE | 无 | Azure App Insights / OpenCensus 链路追踪遥测 |
实测交叉验证：部署篇实测镜像内 Gunicorn 23.0.0 启动 4 个 worker，PROMETHEUS_ENABLED='true' 时启动日志出现 Prometheus metrics server started on port 9100，与上表行为一致。
五、访问控制与注册参数
控制「谁能注册、谁能建组织、谁能进 Admin」：
| 变量 | 默认 | 说明与建议 |
|---|---|---|
ALLOW_REGISTRATION_WITHOUT_INVITE | True | 设 False/0 后新用户只能经邮件邀请进入 |
PREVENT_SIGNUP | 未设 | 设 'true' 完全关闭注册入口（官方 Compose 注释示例） |
USER_CREATE_PERMISSIONS | 'rest_framework.permissions.AllowAny' | 用户创建接口的 DRF/Djoser 权限列表（逗号分隔）；自托管封闭场景官方建议值 'djoser.permissions.CurrentUserOrAdmin' |
ENABLE_EMAIL_ACTIVATION | False | 注册后需邮件激活 |
RESTRICT_ORG_CREATE_TO_SUPERUSERS | 未设 | 仅超管可创建组织（多租户收敛用） |
DEFAULT_ORG_STORE_TRAITS_VALUE | 无 | 新组织默认不持久化 traits（数据敏感场景） |
ALLOW_ADMIN_INITIATION_VIA_CLI | 未设 | 启用 bootstrap 管理命令（一键建默认超管+组织+项目） |
ADMIN_EMAIL / ORGANISATION_NAME / PROJECT_NAME | 无 | bootstrap 命令配套：默认超管邮箱/默认组织名/默认项目名 |
ENABLE_ADMIN_ACCESS_USER_PASS | 未设 | 允许用户名密码登录 Django Admin（默认 Admin 走 SSO 通道） |
ALLOWED_ADMIN_IP_ADDRESSES | 未设 | 逗号分隔 IP 白名单，仅限名单访问 Django Admin |
USE_X_FORWARDED_HOST | False | 反代场景以 X-Forwarded-Host 替代 Host 头（仅在反代确实设置该头时开启） |
实测交叉验证：本系列运维篇实测 bootstrap 命令依赖上述三件套变量（ADMIN_EMAIL/ORGANISATION_NAME/PROJECT_NAME），缺任一即 Error: Missing argument——与官方「先开 ALLOW_ADMIN_INITIATION_VIA_CLI 再跑命令」的链路一致。
六、安全与反代参数
| 变量 | 默认 | 说明与建议 |
|---|---|---|
DJANGO_ALLOWED_HOSTS | 无（官方 Compose 示例 '*'） | Host 头白名单，逗号分隔。生产必须收紧为实际域名，否则 Django 对不匹配 Host 直接拒绝 |
DJANGO_CSRF_TRUSTED_ORIGINS | 无 | 允许发起 POST/PUT 的跨域来源列表；控制台与 API 不同域（拆分部署）时必配 |
SECURE_PROXY_SSL_HEADER_NAME | HTTP_X_FORWARDED_PROTO | 反代 TLS 卸载场景告诉 Django 哪个头代表真实协议 |
SECURE_PROXY_SSL_HEADER_VALUE | https | 同上，头的取值 |
DJANGO_SECURE_SSL_REDIRECT | False | 强制 HTTP→HTTPS 跳转（经反代终止 TLS 时配合上两项） |
DJANGO_SECURE_SSL_HOST | None | 强制重定向目标主机 |
DJANGO_SECURE_REFERRER_POLICY | same-origin | Referrer-Policy 头 |
DJANGO_SECURE_REDIRECT_EXEMPT | [] | 免跳转路径列表 |
FLAGSMITH_CORS_EXTRA_ALLOW_HEADERS | 'sentry-trace,' | 跨域额外放行的请求头（逗号分隔） |
AXES_FAILURE_LIMIT | 10 | 登录失败锁定阈值（内置 django-axes 防爆破） |
AXES_ONLY_USER_FAILURES | True | 仅按用户名锁定（官方镜像默认；镜像启动日志会伴随 axes.W004/W006 两条告警，属上游默认配置，见部署篇 Q8） |
实测交叉验证：部署篇实测用 curl 模拟 Django Admin 登录被 CSRF 拦截（403 Forbidden — CSRF cookie not set），根因即本组 DJANGO_CSRF_TRUSTED_ORIGINS/CSRF 中间件的安全默认；浏览器访问不受影响。
七、邮件参数
官方文档明确：不配邮件平台也能完整运行——邀请用户可用邀请链接完成（邮件仅是补充通道）。核心三选一：
| 变量 | 说明 |
|---|---|
EMAIL_BACKEND | 后端类：django.core.mail.backends.smtp.EmailBackend（通用 SMTP）/ sgbackend.SendGridBackend / django_ses.SESBackend |
SENDER_EMAIL | 发件人地址 |
SMTP 后端配套：EMAIL_HOST（默认 localhost）、EMAIL_PORT（默认 587）、EMAIL_USE_TLS（默认 True）、EMAIL_HOST_USER / EMAIL_HOST_PASSWORD。官方 Compose 注释给出的完整示例即此组合（mail.example.com + 587 + TLS）。
SendGrid 配套：SENDGRID_API_KEY。AWS SES 配套：AWS_SES_REGION_NAME（默认 us-east-1）、AWS_SES_REGION_ENDPOINT。
⚠️ 官方特别提示（原文要点）：邮件模板里的链接域名取自 Django
django_site表记录，FLAGSMITH_DOMAIN只影响平台自身生成的地址——邮件链接打不开时先查django_site表记录是否指向你的真实域名。
八、任务处理器与性能参数
| 变量 | 取值 | 说明与建议 |
|---|---|---|
TASK_RUN_METHOD | SEPARATE_THREAD（默认）/ SYNCHRONOUSLY / TASK_PROCESSOR | 官方 Compose 注释原话列出三值。默认在进程内线程执行异步任务；TASK_PROCESSOR 交给独立任务处理器服务（生产多实例推荐）；SYNCHRONOUSLY 在请求线程同步执行（仅小规模） |
SEGMENT_CONDITION_VALUE_LIMIT | 1000（0–2000000） | 分段条件值字节上限。官方 WARNING：该值改的是数据库列长，仅限新装实例设置，运行中禁改；调大可能影响未来向 SaaS 迁移导入 |
SEGMENT_RULES_CONDITIONS_EXPLICIT_ORDERING_ENABLED | False | 强制分段条件按主键升序求值；官方警告改动可能影响既有分段求值结果 |
PROMETHEUS_ENABLED | False | 开启 /metrics（容器内 :9100），官方 Compose 设 'true' |
PROMETHEUS_HISTOGRAM_BUCKETS | 客户端默认 | 直方图桶，如 "0.5,0.6,1.0,Inf" |
REPLICA_DATABASE_URLS 系列 | 无 | 见第三章（读写分离） |
实测交叉验证：部署篇编排采用 TASK_RUN_METHOD=TASK_PROCESSOR + 独立 run-task-processor 服务，实测组织/项目/环境创建产生的后台任务由其消化，任务表 total tasks: 7 且无 FAILED 积压——多实例生产形态按此配。
九、观测与集成参数
| 变量 | 说明 |
|---|---|
SENTRY_SDK_DSN | Sentry 错误上报 DSN |
SENTRY_TRACE_SAMPLE_RATE | 追踪采样率，默认 1.0 |
OAUTH_CLIENT_ID / OAUTH_CLIENT_SECRET | Google OAuth 凭据，用于 Django Admin 的 SSO 登录（django-admin-sso 通道）；官方 Compose 注释提示：开启 OAuth 还需「Flagsmith on Flagsmith」层面配置，仅设变量不生效 |
GOOGLE_SERVICE_ACCOUNT | 读组织用量的 Google 服务账号 JSON（需 analytics.readonly 权限） |
APPLICATION_INSIGHTS_CONNECTION_STRING / OPENCENSUS_SAMPLING_RATE | 见第四章表 |
自托管最小集建议：SENTRY_SDK_DSN（可选）+ PROMETHEUS_ENABLED + 反代访问日志即可覆盖绝大多数排障需要，遥测类变量在合规敏感环境应保持默认关闭。
十、前端面板参数
统一镜像下控制台（React SPA）由后端容器直接伺服，相关变量：
| 变量 | 说明 |
|---|---|
API_URL | 控制台调用的 REST API 地址（官方 Docker 文档「Access Flagsmith Remotely」原话：配置 dashboard 环境变量 API_URL 告知控制台 API 位置）。统一镜像默认同源 /api/v1/；仅当控制台与 API 拆分部署时需要显式设置 |
FLAGSMITH_FRONTEND_* 系列 | 前端静态资源与品牌定制变量（官方前端变量清单 docs.flagsmith.com/deployment/hosting/locally-frontend），常规部署不动 |
DISABLE_FLAGSMITH_UI | 见第四章（关闭内置面板，纯 API 实例） |
外部 SDK 侧的地址配置不属于本表：各语言 SDK 以 flagsmith 或 environment_key 初始化时传自托管 API 地址（如 http://<host>:8142/api/v1/，部署篇 4.7 实测即此端点形态）。
十一、参数速查表
按「装完必查」优先级汇总（✅=建议生产必设，⚠️=按场景设置，—=保持默认）：
| 变量 | 生产建议 | 一句话作用 |
|---|---|---|
DATABASE_URL | ✅ | 唯一强依赖连接串 |
DJANGO_SECRET_KEY | ✅ | 加密基钥，多实例共享固定值 |
DJANGO_ALLOWED_HOSTS | ✅ | Host 白名单，收紧域名 |
FLAGSMITH_DOMAIN | ✅ | 对外域名，邮件/链接地址基准 |
ENVIRONMENT | ✅（production） | 运行环境标记 |
TASK_RUN_METHOD | ⚠️（多实例用 TASK_PROCESSOR） | 异步任务执行方式 |
USE_POSTGRES_FOR_ANALYTICS | ⚠️（'true'） | 分析数据落库 |
PROMETHEUS_ENABLED | ⚠️（'true'） | 指标端点 |
ALLOW_REGISTRATION_WITHOUT_INVITE | ⚠️（封闭设 False） | 邀请制注册 |
PREVENT_SIGNUP | ⚠️ | 完全关注册 |
RESTRICT_ORG_CREATE_TO_SUPERUSERS | ⚠️ | 组织创建收敛 |
EMAIL_BACKEND 等 | ⚠️ | 邮件通道（可不配） |
DJANGO_CSRF_TRUSTED_ORIGINS | ⚠️（拆分部署必配） | 跨域写请求来源 |
SECURE_PROXY_SSL_HEADER_NAME/_VALUE | ⚠️（TLS 反代必配） | 反代真实协议头 |
GUNICORN_WORKERS/_THREADS/_TIMEOUT | — | Web 并发基线 |
LOG_LEVEL/LOG_FORMAT | — | 日志级别/格式 |
SEGMENT_CONDITION_VALUE_LIMIT | —（新装才可设） | 分段条件值上限 |
SENTRY_SDK_DSN | — | 错误上报 |
十二、常见问题
Q1：多实例部署后用户频繁掉线/会话互不识别。
原因即官方 WARNING：未设共享 DJANGO_SECRET_KEY，各实例用各自随机值。解法：编排中显式设同一强随机值（部署篇 4.1 编排示例的写法），经 Secret 注入而非明文入仓。
Q2：访问报 Invalid HTTP_HOST header / 控制台打不开。
原因：DJANGO_ALLOWED_HOSTS 未含实际访问域名（或仍为官方示例 '*' 被安全基线纠正后遗漏）。解法：设为逗号分隔的真实域名清单并重启；经反代还需核对 USE_X_FORWARDED_HOST 与 SECURE_PROXY_SSL_HEADER_* 两项。
Q3：设了 TASK_PROCESSOR 但异步任务不执行/积压。
原因：只改了 TASK_RUN_METHOD 没起任务处理器服务（该方式必须配套 run-task-processor 常驻进程，官方 Compose 注释原话「only needed if TASK_RUN_METHOD set to TASK_PROCESSOR」）。解法：编排中补 task-processor 服务（部署篇 4.1 模板），或临时退回默认 SEPARATE_THREAD。
Q4：注册接口拒绝 q1w2e3r4 等弱密码。
行为：注册/建用户接口返回 {'password': ["This password is too common."]}（部署篇实测回显）。这属 Django 内置校验，无对应环境变量可关；脚本化初始化请直接用强口令（示例 Q1w2e3r4@2026）。
Q5：邀请邮件里的链接域名不对。
原因与解法见第七章官方提示：链接域名取自 django_site 表而非 FLAGSMITH_DOMAIN，用 Django Admin 的 Sites 记录改成真实域名。
Q6：改了 SEGMENT_CONDITION_VALUE_LIMIT 后升级报错/数据异常。
原因：官方明确该值变更数据库列长，仅限新装实例设置。解法：运行中实例保持默认 1000，确需扩容走官方支持通道评估。
Q7：控制台跨域调用 API 被拒（拆分部署）。
解法：DJANGO_CSRF_TRUSTED_ORIGINS 加控制台来源、FLAGSMITH_CORS_EXTRA_ALLOW_HEADERS 按需补自定义头，并把 API_URL 指到 API 真实地址（第十章）。
十三、参考链接
- API 环境变量官方清单（本篇主依据）：https://docs.flagsmith.com/deployment/hosting/locally-api
- 前端环境变量官方清单：https://docs.flagsmith.com/deployment/hosting/locally-frontend
- Docker 部署文档（Gunicorn/访问日志变量）：https://docs.flagsmith.com/deployment/docker
- 官方 Compose 编排（变量注释与示例）：https://raw.githubusercontent.com/Flagsmith/flagsmith/main/docker-compose.yml
- Django Admin 配置文档：https://docs.flagsmith.com/deployment/configuration/django-admin
- 容量与扩缩官方指引：https://docs.flagsmith.com/deployment/configuration/sizing-and-scaling
- 本系列姊妹篇：《Flagsmith 介绍与选型指南》、《Flagsmith Docker Compose 部署实战》、《Flagsmith 常用命令与运维实战》