docs: improve deployment troubleshooting (#1011)

* docs: improve deployment troubleshooting docs

* docs: fix GitHub casing in FAQ

* docs: clarify subdomain address creation

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 安全挑战页 |
 
 ## 发送邮件相关
 

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)
 

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 直接指定子域名

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），可以启用邮箱格式转换功能。

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 部署
 

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`。
 
     <div :class="$style.container">
         <input :class="$style.input" type="text" v-model="domain" placeholder="请输入以 https:// 开头的后端 API 地址"></input>
@@ -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 包
 

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`，新邮件无法继续写入，表现为“突然收不到邮件；删除几封后恢复”。