diff --git a/CHANGELOG.md b/CHANGELOG.md index 112dcbff..4257e3c8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,6 +15,7 @@ - feat: |Skill| 新增仓库内置只读 skill `cf-temp-mail-agent-mail`（`skills/cf-temp-mail-agent-mail/`），让 OpenClaw / Codex / Cursor 等 AI agent 凭用户提供的 Address JWT + API 地址读取邮箱、轮询验证码，绕开创建邮箱时的 Turnstile 人机验证；可通过 `npx degit dreamhunter2333/cloudflare_temp_email/skills/cf-temp-mail-agent-mail` 安装 - docs: |文档| 新增"AI Agent 使用邮箱"文档（`guide/feature/agent-email`），说明 `parsed_mail` API 用法，并在 parsed API 不可用时给出对齐前端的 `mail-parser-wasm` + `postal-mime` 本地解析回退方案 - docs: |文档| 在 `quick-start` / `worker-vars` / `email-routing` 三个入口文档（中英文）显式补充"域名是部署前提条件"提示，强调需先在 Cloudflare 启用 Email Routing 并下发邮件 DNS 记录、Worker 部署后再绑定 Catch-all，子域名需单独启用，避免用户在没有可用域名时直接开始部署却收不到邮件（issue #1004） +- docs: |部署排障| 优化近期 issue 暴露的 UI 部署与升级排障文档：补充 `nodejs_compat`、D1 绑定名必须为 `DB`、`/open_api/settings` 校验、后端 API 地址填写、Cloudflare 安全挑战导致 `Network Error`、D1 容量上限与 Cron Trigger 自动清理、GitHub OAuth 公开邮箱、admin 管理口令与用户账号区别、随机二级域名 API 需传 `enableRandomSubdomain` 等说明；同时将帮助/FAQ 菜单移动到核心配置之后，提升可见性 ### Bug Fixes diff --git a/CHANGELOG_EN.md b/CHANGELOG_EN.md index 8c6d4abd..dde8f255 100644 --- a/CHANGELOG_EN.md +++ b/CHANGELOG_EN.md @@ -15,6 +15,7 @@ - feat: |Skill| Bundle a read-only skill `cf-temp-mail-agent-mail` (`skills/cf-temp-mail-agent-mail/`) so AI agents like OpenClaw / Codex / Cursor can consume a mailbox with a user-supplied Address JWT + API base URL — list mails, poll verification codes, etc. — sidestepping the Turnstile challenge required to create a mailbox. Install via `npx degit dreamhunter2333/cloudflare_temp_email/skills/cf-temp-mail-agent-mail` - docs: |Docs| Add "AI Agent Mailbox Usage" doc (`guide/feature/agent-email`) covering the `parsed_mail` API and a local-parse fallback using `mail-parser-wasm` + `postal-mime` (mirrors the frontend) when parsed endpoints are unavailable - docs: |Docs| Make "a domain is a hard prerequisite" explicit at the top of `quick-start`, `worker-vars`, and `email-routing` (zh + en), spelling out that Cloudflare Email Routing must be enabled with email DNS records provisioned before deployment, the Catch-all rule must be bound after the Worker is deployed, and subdomains do not inherit the parent domain's Email Routing — so users no longer start deploying without a usable domain and end up unable to receive mail (issue #1004) +- docs: |Deployment troubleshooting| Improve docs for recent UI-deployment and upgrade issues: document `nodejs_compat`, the required uppercase `DB` D1 binding, `/open_api/settings` verification, backend API URL entry, Cloudflare security challenges causing `Network Error`, D1 size limits and Cron Trigger cleanup, GitHub OAuth public email requirements, the difference between admin passwords and user accounts, and the `enableRandomSubdomain` API flag; move the Help/FAQ menu directly after Core Configuration so it is easier to find ### Bug Fixes diff --git a/vitepress-docs/docs/.vitepress/en.ts b/vitepress-docs/docs/.vitepress/en.ts index cd2e25b8..b08f0159 100644 --- a/vitepress-docs/docs/.vitepress/en.ts +++ b/vitepress-docs/docs/.vitepress/en.ts @@ -143,6 +143,13 @@ function sidebarGuide(): DefaultTheme.SidebarItem[] { { text: 'Configure Email Sending', link: 'config-send-mail' }, ] }, + { + text: 'Help', + collapsed: false, + items: [ + { text: 'FAQ', link: 'common-issues' }, + ] + }, { text: 'Notifications & Integrations', collapsed: false, @@ -184,13 +191,6 @@ function sidebarGuide(): DefaultTheme.SidebarItem[] { { text: 'Admin User Management', link: 'feature/admin-user-management' }, ] }, - { - text: 'Help', - collapsed: false, - items: [ - { text: 'FAQ', link: 'common-issues' }, - ] - }, { text: 'Reference', base: "/en/", link: 'reference' } ] } diff --git a/vitepress-docs/docs/.vitepress/zh.ts b/vitepress-docs/docs/.vitepress/zh.ts index 12998db7..9ff23e79 100644 --- a/vitepress-docs/docs/.vitepress/zh.ts +++ b/vitepress-docs/docs/.vitepress/zh.ts @@ -143,6 +143,13 @@ function sidebarGuide(): DefaultTheme.SidebarItem[] { { text: '配置发送邮件', link: 'config-send-mail' }, ] }, + { + text: '帮助', + collapsed: false, + items: [ + { text: '常见问题 (FAQ)', link: 'common-issues' }, + ] + }, { text: '通知与集成', collapsed: false, @@ -184,13 +191,6 @@ function sidebarGuide(): DefaultTheme.SidebarItem[] { { text: 'Admin 用户管理', link: 'feature/admin-user-management' }, ] }, - { - text: '帮助', - collapsed: false, - items: [ - { text: '常见问题 (FAQ)', link: 'common-issues' }, - ] - }, { text: '参考', base: "/zh/", link: 'reference' } ] } diff --git a/vitepress-docs/docs/en/guide/common-issues.md b/vitepress-docs/docs/en/guide/common-issues.md index 32ed491a..b34c2310 100644 --- a/vitepress-docs/docs/en/guide/common-issues.md +++ b/vitepress-docs/docs/en/guide/common-issues.md @@ -19,16 +19,19 @@ | `No such module "node:stream". imported from "worker.js"` | [Reference](/en/guide/ui/worker) | | `Subdomain cannot send emails` | [Reference](https://github.com/dreamhunter2333/cloudflare_temp_email/issues/515) | | `Failed to send verify code: No balance` | Set unlimited emails in admin console or increase quota on the sending permission page | -| `Github OAuth unable to get email 400 Failed to get user email` | GitHub user needs to set email to public | +| `GitHub OAuth unable to get email` / `[400]: Failed to get user email from OAuth2 provider` | The GitHub template reads the `email` field from `https://api.github.com/user`. If the GitHub account hides its public email, this field is `null`. Make the email public in the GitHub profile, or use an OAuth2 provider/API that returns an email field | | `Cannot read properties of undefined (reading 'map')` during page initialization | First check whether `/open_api/settings` is returning valid data. In a direct Worker deployment, this usually means Worker variables were not configured correctly, so verify JSON-format variables such as `DOMAINS` and `ADMIN_PASSWORDS`. If this happens in a Pages deployment because requests are going to the wrong backend address, continue with the Pages troubleshooting section below | +| Worker backend opens as `OK`, but every frontend request shows `Network Error` | First open the frontend in an incognito window to rule out a cached old frontend bundle. Then make sure Cloudflare security modes such as Under Attack, Bot Fight, or Managed Challenge are not applied to the API domain; those browser challenges block XHR/API requests and surface as `Network Error` | +| Mail suddenly stops arriving, deleting a few mails makes it work again, and Worker logs show `D1_ERROR: Exceeded maximum DB size` | The D1 database has reached its per-database size limit and can no longer write `raw_mails`. Delete old mails, enable auto cleanup in the admin console, and make sure the Worker has a `Settings -> Trigger Events -> Cron Triggers` schedule; otherwise admin cleanup settings will not run automatically | ## Pages Related | Issue | Solution | | --------------- | --------------------------------------------------------- | -| `network error` | Use incognito mode or clear browser cache and DNS cache | +| `Network Error` | First use incognito mode or clear browser cache and DNS cache; then inspect the failed request URL, status code, and response body in the browser DevTools Network panel | | Pages deployment shows the `map` error, or API requests such as `/admin/users` / `/admin/new_address` return `405 Method Not Allowed` | This is usually caused by an incorrect frontend backend address. Check `VITE_API_BASE`, the URL entered when generating the zip in the UI guide, or `FRONTEND_ENV`: for separate frontend/backend deployment talking directly to Worker, it should be the backend Worker API root URL, start with `https://`, and have no trailing `/`; if you use `PAGE_TOML` to proxy backend requests through Page Functions, `VITE_API_BASE` can be left empty to use same-origin requests. See [Pages Frontend Deployment](/en/guide/ui/pages) | | Refreshing page or directly visiting `/admin`, `/user` returns 404 | This project is a Single-Page Application (SPA). When deploying Pages via UI, set "Not Found handling" to `Single-page application (SPA)` in the advanced options. See [Pages Frontend Deployment](/en/guide/ui/pages) | +| Admin login shows `Network Error` and the request is `/open_api/admin_login` | Check that the backend API root URL used when generating the frontend zip is the Worker domain, not the Pages domain; it must not include `/admin`, `/api`, or a trailing `/`. Also confirm the response is not a Cloudflare security challenge page | ## Email Sending Related diff --git a/vitepress-docs/docs/en/guide/feature/admin.md b/vitepress-docs/docs/en/guide/feature/admin.md index f6678050..c0a82c28 100644 --- a/vitepress-docs/docs/en/guide/feature/admin.md +++ b/vitepress-docs/docs/en/guide/feature/admin.md @@ -8,6 +8,19 @@ After deploying the frontend application, click the upper-left logo 5 times or v You need to configure `ADMIN_PASSWORDS` in the backend or ensure the current user role is `ADMIN_USER_ROLE`, otherwise access to the console will be denied. +## Admin Passwords vs User Accounts + +`ADMIN_PASSWORDS` is the management password for the Admin console. It is not a site user account +and does not correspond to any mailbox address. Logging in with an admin password grants access to +the console, but that login itself cannot receive mail. + +Site user accounts are stored in the `users` table and use the user login flow. Whether a user can +receive mail depends on whether they created or bound a mailbox address. Creating a normal user +whose email looks like `admin@example.com` does not automatically grant admin permissions. + +If you want a user account to access the Admin console, configure `ADMIN_USER_ROLE` and assign the +same role to that user in user management. + ![admin](/feature/admin.png) ## Account List Sorting diff --git a/vitepress-docs/docs/en/guide/feature/subdomain.md b/vitepress-docs/docs/en/guide/feature/subdomain.md index 0056fa51..a15b6e90 100644 --- a/vitepress-docs/docs/en/guide/feature/subdomain.md +++ b/vitepress-docs/docs/en/guide/feature/subdomain.md @@ -30,9 +30,29 @@ RANDOM_SUBDOMAIN_LENGTH = 8 - `RANDOM_SUBDOMAIN_DOMAINS`: base domains that allow optional random second-level subdomains - `RANDOM_SUBDOMAIN_LENGTH`: random string length, range `1-63`, default `8` +The create-address APIs only generate a random subdomain when the request explicitly passes +`enableRandomSubdomain: true`. The frontend sends this field when the "enable random subdomain" +option is checked. If you call `/api/new_address` or `/admin/new_address` yourself, include it in +the request body: + +```json +{ + "name": "test", + "domain": "abc.com", + "enableRandomSubdomain": true +} +``` + +`domain` must be the base domain configured in `RANDOM_SUBDOMAIN_DOMAINS`, such as `abc.com`. +If you want to create an address under a specific subdomain such as `team.abc.com`, do not pass +`enableRandomSubdomain: true`; use the direct-subdomain flow below instead. + > [!NOTE] > This feature only appends a random second-level subdomain when the mailbox is created. > +> There is currently no backend switch that globally forces random subdomains; API calls that do +> not pass `enableRandomSubdomain: true` will not randomize automatically. +> > It does not automatically create Cloudflare-side subdomain mail routes or DNS records for you, > so make sure the base-domain/subdomain routing is already available first. diff --git a/vitepress-docs/docs/en/guide/feature/user-oauth2.md b/vitepress-docs/docs/en/guide/feature/user-oauth2.md index 85bd2cc5..c6ad6961 100644 --- a/vitepress-docs/docs/en/guide/feature/user-oauth2.md +++ b/vitepress-docs/docs/en/guide/feature/user-oauth2.md @@ -10,6 +10,12 @@ ### GitHub - Please first create an OAuth App, then obtain the `Client ID` and `Client Secret` +- The default GitHub template uses `https://api.github.com/user` as the user info endpoint and reads + the `email` field from the returned JSON. If the GitHub account hides its public email, this field + is `null`, and login returns `[400]: Failed to get user email from OAuth2 provider`. +- Fix it by making the email public in the GitHub profile, or by using a provider/API that returns + an email field. If the returned value is not a standard email, use the "Email Format + Transformation" section below. Reference: [Creating an OAuth App](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app) @@ -41,6 +47,17 @@ Reference: [Creating an OAuth App](https://docs.github.com/en/apps/oauth-apps/bu | Redirect URL | OAuth2 callback URL | | Scope | OAuth2 permission scope | +`Redirect URL` must exactly match the callback URL configured in the third-party OAuth App. The +default frontend callback path is: + +```text +https://your-frontend-domain/user/oauth2/callback +``` + +Even if your site uses locale-prefixed routes, it is still recommended to configure the OAuth +provider with the callback URL without a locale prefix to avoid callback mismatches between +languages. + ### Email Format Transformation When OAuth2 returns a non-standard email format (e.g., returns a user ID), you can enable the Email Format feature. diff --git a/vitepress-docs/docs/en/guide/quick-start.md b/vitepress-docs/docs/en/guide/quick-start.md index d8b85db7..956a3cc3 100644 --- a/vitepress-docs/docs/en/guide/quick-start.md +++ b/vitepress-docs/docs/en/guide/quick-start.md @@ -30,6 +30,13 @@ Then review all changes from your current version onwards. Note that `Breaking C Then refer to the documentation below to use `CLI` or `UI` to redeploy the `worker` and `pages` over the previous deployment. +Upgrading does not mean editing the old code already running in the Cloudflare console. It means redeploying the new version artifacts over the existing Worker and Pages deployment: + +- If you use UI deployment, download the latest release `worker.js` and `frontend.zip`, then upload them again using the same deployment method. +- If you use GitHub Actions, sync your fork first and rerun the corresponding workflow. +- If the changelog lists database changes, run the upgrade in `Admin -> Quick Setup -> Database`, or execute the corresponding SQL according to the D1 guide. +- If the frontend still shows an old error after upgrading, test in an incognito window or clear browser cache so it stops loading the old frontend assets. + ### CLI Deployment - [Update D1 via Command Line](/en/guide/cli/d1) diff --git a/vitepress-docs/docs/en/guide/ui/pages.md b/vitepress-docs/docs/en/guide/ui/pages.md index 4779f1a3..83c7856e 100644 --- a/vitepress-docs/docs/en/guide/ui/pages.md +++ b/vitepress-docs/docs/en/guide/ui/pages.md @@ -115,9 +115,12 @@ const generate = async () => { - The worker domain here is the backend API domain. For example, if I deployed at `https://temp-email-api.awsl.uk`, then fill in `https://temp-email-api.awsl.uk` - If your domain is `https://temp-email-api.xxx.workers.dev`, then fill in `https://temp-email-api.xxx.workers.dev` - Do not enter your frontend `Pages` domain, and do not include paths like `/admin` or `/api`. Otherwise frontend requests will hit the wrong address and you may see `Cannot read properties of undefined (reading 'map')` or `405 Method Not Allowed` + - Before filling it in, open `https://your-worker-domain/open_api/settings` in the browser and confirm it returns JSON. If it returns HTML, 404, 405, or a Cloudflare challenge page, fix the Worker binding, variables, or security policy first > [!warning] Note > The `worker.dev` domain is not accessible in China, please use a custom domain. + > + > Do not enable security policies such as Under Attack, Bot Fight, or Managed Challenge on the backend API domain. Frontend XHR requests cannot complete those browser challenges, and the common symptom is `Network Error`.
@@ -133,6 +136,8 @@ const generate = async () => { > Modify the index-xxx.js file in the archive, where xx is a random string > > Search for `https://temp-email-api.xxx.xxx` and replace it with your worker's backend API root URL, then deploy the new zip file. If you replace it with the frontend Pages domain, common symptoms are the `map` error or `405` responses from API requests + > + > If you entered the wrong address the first time and still see errors after redeploying, test in an incognito window or clear browser cache so the browser stops using the old frontend assets. 4. Select `Pages`, click `Create Pages`, modify the name, upload the downloaded zip package diff --git a/vitepress-docs/docs/en/guide/ui/worker.md b/vitepress-docs/docs/en/guide/ui/worker.md index 6ea85942..6930d3a2 100644 --- a/vitepress-docs/docs/en/guide/ui/worker.md +++ b/vitepress-docs/docs/en/guide/ui/worker.md @@ -16,6 +16,9 @@ ![worker-runtime](/ui_install/worker-runtime.png) + > [!IMPORTANT] + > Add `nodejs_compat` before deploying `worker.js`. Without this compatibility flag, common errors include `No such module "path"` and `No such module "node:stream"`, and the frontend may only show `Network Error`. + 4. Download [worker.js](https://github.com/dreamhunter2333/cloudflare_temp_email/releases/latest/download/worker.js) 5. Go back to `Overview`, find the worker you just created, click `Edit Code`, delete the original file, upload `worker.js`, and click `Deploy` @@ -23,7 +26,7 @@ > [!NOTE] > To upload, first click Explorer in the left menu, > then right-click in the file list window and find `Upload` in the context menu, - > please refer to the screenshots below + > please refer to the screenshots below. Do not manually create a path such as `\worker.js` in the editor. If saving fails with `No file system handle registered (\worker.js)`, go back to the Explorer file list, right-click upload the root `worker.js`, and then click `Deploy`. > > Reference: [issues156](https://github.com/dreamhunter2333/cloudflare_temp_email/issues/156#issuecomment-2079453822) @@ -56,7 +59,7 @@ 7. Click `Settings` -> `Bindings`, click `Add Binding`, enter the name as shown, select the D1 database you just created, and click `Add Binding` > [!NOTE] Important - > Note that the binding name for `D1 Database` here must be `DB` + > Note that the binding name for `D1 Database` here must be `DB` in uppercase. If the binding is named `db`, `DATABASE`, or anything else, `/open_api/settings` and `/admin/*` will fail; common frontend symptoms are the `map` initialization error or `Network Error`. ![worker-bindings](/ui_install/worker-bindings.png) @@ -70,6 +73,8 @@ > Open the `worker` `url`, if it displays `OK`, the deployment is successful > > Open `/health_check`, if it displays `OK`, the deployment is successful + > + > Open `/open_api/settings`; if it returns JSON, the public settings endpoint required by the frontend is working. Check this before deploying Pages. ![worker3](/ui_install/worker-3.png) @@ -105,3 +110,5 @@ > [!NOTE] > Select `cron` expression, enter `0 0 * * *` (this expression means run daily at midnight), click `Add` to add. Please adjust this expression according to your needs. + > + > Enabling auto cleanup in the admin page is not enough by itself. You must add a Cron Trigger so the Worker's `scheduled` event actually runs. When D1 reaches its size limit, writes fail with `D1_ERROR: Exceeded maximum DB size`, new mails cannot be stored, and the symptom is "mail suddenly stops arriving; deleting a few mails makes it work again". diff --git a/vitepress-docs/docs/zh/guide/common-issues.md b/vitepress-docs/docs/zh/guide/common-issues.md index ea7a36e5..216643c8 100644 --- a/vitepress-docs/docs/zh/guide/common-issues.md +++ b/vitepress-docs/docs/zh/guide/common-issues.md @@ -19,16 +19,19 @@ | `No such module "node:stream". imported from "worker.js"` | [参考](/zh/guide/ui/worker) | | `二级域名无法发送邮件` | [参考](https://github.com/dreamhunter2333/cloudflare_temp_email/issues/515) | | `Failed to send verify code: No balance` | admin 后台设置无限制邮件或者发件权限页面增加额度 | -| `Github OAuth无法获取到邮箱 400 Failed to get user email` | 需要 github 用户设置公开邮箱 | +| `GitHub OAuth 无法获取到邮箱` / `[400]: 从 Oauth2 提供商获取用户邮箱失败` | GitHub 模板会从 `https://api.github.com/user` 的 `email` 字段读取邮箱。GitHub 账号如果隐藏公开邮箱，该字段会是 `null`，需要在 GitHub 个人资料中设置公开邮箱，或改用会返回邮箱字段的 OAuth2 提供商/接口 | | 页面初始化时报 `Cannot read properties of undefined (reading 'map')` | 先看 `/open_api/settings` 返回是否正常。如果是 Worker 直连部署，通常是 worker 变量没有设置成功，请检查 `DOMAINS`、`ADMIN_PASSWORDS` 等 JSON 格式变量是否正确配置；如果是 Pages 前端部署并且请求打到了错误地址，则继续看下方 Pages 相关排障 | +| 后端 Worker 页面打开是 `OK`，但前端所有请求都是 `Network Error` | 先在浏览器无痕模式打开前端，排除旧前端包缓存。再确认 Cloudflare 没有对 API 域名开启 Under Attack、Bot Fight、Managed Challenge 等需要浏览器挑战的安全策略；这些挑战会拦截 XHR/API 请求并表现为 `Network Error` | +| 邮件突然收不到，删除几封邮件后恢复，Worker 日志出现 `D1_ERROR: Exceeded maximum DB size` | D1 单数据库达到容量上限后无法继续写入 `raw_mails`。请清理旧邮件、开启 admin 后台自动清理，并确认 Worker 的 `Settings -> Trigger Events -> Cron Triggers` 已添加定时触发器，否则后台清理配置不会自动执行 | ## Pages 相关 | 问题 | 解决方案 | | --------------- | ---------------------------------------- | -| `network error` | 使用无痕模式或者清空浏览器缓存，DNS 缓存 | +| `Network Error` | 先使用无痕模式或者清空浏览器缓存、DNS 缓存；再打开浏览器 DevTools 的 Network 面板确认失败请求的实际 URL、状态码和响应内容 | | Pages 部署后页面报 `map` 错误，或 `/admin/users`、`/admin/new_address` 等接口返回 `405 Method Not Allowed` | 通常是前端后端地址配置错误。请检查 `VITE_API_BASE`、UI 页面生成 zip 时填写的地址或 `FRONTEND_ENV`：前后端分离直连 Worker 时，应填写后端 Worker API 根地址，并且以 `https://` 开头、末尾不要带 `/`；如果使用 `PAGE_TOML` 通过 Page Functions 反代后端，则可保持 `VITE_API_BASE` 为空走同域请求。详见 [Pages 前端部署](/zh/guide/ui/pages) | | 刷新页面或直接访问 `/admin`、`/user` 返回 404 | 本项目是单页应用（SPA），通过 UI 部署 Pages 时需要在高级选项中将「未找到处理」设置为 `Single-page application (SPA)`。详见 [Pages 前端部署](/zh/guide/ui/pages) | +| 管理员登录后报 `Network Error`，请求为 `/open_api/admin_login` | 检查前端生成 zip 时填写的后端 API 根地址是否就是 Worker 域名，不要填 Pages 域名、不要带 `/admin` 或 `/api`、不要带结尾 `/`。同时确认请求响应不是 Cloudflare 安全挑战页 | ## 发送邮件相关 diff --git a/vitepress-docs/docs/zh/guide/feature/admin.md b/vitepress-docs/docs/zh/guide/feature/admin.md index 9375cb97..78285e4c 100644 --- a/vitepress-docs/docs/zh/guide/feature/admin.md +++ b/vitepress-docs/docs/zh/guide/feature/admin.md @@ -6,7 +6,15 @@ 部署前端应用之后，点击 左上角 logo 5 次 或者访问 `/admin` 路径即可进入管理控制台。 -需要在后端配置 `ADMIN_PASSWORDS` 或者当前用户角色为 `ADMIN_USER_ROLE`, 则不允许访问控制台。 +需要在后端配置 `ADMIN_PASSWORDS` 或者当前用户角色为 `ADMIN_USER_ROLE`，否则不允许访问控制台。 + +## 管理口令和用户账号的区别 + +`ADMIN_PASSWORDS` 是 Admin 控制台的管理口令，不是站点用户账号，也不对应某个邮箱地址。使用管理口令登录后可以进入后台，但它本身不能收信。 + +站点用户账号存储在 `users` 表中，需要通过用户登录体系进入；用户是否能收信取决于是否创建或绑定了邮箱地址。即使你创建了一个邮箱为 `admin@example.com` 或用户名看起来像 `admin` 的普通用户，它也不会自动获得后台权限。 + +如果希望某个用户也能进入 Admin 控制台，请配置 `ADMIN_USER_ROLE`，并在用户管理中给该用户设置相同的角色。 ![admin](/feature/admin.png) diff --git a/vitepress-docs/docs/zh/guide/feature/subdomain.md b/vitepress-docs/docs/zh/guide/feature/subdomain.md index 44ab7b87..a962e69b 100644 --- a/vitepress-docs/docs/zh/guide/feature/subdomain.md +++ b/vitepress-docs/docs/zh/guide/feature/subdomain.md @@ -29,9 +29,23 @@ RANDOM_SUBDOMAIN_LENGTH = 8 - `RANDOM_SUBDOMAIN_DOMAINS`：允许启用随机二级域名的基础域名列表 - `RANDOM_SUBDOMAIN_LENGTH`：随机串长度，范围 `1-63`，默认 `8` +创建地址 API 需要显式传入 `enableRandomSubdomain: true` 才会生成随机二级域名。前端勾选“启用随机二级域名”时会自动传这个字段；如果你自己调用 `/api/new_address` 或 `/admin/new_address`，也需要在请求体中传入： + +```json +{ + "name": "test", + "domain": "abc.com", + "enableRandomSubdomain": true +} +``` + +`domain` 必须传 `RANDOM_SUBDOMAIN_DOMAINS` 中配置的基础域名，例如 `abc.com`。如果要创建 `team.abc.com` 这种指定子域名地址，请不要传 `enableRandomSubdomain: true`，而是使用下方“直接指定子域名”的流程。 + > [!NOTE] > 这个功能只是在“创建地址”时自动补一个随机二级域名。 > +> 当前没有“全局强制随机二级域名”的后端开关；未传 `enableRandomSubdomain: true` 的 API 调用不会自动随机。 +> > 它不会自动帮你创建 Cloudflare 侧的子域名收件路由或 DNS 配置，请先确保基础域名/子域名路由本身已经可用。 ## 允许 API 直接指定子域名 diff --git a/vitepress-docs/docs/zh/guide/feature/user-oauth2.md b/vitepress-docs/docs/zh/guide/feature/user-oauth2.md index a471499d..13e1dd21 100644 --- a/vitepress-docs/docs/zh/guide/feature/user-oauth2.md +++ b/vitepress-docs/docs/zh/guide/feature/user-oauth2.md @@ -10,6 +10,8 @@ ### GitHub - 请先创建一个 OAuth App，然后获取 `Client ID` 和 `Client Secret` +- 默认 GitHub 模板使用 `https://api.github.com/user` 作为用户信息接口，并读取返回 JSON 的 `email` 字段。GitHub 账号如果隐藏公开邮箱，该字段会是 `null`，登录会返回 `[400]: 从 Oauth2 提供商获取用户邮箱失败`。 +- 解决方式是在 GitHub 个人资料中设置公开邮箱，或改成能返回邮箱的接口/提供商；如果返回值不是标准邮箱，可以使用下方“邮箱格式转换”。 参考 [Creating an OAuth App](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app) @@ -41,6 +43,14 @@ | Redirect URL | OAuth2 回调地址 | | Scope | OAuth2 权限范围 | +`Redirect URL` 必须和第三方平台 OAuth App 中配置的回调地址完全一致。前端默认回调路径为： + +```text +https://你的前端域名/user/oauth2/callback +``` + +如果你的站点使用语言前缀路由，也仍然建议在 OAuth 平台中配置无语言前缀的回调地址，避免不同语言路径导致回调不一致。 + ### 邮箱格式转换 当 OAuth2 返回的不是标准邮箱格式时（如返回用户 ID），可以启用邮箱格式转换功能。 diff --git a/vitepress-docs/docs/zh/guide/quick-start.md b/vitepress-docs/docs/zh/guide/quick-start.md index 0cc840c0..2ec13950 100644 --- a/vitepress-docs/docs/zh/guide/quick-start.md +++ b/vitepress-docs/docs/zh/guide/quick-start.md @@ -30,11 +30,18 @@ 然后参考下面的文档使用 `CLI` 或者 `UI` 覆盖部署之前的 `worker` 和 `pages` 即可 +升级不是修改 Cloudflare 控制台里已经运行的旧代码，而是用新版本产物重新覆盖部署： + +- 如果使用 UI 部署，请重新下载最新 release 的 `worker.js` 和 `frontend.zip`，按原部署方式覆盖上传。 +- 如果使用 GitHub Actions 部署，请先同步 fork 仓库，再重新运行对应 workflow。 +- 如果 changelog 标注了数据库变更，请在 admin 后台的 `快速设置 -> 数据库` 执行升级，或按 D1 文档执行对应 SQL。 +- 升级后如果前端仍显示旧错误，请用无痕窗口测试或清理浏览器缓存，避免继续加载旧前端资源。 + ### CLI 部署 - [命令行更新 d1](/zh/guide/cli/d1) - [命令行部署 worker](/zh/guide/cli/worker) -- [命令行部署 pages](/zh/guide/cli/worker) +- [命令行部署 pages](/zh/guide/cli/pages) ### UI 部署 diff --git a/vitepress-docs/docs/zh/guide/ui/pages.md b/vitepress-docs/docs/zh/guide/ui/pages.md index e808d50e..ee353797 100644 --- a/vitepress-docs/docs/zh/guide/ui/pages.md +++ b/vitepress-docs/docs/zh/guide/ui/pages.md @@ -115,9 +115,12 @@ const generate = async () => { - 此处 worker 域名为后端 api 的域名，比如我部署在 `https://temp-email-api.awsl.uk`，则填写 `https://temp-email-api.awsl.uk` - 如果你的域名是 `https://temp-email-api.xxx.workers.dev`，则填写 `https://temp-email-api.xxx.workers.dev` - 不要填写前端 `Pages` 自己的域名，也不要带 `/admin`、`/api` 等路径，否则前端请求会打到错误地址，可能出现 `Cannot read properties of undefined (reading 'map')` 或 `405 Method Not Allowed` + - 填写前请先在浏览器打开 `https://你的worker域名/open_api/settings`，确认返回 JSON；如果返回 HTML、404、405 或 Cloudflare 挑战页，请先修复 Worker 绑定、变量或安全策略 > [!warning] 注意 > `worker.dev` 域名在中国无法访问，请自定义域名 + > + > 不要给后端 API 域名开启 Under Attack、Bot Fight、Managed Challenge 等会返回浏览器挑战页的安全策略。前端 XHR 请求无法完成这些挑战，常见表现是 `Network Error`。
@@ -133,6 +136,8 @@ const generate = async () => { > 修改压缩包里面的 index-xxx.js 文件 ，xx 是随机的字符串 > > 搜索 `https://temp-email-api.xxx.xxx` ，替换成你 worker 的后端 API 根地址，然后部署新的 zip 文件。如果填成前端 Pages 域名，常见现象就是页面报 `map` 错误或接口返回 `405` + > + > 如果第一次填错后重新部署仍然报错，请用无痕窗口测试或清理浏览器缓存，避免浏览器继续使用旧的前端资源。 4. 选择 `Pages`，点击 `Create Pages`, 修改名称，上传下载的 zip 包 diff --git a/vitepress-docs/docs/zh/guide/ui/worker.md b/vitepress-docs/docs/zh/guide/ui/worker.md index 085fe239..54e3e2c3 100644 --- a/vitepress-docs/docs/zh/guide/ui/worker.md +++ b/vitepress-docs/docs/zh/guide/ui/worker.md @@ -16,6 +16,9 @@ ![worker-runtime](/ui_install/worker-runtime.png) + > [!IMPORTANT] + > `nodejs_compat` 必须添加成功后再部署 `worker.js`。如果缺少该兼容标记，常见错误是 `No such module "path"`、`No such module "node:stream"`，前端也可能只显示 `Network Error`。 + 4. 下载 [worker.js](https://github.com/dreamhunter2333/cloudflare_temp_email/releases/latest/download/worker.js) 5. 回到 `Overview`，找到刚刚创建的 worker，点击 `Edit Code`, 删除原来的文件，上传 `worker.js`, 点击 `Deploy` @@ -23,7 +26,7 @@ > [!NOTE] > 上传需要先点击左侧菜单的 Explorer, > 在文件列表的窗口里点击鼠标右键，在右键菜单里找到 `Upload`, - > 请参考下面的截图 + > 请参考下面的截图。不要在编辑器中手动创建 `\worker.js` 这类带反斜杠的路径；如果保存时报 `No file system handle registered (\worker.js)`，请回到 Explorer 文件列表右键上传根目录的 `worker.js`，然后再点击 `Deploy`。 > > 参考: [issues156](https://github.com/dreamhunter2333/cloudflare_temp_email/issues/156#issuecomment-2079453822) @@ -56,7 +59,7 @@ 7. 点击 `Settings` -> `Bindings`, 点击 `Add Binding`, 名称如图，选择刚刚创建的 D1 数据库，点击 `Add Binding` > [!NOTE] 重要 - > 注意此处 `D1 Database` 的绑定名称必须为 `DB` + > 注意此处 `D1 Database` 的绑定名称必须为 `DB`，必须是大写。绑定名写成 `db`、`DATABASE` 或其他值时，`/open_api/settings`、`/admin/*` 等接口会异常，前端常见表现是页面初始化报 `map` 错误或 `Network Error`。 ![worker-bindings](/ui_install/worker-bindings.png) @@ -64,12 +67,14 @@ ![worker-d1-2](/ui_install/worker-d1-2.png) -8. 点击 `Settings` -> `Trggers`, 这里可以添加自己的域名，你也可以使用自动生成的 `*.workers.dev` 的域名。记录下这个域名，后面部署前端会用到。 +8. 点击 `Settings` -> `Triggers`, 这里可以添加自己的域名，你也可以使用自动生成的 `*.workers.dev` 的域名。记录下这个域名，后面部署前端会用到。 > [!NOTE] > 打开 `worker` 的 `url`，如果显示 `OK` 说明部署成功 > > 打开 `/health_check`，如果显示 `OK` 说明部署成功 + > + > 打开 `/open_api/settings`，如果返回 JSON，说明前端初始化依赖的公开配置接口可用。部署 Pages 前建议先确认这个地址正常。 ![worker3](/ui_install/worker-3.png) @@ -105,3 +110,5 @@ > [!NOTE] > 选择 `cron` 表达式，输入 `0 0 * * *`（此表达式表示每天午夜运行），点击 `Add` 增加。请根据您的需求调整此表达式。 + > + > 只在 admin 页面开启自动清理配置还不够，必须添加 Cron Trigger 后 Worker 的 `scheduled` 事件才会运行。D1 到达容量上限后会出现 `D1_ERROR: Exceeded maximum DB size`，新邮件无法继续写入，表现为“突然收不到邮件；删除几封后恢复”。