FireMail Plus 项目部署
【摘要】 一、功能概览类别说明多邮箱聚合同时管理多个账号,支持 Gmail、Outlook、QQ 邮箱、163 邮箱、自定义 IMAP/SMTP认证方式OAuth2(Gmail、Outlook)与自定义 IMAP/SMTP 密码;Gmail 目前仅支持应用专用密码登录实时同步基于服务器推送(SSE)的实时邮件同步搜索全文搜索与高级过滤附件附件上传、下载与预览界面响应式设计,适配桌面与移动端;支持明暗...
一、功能概览
| 类别 | 说明 |
|---|---|
| 多邮箱聚合 | 同时管理多个账号,支持 Gmail、Outlook、QQ 邮箱、163 邮箱、自定义 IMAP/SMTP |
| 认证方式 | OAuth2(Gmail、Outlook)与自定义 IMAP/SMTP 密码;Gmail 目前仅支持应用专用密码登录 |
| 实时同步 | 基于服务器推送(SSE)的实时邮件同步 |
| 搜索 | 全文搜索与高级过滤 |
| 附件 | 附件上传、下载与预览 |
| 界面 | 响应式设计,适配桌面与移动端;支持明暗主题自动切换 |
| 运维友好 | 内置健康检查与日志系统,具备数据库自动备份机制 |
| 多架构镜像 | 镜像提供 amd64 与 arm64 两种架构,树莓派等设备可用,镜像体积较小(约 86MB) |
二、部署方案选择
| 方案 | 适用场景 | 说明 |
|---|---|---|
| Docker Compose | 长期使用、生产环境 | 官方推荐,克隆仓库后使用其中的 Compose 文件 |
| Docker CLI | 快速体验、测试 | 一条命令启动,本文第四章给出完整示例 |
| 源码运行 | 二次开发 | 需 Go 环境与 pnpm,前端默认 3000 端口,后端默认 8080 端口 |
本文以 Docker 为主。
三、环境要求
- Linux 服务器或家用主机(amd64 或 arm64)
- Docker Engine 与 Docker Compose 插件
- 内存:512MB 以上即可;磁盘:取决于同步的邮件与附件量
- 默认服务端口:3000
- 服务器能够主动访问目标邮箱的 IMAP 与 SMTP 服务(常用 993、465、587 端口)。部分云厂商会限制出站的 25 端口,但 465 与 587 通常可用
- 若使用公网域名,需要域名解析与 HTTPS 反向代理
四、Docker 部署
4.1 Docker CLI 快速启动
# 1. 拉取镜像
docker pull luofengyuan/firemailplus:latest
# 2. 创建数据卷
docker volume create firemail_data
docker volume create firemail_logs
# 3. 生成密钥
openssl rand -hex 32 # 用作 JWT_SECRET
openssl rand -hex 32 # 用作 ENCRYPTION_KEY
# 4. 运行容器
docker run -d \
--name firemail-app \
--restart unless-stopped \
-p 3000:3000 \
-v firemail_data:/app/data \
-v firemail_logs:/app/logs \
-e ADMIN_USERNAME=admin \
-e ADMIN_PASSWORD=请替换为强密码 \
-e JWT_SECRET=填入第一个随机值 \
-e ENCRYPTION_KEY=填入第二个随机值 \
luofengyuan/firemailplus:latest
# 5. 查看状态与日志
docker ps
docker logs -f firemail-app
说明:
- 容器内数据目录为
/app/data,日志目录为/app/logs,务必挂载为持久化卷。 ENCRYPTION_KEY在官方说明中是可选项,用于加密保存的邮箱凭据。建议配置,并和JWT_SECRET一起长期保存。- 官方 README 的示例里还带有一个
EXTERNAL_OAUTH_SERVER_URL变量,指向作者提供的第三方 OAuth 中转服务,详见本文第六章。
4.2 Docker Compose(推荐长期使用)
官方方式是克隆仓库,复制环境变量模板后启动:
git clone 仓库地址 firemailplus # 仓库为 fengyuanluo 名下的 firemailplus
cd firemailplus
cp .env.example .env
# 编辑 .env:修改管理员密码与 JWT_SECRET,建议同时配置 ENCRYPTION_KEY
docker compose up -d
docker compose ps
docker compose logs -f
注意:README 中写的是 docker-compose(带连字符),新版 Docker 请使用 docker compose(带空格)。
如果想自己维护 Compose 文件,可以参考下面按 4.1 命令改写的版本:
services:
firemail:
image: luofengyuan/firemailplus:latest
container_name: firemail-app
restart: unless-stopped
ports:
- "127.0.0.1:3000:3000"
volumes:
- firemail_data:/app/data
- firemail_logs:/app/logs
environment:
ADMIN_USERNAME: admin
ADMIN_PASSWORD: ${ADMIN_PASSWORD}
JWT_SECRET: ${JWT_SECRET}
ENCRYPTION_KEY: ${ENCRYPTION_KEY}
volumes:
firemail_data:
firemail_logs:
同目录下的 .env:
ADMIN_PASSWORD=请替换为强密码
JWT_SECRET=请替换为随机值
ENCRYPTION_KEY=请替换为随机值
要点:
- 端口绑定到 127.0.0.1,由反向代理对外提供 HTTPS,避免明文暴露。
.env含有密钥,不要提交到代码仓库。- 变量名与容器内路径来自官方 Docker CLI 示例,若你使用的镜像版本有调整,请以仓库里的
.env.example为准。 - 镜像标签:
latest与带提交编号的标签(例如 main 开头的标签)都可使用。生产环境建议固定到某个具体标签,升级时再手动修改。
4.3 首次登录
访问「服务器IP地址:3000」,使用环境变量里设置的管理员账号登录。
- 默认管理员账号是 admin,默认密码是 admin123(官方建议修改)。这是公开信息,部署时务必通过环境变量改成强密码,不要使用默认值。
- 登录后,在账号管理中添加你的邮箱。
五、添加邮箱账号
5.1 通用 IMAP/SMTP
选择自定义邮箱,填写:
| 项目 | 说明 |
|---|---|
| IMAP 服务器与端口 | 收信,常见为 993(SSL) |
| SMTP 服务器与端口 | 发信,常见为 465(SSL)或 587(STARTTLS) |
| 用户名与密码 | 多数邮箱要求使用「授权码」或「应用专用密码」,而不是登录密码 |
5.2 各类邮箱提示
| 邮箱 | 提示 |
|---|---|
| QQ 邮箱、163 邮箱 | 需要先在邮箱设置中开启 IMAP/SMTP 服务,并生成授权码,客户端填写授权码 |
| Gmail | 目前仅支持应用专用密码登录,需要账号开启两步验证后生成应用密码 |
| Outlook | 支持 OAuth2 登录;个人账号的基础认证策略可能变化,以微软当前规则为准 |
5.3 安全建议
- 优先使用授权码或应用专用密码,不要把主密码交给任何第三方客户端,包括自建的。
- 该工具会保存你的邮箱凭据(经加密),所以服务器本身与其备份都必须当作高敏感资产保护。
- 邮件内容往往含验证码、账单、重置链接,部署在公网时更要重视访问控制。
六、关于外部 OAuth 服务
官方示例里的 EXTERNAL_OAUTH_SERVER_URL 指向作者提供的第三方 OAuth 服务,用于配合 Gmail、Outlook 的 OAuth2 授权流程。我的理解是:
- 如果你只使用 IMAP/SMTP 授权码或应用密码方式,通常不依赖这项服务。
- 如果要使用 OAuth2 登录,授权过程会经过该第三方服务器,你需要信任它。
- 对隐私要求高的场景,建议先阅读仓库说明,评估是否使用,或自行申请 OAuth 应用并按项目文档配置。
这部分属于我对 README 的解读,不同版本的行为可能不同,请以仓库说明为准。
七、反向代理与 HTTPS
Caddy 示例:
mail.你的域名 {
encode zstd gzip
reverse_proxy 127.0.0.1:3000
}
使用 Nginx 时请注意:
- 项目使用服务器推送(SSE)做实时同步,需要关闭对该路径的代理缓冲(
proxy_buffering off),并延长读超时,否则新邮件提醒会延迟。 - 适当调大请求体大小限制,以便上传较大的附件。
- 保持升级头与长连接设置正常。
额外建议:
- 在代理层或防火墙上限制访问来源,或放在 VPN 之后使用。
- 为管理员账号使用强密码,并定期更换。
八、备份与恢复
8.1 备份内容
| 内容 | 说明 |
|---|---|
| 数据卷 firemail_data | 应用数据,包括账号、设置、同步数据与数据库 |
| JWT_SECRET 与 ENCRYPTION_KEY | 必须长期保存,丢失后无法解密已保存的邮箱凭据 |
| Compose 与 .env | 部署配置 |
| 日志卷 firemail_logs | 按需备份,通常不是必须 |
官方 README 对此有明确警告:JWT_SECRET 要长期保存;如果配置了 ENCRYPTION_KEY 也必须保存,否则历史邮箱凭据无法解密。
8.2 备份方法
在容器停止或低峰时执行,使用临时容器打包数据卷:
docker run --rm \
-v firemail_data:/data:ro \
-v "$PWD":/backup \
alpine tar czf /backup/firemail-data-$(date +%F).tar.gz -C /data .
注意:
- 项目自身有数据库自动备份机制,但那些备份也在同一台服务器上,不能替代异地备份。
- 备份文件包含凭据密文,请加密保存并同步到异地,遵循 3-2-1 原则:3 份副本、2 种介质、1 份异地。
- 邮件本身仍保存在你的邮箱服务商处,这里备份的是客户端的配置与同步数据,两者要区分。
8.3 恢复
- 部署相同或兼容版本的镜像。
- 把备份解压回数据卷。
- 使用原来的 JWT_SECRET 与 ENCRYPTION_KEY 启动。
- 登录后检查邮箱账号是否能正常连接。
九、升级与维护
# Docker Compose
cd firemailplus
docker compose pull
docker compose up -d
docker image prune
# Docker CLI
docker pull luofengyuan/firemailplus:latest
docker stop firemail-app && docker rm firemail-app
# 然后用原来的 docker run 命令(含数据卷和环境变量)重新启动
建议:
- 升级前先备份数据卷,并留意仓库的更新说明。
- 查看项目与镜像的更新频率。作为个人项目,更新节奏可能不固定,选用前应确认它仍在维护,并关注安全修复。
- 固定镜像标签,避免意外升级带来行为变化。
- 定期查看日志与健康状态,确认邮箱同步正常。
十、安全检查清单
- 管理员密码是否已改掉默认值?
- JWT_SECRET 与 ENCRYPTION_KEY 是否为随机强值,并已备份到安全位置?
- 服务是否只通过 HTTPS 对外提供,3000 端口是否只绑定本机?
- 邮箱是否使用授权码或应用专用密码,而不是主密码?
- 是否评估并决定了是否使用第三方 OAuth 中转服务?
- 数据卷与备份是否加密保存?
- 是否限制了访问来源,或放在 VPN 之后?
十一、常见问题排查
| 现象 | 可能原因 | 处理办法 |
|---|---|---|
| 无法访问页面 | 端口未放行或容器未启动 | 检查端口映射、防火墙与容器日志 |
| 默认账号登录失败 | 已通过环境变量改了账号密码 | 使用你设置的用户名与密码 |
| 邮箱连接失败 | 服务器不能访问 IMAP/SMTP 端口,或使用了登录密码 | 检查出站网络,改用授权码或应用密码 |
| QQ 或 163 邮箱登录失败 | 未开启 IMAP/SMTP 服务或授权码错误 | 在邮箱设置中开启服务并重新生成授权码 |
| Gmail 登录失败 | 未开启两步验证或未使用应用密码 | 开启两步验证并生成应用专用密码 |
| 新邮件延迟出现 | 反向代理缓冲了 SSE | 关闭缓冲并延长超时 |
| 重启后账号凭据全部失效 | 密钥变化 | 使用原来的 JWT_SECRET 与 ENCRYPTION_KEY |
| 数据丢失 | 没有挂载数据卷 | 确认 /app/data 已持久化 |
| 附件上传失败 | 反向代理请求体限制 | 调大限制 |
| OAuth 登录失败 | 外部授权服务不可用或配置不匹配 | 改用授权码方式,或检查相关配置 |
十二、命令速查
# 启动 / 停止 / 重启(Compose)
docker compose up -d
docker compose down
docker compose restart
# 查看日志
docker logs -f firemail-app
# 生成随机密钥
openssl rand -hex 32
# 升级(Compose)
docker compose pull && docker compose up -d
# 备份数据卷
docker run --rm -v firemail_data:/data:ro -v "$PWD":/backup alpine \
tar czf /backup/firemail-data-$(date +%F).tar.gz -C /data .
【声明】本内容来自华为云开发者社区博主,不代表华为云及华为云开发者社区的观点和立场。转载时必须标注文章的来源(华为云社区)、文章链接、文章作者等基本信息,否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱:
cloudbbs@huaweicloud.com
- 点赞
- 收藏
- 关注作者
评论(0)