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

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
2026-05-06 20:32:55 +08:00 · 2026-04-06 11:11:44 +08:00
parent a0db913952
commit b86d1faac4
16 changed files with 120 additions and 20 deletions
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -14,6 +14,13 @@

 ### Improvements

+- docs: |发送邮件 API| 明确 `/api/send_mail` 与 `/external/api/send_mail` 两个端点的认证方式差异，补充"地址 JWT"概念说明（#922）
+- docs: |Worker 变量| `JWT_SECRET` 补充生成方式说明（`openssl rand -hex 32`）（#932）
+- docs: |CLI 部署| `routes` 自定义域名配置增加用途说明（#932）
+- docs: |Admin API| `/admin/new_address` 返回值文档补充 `address_id` 字段（#912）
+- docs: |Admin| 补充管理后台账号列表排序功能说明（#918）
+- docs: |Pages 部署| 补充 SPA 模式说明，避免刷新页面或直接访问子路径时 404（#813）
+
 ## v1.5.0(main)

 ### Features
--- a/CHANGELOG_EN.md
+++ b/CHANGELOG_EN.md
@@ -14,6 +14,13 @@

 ### Improvements

+- docs: |Send Mail API| Clarify authentication differences between `/api/send_mail` and `/external/api/send_mail`, add "Address JWT" concept explanation (#922)
+- docs: |Worker Variables| Add generation instructions for `JWT_SECRET` (`openssl rand -hex 32`) (#932)
+- docs: |CLI Deployment| Add usage explanation for `routes` custom domain configuration (#932)
+- 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)
+
 ## v1.5.0(main)

 ### Features
--- a/vitepress-docs/docs/en/guide/cli/pages.md
+++ b/vitepress-docs/docs/en/guide/cli/pages.md
@@ -9,6 +9,10 @@ Refer to [Deploy Worker](/en/guide/cli/worker#deploy-worker-with-frontend-option

 ## Separate Frontend and Backend Deployment

+> [!warning] Important: SPA Mode
+> This project is a Single-Page Application (SPA). If you deploy manually via the Cloudflare dashboard, **you must set "Not Found handling" to `Single-page application (SPA)` in the advanced options**, otherwise refreshing the page or directly accessing sub-paths like `/admin` will return a 404 error.
+> When deploying via CLI (`wrangler pages deploy`), this is handled automatically and no extra configuration is needed.
+
 The first deployment will prompt you to create a project. For the `production` branch, enter `production`.

 ```bash
--- a/vitepress-docs/docs/en/guide/cli/worker.md
+++ b/vitepress-docs/docs/en/guide/cli/worker.md
@@ -35,6 +35,8 @@ compatibility_date = "2024-09-23"
 compatibility_flags = [ "nodejs_compat" ]

 # If you want to use a custom domain, you need to add routes configuration
+# Replace pattern with your own domain, which must already be added to your Cloudflare account
+# Once configured, the Worker will serve via this custom domain instead of the default *.workers.dev domain
 # routes = [
 #  { pattern = "temp-email-api.xxxxx.xyz", custom_domain = true },
 # ]
@@ -59,7 +61,8 @@ compatibility_flags = [ "nodejs_compat" ]
 PREFIX = "tmp"
 # All domains used for temporary email, supports multiple domains
 DOMAINS = ["xxx.xxx1" , "xxx.xxx2"]
-# Secret key for generating JWT, JWT is used for user login and authentication
+# Secret key for signing JWTs used in login and authentication
+# Use a random string, e.g. generated via: openssl rand -hex 32
 JWT_SECRET = "xxx"

 # Admin console password, if not configured, console access is not allowed
--- a/vitepress-docs/docs/en/guide/feature/admin.md
+++ b/vitepress-docs/docs/en/guide/feature/admin.md
@@ -10,6 +10,19 @@ You need to configure `ADMIN_PASSWORDS` in the backend or ensure the current use

 ![admin](/feature/admin.png)

+## Account List Sorting
+
+The Accounts tab in the admin console supports column sorting. Click the column header to toggle ascending/descending order for:
+
+- ID
+- Name
+- Created At
+- Updated At
+- Mail Count
+- Send Count
+
+When searching for email addresses, pagination automatically resets to page 1.
+
 ## If your website is for private access only, you can disable this check

 `DISABLE_ADMIN_PASSWORD_CHECK = true`
--- a/vitepress-docs/docs/en/guide/feature/new-address-api.md
+++ b/vitepress-docs/docs/en/guide/feature/new-address-api.md
@@ -35,7 +35,7 @@ res = requests.post(
    }
 )

-# Returns {"jwt": "<Jwt>"}
+# Returns {"jwt": "<Jwt>", "address": "<email_address>", "address_id": 123}
 print(res.json())
 ```

--- a/vitepress-docs/docs/en/guide/feature/send-mail-api.md
+++ b/vitepress-docs/docs/en/guide/feature/send-mail-api.md
@@ -2,7 +2,19 @@

 ## Send Email via HTTP API

-This is a `python` example using the `requests` library to send emails.
+There are two HTTP API endpoints for sending emails:
+
+| Endpoint | Authentication | Use Case |
+|----------|---------------|----------|
+| `/api/send_mail` | `Authorization: Bearer <address_JWT>` header | Internal calls, requires cookie / header auth |
+| `/external/api/send_mail` | `token` field in request body | External system integration, no header auth needed |
+
+::: tip What is "Address JWT"?
+The Address JWT is the `jwt` field returned when creating an email address via `/api/new_address` or `/admin/new_address`.
+You can view it in the "Password" menu in the frontend UI. It is **NOT** the `JWT_SECRET` environment variable, nor the admin password.
+:::
+
+### Method 1: Header Authentication (`/api/send_mail`)

 ```python
 send_body = {
@@ -15,17 +27,22 @@ send_body = {
 }

 res = requests.post(
-    "http://localhost:8787/api/send_mail",
+    "https://your_worker_domain/api/send_mail",
    json=send_body, headers={
-        "Authorization": f"Bearer {your_JWT_password}",
+        "Authorization": f"Bearer {address_JWT}",
        # "x-custom-auth": "<your_website_password>", # If private site password is enabled
        "Content-Type": "application/json"
    }
 )
+```

-# Using body authentication
+### Method 2: Body Token Authentication (`/external/api/send_mail`)
+
+Suitable for external system calls, place the Address JWT in the `token` field of the request body:
+
+```python
 send_body = {
-    "token": "<your_JWT_password>",
+    "token": "<address_JWT>",
    "from_name": "Sender Name",
    "to_name": "Recipient Name",
    "to_mail": "Recipient Address",
@@ -34,7 +51,7 @@ send_body = {
    "content": "<Email content: html or text>",
 }
 res = requests.post(
-    "http://localhost:8787/external/api/send_mail",
+    "https://your_worker_domain/external/api/send_mail",
    json=send_body, headers={
        # "x-custom-auth": "<your_website_password>", # If private site password is enabled
        "Content-Type": "application/json"
--- a/vitepress-docs/docs/en/guide/ui/pages.md
+++ b/vitepress-docs/docs/en/guide/ui/pages.md
@@ -70,7 +70,13 @@ const generate = async () => {
    >
    > Search for `https://temp-email-api.xxx.xxx` and replace it with your worker's domain, then deploy the new zip file

-4. Select `Pages`, click `Create Pages`, modify the name, upload the downloaded zip package, and then click `Deploy`
+4. Select `Pages`, click `Create Pages`, modify the name, upload the downloaded zip package
+
+    > [!warning] Important: SPA Mode
+    > This project is a Single-Page Application (SPA). **You must expand the advanced options during deployment and set "Not Found handling" to `Single-page application (SPA)`**.
+    > Otherwise, refreshing the page or directly accessing sub-paths like `/admin` will return a 404 error.
+
+    Then click `Deploy`

    ![pages1](/ui_install/pages-1.png)

--- a/vitepress-docs/docs/en/guide/worker-vars.md
+++ b/vitepress-docs/docs/en/guide/worker-vars.md
@@ -8,7 +8,7 @@
 | Variable Name              | Type        | Description                                                            | Example                              |
 | -------------------------- | ----------- | ---------------------------------------------------------------------- | ------------------------------------ |
 | `DOMAINS`                  | JSON        | All domains for temporary email, supports multiple domains             | `["awsl.uk", "dreamhunter2333.xyz"]` |
-| `JWT_SECRET`               | Text/Secret | Secret key for generating JWT, used for login and authentication       | `xxx`                                |
+| `JWT_SECRET`               | Text/Secret | Secret key for signing JWTs used in login and authentication. Use a random string, e.g. generated via `openssl rand -hex 32` | `a1b2c3d4...`                        |
 | `ADMIN_PASSWORDS`          | JSON        | Admin console passwords, console access disabled if not configured     | `["123", "456"]`                     |
 | `ENABLE_USER_CREATE_EMAIL` | Text/JSON   | Whether to allow users to create mailboxes, disabled if not configured | `true`                               |
 | `ENABLE_USER_DELETE_EMAIL` | Text/JSON   | Whether to allow users to delete emails, disabled if not configured    | `true`                               |
--- a/vitepress-docs/docs/zh/guide/cli/pages.md
+++ b/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
--- a/vitepress-docs/docs/zh/guide/cli/worker.md
+++ b/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 控制台密码, 不配置则不允许访问控制台
--- a/vitepress-docs/docs/zh/guide/feature/admin.md
+++ b/vitepress-docs/docs/zh/guide/feature/admin.md
@@ -10,6 +10,19 @@

 ![admin](/feature/admin.png)

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

 `DISABLE_ADMIN_PASSWORD_CHECK = true`
--- a/vitepress-docs/docs/zh/guide/feature/new-address-api.md
+++ b/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())
 ```

--- a/vitepress-docs/docs/zh/guide/feature/send-mail-api.md
+++ b/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"
--- a/vitepress-docs/docs/zh/guide/ui/pages.md
+++ b/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)

--- a/vitepress-docs/docs/zh/guide/worker-vars.md
+++ b/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`                               |