[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-81753":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":17,"stars7d":13,"stars30d":18,"stars90d":16,"forks30d":16,"starsTrendScore":19,"compositeScore":20,"rankGlobal":10,"rankLanguage":10,"license":10,"archived":21,"fork":21,"defaultBranch":22,"hasWiki":21,"hasPages":21,"topics":23,"createdAt":10,"pushedAt":10,"updatedAt":24,"readmeContent":25,"aiSummary":26,"trendingCount":16,"starSnapshotCount":16,"syncStatus":27,"lastSyncTime":28,"discoverSource":29},81753,"HloolMail","hloolx\u002FHloolMail","hloolx","Self-hosted temporary mail and custom-domain inbox platform","https:\u002F\u002Femail.hlool.cc\u002F",null,"Go",34,6,26,1,0,3,8,9,49.34,false,"main",[],"2026-06-12 04:01:35","\u003Cp align=\"center\">\n  \u003Cimg src=\"web\u002Fpublic\u002Fbrand-logo.svg\" width=\"96\" height=\"96\" alt=\"HLOOL Mail logo\">\n\u003C\u002Fp>\n\n\u003Ch1 align=\"center\">HLOOL Mail\u003C\u002Fh1>\n\n\u003Cp align=\"center\">\n  自托管临时邮箱与私有域名收信平台，内置 SMTP catch-all、Web Console、API Key、Webhook、Share Link 和 CLI。\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"#hlool-mail-是什么--不是什么\">是什么\u003C\u002Fa> ·\n  \u003Ca href=\"#5-分钟-docker-compose\">Docker Compose\u003C\u002Fa> ·\n  \u003Ca href=\"#release-二进制\">Release\u003C\u002Fa> ·\n  \u003Ca href=\"#api-自动化\">API\u003C\u002Fa> ·\n  \u003Ca href=\"#cli\">CLI\u003C\u002Fa>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"https:\u002F\u002Flinux.do\">学 AI 上 L 站\u003C\u002Fa>\n\u003C\u002Fp>\n\n## HLOOL Mail 是什么 \u002F 不是什么\n\nHLOOL Mail 用来搭建自部署、支持多用户的匿名邮箱和私有域名收信服务。只需要把域名的 MX 指向你的 HLOOL Mail 收信主机，就可以让所有用户在你的域名下创建和使用自己的匿名邮箱；你也可以接入自有域名，为团队、脚本、测试平台、CI 或 AI 助手提供可控的收信能力。\n\n它最初是为批量注册和自动化验证设计的：网上常见匿名邮箱经常被屏蔽；用 Cloudflare 或第三方服务临时接入流程又太繁琐；直接把 MX 指向第三方站点，还会担心滥用、权限和数据不可控。\n\n现在，你可以用这个项目改变这些问题：域名由你提供，MX 由你控制，用户、额度、API Key 和访问边界也由你管理。\n\n它不是什么：\n\n- 不是传统 IMAP\u002FPOP3 邮箱客户端，也不提供 IMAP\u002FPOP3。\n- 不负责外发邮件，核心目标是稳定收信、归属隔离、自动化读取和控制台管理。\n\n## 5 分钟 Docker Compose\n\nDocker Compose 是推荐部署方式，默认启动 `app` 和 `postgres`，应用通过 PostgreSQL 持久化数据。\n\n```bash\ncp .env.compose.example .env\nnano .env\ndocker compose up -d --build\ndocker compose logs -f app\n```\n\n不要直接复用本地开发用的 `.env`，尤其是包含 `DATABASE_URL=storage\u002Fgptmail.db` 的文件；Compose 部署请从 `.env.compose.example` 复制，并使用下面的 Compose 专用变量。\n\n至少修改这些值：\n\n```env\nPUBLIC_BASE_URL=https:\u002F\u002Fmail.example.com\nMAIL_HOSTNAME=mail.example.com\nEXPECTED_MX=mail.example.com\nPOSTGRES_PASSWORD=replace-with-a-strong-postgres-password\nDEV_MODE=false\n```\n\n`SESSION_SECRET` 和 `INBOX_TOKEN_SECRET` 可以留空，让 Install Page 首次安装时自动生成并保存到 `\u002Fapp\u002Fstorage\u002F.env`；也可以提前填入两个不同的强随机值。\n\n本地测试可以保留 `SMTP_PORT=2525`。真实接收互联网邮件时，外部邮件服务器通常连接 TCP 25；如果服务器和云厂商允许，把 `.env` 里的 `SMTP_PORT` 改成 `25`，或在负载均衡\u002F端口转发层把公网 25 转到容器的 2525。\n\n使用已经发布的 GHCR 镜像：\n\n```bash\ndocker compose pull\ndocker compose up -d\n```\n\n如果本地 Docker 构建访问 Go 或 npm 官方源较慢，可以在 `.env` 里调整：\n\n```env\nGOPROXY=https:\u002F\u002Fgoproxy.cn,direct\nNPM_CONFIG_REGISTRY=https:\u002F\u002Fregistry.npmmirror.com\u002F\n```\n\n使用外部托管 PostgreSQL 时，把 `.env` 的 `HLOOLMAIL_DATABASE_URL` 改成外部连接串：\n\n```env\nHLOOLMAIL_DATABASE_URL=postgres:\u002F\u002Fuser:password@db.example.com:5432\u002Fhloolmail?sslmode=require\n```\n\n然后只启动应用服务：\n\n```bash\ndocker compose up -d app\n```\n\n## Release 二进制\n\nRelease 包会把前端静态资源内嵌进后端二进制。下载对应平台的包后，不需要单独携带 `web\u002Fdist`，程序会直接托管 Web Console。\n\n常见资产：\n\n| 文件 | 适用环境 |\n| --- | --- |\n| `hloolmail-linux-amd64.tar.gz` | 常见 x86_64\u002FAMD64 Linux 服务器 |\n| `hloolmail-linux-arm64.tar.gz` | ARM64 Linux 服务器、部分云主机、树莓派 64 位系统 |\n| `hloolmail-linux-armv7.tar.gz` | ARMv7 Linux 设备、部分 32 位树莓派系统 |\n| `hloolmail-darwin-arm64.tar.gz` | Apple Silicon macOS |\n| `hloolmail-windows-amd64.zip` | Windows x64 |\n\nLinux 二进制包示例：\n\n```bash\ntar -xzf hloolmail-linux-amd64.tar.gz\ncd hloolmail-linux-amd64\nchmod +x hloolmail\n\nexport HTTP_ADDR=:3000\nexport SMTP_ADDR=:2525\nexport DATABASE_DRIVER=postgres\nexport DATABASE_URL='postgres:\u002F\u002Fuser:password@127.0.0.1:5432\u002Fhloolmail?sslmode=disable'\nexport PUBLIC_BASE_URL=https:\u002F\u002Fmail.example.com\nexport MAIL_HOSTNAME=mail.example.com\nexport EXPECTED_MX=mail.example.com\nexport DEV_MODE=false\n\n.\u002Fhloolmail\n```\n\n`hloolmail` 同时也是 CLI。无参数或 `serve` 会启动服务；其他子命令用于 API 自动化。\n\nsystemd 示例：\n\n```ini\n[Unit]\nDescription=HLOOL Mail\nAfter=network.target\n\n[Service]\nWorkingDirectory=\u002Fopt\u002Fhloolmail\nExecStart=\u002Fopt\u002Fhloolmail\u002Fhloolmail\nRestart=always\nEnvironment=HTTP_ADDR=:3000\nEnvironment=SMTP_ADDR=:2525\nEnvironment=DATABASE_DRIVER=postgres\nEnvironment=DATABASE_URL=postgres:\u002F\u002Fuser:password@127.0.0.1:5432\u002Fhloolmail?sslmode=disable\nEnvironment=PUBLIC_BASE_URL=https:\u002F\u002Fmail.example.com\nEnvironment=MAIL_HOSTNAME=mail.example.com\nEnvironment=EXPECTED_MX=mail.example.com\nEnvironment=DEV_MODE=false\n\n[Install]\nWantedBy=multi-user.target\n```\n\n自定义前端只适合高级场景。二进制部署把 `FRONTEND_DIST` 指向一个包含 `index.html` 和 `assets\u002F` 的构建目录即可；Docker Compose 部署请使用 `HLOOLMAIL_FRONTEND_DIST`，避免误读本地开发环境变量。如果目录不存在或缺少 `index.html`，程序会回退到内置前端。\n\n```bash\ncd web\nnpm install\nnpm run build\ncd ..\n\nexport FRONTEND_DIST=web\u002Fdist\n.\u002Fhloolmail\n```\n\n只把 `web\u002Fdist` 当成纯静态前端单独部署不是推荐模式，因为前端默认调用同源 `\u002Fapi`。如果确实要分离部署，需要在前端域名上反向代理 `\u002Fapi` 到 HLOOL Mail 后端，并处理 Cookie、CORS 和 HTTPS。\n\n## Install Page\n\n首次打开 `http:\u002F\u002F服务器IP:3000` 或你的域名后，如果还没有管理员账号，会自动进入 Install Page。\n\n| 部署方式 | Install Page 行为 |\n| --- | --- |\n| Docker Compose | 生效，用于创建管理员账号，并可自动生成 `SESSION_SECRET` \u002F `INBOX_TOKEN_SECRET`。数据库、端口、站点 URL、MX 主机等运行时配置会被锁定，必须通过 `.env` \u002F Compose 修改后重启。 |\n| Docker 单容器 | 同 Compose。容器环境会自动锁定运行时配置，避免页面里写入的配置和容器环境变量打架。 |\n| Release 二进制 | 生效，可创建管理员，也可以把配置写入 `.env` 或 `CONFIG_ENV_PATH` 指定的文件。若在页面里切换数据库或数据库地址，可能需要重启程序。 |\n| 本地开发 | 生效，适合快速体验 SQLite 或本地 PostgreSQL。 |\n\n容器内默认 `HLOOLMAIL_CONFIG_LOCKED=true`。Install Page 会禁用数据库、端口、URL 等字段，后端提交安装时也会保留容器环境变量里的运行时配置。\n\n如果你确实希望 Docker 内的 Install Page 也能改数据库\u002F端口等配置，可以设置：\n\n```env\nHLOOLMAIL_CONFIG_LOCKED=false\n```\n\n生产环境不建议这样做。更稳的方式是：运行时配置放在 `.env` \u002F Compose，Install Page 只负责首次管理员和密钥初始化。\n\n## DNS\u002FMX\n\n`MAIL_HOSTNAME` \u002F `EXPECTED_MX` 应该填写你自己的 HLOOL Mail 收信主机名，不是 QQ、Google 或 Outlook 的邮箱服务器。\n\n如果你的站点是 `https:\u002F\u002Fmail.example.com`，希望接收 `user@example.com`：\n\n```env\nPUBLIC_BASE_URL=https:\u002F\u002Fmail.example.com\nMAIL_HOSTNAME=mail.example.com\nEXPECTED_MX=mail.example.com\n```\n\nDNS 示例：\n\n```dns\nmail.example.com.    A      your.server.ip\nexample.com.         MX 10  mail.example.com.\n```\n\n如果还要支持 `user@random.example.com` 这类子域名邮箱，需要 wildcard MX：\n\n```dns\n*.example.com.       MX 10  mail.example.com.\n```\n\nMX 不写端口。端口转发只发生在服务器、面板、云防火墙或负载均衡层。\n\n## Web Console\n\nWeb Console 面向人工管理，使用 `gptmail_session` Cookie\u002Fsession。它包含安装、登录、收件箱、域名管理、API Key、API Docs、Webhooks、Share Links、通知公告、用户和管理页。\n\n收件箱、通知和公告会在控制台中实时刷新，适合日常管理和排查。\n\nWeb Console 中创建 API Key 后，明文只会显示一次；后续只能看到前缀或重新 reveal。\n\n### 权限边界\n\n普通工作区页面（收件箱、Dashboard、域名、API Key、Webhooks、Share Links）只展示和操作当前登录账号可见的数据；即使账号是管理员，进入这些普通页面时也不会自动切到全局视角。\n\n跨用户的域名健康、公开分享链接、配额预警、审计和其他全局处置只放在管理后台，并走 `\u002Fapi\u002Fadmin\u002F*` 管理接口。普通路由如果处理 share、mailbox、stats、webhook 或 domain 数据，都必须继续按 owner scope 返回。\n\n## API 自动化\n\nAPI 自动化使用 `X-API-Key` 请求头。当前稳定面向脚本和 AI 的接口主要是：可用域名、生成邮箱、邮箱列表、邮件读取、邮件删除、统计。完整契约以运行中服务导出的文档为准。\n\nAPI Key 与所属账号绑定；普通 API 自动化只读取和操作该账号有权访问的数据，不提供跨用户管理能力。\n\nHLOOL Mail 是开源项目，可以部署在你自己的域名或内网环境中。示例里的 `BASE_URL` 不是固定官方 API 地址，请替换为你的 HLOOL Mail 实例地址，例如 `https:\u002F\u002Fyour-hlool-mail.example`。\n\n完整接口不要复制到 README，请直接查看运行中服务：\n\n- Markdown API Guide: `$BASE_URL\u002Fapi\u002Fdocs.md`\n- OpenAPI JSON: `$BASE_URL\u002Fapi\u002Fopenapi.json`\n- OpenAPI YAML: `$BASE_URL\u002Fapi\u002Fopenapi.yaml`\n\nAI 助手或脚本创建邮箱前，推荐先调用 `GET \u002Fapi\u002Fdomains\u002Favailable`。新客户端应优先读取 `data.public_domains` 和 `data.private_domains`，把公共域名和当前 API Key 可访问的私有域名分组展示给用户；需要处理多个邮箱或多个域名时，可以让用户多选后逐个生成。`data.domains` 只保留为旧客户端公共域名 fallback，不要因为它只含公共域名就要求用户手填私有域名。\n\n可跑的 curl 示例：\n\n```bash\nBASE_URL=\"https:\u002F\u002Fyour-hlool-mail.example\"\nAPI_KEY=key-hloolmail_xxx\n\ncurl \"$BASE_URL\u002Fapi\u002Fdomains\u002Favailable\" \\\n  -H \"X-API-Key: $API_KEY\"\n\ncurl -X POST \"$BASE_URL\u002Fapi\u002Fgenerate-email\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -H \"X-API-Key: $API_KEY\" \\\n  -d '{\"prefix\":\"demo\",\"domain\":\"example.com\"}'\n\ncurl \"$BASE_URL\u002Fapi\u002Femails\u002Fnext?email=demo@example.com\" \\\n  -H \"X-API-Key: $API_KEY\"\n\ncurl \"$BASE_URL\u002Fapi\u002Femails?email=demo@example.com&page=1&per_page=20\" \\\n  -H \"X-API-Key: $API_KEY\"\n```\n\n`GET \u002Fapi\u002Femails\u002Fnext` 会返回下一封未读邮件并自动标记已读，适合验证码轮询。需要不改变已读状态时，使用 `GET \u002Fapi\u002Femails?email=...&page=1&per_page=20`。\n\n## Webhook\n\nWebhook 用于在新邮件到达后把事件投递到你的系统、队列或自动化流程。创建、启停、测试和查看投递记录推荐在 Web Console 中完成。\n\n当前事件是 `message.received`，范围支持 `all`、`domain`、`mailbox`。投递端点必须是 `https:\u002F\u002F`，不能指向 localhost、私网地址或云元数据地址。后台 worker 异步投递，失败会按退避策略重试；设置 `WEBHOOKS_ENABLED=false` 可以禁用投递，Docker Compose 会把这个变量传入容器。\n\n已经登录 Web Console 并拿到 session Cookie 时，也可以直接调用管理接口：\n\n```bash\nBASE_URL=\"https:\u002F\u002Fyour-hlool-mail.example\"\nSESSION_COOKIE=your-gptmail-session-cookie\n\ncurl -X POST \"$BASE_URL\u002Fapi\u002Fwebhooks\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -H \"Cookie: gptmail_session=$SESSION_COOKIE\" \\\n  -d '{\"name\":\"automation\",\"url\":\"https:\u002F\u002Fexample.com\u002Fhlool\u002Fwebhook\",\"events\":[\"message.received\"],\"scope\":\"all\",\"enabled\":true}'\n```\n\nWebhook 请求会带上 `X-Hlool-Event`、`X-Hlool-Delivery`、`X-Hlool-Timestamp`、`X-Hlool-Signature`、`X-Hlool-Attempt`，正文包含事件名和经过清洗的邮件 payload。\n\n## Share Link\n\nShare Link 用于把邮箱收件箱安全分享给外部访问者。分享对象是 mailbox，公开读取使用不可猜测 token 和访问 key。\n\nAPI Key 自动化可以在生成邮箱时同步创建邮箱分享：\n\n```bash\nBASE_URL=\"https:\u002F\u002Fyour-hlool-mail.example\"\nAPI_KEY=key-hloolmail_xxx\n\ncurl -X POST \"$BASE_URL\u002Fapi\u002Fgenerate-email\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -H \"X-API-Key: $API_KEY\" \\\n  -d '{\"prefix\":\"demo\",\"domain\":\"example.com\",\"share\":true}'\n```\n\n响应中的 `data.share.url` 是不带 key 的分享页 URL；`data.share.access_url` 会带上 `?key=...`，可直接访问分享邮箱。完整 token 和 key 只在创建或重新生成时返回一次；后台只保存 hash，不能再次查看旧完整链接，需要再次复制时请重新生成分享链接。\n\n管理接口是 Web Console session-only；公开读取走匿名 token 和 key：\n\n- `GET \u002Fapi\u002Fshared\u002F:token`\n- `GET \u002Fapi\u002Fshared\u002F:token\u002Fmessages`\n- `GET \u002Fapi\u002Fshared\u002F:token\u002Fmessages\u002F:message_id`\n\n公开分享不提供 `POST \u002Fapi\u002Fshared\u002F:token\u002Faccess` 解锁接口；带 `key` 的只读 GET 路径就是唯一公开读取面。\n\n已经登录 Web Console 并拿到 session Cookie 时，可以为当前账号自己的邮箱创建邮箱分享；管理员在普通分享链接页也只管理自己的分享链接。跨用户外显链接审计与处置请到管理后台的“链接管理”分页：\n\n```bash\nBASE_URL=\"https:\u002F\u002Fyour-hlool-mail.example\"\nSESSION_COOKIE=your-gptmail-session-cookie\n\ncurl -X POST \"$BASE_URL\u002Fapi\u002Fshare-links\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -H \"Cookie: gptmail_session=$SESSION_COOKIE\" \\\n  -d '{\"resource_type\":\"mailbox\",\"mailbox_id\":45}'\n```\n\n公开读取分享邮箱邮件：\n\n```bash\nBASE_URL=\"https:\u002F\u002Fyour-hlool-mail.example\"\nTOKEN=share-token\nKEY=sharekey-hloolmail_xxx\n\ncurl \"$BASE_URL\u002Fapi\u002Fshared\u002F$TOKEN?key=$KEY\"\ncurl \"$BASE_URL\u002Fapi\u002Fshared\u002F$TOKEN\u002Fmessages?key=$KEY&page=1&per_page=20\"\ncurl \"$BASE_URL\u002Fapi\u002Fshared\u002F$TOKEN\u002Fmessages\u002Fmsg-uuid?key=$KEY\"\n```\n\n## 附件策略\n\n附件默认只保存 metadata，不保存附件原始字节。metadata 包含文件名、MIME 类型、Content-ID、Disposition、传输编码、大小、SHA-256、inline 标记和顺序号。\n\n这样做的目标是让邮件内容、Webhook payload、Share Link 页面可以知道“有附件”和附件属性，但避免把大文件或不可信二进制长期落库。附件正文不会混进 `text_content` \u002F `html_content`，HTML 内容仍会经过服务端清洗。\n\n`MAX_ATTACHMENT_BYTES` 控制单个附件的解析上限，默认跟 `MAX_MESSAGE_BYTES` 一致。超限附件会让 SMTP DATA 返回 `552 attachment exceeds size limit`。\n\n## CLI\n\nRelease 二进制内置 CLI。默认配置文件在系统用户配置目录的 `hloolmail\u002Fconfig.json`，也可以用环境变量或全局参数覆盖：`HLOOLMAIL_BASE_URL`、`HLOOLMAIL_API_KEY`、`HLOOLMAIL_PROFILE`、`HLOOLMAIL_OUTPUT`、`HLOOLMAIL_TIMEOUT`。\n\n```bash\n.\u002Fhloolmail --help\n.\u002Fhloolmail config set base_url https:\u002F\u002Fmail.example.com\n.\u002Fhloolmail config set api_key key-hloolmail_xxx\n.\u002Fhloolmail domains list\n.\u002Fhloolmail mailbox create --prefix demo --domain example.com\n.\u002Fhloolmail mail next demo@example.com --wait 120s --interval 3s --code-regex \"\\d{6}\" --quiet\n.\u002Fhloolmail mail list demo@example.com --page 1 --per-page 20\n.\u002Fhloolmail openapi json --raw > openapi.json\n```\n\n也可以不写入配置，直接用全局参数：\n\n```bash\n.\u002Fhloolmail --base-url https:\u002F\u002Fmail.example.com --api-key key-hloolmail_xxx mailbox create --prefix demo --domain example.com\n```\n\n主要命令：\n\n```text\nhloolmail                 Start server\nhloolmail serve           Start server\nhloolmail version\nhloolmail config path|get|set|use\nhloolmail health\nhloolmail openapi json|yaml|markdown|skill\nhloolmail domains list\nhloolmail mailbox create|list|delete\nhloolmail mail next|list|read|mark-read|delete|clear\nhloolmail stats\n```\n\n## OpenAPI\u002FSDK 状态\n\n`\u002Fapi\u002Fdocs.md`、`\u002Fapi\u002Fopenapi.json`、`\u002Fapi\u002Fopenapi.yaml` 都由同一份 OpenAPI registry 生成，是当前接口的来源。README 只放入口和少量示例，不复制完整 API 文档。\n\nSDK 暂缓。现阶段不承诺官方 SDK 的稳定发布节奏；需要强类型客户端时，请用 `\u002Fapi\u002Fopenapi.json` 或 `\u002Fapi\u002Fopenapi.yaml` 在自己的项目里生成。后续如果发布官方 SDK，会以 OpenAPI registry 为准，而不是手写一套新接口。\n\n## 生产安全\n\n- 生产环境设置 `DEV_MODE=false`。\n- `SESSION_SECRET` 和 `INBOX_TOKEN_SECRET` 必须是两个不同的强随机值；Docker 部署可由 Install Page 自动生成。\n- API Key 明文只在创建或 reveal 时返回一次，不要放进 URL、日志或前端代码。\n- 默认只从 `X-API-Key` 请求头读取 API Key；不建议生产长期启用 `ALLOW_API_KEY_QUERY_PARAM=true`。\n- Web Console、Webhook 目标和公开 Share Link 建议全程 HTTPS。\n- Webhook secret 只显示一次，轮换后旧 secret 立刻失效。\n- 反向代理需要保留 `Host`、`X-Forwarded-Proto`，否则 Share Link URL 和登录回调可能生成错误地址。\n- HTML 邮件详情会经过服务端清洗，并在前端 sandbox iframe 中展示。\n- 定期备份 PostgreSQL 或 SQLite 数据；升级前尤其要备份。\n\n## 升级\n\nDocker Compose：\n\n```bash\ndocker compose pull\ndocker compose up -d\ndocker compose logs -f app\n```\n\n如果使用本地源码构建镜像：\n\n```bash\ndocker compose up -d --build\n```\n\nPostgreSQL 备份示例，默认库名和账号都是 `hloolmail`：\n\n```bash\ndocker compose exec postgres pg_dump -U hloolmail hloolmail > hloolmail.sql\n```\n\nRelease 二进制升级时，先停服务、替换二进制，再启动。程序启动时会执行数据库迁移。\n\n```bash\nsystemctl stop hloolmail\ntar -xzf hloolmail-linux-amd64.tar.gz\ninstall -m 0755 hloolmail-linux-amd64\u002Fhloolmail \u002Fopt\u002Fhloolmail\u002Fhloolmail\nsystemctl start hloolmail\nsystemctl status hloolmail\n```\n\n跨大版本升级前先阅读 Release Note，并确认 `.env` \u002F systemd 环境变量仍然符合当前版本要求。\n\n## 本地开发\n\n后端和完整构建：\n\n```bash\ngo test .\u002F...\ncd web\nnpm install\nnpm run build\ncd ..\ngo run .\u002Fcmd\u002Fserver\n```\n\n前端开发模式：\n\n```bash\ncd web\nnpm install\nnpm run dev\n```\n\nVite 会代理 `\u002Fapi` 到 `http:\u002F\u002Flocalhost:3000`。\n\nInstall Page 开发者快捷键：在 Install Page 快速点击页面左上角 Logo 图标 3 次（2 秒内），系统会自动以开发模式完成安装：\n\n- 管理员账号：`dev@localhost` \u002F `devdevdev`\n- 数据库：SQLite (`storage\u002Fhlool-mail.db`)\n- `DEV_MODE=true`，`.test` 域名跳过 DNS 验证\n- 其他配置使用默认值\n\n安装完成后会自动登录到管理控制台。此功能仅用于本地开发，请勿在生产环境使用。\n\n## Troubleshooting\n\n### PostgreSQL `permission denied for schema public`\n\n如果 Install Page 报错：\n\n```text\n数据库迁移失败：当前数据库账号没有 PostgreSQL public schema 的建表\u002F改表权限\n```\n\n或原始错误包含：\n\n```text\npermission denied for schema public (SQLSTATE 42501)\n```\n\n说明数据库连接已经成功，但当前业务账号没有在 `public` schema 里创建数据表的权限。用 PostgreSQL 管理员密码执行一次授权即可。宝塔 PostgreSQL 常见 `psql` 路径是 `\u002Fwww\u002Fserver\u002Fpgsql\u002Fbin\u002Fpsql`：\n\n```bash\n\u002Fwww\u002Fserver\u002Fpgsql\u002Fbin\u002Fpsql -U postgres -d hlooltest -c 'ALTER DATABASE \"hlooltest\" OWNER TO \"hlooltest\"; ALTER SCHEMA public OWNER TO \"hlooltest\"; GRANT USAGE, CREATE ON SCHEMA public TO \"hlooltest\";'\n```\n\n把命令里的 `hlooltest` 换成你在安装页填写的数据库名和数据库账号。执行成功会看到：\n\n```text\nALTER DATABASE\nALTER SCHEMA\nGRANT\n```\n\n如果提示 `psql: command not found`，先查找实际路径：\n\n```bash\nfind \u002F -name psql -type f 2>\u002Fdev\u002Fnull | head\n```\n\n### 宝塔 \u002F 25 -> 2525\n\n宝塔面板里直接运行二进制时，程序监听 `:25` 可能会因为系统权限、面板防火墙或端口占用导致无法收信。推荐让程序继续监听 `:2525`：\n\n```bash\nexport SMTP_ADDR=:2525\n```\n\n然后在宝塔面板的防火墙 \u002F 端口转发里，把公网 TCP `25` 转发到本机 `2525`。DNS 的 MX 仍然指向你的收信主机名，例如 `hlool.00a.chat`，不要把 MX 写成端口。\n\n### API 401 或收不到邮件\n\n- API 自动化必须带 `X-API-Key`，不要用 Web Console Cookie 代替。\n- Webhook 和 Share Link 管理必须是 Web Console session；API Key 只能在 `generate-email` 时创建邮箱分享，不能管理分享链接。\n- 私有域名要先在 Web Console 添加并完成 MX 验证，再用 API 生成该域名邮箱。\n- 如果目标网站拦截临时邮箱域名，换公共域名或使用自己的私有域名。\n- 公网收不到邮件时，先检查 DNS MX、云厂商入站 TCP 25、服务器防火墙、Compose `SMTP_PORT` 或 25 -> 2525 转发。\n","HLOOL Mail 是一个自托管的临时邮箱和私有域名收信平台。项目使用 Go 语言编写，支持通过 Docker Compose 快速部署，并提供内置的 SMTP catch-all、Web 控制台、API Key、Webhook、分享链接以及命令行工具等功能。它特别适用于需要为团队成员、自动化脚本或测试环境提供可控制的邮件接收服务的场景，如批量注册验证、CI\u002FCD 流程中的邮件处理等。HLOOL Mail 不支持传统的 IMAP\u002FPOP3 协议，也不负责发送邮件，其主要目标是确保稳定的邮件接收能力与良好的管理界面。",2,"2026-06-11 04:06:14","CREATED_QUERY"]