R44VC0RP/superlocal · 上手攻略

  • 仓库：R44VC0RP/superlocal
  • 链接：https://github.com/R44VC0RP/superlocal
  • 分类：邮件客户端 / 开发者工具 / Inbox SDK
  • 作者：Tom
  • 更新：2026-09-07

这是什么

Superlocal 是一个基于 Inbox SDK 的邮件客户端 + 提供商网关。它把多个邮箱账号统一到一个收件箱，同时保持各账号的独立身份、凭证和提供商能力互不干扰。支持 Gmail / Yahoo / Outlook 等主流邮箱的自定义接入，也提供离线 mock 模式（首次运行自动带两个虚构邮箱），无需任何真实凭证即可体验完整界面。

⚠️ GitHub 已验：依赖 Bun 1.4+（README 明确标注）；Docker 镜像发布在 ghcr.io/r44vc0rp/superlocal；仅 Web 端口暴露，backend 隔离在容器内。

解决什么问题

  • 开发者：需要一个本地可跑的邮件客户端，用于开发、测试、演示，不依赖真实账号
  • 多账号用户：统一管理 Gmail + 工作邮箱 + 个人邮箱，各账号身份完全隔离
  • 隐私敏感用户：自托管，所有邮件数据留在本地或自己的服务器
  • 产品经理 / 设计师：快速预览基于 Inbox SDK 的邮件客户端 UI，不需要配置任何 OAuth

快速安装

环境要求

  • Bun 1.4+（必须）
  • 或 Docker + docker compose

本地开发模式（推荐）

# 安装依赖
bun --no-env-file install

# 启动
bun --no-env-file run start

# 打开浏览器
# → http://localhost:5178

首次运行自动创建两个虚构邮箱（mock 模式），可直接体验全部功能，无需配置任何 OAuth 或真实账号。

  • bun --no-env-file run dev：热重载开发模式（React 诊断开销大，建议大邮箱时用 start）
  • Ctrl+C 停止客户端和本地服务

Docker 部署

docker compose up -d --build --wait
# 打开 → http://localhost:5178

容器镜像为预构建的优化版，不包含用户配置、邮件或密钥。首次运行同样创建 mock 模式。

关键卷： - /persist/superlocal.local.json：配置文件 - /persist/data/mock/：虚构邮件和数据库 - /persist/data/real/：真实模式下创建

⚠️ 不要运行两个共享同一卷的实例；不要用 docker compose down -v（会删数据卷）；更新后重新 up 时卷自动保留。

直接用已发布镜像（不本地构建）

SUPERLOCAL_IMAGE=ghcr.io/r44vc0rp/superlocal:latest \
 docker compose up -d --no-build --pull always --wait

可换成 sha-<commit-sha> 固定版本。

核心用法

配置真实邮箱（生产模式）

在 docker compose 环境下设置以下环境变量：

# 启用 Google 认证
SUPERLOCAL_AUTH_METHOD=google
SUPERLOCAL_AUTH_ALLOWED_EMAILS=you@example.com,teammate@example.com
SUPERLOCAL_WEB_ORIGIN=https://mail.example.com

# Google OAuth 凭证
SUPERLOCAL_GOOGLE_CLIENT_ID=your-google-web-client-id
SUPERLOCAL_GOOGLE_CLIENT_SECRET=your-google-web-client-secret

然后在应用内将模式切换为 real，并启用所需邮箱提供商（Gmail 等）。

⚠️ Google OAuth 回调 URI 需在 Google Cloud Console 注册： - https://mail.example.com/api/auth/callback/google（应用登录） - https://mail.example.com/v1/oauth/google/callback（Gmail 连接）

架构速览

┌─────────────────────────────────┐
│  Browser (React SPA, port 5178) │
│  └── 每次登录是独立用户会话       │
└──────────────┬──────────────────┘
               │  仅 Web 端口对外
┌──────────────▼──────────────────┐
│  Docker Container                │
│  ├── Backend (API, auth, mail)  │
│  ├── auth.sqlite (Better Auth)  │
│  └── mail DB (SQLite)           │
└─────────────────────────────────┘
  • 邮件、附件、设置、认证图像均需有效会话
  • 健康检查端点公开，用于健康监控
  • HTTPS 必须（生产 origin）；loopback 模式仍拒绝公网 origin

数据持久化注意事项

  • host.sqlite、邮件数据库、运行时密钥一起存于 /persist
  • runtime-secrets.json 密钥由 retained session key 派生，丢失会导致所有登录状态失效
  • 建议整体备份（配置 + 数据库 + 密钥），而非单独备份

典型适用场景

  • 本地邮件客户端开发：不碰真实数据，快速迭代 UI
  • 隐私优先的自托管邮件网关：多账号统一入口，数据完全自控
  • 团队演示：mock 模式无需账号，任意时刻可演示
  • Gmail API 集成测试：基于真实 Inbox SDK，行为接近生产

坑与注意

  1. Bun 版本必须 1.4+：低于此版本行为未定义
  2. GHCR 镜像默认私有：首次需要在 GitHub Packages 页面手动将包设为 public，否则拉取失败
  3. Google 认证不支持通配符域名：allowedEmails 必须是精确地址，空白列表拒绝所有人
  4. session 不跨用户共享：切换登录人会清空应用上下文，旧 Tab 无法使用新 session
  5. macOS 安装不自动导入旧数据：从本地迁移到远程时需重新配置提供商
  6. 数据库降级受限：Inbox SDK 数据库迁移是单向的，降版本可能需要重建数据
  7. 健康检查无认证：用于监控，不用于邮件访问

与同类对比

项目 简介 与 Superlocal 对比
Thunderbird 成熟开源邮件客户端 功能完整但 UI 古老；Superlocal 更适合开发者自托管
Mailspring 跨平台邮件客户端，统一多账号 有商业账号限制；Superlocal 基于 Inbox SDK 更灵活
SimpleLogin / Anonymise 邮件别名服务 完全不同的定位；Superlocal 是完整客户端而非别名工具
Roundcube Webmail 自托管方案 需要 PHP + IMAP；Superlocal 基于专有 SDK，提供统一 API

Superlocal 的核心差异：开发者友好 + Inbox SDK 驱动 + 完整的账户隔离 + mock 零配置演示。

一句话结论

如果你是开发者，想要一个可以本地零配置体验、也可以自托管的多账号邮件前端，Superlocal 是一个值得关注的新选择——基于 Inbox SDK，mock 模式开箱即用，生产模式支持多账号统一管理。