You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
# 前置要求: 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 .
2. 安全配置(必读)
管理界面与 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。管理员会话只存内存,进程重启即失效。
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 反爬)
常见问题
Q: 创建别名返回 401/403 错误?
A: Cookie 已过期,需要重新获取。iCloud Cookie 有效期通常为 24 小时。
Q: 读取邮件返回超时?
A: 检查网络连接,确保可以访问 imap.mail.me.com:993。
Q: 如何查看某个别名收到了哪些邮件?
A: 调用 GET /api/inbox?account_id=acc_1&alias=your_alias@icloud.com
Q: 支持同时管理多个 iCloud 账号吗?
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 .
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).
Features
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
# 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_amd64
The password above is only an example — do NOT copy it. Use a strong password with at least 8 characters.
Option 3: Build from source (Go 1.26+ and Node.js 22.12+)
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 .
Configuration
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_PASSWORD the 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.