Psono v7.5.3 配置参数详解

目标：逐项讲清 Psono 服务端 settings.yaml 的参数体系与改法——密钥类、站点域名类、数据库类、缓存限流类、邮件类、注册账户类、多因子类与运维开关类，并给出生产配置模板。参数语义与默认值溯源自官方文档站（doc.psono.com，2026-10-24 实查），缓存、限流、时间同步三项在 Ubuntu 22.04 + Psono v7.5.3 环境实测验证。

一、环境信息

• 操作系统：Ubuntu 22.04（x86_64）
• Psono：v7.5.3（Build 5638426c，组合镜像 psono/psono-combo，/server/info/ 回显确认）
• 配置载体：/opt/docker/psono/settings.yaml（挂载到服务内 /root/.psono_server/settings.yaml）
• 数据库：PostgreSQL 18（postgres:18-alpine）
• 缓存（可选）：Redis 8（redis:8-alpine，13 号库）
• 配套部署与参数基础见本专栏《Psono v7.5.3 Docker Compose 部署指南》；本文所有改参操作均在该部署形态上实测。

二、前置条件

1. 已按部署篇完成基础部署，健康检查三项全绿：

curl -s -w "\nHTTP=%{http_code}\n" "http://127.0.0.1:8153/server/healthcheck/"

实测回显：

{"db_read":{"healthy":true},"db_sync":{"healthy":true},"time_sync":{"healthy":true},"_info":{"ip":"10.89.58.1"}}
HTTP=200

2. 知悉改参的两条铁律（官方 settings.yaml 模板头注释原文，2026-10-24 实查）：
   • 「Backup this config and keep it secret. You need it if you ever need to restore your system with your old database」——settings.yaml 必须备份且保密，恢复系统时必需。
   • 7 个生成密钥「Do this only for a fresh installation! Changing those variables afterwards will break the program」——密钥一经使用不可变更。

三、参数查看与修改方式

3.1 三种配置通道与优先关系

Psono 支持三种配置方式（官方「Environment Variables」「Docker secrets」文档，2026-10-24 实查）：

实测验证环境变量通道可用：在 compose 的 psono-server 服务加环境变量 PSONO_TIME_SERVER 后重启，健康检查的 time_sync 项即按新 NTP 源工作（与 settings.yaml 中 TIME_SERVER 等效）。三种通道同名参数取值时，环境变量与秘密文件优先于配置文件（官方 secrets 文档以「instead of config files」表述）。

3.2 Docker Secrets 用法（敏感参数托管）

官方为每个敏感参数提供了 *_FILE 变体：建秘密文件后，把「指向文件路径」传给同名 _FILE 环境变量。官方文档示例（节选转录）：

docker secret create PSONO_DB_SECRET -
docker service create ... -e PSONO_DB_SECRET_FILE=/run/secrets/PSONO_DB_SECRET ...

支持 *_FILE 的参数清单（官方文档实查）：SECRET_KEY、PRIVATE_KEY、PUBLIC_KEY、ACTIVATION_LINK_SECRET、DB_SECRET、EMAIL_SECRET_SALT、EMAIL_HOST_USER、EMAIL_HOST_PASSWORD、DATABASES_DEFAULT_USER、DATABASES_DEFAULT_PASSWORD。

3.3 改参后如何验证生效

改 settings.yaml 或环境变量后必须重启服务（官方限流文档每项均标注「Restart the server afterward」），再用三个观测点确认：

1. /server/info/：反映站点类与功能开关类参数（web_client、management、files、allowed_second_factors、type 等字段）。
2. /server/healthcheck/：反映数据库与时间同步类参数（db_read/db_sync/time_sync）。
3. Redis 键名：反映限流与缓存类参数（键内含限流组名与版本构建号，见 5.4 实测）。

四、参数总览

settings.yaml 参数按职能分八类（名称、类别、必填性均按官方 settings.yaml 模板与环境变量文档归类，2026-10-24）：

五、核心参数分类详解

5.1 密钥类参数

密钥类由官方脚本一次性生成（实测回显与安全语义见部署篇 4.1 节），七个键各司其职：

• SECRET_KEY：Django 主密钥，参与会话与签名。
• ACTIVATION_LINK_SECRET：激活链接签名，改了旧激活链接全部失效。
• DB_SECRET：数据库字段级加密密钥，与保险库数据直接相关。
• EMAIL_SECRET_SALT：邮件内容加密盐（官方示例值 $2b$12$XUG.sKxC2jmkUvWQjg53.e 为 bcrypt 盐格式）。
• PRIVATE_KEY / PUBLIC_KEY：服务器 Ed25519 签名密钥对，/server/info/ 响应的 signature 字段即用其签名（实测 info JSON 中 public_key 与 settings.yaml 中 PUBLIC_KEY 一致：b97434da…f7845）。
• ADMIN_RECOVERY_PUBLIC_KEY：管理员恢复公钥；对应的 ADMIN_RECOVERY_PRIVATE_KEY 仅离线保存，官方原话：「Anyone with this key may be able to decrypt protected recovery data」。

变更后果：任何一项变更都会导致既有数据/链接/会话异常，官方明确警告仅限全新安装时设置。

5.2 站点与域名类参数

• WEB_CLIENT_URL: 'https://psono.example.com'：Web 客户端地址（不含尾斜杠），服务端生成指向客户端的链接用。
• HOST_URL: 'https://psono.example.com/server'：服务端对外地址，激活/邀请链接以此为基底；官方注释说明访问该地址加 /info/ 应能看到版本 JSON（与本文实测一致）。
• ALLOWED_HOSTS: ['*']：Django 层允许的 Host 头，生产建议收敛为真实域名。
• ALLOWED_DOMAINS: ['example.com']：用户名的域名部分白名单（用户名形如邮箱），登录页展示的域名后缀即来源于此；多域名等价分组用 DOMAIN_SYNONYMS（官方示例：[['example.com', 'example.net']]）。
• NUM_PROXIES: 2：解析 X-Forwarded-For 时信任的代理层数。官方注释原文：「The basic setup of Psono uses 2 reverse proxies, the regular one and one in the combo container」——组合镜像内置一层 Nginx，前面再加一层反代即 2；直接暴露（无外层反代）应设 1，否则限流按错误 IP 计数。实测环境外层无反代但仍保留了组合镜像内部一层，按官方默认 2 配置并通过健康检查。

5.3 数据库类参数

DATABASES 为 Django 标准结构，默认 default 连接；官方要求 PostgreSQL 并需要 ltree、pgcrypto 扩展（官方 Commands 文档：manage.py presetup 会自动安装这两个扩展，数据库账号具备足够权限时使用）。实测采用的最小配置：

DATABASES:
    default:
        'ENGINE': 'django.db.backends.postgresql_psycopg2'
        'NAME': 'psono'
        'USER': 'psono'
        'PASSWORD': 'q1w2e3r4'
        'HOST': 'psono-db'
        'PORT': '5432'

只读分担：官方支持 slave 连接（注释原文「all reads will be redirected to the slave」），读多写少的大规模部署可加；环境变量通道用 PSONO_DATABASE_URL（URL 形式）或 PSONO_DATABASES_DEFAULT_* 分项。验证手段：改参重启后健康检查 db_read/db_sync 必须仍为 true。

5.4 缓存与限流类参数

缓存三件套（官方默认全部关闭；官方警告原文「Cache enabled without belows Redis may lead to unexpected behaviour」）：

CACHE_ENABLE: True
CACHE_REDIS: True
CACHE_REDIS_LOCATION: 'redis://psono-cache:6379/13'

CACHE_REDIS_LOCATION 支持 redis://[:password]@host:6379/13、rediss://（TLS）与 unix:// 套接字三种形式；官方建议避开 0/1 号库，示例用 13（Redis 默认最多 16 库）。实测：开启后重启，Redis 13 号库即出现限流计数键（dbsize 回显 3），且健康检查保持 200。

限流 15 组：官方限流文档给出全部默认值（2026-10-24 实查转录，格式 次数/时间窗，Django 风格）：

关键差异与如何选型：默认值以「最小摩擦、最少误伤」取值，常规团队不建议动 USER/ANON；需要收紧的是公网暴露面的 LOGIN（登录爆破）与 REGISTRATION（滥注册）。范围口径注意：有中央缓存（Redis）时限流计数全局共享，无缓存时按进程独立计数（官方原文受 UWSGI_PROCESSES 控制，默认 10）。

限流生效实测：将 THROTTLE_RATE_HEALTH_CHECK 临时改为 '2/hour'，重启后连续请求健康检查端点：

for i in 1 2 3; do curl -s -o /dev/null -w "try$i HTTP=%{http_code}\n" "http://127.0.0.1:8153/server/healthcheck/"; done

实测回显：

try1 HTTP=200
try2 HTTP=429
try3 HTTP=429

第 2 次请求即触发 429——因为组合镜像自带服务健康探测（每 120 秒 curl 一次 /server/healthcheck/），配额被一并消耗（实测镜像内 HEALTHCHECK 定义：{"Test":["CMD-SHELL","sh -c \"curl -f http://localhost:80/server/healthcheck/ || exit 1\""],"Interval":120000000000}）。结论：健康检查限流不宜低于「120 秒 1 次 × 期望小时数」的余量（默认 61/hour 正好满足 30 次/小时探测 + 人工请求），否则编排层会把服务误判为不健康。验证恢复：删掉临时配置重启后回显 restore HTTP=200。

5.5 邮件类参数

SMTP 基础组：EMAIL_FROM（发件人）、EMAIL_HOST/EMAIL_PORT（服务器与端口）、EMAIL_HOST_USER/EMAIL_HOST_PASSWORD（认证）、EMAIL_USE_TLS/EMAIL_USE_SSL（加密，二者互斥）、EMAIL_SSL_CERTFILE/EMAIL_SSL_KEYFILE（自定义证书）、EMAIL_TIMEOUT（秒）。切换邮件服务商用 EMAIL_BACKEND（如 Mailgun 用 django_mailgun.MailgunBackend，官方 settings.yaml 注释）或直接用各家专项目录（官方配置站列出 Amazon SES、Brevo、Mailgun、Mailjet、Mandrill、Postmark、SendGrid、SparkPost 八种 ESP 配置页）。官方提供发信自测命令：manage.py sendtestmail <邮箱>（官方安装文档：「If you receive this test e-mail, it should be configured properly」）。未配邮件不影响部署验证：可用命令行 createuser 建号。

5.6 注册与账户类参数

• ALLOW_REGISTRATION: False：关闭自助注册（企业内推荐关闭，账号由管理员创建）。
• ALLOW_LOST_PASSWORD: False：关闭忘记密码自助流程（关闭后找回走管理员，官方与恢复码机制配合使用）。
• ENFORCE_MATCHING_USERNAME_AND_EMAIL: False：强制注册时用户名与邮箱一致。
• REGISTRATION_EMAIL_FILTER: ['company1.com']：注册邮箱域名白名单。
• ALLOW_USER_SEARCH_BY_USERNAME_PARTIAL / ALLOW_USER_SEARCH_BY_EMAIL：是否允许按部分用户名/邮箱搜索协作者（默认关闭，官方 Supported Features 明示默认「does not allow」，大企业按需开启）。

5.7 多因子与认证类参数

• MULTIFACTOR_ENABLED: True：官方注释原文「Normally only one of the configured second factors needs to be solved. Setting this to True forces the client to solve all」——开启后配置的第二个因子全部强制通过。
• ALLOWED_SECOND_FACTORS: ['yubikey_otp', 'google_authenticator', 'duo', 'webauthn', 'ivalt']：管理门户可用的 2FA 类型白名单（实测 /server/info/ 回显 allowed_second_factors 为 ["yubikey_otp", "webauthn", "google_authenticator", "duo"]，即默认四项）。
• YubiKey：YUBICO_API_URLS（自建 Yubico 服务地址列表）+ YUBIKEY_CLIENT_ID/YUBIKEY_SECRET_KEY。
• Duo：DUO_INTEGRATION_KEY/DUO_SECRET_KEY/DUO_API_HOSTNAME，代理另配 DUO_PROXY_HOST/PORT/TYPE/HEADERS；官方提供 manage.py testduoconnection 自测。
• iVALT：IVALT_SECRET_KEY（企业版能力）。

5.8 功能开关与运维类参数

• DEBUG: False：生产必须 False（Django 调试页会暴露配置与堆栈）。
• MANAGEMENT_ENABLED: True：管理门户 API 开关，门户必需（默认 False，部署篇已实测开启后 /portal/ 可用）。
• FILES_ENABLED：用户文件功能开关；FILESERVER_HANDLER_ENABLED：文件服务器 API；GATEWAY_HANDLER_ENABLED：网关 API（EE）。
• DISABLE_CENTRAL_SECURITY_REPORTS: True：关闭中心安全报告外呼。
• TIME_SERVER：健康检查用的 NTP 源（默认 time.google.com，境内改 ntp.aliyun.com，实测有效）；确认本机时间可靠时可用 HEALTHCHECK_TIME_SYNC_ENABLED: False 整体关闭该校验。
• PSONO_DISABLED / PSONO_MAINTENANCE_ACTIVE（环境变量通道）：维护模式开关，升级窗口使用。
• TEMPLATES：Django 模板目录，组合镜像固定 /root/psono/templates，自定义邮件模板时替换该目录（"shadowed"）。

六、生产配置模板

适用场景：约 50 用户的中小团队、16GB 内存服务器、SSD 磁盘、域名 HTTPS 反代（Nginx/Traefik 均可）、Redis 同机复用为缓存。以下为可直接落地的 settings.yaml 骨架（密钥值用官方命令生成后填入）：

SECRET_KEY: '<generateserverkeys 生成>'
ACTIVATION_LINK_SECRET: '<generateserverkeys 生成>'
DB_SECRET: '<generateserverkeys 生成>'
EMAIL_SECRET_SALT: '<generateserverkeys 生成>'
PRIVATE_KEY: '<generateserverkeys 生成>'
PUBLIC_KEY: '<generateserverkeys 生成>'
ADMIN_RECOVERY_PUBLIC_KEY: '<generateserverkeys 生成>'

WEB_CLIENT_URL: 'https://psono.example.com'
HOST_URL: 'https://psono.example.com/server'
ALLOWED_HOSTS: ['psono.example.com']
ALLOWED_DOMAINS: ['example.com']
NUM_PROXIES: 2
DEBUG: False
TIME_SERVER: 'ntp.aliyun.com'

ALLOW_REGISTRATION: False
ALLOW_LOST_PASSWORD: False
ALLOW_USER_SEARCH_BY_USERNAME_PARTIAL: False
ALLOW_USER_SEARCH_BY_EMAIL: False
DISABLE_CENTRAL_SECURITY_REPORTS: True

MANAGEMENT_ENABLED: True
FILES_ENABLED: True

CACHE_ENABLE: True
CACHE_REDIS: True
CACHE_REDIS_LOCATION: 'redis://psono-cache:6379/13'

THROTTLE_RATE_LOGIN: '48/day'
THROTTLE_RATE_REGISTRATION: '6/minute'

EMAIL_FROM: 'psono@example.com'
EMAIL_HOST: 'smtp.example.com'
EMAIL_PORT: 587
EMAIL_USE_TLS: True
EMAIL_TIMEOUT: 10

DATABASES:
    default:
        'ENGINE': 'django.db.backends.postgresql_psycopg2'
        'NAME': 'psono'
        'USER': 'psono'
        'PASSWORD': '<数据库强口令>'
        'HOST': 'psono-db'
        'PORT': '5432'

TEMPLATES: [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'DIRS': ['/root/psono/templates'],
        'APP_DIRS': True,
        'OPTIONS': {
            'context_processors': [
                'django.template.context_processors.debug',
                'django.template.context_processors.request',
                'django.contrib.auth.context_processors.auth',
                'django.contrib.messages.context_processors.messages',
            ],
        },
    },
]

模板解读：该档位资源画像为 PostgreSQL 约 1GB、组合镜像服务约 512MB–1GB、Redis 256MB 上限，冗余充足；ALLOWED_HOSTS 收敛到真实域名、注册与找回全部关闭（账号管理员制）是该场景最稳妥的口子组合；THROTTLE_RATE_LOGIN 维持官方默认 48/day/IP，公网暴露时可再收紧。进一步的网络层与密钥治理见本专栏《Psono v7.5.3 安全加固指南》。

七、常见问题

7.1 限流调低后健康检查变 429

现象：把 THROTTLE_RATE_HEALTH_CHECK 调到 '2/hour' 后，第二次请求即 429（实测回显见 5.4 节）。原因：组合镜像自带每 120 秒一次的服务健康探测，与健康检查端点共享限流配额。解决：健康检查限流保留默认 61/hour 或按「探测频次 + 人工余量」计算后再调。

7.2 开启缓存后行为异常

现象：仅设 CACHE_ENABLE: True 未配 Redis。官方 settings.yaml 注释原文已警告「Cache enabled without belows Redis may lead to unexpected behaviour」。解决：三个缓存参数同时设置（CACHE_ENABLE + CACHE_REDIS + CACHE_REDIS_LOCATION），并用 redis-cli -n 13 dbsize 确认计数键在写入。

7.3 time_sync 永远不健康

原因与两种修复（TIME_SERVER 换源 / HEALTHCHECK_TIME_SYNC_ENABLED: False）已在部署篇 7.1 节完整实测，配置篇视角补充：该参数属于「时间同步类」，用 /server/healthcheck/ 的 time_sync 字段验证生效。

7.4 误改密钥类参数后激活链接失效

原因：密钥类参数参与链接签名与数据加密，官方警告变更即破坏。解决：全新安装阶段确定密钥；已投入使用的实例严禁变更，误改后从 settings.yaml 备份恢复原值（这也再次强调 5.1 节「备份且保密」的要求）。

八、参考链接

• 官方 settings.yaml 模板（仓库 configs/mainconfig/settings.yaml）：https://gitlab.com/esaqa/psono/psono-server/-/blob/master/configs/mainconfig/settings.yaml
• 官方 CE 安装文档（新版 settings.yaml 示例）：https://doc.psono.com/admin/installation/install-psono-ce.html
• 官方环境变量清单：https://doc.psono.com/admin/other/environment-variables.html （2026-10-24 实查）
• 官方 Docker Secrets 文档：https://doc.psono.com/admin/other/docker-secrets.html
• 官方限流速率文档：https://doc.psono.com/admin/configuration/throttle-rates.html （15 组默认值，2026-10-24 实查）
• 官方命令文档：https://doc.psono.com/admin/other/commands.html （presetup/sendtestmail 等）
• 本专栏配套：见《Psono v7.5.3 Docker Compose 部署指南》（部署主线与排障）、《Psono v7.5.3 安全加固指南》（加固清单）
• 同类产品配置篇对照：《Vaultwarden 1.37.4 配置参数详解》、《Passbolt 5.16.0 配置参数详解》