安装与上线准备

1. 适用范围

以下配置适用于 WMail 单节点或小型生产部署。实际容量受账号数量、并发 IMAP 连接、附件大小、邮件保留周期、反垃圾/防病毒策略和备份周期影响；正式上线前请先做压测和试投递。

2. 操作系统与基础软件

• 推荐系统：Ubuntu 22.04 LTS / Debian 12 / Rocky Linux 9 / AlmaLinux 9，x86_64，内核 5.10+。
• Docker 部署：Docker 24+、Docker Compose v2.20+。
• 二进制/systemd 部署：systemd、Nginx 或等效反向代理、PostgreSQL 15+、Redis 7+。
• 邮件组件：Postfix、Dovecot、Amavisd-new、SpamAssassin；ClamAV 可按安全要求开启。
• 时间同步：启用 NTP/chrony，避免 TLS、DKIM、许可证校验和审计时间偏差。

3. 服务器配置建议

场景	CPU	内存	系统盘	数据盘/存储	适用说明
评估/测试	2 vCPU	4 GB	50 GB SSD	按测试数据准备	仅用于演示、功能验证或少量测试账号，ClamAV 建议关闭。
最低生产单节点	2 vCPU	6 GB	80 GB SSD	邮箱容量总和 × 1.2 以上	适合低并发、小团队起步；开启 ClamAV 时只建议低流量使用。
推荐生产单节点	4 vCPU	8 GB	100 GB SSD	独立 SSD/NVMe 数据盘	适合常规企业生产；建议开启备份、监控、DKIM/DMARC/SPF。
开启 ClamAV 的推荐生产	4 vCPU	12 GB	100 GB SSD	独立 SSD/NVMe，预留扫描临时空间	ClamAV、SpamAssassin、Amavis 与数据库同机运行时更稳；病毒库更新和附件扫描会占用额外内存。
中大型或高附件流量	8 vCPU+	16 GB+	200 GB SSD	独立数据盘/对象存储/备份盘	适合账号较多、附件较大或并发较高；建议拆分数据库、Redis、存储和扫描节点。

经验值：ClamAV 开启后至少额外预留 2-4 GB 内存。生产环境若与 PostgreSQL、Redis、邮件队列同机部署，建议从 4 vCPU / 12 GB 起步；高峰附件扫描明显时使用 8 vCPU / 16 GB 或拆分扫描服务。

4. ClamAV 与反垃圾配置

• 默认部署可先关闭 ClamAV，确认基础收发、DNS、TLS 和许可证正常后再开启。
• 开启 ClamAV 前确认 clamd 可用、freshclam 能更新病毒库，并为病毒库目录和扫描临时目录准备稳定磁盘。
• 建议设置附件扫描上限，例如 25 MB 起步；大附件可根据业务选择跳过、隔离或异步扫描。
• ClamAV 首次启动会下载病毒库，可能需要数分钟；上线脚本和健康检查要预留启动时间。
• 若启用 SpamAssassin + ClamAV，邮件进入 Amavis 内容过滤链路后延迟会增加，应结合队列长度、扫描耗时、CPU load 和内存水位做监控。
• 高流量环境建议将 ClamAV/Amavis 拆到独立节点，或至少为扫描容器设置独立资源限制和重启策略。

5. 磁盘、备份与容量规划

• 系统盘不要承担大量邮箱数据；建议将 /data、Maildir、附件、日志和备份放到独立数据盘。
• 邮箱数据盘按“授权邮箱配额总和 × 1.2-1.5”规划，另预留增长空间。
• 备份空间按“保留周期内全量 + 增量”规划，通常准备 1-3 倍有效数据量。
• 日志和队列建议至少预留 20-50 GB，附件流量大时单独规划。
• 生产环境使用 SSD/NVMe，避免低 IOPS 云盘承载数据库、Redis 和 Maildir 热数据。

6. 网络、域名与端口

• 准备固定公网 IP，并配置 PTR/rDNS，避免发信信誉受影响。
• DNS 至少包括 MX、A/AAAA、SPF、DKIM、DMARC；上线前用测试域名完成投递验证。
• 常用端口：25 SMTP 入站，465/587 提交发信，993 IMAP TLS，995 POP3 TLS（如启用），80/443 Web 与证书校验。
• 云厂商如默认封禁 25 端口，需要提前申请解封或规划外发 SMTP 中继。
• 生产环境必须启用 TLS 证书，并确认服务器时间、证书链和域名一致。

7. 数据库、Redis 与部署方式

• Docker Compose 部署适合单节点快速交付；生产环境应固定镜像版本、挂载持久化目录并设置重启策略。
• 二进制/systemd 部署适合已有 PostgreSQL、Redis、Nginx 和运维体系的环境。
• PostgreSQL 建议 15+，开启定期备份、慢查询观察和磁盘告警。
• Redis 建议 7+，配置密码、持久化策略和内存上限，避免缓存挤占系统内存。
• 如果账号规模、审计日志或投递量增长，优先拆分数据库和 Redis，再拆分扫描与存储。

8. 安装前检查清单

1. 已确认许可证、授权域名、部署模式和安装包来源。
2. 已准备服务器规格、数据盘、备份盘、快照或异地备份策略。
3. 已确认防火墙、安全组、端口放行、NTP 和 DNS 记录。
4. 已准备数据库、Redis、管理员初始密码和 SMTP/IMAP/POP3 暴露策略。
5. 已决定是否开启 ClamAV；若开启，已确认内存、病毒库更新和扫描临时空间。
6. 已准备 TLS 证书、反向代理配置和上线回滚方案。

9. 安装步骤

Docker Compose

1. 下载交付包并解压到目标目录。
2. 复制环境变量模板，填写域名、数据库密码、Redis 密码、端口、许可证和安全开关。
3. 执行 docker compose pull 和 docker compose up -d。
4. 等待数据库、Redis、后端、Web、邮件组件和可选 ClamAV 健康检查通过。
5. 登录管理后台，完成许可证激活、域名同步、DNS 检查和试投递。

二进制/systemd

1. 准备 PostgreSQL、Redis、Nginx、TLS 证书和运行用户。
2. 上传 wmail-server 与配置文件，创建数据、日志、附件和备份目录。
3. 配置 systemd 服务和环境变量，执行启动前检查。
4. 启动服务后检查 /health、日志、数据库连接、Redis 连接和邮件组件状态。
5. 配置反向代理与 HTTPS，再进入管理后台完成上线验证。

10. 常见排查

• 启动失败：先看环境变量、数据库/Redis 连接、端口冲突和数据目录权限。
• 登录或许可证异常：检查服务器时间、授权域名、网络访问和许可证服务连通性。
• 发信失败：检查 25/465/587 出站策略、PTR/rDNS、SPF/DKIM/DMARC 和邮件队列。
• 收信失败：检查 MX、25 入站、防火墙、安全组、Postfix/Dovecot 状态。
• ClamAV 启动慢或占内存：确认病毒库下载状态，给 clamd 预留内存，必要时拆分扫描节点。
• 下载慢或离线部署：使用内网镜像或联系支持团队获取离线交付包。

生产上线前建议至少完成一次内部试投递、一次恢复演练和一次许可证续租/心跳验证。

使用配置与上线检查

1. 许可证激活

1. 登录授权平台购买或获取许可证。
2. 在管理后台「平台配置 → 许可证管理」完成激活或同步许可证。
3. 确认当前授权已开通完整 WMail 能力，例如 SMTP/IMAP/POP3、共享邮箱、SSO/LDAP 或 AI。

2. 授权域名与 DNS

• 先同步许可证中的授权域名，后台不能手工新增业务域名。
• 在「平台配置 → 域名管理」执行 DNS 检查、所有权验证或 Nginx 配置生成。
• 按部署要求完成 SPF / DKIM / DMARC 等记录配置。

3. 邮件协议与登录配置

• SMTP / IMAP / POP3 的访问地址、端口和加密方式以当前部署实例配置为准，不以官网示例地址为准。
• 如需第三方客户端接入，先确认本地服务与授权状态正常。
• 如需 2FA、SSO 或 LDAP，先在后台完成相应配置，并用测试账号验证登录链路。

4. 运行与合规检查

• 用请求日志、健康检查和 Prometheus 指标确认运行态。
• 如使用外发 SMTP 中继，先完成测试连接和测试发信。
• 上线前完成内部试投递，并检查审计日志、反垃圾策略和备份恢复是否正常。

建议上线前先进行内部试投递。