docs: restructure sidebar, expand FAQ, enhance send mail docs (#949)

* docs: restructure sidebar, expand FAQ, enhance send mail docs Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * docs: remove specific example domain reference in FAQ per review Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
2026-07-01 12:21:57 +08:00 · 2026-04-06 11:47:25 +08:00
parent b86d1faac4
commit 5248c03b6c
8 changed files with 201 additions and 35 deletions
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -20,6 +20,9 @@
 - docs: |Admin API| `/admin/new_address` 返回值文档补充 `address_id` 字段（#912）
 - docs: |Admin| 补充管理后台账号列表排序功能说明（#918）
 - docs: |Pages 部署| 补充 SPA 模式说明，避免刷新页面或直接访问子路径时 404（#813）
+- docs: |侧边栏| 重组文档侧边栏结构，拆分为"核心配置"、"通知与集成"、"高级功能"、"管理后台"等分组
+- docs: |FAQ| 大幅扩充常见问题，新增 SPA 404、发信余额、SMTP_CONFIG 配置、邮件客户端登录等高频问题（#919, #925, #839, #715, #921, #609）
+- docs: |发送邮件| 增强 SMTP_CONFIG 字段说明和多域名示例，新增发信余额机制说明

 ## v1.5.0(main)

--- a/CHANGELOG_EN.md
+++ b/CHANGELOG_EN.md
@@ -20,6 +20,9 @@
 - docs: |Admin API| Add `address_id` field to `/admin/new_address` response documentation (#912)
 - docs: |Admin| Add account list sorting feature documentation (#918)
 - docs: |Pages Deployment| Add SPA mode instructions to avoid 404 when refreshing or accessing sub-paths directly (#813)
+- docs: |Sidebar| Restructure documentation sidebar into "Core Configuration", "Notifications & Integrations", "Advanced Features", "Admin Console" groups
+- docs: |FAQ| Significantly expand FAQ with SPA 404, send balance, SMTP_CONFIG, mail client login and more (#919, #925, #839, #715, #921, #609)
+- docs: |Email Sending| Enhance SMTP_CONFIG field reference and multi-domain examples, add send balance mechanism documentation

 ## v1.5.0(main)

--- a/vitepress-docs/docs/.vitepress/en.ts
+++ b/vitepress-docs/docs/.vitepress/en.ts
@@ -136,25 +136,31 @@ function sidebarGuide(): DefaultTheme.SidebarItem[] {
            ]
        },
        {
-            text: 'General',
+            text: 'Core Configuration',
            collapsed: false,
            items: [
                { text: 'Worker Variables', link: 'worker-vars' },
-                { text: 'Common Issues', link: 'common-issues' },
+                { text: 'Configure Email Sending', link: 'config-send-mail' },
            ]
        },
        {
-            text: 'Additional Features',
+            text: 'Notifications & Integrations',
+            collapsed: false,
+            items: [
+                { text: 'Configure Telegram Bot', link: 'feature/telegram' },
+                { text: 'Configure Webhook', link: 'feature/webhook' },
+                { text: 'Configure SMTP/IMAP Mail Client', link: 'feature/config-smtp-proxy' },
+                { text: 'OAuth2 Third-party Login', link: 'feature/user-oauth2' },
+            ]
+        },
+        {
+            text: 'Advanced Features',
            collapsed: false,
            items: [
                { text: 'AI Email Recognition', link: 'feature/ai-extract' },
-                { text: 'Configure SMTP IMAP Proxy', link: 'feature/config-smtp-proxy' },
                { text: 'Configure Subdomain Email', link: 'feature/subdomain' },
-                { text: 'Configure Telegram Bot', link: 'feature/telegram' },
                { text: 'Configure S3 Attachments', link: 'feature/s3-attachment' },
                { text: 'Configure WASM Email Parser', link: 'feature/mail_parser_wasm_worker' },
-                { text: 'Configure Webhook', link: 'feature/webhook' },
-                { text: 'OAuth2 Third-party Login', link: 'feature/user-oauth2' },
                { text: 'Enhance with Other Workers', link: 'feature/another-worker-enhanced' },
                { text: 'Add Google Ads', link: 'feature/google-ads.md' },
            ]
@@ -170,13 +176,20 @@ function sidebarGuide(): DefaultTheme.SidebarItem[] {
            ]
        },
        {
-            text: 'Feature Overview',
+            text: 'Admin Console',
            collapsed: false,
            items: [
                { text: 'Admin Console', link: 'feature/admin' },
                { text: 'Admin User Management', link: 'feature/admin-user-management' },
            ]
        },
+        {
+            text: 'Help',
+            collapsed: false,
+            items: [
+                { text: 'FAQ', link: 'common-issues' },
+            ]
+        },
        { text: 'Reference', base: "/en/", link: 'reference' }
    ]
 }
--- a/vitepress-docs/docs/.vitepress/zh.ts
+++ b/vitepress-docs/docs/.vitepress/zh.ts
@@ -136,26 +136,32 @@ function sidebarGuide(): DefaultTheme.SidebarItem[] {
            ]
        },
        {
-            text: '通用',
+            text: '核心配置',
            collapsed: false,
            items: [
-                { text: 'worker变量说明', link: 'worker-vars' },
-                { text: '常见问题', link: 'common-issues' },
+                { text: 'Worker 变量说明', link: 'worker-vars' },
+                { text: '配置发送邮件', link: 'config-send-mail' },
            ]
        },
        {
-            text: '附加功能',
+            text: '通知与集成',
+            collapsed: false,
+            items: [
+                { text: '配置 Telegram Bot', link: 'feature/telegram' },
+                { text: '配置 webhook', link: 'feature/webhook' },
+                { text: '配置 SMTP/IMAP 邮件客户端', link: 'feature/config-smtp-proxy' },
+                { text: 'Oauth2 第三方登录', link: 'feature/user-oauth2' },
+            ]
+        },
+        {
+            text: '高级功能',
            collapsed: false,
            items: [
                { text: 'AI 邮件识别', link: 'feature/ai-extract' },
-                { text: '配置 SMTP IMAP 代理服务', link: 'feature/config-smtp-proxy' },
                { text: '配置子域名邮箱', link: 'feature/subdomain' },
-                { text: '配置 Telegram Bot', link: 'feature/telegram' },
                { text: '配置 S3 附件', link: 'feature/s3-attachment' },
                { text: '配置 worker 使用 wasm 解析邮件', link: 'feature/mail_parser_wasm_worker' },
-                { text: '配置 webhook', link: 'feature/webhook' },
-                { text: 'Oauth2 第三方登录', link: 'feature/user-oauth2' },
-                { text: '配置其他worker增强', link: 'feature/another-worker-enhanced' },
+                { text: '配置其他 worker 增强', link: 'feature/another-worker-enhanced' },
                { text: '给网页增加 Google Ads', link: 'feature/google-ads.md' },
            ]
        },
@@ -170,13 +176,20 @@ function sidebarGuide(): DefaultTheme.SidebarItem[] {
            ]
        },
        {
-            text: '功能简介',
+            text: '管理后台',
            collapsed: false,
            items: [
                { text: 'Admin 控制台', link: 'feature/admin' },
                { text: 'Admin 用户管理', link: 'feature/admin-user-management' },
            ]
        },
+        {
+            text: '帮助',
+            collapsed: false,
+            items: [
+                { text: '常见问题 (FAQ)', link: 'common-issues' },
+            ]
+        },
        { text: '参考', base: "/zh/", link: 'reference' }
    ]
 }
--- a/vitepress-docs/docs/en/guide/common-issues.md
+++ b/vitepress-docs/docs/en/guide/common-issues.md
@@ -1,4 +1,4 @@
-# Common Issues
+# FAQ

 > [!NOTE] Note
 > If you don't find a solution here, please search or ask in `Github Issues`, or ask in the Telegram group.
@@ -19,13 +19,28 @@
 | `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                                    |
-| `Cannot read properties of undefined (reading 'map')`              | Worker variables not set successfully                                       |
+| `Cannot read properties of undefined (reading 'map')`              | Worker variables not set successfully. Check that JSON-format variables like `DOMAINS` and `ADMIN_PASSWORDS` are configured correctly |

 ## Pages Related

 | Issue           | Solution                                                  |
 | --------------- | --------------------------------------------------------- |
 | `network error` | Use incognito mode or clear browser cache and DNS cache   |
+| 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) |
+
+## Email Sending Related
+
+| Issue           | Solution                                                  |
+| --------------- | --------------------------------------------------------- |
+| Set `DEFAULT_SEND_BALANCE` but still getting `No balance` | `DEFAULT_SEND_BALANCE` is the default quota when users **request sending permission**. Users must first click "Request Send Permission" in the frontend. Alternatively, add the address to the "No Limit Send Address List" in the admin console, or configure `NO_LIMIT_SEND_ROLE` |
+| Error: `Please enable resend or smtp for this domain` | You need to configure `RESEND_TOKEN` or `SMTP_CONFIG` first. See [Configure Email Sending](/en/guide/config-send-mail) |
+| `SMTP_CONFIG` configured but sending fails | Make sure the JSON key is **your own sending domain** (e.g. `your-domain.com`), not the example `awsl.uk`. See [Configure Email Sending](/en/guide/config-send-mail#send-emails-using-smtp) |
+
+## Mail Client Related
+
+| Issue           | Solution                                                  |
+| --------------- | --------------------------------------------------------- |
+| Set `ENABLE_ADDRESS_PASSWORD` but Foxmail/Outlook cannot login | `ENABLE_ADDRESS_PASSWORD` only enables the "address password login" web API. It does **NOT** provide standard IMAP/SMTP service. To use mail clients, you need to deploy the [SMTP/IMAP Proxy Service](/en/guide/feature/config-smtp-proxy) |

 ## Telegram Bot

--- a/vitepress-docs/docs/en/guide/config-send-mail.md
+++ b/vitepress-docs/docs/en/guide/config-send-mail.md
@@ -35,12 +35,18 @@ wrangler secret put RESEND_TOKEN_DREAMHUNTER2333_XYZ

 ## Send Emails Using SMTP

-The format of `SMTP_CONFIG` is as follows, where key is the domain name and value is the SMTP configuration. For SMTP configuration format details, refer to [zou-yu/worker-mailer](https://github.com/zou-yu/worker-mailer/blob/main/README_zh-CN.md)
+The format of `SMTP_CONFIG` is as follows. **The key must be your own sending domain**, and the value is the SMTP configuration.
+
+For SMTP configuration format details, refer to [zou-yu/worker-mailer](https://github.com/zou-yu/worker-mailer/blob/main/README_zh-CN.md)
+
+> [!warning] Important
+> The JSON key (e.g. `your-domain.com` in the example below) must be replaced with **your own domain** — the domain configured in your `DOMAINS` variable.
+> This is one of the most common configuration mistakes. Do not copy the example domain directly.

 ```json
 {
-    "awsl.uk": {
-        "host": "smtp.xxx.com",
+    "your-domain.com": {
+        "host": "smtp.example.com",
        "port": 465,
        "secure": true,
        "authType": [
@@ -48,13 +54,46 @@ The format of `SMTP_CONFIG` is as follows, where key is the domain name and valu
            "login"
        ],
        "credentials": {
-            "username": "username",
-            "password": "password"
+            "username": "your-smtp-username",
+            "password": "your-smtp-password"
        }
    }
 }
 ```

+**Field Reference:**
+
+| Field | Description |
+|-------|-------------|
+| key (e.g. `your-domain.com`) | Your sending domain, must match a domain configured in `DOMAINS` |
+| `host` | SMTP server address, e.g. `smtp.mailgun.org`, `smtp.gmail.com`, or your self-hosted SMTP server |
+| `port` | SMTP port, typically `465` (SSL) or `587` (STARTTLS) |
+| `secure` | Whether to use SSL/TLS. Set to `true` for port 465, `false` for port 587 |
+| `authType` | Authentication method, typically `["plain", "login"]` |
+| `credentials.username` | SMTP server login username |
+| `credentials.password` | SMTP server login password |
+
+If you have **multiple domains** using different SMTP services, add multiple keys in the same JSON:
+
+```json
+{
+    "domain-a.com": {
+        "host": "smtp.mailgun.org",
+        "port": 465,
+        "secure": true,
+        "authType": ["plain", "login"],
+        "credentials": { "username": "user@domain-a.com", "password": "xxx" }
+    },
+    "domain-b.com": {
+        "host": "smtp.gmail.com",
+        "port": 465,
+        "secure": true,
+        "authType": ["plain", "login"],
+        "credentials": { "username": "user@gmail.com", "password": "app-password" }
+    }
+}
+```
+
 Then execute the following command to add `SMTP_CONFIG` to secrets:

 > [!NOTE]
@@ -68,6 +107,19 @@ cd worker
 wrangler secret put SMTP_CONFIG
 ```

+## Send Balance Mechanism
+
+Users need a send balance to send emails. The balance mechanism works as follows:
+
+1. **Request Send Permission**: Users must first click the "Request Send Permission" button in the frontend
+2. **Default Quota**: Upon requesting, users receive the default quota set by the `DEFAULT_SEND_BALANCE` environment variable (defaults to 0 if not set)
+3. **Unlimited Sending**: The following methods can bypass balance checks:
+   - Add the address to the "No Limit Send Address List" in the admin console
+   - Configure the `NO_LIMIT_SEND_ROLE` environment variable to specify roles that can send without limits
+
+> [!NOTE]
+> `DEFAULT_SEND_BALANCE` does **NOT** automatically grant balance to all addresses. Users must actively request send permission first for the quota to take effect.
+
 ## Send Emails to Authenticated Forwarding Addresses on Cloudflare

 Only supported for CLI deployment, add `send_email` configuration in `wrangler.toml`.
--- a/vitepress-docs/docs/zh/guide/common-issues.md
+++ b/vitepress-docs/docs/zh/guide/common-issues.md
@@ -1,4 +1,4 @@
-# 常见问题
+# 常见问题 (FAQ)

 > [!NOTE] 注意
 > 如果你的问题没有在这里找到解决方案，请到 `Github Issues` 中搜索或者提问, 或者到 Telegram 群组中提问。
@@ -10,7 +10,7 @@
 | 使用 Cloudflare Workers 给已认证的转发邮箱发送邮件 | 使用 cf 的 API 进行发送，只支持绑定到 CF 上的收件地址，即 CF EMAIL 转发目的地址 |
 | 绑定多个域名                                       | 每个域名都需要设置 email 转发到 worker                                          |

-## worker 相关
+## Worker 相关

 | 问题                                                               | 解决方案                                                                    |
 | ------------------------------------------------------------------ | --------------------------------------------------------------------------- |
@@ -19,15 +19,30 @@
 | `二级域名无法发送邮件`                                             | [参考](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 用户设置公开邮箱                                                |
-| `Cannot read properties of undefined (reading 'map')`              | worker 变量没有设置成功                                                     |
+| `Cannot read properties of undefined (reading 'map')`              | worker 变量没有设置成功，请检查 `DOMAINS`、`ADMIN_PASSWORDS` 等 JSON 格式变量是否正确配置 |

-## pages 相关
+## Pages 相关

 | 问题            | 解决方案                                 |
 | --------------- | ---------------------------------------- |
 | `network error` | 使用无痕模式或者清空浏览器缓存，DNS 缓存 |
+| 刷新页面或直接访问 `/admin`、`/user` 返回 404 | 本项目是单页应用（SPA），通过 UI 部署 Pages 时需要在高级选项中将「未找到处理」设置为 `Single-page application (SPA)`。详见 [Pages 前端部署](/zh/guide/ui/pages) |

-## telegram bot
+## 发送邮件相关
+
+| 问题            | 解决方案                                 |
+| --------------- | ---------------------------------------- |
+| 设置了 `DEFAULT_SEND_BALANCE` 但仍提示 `No balance` | `DEFAULT_SEND_BALANCE` 是用户**申请发信权限时**的默认额度，用户需要先在前端界面点击「申请发信权限」才会生效。也可以在 admin 后台将地址加入「无限制发送地址列表」，或配置 `NO_LIMIT_SEND_ROLE` |
+| 提示 `请先为此域名启用 resend 或 smtp` | 需要先配置 `RESEND_TOKEN` 或 `SMTP_CONFIG`，详见 [配置发送邮件](/zh/guide/config-send-mail) |
+| `SMTP_CONFIG` 配置了但发送失败 | 请确认 JSON 中的 key 是**你自己的发信域名**（如 `your-domain.com`），不要直接复制示例 key。详见 [配置发送邮件](/zh/guide/config-send-mail#使用-smtp-发送邮件) |
+
+## 邮件客户端相关
+
+| 问题            | 解决方案                                 |
+| --------------- | ---------------------------------------- |
+| 设置了 `ENABLE_ADDRESS_PASSWORD` 但 Foxmail/Outlook 等客户端无法登录 | `ENABLE_ADDRESS_PASSWORD` 只是开启「地址密码登录」Web 接口，**不等于**提供标准 IMAP/SMTP 服务。要使用邮件客户端收发邮件，需要额外部署 [SMTP/IMAP 代理服务](/zh/guide/feature/config-smtp-proxy) |
+
+## Telegram Bot

 | 问题                                                           | 解决方案                                           |
 | -------------------------------------------------------------- | -------------------------------------------------- |
--- a/vitepress-docs/docs/zh/guide/config-send-mail.md
+++ b/vitepress-docs/docs/zh/guide/config-send-mail.md
@@ -35,12 +35,18 @@ wrangler secret put RESEND_TOKEN_DREAMHUNTER2333_XYZ

 ## 使用 SMTP 发送邮件

-`SMTP_CONFIG` 的格式如下，key 为域名，value 为 SMTP 配置，SMTP 配置格式详情可以参考 [zou-yu/worker-mailer](https://github.com/zou-yu/worker-mailer/blob/main/README_zh-CN.md)
+`SMTP_CONFIG` 的格式如下，**key 必须是你自己的发信域名**，value 为 SMTP 配置。
+
+SMTP 配置格式详情可以参考 [zou-yu/worker-mailer](https://github.com/zou-yu/worker-mailer/blob/main/README_zh-CN.md)
+
+> [!warning] 重要
+> JSON 中的 key（如下面示例中的 `your-domain.com`）必须替换为**你自己的域名**，即 `DOMAINS` 变量中配置的域名。
+> 这是最常见的配置错误之一，请勿直接复制示例中的域名。

 ```json
 {
-    "awsl.uk": {
-        "host": "smtp.xxx.com",
+    "your-domain.com": {
+        "host": "smtp.example.com",
        "port": 465,
        "secure": true,
        "authType": [
@@ -48,13 +54,46 @@ wrangler secret put RESEND_TOKEN_DREAMHUNTER2333_XYZ
            "login"
        ],
        "credentials": {
-            "username": "username",
-            "password": "password"
+            "username": "your-smtp-username",
+            "password": "your-smtp-password"
        }
    }
 }
 ```

+**字段说明：**
+
+| 字段 | 说明 |
+|------|------|
+| key（如 `your-domain.com`） | 你的发信域名，必须与 `DOMAINS` 中配置的域名一致 |
+| `host` | SMTP 服务器地址，如 `smtp.mailgun.org`、`smtp.gmail.com` 或你自建的 SMTP 服务器地址 |
+| `port` | SMTP 端口，通常 `465`（SSL）或 `587`（STARTTLS） |
+| `secure` | 是否使用 SSL/TLS，端口 465 时设为 `true`，端口 587 时设为 `false` |
+| `authType` | 认证方式，一般使用 `["plain", "login"]` |
+| `credentials.username` | SMTP 服务器的登录用户名 |
+| `credentials.password` | SMTP 服务器的登录密码 |
+
+如果你有**多个域名**使用不同的 SMTP 服务，在同一个 JSON 中添加多个 key 即可：
+
+```json
+{
+    "domain-a.com": {
+        "host": "smtp.mailgun.org",
+        "port": 465,
+        "secure": true,
+        "authType": ["plain", "login"],
+        "credentials": { "username": "user@domain-a.com", "password": "xxx" }
+    },
+    "domain-b.com": {
+        "host": "smtp.gmail.com",
+        "port": 465,
+        "secure": true,
+        "authType": ["plain", "login"],
+        "credentials": { "username": "user@gmail.com", "password": "app-password" }
+    }
+}
+```
+
 然后执行下面的命令，将 `SMTP_CONFIG` 添加到 secrets 中

 > [!NOTE]
@@ -68,6 +107,19 @@ cd worker
 wrangler secret put SMTP_CONFIG
 ```

+## 发信余额机制
+
+用户发送邮件需要有发信余额。余额机制如下：
+
+1. **申请发信权限**：用户需要先在前端界面点击「申请发信权限」按钮
+2. **默认额度**：申请时会获得 `DEFAULT_SEND_BALANCE` 环境变量设置的默认额度（如果未设置则为 0）
+3. **无限制发送**：以下方式可以跳过余额检查：
+   - 在 admin 后台将地址加入「无限制发送地址列表」
+   - 配置 `NO_LIMIT_SEND_ROLE` 环境变量，指定可以无限发送的用户角色
+
+> [!NOTE]
+> `DEFAULT_SEND_BALANCE` **不会**自动给所有地址充值余额，用户必须先主动申请发信权限，额度才会生效。
+
 ## 给 Cloudflare 上已认证的转发邮箱发送邮件

 仅支持 CLI 部署时使用，在 `wrangler.toml` 中添加 `send_email` 配置