在Ubuntu 26.04上设置PostfixAdmin-果果开发

当您为虚拟用户托管邮件时，需要一种可靠的方式来管理域名、邮箱和别名，而无需手动编辑数据库行。Postfix Admin 是一个基于 Web 的界面，用于管理基于 Postfix 的邮件服务器。

这是“设置和配置邮件服务器”系列文章中的第一篇。它涵盖了所需的 DNS 记录，并展示了如何安装和配置 Postfix Admin、带有免费 Let’s Encrypt 证书的 Nginx、PHP 和 MySQL。

本教程是为 Ubuntu 26.04 编写的，但稍加修改后，相同的步骤应该适用于任何较新版本的 Ubuntu。

前提条件

作为本系列文章的前提条件，您需要：

一台 Ubuntu 26.04 服务器。服务器主机名必须是 FQDN。在本系列中，我们将使用 mail.ggdoc.cn。
一个具有 sudo 权限的用户。

DNS 设置

您需要为邮件系统设置以下 DNS 记录才能正常工作：

A 记录，将您系统的 FQDN（主机名）指向您的邮件服务器 IPv4 地址。

mail.ggdoc.cn. 3600 IN A   23.45.67.89

信息FQDN 由两部分组成：主机名和域名。

MX 记录，用于指定哪个邮件服务器负责代表收件人的域接受电子邮件。在我们的案例中，我们希望所有发送到 @ggdoc.cn 电子邮件地址的邮件都由 mail.ggdoc.cn 邮件服务器接受。

ggdoc.cn.      3600 IN MX  0 mail.ggdoc.cn.

SPF 记录，用于验证哪些邮件服务器被批准代表给定域发送电子邮件。在下面的示例中，我们批准了域邮件服务器（mx），如果 SPF 检查失败，结果将是软失败（~all）：

ggdoc.cn.      3600 IN TXT "v=spf1 mx ~all"

信息您需要将域名和 IP 地址替换为您的真实域名和邮件服务器 IP 地址。

反向 DNS（PTR）

反向 DNS（PTR）是将 IP 地址映射到域名的记录，与将域名映射到 IP 地址的 DNS 正好相反。

大多数邮件服务器会对尝试连接到它们的 IP 地址执行反向 DNS 查找，如果未设置 PTR 记录，则可能不接受来自该服务器的电子邮件。

在大多数情况下，PTR 条目可以通过您的主机提供商 Web 界面设置。如果您看不到该选项，请联系支持团队，请他们为您设置正确的 PTR 记录。

您可以使用 dig 命令来查找给定 IP 地址的反向 DNS。

终端

dig -x 23.45.67.89

输出

23.45.67.89.in-addr.arpa domain name pointer mail.ggdoc.cn.

创建一个系统用户

由于我们正在配置一个带有虚拟用户的邮件服务器，我们需要一个系统用户，该用户将是所有邮箱的所有者，并将被虚拟用户用来访问服务器上的电子邮件。

以下命令将创建一个名为 vmail 的新组和用户，并将用户的主目录设置为 /var/mail/vmail：

终端

sudo groupadd -g 5000 vmail
sudo useradd -u 5000 -g vmail -s /usr/sbin/nologin -d /var/mail/vmail -m vmail
sudo chmod 770 /var/mail/vmail

所有虚拟邮箱都将存储在 /var/mail/vmail 目录中。

安装 Nginx、PHP 和 MySQL

Postfix Admin 是一个基于 PHP 的应用程序。为了能够访问 PostfixAdmin Web 界面，我们需要安装 Web 服务器和 PHP。

运行以下命令安装 Nginx、MySQL、PHP 以及所有必需的 PHP 模块：

终端

sudo apt update
sudo apt install -y nginx mysql-server php-fpm php-cli php-mysql php-mbstring php-xml php-curl php-zip php-intl php-gd php-bcmath php-readline php-sqlite3 git

安装完成后，确认 PHP-FPM 服务和套接字，以便 Nginx 服务器块指向正确的路径：

终端

php -v
systemctl list-units 'php*-fpm.service'
ls -l /run/php/

在 Ubuntu 26.04 上，符号链接 /run/php/php-fpm.sock 指向活动的版本化套接字，例如 /run/php/php8.5-fpm.sock。在 Nginx 中使用符号链接，以便配置在 PHP 次要版本升级后仍然有效。

PostfixAdmin 4.x 使用 Composer 管理其 PHP 库，因此接下来安装 Composer：

终端

sudo apt install -y composer

如果 composer 在最小的 Ubuntu 镜像上缺失，请启用 Universe 存储库并重试：

终端

sudo apt install -y software-properties-common
sudo add-apt-repository -y universe
sudo apt update
sudo apt install -y composer

下载并配置 Postfix Admin

在撰写本文时，4.0.5 是 Postfix Admin 的最新稳定版本。

使用以下 wget 命令从 GitHub 下载 Postfix Admin 发布压缩包：

终端

cd /tmp
wget https://github.com/postfixadmin/postfixadmin/archive/refs/tags/v4.0.5.tar.gz -O postfixadmin-4.0.5.tar.gz

下载完成后，解压归档文件并将 Postfix Admin 源文件移动到 /var/www 目录：

终端

tar xzf postfixadmin-4.0.5.tar.gz
sudo mv postfixadmin-4.0.5 /var/www/postfixadmin
cd /var/www/postfixadmin

该仓库附带一个 install.sh 辅助脚本，用于运行 Composer 并创建 Smarty 缓存使用的 templates_c 目录。以您的常规 sudo 用户运行该辅助脚本，以便 Composer 不以 root 身份运行，然后将所有权交给 www-data 并收紧权限：

终端

sudo chown -R "$(id -un):$(id -gn)" /var/www/postfixadmin
/bin/bash install.sh
sudo chown -R www-data:www-data /var/www/postfixadmin
sudo find /var/www/postfixadmin -type d -exec chmod 755 {} \;
sudo find /var/www/postfixadmin -type f -exec chmod 644 {} \;
sudo chmod 750 /var/www/postfixadmin/templates_c

如果 Composer 报告缺少 ext-sqlite3，请安装 php-sqlite3 并重新运行 install.sh。即使使用 --no-dev，当没有 composer.lock 时，PostfixAdmin 仍会解析开发平台要求。

Postfix Admin 将使用 MySQL 数据库来存储有关用户、域和应用程序配置的信息。

终端

sudo mysql

使用以下命令创建一个新的 MySQL 用户和数据库：

CREATE DATABASE postfixadmin CHARACTER SET utf8mb4;
CREATE USER 'postfixadmin'@'localhost' IDENTIFIED BY 'postfixadmin_db_password';
GRANT ALL PRIVILEGES ON postfixadmin.* TO 'postfixadmin'@'localhost';
FLUSH PRIVILEGES;
EXIT;

警告将 postfixadmin_db_password 替换为一个长随机密码。不要重用示例密码，也不要将真实密码或生成的设置哈希提交到版本控制。

我们将不编辑默认的 Postfix Admin 配置，而是将其复制到一个名为 config.local.php 的新文件中，该文件将覆盖默认的应用程序设置：

终端

sudo cp /var/www/postfixadmin/config.inc.php /var/www/postfixadmin/config.local.php

PostfixAdmin 4.x 使用密码哈希保护设置页面。从临时明文密码生成一个哈希并复制输出：

终端

php -r 'echo password_hash("replace-with-setup-password", PASSWORD_DEFAULT), PHP_EOL;'

使用您的文本编辑器打开文件：

终端

sudo nano /var/www/postfixadmin/config.local.php

设置或验证以下值，将生成的哈希粘贴到 setup_password 中：

/var/www/postfixadmin/config.local.phpphp

<?php
$CONF['configured'] = true;

$CONF['database_type'] = 'mysqli';
$CONF['database_host'] = 'localhost';
$CONF['database_user'] = 'postfixadmin';
$CONF['database_password'] = 'postfixadmin_db_password';
$CONF['database_name'] = 'postfixadmin';

$CONF['setup_password'] = 'paste-generated-hash-here';
$CONF['admin_email'] = 'Support <admin@ggdoc.cn>';

$CONF['default_aliases'] = array(
    'abuse'      => 'admin@ggdoc.cn',
    'hostmaster' => 'admin@ggdoc.cn',
    'postmaster' => 'admin@ggdoc.cn',
    'webmaster'  => 'admin@ggdoc.cn'
);

$CONF['encrypt'] = 'ARGON2I';
$CONF['dovecotpw'] = "/usr/bin/doveadm pw";
$CONF['domain_path'] = 'YES';
$CONF['domain_in_mailbox'] = 'NO';
?>

保存并关闭文件。

ARGON2I 设置原生存储与 Dovecot 兼容的密码哈希，因此 PostfixAdmin 无需从 Web 应用程序调用 doveadm 来哈希密码。默认别名会在添加新域时自动创建，因此目标管理员邮箱应在添加域之前存在。

为 Postfix Admin 配置 Nginx

创建一个专用于 PostfixAdmin 的服务器块，并将其文档根目录指向解压树内的 public/ 目录：

终端

sudo nano /etc/nginx/sites-available/mail.ggdoc.cn

粘贴以下配置：

/etc/nginx/sites-available/mail.ggdoc.cnnginx

server {
    listen 80;
    server_name mail.ggdoc.cn;
    root /var/www/postfixadmin/public;

    index index.php index.html;

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

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

    location ~ /\. {
        deny all;
    }
}

如果你的系统上不存在 /run/php/php-fpm.sock，请将其替换为你之前看到的带版本号的路径，例如 /run/php/php8.5-fpm.sock。

启用站点，测试配置，并重新加载 Nginx 服务以使更改生效：

终端

sudo ln -s /etc/nginx/sites-available/mail.ggdoc.cn /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

安装免费的 Let’s Encrypt SSL 证书

我们将使用 SSL 证书来访问我们的 Postfix Admin 安装，并在后续系列中启用 Dovecot 和 Postfix 的 SSL/TLS 加密。

我们已经有一篇关于如何在 Nginx 上安装 Let’s Encrypt SSL 证书的教程。这里我们将使用 Certbot 的 Nginx 插件，它会自动为你编辑服务器块，所以请安装这两个软件包：

终端

sudo apt install -y certbot python3-certbot-nginx

最关键的一点是为你的服务器主机名（FQDN）生成 SSL 证书，在我们的案例中是 mail.ggdoc.cn：

终端

sudo certbot --nginx -d mail.ggdoc.cn

签发完成后，验证 HTTPS 重定向是否正常，以及证书是否有效：

终端

sudo nginx -t
curl -I https://mail.ggdoc.cn/
sudo certbot certificates

运行 PostfixAdmin 安装向导

在浏览器中打开安装页面：

https://mail.ggdoc.cn/setup.php

页面会显示安装摘要、主机环境检查以及数据库更新检查。一旦两项检查均通过，使用你之前在本教程中生成哈希时使用的纯文本安装密码登录。PostfixAdmin 将为你创建或更新数据库结构。

在同一页面中创建你的第一个超级管理员账户。你在这里选择的邮箱账户将用于登录 PostfixAdmin，并管理域名、用户和别名。

如果你更倾向于使用命令行，请以 www-data 身份运行 postfixadmin-cli 工具：

终端

cd /var/www/postfixadmin
sudo -u www-data php scripts/postfixadmin-cli admin add admin@ggdoc.cn --superadmin 1 --active 1 --password 'replace-with-long-password' --password2 'replace-with-long-password'

输出应该类似于以下内容：

输出

Welcome to Postfixadmin-CLI v0.2
---------------------------------------------------------------

The admin admin@ggdoc.cn has been added!

---------------------------------------------------------------

信息在离开安装页面之前，请为超级管理员账户使用一个长的随机密码。

此时，你可以使用刚创建的超级管理员账户，在 https://mail.ggdoc.cn/ 登录你的 Postfix Admin 安装。从那里，添加你的第一个虚拟域，并创建本系列后续部分将用于投递邮件的邮箱。

故障排除

Composer 报告缺少 ext-sqlite3 扩展
安装 php-sqlite3 并重新运行辅助程序：

终端

sudo apt install -y php-sqlite3
cd /var/www/postfixadmin
/bin/bash install.sh

Nginx 返回 502 错误
fastcgi_pass 套接字与正在运行的 PHP-FPM 服务不匹配。请检查活动的套接字并更新服务器块：

终端

ls -l /run/php/
systemctl list-units 'php*-fpm.service'

安装页面报告数据库连接错误
确认 config.local.php 中的 MySQL 用户、密码和数据库名称与你之前创建的值一致，并且该用户对 postfixadmin 数据库具有权限。

在Ubuntu 26.04上设置PostfixAdmin