docs: improve deployment troubleshooting (#1011)

* docs: improve deployment troubleshooting docs

* docs: fix GitHub casing in FAQ

* docs: clarify subdomain address creation

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
 

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

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.
 

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.

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)

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`.
 
     <div :class="$style.container">
         <input :class="$style.input" type="text" v-model="domain" placeholder="Enter a backend API URL starting with https://"></input>
@@ -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
 

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".