diff --git a/CHANGELOG.md b/CHANGELOG.md index bc71337e..8571da58 100644 --- 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) diff --git a/CHANGELOG_EN.md b/CHANGELOG_EN.md index 7758cdad..f5c091a2 100644 --- 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) diff --git a/vitepress-docs/docs/.vitepress/en.ts b/vitepress-docs/docs/.vitepress/en.ts index 1fe1f842..a5c5ffaa 100644 --- 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' } ] } diff --git a/vitepress-docs/docs/.vitepress/zh.ts b/vitepress-docs/docs/.vitepress/zh.ts index 7df7a648..e9877b0b 100644 --- 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' } ] } diff --git a/vitepress-docs/docs/en/guide/common-issues.md b/vitepress-docs/docs/en/guide/common-issues.md index 1e8b0650..4ea3af6c 100644 --- 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 diff --git a/vitepress-docs/docs/en/guide/config-send-mail.md b/vitepress-docs/docs/en/guide/config-send-mail.md index e16ac581..230e3eb3 100644 --- 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`. diff --git a/vitepress-docs/docs/zh/guide/common-issues.md b/vitepress-docs/docs/zh/guide/common-issues.md index 91f2ea50..85474124 100644 --- 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 | 问题 | 解决方案 | | -------------------------------------------------------------- | -------------------------------------------------- | diff --git a/vitepress-docs/docs/zh/guide/config-send-mail.md b/vitepress-docs/docs/zh/guide/config-send-mail.md index 01b7da50..526905ba 100644 --- 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` 配置