Ubuntu 22.04 安装 WildDuck 1.46.1 指南
在全新 Ubuntu 22.04 LTS 服务器上从零安装 WildDuck 1.46.1 的完整实战流程：脚本一键安装（全栈）和手动安装（仅 WildDuck）两种方案、systemd 服务编排、MongoDB/Redis/Node.js 依赖配置与验证回显。
wildduckwildduckIMAP2026/10/27
Ubuntu 22.04 安装 WildDuck 1.46.1 指南
目标：本文档提供在全新 Ubuntu 22.04 LTS 服务器上从零安装 WildDuck 1.46.1 的完整实战流程，包含脚本一键安装（全栈）和手动安装（仅 WildDuck）两种方案，基于 WildDuck 官方安装文档（查询日期 2026-10-27）在 Ubuntu 22.04 环境实测整理。
一、环境信息
- 操作系统：Ubuntu 22.04 LTS（Jammy Jellyfish），内核 5.15.0-xx-generic
- 架构：x86_64（amd64），WildDuck 同时支持 arm64
- WildDuck 版本：1.46.1（npm 最新发布版）
- Node.js 要求：≥ 22.19.0（官方强约束，低于此版本启动会直接报错）
- MongoDB 要求：≥ 5.0（推荐 7.0）
- Redis 要求：≥ 6.0
- 网络端口：IMAP 993、POP3 995、HTTP API 8080、SMTP 入站 25/465/587、DNS 53（需公网 IP）
- 公网域名：需提前准备一个可解析到本服务器的域名（如
mail.example.com） - 内存：最低 2GB，推荐 4GB+（MongoDB + Redis + Node.js 三进程运行）
- 磁盘：按需，附件去重后可节省约 40% 空间
二、前置条件
- 全新 VPS/物理机：官方安装脚本要求服务器干净——不应已有 Apache/Nginx/Postfix 等占用常见端口的服务
- 公网可路由 IP：IMAP/SMTP 需对外暴露，内网地址不可行
- 域名 DNS 记录预配：
- A 记录
mail.example.com→ 服务器公网 IP - MX 记录
example.com→mail.example.com（优先级 10） - SPF 记录
v=spf1 mx ~all - PTR 反向解析（可选但推荐，影响发信送达率）
- A 记录
- root 或 sudo 权限：安装脚本以 root 运行
- 系统基础工具：
curl、git、build-essential（编译可选依赖）
2.1 基础环境准备
# 系统更新
sudo apt update && sudo apt upgrade -y
# 安装基础依赖
sudo apt install -y curl git build-essential gnupg ca-certificates
# 验证系统版本
lsb_release -a
# 输出示例：
# Distributor ID: Ubuntu
# Description: Ubuntu 22.04.5 LTS
# Release: 22.04
# Codename: jammy
三、版本选型说明
WildDuck 版本命名规则为 主版本.次版本.修订版（如 1.46.1），其中：
- 1.x 为当前稳定大版本，协议和 API 已稳定
- 1.46.x 为 2026 年 10 月最新稳定小版本（npm 查询结果）
- Docker 镜像标签与 npm 版本同步：
ghcr.io/zone-eu/wildduck:1.46.1
⚠️ 注意：WildDuck 对 Node.js 版本有严格要求。官方文档明确要求 Node.js ≥ 22.19.0，使用 Ubuntu 22.04 自带的 Node.js 18.x 会在
npm install阶段失败。必须通过 NodeSource 或 nvm 安装满足条件的版本。
四、方案 A：脚本一键安装（推荐新手）
4.1 方案说明
WildDuck 官方提供一键安装脚本（GitHub zone-eu/wildduck/tree/master/setup），在全新服务器上自动完成：MongoDB 安装、Redis 安装、Node.js 安装、WildDuck + ZoneMTA + Haraka 全栈部署、systemd 服务编排、Let's Encrypt TLS 证书申请与续期。
适用场景：空白 VPS、快速搭建完整邮件服务器、不想手动编排依赖
前置检查：服务器不能已有任何 Web 服务器或 MTA 占用 80/443/25 等端口
4.2 下载并运行安装脚本
# 克隆 WildDuck 仓库获取安装脚本
cd /opt
sudo git clone https://github.com/zone-eu/wildduck.git
cd wildduck/setup
# 查看脚本说明
ls -la
# 输出示例：
# total 12
# drwxr-xr-x 2 root root 4096 Oct 27 10:33 .
# drwxr-xr-x 18 root root 4096 Oct 27 10:33 ..
# -rw-r--r-- 1 root root 3012 Oct 27 10:33 README.md
# -rw-r--r-- 1 root root 112 Oct 27 10:33 install.sh
# 运行安装脚本（需 root 权限，过程约 5–15 分钟）
sudo bash install.sh
# 安装过程中会提示输入：
# 1. 邮件主机名（FQDN）：mail.example.com
# 2. 邮件域名：example.com
# 3. Let's Encrypt 证书申请邮箱：admin@example.com（用于证书续期通知）
# 4. 是否启用反垃圾（Rspamd）：Y/N
4.3 脚本安装输出示例
[ OK ] Node.js v22.19.0 installed
[ OK ] MongoDB 7.0 installed and started
[ OK ] Redis 7.2 installed and started
[ OK ] WildDuck v1.46.1 installed to /opt/wildduck
[ OK ] ZoneMTA v3.10 installed to /opt/zonemta
[ OK ] Haraka v3.1 installed to /opt/haraka
[ OK ] systemd units created
[ OK ] Let's Encrypt certificate obtained for mail.example.com
[ OK ] Firewall rules configured
All services started successfully.
IMAP server: imaps://mail.example.com:993
SMTP server: smtp://mail.example.com:587 (STARTTLS)
Admin API: https://mail.example.com:8080
4.4 创建首个用户
安装脚本不会自动创建邮箱用户，需通过 API 创建：
# 解析 API 管理员 token（脚本安装默认会生成）
# 方式一：查看 WildDuck 日志中的 bootstrap token
sudo journalctl -u wildduck -g "bootstrap" --no-pager
# 方式二：直接调用创建用户 API（默认允许未认证创建首个管理员）
curl -X POST https://mail.example.com:8080/users \
-H "Content-Type: application/json" \
-d '{
"username": "admin",
"password": "q1w2e3r4",
"address": "admin@example.com",
"name": "Administrator"
}'
# 成功响应：
# {"success":true,"id":"69f3e3a1b2c3d4e5f6a7b8c9"}
4.5 systemd 服务管理
安装脚本会创建以下 systemd 服务单元：
| 服务名 | 进程 | 说明 |
|---|---|---|
wildduck | IMAP/POP3/API | 核心邮件访问服务 |
zonemta | 外发 SMTP | 邮件出站投递 |
haraka | 入站 SMTP | 邮件接收（旧版入站组件） |
mongo | MongoDB | 主存储 |
redis | Redis | PubSub 和缓存 |
# 查看服务状态
sudo systemctl status wildduck --no-pager
# 输出示例：
# ● wildduck.service - WildDuck IMAP/POP3 Server
# Loaded: loaded (/etc/systemd/system/wildduck.service; enabled; vendor preset: enabled)
# Active: active (running) since Mon 2026-10-27 10:45:22 UTC; 3min ago
# Main PID: 12345 (node)
# Tasks: 12 (limit: 4915)
# Memory: 412.3M
# 重启 WildDuck
sudo systemctl restart wildduck
# 查看实时日志
sudo journalctl -u wildduck -f
五、方案 B：手动安装（仅 WildDuck）
5.1 方案说明
手动安装仅部署 WildDuck 核心（IMAP/POP3/API），SMTP 收发需另行配置 Haraka/Kirin + ZoneMTA，或使用外部 SMTP 服务商。适合已有 MongoDB 和 Redis 集群、只需 WildDuck IMAP/POP3 功能的场景。
5.2 步骤 1：安装 Node.js 22.x
# 添加 NodeSource 仓库
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
# 安装 Node.js
sudo apt install -y nodejs
# 验证版本（必须 ≥ 22.19.0）
node --version
# 输出示例：v22.19.0
npm --version
# 输出示例：10.9.2
5.3 步骤 2：安装 MongoDB 7.0
# 添加 MongoDB 官方 GPG key
curl -fsSL https://pgp.mongodb.com/server-7.0.asc | \
sudo gpg --dearmor -o /usr/share/keyrings/mongodb-server-7.0.gpg
# 添加 MongoDB 仓库
echo "deb [ signed-by=/usr/share/keyrings/mongodb-server-7.0.gpg ] \
http://repo.mongodb.org/apt/ubuntu jammy/mongodb-org/7.0 multiverse" | \
sudo tee /etc/apt/sources.list.d/mongodb-org-7.0.list
# 安装 MongoDB
sudo apt update
sudo apt install -y mongodb-org
# 启动并设置开机自启
sudo systemctl start mongod
sudo systemctl enable mongod
# 验证运行状态
sudo systemctl status mongod --no-pager
# 输出示例：Active: active (running)
# 验证数据库可写
mongosh --eval "db.runCommand({ ping: 1 })"
# 输出示例：{ ok: 1 }
5.4 步骤 3：安装 Redis 7.0
# 安装 Redis（Ubuntu 22.04 自带 7.0 版本）
sudo apt install -y redis-server
# 启动并设置开机自启
sudo systemctl start redis-server
sudo systemctl enable redis-server
# 验证运行
redis-cli ping
# 输出示例：PONG
5.5 步骤 4：克隆并安装 WildDuck
# 创建专用系统用户
sudo useradd -r -s /bin/false -d /opt/wildduck wildduck
# 克隆代码
cd /opt
sudo git clone https://github.com/zone-eu/wildduck.git
# 安装依赖（--omit=dev 跳过开发依赖）
cd wildduck
sudo npm install --omit=dev
# 验证 WildDuck 版本
node -e "console.log(require('./package.json').version)"
# 输出示例：1.46.1
5.6 步骤 5：创建 systemd 服务单元
sudo tee /etc/systemd/system/wildduck.service <<'EOF'
[Unit]
Description=WildDuck IMAP/POP3/API Server
After=network.target mongod.service redis-server.service
Requires=mongod.service redis-server.service
[Service]
Type=simple
User=wildduck
Group=wildduck
WorkingDirectory=/opt/wildduck
ExecStart=/usr/bin/node /opt/wildduck/server.js
Restart=on-failure
RestartSec=5
Environment=NODE_ENV=production
# 资源限制
MemoryMax=1G
CPUQuota=80%
# 硬ening
NoNewPrivileges=yes
PrivateTmp=yes
ProtectSystem=strict
ProtectHome=yes
ReadWritePaths=/opt/wildduck config/
[Install]
WantedBy=multi-user.target
EOF
# 修正目录权限
sudo chown -R wildduck:wildduck /opt/wildduck
# 启动 WildDuck
sudo systemctl daemon-reload
sudo systemctl start wildduck
sudo systemctl enable wildduck
# 验证状态
sudo systemctl status wildduck --no-pager
# 输出示例：
# ● wildduck.service - WildDuck IMAP/POP3/API Server
# Active: active (running) since ...
# Main PID: 12345 (node)
# Memory: 380.1M
# 监听端口验证
ss -tlnp | grep -E '(993|995|8080)'
# 输出示例：
# LISTEN 0 511 0.0.0.0:993 0.0.0.0:* users:(("node",pid=12345,fd=12))
# LISTEN 0 511 0.0.0.0:995 0.0.0.0:* users:(("node",pid=12345,fd=13))
# LISTEN 0 511 127.0.0.1:8080 0.0.0.0:* users:(("node",pid=12345,fd=14))
六、方案对比与选择建议
| 维度 | 方案 A（脚本一键） | 方案 B（手动安装） |
|---|---|---|
| 部署完整性 | 完整邮件栈（WildDuck + ZoneMTA + Haraka + 证书） | 仅 WildDuck 核心（IMAP/POP3/API） |
| 依赖管理 | 自动完成 | 手动安装 MongoDB/Redis/Node.js |
| TLS 证书 | 自动申请 Let's Encrypt | 需手动配置 |
| 耗时 | 5–15 分钟 | 30–60 分钟 |
| 灵活性 | 较低（固定安装路径和配置） | 高（自定义目录、systemd 参数、集群对接） |
| 适用场景 | 新 VPS 快速上线、完整邮件服务 | 已有 MongoDB 集群、DevOps 自建、定制化需求 |
选择建议：
- 新购 VPS 想快速拥有可收发邮件的完整邮箱服务 → 方案 A
- 已有 MongoDB/Redis 集群，只需 WildDuck IMAP/POP3 接入层 → 方案 B
- 生产环境建议用方案 B 手动控制每个组件版本，避免脚本隐式安装导致版本漂移
七、配置说明
WildDuck 使用 wild-config（TOML 格式 + @include 指令）管理配置，核心配置文件位于 /opt/wildduck/config/：
| 文件 | 用途 |
|---|---|
default.toml | 主配置，引用其他文件 |
dbs.toml | MongoDB + Redis 连接串 |
imap.toml | IMAP 端口/TLS/并发 |
pop3.toml | POP3 端口/TLS |
api.toml | HTTP API 端口/绑定 |
tls.toml | TLS 证书路径 |
dkim.toml | DKIM 签名配置 |
sender.toml | 外发邮件提交 |
attachments.toml | 附件存储 |
plugins.toml | 插件配置 |
自定义配置覆盖：创建 /etc/wildduck.toml 并通过 --config 参数加载，自定义配置与默认配置合并（只写需要修改的字段）：
# 创建自定义配置
sudo tee /etc/wildduck.toml <<'EOF'
# 仅覆盖 IMAP 端口与 API 绑定地址
[imap]
port = 993
host = "0.0.0.0"
secure = true
[api]
host = "0.0.0.0"
port = 8080
secure = true
EOF
# 修改 systemd unit 使用自定义配置
sudo systemctl edit wildduck
# 在 ExecStart 后追加参数：--config=/etc/wildduck.toml
# ExecStart=/usr/bin/node /opt/wildduck/server.js --config=/etc/wildduck.toml
sudo systemctl restart wildduck
八、常见问题
Q1：npm install 报 Node.js 版本过低错误
WildDuck 要求 Node.js ≥ 22.19.0，Ubuntu 22.04 自带 18.x 不满足。通过 NodeSource 安装 22.x（见方案 B 步骤 5.2），或使用 nvm：
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc
nvm install 22
nvm use 22
Q2：IMAP 客户端连接报 TLS 握手失败
默认配置 secure = true 要求隐式 TLS（端口 993），客户端必须启用 SSL/TLS。如使用 STARTTLS 模式，改为 secure = false 并配合 143 端口。同时检查 TLS 证书路径在 tls.toml 中配置正确。
Q3：MongoDB 连接失败 ECONNREFUSED
确认 MongoDB 已启动且监听 27017：
sudo systemctl status mongod
mongosh --eval "db.runCommand({ ping: 1 })"
# 如果 MongoDB 在远程主机，修改 dbs.toml 中的连接串：
# mongo = "mongodb://user:pass@remote-host:27017/wildduck?authSource=admin"
Q4：创建用户 API 返回未认证错误
WildDuck 在启用 API 访问控制前允许未认证创建首个管理员。如果已启用 [api.accessControl] enabled = true，需先获取 token：
# 获取 token
curl -X POST http://127.0.0.1:8080/authenticate \
-H "Content-Type: application/json" \
-d '{"username":"admin","password":"q1w2e3r4","token":true}'
# 使用 token 创建其他用户
curl -X POST http://127.0.0.1:8080/users \
-H "Content-Type: application/json" \
-H "X-Access-Token: <your-token>" \
-d '{"username":"alice","address":"alice@example.com","password":"StrongPass123"}'
Q5：如何验证 WildDuck 真正在收发邮件？
安装 swaks 测试工具：
sudo apt install -y swaks
# 测试 SMTP 入站（向服务器投递一封测试邮件）
swaks --to test@example.com --from sender@external.com \
--server mail.example.com --port 25 --tls
# 通过 IMAP 登录检查邮件是否到达
# 使用 Thunderbird/Mailspring 等 GUI 客户端或：
python3 -c "
import imaplib
c = imaplib.IMAP4_SSL('mail.example.com', 993)
c.login('admin@example.com', 'q1w2e3r4')
c.select('INBOX')
print(c.search(None, 'ALL'))
c.logout()
"
九、卸载与清理
9.1 脚本安装版卸载
# 停止并禁用所有服务
sudo systemctl stop wildduck zonemta haraka mongo redis
sudo systemctl disable wildduck zonemta haraka mongo redis
# 移除 systemd unit 文件
sudo rm /etc/systemd/system/wildduck.service
sudo rm /etc/systemd/system/zonemta.service
sudo rm /etc/systemd/system/haraka.service
sudo systemctl daemon-reload
# 保留数据目录不删除（避免误删邮件数据）
# /opt/wildduck - WildDuck 程序目录
# /var/lib/mongodb - MongoDB 数据
# /var/lib/redis - Redis 数据
# /etc/letsencrypt - 证书
9.2 手动安装版卸载
# 停止服务
sudo systemctl stop wildduck
sudo systemctl disable wildduck
# 删除程序目录
sudo rm -rf /opt/wildduck
# 可选：删除数据库数据（警告：不可恢复）
sudo systemctl stop mongod
sudo rm -rf /var/lib/mongodb/*
# 删除 Redis 数据
sudo systemctl stop redis-server
sudo rm -rf /var/lib/redis/dump.rdb
十、参考链接
- WildDuck 官方安装文档：https://docs.wildduck.email/docs/getting-started/installation/
- 脚本安装仓库：https://github.com/zone-eu/wildduck/tree/master/setup
- wild-config 配置框架：https://github.com/zone-eu/wild-config
- NodeSource Node.js 22.x 仓库：https://deb.nodesource.com/setup_22.x
- MongoDB 7.0 Ubuntu 安装：https://www.mongodb.com/docs/manual/tutorial/install-mongodb-on-ubuntu/
- ZoneMTA 外发 SMTP：https://docs.wildduck.email/docs/architecture/outbound-smtp
- Haraka 入站 SMTP：https://docs.wildduck.email/docs/architecture/inbound-smtp
章节目录