Add files via upload

2026-05-06 20:02:56 +08:00 · 2026-04-25 16:24:16 +08:00
parent 09fc1c4364
commit 31507a4712
1 changed files with 76 additions and 106 deletions
--- a/README.md
+++ b/README.md
@@ -2,18 +2,16 @@

 一個極簡的 Cloudflare Worker，用於接收私人域名郵件並提供 HTTP API 讀取。

-無需前端、無需 JWT，部署後即可通過 API 取得最新郵件內容。
+無需資料庫、無需前端、無需 JWT，部署後即可通過 API 取得最新郵件內容。

 ## 特性

 - 📨 通過 Cloudflare Email Routing 接收郵件
- 🗄️ 使用 Durable Objects + SQLite 儲存郵件 metadata，使用 R2 儲存附件內容
+- 🗄️ 使用 KV 儲存，最多保留 50 封
 - 🔑 API Key 鑑權
 - 🌐 支持多個自定義域名（域名需托管在 Cloudflare）
- 📦 保留原版極簡 API：`/latest`、`/mails`、`/mail/:id`
- 🧵 支持 threaded inbox、thread detail、附件下載
- ✉️ 可選支持 `send / reply / forward`（配置 `EMAIL` binding 後啟用）
- 🚫 未配置 `EMAIL` binding 時，收信與讀信 API 仍可正常工作
+- 📦 僅依賴 `postal-mime`，無其他依賴
+- 🚫 附件只保留 metadata，不存 base64，避免撞 KV 25MB 限制

 ## 工作原理

@@ -21,21 +19,18 @@
 外部郵件 → 你的域名 MX（Cloudflare Email Routing）
                  ↓ catch-all 轉發
         Cloudflare Worker（收信 + HTTP API）
-                  ↓
-         Mailbox Durable Object（每個 mailbox 一個）
-                  ↓
-         SQLite（郵件 metadata / thread） + R2（附件）
-                  ↓
+                  ↓ 存儲
+         Cloudflare KV（最近 50 封）
+                  ↓ 讀取
         curl /latest → 自動化腳本
 ```

-郵件到達後由 `postal-mime` 解析為結構化 JSON，通過帶鑑權的 HTTP API 按需讀取。
+郵件到達後由 `postal-mime` 解析為結構化 JSON，通過帶鑑權的 HTTP API 按需讀取，無需輪詢、無需訂閱。

 ## 前置條件

 - 域名已托管在 Cloudflare
 - 已啟用 Cloudflare Email Routing
- Node.js 20 或更高版本

 > ⚠️ 收信地址必須是托管在 Cloudflare 的真實域名（如 `user@yourdomain.com`），
 > `*.workers.dev` 不支持 Email Routing，發往 workers.dev 地址的信不會被收到。
@@ -44,134 +39,109 @@

 ### 方式一：Cloudflare 一鍵部署

-上傳到你自己的 GitHub 倉庫後，將下方按鈕中的 `<YOUR_USERNAME>/<YOUR_REPO>` 換成實際倉庫地址即可：
+[![Deploy to Cloudflare Workers](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/mskatoni/ni-mail)

-```markdown
-[![Deploy to Cloudflare Workers](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/<YOUR_USERNAME>/<YOUR_REPO>)
-```
-
-Cloudflare Builds 建議配置：
-
- Root directory：留空或 `/`
- Build command：留空
- Deploy command：`npm run deploy`
+點擊按鈕後，Cloudflare 會自動 Fork 此 repo 並完成代碼部署。

 部署完成後，還需在控制台完成以下配置：

-**1. 設定 AUTH_KEY**
+**1. 綁定 KV Namespace**
+
+Cloudflare 控制台 → Workers & Pages → `ni-mail` → Settings → Bindings → 新增 KV Namespace：
+- 名稱：`MAIL_KV`
+- 選擇已建立的 KV namespace（若尚未建立，先到 Workers & Pages → KV → Create namespace）
+
+**2. 設定 AUTH_KEY**

 Settings → Variables and Secrets → 新增：
-
 - 類型：**Secret（密鑰）**，不要選 Text（明文可見）
 - 變數名稱：`AUTH_KEY`
 - 值：自訂一個密碼

 儲存後點 **Deploy** 讓設定生效。

-**2. 設定可收信域名**
-
-在 `wrangler.jsonc` 中設定你的域名：
-
-```jsonc
-{
-  "vars": {
-    "DOMAINS": "example.com,example.net"
-  }
-}
-```
-
-公開模板預設留空，方便任何 Cloudflare 帳號先完成第一次部署。
-
 **3. 設定 Email Routing**

 Cloudflare 控制台 → 你的域名 → Email → Email Routing → Routing rules → Catch-all：
-
 - Action：Send to Worker
 - 選擇 `ni-mail`

-**4. （可選）啟用發信功能**
-
-若你需要使用發信 / 回覆 / 轉發接口，請為 Worker 新增一個名為 `EMAIL` 的 `send_email` binding。
-
-未配置 `EMAIL` binding 時，收信和讀信 API 仍可正常工作，只是發信接口會回 `501`。
-
 ---

 ### 方式二：本地 CLI 部署

 ```bash
-git clone https://github.com/<YOUR_USERNAME>/<YOUR_REPO>.git
+git clone https://github.com/mskatoni/ni-mail.git
 cd ni-mail
-npm ci
-npm run check:deploy
-npm exec -- wrangler secret put AUTH_KEY
-npm run deploy
+npm install
+
+# 建立 KV Namespace
+wrangler kv:namespace create MAIL_KV
 ```

-如果你是本地部署，通常只需要：
+複製輸出的 ID，在 Cloudflare 控制台綁定，或直接加進 `wrangler.toml`：

-1. 修改 `wrangler.jsonc` 中的：
-   - `name`
-   - `vars.DOMAINS`
-   - `r2_buckets[*].bucket_name`
-2. 在 Cloudflare 後台設置 `AUTH_KEY`
-3. 配置 Email Routing 的 Send to Worker 規則
+```toml
+[[kv_namespaces]]
+binding = "MAIL_KV"
+id = "你的 KV ID"
+```
+
+```bash
+wrangler deploy
+```

 ## 自定義域名（可選）

 > 域名必須已托管在 Cloudflare，無需手動建立 DNS 記錄，Cloudflare 會自動處理並簽發 SSL。

-首次部署成功後，可以在 Cloudflare 控制台為 Worker 添加 Custom Domain。
+在 `wrangler.toml` 中取消注釋，支持多個：

-如需用 Wrangler 管理，在 `wrangler.jsonc` 中添加你自己的域名：
+```toml
+[[routes]]
+pattern = "mail.domain-a.com"
+custom_domain = true

-```jsonc
-{
-  "routes": [
-    {
-      "pattern": "mail.example.com",
-      "custom_domain": true
-    }
-  ]
-}
+[[routes]]
+pattern = "mail.domain-b.com"
+custom_domain = true
 ```

-不要把不屬於部署者 Cloudflare 帳號的域名提交到公開模板中。
+重新部署後即可通過自定義域名訪問 API。多個域名收到的郵件共用同一個 inbox，`to` 欄位可用於區分來源域名。

 ## API

 所有請求需帶上 Header：`X-Auth-Key: 你的密碼`

-### 與原版兼容的路由
-
 | 方法 | 路徑 | 說明 |
 |---|---|---|
-| GET | `/latest?mailbox=user@example.com` | 取得最新一封完整郵件 |
-| GET | `/mails?mailbox=user@example.com&limit=10` | 取得最近 N 封郵件列表（不含正文） |
-| GET | `/mail/:id?mailbox=user@example.com` | 取得單封完整郵件（含 html/text） |
-| DELETE | `/mails?mailbox=user@example.com&folder=inbox` | 清空收件匣 |
-
-### 新增路由
-
-| 方法 | 路徑 | 說明 |
-|---|---|---|
-| GET | `/api/mailboxes/:mailboxId/latest` | 讀取指定 mailbox 最新郵件 |
-| GET | `/api/mailboxes/:mailboxId/emails` | 列表 / 搜索 / 排序 |
-| GET | `/api/mailboxes/:mailboxId/emails/:id` | 讀取單封郵件 |
-| POST | `/api/mailboxes/:mailboxId/emails/:id/read` | 標記已讀 |
-| GET | `/api/mailboxes/:mailboxId/threads/:threadId` | 讀取整個 thread |
-| GET | `/api/attachments/:attachmentId?mailbox=user@example.com` | 下載附件 |
-| POST | `/api/mailboxes/:mailboxId/send` | 發新郵件（需 `EMAIL` binding） |
-| POST | `/api/mailboxes/:mailboxId/reply` | 回覆郵件（需 `EMAIL` binding） |
-| POST | `/api/mailboxes/:mailboxId/forward` | 轉發郵件（需 `EMAIL` binding） |
+| GET | `/latest` | 取得最新一封完整郵件 |
+| GET | `/mails?limit=10` | 取得最近 N 封郵件列表（不含正文） |
+| GET | `/mail/:id` | 取得單封完整郵件（含 html/text） |
+| DELETE | `/mails` | 清空收件匣 |

 **範例**

 ```bash
-curl "https://your-worker.workers.dev/latest?mailbox=user@example.com" \
+curl https://your-worker.workers.dev/latest \
  -H "X-Auth-Key: 你的密碼"
 ```

+**成功回應（有郵件）**
+
+```json
+{
+  "id": "7eb63a8d-1195-4124-9eb3-fb4c2673e90c",
+  "receivedAt": "2026-03-22T10:28:01.506Z",
+  "from": "[email protected]",
+  "to": "[email protected]",
+  "subject": "beta",
+  "text": "beta\n\n",
+  "html": "<div dir=\"ltr\">beta</div>\n\n",
+  "attachments": []
+}
+```
+
 **無郵件時（HTTP 404）**

 ```json
@@ -184,28 +154,19 @@ curl "https://your-worker.workers.dev/latest?mailbox=user@example.com" \
 { "error": "unauthorized" }
 ```

-**未配置發信 binding 而調用發信接口時（HTTP 501）**
-
-```json
-{ "error": "outbound email is not configured; add an EMAIL send_email binding after deployment" }
-```
-
 ## 常見問題

 ### error code: 1101

-Worker 運行時拋出未捕獲異常，常見原因包括：
+Worker 運行時拋出未捕獲異常，最常見原因是 **KV Namespace 沒有正確綁定**。

- `AUTH_KEY` 沒有設置
- Email Routing 沒有正確指到這個 Worker
- `DOMAINS` 沒有包含當前 mailbox 的域名
- R2 / Durable Object 綁定不完整
+確認步驟：控制台 → Workers & Pages → `ni-mail` → Settings → Bindings，確認有一條：

-先確認：
+| 類型 | 名稱 | 值 |
+|---|---|---|
+| KV Namespace | `MAIL_KV` | 你建立的 namespace |

- Worker 已成功部署
- `wrangler.jsonc` 中的 `MAILBOX` 與 `BUCKET` binding 存在
- 控制台裡 `AUTH_KEY` 已設為 Secret
+如果是空的，重新新增並點 **Save** 後重新部署即可。

 ### AUTH_KEY 建議使用 Secret 而非 Text

@@ -214,6 +175,15 @@ Settings → Variables and Secrets 新增 `AUTH_KEY` 時，類型請選 **Secret
 - **Secret**：值加密儲存，部署後不可見，適合密碼類資訊
 - **Text**：明文儲存，任何有控制台權限的人都能看到

+## Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=mskatoni/ni-mail&type=Date)](https://star-history.com/#mskatoni/ni-mail&Date)
+
+## 社區
+
+<a href="https://v2ex.com"><img src="https://user-images.githubusercontent.com/80169337/122051970-cd075b80-ce02-11eb-9653-0b8702377727.png" width="24" height="24" alt="V2EX" /></a>&nbsp;
+<a href="https://www.nodeseek.com/post-659586-1"><img src="https://github.com/user-attachments/assets/0c6db696-769c-4d79-997c-9bc014cc6895" width="24" height="24" alt="NodeSeek" /></a>&nbsp;
+
 ## License

 Apache License 2.0