Ubuntu 22.04 安装 SnappyMail 指南

目标：在一台全新初始化的 Ubuntu 22.04 服务器上，把 SnappyMail 2.38.2 装起来并完成初始化向导，最终实现「管理员配置邮件域 → 用户浏览器登录 → 收到一封真实投递的邮件」的完整验收闭环。本文所有命令均在目标环境实际执行，回显逐行照录。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS（x86_64），主机名 mail.example.com，全新初始化
SnappyMail 版本：2.38.2（官方发布通道 https://snappymail.eu/repository/latest.tar.gz，2026-10-21 下载）
Web 服务器：Nginx 1.18.0（Ubuntu 仓库）
PHP：8.1.2-1ubuntu2.27（PHP-FPM，Unix Socket 模式）
邮件后端：Dovecot 2.3.16（IMAP）+ Postfix 3.6.4（SMTP），与本机 Webmail 同机部署，仅监听本机回环地址
域名约定：邮件域 example.com，测试账号 demo@example.com、alice@example.com（密码 q1w2e3r4，仅实验环境使用）
SnappyMail 是 Webmail 客户端（IMAP/SMTP 的浏览器前端），本身不含邮件服务，需依赖邮件后端，本文第六节给出最小可用后端配置。

二、安装前准备

2.1 更新索引并安装基础软件包

apt-get update
DEBIAN_FRONTEND=noninteractive apt-get install -y nginx php-fpm php-mbstring php-xml \
  php-zip php-curl php-gd php-intl php-ldap php-sqlite3 dovecot-imapd postfix \
  curl wget

安装完成后确认版本与关键 PHP 模块：

php -v | head -1
php-fpm8.1 -v | head -1
nginx -v 2>&1
dovecot --version

实测回显：

PHP 8.1.2-1ubuntu2.27 (cli) (built: ...)
PHP 8.1.2-1ubuntu2.27 (fpm-fcgi) (built: ...)
nginx version: nginx/1.18.0
2.3.16 (d090c76)

2.2 启动服务

systemctl enable --now nginx php8.1-fpm dovecot postfix
systemctl is-active nginx php8.1-fpm dovecot postfix

实测回显（四个服务均为 active）：

active
active
active
active

确认邮件端口只监听本机回环（安全基线：143/993/25 等不应对公网暴露在 Webmail 同机时尽量收敛）：

ss -ltn | grep -E ':(25|143|993|80)\b'

实测回显：

LISTEN 0      100        127.0.0.1:25         0.0.0.0:*    users:(("master",pid=238,fd=13))
LISTEN 0      128          0.0.0.0:80           0.0.0.0:*    users:(("nginx",pid=183,fd=6))
LISTEN 0      100            [::1]:25            [::]:*     users:(("master",pid=238,fd=14))
LISTEN 0      128             [::]:80             [::]:*     users:(("nginx",pid=183,fd=7))
LISTEN 0      128          0.0.0.0:143          0.0.0.0:*    users:(("dovecot",pid=236,fd=56))
LISTEN 0      128             [::]:143            [::]:*     users:(("dovecot",pid=236,fd=51))

说明：本实验环境 Postfix/Dovecot 均通过 inet_interfaces = loopback-only 与回环监听收敛；Webmail 与邮件后端同机时，SnappyMail 走 127.0.0.1 连接 IMAP/SMTP，80 端口是唯一的对外入口。

三、方案 A（主线）：官方发布包 + Nginx + PHP-FPM

3.1 下载与校验

官方稳定版发布通道为 snappymail.eu 仓库的 latest.tar.gz，固定指向最新稳定版（当前即 2.38.2）：

cd /tmp
curl -sL --max-time 120 -o latest.tar.gz https://snappymail.eu/repository/latest.tar.gz
ls -l latest.tar.gz
file latest.tar.gz
sha256sum latest.tar.gz

实测回显：

-rw-r--r-- 1 root root 6816164 Oct 21 03:06 latest.tar.gz
latest.tar.gz: gzip compressed data, from Unix, original size modulo 2^32 73797632
71f1d8a9065cc9cf7ddd064f5c47cc7b255cb70e6a56713647fc73d4b79e33ec  latest.tar.gz

包内版本可通过解压后的 package.json 复核：grep -m1 version package.json → "version": "2.38.2"。

3.2 解压与权限

按官方 Wiki 建议部署到 /var/www/webmail/snappymail：

mkdir -p /var/www/webmail/snappymail
cd /var/www/webmail/snappymail
tar -xzf /tmp/latest.tar.gz
# 目录 755 / 文件 644 / 属主为 PHP-FPM 运行用户 www-data
find /var/www/webmail/snappymail -type d -exec chmod 755 {} +
find /var/www/webmail/snappymail -type f -exec chmod 644 {} +
chown -R www-data:www-data /var/www/webmail/snappymail
ls -l /var/www/webmail/snappymail/

实测回显（关键文件）：

total 24
-rw-r--r--  1 www-data www-data  670 Oct  9  2024 _include.php
drwxr-xr-x  3 www-data www-data 4096 Oct 21 03:09 data
-rw-r--r--  1 www-data www-data 5447 Oct  9  2024 index.php
drwxr-xr-x  2 www-data www-data 4096 Oct  9  2024 .well-known
-rw-r--r--  1 www-data www-data  118 Sep 25  2024 README
...

⚠️ 安全要点：data/ 目录承载全部配置与凭据（含管理员密码哈希、域配置），绝不能允许 Web 直接访问，下一节 Nginx 配置中已用 deny all 封禁。

3.3 配置 Nginx 站点

cat > /etc/nginx/sites-available/snappymail.conf <<'EOF'
server {
    listen 80 default_server;
    listen [::]:80 default_server;
    server_name _;
    root /var/www/webmail/snappymail;
    index index.php;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/run/php/php8.1-fpm.sock;
    }

    location ~ ^/(data|snappymail/V) {
        deny all;
    }
}
EOF
ln -sf /etc/nginx/sites-available/snappymail.conf /etc/nginx/sites-enabled/snappymail.conf
rm -f /etc/nginx/sites-enabled/default
nginx -t && systemctl reload nginx

实测回显：

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

说明：PHP-FPM 默认池 www.conf 监听 Unix Socket /run/php/php8.1-fpm.sock（grep "^listen = " /etc/php/8.1/fpm/pool.d/www.conf 实测回显 listen = /run/php/php8.1-fpm.sock），与 fastcgi_pass 一致。若改用 TCP 9000 端口需同步修改两侧。

3.4 连通性验证

curl -sI http://127.0.0.1/ | head -4

实测回显：

HTTP/1.1 200 OK
Server: SnappyMail
Date: Tue, 21 Oct 2026 03:10:32 GMT
Content-Type: text/html; charset=utf-8

Server: SnappyMail 响应头与 200 状态码说明 PHP 应用已正确接管请求。

四、方案 B（备用）：离线安装（GitHub Release 包）

内网或无法访问 snappymail.eu 的环境，可从 GitHub Releases 下载同一版本的 zip 包（内容结构一致，多一层版本目录），本环境实测：

curl -sL --max-time 120 -o snappymail-2.38.2.zip \
  https://github.com/the-djmaze/snappymail/releases/download/v2.38.2/snappymail-2.38.2.zip
ls -l snappymail-2.38.2.zip
sha256sum snappymail-2.38.2.zip
unzip -l snappymail-2.38.2.zip | head -6

实测回显：

-rw-r--r-- 1 root root 7197601 Oct 21 11:30 snappymail-2.38.2.zip
ad37235002520958094f69bfe97952aab773c5634d68d967db4fc2d439f26399  snappymail-2.38.2.zip
Archive:  snappymail-2.38.2.zip
  Length      Date    Time    Name
---------  ---------- -----   ----
        0  2024-10-09 21:37   snappymail/v/2.38.2/
        0  2024-10-09 21:37   snappymail/v/2.38.2/app/
        0  2024-10-09 21:37   snappymail/v/2.38.2/app/libraries/

解压后把 zip 根目录的 _include.php、index.php、data/、snappymail/ 等条目释放到同一站点目录（如 unzip -q snappymail-2.38.2.zip -d /var/www/webmail/snappymail），后续权限、Nginx、向导步骤与方案 A 完全一致。

五、安装向导（初始化管理员）

5.1 首次访问：生成临时管理员密码

浏览器打开 https://<服务器地址>/?admin（命令行环境可先 curl 触发同样的初始化逻辑）：

curl -s -o /dev/null -w '%{http_code}\n' 'http://127.0.0.1/?admin'
cat /var/www/webmail/snappymail/data/_data_/_default_/admin_password.txt

实测回显：

200
0c3SNaU63l4I

首次访问管理面板时，应用检测到尚未设置管理员凭据，会生成一次性密码文件 data/_data_/_default_/admin_password.txt，同时在 application.ini 写入对应的 password_hash（bcrypt 哈希，可通过 grep -n "admin_password\|admin_login" data/_data_/_default_/configs/application.ini 核对，实测已生成 admin_login = "admin" 与 60 位 $2y$ 开头的哈希）。

5.2 登录并立即修改管理员凭据

在管理面板登录页输入用户名 admin 与临时密码完成登录；登录后进入 Security 页，把默认用户名改为 admin（或自定义），将密码改为强密码。本实验通过管理接口执行同一动作（?/admin/Json 的 AdminPasswordUpdate），实测回显：

{"Result": {"Weak": false}}

改密成功后，临时密码文件会被应用自动删除——这是安全设计，可据此确认初始化已完成：

ls /var/www/webmail/snappymail/data/_data_/_default_/admin_password.txt

实测回显：

ls: cannot access '/var/www/webmail/snappymail/data/_data_/_default_/admin_password.txt': No such file or directory

用新密码重新登录验证（实测 AdminLogin 回显 "Auth": true），向导第一步完成。

5.3 添加邮件域

进入管理面板 Domains 页，点击 Add Domain，填入：

Name：example.com
IMAP：服务器 127.0.0.1、端口 143、加密 None（同机回环场景；跨机建议 TLS 993）、勾选启用
SMTP：服务器 127.0.0.1、端口 25、加密 None、无需认证（本机 Postfix 回环放行；跨机建议 TLS 587 + 认证）

保存后域配置落盘为 data/_data_/_default_/domains/example.com.json（v2.38.2 域配置为 JSON 格式），实测文件已生成且管理接口域列表回显 enabled: true。

提示：首次初始化时应用会把内置模板域（gmail.com、hotmail.com 等默认停用项）与通配域 * 一并写入该目录，生产环境建议删除不用的模板文件。

六、邮件后端最小可用配置（Dovecot + Postfix 本机收发）

若邮件后端尚未就绪，以下是本实验验证过的最小可用配置（仅用于 Webmail 验收与小型内网环境，生产环境请按正式邮件服务器方案建设）：

# 创建两个测试账号（系统用户，Dovecot 走 PAM 认证）
useradd -m -s /bin/bash demo && echo "demo:q1w2e3r4" | chpasswd
useradd -m -s /bin/bash alice && echo "alice:q1w2e3r4" | chpasswd

# Postfix：收下 example.com 的本地邮件，仅监听回环
postconf -e 'mydestination = $myhostname, example.com, localhost.example.com, localhost'
postconf -e 'inet_interfaces = loopback-only'
systemctl reload postfix

Dovecot 在 Ubuntu 22.04 默认配置（PAM 认证 + mbox 存储 /var/mail/%u）无需修改即可配合本机系统用户工作。命令行投递一封测试邮件验证本地链路：

echo "From: alice@example.com
To: demo@example.com
Subject: SnappyMail Install Verification Test

Hello, this is a test mail delivered by Postfix for the SnappyMail acceptance check.
" | sendmail -t
sleep 2 && ls -l /var/mail/

实测回显：

total 4
-rw------- 1 demo mail 546 Oct 21 03:21 demo

Postfix 已把测试邮件投递进 demo 的邮箱，邮件后端收发链路就绪。

七、安装验收

7.1 用户登录

浏览器打开 Webmail 首页，输入 demo@example.com / q1w2e3r4 登录。命令行等价验证（Webmail 登录接口实测）：

{"Result": {"Email": "demo@example.com"}}

登录成功即证明「SnappyMail → Dovecot IMAP 143 → PAM 认证」链路贯通。

7.2 收信验证

登录后应能在收件箱看到第六节投递的测试邮件（主题 SnappyMail Install Verification Test）。底层链路可用 IMAP 直连复核（与 Webmail 实际使用同一认证与存储路径）：

('login:', 'OK ...Welcome.')
('select:', ('OK', ['[READ-WRITE] ...INBOX selected']))
ids: [b'1']
From: alice@example.com
Subject: SnappyMail Install Verification Test

7.3 验收清单

检查项	通过标准
Nginx 站点	`curl -I http://<服务器>/` 返回 200 且 `Server: SnappyMail`
管理面板	`/?admin` 可登录，`admin_password.txt` 已随改密删除
邮件域	Domains 页显示 `example.com` 且启用
用户登录	demo@example.com 可进入收件箱
收信	能读到 Postfix 投递的测试邮件
发信	界面撰写发送后，接收方（alice@example.com）邮箱可见

八、常见安装问题与排障

页面 502：PHP-FPM 未启动或 Socket 路径不一致。systemctl is-active php8.1-fpm，核对 listen = /run/php/php8.1-fpm.sock 与 fastcgi_pass 是否一致。
页面 500 / 空白：PHP 扩展缺失（尤其 mbstring、dom、libxml、zlib）。php -m 对照第四节清单；查看 Nginx error.log 与 SnappyMail data/logs/。
无法保存配置 / 白屏报权限：data/ 目录属主必须是 PHP-FPM 运行用户（www-data），chown -R www-data:www-data /var/www/webmail/snappymail/data。
/?admin 返回 403：管理面板被关闭（application.ini 中 allow_admin_panel = Off）。这是安全开关的正常行为，恢复方法：编辑 data/_data_/_default_/configs/application.ini 将该项改回 On（实测编辑保存后立即生效，无需重启服务）。
登录报 IMAP 连接失败：确认 Dovecot 监听（ss -ltn | grep 143）、域配置里 IMAP 服务器地址/端口/加密方式与实际一致；同机场景用 127.0.0.1 而不是 localhost（避免解析为 IPv6 导致的连接偏差）。
管理面板入口 URL：默认 /?admin；若设置了 security.admin_panel_host，则仅允许从该主机名访问。

九、参考链接

官方安装说明：https://github.com/the-djmaze/snappymail/wiki/Installation-instructions
官方发布通道：https://snappymail.eu/repository/latest.tar.gz
GitHub Release（v2.38.2）：https://github.com/the-djmaze/snappymail/releases/tag/v2.38.2
本专栏姊妹篇：《SnappyMail 2.38.2 介绍与选型指南》（产品认知与选型）、《SnappyMail 2.38.2 配置参数详解》（application.ini 与域配置逐项实测）