AliasVault 0.31.1 Docker Compose 部署指南

本文以官方 Docker Compose 部署方案（All-In-One 单容器）为基准，在 64 位 Linux 宿主机上完成全流程实测：从镜像拉取、编排启动、服务验证、管理端初始化到数据库备份。所有命令与回显均为 2026-10-24 实测原文。组件定位与选型背景见《AliasVault 0.31.1 介绍与选型指南》。

一、官方部署形态：为什么选 All-In-One 单容器

AliasVault 官方提供两条自托管路线，先分清再动手：

路线	形态	SSL	适用
install.sh 安装脚本	7 个容器（postgres/client/api/admin/smtp/task-runner/reverse-proxy）	内置自动 SSL（Let's Encrypt）	有公网域名与 80/443 的 VPS
Docker Compose（本文）	1 个容器（s6-overlay 合并全部服务）	无内置 SSL，需自带反代	NAS、家庭实验室、已有 TLS 体系

官方文档（docs.aliasvault.com → Installation → Docker Compose）明确说明单容器方案 "uses s6-overlay to combine all AliasVault's services into one image for convenience"，代价是不带 SSL/TLS，需要「自己已有的 SSL 代理基础设施」。本次实测环境无公网 443 条件，故按官方 Compose 方案落地，与官方文档一一对应。

版本与镜像实查：ghcr.io/aliasvault/aliasvault:latest 于 2026-10-24 拉取，digest sha256:fe1446798b7a391ff6df9eb552408606786d7fb39038f5fa4cd07ca4a18c2ffe，与当时 GitHub releases 最新稳定版 0.31.1 对应。

二、环境规划

项目	本次实测取值	说明
宿主机	64 位 Linux，内核 6.x	官方要求 Docker ≥ 20.10
Docker Compose	v2（`docker compose` 子命令）	官方要求 ≥ 2.0
数据目录	/opt/data/quzuo/tmp/aliasvault/deploy/	database/logs/secrets/certificates 四个子目录由容器首启自动创建
Web 端口	宿主 8132 → 容器 80（HTTP）
Web TLS 端口	宿主 8133 → 容器 443	无证书时仅监听，供反代或后续启用
SMTP 端口	宿主 8143 → 容器 25	别名收信入口
SMTP TLS 端口	宿主 8152 → 容器 587	STARTTLS 提交入口
容器网络	自定义 bridge，`--subnet 10.89.61.0/24`	显式指定，避免与宿主其他栈冲突
邮件域名	aliasvault.local.test	测试用私有域名，生产请换自有域名

启动前复核端口未被占用：

$ ss -ltn | grep -E ':(8132|8133|8143|8152)\b'
（无输出，四个端口均空闲）

三、编写 docker-compose.yml

在数据目录创建 docker-compose.yml，内容如下（在官方文档模板基础上，按本机端口规划改写映射，并显式声明项目名与子网）：

name: aliasvault-0.31.1-stack
services:
  aliasvault:
    image: ghcr.io/aliasvault/aliasvault:latest
    container_name: aliasvault-0.31.1
    restart: unless-stopped

    ports:
      - "8132:80"
      - "8133:443"
      - "8143:25"
      - "8152:587"

    volumes:
      - ./database:/database
      - ./logs:/logs
      - ./secrets:/secrets
      - ./certificates:/certificates

    environment:
      FORCE_HTTPS_REDIRECT: "false"
      PUBLIC_REGISTRATION_ENABLED: "true"
      PRIVATE_EMAIL_DOMAINS: "aliasvault.local.test"
      SMTP_ADVERTISED_HOSTNAME: "mail.aliasvault.local.test"

    networks:
      avnet:
        ipv4_address: 10.89.61.10

networks:
  avnet:
    driver: bridge
    ipam:
      config:
        - subnet: 10.89.61.0/24

要点：

volumes 四件套是官方固定结构：database（内嵌 PostgreSQL 数据）、logs、secrets（自动生成的密钥类文件）、certificates（SMTP TLS 证书，可选）。
FORCE_HTTPS_REDIRECT: "false"：无 SSL 证书的测试环境必须关闭，否则 HTTP 访问会被强制跳转 HTTPS（该参数行为实测见《AliasVault 0.31.1 配置参数详解》）。
PRIVATE_EMAIL_DOMAINS：声明别名邮箱的收信域名，逗号分隔可配多个。
SMTP_ADVERTISED_HOSTNAME：SMTP banner 与 EHLO 中对外公示的主机名，默认 aliasvault，与 MX 记录一致可改善投递兼容性。

四、启动与初始化实录

镜像已在启动前拉取（docker pull ghcr.io/aliasvault/aliasvault:latest）。执行启动：

$ docker compose up -d
 Network aliasvault-0311-stack_avnet Created
 Container aliasvault-0.31.1 Creating
 Container aliasvault-0.31.1 Created
 Container aliasvault-0.31.1 Starting
 Container aliasvault-0.31.1 Started

等待约 20 秒后查看容器状态与健康检查：

$ docker compose ps --format '{{.Name}}\t{{.Status}}'
aliasvault-0.31.1       Up 25 seconds (healthy)

容器内 s6-overlay 依次拉起内嵌 PostgreSQL、API、Admin、Client、SMTP、TaskRunner，启动完成时容器日志尾部输出：

=========================================
🎉 AliasVault is now ready and accessible!
=========================================

🌐 Web Access:
  • HTTP:  http://localhost:80
  • HTTPS: https://localhost:443
  • Admin: https://localhost:443/admin

🔑 Admin Setup:
  • Admin user is not configured by default
  • To configure admin access:
    1. $ docker exec -it aliasvault /bin/bash
    2. $ aliasvault reset-admin-password
    3. $ docker compose restart

📧 Email Ports (if email server enabled):
  • SMTP:     port 25
  • SMTP TLS: port 587

[05:02:47 INF] AliasVault.WorkerStatus.StatusWorker Service AliasVault.SmtpService status changed from Starting to Started {"Application": "AliasVault.SmtpService"}

注意官方提示：Admin 账号默认不配置，需要手动执行一次 reset-admin-password，这是新手最容易卡住的点（管理端初始化见第六节）。

首启自动生成的 secrets 文件：

$ ls -la secrets/
total 20
drwxr-xr-x 2 root root 4096 10月 24 13:02 .
drwxr-xr-x 6 root root 4096 10月 24 13:02 ..
-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

三个 44 字节随机密钥文件分别用于数据保护证书口令、JWT 签名密钥、内嵌 PostgreSQL 口令。这三个文件是实例的安全根，务必纳入备份（安全篇会展开）。

五、服务验证

5.1 网络验证

$ docker network inspect aliasvault-0311-stack_avnet \
    --format '{{range .IPAM.Config}}{{.Subnet}}{{end}} \
    {{range .Containers}}{{.IPv4Address}}{{end}}'
10.89.61.0/24 10.89.61.10/24

子网与静态 IP 均按 compose 声明生效。宿主侧四端口监听确认：

$ 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:*

5.2 Web 客户端与 API

$ curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8132/
200
$ curl -s http://localhost:8132/api
OK

客户端页面返回 200，API 根路径返回 OK。浏览器访问 http://<服务器IP>:8132/ 即可注册账号并使用保险库；浏览器扩展与移动 App 连接服务器时填 http://<服务器IP>:8132/api。

5.3 Admin 面板路由

$ curl -s -o /dev/null -w "%{http_code} -> %{redirect_url}\n" http://localhost:8132/admin
302 -> http://localhost:8132/admin/user/login?ReturnUrl=%2Fadmin

/admin 未登录时 302 到 /admin/user/login，与官方文档一致。

5.4 SMTP 服务

对映射到宿主的 25 端口（宿主 8143）发起 TCP 连接，抓取服务端 banner：

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

banner 中的 mail.aliasvault.local.test 正是 compose 里 SMTP_ADVERTISED_HOSTNAME 的值，证明该参数即时生效。587 端口（宿主 8152）同样处于监听状态。

六、管理端初始化（admin 凭据）

容器内执行 aliasvault reset-admin-password 会先要求确认，直接回车取消的实拍：

$ docker exec aliasvault-0.31.1 /bin/bash -c "aliasvault reset-admin-password"
=== AliasVault Admin Password Reset ===

This will reset the admin password with a new randomly generated password.
The current admin password (if any) will be permanently overwritten.

Password reset cancelled

非交互环境下用管道注入确认字符 y：

$ docker exec aliasvault-0.31.1 /bin/bash -c "echo y | aliasvault reset-admin-password"

New Admin Credentials:
Username: admin
Password: (1D@VV9Z2s@ES9px

IMPORTANT:
1. Save this password securely - it will not be shown again
2. The password hash has been saved to /secrets/admin_password_hash
3. Restart the Docker container for the new password to take effect

密码只显示这一次，哈希落在 secrets/admin_password_hash。随后重启容器生效：

$ docker compose restart
 Container aliasvault-0.31.1 Restarting
 Container aliasvault-0.31.1 Started
$ docker compose ps --format '{{.Name}}\t{{.Status}}'
aliasvault-0.31.1       Up 20 seconds (healthy)
$ ls secrets/
admin_password_hash
data_protection_cert_pass
jwt_key
postgres_password

此时 http://<服务器IP>:8132/admin 即可用上述凭据登录管理面板（用户管理、系统日志、SMTP 状态等）。上例口令来自一次性测试环境，任何人在自己服务器上都必须以自己执行 reset-admin-password 生成的随机口令为准。

忘记密码时的重置就是重复本节流程，官方 troubleshooting 的说法是 "This will generate a new random password and update the secret"。

七、数据库备份实测

单容器内嵌 PostgreSQL。官方给出的备份命令（在 compose 目录执行）：

$ docker compose exec aliasvault pg_dump -U aliasvault aliasvault > /opt/data/quzuo/tmp/aliasvault/backup.sql
$ echo $?
0
$ stat -c%s /opt/data/quzuo/tmp/aliasvault/backup.sql
83210
$ grep -cE "CREATE TABLE" /opt/data/quzuo/tmp/aliasvault/backup.sql
39

全新实例导出 83 KB、39 张建表语句，exit 0。恢复流程（官方 database.mdx）：先 DROP DATABASE IF EXISTS aliasvault WITH (FORCE)、再 CREATE DATABASE aliasvault OWNER aliasvault、最后 psql -U aliasvault aliasvault < backup.sql，均通过 docker compose exec -T aliasvault ... 执行。更完整的加密备份与恢复演练放在《AliasVault 0.31.1 安全加固指南》。

八、日常运维

官方 lifecycle 文档与实测对应的常用操作（均在 compose 目录执行）：

操作	命令	说明
停止	`docker compose down`	移除容器，数据保留在 ./database 等目录
启动	`docker compose up -d`	首启会初始化数据库，再启直接复用
重启	`docker compose restart`	修改 environment 后必须用 down+up 重建才生效
升级	`docker compose pull && docker compose up -d`	官方每 2–3 周发版，迁移自动执行

升级注意：latest 标签滚动更新，升级前先做第七节的 pg_dump 备份；升级后用 docker logs 观察迁移日志直到出现 ready 字样。

九、排障速查

实测与官方 troubleshooting 文档中该部署形态的常见问题：

页面一直转圈 / 容器 unhealthy：内嵌 PostgreSQL 初始化未完成，等 30–60 秒；docker logs aliasvault-0.31.1 看到 AliasVault is now ready 再验证。
HTTP 被强跳 HTTPS 打不开：FORCE_HTTPS_REDIRECT 为 true 且无证书所致，改回 false 后必须 docker compose down && docker compose up -d（restart 不刷新 environment）。
admin 登录页 404 或凭据无效：admin 默认未配置，按第六节初始化；改过密码未重启容器也会无效。
别名无法收信：先看 SMTP banner 是否为 220（5.4 节方法）；再核对 PRIVATE_EMAIL_DOMAINS 是否包含所用域名；生产环境还要确认公网 25/587 可达与 MX 记录（DNS 生效最长 24–48 小时，官方原文提示）。
移动 App 连不上服务器：移动端强制校验受信 CA 证书，自签名/内部 CA 会被系统层拒绝，需给 API 域名配公开信任的 TLS（官方文档原文强调 "no 'Proceed anyway' option"）。

十、下一步

逐项理解 compose/.env 参数行为：《AliasVault 0.31.1 配置参数详解》
管理端安全、JWT 密钥、TLS 反代、备份加密：《AliasVault 0.31.1 安全加固指南》
同组参考：2FAuth（TOTP 验证码自托管）与本文的 All-In-One 形态互为对照。

参考来源（实查日期 2026-10-24）

官方安装文档：docs.aliasvault.com → Installation → Docker Compose（单容器部署、邮件服务器配置、SSL 要求）
官方仓库文档源码：github.com/aliasvault/aliasvault 0.31.1 tarball 内 docs/docs/installation/docker-compose/（index.md、advanced/admin-access.md、advanced/database.mdx、advanced/lifecycle.md、troubleshooting.md）
实测环境：本文全部回显来自本机 Docker Compose 实例（镜像 digest sha256:fe14467...，2026-10-24 拉取）