AliasVault 0.31.1 安全加固指南

本文是 AliasVault 专栏的加固篇：在《AliasVault 0.31.1 Docker Compose 部署指南》的部署基线与《AliasVault 0.31.1 配置参数详解》的参数实测之上，给出一份全部经过真实服务器验证的加固清单——管理端凭据、注册开关、密钥文件、HTTPS 与 TLS 反代、备份加密、暴露面收敛，逐项给出证据与操作。实测日期 2026-10-24，组件版本 0.31.1。零知识架构层面的安全设计（端到端加密、主密码不出设备）属产品能力，见《AliasVault 0.31.1 介绍与选型指南》，本文只管部署侧守土。

一、攻击面盘点：先看清守什么

加固前先盘点暴露面。当前服务器四个端口全部绑定在 0.0.0.0（含 IPv6），即对所有网络接口开放：

$ ss -ltn | grep -E ':(8132|8133|8143|8152)\b'
LISTEN 0      4096         0.0.0.0:8143       0.0.0.0:*
LISTEN 0      4096         0.0.0.0:8132       0.0.0.0:*
LISTEN 0      4096         0.0.0.0:8133       0.0.0.0:*
LISTEN 0      4096         0.0.0.0:8152       0.0.0.0:*

对应四类资产：Web 客户端与 API（8132/8133，浏览器扩展与移动 App 的同步入口）、管理端（同端口的 /admin 路径）、SMTP 收信（8143/8152，别名邮件入口）。磁盘侧另有三处高价值目标：数据目录（内嵌 PostgreSQL 全量数据，端到端加密的保险库密文在其中）、secrets 目录（四个密钥类文件）、日志目录。据此排序，本文的加固动作按「先关门、再上锁、后缩面」展开。

二、管理端凭据治理

admin 账号默认不存在——首次部署后管理端没有可用凭据，必须主动初始化（部署篇第六节实录了完整流程：执行官方提供的 reset-admin-password 交互命令，系统生成随机强口令、仅显示一次，口令哈希落盘后重启服务生效）。这一设计本身是安全的：不存在「出厂默认口令」可被爆破。

初始化后要管好三件事：

1. 口令即取即存：reset 输出的随机口令只显示一次，当场存入密码管理器（用 AliasVault 自己存亦是正解）；丢失即重复 reset 流程轮换，旧口令永久作废——轮换无副作用，不必吝啬。
2. 哈希文件看护：口令哈希落盘在 secrets 目录，实测权限与三个密钥文件一致，均为属主可读写（-rw-------）：

$ ls -la secrets/
-rw------- 1 root root  106 10月 24 13:03 admin_password_hash
-rw------- 1 root root   44 10月 24 13:02 data_protection_cert_pass
-rw------- 1 root root   44 10月 24 13:02 jwt_key
-rw------- 1 root root   44 10月 24 13:02 postgres_password

3. 入口收敛：管理端路径叠加 ADMIN_IP_ALLOWLIST（参数行为见配置篇第四节实测：白名单外请求被静默回退到客户端页面，不回 403/404）。但注意两个前提：回环来源恒放行；且白名单判定依赖 X-Forwarded-For 的可信度——若端口直接暴露在局域网，同网段主机可伪造该头穿越白名单（配置篇第四、五节实测复现）。因此 allowlist 必须与第五节的端口绑定、TRUSTED_PROXIES 收敛配套使用，单开无效。

三、注册开关：先建号，后关门

公网可达的实例若开着注册，任何人都能创建账号写入用户表。加固动作一条：PUBLIC_REGISTRATION_ENABLED 置 false。配置篇第二节已给出开关两态的探针实录（validate-username 端点 200/400），本服务器收尾终态即为关闭态：

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

两个操作要点：先建后关——官方注释明确提醒置 false 前先创建好自己的账号；邀请通道保留——关闭公开注册后，新用户仍可通过管理端 Users → Invites 生成的邀请链接注册，家庭/团队场景不受影响。

四、令牌与密钥文件：实例的安全根

secrets 目录四个文件是整台实例的信任锚，语义各不相同：

• jwt_key（44 字节随机）：API 会话令牌（JWT）的签名密钥。API 未携带有效令牌的受保护请求一律 401（实测 GET /api/v1/vault 返回 vault_noauth=401）。由于签发与验签共用此密钥，更换该文件并重启服务后，所有已签发令牌验签失败，等价于全端强制登出——这是令牌疑似泄露时的应急手段。
• data_protection_cert_pass（44 字节随机）：服务端数据保护证书的口令，保护应用层数据的加解密。
• postgres_password（44 字节随机）：内嵌 PostgreSQL 口令，指向外部数据库时按官方说明写入同名文件。
• admin_password_hash（106 字节）：管理端口令的哈希（第二节）。

四文件实测权限均为 0600，保持即可。加固要求三条：不进版本库、不进聊天记录；纳入加密备份（与第六节的数据库备份同一通道）；接受轮换的代价——jwt_key 与 data_protection_cert_pass 更换会使既有会话/受保护数据不可解，属「灾难动作」而非例行操作，日常安全靠文件权限与备份加密保障。

架构层面再强调一次边界：保险库内容与收到的邮件在设备端加密后才落库，服务器侧只有密文（主密码不离开设备），所以数据库文件泄露不直接等于密码泄露。但密文库仍是离线爆破目标，secrets 与备份仍是活口令等价物——服务器侧的每一层都值得认真对待。

五、HTTPS：FORCE_HTTPS_REDIRECT 与 TLS 反代

配置篇第三节实测了 FORCE_HTTPS_REDIRECT=true 的行为：HTTP 全路径 301 到 https://主机/（含 /api，连探针都被拦截），HTTPS 端口在证书可用时正常 200。由此得出两层加固动作：

第一层：上真证书。 All-In-One 部署形态不自带受信 TLS（官方文档明确「需要自己已有的 SSL 代理基础设施」，部署篇第一节引原文），首启生成的证书对位于 certificates/ssl/（cert.pem/key.pem，自签，仅够内网验证）。生产入口应在宿主前置一个 TLS 终结反代，Let's Encrypt 证书按官方 Install Script 路线自动管理，或自备 certbot 签发。反代核心配置样例（宿主 nginx）：

server {
    listen 443 ssl;
    server_name aliasvault.example.com;
    ssl_certificate     /etc/letsencrypt/live/aliasvault.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/aliasvault.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:8132;
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

第二层：开强跳 + 缩绑定。 证书就位后再把 FORCE_HTTPS_REDIRECT 置 true（顺序不能反——无证书开强跳等于把用户推进不可达的 443，配置篇第三节有实测）。同时把部署篇的端口映射从 0.0.0.0 收敛到回环，让公网流量只能走 443 反代入口。

反代链路下的两个联动参数（配置篇第四、五节实测结论，此处给取值）：

• TRUSTED_PROXIES：有宿主反代时显式指定，如 10.89.61.0/24（网关回源网段），不让任意 RFC1918 来源都有资格提交 X-Forwarded-For；完全无反代直接暴露时置 none。
• ADMIN_IP_ALLOWLIST：白名单基于还原后的真实客户端 IP 判定，在上述链路下依然有效；取值 private 是通用起点，再按团队出口 IP 精细化。

六、备份加密与恢复演练（实测）

部署篇第七节用 pg_dump 导出了全新实例的全量备份：83210 字节、39 张建表语句。明文备份是攻击面的一部分——它包含全部用户表、设备表与会话相关数据，拿到它等同于拿到整库密文。备份落盘必须加密，全程实测如下。

加密（AES-256-CBC + PBKDF2 口令派生）：

$ sha256sum backup.sql
0fe2096b4f1e169d833ba731cacffdfe534d3243978cdda0eb911898e2d63b2c  backup.sql
$ openssl enc -aes-256-cbc -pbkdf2 -salt -in backup.sql -out backup.sql.enc -pass pass:<口令>
$ sha256sum backup.sql.enc
a9df84aca6907efcc755e2874f9c535b48166cb47235dc0e1fe84c8550894b8a  backup.sql.enc

密文 83232 字节（对齐分组后较明文略增）。解密回读并比对哈希：

$ openssl enc -d -aes-256-cbc -pbkdf2 -in backup.sql.enc -out backup-decrypted.sql -pass pass:<口令>
$ sha256sum backup-decrypted.sql
0fe2096b4f1e169d833ba731cacffdfe534d3243978cdda0eb911898e2d63b2c  backup-decrypted.sql

解密产物与原库哈希逐字一致。落库验证：将解密产物按部署篇第七节的恢复流程导入临时库，pg_tables 清点得到 39 张表，与源备份的 39 条建表语句吻合，验证后临时库已删除。至此「加密 → 传输 → 解密 → 可恢复」全链路闭环。

口令保管纪律：加密口令与密文备份物理分离（口令在密码管理器、密文在备份介质），二者同失等于裸奔；轮换口令时旧密文仍用旧口令解密，建议在文件名中带日期与代次。secrets 目录四文件（第四节）随同一策略加密归档——没有 jwt_key 的密文库依旧可被离线爆破提速，没有备份的 secrets 则让恢复无从谈起。

七、暴露面收敛清单

把前六节的动作与配置篇参数收拢成一张可执行的清单，按优先级排列：

其中 1、7、8 三项在本服务器已实测达成并保持；2–6 项给出的是生产化补完路径（本测试环境无公网 443 条件，配置篇/部署篇已给出对应行为证据）；第 10 项提醒：滚动更新 latest 标签意味着安全补丁与新增参数随版本来，升级后重读一遍官方 .env.example 的 diff 是最低成本的安全巡检。

八、收尾

AliasVault 的零知识设计把「服务器被拖库」的代价压到了密文层面，但这不是放松部署侧纪律的理由：管理端口令与哈希文件、四个密钥文件、明文备份，任何一项失守都会把攻击者送回起点之内。本文十条清单里，注册关闭、白名单静默回退、HTTPS 强跳、413 拦截全部有配置篇的逐参数实测背书，备份加密有本文的全链路演练背书——参数、部署、加固三篇互为证据链，组合起来才是一台能见人的密码管理服务器。