AliasVault 0.31.1 配置参数详解

本文是 AliasVault 专栏的配置篇，承接《AliasVault 0.31.1 Docker Compose 部署指南》。官方配置文件 .env.example 中的全部 21 个参数在本文逐一过审：行为类参数（注册开关、HTTPS 强跳、admin IP 白名单、上传上限、SMTP TLS）全部在真实服务器上改参数实测，HTTP 状态码与 JSON 报文原文收录；静态类参数按官方注释与源码如实整理。实测日期 2026-10-24，组件版本 0.31.1。组件定位与选型背景见《AliasVault 0.31.1 介绍与选型指南》。

一、参数体系总览与生效方式

官方 .env.example（随源码发布）把配置分为六组、共 21 个参数，分组如下：

参数落点因部署路线而异：Install Script 路线（官方推荐）由安装脚本自动生成 .env 并提供 CLI 修改入口；本文沿用部署篇的 Docker Compose 路线，参数写在 docker-compose.yml 的 environment 段，与 .env 文件语义完全等价——服务端读到的都是同一组环境变量。

生效方式是参数调优的第一坑：修改参数后必须按部署篇第八节的方式重建服务。部署篇已实测：docker compose restart 不刷新 environment，只有 down 后再 up 才能让新参数进入运行态。本文每组实验都遵循「改参数 → 重建 → 探针验证」三步，探针一律从服务器本机发起，指向部署篇映射的宿主端口（HTTP 8132 / HTTPS 8133 / SMTP 25→8143 / SMTP TLS 587→8152）。

另一处容易踩的默认值差异：.env.example 里 FORCE_HTTPS_REDIRECT 的示例默认是 true（Install Script 路线自带 TLS，开强跳合理）；而官方 Docker Compose 模板把该项显式置为 false——无内置 TLS 的部署形态若沿用 true，HTTP 流量会被强制跳转到一个没有证书的端口。参数默认值必须结合部署路线看，本文第三节有实测。

二、注册开关 PUBLIC_REGISTRATION_ENABLED（实测）

官方语义（.env.example 注释原文）：控制是否允许新用户通过 Web 界面注册账号；注释特别提醒「置 false 前先创建好自己的账号」，且置 false 后新用户仍可通过管理端（Users → Invites）生成的邀请链接注册。这是自托管场景最常用的第一道闸门——服务器公网可达时，开着注册等于任何人都能往你的数据库里写账号。

探针端点说明：判别注册开关不需要真的注册一个账号，向 API 的用户名校验端点 POST /api/v1/auth/validate-username 提交 JSON 即可，开关状态直接改变该端点的响应。（注：0.30 之前常用的 v1 注册端点在 0.31.x 已废弃，请求返回 410 Gone，老教程的探针方法不再可用。）

T0 基线（PUBLIC_REGISTRATION_ENABLED: "true"）实测：

$ curl -s -X POST http://localhost:8132/api/v1/auth/validate-username \
    -H "Content-Type: application/json" -d '{"username":"probe_baseline"}'
{"message":"USERNAME_AVAILABLE","code":"USERNAME_AVAILABLE","details":{},"statusCode":200,"timestamp":"2026-10-24T05:08:48.0222006Z"}
HTTP=200

开关关闭（置 "false" 后重建）实测：

$ curl -s -X POST http://localhost:8132/api/v1/auth/validate-username \
    -H "Content-Type: application/json" -d '{"username":"probe_baseline"}'
{"message":"PUBLIC_REGISTRATION_DISABLED","code":"PUBLIC_REGISTRATION_DISABLED","details":{},"statusCode":400,"timestamp":"2026-10-24T05:09:11.9004681Z"}
HTTP=400

同一探针，状态码从 200 变为 400，报文 code 从 USERNAME_AVAILABLE 变为 PUBLIC_REGISTRATION_DISABLED，参数即时生效、判定干净利落。本文全部实验结束后，服务器最终保留了 false 的加固态（收尾复测：reg_probe=400，报文同上），后续安全篇将把它列入加固清单。

三、FORCE_HTTPS_REDIRECT（实测）

官方语义：将全部 HTTP（80）流量强制重定向到 HTTPS（443），示例默认 true。它工作在网关层，改的是整台服务的路由行为而不只是首页。

置 "true" 后重建，实测结果：

$ curl -s -o /dev/null -w "GET80=%{http_code} location=%{redirect_url}\n" http://localhost:8132/
GET80=301 location=https://localhost/
$ curl -s -o /dev/null -w "GET80_api=%{http_code} location=%{redirect_url}\n" http://localhost:8132/api
GET80_api=301 location=https://localhost/api
$ curl -sk -o /dev/null -w "GET443=%{http_code}\n" https://localhost:8133/
GET443=200

三个关键事实：

1. 首页 301 跳转目标是 https://localhost/——不带端口号，即网关默认的 443 端口。在非标准端口映射的服务器上，浏览器跟随跳转会访问 https://服务器IP/（443），与实际映射端口（本文 8133）不符，跳转后不可达。这是非标准端口部署时必须关闭该参数的硬理由。
2. 强跳范围覆盖 /api 等全部路径——连注册探针都被 301 拦截（REG_HTTP=301），不存在「只有网页跳、API 不跳」的旁路。客户端（浏览器扩展/移动 App）配置的服务器地址若是 http://，会在同步时被一并 301，因此开强跳前必须先保证 TLS 可用。
3. HTTPS 端口（443）在自签证书下工作正常（GET443=200，curl 需加 -k 跳过校验），强跳本身不依赖受信证书。

置回 "false" 后重建：首页恢复 200，API 恢复 OK。与部署篇排障速查第 2 条互相印证：HTTP 被强跳打不开时，改回 false 且必须重建（restart 不刷新参数）。

四、ADMIN_IP_ALLOWLIST：管理端 IP 白名单（实测，重点）

官方语义（.env.example 注释原文）在网关层限制 /admin 的可达来源，三种种取值：

• 空 = 不限制（默认）；
• private = 仅放行回环与 RFC1918 私网段（127/8、10/8、172.16/12、192.168/16）；
• 逗号分隔的 CIDR/IP 列表（如 192.168.1.0/24,10.0.0.0/8）。

注释还写明：非白名单来源的请求会被「静默转发给客户端应用，结果是 404 错误」。

实测矩阵（置 ADMIN_IP_ALLOWLIST: "203.0.113.0/24" 后重建，FORCE_HTTPS_REDIRECT 已置回 false）：

$ curl -s -o /dev/null -w "admin_noXFF=%{http_code} redirect=%{redirect_url}\n" http://localhost:8132/admin
admin_noXFF=200 redirect=
$ curl -s -o /dev/null -w "admin_XFF_203.0.113.5=%{http_code} redirect=%{redirect_url}\n" \
    -H "X-Forwarded-For: 203.0.113.5" http://localhost:8132/admin
admin_XFF_203.0.113.5=302 redirect=http://localhost:8132/admin/user/login?ReturnUrl=%2Fadmin
$ curl -s -o /dev/null -w "admin_XFF_198.51.100.7=%{http_code} redirect=%{redirect_url}\n" \
    -H "X-Forwarded-For: 198.51.100.7" http://localhost:8132/admin
admin_XFF_198.51.100.7=200 redirect=
$ curl -s -o /dev/null -w "client_root=%{http_code}\n" http://localhost:8132/
client_root=200
$ curl -s http://localhost:8132/api
OK

逐条解读：

1. 本机直连 /admin（不带 X-Forwarded-For，源地址落在 RFC1918 网段而非白名单内的 203.0.113.0/24）：返回 200 而非 403/404，报文是客户端单页应用的 index.html（HTML 注释头开头）——请求被静默转发给客户端应用，与官方注释「静默路由到客户端应用」一致；「404」的表述适用于直接请求具体管理端资源路径的场景，/admin 入口本身拿到的是客户端页面。
2. 伪造 X-Forwarded-For: 203.0.113.5（白名单内）→ 302 到管理端登录页 /admin/user/login?ReturnUrl=%2Fadmin，管理端可达。
3. 伪造 X-Forwarded-For: 198.51.100.7（白名单外）→ 200，回到客户端页面回退。
4. 白名单只影响 /admin，客户端首页与 /api 完全不受影响（200 / OK）。

机制结论（与源码网关配置一致）：白名单命中阻断时走 @admin_fallback 静默回退，不回 403 也不回 404——被拦者看到的是一个正常的客户端页面，无从得知管理端是否存在，也不会因返回码差异暴露管理端入口。**这带来一个重要的运维判据：判断白名单是否放行不能看状态码，要看 /admin 是否 302 到登录页。**若只记录「返回 200」就断定白名单没生效（第一轮实测即犯此误），会得出完全相反的结论。

两个细节（源码网关脚本注释）：回环地址（127.0.0.0/8）永远放行，不受白名单约束；列表中的非法 CIDR 项会被告警跳过（warning: ADMIN_IP_ALLOWLIST: ignoring invalid CIDR/IP ...），若全部条目非法则收敛为「除回环外全部阻断」，宁可错杀不可放行。

五、TRUSTED_PROXIES：可信上游与 X-Forwarded-For（实测联动）

官方语义：控制网关接受哪些上游代理提交的 X-Forwarded-For 头来还原真实客户端 IP。三态：空 = 信任全部 RFC1918 网段（兼容默认）；逗号分隔 CIDR/IP 列表 = 仅信任指定上游（官方建议：前面有 HAProxy/Traefik/Cloudflare 等反代时配置）；none = 不信任任何上游，日志永远记录直连对端 IP。

第四节实测同时是本参数的行为证明：默认配置下源地址属 RFC1918（10.x 网桥网段）的请求，其 X-Forwarded-For 头被网关采纳并参与白名单判定——否则第 2 条的 302 不会出现。网关配置中 real_ip_header X-Forwarded-For 与 real_ip_recursive on 与该行为吻合。

安全视角提示：默认「信任 RFC1918」意味着同网段任何主机都能通过伪造 X-Forwarded-For 冒充白名单 IP——第四节里 302 与回退的翻转仅由一个请求头决定。若 8132/8133 端口暴露给局域网或公网，必须把 TRUSTED_PROXIES 收敛为 none 或实际反代地址，并配合防火墙。完整的利用面分析与收敛步骤在《AliasVault 0.31.1 安全加固指南》展开。

六、MAX_UPLOAD_SIZE_MB：上传上限（实测）

官方语义：客户端到服务端请求体的大小上限（MB），默认 100，同步大保险库遇到 413 Request Entity Too Large 时调大。该参数最终渲染为网关的 client_max_body_size（实测确认配置文件中生成 client_max_body_size 1M;）。

实测（置 MAX_UPLOAD_SIZE_MB: "1" 后重建）：向 POST /api/v1/auth/validate-username 提交 3145764 字节的 JSON 请求体：

$ stat -c "big.json=%s bytes" /tmp/big.json
big.json=3145764 bytes
$ curl -s -o /dev/null -w "big_POST=%{http_code}\n" -X POST http://localhost:8132/api/v1/auth/validate-username \
    -H "Content-Type: application/json" --data-binary @/tmp/big.json
big_POST=413

3MB 请求体被 1MB 上限拦下，返回 413。拦截发生在网关层（先于应用），因此无论目标端点是什么、是否已登录，超限一律 413。恢复默认 100 后重建，常规请求无影响。

一个实测方法论注脚：本轮第一发探针曾误报 400——排查后发现是测试载荷文件生成脚本的重定向作用域错误，实际只发出了 2 字节，与组件行为无关；修正载荷为 3145764 字节后即得 413。探针实验必须先核实请求体真实大小再下结论，这也是把勘误写入实验记录的原因。

七、SMTP 参数组（实测）

7.1 SMTP_ADVERTISED_HOSTNAME：对外公示主机名

SMTP banner 与 EHLO 中公示的主机名，留空默认 aliasvault；官方建议与服务器公网 IP 的 PTR 反解记录一致以改善投递。部署篇已实测 banner 与参数值的对应关系，本次复核（值 mail.aliasvault.local.test）：

$ timeout 6 bash -c 'exec 3<>/dev/tcp/127.0.0.1/8143 && timeout 5 cat <&3 | head -c 60'
220 mail.aliasvault.local.test v11.1.0.0 ESMTP ready

banner 首行与参数值逐字一致，参数即改即生效。

7.2 SMTP_TLS_ENABLED：STARTTLS 开关与证书回退

开启后 SMTP 服务向连接方提供 STARTTLS；证书必须自备——签发给邮件主机名（多域名用 SAN 证书），合并为单个 .pem 放入 certificates/smtp/ 目录。官方注释同时预告了无证书时的行为：记警告日志、以非 TLS 模式继续运行。实测与注释完全一致（置 true 且目录为空后重建）：

$ timeout 6 bash -c 'exec 3<>/dev/tcp/127.0.0.1/8143 && timeout 5 cat <&3 | head -c 60'
220 mail.aliasvault.local.test v11.1.0.0 ESMTP ready
[05:10:06 WRN] AliasVault.SmtpService.Workers.SmtpServerWorker SMTP TLS is enabled but certificate could not be loaded: No .pem certificate files found in folder: '/certificates/smtp'. Falling back to non-TLS mode. To fix: place valid .pem certificate file(s) in /certificates/smtp {"Application": "AliasVault.SmtpService"}

服务没有拒绝启动，banner 正常，但 WRN 级日志明确提示 TLS 证书加载失败、回退非 TLS 模式。官方注释补充：关闭 TLS 对投递率影响有限（仅约不足 1% 的发信方强制要求 TLS），所以该参数可以放心保持 false 直到证书就位；开启后务必到管理端日志确认无此 WRN。

7.3 PRIVATE_EMAIL_DOMAINS 与 HIDDEN_PRIVATE_EMAIL_DOMAINS

PRIVATE_EMAIL_DOMAINS 声明别名邮箱的收信域名，逗号分隔可多个（本文取 aliasvault.local.test）；置空则整体关闭别名收信特性。HIDDEN_PRIVATE_EMAIL_DOMAINS 用于下线过渡：列在其中的域名仍正常收信、建立别名认领，但不出现在界面的域名下拉与设置项中——注意官方要求这些域名必须同时还在 PRIVATE_EMAIL_DOMAINS 里。两个参数均需配套 DNS（MX 指向服务器、SPF/DKIM 按官方邮件服务文档配置）。

八、静态参数速览

以下参数的行为由官方注释与源码定义，属于「配置即语义」，未逐项做破坏性实测，取值要点如下：

其中 secrets 三件套是实例的安全根（JWT 签名密钥、数据保护证书口令、数据库口令），与 admin_password_hash 一起纳入备份策略——加密备份与恢复演练见《AliasVault 0.31.1 安全加固指南》。

九、21 参数速查总表

十、收尾

把 21 个参数过完，三条主线值得记住：注册开关是公网实例的第一道闸（200/400 一探便知）；FORCE_HTTPS_REDIRECT 与部署路线的 TLS 能力强绑定，非标准端口下谨慎开启；ADMIN_IP_ALLOWLIST 的「静默回退」设计让返回码失去判别力，验证白名单要看 /admin 是否 302 到登录页，而它的可信度又取决于 TRUSTED_PROXIES 是否收敛。参数层之上还有一整层加固动作——管理端凭据治理、密钥文件保护、加密备份、TLS 反代与暴露面收敛——全部在《AliasVault 0.31.1 安全加固指南》逐项落地。