docs: update missing documentation from closed issues (#948)

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

vitepress-docs/docs/zh/guide/cli/pages.md

@@ -9,6 +9,10 @@
 
 ## 前后端分离部署
 
+> [!warning] 重要：SPA 模式
+> 本项目是单页应用（SPA）。如果你通过 Cloudflare 控制台手动上传部署，**必须在高级选项中将「未找到处理」设置为 `Single-page application (SPA)`**，否则刷新页面或直接访问 `/admin` 等子路径时会返回 404。
+> 通过 CLI（`wrangler pages deploy`）部署时会自动处理，无需额外配置。
+
 第一次部署会提示创建项目, `production` 分支请填写 `production`
 
 ```bash

vitepress-docs/docs/zh/guide/cli/worker.md

@@ -35,6 +35,8 @@ compatibility_date = "2024-09-23"
 compatibility_flags = [ "nodejs_compat" ]
 
 # 如果你想使用自定义域名，你需要添加 routes 配置
+# 将 pattern 替换为你自己的域名，该域名需要已添加到你的 Cloudflare 账户中
+# 配置后 Worker 将通过该自定义域名提供服务，而非默认的 *.workers.dev 域名
 # routes = [
 #  { pattern = "temp-email-api.xxxxx.xyz", custom_domain = true },
 # ]
@@ -59,7 +61,8 @@ compatibility_flags = [ "nodejs_compat" ]
 PREFIX = "tmp"
 # 用于临时邮箱的所有域名, 支持多个域名
 DOMAINS = ["xxx.xxx1" , "xxx.xxx2"]
-# 用于生成 jwt 的密钥, jwt 用于给用户登录以及鉴权
+# 用于签名 JWT 的密钥，JWT 用于登录鉴权
+# 请使用随机字符串，例如通过 openssl rand -hex 32 生成
 JWT_SECRET = "xxx"
 
 # admin 控制台密码, 不配置则不允许访问控制台

vitepress-docs/docs/zh/guide/feature/admin.md

@@ -10,6 +10,19 @@
 
 ![admin](/feature/admin.png)
 
+## 账号列表排序
+
+管理后台的账号标签页支持按列排序，可点击表头对以下列进行升序/降序排列：
+
+- ID
+- 名称
+- 创建时间
+- 更新时间
+- 邮件数量
+- 发送数量
+
+搜索邮箱地址时，分页会自动重置到第 1 页。
+
 ## 如果你的网站只可私人访问，可通过此禁用检查
 
 `DISABLE_ADMIN_PASSWORD_CHECK = true`

vitepress-docs/docs/zh/guide/feature/new-address-api.md

@@ -35,7 +35,7 @@ res = requests.post(
     }
 )
 
-# 返回值 {"jwt": "<Jwt>"}
+# 返回值 {"jwt": "<Jwt>", "address": "<邮箱地址>", "address_id": 123}
 print(res.json())
 ```
 

vitepress-docs/docs/zh/guide/feature/send-mail-api.md

@@ -2,7 +2,19 @@
 
 ## 通过 HTTP API 发送邮件
 
-这是一个 `python` 的例子，使用 `requests` 库发送邮件。
+有两种 HTTP API 端点可以发送邮件，区别如下：
+
+| 端点 | 认证方式 | 适用场景 |
+|------|---------|---------|
+| `/api/send_mail` | `Authorization: Bearer <地址JWT>` header | 内部调用，需要先通过 cookie / header 鉴权 |
+| `/external/api/send_mail` | 请求体中的 `token` 字段 | 外部系统集成，无需 header 鉴权 |
+
+::: tip 什么是"地址 JWT"？
+地址 JWT 是通过 `/api/new_address` 或 `/admin/new_address` 创建邮箱地址时返回的 `jwt` 字段。
+你可以在前端 UI 的「密码」菜单中查看它。它**不是** `JWT_SECRET` 环境变量，也**不是** admin 密码。
+:::
+
+### 方式一：通过 Header 认证（`/api/send_mail`）
 
 ```python
 send_body = {
@@ -15,17 +27,22 @@ send_body = {
 }
 
 res = requests.post(
-    "http://localhost:8787/api/send_mail",
+    "https://你的worker域名/api/send_mail",
     json=send_body, headers={
-        "Authorization": f"Bearer {你的JWT密码}",
+        "Authorization": f"Bearer {地址JWT}",
         # "x-custom-auth": "<你的网站密码>", # 如果启用了私有站点密码
         "Content-Type": "application/json"
     }
 )
+```
 
-# 使用 body 验证
+### 方式二：通过 Body Token 认证（`/external/api/send_mail`）
+
+适合外部系统调用，将地址 JWT 放在请求体的 `token` 字段中：
+
+```python
 send_body = {
-    "token": "<你的JWT密码>",
+    "token": "<地址JWT>",
     "from_name": "发件人名字",
     "to_name": "收件人名字",
     "to_mail": "收件人地址",
@@ -34,7 +51,7 @@ send_body = {
     "content": "<邮件内容：html 或者 文本>",
 }
 res = requests.post(
-    "http://localhost:8787/external/api/send_mail",
+    "https://你的worker域名/external/api/send_mail",
     json=send_body, headers={
         # "x-custom-auth": "<你的网站密码>", # 如果启用了私有站点密码
         "Content-Type": "application/json"

vitepress-docs/docs/zh/guide/ui/pages.md

@@ -70,7 +70,13 @@ const generate = async () => {
     >
     > 搜索 `https://temp-email-api.xxx.xxx` ，替换成你worker 的域名，然后部署新的zip文件
 
-4. 选择 `Pages`，点击 `Create Pages`, 修改名称，上传下载的 zip 包，然后点击 `Deploy`
+4. 选择 `Pages`，点击 `Create Pages`, 修改名称，上传下载的 zip 包
+
+    > [!warning] 重要：SPA 模式
+    > 本项目是单页应用（SPA），**必须在部署时展开高级选项，将「未找到处理」设置为 `Single-page application (SPA)`**。
+    > 否则刷新页面或直接访问 `/admin` 等子路径时会返回 404。
+
+    然后点击 `Deploy`
 
     ![pages1](/ui_install/pages-1.png)
 

vitepress-docs/docs/zh/guide/worker-vars.md

@@ -8,7 +8,7 @@
 | 变量名                     | 类型        | 说明                                       | 示例                                 |
 | -------------------------- | ----------- | ------------------------------------------ | ------------------------------------ |
 | `DOMAINS`                  | JSON        | 用于临时邮箱的所有域名, 支持多个域名       | `["awsl.uk", "dreamhunter2333.xyz"]` |
-| `JWT_SECRET`               | 文本/Secret | 用于生成 jwt 的密钥, jwt 用于登录以及鉴权  | `xxx`                                |
+| `JWT_SECRET`               | 文本/Secret | 用于签名 JWT 的密钥，JWT 用于登录鉴权。请使用随机字符串，例如通过 `openssl rand -hex 32` 生成  | `a1b2c3d4...`                        |
 | `ADMIN_PASSWORDS`          | JSON        | admin 控制台密码, 不配置则不允许访问控制台 | `["123", "456"]`                     |
 | `ENABLE_USER_CREATE_EMAIL` | 文本/JSON   | 是否允许用户创建邮箱, 不配置则不允许       | `true`                               |
 | `ENABLE_USER_DELETE_EMAIL` | 文本/JSON   | 是否允许用户删除邮件, 不配置则不允许       | `true`                               |