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