docs: clarify mailbox rebinding and page function actions (#1012)

docs: clarify mailbox rebinding and page functions actions

CHANGELOG.md

@@ -16,6 +16,7 @@
 - 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 菜单移动到核心配置之后，提升可见性
+- docs: |文档| 补充重新创建旧邮箱提示地址已存在时的处理方式，并完善 GitHub Actions 自动更新配合 Page Functions 转发后端请求的 workflow 说明（issues #947 #654）
 
 ### Bug Fixes
 

CHANGELOG_EN.md

@@ -16,6 +16,7 @@
 - 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
+- docs: |Docs| Document how to handle the "address already exists" case when recreating an old mailbox, and clarify the GitHub Actions workflow for automatic updates with Page Functions forwarding backend requests (issues #947 #654)
 
 ### Bug Fixes
 

vitepress-docs/docs/en/guide/actions/github-action.md

@@ -57,6 +57,16 @@ Then go to the repository page `Settings` -> `Secrets and variables` -> `Actions
 - If you need separate frontend and backend deployment that talks to Worker directly, find `Deploy Frontend` and click `Run workflow` to select a branch and deploy manually
 - If you need Pages deployment with Page Functions forwarding backend requests, find `Deploy Frontend with page function` and click `Run workflow` to deploy manually
 
+### Auto-Update with Page Functions Forwarding
+
+If you want to use `Upstream Sync` for automatic updates and also let Pages forward backend requests through Page Functions, use the `Deploy Frontend with page function` workflow instead of `Deploy Frontend`.
+
+- Enable `Upstream Sync`, `Deploy Backend`, and `Deploy Frontend with page function`
+- Configure the `PAGE_TOML` repository secret by copying the content of `pages/wrangler.toml`
+- Change the `service` field in `PAGE_TOML` to your Worker backend name
+- This workflow runs `pnpm build:pages`, uses same-origin frontend requests, and does not read `FRONTEND_ENV`
+- After each completed `Upstream Sync`, `Deploy Frontend with page function` deploys the frontend automatically when `PAGE_TOML` is configured
+
 ## How to Configure Auto-Update
 
 1. Open the `Actions` page of the repository, find `Upstream Sync`, and click `enable workflow` to enable the `workflow`

vitepress-docs/docs/en/guide/common-issues.md

@@ -10,6 +10,7 @@
 | Sending emails to authenticated forwarding addresses using Cloudflare Workers | Use CF's API for sending, only supports recipient addresses bound to CF, i.e., CF EMAIL forwarding destination addresses |
 | Binding multiple domains                               | Each domain needs to configure email forwarding to worker                                         |
 | Subdomain cannot receive email                         | Subdomains must have Email Routing **enabled separately** on Cloudflare with their own DNS records and Catch-all rule. Enabling it only on the apex domain does NOT cover subdomains. See [Email Routing](/en/guide/email-routing) |
+| Recreating a previously used mailbox shows that the address already exists | The address may have been recreated or bound by another user after it expired or was unbound, so a normal user cannot reclaim it directly. If you have admin access, find the address in the admin address list, get its address credential, and then bind it to the target user again |
 
 ## Worker Related
 
@@ -59,3 +60,4 @@
 | Issue                                                      | Solution                                                                                     |
 | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
 | After Github Action deployment, CF always shows preview branch | Go to CF pages settings to confirm that the frontend branch matches the Github Action frontend deployment branch |
+| Use GitHub Actions auto-update while forwarding backend requests through Page Functions | Enable the `Deploy Frontend with page function` workflow and configure the `PAGE_TOML` secret. Copy `pages/wrangler.toml` into `PAGE_TOML`, then change `service` to your Worker backend name. This workflow uses same-origin requests and does not need `FRONTEND_ENV` |

vitepress-docs/docs/zh/guide/actions/github-action.md

@@ -57,6 +57,16 @@
 - 如果需要前后端分离并直连 Worker, 找到 `Deploy Frontend`，点击 `Run workflow` 选择分支手动部署
 - 如果需要通过 Page Functions 转发后端请求的 Pages 部署, 找到 `Deploy Frontend with page function`，点击 `Run workflow` 手动部署
 
+### 自动更新与 Page Functions 转发
+
+如果你既想通过 `Upstream Sync` 自动更新，又想让 Pages 通过 Page Functions 转发后端请求，请使用 `Deploy Frontend with page function` workflow，而不是 `Deploy Frontend`。
+
+- 先启用 `Upstream Sync`、`Deploy Backend` 和 `Deploy Frontend with page function`
+- 在仓库 `Secrets` 中配置 `PAGE_TOML`，内容复制 `pages/wrangler.toml`
+- 将 `PAGE_TOML` 里的 `service` 改成你的 Worker 后端名称
+- 这个 workflow 会执行 `pnpm build:pages`，前端走同域请求，不读取 `FRONTEND_ENV`
+- 每次 `Upstream Sync` 完成后，如果 `PAGE_TOML` 已配置，`Deploy Frontend with page function` 会自动部署前端
+
 ## 如何配置自动更新
 
 1. 打开仓库的 `Actions` 页面，找到 `Upstream Sync`，点击 `enable workflow` 启用 `workflow`

vitepress-docs/docs/zh/guide/common-issues.md

@@ -10,6 +10,7 @@
 | 使用 Cloudflare Workers 给已认证的转发邮箱发送邮件 | 使用 cf 的 API 进行发送，只支持绑定到 CF 上的收件地址，即 CF EMAIL 转发目的地址 |
 | 绑定多个域名                                       | 每个域名都需要设置 email 转发到 worker                                          |
 | 子域名收不到邮件                                   | 子域名需要在 CF 上**单独启用** Email Routing 并配置 DNS 与 Catch-all 规则，仅在一级域开启不会自动覆盖子域，详见 [Email Routing](/zh/guide/email-routing) |
+| 重新创建以前用过的邮箱提示地址已存在 | 这个地址可能在过期释放或解绑后已经被其他用户重新创建或绑定，普通用户不能直接抢回。若你有 admin 权限，可以在 admin 地址列表中找到该地址并获取邮箱地址凭据，然后用凭据重新绑定到目标用户 |
 
 ## Worker 相关
 
@@ -59,3 +60,4 @@
 | 问题                                       | 解决方案                                                                          |
 | ------------------------------------------ | --------------------------------------------------------------------------------- |
 | Github Action部署后，cf里始终是preview分支 | 到 cf pages 页面的设置中确认 前端的分支 和 Github Action 的 前端部署分支 是否相同 |
+| 想用 GitHub Actions 自动更新，同时通过 Page Functions 转发后端请求 | 启用 `Deploy Frontend with page function` workflow，并配置 `PAGE_TOML` secret；`PAGE_TOML` 复制 `pages/wrangler.toml` 内容后把 `service` 改成你的 Worker 后端名称。这个 workflow 走同域请求，不需要 `FRONTEND_ENV` |