从零到一：手把手在 Ubuntu 上部署企业级邮件系统 mailcow（避坑指南）

从零到一：手把手在 Ubuntu 上部署企业级邮件系统 mailcow（避坑指南）

📬 你是否厌倦了 Gmail 的广告？是否想拥有完全自主可控的邮箱？本文将带你从裸机开始，在 Ubuntu 服务器上部署功能完整、界面现代、安全可靠的开源邮件系统 mailcow，并解决安装过程中最棘手的“容器健康检查失败”问题。

1. 准备工作：为 mailcow 打造完美运行环境

在开始之前，请确保你有一台干净的 Ubuntu 22.04/24.04 LTS 服务器（推荐 2 核 4GB 内存以上），并已配置好一个可解析到该服务器公网 IP 的域名（如 mail.yourdomain.com）。

1.1 安装 Docker 与 Docker Compose

mailcow 完全基于 Docker 容器化运行，因此首要任务是安装最新版的 Docker 引擎和 Docker Compose。

1.1.1 为什么必须用官方 Docker？

Ubuntu 官方仓库中的 Docker 版本通常严重滞后，而 mailcow 要求 Docker ≥ 24.0.0 和 Docker Compose ≥ 2.0。使用旧版本会导致兼容性问题甚至启动失败。

1.1.2 在 Ubuntu 上一键安装

# 使用官方脚本安装最新版 Docker Engine
curl -sSL https://get.docker.com/ | CHANNEL=stable sh

# 启用并立即启动 Docker 服务
sudo systemctl enable --now docker

1.1.3 安装 Docker Compose 插件

mailcow 强制要求使用 Compose v2。如果你是通过上述脚本安装的 Docker，通常已自带 Compose 插件。为保险起见，手动安装一次：

sudo apt update
sudo apt install docker-compose-plugin

💡 重要提示：插件版的命令是 docker compose（中间是空格），而非旧版的 docker-compose。

1.1.4 验证安装

docker --version      # 应 ≥ 24.0.0
docker compose version # 应 ≥ 2.0

2. 部署 mailcow：克隆、配置与启动

2.1 克隆官方仓库

mailcow 要求以 root 用户 操作，以确保权限正确。

sudo su
umask  # 确认输出为 0022
cd /opt
git clone https://github.com/mailcow/mailcow-dockerized
cd mailcow-dockerized

2.2 生成初始配置

运行配置向导，输入你的完全限定域名（FQDN），例如 mail.example.com：

./generate_config.sh

该脚本会生成 mailcow.conf 文件。

2.3 自定义配置（可选但推荐）

nano mailcow.conf

常见调整项：

SKIP_LETSENCRYPT_CHECK=y：若服务器无法访问公网，可临时跳过证书检查。
修改时区：TZ=Asia/Shanghai
关键：确保 MAILCOW_HOSTNAME 是你的真实域名。

⚠️ 端口冲突处理：如果你的 80/443 端口已被占用（如 Nginx），请修改 docker-compose.yml 中 nginx-mailcow 的 ports 映射：
ports:
  - "81:80"
  - "444:443"

2.4 启动 mailcow

docker compose pull    # 拉取所有镜像
docker compose up -d   # 后台启动

3. 故障排查：解决“容器不健康”顽疾

在实际部署中，你可能会遇到类似错误：

dependency failed to start: container ...-unbound-mailcow-1 is unhealthy

或

dockerapi-mailcow ... Up About a minute (频繁重启)

这通常不是 mailcow 本身的问题，而是依赖服务通信失败。下面我们将逐一击破。

3.1 问题一：unbound 容器无法下载根 DNS 列表

3.1.1 错误现象

docker compose logs unbound-mailcow 显示：

curl: (28) Failed to connect to www.internic.net port 443

3.1.2 根本原因

容器内部 DNS 解析失败，无法访问外网。

3.1.3 解决方案

为 Docker 配置全局 DNS：

# 创建或编辑 Docker 配置文件
sudo nano /etc/docker/daemon.json

添加：

{
  "dns": ["8.8.8.8", "1.1.1.1"]
}

重启 Docker：

sudo systemctl restart docker

然后重建 mailcow：

cd /opt/mailcow-dockerized
docker compose down
docker compose up -d

3.2 问题二：dockerapi-mailcow 因 Redis 认证失败而重启

3.2.1 错误现象

docker compose ps 显示 dockerapi-mailcow 状态为 Up About a minute，日志显示：

redis.exceptions.TimeoutError: Timeout connecting to server

但 docker exec -it ... redis-cli ping 返回：

(error) NOAUTH Authentication required.

3.2.2 根本原因

Redis 启用了密码认证，但 dockerapi-mailcow 未配置密码。

3.2.3 解决方案

在 mailcow.conf 中设置 Redis 密码：

cd /opt/mailcow-dockerized
nano mailcow.conf

找到 Redis 配置区，设置强密码：

REDIS_PASSWORD=Your_Strong_Redis_Pass_123!

保存后重启：

docker compose down
docker compose up -d

3.2.4 验证

docker exec -it mailcowdockerized-redis-mailcow-1 redis-cli -a Your_Strong_Redis_Pass_123! ping
# 应返回 PONG

3.3 问题三：与其他邮件系统（如 Mailu）冲突

3.3.1 识别冲突

docker network ls 显示存在 mailu_* 网络。

3.3.2 后果

Mailu 与 mailcow 会争夺 SMTP/IMAP 等关键端口，导致服务异常。

3.3.3 解决方案

二选一，彻底卸载其中一个：

# 卸载 Mailu（假设其目录为 /opt/mailu）
cd /opt/mailu
docker compose down --volumes --remove-orphans
docker network prune -f

清理后，再启动 mailcow。

4. 验证与使用：登录你的专属邮箱

4.1 检查服务状态

docker compose ps

所有容器应为 Up X minutes，无 (unhealthy) 标记。

4.2 访问 Web 界面

根据你修改的端口，访问：

普通用户登录：https://your-server-ip:444
管理员后台：https://your-server-ip:444/admin
- 用户名：admin
- 密码：moohoo

🔒 首次访问会提示证书不安全（自签名），点击“高级” → “继续”即可。

4.3 后续配置建议

添加域名：在管理员后台 → “配置” → “域名” 中添加你的域名。
配置 DNS 记录：添加 MX、SPF、DKIM、DMARC 记录以确保邮件收发正常。
申请正式证书：确保域名解析正确且 443/444 端口对外开放，mailcow 会自动申请 Let's Encrypt 证书。

5. 总结

mailcow 是一个强大而复杂的系统，部署过程中的“坑”主要集中在 网络、端口、认证 三大方面。只要掌握以下原则，就能轻松驾驭：

永远使用官方最新版 Docker
所有配置通过 mailcow.conf 修改
遇到容器重启，第一时间看日志
绝不与其他邮件系统共存

现在，你已经拥有了一个完全属于自己的、功能媲美 Gmail 的企业级邮件系统。快去创建你的第一个邮箱吧！📧

附：常用命令速查

# 查看日志
docker compose logs --tail=100 <service>

# 重启服务
docker compose restart <service>

# 查看数据卷（邮件数据在此，切勿删除！）
docker volume ls | grep mailcow