Freemail Mail Chain + VPS Admin

Important

本机的本地 freemail 部署已停用，请勿再使用。（2026-09-28 停止并取消开机自启）

真正的 freemail 服务：http://mail.example.com:18080/ ，API Token 与部署环境中的 API_TOKEN 相同 需要调用 freemail（生成临时邮箱、收信、取验证码等）时，请直接使用上述远程地址和 token；不要启动或调用本机的 /opt/freemail-db-api（:18080）、/opt/freemail-smtp-ingress（:25）等已停用组件。详见 /opt/freemail-db-api/README.md。

这是一个基于原 freemail 改造的版本，目标是将系统拆成两部分：

• Cloudflare Worker 只保留邮件链路
• VPS 提供单管理员极简后台与 PostgreSQL 存储

当前架构

外部邮件
-> Cloudflare Email Routing
-> freemail-mail-chain / freemail-wen-api（当前实际收件入口按你的 Catch-all 决定）
-> VPS /inbound-email
-> PostgreSQL

VPS 管理面板
-> VPS /api/*
-> PostgreSQL

VPS 直收 SMTP

仓库中额外提供了一套最小可用的 VPS 直收入口，位置：tools/smtp-test/。

这套服务的职责是：

• 监听 SMTP 入站
• 解析正文 / HTML / 验证码 / 预览
• 调用现有 DB_API_URL/inbound-email
• 复用现有 PostgreSQL 入库链路

建议环境变量：

SMTP_PORT=25
DB_API_URL=http://127.0.0.1:18080
DB_API_TOKEN=your-db-api-token

本地验证示例：

cd tools/smtp-test
npm install
SMTP_TEST_RECIPIENT="test@example.com" npm run send:test

这套服务适合把 Cloudflare Worker -> VPS /inbound-email 这一段替换成 SMTP -> VPS /inbound-email。

自动迁移单个域名

仓库提供了一个脚本，可在输入域名和 Cloudflare API Token 后自动完成迁移：

npm run migrate:domain -- --domain example.com --token <cloudflare-api-token>

默认会做这些事：

1. 创建 mail.<domain> 的 A 和 AAAA
2. 创建根域 MX 到 mail.<domain>
3. 创建泛子域 MX 到 mail.<domain>
4. 如果发现 *.<domain> 仍指向 route1/2/3.mx.cloudflare.net，会自动删除并替换

如果根域仍被 Cloudflare Email Routing 托管，脚本会保留根域 MX 并提示你先解锁 Email Routing。

网页版域名迁移

如果你已经登录后台的超级管理员账号，也可以直接打开：

• /html/domain-migrate.html

在页面里填写：

1. 域名
2. Cloudflare API Token
3. VPS IPv4 / IPv6
4. TTL

提交后会调用后端 /api/domain-migrate 自动执行迁移。

当前版本特征

• 无 D1 主数据路径
• 无 R2 依赖（不保留原始 EML）
• 只保留正文和元数据
• 单管理员模式
• 不包含多用户管理、发件、收藏、转发等非核心能力

组件说明

1. Cloudflare Worker

Worker 只负责：

• 接收邮件
• 解析邮件正文、HTML、验证码、预览
• 将邮件元数据直接投递到 VPS

不再负责：

• 后台页面
• 邮箱管理 API
• 数据库存储
• 原始 EML 保留

2. VPS 后台

VPS 负责：

• 单管理员登录
• 邮箱列表 / 创建 / 生成 / 删除
• 邮件列表 / 详情 / 删除
• PostgreSQL 存储
• 静态面板托管

公开仓库中的配置说明

仓库里的配置文件已经脱敏，你需要自行替换为真实值。

wrangler.toml

关键变量：

ADMIN_NAME="admin"
ADMIN_PASSWORD="your-admin-password"
JWT_TOKEN="your-jwt-token"
MAIL_DOMAIN="example.com,alt.example.com"
DB_API_URL="http://your-vps-host:18080"
DB_API_TOKEN="your-api-token"

说明：

• DB_API_URL 指向你的 VPS 后端
• DB_API_TOKEN 用于 Worker -> VPS 的安全投递
• MAIL_DOMAIN 是可用根域列表

VPS 后台 API

当前这套单管理员极简版主要保留这些接口：

认证

• POST /api/login
• POST /api/logout
• GET /api/session

域名 / 邮箱

• GET /api/domains
• GET /api/mailboxes
• GET /api/mailbox/info
• POST /api/create
• GET /api/generate
• GET /api/user/quota
• POST /api/mailboxes/pin
• POST /api/mailboxes/toggle-login
• POST /api/mailboxes/change-password
• POST /api/mailboxes/reset-password
• POST /api/mailboxes/batch-toggle-login
• DELETE /api/mailboxes

邮件

• GET /api/emails
• GET /api/emails/batch
• GET /api/email/:id
• GET /api/email/:id/download
• DELETE /api/email/:id
• DELETE /api/emails

说明：

• 无 R2 模式下，/api/email/:id/download 返回 410 raw_email_not_retained
• 邮件详情正文直接来自 PostgreSQL 中的 content / html_content

管理面板

原 freemail 面板已经迁到 VPS，可作为单管理员极简后台使用。

当前首页面板还额外支持：

• 在页面内新增 / 删除根域名
• 生成邮箱时直接使用真实域名，而不是前端域名索引
• 指定随机子域层级（适合泛域名直收场景）

示例地址：

• http://your-vps-host:18080/
• http://your-vps-host:18080/html/login.html

PostgreSQL 要求

数据库需至少包含：

• mailboxes
• messages
• users
• user_mailboxes
• sent_emails

在无 R2 版本中，messages 表建议包含：

• content
• html_content

并允许：

• r2_bucket 为 NULL
• r2_object_key 为 NULL

注意事项

• 如果真实 Catch-all 还指向旧 Worker，那么新代码不会生效
• 要确认哪个 Worker 在实际收件，建议用 wrangler tail + 实际发信联合确认
• 公开仓库中的配置均为示例值，请不要直接用于生产

适用场景

适合：

• 临时邮箱系统本地化
• 只保留 Cloudflare 邮件入口
• 后台和数据完全迁到 VPS
• 单管理员模式

不适合：

• 需要完整原始 EML 存档
• 需要发件
• 需要复杂多用户权限体系