English | 中文
通过逆向 iCloud Web 接口和 IMAP 邮件协议,实现 Apple iCloud 隐藏邮箱别名的创建、列出和邮件收取功能。内置中文管理界面(React 单页应用,随二进制内嵌分发)。
别名列表:提速并给出失败原因
- HME 客户端按账号复用。旧版每次操作都要新建 TLS 连接,先 validate、再发业务请求(3~6 秒);现在复用已解析的服务端点,只发一次业务请求。
- 别名列表有 2 分钟缓存。创建、删除、停用、激活后自动失效;页面上的「从 iCloud 刷新」按钮可以强制重新拉取。
- 上游错误分类返回,界面直接显示原因:
- 会话失效(HTTP 401/403/421/450)→
UPSTREAM_UNAUTHORIZED - Apple 限流(429 /
-41015)→UPSTREAM_RATE_LIMITED - 网络或代理不可达 →
UPSTREAM_UNREACHABLE - 其它错误 → 附带 HTTP 状态码和 Apple 错误码
- 会话失效(HTTP 401/403/421/450)→
- 会话失效时不再重试 3 次(旧版要 6 秒才报错);限流时不再连续重试 5 次(旧版要 20 秒,还会加重风控)。
- Cookie 按浏览器格式原样回传:保留双引号,不再与 cookie jar 重复发送;Set-Cookie 的过期指令也会生效。
- 新增会话保活:默认每 15 分钟 validate 一次,并把服务端轮换后的 Cookie 写回磁盘。用
ICLOUD_HME_KEEPALIVE=0关闭。 - 账号页显示具体的失效原因。iCloud 会话失效不会再误触发管理员登出。
收件箱:摘要截断,长邮件不再撑破页面
- 改用完整的 MIME 解析(multipart、base64、quoted-printable、GBK/GB18030 等字符集),不再把原始 MIME 和 base64 当正文显示。
- 列表摘要压成单行、去掉链接、最多 160 字;完整正文点主题查看。text/plain 只有一句「请用 HTML 查看」的邮件,自动改用 HTML 正文。
- 表格固定列宽,摘要最多显示 2 行,「操作」列始终可见。
收件箱:读取、删除提速
- 外部邮箱(QQ、Gmail 等)也走 IMAP 长连接池。旧版每次读信、删信都要重新做 TLS 握手和登录;断线后自动重连并重试一次。
- 列表只批量拉取每封邮件的前 64KB,用一次 UID FETCH 完成;旧版逐封拉取完整邮件,附件也一起下载。
- 时间范围改由服务端
SEARCH SINCE过滤。旧版的天数过滤因为日期格式不匹配,实际从未生效。 - 支持 UIDPLUS 时用
UID EXPUNGE只删除目标邮件;删除成功后前端直接移除该行,不再整页重新拉取。 - 查看详情改用
BODY.PEEK,不会把邮件标记为已读。
弹窗与标签
- 点击弹ç 10BC8 ª—外的遮罩不再关闭弹窗(只能用按钮或 Esc 关闭);创建别名时填写的标签在取消后保留,创建成功后才清空。
- 新增「修改标签」:别名列表的标签旁有编辑按钮,调用 iCloud
/v1/hme/updateMetaData,自动带上原备注,避免被接口清空;接口为PATCH /api/aliases/:id。 - 服务端拒绝含乱码(U+FFFD)的标签,防止编码错误的请求把乱码写进 iCloud。
其它
- 前端请求加了超时,超时后提示原因,不再无限转圈。
- 修复 MailboxDialog 的 lint 错误(原 CI 因此失败),新增解析和错误分类的单元测试。
- ✅ 中文管理界面 — 浏览器访问
http://localhost:8081即开即用 - ✅ 创建 HME 别名 — 自动生成 iCloud 隐藏邮箱地址
- ✅ 列出所有别名 — 查看账号下的所有 HME 别名
- ✅ 收取邮件 — 通过 IMAP 或 Web API 读取发到 HME 别名的邮件
- ✅ 双路径读信 — 邮件读取优先走 IMAP (App Password),无 App Password 时回退 Web API (Cookie)
- ✅ 多账号管理 — 支持多个 iCloud 账号并行管理
- ✅ 双认证模式 — Cookie (创建别名 + 读邮件回退) 和 App Password (IMAP 优先)
- ✅ 安全模型 — 单管理员会话、CSRF 校验、登录限流、响应脱敏
从 GitHub Releases 下载对应平台的二进制文件:
| 平台 | 文件 |
|---|---|
| Linux x86_64 | icloud-hme_linux_amd64 |
| Linux ARM64 | icloud-hme_linux_arm64 |
| macOS Intel | icloud-hme_darwin_amd64 |
| macOS Apple Silicon | icloud-hme_darwin_arm64 |
| Windows x86_64 | icloud-hme_windows_amd64.exe |
# 示例:Linux 下直接运行(必须先设置管理员密码)
export ICLOUD_HME_ADMIN_PASSWORD='change-this-before-running-2026'
chmod +x icloud-hme_linux_amd64
./icloud-hme_linux_amd64# 拉取镜像
docker pull ghcr.io/xiaozhou26/icloud-hme:latest
# 运行(将本机 data 目录挂载进去)
docker run -d \
--name icloud-hme \
-p 8081:8081 \
-v /path/to/data:/app/data \
-e ICLOUD_HME_ADMIN_PASSWORD='change-this-before-running-2026' \
ghcr.io/xiaozhou26/icloud-hme:latest
⚠️ 上面的密码仅为示例,不可照抄,请务必更换为至少 8 字符的强密码。
镜像支持 linux/amd64 和 linux/arm64 双架构,自动适配。
# 前置要求: Go 1.26+、Node.js 22.12+
git clone https://github.com/xiaozhou26/icloud-hme.git
cd icloud-hme
# 一键构建(安装前端依赖 → 前端测试 → 前端构建 → Go 测试 → 编译)
./build.sh
# 或者手动分步构建
npm --prefix web ci
npm --prefix web run build
go build -o icloud-hme .管理界面与 API 均需要管理员登录,升级后所有 API 都必须先通过 POST /api/auth/login 获取会话:
| 环境变量 | 说明 | 默认 |
|---|---|---|
ICLOUD_HME_ADMIN_PASSWORD |
管理员密码,必填,至少 8 字符 | 无(缺失时拒绝启动) |
ICLOUD_HME_SESSION_TTL |
会话有效期 | 12h(范围 15m–168h) |
ICLOUD_HME_SECURE_COOKIE |
通过 TLS 反向代理部署时设为 true |
false |
Breaking Change(v0.3+):升级后未设置
ICLOUD_HME_ADMIN_PASSWORD将拒绝启动; 原有匿名 API 调用将收到401 AUTH_REQUIRED。管理员会话只存内存,进程重启即失效。
在程序 data/ 目录下创建 accounts.json(参考仓库内 accounts.json.template):
{
"accounts": {
"acc_1": {
"id": "acc_1",
"name": "主号",
"real_email": "owner@example.com",
"icloud_email": "owner@icloud.com",
"cookies": {
"X-APPLE-WEBAUTH-TOKEN": "token_value",
"X-APPLE-WEBAUTH-USER": "v=1:s=1:d=22789132008"
},
"host": "icloud.com",
"proxy": "http://user:pass@host:port",
"app_password": "xxxx-xxxx-xxxx-xxxx",
"status": "active"
}
}
}提示: 也可以通过管理界面的「账号」页面动态添加账号,无需手动编辑 JSON 文件。
cookies、app_password、proxy都是可选的。
# 二进制方式(默认 data 目录)
export ICLOUD_HME_ADMIN_PASSWORD='your-strong-password'
./icloud-hme_linux_amd64
# 指定端口和数据目录
./icloud-hme_linux_amd64 -addr :9090 -data ./my_data
# 调试模式(启用请求日志)
./icloud-hme_linux_amd64 -debug
# 查看完整参数
./icloud-hme_linux_amd64 -h服务默认监听 :8081。浏览器打开 http://localhost:8081 进入管理界面(账号 / 别名 / 收件箱)。完整 API 契约见 API.md。
认证:除
POST /api/auth/login与GET /api/auth/session外,所有/api接口都需要管理员会话 Cookie(hme_session);非 GET/HEAD/OPTIONS 请求还需携带X-CSRF-Token请求头。完整契约与 curl 示例见 API.md。
POST /api/create
# 请求体
{
"account_id": "acc_1", # 必填: 账号 ID
"label": "注册某网站" # 可选: 别名标签
}
# 响应
{
"success": true,
"data": {
"email": "xyz123@icloud.com",
"label": "注册某网站",
"created_at": "2024-01-15T10:30:00Z",
"account_id": "acc_1"
}
}GET /api/inbox?account_id=acc_1&alias=xyz123@icloud.com&limit=20&days=7
# 参数说明:
# account_id - 必填: 账号 ID
# alias - 可选: 只读取发到该别名的邮件
# limit - 可选: 返回邮件数量 (默认 20)
# days - 可选: 查找最近几天的邮件 (默认 7,仅 IMAP 模式)
# 响应
{
"success": true,
"data": {
"account_id": "acc_1",
"alias": "xyz123@icloud.com",
"count": 2,
"method": "imap",
"messages": [
{
"id": "1042",
"from": "noreply@example.com",
"to": "xyz123@icloud.com",
"subject": "欢迎注册",
"preview": "感谢您的注册...",
"date": "2026-07-09T14:32:10+08:00"
}
]
}
}
# 读取方式 (自动选择):
# method: "imap" — 通过 App Password 认证 (优先)
# method: "web_api" — 通过 Cookie 认证,无需 App Password (回退)GET /api/accounts
# 响应
{
"success": true,
"data": [
{"id": "acc_1", "name": "主号"},
{"id": "acc_2", "name": "副号"}
]
}简化版(cookies 可选):
POST /api/accounts
# 请求体
{
"name": "新账号",
"host": "icloud.com", # 可选
"proxy": "http://..." # 可选
}
# 响应 - 状态为 pending,需登录
{
"success": true,
"data": {
"id": "acc_xxx",
"name": "新账号",
"status": "pending"
}
}完整版(带 Cookie):
POST /api/accounts
# 请求体
{
"name": "新账号",
"cookies": "{\"x-apple-session-token\":\"token_value\"}", # JSON 或 Header 格式
"host": "icloud.com", # 可选
"proxy": "http://..." # 可选
}
# 响应
{
"success": true,
"data": {
"id": "acc_3",
"name": "新账号",
"status": "active"
}
}POST /api/accounts/:id/login
# 请求体
{
"password": "用户的常规iCloud密码", # 不是 App Password
"otp_code": "123456" # 可选,2FA 验证码
}
# 响应
{
"success": true,
"data": {
"id": "acc_1",
"cookies": {
"x-apple-session-token": "...",
"X-APPLE-WEBAUTH-TOKEN": "..."
}
}
}DELETE /api/accounts/:id
# 响应
{
"success": true,
"data": {"id": "acc_3"}
}POST /api/accounts/:id/password
# 请求体
{
"icloud_email": "your_email@icloud.com",
"app_password": "xxxx-xxxx-xxxx-xxxx"
}
# 响应
{
"success": true,
"data": {
"id": "acc_1",
"icloud_email": "your_email@icloud.com"
}
}GET /api/aliases?account_id=acc_1
# 响应
{
"success": true,
"data": {
"account_id": "acc_1",
"count": 15,
"aliases": [
{
"email": "xyz123@icloud.com",
"label": "注册某网站",
"created_at": "2024-01-15T10:30:00Z"
}
]
}
}POST /api/aliases/:id/deactivate
# 请求体
{
"account_id": "acc_1"
}
# 响应
{
"success": true,
"data": {
"anonymous_id": "abc123",
"success": true
}
}POST /api/aliases/:id/reactivate
# 请求体
{
"account_id": "acc_1"
}
# 响应
{
"success": true,
"data": {
"anonymous_id": "abc123",
"success": true
}
}DELETE /api/aliases/:id
# 请求体
{
"account_id": "acc_1"
}
# 响应
{
"success": true,
"data": {
"anonymous_id": "abc123"
}
}Cookie 认证可实现所有功能:创建别名、读取邮件、管理别名。
适用范围:
- 创建/停用/激活/删除 HME 别名 ✅
- 读取邮件 (通过 iCloud Web API,无需 App Password) ✅
获取 Cookie:
- 使用浏览器登录 icloud.com 或 icloud.com.cn (国区)
- 打开浏览器开发者工具 (F12)
- 进入 Application → Cookies
- 导出全部 Cookie 为
{"key":"value"}格式的 JSON
关键 Cookie (必需):
X-APPLE-WEBAUTH-TOKEN— 认证 tokenX-APPLE-WEBAUTH-USER— 含 dsid (v=1:s=1:d=22789132008)X-APPLE-WEBAUTH-HSA-TRUST— 设备信任 tokenX-APPLE-DS-WEB-SESSION-TOKEN— 会话 token
注意: 导出的 Cookie 值不要包含多余的引号或转义字符。
App Password 用于 IMAP 读取邮件,是邮件读取的优先路径 (支持服务端按收件人搜索)。
生成 App Password:
- 登录 appleid.apple.com
- 进入 "登录和安全" → "App 专用密码"
- 生成新密码,用于此工具
GET /api/inbox 自动选择读取方式:
- 优先: IMAP (App Password) — 设置了 App Password 时使用,支持服务端按收件人 (
TO) 搜索 - 回退: Web API (Cookie) — 无 App Password 或 IMAP 失败时,通过
mccgateway端点读取,本地按别名过滤
响应中包含 "method": "web_api" 或 "method": "imap" 字段,标识实际使用的读取方式。
icloud-hme/
├── main.go # 入口: 读取安全配置、加载账号、启动服务
├── web/ # 前端工程 (React + TypeScript + Vite)
│ └── src/ # 管理界面源码
├── accounts.json # 账号配置文件 (自动生成)
├── go.mod
└── internal/
├── account/
│ ├── manager.go # 多账号管理器 (持久化、客户端工厂)
│ └── public.go # 公开 DTO (Summary) 与输入校验
├── auth/
│ ├── manager.go # 管理员会话 + CSRF
│ └── limiter.go # 登录失败限流
├── hme/
│ ├── client.go # iCloud HME Web 客户端 (Cookie 认证)
│ └── auth.go # SRP 登录 (账号密码 + 2FA 获取 Cookie)
├── mail/
│ ├── client.go # IMAP 邮件客户端 (App Password 认证)
│ └── web_client.go # Web 邮件客户端 (Cookie 认证,无需 App Password)
├── server/
│ ├── server.go # 路由分组 (认证 + CSRF)
│ ├── backend.go # 业务接口与 Manager 适配器
│ ├── auth.go # 登录/会话/退出 handler 与中间件
│ ├── account_handlers.go # 账号管理 handler
│ └── middleware.go # 安全响应头、请求上限
└── webui/
└── embed.go # 内嵌前端资源 + SPA fallback
- account.Manager: 管理多个 iCloud 账号,负责配置持久化和客户端创建
- hme.Client: 封装 iCloud HME Web API,支持 Cookie 认证
- hme.auth: SRP 协议登录,支持账号密码 + 可 8 选 2FA< B8AA /li>
- mail.Client: IMAP 邮件客户端 (App Password,优先读邮件)
- mail.WebClient: 通过 iCloud Web API (mccgateway) 读取邮件,无需 App Password
- server.Server: HTTP API 服务 + 管理界面静态资源
- Go 1.26+ / Gin — HTTP 框架
- React 19 + TypeScript + Vite 8 — 管理界面
- go-imap — IMAP 协议实现
- tls-client — TLS 指纹模拟 (绕过 iCloud 反爬)
A: Cookie 已过期,需要重新获取。iCloud Cookie 有效期通常为 24 小时。
A: 检查网络连接,确保可以访问 imap.mail.me.com:993。
A: 调用 GET /api/inbox?account_id=acc_1&alias=your_alias@icloud.com
A: 支持,在 accounts.json 中配置多个账号即可,每个账号有独立的 id。
# 前端开发模式 (vite dev server, /api 代理到 :8081)
npm --prefix web ci
npm --prefix web run dev
# 后端开发模式
export ICLOUD_HME_ADMIN_PASSWORD='your-strong-password'
go run main.go -debug
# 前端检查 (lint + test + build)
npm --prefix web run check
# 完整构建 (含前端)
./build.sh
# 交叉编译
GOOS=linux GOARCH=amd64 go build -o icloud-hme .
GOOS=windows GOARCH=amd64 go build -o icloud-hme.exe .推送 v* tag 到 GitHub 自动触发 CI:
git tag v0.2.0 && git push origin --tagsActions 会自动构建多平台二进制、Docker 镜像(ghcr.io/xiaozhou26/icloud-hme)并创建 Release。
- 代码注释使用中文
- 错误信息返回给用户时使用中文
- API 响应格式统一:
{success: bool, data: any, message: string}
MIT License
友情链接:LINUX DO
A local management tool for Apple iCloud Hide My Email (HME) aliases, supporting creation, listing, and email reading through reverse-engineered iCloud Web API and IMAP protocol. Ships with a built-in Chinese management UI (React SPA embedded in the single binary).
- Built-in management UI at
http://localhost:8081 - Create HME aliases automatically
- List all aliases for an account
- Read emails sent to HME aliases via IMAP or Web API
- Manage multiple iCloud accounts
- Dual authentication: Cookie and App Password
- Security: single-admin session, CSRF checks, login rate limiting, redacted API responses
Download the latest binary from GitHub Releases:
| Platform | File |
|---|---|
| Linux x86_64 | icloud-hme_linux_amd64 |
| Linux ARM64 | icloud-hme_linux_arm64 |
| macOS Intel | icloud-hme_darwin_amd64 |
| macOS Apple Silicon | icloud-hme_darwin_arm64 |
| Windows x86_64 | icloud-hme_windows_amd64.exe |
# Linux example (admin password is REQUIRED, min 8 chars)
export ICLOUD_HME_ADMIN_PASSWORD='change-this-before-running-2026'
chmod +x icloud-hme_linux_amd64
./icloud-hme_linux_amd64docker pull ghcr.io/xiaozhou26/icloud-hme:latest
docker run -d \
--name icloud-hme \
-p 8081:8081 \
-v /path/to/data:/app/data \
-e ICLOUD_HME_ADMIN_PASSWORD='change-this-before-running-2026' \
ghcr.io/xiaozhou26/icloud-hme:latestThe password above is only an example — do NOT copy it. Use a strong password with at least 8 characters.
git clone https://github.com/xiaozhou26/icloud-hme.git
cd icloud-hme
# One-shot build (frontend deps → frontend test → frontend build → Go test → binary)
./build.sh
# Or step by step
npm --prefix web ci
npm --prefix web run build
go build -o icloud-hme .| Env var | Description | Default |
|---|---|---|
ICLOUD_HME_ADMIN_PASSWORD |
Admin password, required, min 8 chars | none (refuses to start) |
ICLOUD_HME_SESSION_TTL |
Session TTL | 12h (range 15m–168h) |
ICLOUD_HME_SECURE_COOKIE |
Set true when deployed behind TLS |
false |
Breaking change (v0.3+): without
ICLOUD_HME_ADMIN_PASSWORDthe server refuses to start; all API endpoints now require login (401 AUTH_REQUIRED). Admin sessions are in-memory only and are lost on restart.
Create data/accounts.json (see accounts.json.template) and start the server (default port :8081). Open http://localhost:8081 to use the management UI. Full API contract: API.md.