ChiefOnboarding v2.5.0 配置参数详解

目标：把 ChiefOnboarding v2.5.0 的全部环境变量按功能域逐项讲清——名字、类型、默认值、生效逻辑（源码 back/settings.py 的读取规则）与生产建议。全部默认值均于 2026-10-30 从 v2.5.0 源码逐行核对，并在本地部署实例上验证过关键项的实际行为。部署过程先读 《ChiefOnboarding v2.5.0 Docker Compose 部署指南》；组件背景见 《ChiefOnboarding 介绍与选型指南》。

一、配置机制总览

1.1 读取方式与优先级

ChiefOnboarding 用 django-environ 读配置，入口在 back/settings.py：

env = environ.Env()
environ.Env.read_env(env.str("ENV_PATH", "back/.env"))

即：先看 ENV_PATH 环境变量指向的文件，默认读应用目录下 back/.env；Docker Compose 部署时所有配置都走 compose 的 environment 段（镜像内无 .env 文件）。ENV_PATH 也可显式指向挂载进来的 .env 文件。环境变量一律在应用启动时读取一次，改配置需重启 web 服务。

1.2 三个「布尔真值」习惯

django-environ 的 env.bool 接受 True/true/1/yes 等写法；列表型变量（ALLOWED_HOSTS、CSRF_TRUSTED_ORIGINS、ALLAUTH_PROVIDERS）用逗号分隔；SSO_PROVIDERS 特殊——它是 Python 字典字面量字符串，用 ast.literal_eval 解析（见第六章）。

1.3 参数全景速查表

⚠️ 任务队列参数 Q_CLUSTER（django-q2：workers=1、timeout=90、retry=1800、queue_limit=50 等）在 v2.5.0 中为 settings.py 硬编码，不提供环境变量覆盖，不要白找配置项。

二、核心必需参数

2.1 SECRET_KEY

Django 全局签名密钥，会话、密码重置链接、CSRF 都依赖它。必填，缺失时应用启动即抛 ImproperlyConfigured。生产用长随机串并妥善保管——泄露等于任何人可伪造会话：

openssl rand -hex 32

2.2 DATABASE_URL

标准 12-factor 连接串，env.db() 直接解析为 Django DATABASES。仅支持 PostgreSQL 方言（psycopg 驱动），MySQL/SQLite 写了也起不来：

postgres://chief:q1w2e3r4@db:5432/chiefonboarding

特殊字符需 URL 转义（@→%40、:→%3A）。数据库高可用独立建设参考 《PostgreSQL 18 流复制（Streaming Replication）集群部署指南》。

2.3 ALLOWED_HOSTS

Django Host 头白名单，逗号分隔。v2.5.0 的兼容逻辑：新变量 ALLOWED_HOSTS 为空时回落到旧的 ALLOWED_HOST（单数，默认 0.0.0.0）；DEBUG=True 时自动放开为 ["*"]。实测缺配置的后果是全站 400 DisallowedHost（部署篇踩坑 4）。

2.4 BASE_URL

系统对外完整地址（协议 + 域名/IP + 端口），用于拼接邮件里的员工激活链接、SSO 回调等。未配置时按 https:// + 第一个 ALLOWED_HOST 拼接——HTTP 直访时必须显式配，否则链接全是错误协议。

三、HTTP 与安全

四、API 开关

API_ACCESS 默认 False；为 True 时向 INSTALLED_APPS 注入 rest_framework.authtoken 与 api 应用——不开启则 /api/* 路由整体不存在（不是 403 而是直接无此路径）。DEBUG 或运行测试时自动为真。开启后建议补跑一次迁移建 Token 表，Token 的生成与调用实测见 《ChiefOnboarding v2.5.0 API 使用详解》。

五、邮件通道

5.1 通道选择逻辑

settings.py 按「谁的环境变量存在就切到谁」的顺序判断，优先级为：Mailgun → Mailjet → Mandrill → Postmark → SendGrid → SendinBlue → 通用 SMTP。全部未配置时回落到控制台输出（console.EmailBackend），邮件内容打到 web 进程日志里——这就是无外网内网环境仍可运行的原因。

5.2 各通道变量

DEFAULT_FROM_EMAIL 独立于通道，默认 example@example.com，生产务必改为真实发信地址（多数服务商要求已验证域名）。

⚠️ 邮箱服务商标识坑：MAILGUN_API_KEY 触发但取值用 MAILGUN_KEY，只配前者会启用 Mailgun 通道却拿不到密钥。

六、登录与 SSO

6.1 本地登录

ALLOW_LOGIN_WITH_CREDENTIALS（默认 True）控制「邮箱 + 密码」登录是否存在；设 False 后 SOCIALACCOUNT_ONLY=True，只剩 SSO 登录。登录方式为邮箱（ACCOUNT_LOGIN_METHODS={"email"}），不开放自助注册（ACCOUNT_EMAIL_VERIFICATION="none"）。

6.2 Google SSO

ALLOW_GOOGLE_SSO=True 时启用，配套 GOOGLE_SSO_CLIENT_ID、GOOGLE_SSO_SECRET。用户需先在管理界面存在（或配合 SSO_AUTO_CREATE_USER=True 自动建号）。

6.3 通用 OIDC

通过 SSO_PROVIDERS 配置，值为 Python 字典字面量字符串（ast.literal_eval 解析），示例形态：

- SSO_PROVIDERS={"keycloak":{"APP":{"client_id":"chief","server_url":"https://sso.example.com/realms/hr/protocol/openid-connect","oidc_endpoint_url":"https://sso.example.com/realms/hr/.well-known/openid-configuration"}}}

角色自动映射由四个变量控制：OIDC_ROLE_PATH_IN_RETURN（角色字段在 OIDC 返回里的路径）、三个正则 OIDC_ROLE_ADMIN_PATTERN（默认 ^cn=Administrators.*）、OIDC_ROLE_MANAGER_PATTERN（默认 ^cn=Managers.*）、OIDC_ROLE_NEW_HIRE_PATTERN（默认 ^cn=Newhires.*），按匹配结果把账号映射为管理员/经理/新员工。

⚠️ 兼容性硬坑：旧版 OIDC 变量 OIDC_CLIENT_ID 一旦被设置，v2.5.0 启动直接抛异常 You need to configure OIDC differently. Please read the docs——必须迁移到 SSO_PROVIDERS 写法。

6.4 双因素（MFA）

TOTP 双因素由 allauth mfa 应用提供（本地登录开启时自动加载），发行方名称取 CHIEFONBOARDING_NAME（默认 ChiefOnboarding），该名称同时用于品牌显示。

七、Slack 集成

不配置时相应功能降级：实测在容器内执行管理命令会出现 Couldn't start slack app: 'NoneType' object has no attribute 'token' 告警——不阻塞执行，仅提示 Slack 通道未启用。

八、对象存储与短信

8.1 S3 兼容对象存储

未配置任何 AWS 变量时文件落本地（数据库同机磁盘），纳入主机备份即可；自建 MinIO 与 PostgreSQL 的组合部署可参考 《PostgreSQL 18.6 Docker Compose 部署指南》 的编排思路扩展一个 object storage 服务。

8.2 Twilio 短信

TWILIO_ACCOUNT_SID、TWILIO_AUTH_TOKEN、TWILIO_FROM_NUMBER 三件套，不配置则一次性消息里的短信通道不可用（邮件/Slack 不受影响）。

九、可观测、防爆破与限流

9.1 Sentry 与调试日志

SENTRY_URL 非空即启用 sentry-sdk（Django 集成，INFO 级 breadcrumb + ERROR 级事件，send_default_pii=False 不发个人身份信息）。DEBUG_LOGGING=True 把 django.request 与 root logger 调到 DEBUG 输出控制台，排查 400/CSRF 问题时临时开。

9.2 django-axes 登录防爆破

9.3 列表分页

DEFAULT_PAGINATE_BY（默认 10）为全站列表页默认分页，并允许 12 个模块单独覆盖：ADMINTASK_ / APPOINTMENT_ / BADGE_ / HARDWARE_ / INTRO_ / NEW_HIRE_ / OFFBOARDING_USERS_ / COLLEAGUE_ / PREBOARDING_ / RESOURCE_ / SEQUENCE_ / TODO_ / INTEGRATION_TRACKER_PAGINATE_BY，其中访问报告页独立默认 25（ACCESS_REPORT_PAGINATE_BY）。仅影响界面每页条数，不影响 API。

十、生产配置模板

组装一份可直接使用的生产环境段（HTTP 经 Nginx 反代终结 TLS 的形态）：

    environment:
      - SECRET_KEY=<openssl rand -hex 32 生成>
      - DATABASE_URL=postgres://chief:<强密码>@db:5432/chiefonboarding
      - ALLOWED_HOSTS=hr.example.com
      - BASE_URL=https://hr.example.com
      - CSRF_TRUSTED_ORIGINS=https://hr.example.com
      - API_ACCESS=True
      - DEFAULT_FROM_EMAIL=hr@example.com
      - EMAIL_HOST=smtp.example.com
      - EMAIL_PORT=587
      - EMAIL_HOST_USER=hr@example.com
      - EMAIL_HOST_PASSWORD=<SMTP密码>
      - EMAIL_USE_TLS=True
      - SENTRY_URL=<可选：Sentry DSN>
      # 不要配 HTTP_INSECURE / DEBUG；HTTPS 语义由默认行为接管

各变量更细的生效条件（含触发键/取值键不一致等特例）已在上文对应章节；部署侧的端口、迁移与初始化流程见 《ChiefOnboarding v2.5.0 Docker Compose 部署指南》 第四章踩坑清单。

十一、参考链接

1. 配置源文件（v2.5.0 标签）：https://github.com/chiefonboarding/chiefonboarding/blob/master/back/settings.py （2026-10-30 逐行核对）
2. 官方配置手册：https://docs.chiefonboarding.com （Email/Object storage/Ratelimits/Google SSO/Slackbot/OIDC 各页）
3. django-environ：https://django-environ.readthedocs.io （env.db/bool/list 解析规则）

本专栏系列：

• 《ChiefOnboarding 介绍与选型指南》：定位、架构与选型对比；
• 《ChiefOnboarding v2.5.0 Docker Compose 部署指南》：从零部署与本篇变量的组合使用；
• 《ChiefOnboarding v2.5.0 API 使用详解》：API_ACCESS 开启后的 API 实操。