PassIt 1.25.0 配置参数详解

目标：把 PassIt 1.25.0 的全部服务端配置项一次讲清——每个参数的默认值、生效逻辑、典型取值与踩坑点。参数语义依据官方仓库 passit/settings.py 源码与运行实例实测（实测日期 2026-10-24），覆盖环境变量与数据库后端（constance）两类配置。

总览：PassIt 没有"配置文件"，配置=环境变量（Django settings 读取）+ 两条运行时开关（constance，存数据库）。核心可调项约 20 个：连接类（DATABASE_URL/CACHE_URL/EMAIL_URL）、安全类（SECRET_KEY/SECURE_COOKIE/SECURE_SSL_REDIRECT/CSP）、组织类（IS_PRIVATE_ORG_MODE/白名单）、功能类（LDAP/MFA/ADMIN）。

一、环境信息

二、前置条件

1. 已按《PassIt 1.25.0 Docker Compose 部署指南》跑起 PassIt 1.25.0 栈；
2. 了解 Django 环境变量的读取方式：容器启动时注入，进程内一次性读取——改环境变量必须重建 web 服务才生效（docker compose up -d web 或 down/up）；
3. 明确本文两个"白名单"不是一回事：环境变量 PRIVATE_ORG_MODE_DOMAIN_WHITELIST（组织模式邮箱域白名单）与数据库配置 REGISTRATION_WHITELIST（constance 注册白名单），详见第四章。

三、参数查看与修改方式

3.1 查看当前生效值

环境变量在容器内可直接查看：

root@passit-server:/opt/passit# docker compose exec web env | grep -E 'DATABASE_URL|CACHE_URL|SECRET_KEY'
DATABASE_URL=postgres://passit:q1w2e3r4@db:5432/passit
CACHE_URL=redis://cache:6379/1
SECRET_KEY=mK7vQ2xL9pR4nT8wZ3yF6jH1cB5dG0sA2eU7iO4qX9zN6mV3kJ8fW2rT5yU1hC4

数据库后端（constance）唯一配置键在运行实例中查询：

REGISTRATION_WHITELIST = ''

3.2 修改与生效

环境变量：改 docker-compose.yml 的 environment: 段，然后 docker compose up -d web 重建。数据库配置：经 Django admin（/admin/ → Constance）改，保存即生效。

四、参数总览（速查表）

五、核心参数分类详解

5.1 连接与基础设施类

DATABASE_URL（必需）

dj-database-url 格式，生产示例：

DATABASE_URL=postgres://passit:q1w2e3r4@db:5432/passit

缺省值指向 postgres://postgres:postgres@db:5432/postgres——用户名口令都是默认值，生产必须改。支持 OpenShift 风格的拆分变量（DATABASE_SERVICE_NAME/DATABASE_NAME/DATABASE_USER/DATABASE_PASSWORD），自托管用 URL 形式即可。

CACHE_URL（1.25.0 必需）

CACHE_URL=redis://cache:6379/1

默认值是 redis://redis:6379/1（主机名 redis）。缓存（django_vcache）与后台任务队列（django_vtasks）共用；不配 Valkey 时页面可用但后台任务全挂（部署篇排障 11.1）。库号 1 是官方默认，多实例共池时建议每实例独立库号。

5.2 安全类

SECRET_KEY（生产必需）

Django 密钥，生产模式（IS_DEBUG=False）下未设置时启动直接失败，故必填；要求 40 位以上随机字符串。实测注意：更换后所有登录 Token 立即失效（用户需重新登录，数据无损），上线后不再更换。

SECURE_COOKIE（默认 True）

实测（2026-10-24，SECURE_COOKIE=True + 纯 HTTP）：

HTTP/1.1 200 OK
set-cookie: csrftoken=CMnIqnfNWG6veemogY1tt49ElaKIu9wu; expires=Sat, 23 Oct 2027 05:13:50 GMT; Max-Age=31449600; Path=/; SameSite=Lax; Secure

Cookie 末尾的 Secure 标记会让浏览器在 HTTP 下拒收，导致登录态存不住。结论：HTTPS 生产保持默认 True；本机 HTTP 验证必须显式 SECURE_COOKIE=False。

SECURE_SSL_REDIRECT（默认 False）

实测（2026-10-24，置 True 后访问 HTTP）：

HTTP/1.1 301 Moved Permanently
location: https://localhost:8128/

所有 HTTP 请求 301 跳 HTTPS。开启前提：TLS 终端已就绪，否则整站不可达；反代场景还需确保跳转后的 HTTPS 能正常回源。

ALLOWED_HOST（默认 *）

注意变量名单数（ALLOWED_HOST，不是 Django 常见的 ALLOWED_HOSTS）。默认 * 放开所有 Host 头，生产建议收敛为具体域名（如 passit.example.com），防 Host 头攻击。

CSP 系列（CSP_DEFAULT_SRC/CSP_STYLE_SRC/CSP_CONNECT_SRC/CSP_SCRIPT_SRC，默认多为 'self'）

内容安全策略，默认自锁定；接入外部资源（如自托管的字体/分析脚本）时才需要动。

CORS_ORIGIN_ALLOW_ALL（默认 True）与 CORS_ORIGIN_WHITELIST

默认全放开的跨域策略——同源部署（扩展与站点同域或扩展自带 host 权限）没问题；把 API 暴露在公网且前端异域部署时，改用白名单。

FIDO_SERVER_ID（默认 localhost）

WebAuthn/FIDO2 的 RP ID，必须是用户访问 PassIt 的域名（如 passit.example.com）；配错会导致安全密钥注册/验证失败。

5.3 邮件类

EMAIL_BACKEND（默认 django.core.mail.backends.smtp.EmailBackend）

实测关键点（2026-10-24）：想让邮件打到控制台，只设 EMAIL_URL=consolemail:// 不生效（读取顺序覆盖问题），必须显式设置本变量：

EMAIL_BACKEND=django.core.mail.backends.console.EmailBackend

生产 SMTP 部署保持默认（或显式 smtp 后端），连接信息走 EMAIL_URL。

EMAIL_URL（django-environ 风格）

smtp+tls://passit:q1w2e3r4@smtp.example.com:587

（用户名与口令按 django-environ 语法写在连接串内；Gmail 为 smtp+tls://user@gmail.com:应用专用密码@smtp.gmail.com:587）

EMAIL_CONFIRMATION_HOST（默认 http://localhost:4200，必改）

确认邮件里"点击确认"链接的主机部分。不改的话新用户收到的确认链接指向 localhost:4200，根本打不开——这是自托管注册"卡在确认"的头号原因。生产示例：https://passit.example.com。

DEFAULT_FROM_EMAIL（默认 blank@example.com）

发件人地址；SMTP 服务商通常要求与认证账号同域，否则拒发。

5.4 组织与注册类

IS_PRIVATE_ORG_MODE（默认 False）

开启后进入"私有组织模式"：全实例用户共享联系人目录（无需按邮箱精确查找）。配合下一项构成注册准入。

PRIVATE_ORG_MODE_DOMAIN_WHITELIST（默认 None）

组织模式下的注册邮箱域白名单，逗号分隔。实测（2026-10-24，IS_PRIVATE_ORG_MODE=True + PRIVATE_ORG_MODE_DOMAIN_WHITELIST=b.com）：

outside@example.org -> sign_up REJECTED: 'Unable to check username'
inside@b.com        -> sign_up OK, user id: 2

非白名单域名的注册请求在用户名可用性检查阶段即被拒，白名单域正常注册。

REGISTRATION_WHITELIST（constance 数据库配置，默认空串=不限制）

与上一项不同源：这是存数据库的注册邮箱整体白名单（支持域名/邮箱条目），经 /admin/ 的 Constance 面板修改、即时生效、无需重启。组织模式白名单管"邮箱域"，本项管"谁能注册"，可叠加使用。

5.5 功能开关类

ENABLE_DJANGO_ADMIN（默认 True）

Django 管理后台开关。实测（2026-10-24，True）：GET /admin/login/ 返回 200。管理后台可管用户/组/constance 配置；生产若不用建议置 False 减少暴露面（详见《PassIt 安全加固指南》）。

LDAP_ENABLED（默认 False）

开启后启用 apps.ldap 的目录认证；需要 LDAP 服务器参数（apps/ldap 配置文件内配置）。企业内网统一认证场景使用。

FIDO_SERVER_ID：见 5.2。MFA 相关端点在 /api/mfa/（生成/验证/激活 TOTP 与 FIDO2）。

5.6 运维辅助类

DJANGO_LOG_LEVEL（默认 INFO）：应用日志级别；排障时临时调 DEBUG，长期运行保持 INFO/WARNING。

IS_TEST_MODE（默认 False）：测试专用，生产永远 False。

ERROR_REPORT_DEFAULT（默认 False）与 SENTRY_DSN：错误上报开关与 Sentry 接入点；注重隐私的自托管保持默认关闭即可。

PASSIT_VERSION（只读）：镜像构建时注入的版本串，用于界面显示与排障对照。

六、生产配置模板

一套可直接抄改的生产环境变量（web 服务）：

    environment:
      DATABASE_URL: postgres://passit:<强口令>@db:5432/passit
      CACHE_URL: redis://cache:6379/1
      SECRET_KEY: "<openssl rand -hex 40 生成的随机串>"
      IS_DEBUG: "False"
      # SECURE_COOKIE 保持默认 True（HTTPS 前提）
      SECURE_SSL_REDIRECT: "True"
      ALLOWED_HOST: passit.example.com
      FIDO_SERVER_ID: passit.example.com
      EMAIL_URL: smtp+tls://passit:q1w2e3r4@smtp.example.com:587
      DEFAULT_FROM_EMAIL: passit@smtp.example.com
      EMAIL_CONFIRMATION_HOST: https://passit.example.com
      DJANGO_LOG_LEVEL: INFO

配套原则：ALLOWED_HOST 与 FIDO_SERVER_ID 用同一个域名；SECURE_SSL_REDIRECT 开启前先确认反代/TLS 就绪；SECRET_KEY 生成后进密钥管理，不进代码库。

七、常见问题

7.1 改了环境变量没生效？

环境变量在进程启动时读取，docker compose up -d web 是"重建"而不是"重启"？——该命令会检测到 env 变化并重建；如仍未见效，用 docker compose exec web env | grep <KEY> 确认容器内实际值，再看 settings 是否有读取顺序覆盖（典型即 EMAIL_BACKEND，见 7.2）。

7.2 EMAIL_URL 设了 consolemail:// 邮件还是走 SMTP

settings 源码中 EMAIL_BACKEND 有独立的默认值声明，EMAIL_URL 解析结果不总是能覆盖它。结论：控制台后端必须显式 EMAIL_BACKEND=django.core.mail.backends.console.EmailBackend；SMTP 后端保持默认即可，EMAIL_URL 只负责连接信息。

7.3 用户收到的确认链接是 localhost:4200 打不开

EMAIL_CONFIRMATION_HOST 没改，保持默认值。改成用户可达的应用地址（域名或 IP:端口），重建 web 服务后重新发送确认邮件即可（未确认用户重新走一遍注册确认流程，或经 /admin/ 重发）。

7.4 开启 SECURE_SSL_REDIRECT 后整站 301 循环/不可达

TLS 还没就绪就开了跳转。顺序：先配好反代与证书 → curl 验证 https 可达 → 再开启跳转变量。

7.5 登录 BASIC 认证 401

Knox BASIC 认证里"密码"是客户端 Argon2 派生哈希，不是主密码明文（服务端设计上就收不到主密码）；浏览器扩展/Web 界面会自动完成派生，脚本直连时需先取 GET /api/user-public-auth/<email>/ 拿 client_salt 自行派生。

八、参考链接

1. 参数源码（settings.py）：https://gitlab.com/passit/passit-backend/-/blob/master/passit/settings.py （查询日期 2026-10-24）
2. django-environ 连接串语法：https://django-environ.readthedocs.io/
3. constance 运行时配置库：https://django-constance.readthedocs.io/
4. 本平台系列篇：《PassIt 1.25.0 Docker Compose 部署指南》（参数注入位置）、《PassIt 安全加固指南》（安全类参数落地清单）
5. 本平台同类配置篇：《Passbolt 5.16.0 配置参数详解》