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