Debian 邮件系统安装教程

1.1 系统选择

其他 Linux 系统的安装命令可能存在差异，请根据实际系统自行查阅对应官方文档。

1.2 检查运行软件并安装基础工具

请使用 root 账户在宝塔终端或 SSH 终端执行。本教程面向 Debian 12 / 13，软件安装使用 Debian 自带的 apt-get；其他步骤尽量采用常见 Linux Shell、coreutils、sudo 和 systemd 命令。

一次执行基础工具安装，并在安装完成后检查 curl 是否可用：

apt-get update && apt-get install -y curl sudo ca-certificates libmariadb3 iproute2 && command -v curl

/usr/bin/curl

1.3 安装宝塔面板

本教程统一使用宝塔官方稳定版安装脚本。Debian 12 和 Debian 13 均使用同一条安装命令，不区分系统版本。第 1.2 步已安装 curl，直接使用 curl 下载并执行安装脚本。

curl -fL --retry 3 --connect-timeout 15 -o installStable_12.sh https://download.bt.cn/install/installStable_12.sh && bash installStable_12.sh 3Tmtilpm

安装完成后，如需查看宝塔面板登录信息，可执行：

bt default

外网面板地址: http://服务器公网IP:面板端口/安全入口
内网面板地址: http://服务器内网IP:面板端口/安全入口
username: 安装时生成的用户名
password: 安装时生成的密码

调出宝塔综合查询操作面板：

bt

宝塔面板命令行管理菜单
……
请选择要执行的功能：

1.4 放行防火墙

根据实际部署情况，在服务器防火墙或云厂商控制台放行以下端口：

腾讯云检查「防火墙」规则，阿里云检查「安全组」规则。

1.5 域名解析

在域名服务商的 DNS 管理页面，增加以下解析记录：

如果要使用子域名作为邮箱后缀，还需要增加对应的解析记录：

前缀    A    服务器 IP

1.6 安装网站运行环境

进入宝塔面板 → 软件商店，安装以下运行环境：

1.7 安装启用 PHP 拓展

PHP 8.2 以上版本（新部署优先 8.3、8.4 或 8.5）大部分拓展已经安装，可能需要手动修改 PHP 配置文件启用。打开 PHP 设置中的配置文件，检查以下拓展是否启用：

extension=openssl
extension=mbstring
extension=pdo_mysql
extension=sodium
extension=zip
extension=curl

如果对应配置行前面存在分号 ;，删除分号即可启用。修改后重启 PHP。

1.8 创建空数据库

进入宝塔面板 → 数据库 → 添加数据库，创建一个全新的空数据库。

2.1 检查系统架构

可在宝塔终端或 SSH 终端中执行，确认服务器 CPU 架构。

uname -m

x86_64

2.2 下载并安装 hMailServer

以下命令适用于 hMailServer 6.3.8，使用 root 权限执行。请在下拉框中选择服务器实际安装的 Debian 版本，页面只显示对应安装包和命令。

curl -fL --retry 3 --connect-timeout 15 -o hmailserver_6.3.8-1~debian13_amd64.deb https://www.progressiverobot.com/hmailserver/Hmail-server/6.3.8/hmailserver_6.3.8-1~debian13_amd64.deb && \
echo 'f36cbfb856f7f6a33bc1b7459d01b015d1cdc1905208c308f1f48223d84245c1  hmailserver_6.3.8-1~debian13_amd64.deb' | sha256sum -c - && \
apt-get install -y ./hmailserver_6.3.8-1~debian13_amd64.deb

curl 下载进度完成（100%）
...
hmailserver_6.3.8-1~debian13_amd64.deb: OK
...
Unpacking hmailserver (...) ...
Setting up hmailserver (...) ...

curl -fL --retry 3 --connect-timeout 15 -o hmailserver_6.3.8-1~debian12_amd64.deb https://www.progressiverobot.com/hmailserver/Hmail-server/6.3.8/hmailserver_6.3.8-1~debian12_amd64.deb && \
echo 'e35afb6653614a5973b2c6a14ae908ef819938097a5bfdc6abf1511c806bdc14  hmailserver_6.3.8-1~debian12_amd64.deb' | sha256sum -c - && \
apt-get install -y ./hmailserver_6.3.8-1~debian12_amd64.deb

curl 下载进度完成（100%）
...
hmailserver_6.3.8-1~debian12_amd64.deb: OK
...
Unpacking hmailserver (...) ...
Setting up hmailserver (...) ...

官方版本与校验值来源：hMailServer 6.3.8 下载与校验页面。本节命令针对 x86-64（amd64）；如果 uname -m 输出 aarch64，请下载对应 Debian 版本的 ARM64（arm64）软件包，不要执行这里的 amd64 命令。

2.3 配置 MariaDB 连接

编辑 hMailServer 数据库配置文件：

/etc/hmailserver/hMailServer.ini

找到 [Database] 配置段，按下面内容填写。数据库密码必须与第 1.8 步创建的 MariaDB 用户密码一致：

[Database]
Type=MySQL
Server=127.0.0.1
Database=hmailserver
Username=hmailserver
Password=数据库密码
Passwordencryption=0
Port=3306
Internal=0

2.4 检查配置文件并初始化数据库

先读取配置报告，并确认输出中的 Database type: 1（表示 Type=MySQL，兼容 MariaDB）；再实际测试数据库连接，最后初始化数据库。注意：--check-config 只输出配置报告，本身始终返回退出码 0，并不会替你判断配置是否正确，因此命令额外用 grep 检查数据库类型，类型不正确就停止。

config_output=$(sudo -u hmailserver -- hmailserver --check-config) && \
printf '%s\n' "$config_output" && \
printf '%s\n' "$config_output" | grep -Eq '^Database type:[[:space:]]*1[[:space:]]*$' && \
sudo -u hmailserver -- hmailserver --check-database && \
sudo -u hmailserver -- hmailserver --create-database

Configuration file: /etc/hmailserver/hMailServer.ini
Program directory:  /usr/share/hmailserver/
Data directory:     /var/lib/hmailserver
Log directory:      /var/log/hmailserver
Database type:      1

Configuration: /etc/hmailserver/hMailServer.ini
Database: MySQL/MariaDB on 127.0.0.1:3306, database hmailserver, as hmailserver
Connected.

Database hmailserver created on MySQL at schema version 6108, from
/usr/share/hmailserver/DBScripts/CreateTablesMySQL.sql.

2.5 设置 hMailServer 管理员密码

默认使用 123456。

若使用其他密码，需要修改 宝塔目录/wwwroot/mail_admin/config/hmailserver_api.php 配置文件中的 hMailServer 管理员密码配置项，确保与实际设置的密码一致。

设置 hMailServer 管理员密码，执行以下命令后按终端提示输入：

hmailserver --set-admin-password

（输入密码时终端不显示字符）
命令完成后返回 shell 提示符。

紧接着执行：echo $?
0

• 这是 hMailServer 管理后台的密码。
• 它不是 MariaDB 数据库密码，也不是斑马邮箱 PHP 后台密码。
• 终端输入密码时通常不会显示字符。
• 本教程默认使用 123456；如果改用其他密码，必须同步修改 PHP 后台 API 配置文件中的对应密码。
• 默认密码的使用前提是 REST API 只监听 127.0.0.1:8045，仅供本机 PHP 管理后台调用；不得将监听地址改为 0.0.0.0 或公网 IP。
• 必须保持 TCP 8045 的公网入站访问关闭：不要在 Debian 防火墙、宝塔防火墙、云安全组或服务器厂商防火墙中添加 8045 放行规则。不开放公网 8045 不影响本机通过 127.0.0.1 调用 API。
• 如果服务器上运行其他不可信本地程序，仍建议将管理员密码改为独立强密码。

2.6 启动 hMailServer 服务

请在 root 终端执行，设置开机自动启动、立即启动服务，并检查运行状态：

systemctl enable --now hmailserver && systemctl is-active hmailserver && systemctl --no-pager --full status hmailserver && ss -lntp | grep hmailserver

Created symlink .../multi-user.target.wants/hmailserver.service → .../hmailserver.service.
active
● hmailserver.service - hMailServer, a mail server for SMTP, IMAP and POP3
     Loaded: loaded (.../hmailserver.service; enabled; preset: enabled)
     Active: active (running) since ...

以上命令还会检查 hMailServer 当前监听的 TCP 端口。若没有 LISTEN 输出，请先检查服务状态和日志。

LISTEN 0 4096 0.0.0.0:25   0.0.0.0:* users:(("hmailserver",pid=1234,fd=20))
LISTEN 0 4096 0.0.0.0:587  0.0.0.0:* users:(("hmailserver",pid=1234,fd=21))
LISTEN 0 4096 0.0.0.0:110  0.0.0.0:* users:(("hmailserver",pid=1234,fd=22))
LISTEN 0 4096 0.0.0.0:143  0.0.0.0:* users:(("hmailserver",pid=1234,fd=23))

2.7 启用 REST API

请在 root 终端执行，将 REST API 设置为仅本机访问的 8045 端口，然后重启服务并检查端口监听：

hmailserver --set-setting RestApiPort=8045 && \
hmailserver --set-setting RestApiBindAddress=127.0.0.1 && \
systemctl restart hmailserver && \
systemctl is-active hmailserver && \
ss -lntp | grep ':8045'

active
LISTEN 0 4096 127.0.0.1:8045 0.0.0.0:* users:(("hmailserver",pid=1234,fd=30))

如果命令未正常完成，请检查服务状态与日志：

journalctl -u hmailserver -n 100 --no-pager

部署核对

3.1 上传程序并解压

wwwroot/
└── mail_admin/
    ├── config/
    │   └── database.php
    └── public/
        └── index.php

以上为关键目录结构示意，其他程序文件和目录以实际压缩包内容为准。

3.2 配置数据库连接信息

宝塔目录/wwwroot/mail_admin/config/database.php

按实际环境填写数据库地址、数据库名称、用户名和密码。数据库名称与用户名均为 hmailserver，密码使用创建数据库时设置的密码。

3.3 添加站点

进入宝塔面板 → 网站 → 添加站点，填写准备使用的域名。

网站域名请使用第 1.5 步中配置的 mail 记录；确认 DNS 解析已添加后，再继续创建站点。

宝塔目录/wwwroot/mail_admin

宝塔目录/wwwroot/mail_admin/public

3.4 Nginx 伪静态设置

进入宝塔面板 → 网站 → 对应站点 → 设置 → 伪静态，将以下规则粘贴到伪静态规则编辑框中。保存后检查配置并重启 Nginx。

location ~ ^/(admin|web|webmail|hmailadmin)/index$ {
    return 301 /$1/$is_args$args;
}
location ~ ^/(admin|web|webmail|hmailadmin)/(?!index\.html$)(.+)\.html$ {
    return 301 /$1/$2$is_args$args;
}
location / {
    try_files $uri $uri.html $uri/ @thinkphp;
}
location @thinkphp {
    rewrite ^/(.*)$ /index.php?s=/$1 last;
}

3.5 系统运行状态与环境诊断

使用浏览器打开以下地址：

你的域名/check

检查数据库连接和 PHP 扩展是否正常：

• 数据库连接异常：检查第 3.2 步数据库配置，以及第 2.3 步 hMailServer 数据库配置。
• PHP 扩展异常：检查第 1.7 步 PHP 扩展是否已启用，并确认修改后已重启 PHP。

3.6 首次登录斑马邮箱管理后台

网站和数据库配置完成后，使用浏览器打开绑定的域名：

你的域名/admin

3.7 修改管理员账户密码

3.8 关闭系统检查

确认网站、数据库和 PHP 环境均运行正常后，为减少公开的系统诊断信息，可在管理后台关闭系统检查：

系统管理 → 邮箱与系统设置 → 系统检查（关闭）

4.0 切换到邮局管理

打开斑马邮箱管理程序，切换到「邮局管理」模块，进入 hMailServer 相关设置。

4.1 关闭登录失败后自动封禁

进入以下设置位置：

设置与运维 → 系统设置 → 服务器

4.2 在服务器端口中添加 465、587、993、995

进入「服务器端口」设置，检查以下端口是否已经存在；已存在且配置正确时，不需要重复添加。

4.3 重启服务器

请在 root 终端执行；端口和服务器设置保存后，重启 hMailServer 服务并检查状态：

systemctl restart hmailserver && systemctl is-active hmailserver