替一個 Zeabur 上的 repo 加寄信 API， 而且 repo 裡一把金鑰都不放

發生了什麼

最近我在整理本站的自我盤點頁，想加一個「寄一份結果給我」的按鈕：讀者勾完 26 題，填 email，收到一封有 ✓／✗ 和原因的信。功能本身很小，但它牽涉三件我們在三起事件裡都付過學費的事：憑證放哪裡、誰能呼叫、被濫用時誰先知道。這篇文章我就把整段流程走一遍，順便講清楚每一步為什麼這樣做。

第一步：應用端不碰 SMTP

我們內部有一個寄信閘道，是一支獨立的小服務，只有它持有 Google 的應用程式密碼。應用端要寄信，是對閘道發一個 HTTP 請求，帶兩個標頭表明「我是誰」，body 是收件人、主旨、HTML 內容、寄件者顯示名稱、頁尾圖與連結。

這樣做的好處在憑證的存在形式：應用端的 repo 與環境變數裡沒有任何 SMTP 密碼，只有一組寄件代號。代號外洩，最壞的情況是有人冒用我們的名義寄信，而且閘道的 log 會標出是哪個代號寄的；SMTP 密碼外洩，最壞的情況是整個信箱被接管。

寄件代號每個應用一組，不共用。本站用自己的代號，會計系統用它自己的。閘道靠代號分辨來源，共用代號等於把 log 弄瞎。

第二步：兩個路由，兩種閘門

| 路由 | 誰能呼叫 | 內容 | 限流 | |---|---|---|---| | POST /api/mail/send | 帶 X-Mail-Token 的內部工具與 agent | 自訂收件人、主旨、HTML | 每 IP 每小時 60 封 | | POST /api/mail/checklist | 任何人 | 固定格式的盤點結果，只寄給填寫者填的那一個信箱 | 每 IP 每小時 5 封、每信箱 3 封 |

第一個路由沒有 token 一律 401，token 是 32 字元以上的隨機值，只存在部署平台的環境變數與本機的 .env.local（已 gitignore）。第二個路由是公開的，所以它不接受任何自訂內容：主旨、內文、頁尾都由伺服器組，使用者能決定的只有「寄到哪個信箱」，而且一小時最多三次。

const senderK  = clean(process.env.UPMAIL_SENDER_K);   // 寄件代號
const senderV  = clean(process.env.UPMAIL_SENDER_V);   // 代號對應的驗證值
if (!senderK || !senderV) throw new Error("尚未設定寄送服務");
// 收件人最多 10 個、主旨 200 字、內容 200KB；超過就 400，不進閘道

第三步：環境變數用單鍵寫，先快照再比對

這一步是整篇最重要的坑。8 月底我們在另一個專案用 CLI 的 variable update -k KEY=VALUE 改一個密碼，結果兩個服務的所有環境變數被清空，連指定的那個 key 都沒留下。原因是那個指令底層是「用這組資料取代整組變數」，主控台又沒有變數歷史可回復。

所以現在改變數一律走平台的單鍵 API（建立、更新、刪除各一個 mutation），流程固定三拍：

• 先把該服務全部變數讀出來存成快照檔
• 逐鍵寫入，已存在就單鍵更新、不存在就單鍵建立
• 寫完再讀一次，比對 key 數量沒少、新值讀回一致

我們把這段寫成腳本，這次替本站寫入 8 個變數（閘道位址、寄件代號與驗證值、頁尾圖、頁尾連結、寄件者名稱、API token、站台網址），讀回 16 個，原本的 8 個一個沒少。

snapshot: …/blog-20260917-212524.json (16 variables)
UPMAIL_SENDER_K: updated
verified: 16 -> 16 variables, none lost; MAIL_API_TOKEN …6bb6a
NOTE: redeploy the service for new variables to take effect

第四步：頁尾圖放共用雲端硬碟，走無金鑰代理上傳

信件頁尾要一張圖，圖要有一個「任何人有連結可讀」的網址。我們不想為了一張圖在 repo 放 Google 金鑰，所以走另一支無金鑰的 Drive 代理上傳到共用雲端硬碟。

這裡踩到兩個坑：新的服務帳戶沒有個人雲端硬碟的儲存配額，只能傳到共用雲端硬碟；而共用雲端硬碟預設不允許非成員存取，代理的服務帳戶設不了「任何人可讀」，最後要用自己的帳號補一筆權限。過渡期先沿用另一個專案的頁尾圖，功能不受影響。

第五步：curl 測試，三種錯誤各代表什麼

curl -sS -X POST "https://<你的網域>/api/mail/send" \
-H "Content-Type: application/json" -H "X-Mail-Token: ***" \
-d '{"to":"[email protected]","subject":"測試","content":"<p>hello</p>"}'
# 200 {"success":true}  → 閘道憑證、token、路由都正常
# 401                    → token 不一致（本機 .env.local 與平台不同）
# 404                    → 服務還沒重新部署帶新路由
# 502                    → 閘道拒絕：寄件代號或驗證值錯

本機用 .env.local 起站測，第一封信 200；沒帶 token 401；正式網域 404，因為線上還是舊 build。這個 404 是預期中的：環境變數要重新部署才生效，程式碼也要。

1. 2026-08-29
   CLI 改單一變數，清空兩個服務全部環境變數
   事故紀錄；主控台手動補回 23 個變數。
2. 2026-09-17 21:0x
   寫 lib/mail.ts 與兩個路由，本機測試 200／401
   本站 commit 與 curl 輸出。
3. 2026-09-17 21:1x
   單鍵寫入 8 個變數，讀回 16 個無遺失
   腳本比對輸出。
4. 2026-09-17 21:5x
   頁尾圖上傳共用雲端硬碟成功，但設不了公開權限
   代理回應 public:false。

這次外洩了什麼

證據等級

跟我們的防暴筆記對照

Crusader 防暴筆記裡那支殭屍網路掃的 542 條路徑，前幾名就是 .env、.git、各種設定檔，目標是 AWS 金鑰、SMTP 憑證、Google 金鑰。這篇的整個設計就是讓那份掃描清單在我們這裡一無所獲：repo 裡沒有密碼、應用端沒有 SMTP、頁尾圖上傳沒有 Google 金鑰。剩下的兩個明文變數（寄件代號、API token）外洩時損害有上限、有 log、能單鍵輪替。

攻擊者 vs 防守者

這篇提到的項目要花多少錢

重點學習

今天就可以來試試