STRANGLER.md
P3 — 後端 Rust strangler(接力筆記)
把 Rust(axum + sqlx)擺在 Express 前面當前置代理,端點逐個搬、其餘原樣 proxy 回 Express。 動機=正確性 + 技術棧一致 + 爽,不是效能(blog 非效能瓶頸)。 計畫全文:
web-ssg-poc/MIGRATION_PLAN.mdPhase 3。
架構
┌─────────────────────────────────────────┐
nginx /api/ ──►│ Rust (axum, :3002) │
│ ├─ 已接管端點 → sqlx → sqlite │
│ └─ fallback → reqwest 代理 → Express │──► Express (:3001)
└─────────────────────────────────────────┘ │
共用同一個 sqlite(WAL)◄───────────┘
- 🚀 已上線(2026-07-14):
nginx /api/ → Rust:3002。指紋確認(接管端點無 X-Powered-By、 未接管經 proxy 有)、/uploads//rss 完好、線上 body byte-identical、瀏覽器煙測 0 error。 rollback:sites-available/koimsurai.bak-enabled-20260714還原 + reload。 ⚠️ 坑:sites-enabled/koimsurai曾是實體檔非 symlink(與 available 漂移),已收斂回 symlink。 ⚠️ 更正:enabled 版有location = /rss → Express——線上 RSS 一直是活的(先前「前端 404」判斷 是直打 13588 所測,經 nginx 不同)。/rss為 app-level 路由,退役 Express 前要遷。 - 切換方式:把 nginx
location /api/的proxy_pass從:3001改成:3002,reload。 Rust 沒接管的全部 fallback 回 Express,行為不變;接管的走 sqlx。可隨時 revert。 - DB 共用:Rust 與 Express 開同一個 sqlite。
/etc/.../web_backend-db-datavolume 掛到/usr/src/app/db/db.sqlite。Rust 容器化後要掛同一個 named volume。 - DB 並發(已決策):單寫者-per-域(非真雙寫)。任一張表同時只有一個 process 寫、
讀可重疊(WAL 罩);兩邊都設
busy_timeout(Rust 端已設 5s)。schema migration 歸 Express 一邊,避免 schema 雙頭。/api/tags是純讀,零寫入競爭。
已接管端點(120 條,全部 byte-identical 對拍 + 指紋確認真接管)
| # | 端點 | handler | 驗證 |
|---|---|---|---|
| 1 | GET /api/tags |
handlers/tags.rs |
byte-identical |
| 2 | GET /api/categories |
handlers/categories.rs |
byte-identical |
| 3 | GET /api/series |
handlers/series.rs |
byte-identical(回應無 message 欄位) |
| 4 | GET /api/series/:name |
handlers/series.rs |
byte-identical |
| 5 | GET /api/stats |
handlers/stats.rs |
byte-identical(days 複製 JS 日期數學) |
| 6 | GET /api/thoughts |
handlers/thoughts.rs |
byte-identical(limit/offset 夾擠、t.* 顯式欄位、edited→bool、ref→parsed JSON) |
| 7 | GET /api/thoughts/:id |
handlers/thoughts.rs |
byte-identical + 404 {"error":"not found"} 一致 |
| 8 | GET /api/posts |
handlers/posts.rs |
byte-identical:分頁/搜尋/tag/category 過濾/sortBy/多語(?lang=) 全矩陣對拍 |
| 9 | GET /api/posts/:id |
handlers/posts.rs |
byte-identical:多語 + 2 種 404(找不到 / 該語無內容) |
| 10 | GET /api/posts/:id/reactions |
handlers/posts.rs |
byte-identical(空集合;型別 trivial) |
| 11 | GET /api/posts/:id/comments |
handlers/posts.rs |
byte-identical:post 17 真實留言驗 14 欄 row 解碼 |
| 12 | GET /api/thoughts/:id/comments |
handlers/thoughts.rs |
byte-identical(重用 posts::CommentRow,post_id 改 Option 容 thought 留言的 NULL) |
| 13 | GET /api/home/digest |
handlers/home.rs |
byte-identical(純 DB;Express 60s 快取→資料同步時一致) |
| 14 | GET /api/admin/tags |
handlers/admin.rs |
第一個 authed:requireAdmin JWT 對拍,兩種 token 分支 + 各種錯誤全 byte-identical |
| 15 | GET /api/admin/categories |
handlers/admin.rs |
requireAdmin;裸陣列(含 created_at、JOIN 不過濾 status) |
| 16 | GET /api/admin/users |
handlers/admin.rs |
requireOwner;{users}。USER token→403「需要擁有者權限」、OWNER→200 全對 |
| 17 | GET /api/admin/blacklist |
handlers/admin.rs |
requireAdmin;{blacklist}(空表,型別 trivial) |
| 18 | GET /api/admin/keyword-filters |
handlers/admin.rs |
requireAdmin;{filters}(空表,型別 trivial) |
| 19 | POST /api/auth/login |
handlers/auth.rs |
bcrypt 驗 + 簽 7d JWT;錯誤路徑對拍、bcrypt $2a/$2b/$2y 相容、token 與 live Express 互通 |
| 20 | GET /api/auth/me |
handlers/auth.rs |
token 兩分支(OAuth→查 oauth_users+linked 解析 / legacy→admin 物件);錯誤用 {error} key |
| 21 | POST /api/auth/logout |
handlers/auth.rs |
{message:"ok"} |
| 22 | GET /api/auth/providers |
handlers/auth.rs |
OAuth clientId/enabled(讀 env GOOGLE_CLIENT_ID/GITHUB_CLIENT_ID) |
| 23 | GET /api/admin/posts |
handlers/admin.rs |
分頁;動態 row→JSON(p.* 全欄位 spread)+ tags/excerpt 覆寫(excerpt 用 UTF-16 substring) |
| 24 | GET /api/admin/comments |
handlers/admin.rs |
分頁;動態 row→JSON(c.*+post_title)+ status counts |
| 25 | POST /api/posts/:id/view |
handlers/posts.rs |
view_count+1(首個寫入) |
| 26 | POST /api/posts/:id/like |
handlers/posts.rs |
likes+1 → 回新 likes |
| 27 | POST /api/posts/:id/unlike |
handlers/posts.rs |
likes-1(限 >0) |
| 28 | POST /api/posts/:id/reactions |
handlers/posts.rs |
emoji upsert(clamp 0;ALLOWED 6 emoji) |
| 29 | POST /api/comments/:id/like |
handlers/posts.rs |
comments.likes+1 |
| 30 | POST /api/thoughts/:id/react |
handlers/thoughts.rs |
讚/倒讚 prev→next 差值(clamp 0) |
| 31 | POST /api/posts/:id/comments |
handlers/comments.rs |
createComment:author/content 必填→OAuth 偵測→captcha→IP 黑名單→關鍵字(reject/spam)→審核狀態→INSERT |
| 32 | POST /api/thoughts/:id/comments |
handlers/comments.rs |
同 createComment(target=thought_id)⚠️ 見下方 broken-path |
| 33-35 | POST/PUT/DELETE /api/admin/tags[/:id] |
handlers/admin.rs |
tag CRUD(UNIQUE→409、404、post_tags 先刪) |
| 36-38 | POST/PUT/DELETE /api/admin/categories[/:id] |
handlers/admin.rs |
category CRUD(gen_slug 複製 JS 正則、改名同步 posts.category、刪除 set NULL) |
| 39-40 | POST/DELETE /api/admin/blacklist[/:id] |
handlers/admin.rs |
IP 黑名單(INSERT OR IGNORE) |
| 41-42 | POST/DELETE /api/admin/keyword-filters[/:id] |
handlers/admin.rs |
關鍵字過濾(action 驗證預設 spam;Rust 不快取→天然等價 Express 的 invalidate) |
| 43 | PATCH /api/admin/comments/:id/status |
handlers/admin.rs |
審核狀態(validStatuses;404) |
| 44 | PUT /api/admin/comments/:id |
handlers/admin.rs |
改留言內容 |
| 45 | DELETE /api/admin/comments/:id |
handlers/admin.rs |
永久刪除 |
| 46 | POST /api/admin/comments/:id/reply |
handlers/admin.rs |
站長回覆(is_admin=1, author='站長', status=approved) |
| 47 | POST /api/admin/thoughts |
handlers/thoughts.rs |
建碎念:refUrl→unfurl(regex 抽 og meta)、ref media→TMDb enrich、ref 直接覆寫 |
| 48 | PUT /api/admin/thoughts/:id |
handlers/thoughts.rs |
編輯(edited=1);clearRef/direct ref(不 enrich)/refUrl 變更才重 unfurl |
| 49 | DELETE /api/admin/thoughts/:id |
handlers/thoughts.rs |
連同留言刪;Express 不回 404(刪 0 列也 success),照抄 |
| 50 | GET /api/admin/posts/:id |
handlers/admin.rs |
編輯器用:動態 row→JSON spread + source_language 覆寫 + available_locales + tags |
| 51 | POST /api/admin/posts |
handlers/admin.rs |
建文:23 欄 INSERT(i18n×12/series/allow_comments)+ manageTags |
| 52 | PUT /api/admin/posts/:id |
handlers/admin.rs |
COALESCE/CASE-flag 語意逐字照抄;⚠️category=? 無 COALESCE(缺 key 也清 NULL)、tags 缺→清空關聯(Express 原樣) |
| 53 | DELETE /api/admin/posts/:id |
handlers/admin.rs |
先清 post_tags 再刪;{message:"文章已刪除",deleted} |
| 54-60 | books 域:GET /books GET/PUT/DELETE /books/:id POST /books GET /books/stats/summary GET /admin/books |
handlers/books.rs |
公開讀 {message,books}/admin 裸陣列;15 欄 COALESCE PUT;stats 的 average_rating(truthy→toFixed(1)→parseFloat) |
| 61-65 | collection 域:GET /collection/:type POST /collection PUT/DELETE /collection/:id POST /collection/search-external |
handlers/collection.rs |
動態欄位 INSERT/UPDATE(欄名來自 body key,照抄);search-external=501 stub 照抄 |
| 66-70 | posts 寫(/posts 路徑,requireAdmin):POST /posts PUT/DELETE /posts/:id PATCH /posts/:id/status + POST /posts/legacy(basicAuth) |
handlers/posts.rs |
簡版建/改文(無 i18n;錯誤回 400 非 500);legacy 帶 WWW-Authenticate 的 Basic auth |
| 71-74 | newsletter:POST /newsletter/{subscribe,unsubscribe} GET /newsletter/by-token/:token GET /newsletter/subscribers(admin) |
handlers/newsletter.rs |
訂閱/退訂/重新啟用/token 查詢/分頁列表;token=crypto.randomBytes(16).hex 等價(rand 32 hex) |
| 75 | POST /api/auth/reset-admin |
handlers/auth.rs |
開發用密碼重置(bcrypt::hash cost10);⚠️ 見下方安全備註 |
| 76-77 | GET /github/{user,events}/:username |
handlers/thirdparty.rs |
純代理/token+enrich PushEvent commits(⚠️ 見 bug #4:Rust 修好了 Express 的亂碼) |
| 78-80 | GET /wakatime/{today,week,projects} |
handlers/thirdparty.rs |
Basic base64(key);today=summaries+durations 並行合併 actualCodingTime(JS toISOString 毫秒版) |
| 81-84 | GET /steam/{player,recent-games,owned-games,achievements/:appid} |
handlers/thirdparty.rs |
https.get 式純代理(不看上游狀態碼、parse 後回 200,照抄) |
| 85 | GET /books/search/external |
handlers/thirdparty.rs |
Google Books→OpenLibrary fallback;cover upgrade(JS replace=首次出現);encodeURIComponent 等價 |
| 86-92 | spotify×7:GET /spotify/{login,recently-played,now-playing,top-genres,top-tracks,audio-features,me} |
handlers/spotify.rs |
首批 in-process 狀態:token 快取(提前 1min 過期)、top-* 6h/1h 快取、403/429 熔斷 1h、audio-features per-track 24h 快取+優雅降級 |
| 93 | GET /steam/profile |
handlers/thirdparty.rs |
SWR 快取:30min 過期背景重抓(tokio spawn+try_lock dedup)、失敗 backoff 5min 保留舊快取、首抓持鎖去重;miniprofile HTML 4 regex 解析((?!_frame) lookahead 因後接 \s+ 恆真、等價移除) |
| 94-97 | watch 公開讀:GET /anime/history /films/recent /tv/recent /watch/stats |
handlers/watch.rs |
limit 的 parseInt→Math.min(NaN→LIMIT NULL 照抄);NULLS LAST;stats 物件 spread 順序 |
| 98-101 | GET/POST /watch/favorites PUT/DELETE /watch/favorites/:id |
handlers/watch.rs |
TMDb 在地化(per kind:id:lang 快取無 TTL)+DB 快照 fallback;Cache-Control: no-store;rating Math.max(1,Math.min(5,ToNumber));quote UTF-16 slice 280;無 404(照抄) |
| 102 | GET /watch/tmdb-search |
handlers/watch.rs |
admin;fetch 不看狀態碼直接 parse(照抄) |
| 103 | GET /watch/now |
handlers/watch.rs |
純讀記憶體 state。 |
| 104 | POST /admin/watch/now |
handlers/watch.rs |
heartbeat:bahamutPushAuth(X-Bahamut-Token constant-time ∥ admin JWT);videoSn 反查 anime_history enrich;同片保留 startedAt;90s TTL |
| 105 | GET /admin/bahamut/status |
handlers/bahamut.rs |
anigamer crate;bahamutPushAuth;純讀記憶體 jar+解碼 BAHARUNE。對live Express byte-identical(push-token / admin-JWT 兩路徑 + 401 拒絕全一致) |
| 106 | POST /admin/bahamut/cookie |
handlers/bahamut.rs |
cookie 熱抽換(set_cookies 內部短鎖,非換 client)+ 觸發 sync_bahamut_history。對 live-db 副本跑真 session:回應形狀一致、upsert 冪等(879 entries / 0 new / 0 covers)、997 列 title/cover/episode 零差異、enrich 47 填 0 退,剩 3 個 TVSP/劇場版 TMDb 本就無 TV 對應(與 Express 同) |
| 107 | POST /admin/posts/:id/generate-zh-cn |
handlers/opencc.rs |
opencc 硬骨頭;requireAdmin;ferrous-opencc Tw2s(純 Rust、內建字典、免 libopencc)繁台→簡。對 opencc-js {from:tw,to:cn} byte-identical(11 真實文章全欄 + 33 欄位 + 20 對抗案例含 著作/著手 語境消歧);DB 寫 zh_cn 三欄+updated_at;404/400×2/401 全對拍 |
| 108 | GET /api/thoughts/rss |
handlers/thoughts.rs |
XML 硬骨頭;碎念 RSS(最新 30)。移植 esc(&<>)、content.slice(0,60)(UTF-16)、ref desc(link/media)、new Date().toUTCString()(自寫 days_from_civil+星期)。對 express-test 對抗 fixture byte-identical(4442B):&<>轉義(內文/標題/URL)、emoji surrogate 截斷、剛好60字、link/media/壞JSON/空title、全 7 星期 |
| 109 | GET /api/admin/stats |
handlers/admin.rs |
requireAdmin;文章/留言 count + visitors=Math.floor(random*1000)+1000([1000,1999],不可 byte 對拍)。對 express-test 除 visitors 外 byte-identical(key 序 + 確定性欄位),visitors 兩邊皆 ∈[1000,1999];401 對拍 |
| 110 | POST /api/sync/collection |
handlers/collection.rs |
n8n 批次匯入 collection_items(x-api-key)。Rust 已是該表寫者→併入單寫者。happy-path 回應 byte-identical、寫入列內容一致(|| 預設:year:0/rating:0→NULL、缺 source→n8n_import、缺 status→completed、is_favorite→1/0)、403/400×2 錯誤 byte-identical |
| 111 | POST /api/admin/posts/:id/send-newsletter |
handlers/mailer.rs |
resend 硬骨頭;reqwest 直打 Resend batch API(emails/batch)。移植 mailer.js HTML/text/subject 模板 + List-Unsubscribe headers。驗證=只組請求不真寄:兩邊 RESEND_BASE_URL 指本地 mock 容器→比對實際 wire body byte-identical(13390B)(含 escapeHtml 5 連轉義、excerpt slice(320)+省略號、named/unnamed greeting、encodeURIComponent token、per-email key 序 from/headers/html/subject/text/to)。response(dispatched/no-subscribers)+404/400/401 全 byte-identical。⚠️ 見 bug #6 |
| 112 | GET /api/gallery/photos |
handlers/gallery.rs |
讀 manifest.json 回傳(零 sharp)。byte-identical(245KB)——揪出 serde_json 預設浮點解析有損(差 1 ULP)→ 開 float_roundtrip feature 對齊 V8 |
| 113 | GET /api/image-proxy |
handlers/gallery.rs |
純串流代理(零 sharp;axios pipe → reqwest bytes_stream)。body byte-identical + CORS/Cache headers + 400/500 分支全對拍 |
| 114 | GET /api/og/:id.png |
handlers/og.rs |
sharp 硬骨頭:SVG 模板(_wrapTitle JS 混合語意=code point 迭代+UTF-16 計數,7 case node 真值單元測試)→ resvg 光柵化。ETag byte-identical、headers/304/404 全對拍、PNG 1200×630 視覺等價(省略號 glyph 字型 fallback 微差)。axum 不支援 :id.png → :file+strip 後綴、非 .png 轉 proxy |
| 115 | POST /api/admin/upload |
handlers/upload.rs |
multer→axum multipart(⚠️ Multipart 不能當參數 extractor,否則 401 順序反了)。檔案落地 bytes=原檔、YYYY/MM/ts-rand 檔名、thumbhash 實測 2/5 byte 相同、3/5 差 ≤2 字元(±1 量化係數,解碼視覺零差異)、txt→null、400/401 對拍 |
| 116 | POST /api/admin/gallery/sync |
handlers/gallery.rs |
sharp 域最大塊:掃描(@eaDir 等目錄排除)→ EXIF orientation rotate → resize 1920/400 → lossy webp q85/80(webp crate=libwebp vendored)→ exifr 9 欄抽取 → manifest。manifest 除 size 外全一致(exif 物件/aspectRatio 浮點/key 序/shootTime);webp 尺寸 3/4 同、1 張差 1px(vips 兩步縮放捨入);視覺 mean diff 1%;skip 冪等/409 guard/401 對拍 |
| 117-118 | POST /api/auth/{google,github}/callback |
handlers/oauth.rs |
OAuth 硬骨頭(底線=不壞現有 user)。upsertOAuthUser 8 分支逐字照抄。驗證:①原函數 node 腳本 vs Rust mock provider 全流程,7 case 輸入矩陣 resolve 值+DB 終態(5 列含 linked_to/OWNER 升級)完全一致——順帶證實 email 關聯大小寫敏感(Express 既有行為)②Rust 簽 30d JWT 對 live /auth/me 驗簽通過③Missing code 400 對 live byte-identical。github 特有:無 email→/user/emails primary、displayName=name||login。provider URL 可 env 覆寫(僅測試;prod 預設同 Express 寫死)。spotify/callback 留 proxy |
| 119 | PUT /api/admin/users/:id/role |
handlers/admin.rs |
全路由差集盤點揪出的漏網。requireOwner;validRoles/「不能改自己」(AdminUser 加 db_user_id:OAuth=主帳號 id、legacy=None 跳過檢查=Express dbUser 語意)。6 分支(400×2/200×2/404/403)byte-identical + DB 終態一致 |
| 120 | GET /api/health |
handlers/home.rs |
純文字 OK,byte-identical |
watch 域要點:
- bahamut cron 同步刻意留在 Express——單寫者原則:
anime_history寫者=Express cron,Rust 只讀;watch_favorites寫者切為 Rust HTTP。/admin/bahamut/*留 proxy(anigamer 輪)。 (film/tv_history原本的寫者是 Trakt 同步,已移除;現在的寫者是 Rust 的 Simkl worker。)GET /watch/now與POST /admin/watch/now成對接管(now-watching 狀態在記憶體,拆開會狀態分裂)。- Trakt token file:Rust 端
TRAKT_TOKEN_FILEenv(預設 DATABASE_URL 同目錄.trakt-token.json)。 兩邊都「每次讀檔、<7 天才 refresh 寫回」→ 與 Express cron 相容(它也每次重讀檔);併發 refresh race 兩邊本就存在、機率極低(90 天 token)。部署時 Rust 容器要掛同一個 db volume(token/cookie 檔在裡面)。- A/B 全綠(favorites 寫入後兩邊 DB 完全一致、now-watching 全生命週期、Trakt poll null、401)。
🔄 cron 遷移 + ⚠️ Express bug #5:Trakt token 自毀設計(2026-07-10)
- Trakt 歷史同步已移植 Rust(
handlers/watch.rs::spawn_trakt_sync,90s 首跑+6h 週期):ENABLE_TRAKT_SYNC=1才啟動(預設關)。單寫者切換流程:切換上線時 Express 設DISABLE_WATCH_CRON=1(watch.js 已加 kill-switch,inert 直到設 env)+ Rust 設ENABLE_TRAKT_SYNC=1。 bahamut sync 仍在 Express(等 anigamer crate,硬骨頭輪)。 - ⚠️ bug #5(live 事故,2026-06-29 起):Trakt 現在發 7 天壽命 token,Express 的「剩 <7 天就
refresh」門檻 ≥ 壽命 → 每次 getValidTraktToken 都 refresh;refresh token 是一次性的、Express
無鎖——cron 與 /watch/now 輪詢併發搶刷 → race 斷鏈 →
invalid_grant永久死。live log 自 6/29 起 全是 invalid_grant + 429(rate limit)=Trakt 同步與 trakt now-watching 已停擺,需scripts/trakt-device-auth.js重新授權。 - Rust deviation(修法,非照抄):① refresh 門檻 =
min(7d, token 壽命/2)(90d token 行為同 Express;7d token 前 3.5 天直接用不 refresh)② refresh 全程 tokio Mutex 串行 + 進鎖 double-check 重讀檔。Express 端同等修法待使用者裁示(動 live 行為)。 - harness 鐵則(新增):絕不把真實 Trakt token 檔放進 fixture——fixture 端 refresh 成功會 消耗一次性 refresh token、把 live 弄死。本次事故是 live 自己先死的(log 佐證),但此風險真實存在。 Rust sync 的完整等價驗證推遲到重新授權後(且只在不觸發 refresh 的窗口內測)。
🦀 硬骨頭 1/N:anigamer Rust crate(2026-07-10)
Server/anigamer-rs(獨立 crate、git init、可發 crates.io)——移植 TS SDKServer/anigamer: cookies(parse/serialize/merge-Set-Cookie 含刪除語意/validate)、jwt(BAHARUNE payload 解碼+到期)、 errors(BahamutApiError+ NO_LOGIN 偵測)、http(bahamut_get(_json) + cookie rotation callback)、 endpoints(history 分頁去重 + animeRef og:image 抓取,extract_meta 手寫掃描免 regex)、client(AniGamer)。- 測試 1:1 移植 TS 套件:cookies 20 + jwt 6 + extract_meta 3 =
cargo test全綠(29 測試)。 - 差異記錄:CookieJar 用
IndexMap(保序 round-trip);cookie 手動管理(非 reqwest cookie store, 才能觸發 rotation callback + 磁碟持久化);HTTP date 解析手寫(只需判過去/未來)。 - ✅ 已整合進 server-rs(2026-07-10):path 依賴
anigamer = { path = "../../anigamer-rs" }; AppState 放Arc<BahamutState>{ client: Arc<AniGamer>, sync_lock: tokio::Mutex, last_jwt_alert_at: AtomicI64, cookie_file }——不套外層 Arc(使用者「不能無腦 Arc」):AniGamer 內部已是Mutex<CookieJar>、方法全&self、鎖不跨 await;cookie 熱抽換用set_cookies(&self, jar)換內容即可, 無需 ArcSwap。handlers/bahamut.rs:status/cookie端點 +sync_bahamut_history+spawn_syncworker(ENABLE_BAHAMUT_SYNC=1才啟;預設 Express cron 仍為寫者)。移植 helpers:notify_discord/maybe_alert_discord(24h 節流 AtomicI64)/check_bahamut_jwt_expiry/simplify_anime_title(regex) /tmdb_search_tv_id/enrich_null_anime;push_auth(constant-time X-Bahamut-Token ∥ require_admin)。 - 真 session 端到端驗證:使用者重抓 cookie(BAHARUNE 7/24 到期)→ status 對 live Express byte-identical; cookie→sync 對 live-db 副本跑:879 entries / 0 new / 0 covers(冪等)、997 列內容零差異、enrich 收斂 (47 填、0 退、剩 TVSP/劇場版本就無 TV 對應且 ⊆ live-null)。詳見端點表 #105-106。
- ⚠️ docker build context:anigamer-rs 在 server-rs 之外,path dep 跨 context → 部署需 workspace 或 vendoring(P4 monorepo 一併處理)。
- Trakt 重授權完成(2026-07-10):使用者跑 device-auth,新 token 壽命 7.0 天=硬證實 bug #5 (門檻 7d ≥ 壽命 → 每 call refresh)。live Express 同步暫恢復;長久靠 Rust(已修 refresh)。
有狀態第三方輪要點:
- in-process 狀態正式引入:
state.spotify/state.steam(Arc)——短臨界區用 parking_lot::Mutex (無 poison;讀寫皆 clone 出來、絕不跨 await 持鎖)、熔斷用 AtomicI64、steam 首抓/背景重抓 dedup 用 tokio::sync::Mutex(需跨 await)。與先前 lock 選型討論一致。- A/B 已證的非決定性(非實作差):Spotify 上游 key 序每次不同(Express 連打兩次同 offset byte 不同、 jq 語意等);now-playing
progress_ms播放中時變;steam/profile_cachedAt=各自抓取時間戳。 其餘(me/top-genres/top-tracks/audio-features/login 302+Location+body)byte-identical。- 最終留 proxy(僅 2 條):
/spotify/callback(一次性 setup 大 HTML)、/quote/daily(隨機外部 名言+每日快取;opencc 部分已證可移植、來源非決定性故留)。加上刻意不註冊的PATCH /admin/comments/batch/status(bug #2 死路由)。其餘 120 條全部接管。 ⚠️ cutover 清單另有:nginxlocation /uploads/直達 Express:3001(static 檔),切換時要改; ②備份 db 後跑scripts/migrate-comments-post-id-nullable.sh(修 bug #1,Rust 同樣需要); ③live 動畫瘋同步現正停擺(bug #9,記憶體 jar 掏空)——不處置,Rust 起來讀磁碟好檔第一輪自癒。 (admin/stats#109 已接管——visitors 用Math.random除該欄外 byte-identical;sync/collection#110 已接管。) ⚠️/sitemap.xml/rss不在 strangler 範圍:nginxlocation /→ 前端(13588)、只有/api/→ 後端。 Express 的app.get('/sitemap.xml'|'/rss')是 app-level(非/api/),前端服(sitemap)或前端 404(/rss現況 = 前端沒這條路由 → 線上koimsurai.com/rss是 404,pre-existing 前端 bug,跟後端遷移無關)。 碎念 RSS 走/api/thoughts/rss(已接管 #108)。
第三方輪要點:
- JS number 正規化(關鍵):外部 API 回
100.0這種整值 float,JSJSON.parse→res.json會輸出100,serde 預設保留100.0→ 新增util::js_normalize_numbers(遞迴、整值 float→int)套在所有 第三方 parse 點。修完 wakatime 三支從 ❌ 轉 byte-identical。- 留 proxy(有狀態/硬骨頭):
/steam/profile(SWR 快取+miniprofile HTML 解析)、/quote/daily(每日快取讓隨機名言穩定一天=必要狀態+zh-TW 需 opencc)、spotify 全部(token refresh 狀態)、 watch 域(Trakt/TMDb+anigamer)。⚠️ Express bug #6(本 session 揪出):newsletter reply_to 沒送出。
mailer.js建 payload 用reply_to(snake_case),但resendSDK v6 的parseEmailToApiOptions讀email.replyTo(camelCase) →reply_to恆undefined→ wire body 不含 reply_to,即使NEWSLETTER_REPLY_TO有設也白搭。 用 mock(RESEND_BASE_URL指本地容器)攔實際 wire body 證實。Rust 遷移期一併省略 reply_to 保 byte-equivalence(13390B 對拍全同)。修法(行為清理版):mailer.js 改用replyTo。⚠️ Express bug #4(本 session 揪出):ghFetch 亂碼。
https.get的data += chunk逐 chunk 隱式 Buffer→string,multi-byte UTF-8 字元跨 TCP chunk 邊界時產生 U+FFFD(���)。實測/github/events兩次呼叫亂碼數不同(14 vs 12,非決定性)、集中在 enrich 的中文 commit message;Rust reqwest 整段解碼=0 亂碼。Rust 版嚴格更正確,此端點不可能(也不應)byte 對齊;排除 commits 後其餘結構 完全一致已驗。(Express 修法=ghFetch 收集 Buffer 最後再 toString,或 res.setEncoding('utf8')。)
本輪驗證重點:
/posts系列(Express 錯誤回 400、admin 版回 500 的差異照抄);legacy Basic auth 三情境(正確/錯誤/無 header +WWW-Authenticate: Basic);newsletter 全生命週期 (訂→重複 400→退→重新啟用→token 查詢);subscribe 的 UNIQUE 檢查是特定欄位 (newsletter_subscribers.email)非通用;bcrypt 雙向相容實證(Rustbcrypt::hash產出 被 bcryptjscompareSync驗過、$2b$10$ 前綴一致)。unsubscribe_token 為隨機值→A/B 只驗格式 (32 hex)與語意,不 byte 比。⚠️ 安全發現 #3:
/auth/reset-admin在正式環境是活的。Express 用NODE_ENV==='production'擋,但容器沒設 NODE_ENV → 任何人可 POST 觸發把 admin 密碼重置成 envADMIN_PASSWORD值 (env 有設所以攻擊者不能自訂密碼,但可未授權觸發重置)。Rust 照抄行為(等價優先); 建議:compose 給 backend 加NODE_ENV=production(Express 與 Rust 都會因此關閉此端點)。
books/collection A/B 全過。要點:
- REAL 欄位的 JS number 序列化:
row_to_json對整值 REAL 輸出整數(4.0→4),對齊JSON.stringify;books.rating(4.9/4.1)、collection.rating(4.5) 驗過。bind_val/js_num_value進 util。- 動態欄位 SQL(collection POST/PUT):欄名直接插進 SQL——Express 既有寫法(admin-only 緩解), 非法欄名兩邊都 500(僅 driver 錯誤字串不同:
SQLITE_ERROR: no such columnvs sqlx(code: 1))。/books/search/external(Google Books/OpenLibrary)已接管(#85)。/sync/collection(n8n 批次)已接管(#110, Rust 已是 collection_items 寫者→併入單寫者)。/books/search/external、/books/stats/summary是雙段路徑、不會撞/books/:id。- 測試 token 鑄造腳本固定放
scripts/mint.cjs(.cjs 因上層 web/package.json 是 ESM;scratchpad 會被清)。
admin posts CRUD A/B 全過,含最細的 JS 語意:
data回應物件的 undefined-key 省略(body 沒帶 excerpt/category → 回應無該 key;JSON.stringify 語意)。- PUT 的 toNullable(缺 key→不動、
''→NULL、值→覆寫)用 CASE-flag 綁定複製;series_order的Number()強制轉換(js_number:null/''→0、字串 parse、NaN→NULL)。- manageTags:先刪關聯→INSERT OR IGNORE tags→查 id→建關聯(順序照抄)。
- newsletter 條件委派:
send_newsletter && status==='published'的 POST/PUT 整包(原 bytes)轉發 給 Express 處理。已驗:委派回應帶 Express 指紋、文章由 Express 寫入。 ⚠️ resend 已遷移(#111)→ 此委派現可收回:讓 Rust 建文後自己呼叫mailer::send_newsletter(待辦:admin_create_post/admin_update_post 加自動寄送分支,取代委派)。/admin/posts/:id/generate-zh-cn(opencc)已接管(ferrous-opencc Tw2s);…/send-newsletter(resend)已接管(#111,reqwest 直打 batch API)。harness 安全改良(重要):寫入測試時 Rust 的
EXPRESS_UPSTREAM改指 express-test(3003) 而非 live——委派/proxy 的寫入絕不落在 live DB;且 fixtures 先DELETE FROM newsletter_subscribers, 就算 dispatch 被觸發也寄不出信。之後所有寫入輪都照此配置。
admin thoughts A/B 全過(第一批含外部 fetch 的寫入):unfurl
https://example.com兩邊 ref_json byte-equal({"title":"Example Domain","desc":null,"image":null,"site":"example.com"}——regex 移植 +key 順序都對);TMDb enrich(tmdbId=550 movie)531B ref_json byte-equal(zh-TW title/overview/ rating(toFixed(1) 字串)/genres/year/poster、spread→source→url→… 插入順序用 serde Map 對齊 JS 物件賦值語意)。 unfurl 的html.slice(0,200000)用 UTF-16 code unit 截斷對齊 JS。TMDb 需TMDB_API_TOKENenv。 已知細節差:JStoFixed(1)半數進位 vs Rust{:.1}banker's rounding——TMDb vote_average 本身只有 一位小數,實務不觸發。timestamps(created_at/updated_at)跨秒可能差 1s,不列對拍。
comments moderation A/B 全過(status/PUT/DELETE/reply + auth 401 + 404 + 400);reply id 一致(comments 未 startup-seed)。
⚠️ 既有 bug #2(本 session 揪出):
PATCH /admin/comments/batch/status是死路由。Express 按 註冊順序匹配,:id/status(index.js:2164)註冊在batch/status(2178)之前 →batch/status被當成id="batch"→UPDATE … WHERE id='batch'→ 0 列 → 404 "Comment not found",batch 端點永遠打不到。 為等價,Rust 刻意不註冊batch/status,讓它落到:id/status(id="batch") → 同樣 404。 意涵:前端若有「批次審核」功能,在 Express 就已失效;修法是把 batch 路由移到:id/status之前註冊。
admin CRUD A/B 全過(含 auth 401、UNIQUE 409、404、400、
gen_slug產hello-world-測試)。gen_slug(util.rs)逐字複製 Expressname.toLowerCase().replace(/\s+/g,'-').replace(/[^\w\-一-龥]+/g,'')。is_unique_violation對齊 Expresserr.message.includes('UNIQUE constraint failed')。⚠️ A/B 對 AUTOINCREMENT 回傳 id 的注意:
categories在 Express 啟動時INSERT OR IGNOREseed 預設分類(database.js:321),即使被 IGNORE 也會 bumpsqlite_sequence。故 express-test 每次啟動其 categories 序列比 rust fixture 快(本次差 3)→ POST category 回傳的 id 差 3,但其餘欄位全 byte-identical。 已查證(sqlite_sequence 差=seed 數、tags 未被 seed 故 id 一致=對照組、restart 又 re-seed)。 正式環境單一共享 DB、Rust 直接 INSERT 取下一 id,無此分歧——純 A/B-雙實例 artifact。 tags/comments/blacklist/keyword 未被 startup-seed,A/B id 完全一致。
寫入端用
get(h).post(h2).fallback(proxy)在同路徑掛多方法(如/posts/:id/reactions、/posts/:id/commentsGET+POST)。createComment A/B 全過(8 情境 response byte-identical + DB 列一致):anon→pending、 OAuth→approved(真 token)、缺 author→400、黑名單 IP→403、關鍵字 reject→400、spam→spam、 captcha mismatch→400、captcha match→pending。IP 取自
X-Forwarded-For最左(生產 nginx 設 XFF;app.set('trust proxy',1));js_loose_eq近似 JS==(captcha 比對)。⚠️ 既有 bug(本 session 揪出):thought 留言發不出來。
comments.post_id是 NOT NULL, createComment 插 thought 留言時沒給 post_id → 約束失敗。Express 與 Rust 都回 400(行為等價、 用戶都無法發 thought 留言),但錯誤字串因 driver 不同(node-sqlite3SQLITE_CONSTRAINT: …vs sqlxerror returned from database: (code: 1299) …)。屬既有 schema 限制,非遷移引入;若日後把post_id改 nullable,兩邊都會正常運作。已保留 Rust 接管(一致性),修 schema 後即生效。
動態 row→JSON(
src/util.rs::row_to_json):給 Express 端直接 spread 整列(SELECT */p.*/c.*)的端點用—— 依 sqlx 實際欄位順序+儲存類別(INTEGER/REAL/TEXT)建 JSON、保留 DB 欄位序(serde preserve_order), 免枚舉欄位、不依賴記住的實體順序、抗 schema 變動。已驗:/admin/posts322KB 全 i18n 欄位 byte-identical。 另含js_substring_prefix(UTF-16 對齊 JSsubstring)、parse_int、split_tags。
require_admin/require_owner共用authorize(.., owner_only):owner_only 決定角色門檻 (OWNER vs ADMIN∨OWNER)與不足訊息(「需要擁有者權限」vs「需要管理員權限」)。 ⚠️ requireOwner 拒絕「ADMIN(非 OWNER)」這條路徑邏輯有實作,但資料無 ADMIN 角色列、未正向對拍 (現有 oauth_users 只有 OWNER×2、USER×1)。/admin/{blacklist,keyword-filters}為空表→只驗空集合。
posts 多語邏輯(
parseLocale/getLocaleContent/availableLocales、12 個 i18n 欄位title_en/content_zh_cn/… +source_language)逐字照抄 Express;!t的 truthy 檢查(null 與 '' 都當無內容) 用nonempty()對齊。list/single 都用SELECT p.*取(FromRow 依名對應、忽略多餘欄位)。
本 session 進度(2026-06-26 ~ 06-27)
- ✅ 盤點完整端點(下表)+ DB schema。
- ✅ 搭好 Rust 骨架:
src/{main,state,error,proxy}.rs+handlers/,cargo build綠、零 warning。 - ✅ proxy fallback 透傳:method / body / query / 狀態碼 / 上游 header / 404 fallthrough 全對。
- ✅ 接管上表 7 個公開純讀端點,全部對拍 byte-identical。
關鍵踩雷 / 學到的 pattern(接力必看)
- 假陽性防呆:proxy 也會讓對拍 byte-identical(因為兩邊都來自 Express)。
→ 每接管一個端點,用 header 指紋確認是 Rust 自處理:Rust 自處理無
X-Powered-By、content-type無charset;proxy 會保留 Express 的x-powered-by: Express+ charset。 SELECT */t.*的欄位順序:別信database.js的 CREATE TABLE 順序——ALTER 後加欄位 排在最後(livethoughts的dislikes、comments的 status/ip… 都在尾巴)。 要 byte-identical 就從 live 回應實際 key 順序反推,用顯式欄位 SELECT(別用t.*)。- method 層 fallback:axum 對「路徑命中但方法沒命中」預設回 405,但 Express 是 404
(catch-all)。→ 每個接管路由都掛
.fallback(proxy_to_express)(或any(proxy)), 非 GET 方法轉回 Express,保留 404 行為。 - static vs param 碰撞:
/thoughts/rss必須在/thoughts/:id之前顯式註冊(這裡是any(proxy)讓它留在 Express),否則會被當成id="rss"進到 Rust handler。 - serde_json
preserve_order:thoughts 的ref(解析 ref_json 再序列化)若用預設 serde_json 會把物件 key 排序 → 跟 Express 的JSON.parse→res.json(保留原順序)不一致。 已在 Cargo.toml 開preserve_order修正。 - 驗證前重撈 DB 副本:Rust 讀的是
docker cp出的副本、Express 讀 live,會漂移 → 每次驗證前重撈(含-wal/-shm)。
🔑 auth 里程碑(requireAdmin JWT 驗章,2026-06-27)
src/auth.rs 的 require_admin(&headers, &state) 對齊 Express createRequireAdmin:
- HS256 Bearer JWT,secret 共用 Express
JWT_SECRET(AppState 啟動載入、fail-fast)。 - Validation 設定(context7 查證後對齊 node jwt.verify):
leeway=0(node clockTolerance=0)、required_spec_claims.clear()(node 不強制 exp,有 exp 才驗)、僅 HS256。 → 已驗:noexptoken(無 exp)兩邊都放行;過期 token 兩邊都 401。 - 兩種 token 分支:① OAuth(
userId)→ 查oauth_users→linked_to解析主帳號→role∈{ADMIN,OWNER}; ② legacy(非空username、無 userId)→ 視為 OWNER。 - 錯誤回應逐字對齊(注意:requireAdmin 用
{"message":...}不是{"error":...}): 無/非 Bearer→401「未提供有效的授權令牌」、驗章失敗→401「無效的授權令牌」、 user 不存在→401「使用者不存在」、角色不足→403「權限不足,需要管理員權限」、 皆無→403「權限不足」。AppError 新增Unauthorized/Forbidden變體(body 用 message key)。 - 對拍矩陣(
/api/admin/tags,用 server node 鑄 token):legacy/oauth-owner(id3)/oauth-linked(id5) →200 裸陣列;oauth-user(id4)→403;無 token/Basic/壞簽/過期→401,全 byte-identical。
✅ JWT_SECRET 收斂(2026-06-27 已修):先前看到的「容器 secret ≠
server/.env」其實不是換密鑰, 是.env的 CRLF 行尾雜訊——.env為 mixed CRLF/LF,JWT_SECRET 那行尾多一個\r(len 59 vs 58)。 Docker env_file 會 strip\r,所以容器跑的一直是正確的 58 字元值;只有 CRLF-unaware 的工具 (shell、Rustdotenvy)會誤讀成 59 字元。修法:sed -i 's/\r$//' server/.env正規化成 LF (內容除行尾 CR 外一字未動),現.env與容器 sha256 完全一致(12f08c…)。無需重啟、不登出。 教訓:部署/驗證 Rust 前確認.env是 LF,或直接以docker exec … printenv JWT_SECRET為準。
🔐 login 驗證(POST /auth/login,bcrypt,2026-06-27)
handlers/auth.rs:查 users→bcrypt::verify(crate 0.19,相容 bcryptjs $2a/$2b/$2y)→ 簽
{id,username,role}+iat+exp 的 7d HS256 JWT。回應 {message:"登入成功",token,user},錯誤逐字照抄
(缺欄位→400「請提供用戶名和密碼」、查無/密碼錯→401「用戶名或密碼錯誤」、DB 錯→500「伺服器錯誤」)。
- 驗證:① 錯誤路徑 Rust(copy) vs Express(live) byte-identical(含拿真實
$2b$10$hash 驗錯密碼→401); ② bcrypt 跨相容:用 server 的 bcryptjs 產$2bhash + 改前綴成$2a/$2y,插副本測試帳號, 三種前綴knownpass都 200、錯密碼 401;③ 解碼簽出的 token:claims 正確、exp−iat=7 天; ④ 互通性:Rust-login 簽的 token 拿去打 live Express 的 requireAdmin → 200(同 secret 同格式)。 - 驗證手法(可複用於所有寫入域):副本插測試列(不碰 live)+ 第三方 lib 產 fixture。
- 邊角:body 非合法 JSON / 空字串 body 時 axum 回 4xx 與 Express 的 400 訊息可能不同(前端必送合法 JSON,未對齊)。
🧪 寫入域 A/B 驗證 harness(2026-06-28,可複用)
寫入會改 DB,無法拿 Rust(副本) 直接比 live Express。改用隔離 A/B:
- 撈 live DB 副本當 base,複製成兩份 fixture:
$SC/fix_express/、$SC/fix_rust/(含-wal/-shm)。 - 用同一個
web-backendimage 起第二個 Express 容器掛 fix_express:docker run -d --name express-test -v $SC/fix_express:/usr/src/app/db --env-file server/.env -p 127.0.0.1:3003:3001 web-backend - Rust 指 fix_rust(port 3002)。兩邊起點相同。
- 同序列寫入請求送兩邊 → 比 ① response byte-identical ② 事後用 python sqlite3 dump 受影響的列、比 DB 狀態。
- 測完
docker rm -f express-test,不碰 live volume。
已驗(計數寫入全過):view/like/unlike/reactions(upsert+clamp+delta+❤️多碼位)/comment-like/thought-react, 含 404(Post/Comment not found)、400(invalid emoji / bad reaction)、找不到 id 仍回 success 等邊角; 最終 DB 狀態(post17/thought5/comment17/post_reactions)express==rust。createComment 亦以此 harness 全過。
harness 踩雷(接力必看):
- ⚠️ 別用
pkill -f 'target/debug/koimsurai-web-backend'——pattern 字串會出現在正在跑的 bash 指令列裡,pkill -f 會匹配並殺掉腳本自己的 shell(自殺→無輸出、exit 1)。改用for pid in $(pgrep -f koimsurai-web-backend); do [ "$pid" != "$$" ] && kill -9 $pid; done。 - 背景 Rust 用 Bash tool 的
run_in_background(&+kill %1只殺當前 shell 的 job、跨 Bash call 的孤兒殺不到→撞 3002 bind 失敗→測到舊 fixture)。每次測試前確認 3002 free、reap 孤兒。 - seed fixture:docker cp 帶
-wal/-shm後先PRAGMA wal_checkpoint(TRUNCATE)再改,避免 table locked。 JWT_SECRET/mint 要在同一個 Bash block export(每個 Bash call 是新 shell、env 不留存)。
proxy 透傳對拍(骨架驗證,仍有效)
| 項目 | 結果 |
|---|---|
/api/health /api/posts?query /api/thoughts/:id/comments(proxy) |
body 全一致 |
/api/thoughts/rss(已接管 #108) |
application/rss+xml XML byte-identical(含對抗 fixture) |
POST /api/auth/login(假帳密,proxy) |
401 + {"message":"用戶名或密碼錯誤"} 一致 |
POST /api/stats(method-fallback→proxy) |
404(非 axum 405),與 Express 一致 |
未知路由 /api/__x__(proxy) |
404 一致(走 Express 的 404 handler) |
已知 header 差異(接管端點,刻意):
- Express:
Content-Type: application/json; charset=utf-8+X-Powered-By: Express - Rust:
content-type: application/json(無 charset)、不送 X-Powered-By - 評估:JSON 一律 UTF-8、前端
fetch().json()不看 charset → 功能等價;X-Powered-By是 Express 的資訊洩漏,本就該移除,刻意不複製。 header name 小寫是 hyper 正常行為(HTTP header 大小寫不敏感)。
驗證用的 DB 是
docker cp出來的 live 副本(含-wal/-shm,WAL 當下有 4.2MB 未 checkpoint 資料,只 copy.sqlite會少資料)。正式切換時 Rust 直接開 volume 內同一檔,無此問題。
本機重跑驗證
cd web/server-rs
# 1. 撈 live DB 副本(含 WAL/SHM)
docker cp personal-website-backend:/usr/src/app/db/db.sqlite /tmp/dbcopy/db.sqlite
docker cp personal-website-backend:/usr/src/app/db/db.sqlite-wal /tmp/dbcopy/db.sqlite-wal
docker cp personal-website-backend:/usr/src/app/db/db.sqlite-shm /tmp/dbcopy/db.sqlite-shm
# 2. 跑 Rust(proxy 回正在跑的 Express container:3001)
DATABASE_URL=sqlite:///tmp/dbcopy/db.sqlite \
EXPRESS_UPSTREAM=http://127.0.0.1:3001 BIND_ADDR=127.0.0.1:3002 \
cargo run
# 3. 對拍
diff <(curl -s :3001/api/tags) <(curl -s :3002/api/tags) # 應無輸出
端點盤點(共 ~111 條,按計畫搬遷順序 = 自包含→高整合)
來源:
web/server/index.js(掛在apiRouter,prefix/api)+routes/{thoughts,watch,home}.js。 「硬骨頭」標記=需 Rust 重寫第三方依賴,非單純 SQL 翻譯。
① thoughts(碎念,routes/thoughts.js)— 部分接管中
- ✅ 已接管:
GET /thoughts(列表)GET /thoughts/:id(單篇) - ✅ 已接管(靜態路由優先於 :id):
GET /thoughts/rss(#108,XML byte-identical,含對抗 fixture) - ⏳ 未接管(proxy):
GET /thoughts/:id/comments—— 目前無任一 thought 有留言。 但 comments row 解碼已透過/posts/:id/comments(post 17 真實留言)驗過 byte-identical, 可低風險接管(重用posts::CommentRow,把post_id換thought_id);只差 thoughts 自身 無資料做正向 byte 對拍。列為最易接的下一個。 - ⏳ 寫入(需先做 auth/createComment 里程碑):
POST /thoughts/:id/{comments,react}、POST/PUT/DELETE /admin/thoughts[/:id] - 表:
thoughts、comments(thought_id)。comments 實際欄位序:id,post_id,author,content,likes,created_at,is_admin,email,website,status,ip,parent_id,avatar_url,thought_id
② watch(觀影,routes/watch.js)— ⚠️ 含硬骨頭 anigamer
- 公開讀:
GET /anime/history/films/recent/tv/recent/watch/stats/watch/favorites/watch/now - admin:
GET /watch/tmdb-search、POST/PUT/DELETE /watch/favorites[/:id]、POST /admin/watch/now - anigamer(硬骨頭):
GET /admin/bahamut/statusPOST /admin/bahamut/cookie— 巴哈動畫瘋爬蟲。 → 拆獨立 Rust crate,可發 crates.io。 - 第三方:Trakt / TMDb(reqwest)
- 表:
anime_historyfilm_historytv_historywatch_favorites
③ posts / comments / reactions / tags / categories — 站核心
- ✅已接管(公開讀):
/tags/categories/stats/series/series/:name/posts(分頁+多語)/posts/:id(多語)/posts/:id/reactions/posts/:id/comments - 互動(寫):
POST /posts/:id/{view,like,unlike,reactions,comments}/comments/:id/like - 公開寫(疑舊):
POST/PUT/PATCH/DELETE /posts[/:id][/status]、POST /posts/legacy(2026-10 移除,只留 MCP 在用的PATCH /posts/:id/status) - admin posts:
GET /admin/posts[/:id]/admin/stats、POST/PUT/DELETE /admin/posts[/:id]、POST /admin/posts/:id/generate-zh-cn(✅ opencc 已接管:ferrous-opencc)、/admin/posts/:id/send-newsletter(✅ resend 已接管 #111) - admin tags/categories:
GET/POST/PUT/DELETE /admin/{tags,categories}[/:id] - admin comments:
GET /admin/comments、PATCH …/:id/status…/batch/status、PUT/DELETE /admin/comments/:id、POST /admin/comments/:id/reply - admin 黑名單/關鍵字:
GET/POST/DELETE /admin/{blacklist,keyword-filters}[/:id] - opencc-js(硬骨頭)✅ 完成:簡繁轉換。改用純 Rust
ferrous-opencc(內建 OpenCC 字典、免 libopencc C 依賴,docker build 乾淨);Tw2s對 opencc-js{from:tw,to:cn}、S2tw對{from:cn,to:tw}皆實測 byte-identical。generate-zh-cn已接管(#107);quote/daily的阻塞是隨機外部名言來源+每日快取(非 opencc),故仍留 proxy。 - 表:
postscategoriestagspost_tagspost_reactionscommentsip_blacklistkeyword_filters
④ auth / oauth — 高整合,謹慎搬(argon2 + jwt)
POST /auth/login、GET /auth/me/auth/providers、POST /auth/logout- OAuth:
POST /auth/google/callback/auth/github/callback - admin:
GET /admin/users、PUT /admin/users/:id/role、POST /auth/reset-admin - 表:
usersoauth_users。對照 NAS 樣板的 argon2 + jwt + middleware。 ⚠️ Express 現用 bcryptjs(非 argon2)——搬遷要驗 hash 相容或規劃 rehash。
⑤ books / collection — 自包含
GET /books[/:id]/books/search/external/books/stats/summary、POST/PUT/DELETE /books[/:id]GET /collection/:type、POST /collection[/search-external]、PUT/DELETE /collection/:id、POST /sync/collection- 表:
bookscollection_items。第三方:Google Books / 外部 API(reqwest)
⑥ newsletter — ⚠️ 硬骨頭 resend
POST /newsletter/{subscribe,unsubscribe}、GET /newsletter/by-token/:token- admin:
GET /newsletter/subscribers、POST /admin/posts/:id/send-newsletter - 表:
newsletter_subscribers。resend(→ reqwest)、mailer.js
⑦ 第三方整合(純 reqwest,無自家 DB 寫)— 可較晚搬
- Steam:
/steam/{profile,player,recent-games,owned-games,achievements/:appid} - Spotify:
/spotify/{login,callback,recently-played,now-playing,top-genres,top-tracks,audio-features,me} - WakaTime:
/wakatime/{today,week,projects} - GitHub:
/github/{user,events}/:username - home:
GET /quote/daily(外部 quote)/home/digest
⑧ media / 雜項 — ⚠️ 硬骨頭 sharp
POST /admin/upload、GET /gallery/photos、POST /admin/gallery/sync(sharp/thumbhash/exifr → image crate,NAS 已驗)GET /image-proxy、GET /og/:id.png(sharp 產 OG 圖)- app-level(非 strangler 範圍:nginx
/→ 前端,非/api/):GET /sitemap.xml(前端服)、/rss(前端目前 404=pre-existing bug)、GET /api/health(純文字OK,/api/底下→經 strangler,仍 proxy)
硬骨頭彙整(→ Rust 重寫)
| 依賴 | 用途 | 端點 | 計畫 |
|---|---|---|---|
anigamer |
巴哈動畫瘋 SDK | watch bahamut/now | ✅ 完成:獨立 crate(anigamer-rs,29 測試)+ 整合 server-rs(端點 #105-106,真 session 驗證冪等) |
opencc-js |
簡繁轉換 | /admin/posts/:id/generate-zh-cn |
✅ 完成:ferrous-opencc(純 Rust)Tw2s 對 opencc-js byte-identical(雙向 S2tw 也驗過);generate-zh-cn 已接管,quote/daily 因隨機來源留 proxy |
sharp/thumbhash/exifr |
圖片處理 | upload/gallery/og | ✅ 完成(#112-116):image+resvg+thumbhash+webp(libwebp vendored)+kamadak-exif;分層驗證=確定性 byte 對拍+圖片視覺等價 |
resend |
寄信 | newsletter | ✅ 完成(#111,reqwest 直打 batch API,wire body byte-identical;⚠️ 復刻 bug #6 reply_to) |
下一步建議
- ✅ JWT requireAdmin 中介層已完成(見上)。接續可搬更多 read-only admin 端點驗骨架:
/admin/categories/admin/posts(分頁,需對齊 admin 版欄位)/admin/comments/admin/users/admin/blacklist/admin/keyword-filters/admin/books。(/admin/stats有Math.random()訪客數→非確定性,不可 byte 對拍,要嘛跳過要嘛只比結構。) - ✅ login + auth 讀(me/logout/providers)已完成。✅ admin 分頁讀(posts/comments)已完成。
- 剩餘讀端點:
/admin/posts/:id(編輯器用,回全 locale 欄位,可用動態 row→JSON)、/admin/stats(⚠️Math.random()訪客數,不可 byte 對拍)、/og/:id.png(sharp)。(/admin/books/books/thoughts/rss均已接管。) - 寫入域(用 JWT 中介層):
POST /thoughts/:id/{react,comments}(createComment:黑名單+ 關鍵字過濾)、admin thoughts/posts/comments/tags/categories CRUD、reactions/view/like、newsletter。 寫入端對拍要建測試 fixture DB(如本檔 login 驗證的手法:副本插測試列),別對 live 變更。 - 第三方(reqwest):steam/spotify/wakatime/github。硬骨頭:anigamer/opencc/sharp/resend。
- 切 nginx 前:對每個接管端點做 body 對拍 + header 指紋(本檔驗證流程)。
- 型別(P4 前置可先鋪):DTO 加
utoipa::ToSchema+specta::Type雙 derive(已決策並存)。 本骨架先用 plain serde,待端點數量起來再導入,避免一開始就背依賴。
async I/O audit(2026-07-03,使用者要求檢查)
- I/O 全 async:sqlx / reqwest(非 blocking 變體)/ axum body 皆
.await;無std::fs、std::net、reqwest::blocking、手開 thread。proxy 的 body 為有界緩衝(10MB,對齊express.json limit)—— 刻意選擇;日後接 image-proxy/upload 再改 streaming。 - 修正:bcrypt 包進
spawn_blocking(login 的verify、reset-admin 的hash)。cost-10 ≈ 數十 ms 純 CPU,原本 inline 會卡 tokio worker。修後功能重驗:login 200/401、token 打 requireAdmin 200、 reset-admin hash 仍被 bcryptjs 驗過。 - 不動的(評估過):jsonwebtoken HMAC(µs 級,慣例 inline);unfurl/email regex per-call 編譯 (µs~ms、admin-only 低頻,改了還要重驗不划算)。
- panic-safety audit(同日):全專案零 Mutex/RwLock(AppState=sqlx Pool+reqwest Client+Arc,
handler 全 stateless)→ 無 poison 疑慮、parking_lot 不適用;日後若加 in-process cache 再選型
(持鎖跨 await 必須 tokio::sync)。guarded unwrap 全清(~15 處
contains_key檢查後get().unwrap()的兩行分離寫法 →if let/unwrap_or單一表達式,消除 guard-drift panic 風險); 煙霧 A/B 11 條全 byte-identical。殘留 panic 點僅:main.rs 啟動 expect×2(fail-fast,刻意)、 靜態 email regex unwrap(常數 pattern 不可能失敗)。
模組結構
src/
main.rs 路由註冊(接管端點 + 各自 method-fallback + 全域 proxy fallback)
state.rs AppState { pool, http(reqwest), upstream }
error.rs AppError → IntoResponse({"error":msg};404 用 not_found())
proxy.rs proxy_to_express:未接管請求原樣轉回 Express
handlers/
tags.rs categories.rs series.rs stats.rs thoughts.rs
統一 audit(2026-07-11,端點遷移完成後)
依使用者提供的 20 條反模式表 + 自補維度全面掃過(server-rs + anigamer-rs)。基線:clippy 僅 7 warnings。
A 級(真 bug,已修)
- CORS 缺失:Express
app.use(cors())全回應帶Access-Control-Allow-Origin: *;Rust 原本沒有 → 補CorsLayer(Any origin、六 methods、AllowHeaders::mirror_request()對齊 cors 套件 reflect 行為)。 已知微差:preflight Rust 200 vs Express 204(瀏覽器語意等價);Rust 多Varyheader(更正確)。 - body limit:axum 預設 2MB vs Express
json({limit:'10mb'})/multer 50MB → 長文 PUT 會 413 → 全域DefaultBodyLimit::max(10MB)+/admin/uploadroute_layer 50MB。驗證:3MB POST 兩邊同回 400(業務層)。 - graceful shutdown 缺:docker stop 硬殺 →
with_graceful_shutdown(SIGTERM/Ctrl-C),實測 SIGTERM 正常退。 - 🔥 Express bug #9(live 事故 + Rust 同洞預修):Bahamut 偶發
deleted; Max-Age=0掏空 cookie, TS SDK 守門只護「檔案」不護「記憶體 jar」→ live 記憶體 jar 被清空、每 6h sync 全 skip(log: "rotation dropped BAHARUNE — NOT persisting" 之後 historyAll 0 筆→missing 全部);磁碟檔完好(BAHARUNE 7/24), Express 無重載機制,重啟容器才會恢復。Rust 端 anigamer crate 加merge_with_destructive_guard: merge 後必要 cookie「從齊變缺」→ 還原快照、不觸發 persist(+3 單元測試)。
B 級(idiom,已修)
- regex 每呼叫重編譯 ×6(newsletter email 熱路徑/bahamut simplify+ep/watch rfc3339/thirdparty isbn)→
std::sync::LazyLock(順帶抓到自己抄錯:simplify 第 3 pattern replacement""誤寫" ",trim 恰好遮掩——已修) - clippy 7:redundant closure/map identity/sort_by_key(Reverse)/clamp×3(f64 但 JSON 來源無 NaN → 與 JS min/max 鏈等價,安全改)
- async 內 std::fs:gallery scan→spawn_blocking、mtime→tokio::fs、bahamut cookie 寫→tokio::fs、watch chmod→tokio::fs
let _ =吞錯 ×6 →tracing::warn/error(Express 有 console.error 的地方尤其補齊)- 「安全 unwrap」重構為編譯器保證(og/gallery/thoughts 的 if-let)
- anigamer:callback 型別 alias(消 complex-type)、clippy 0
C 級(刻意照抄 Express,記錄不修 → 行為清理版)
- collection 動態欄名 SQL(body key 直接進 SQL;admin-only;值全 bind)
- N+1(bahamut cover per-sn、enrich 迴圈——有 sleep 節流,照抄)
- handler 直接回
Response而非Result<_, AppError>(byte 對齊需逐端點細控 body key) - in-process 快取狀態用
Arc<Mutex>(已 review:短臨界區、不跨 await、無 poison;channel 不適合快取型狀態)
D 級(不適用/不動)
- 每 request 重建 client(無)、&String/&Vec 簽名(無)、C 風格 index loop(無)、serde borrow(payload 小)
- rand 0.8/thiserror 1/axum 0.7:非幻覺 API、現行維護;P4 monorepo 時一併升版
驗證
- 修復後冒煙:tags/thoughts-rss/home-digest/gallery-photos/posts 五端點 body byte-identical 不變; CORS/preflight/3MB/SIGTERM 全過。兩 crate clippy 0、測試全綠(server-rs 2 + anigamer 30)。
行為清理版(2026-07-11,commit f27f514)
byte-equivalence 階段照抄的爛行為統一修正(自此起 Rust 與 Express 在這些點刻意不同):
| Bug | 修法 | 驗證 |
|---|---|---|
| #1 thought 留言發不出(post_id NOT NULL) | scripts/migrate-comments-post-id-nullable.sh(12-step 重建+index 重建) |
fixture 演練:列數不變/fk OK/index 在;修復後 thought 留言 201。⚠️ 約束在 db.sqlite 裡(非 Express 碼)——Rust 也需要;使用者裁示併入 cutover 一起跑 |
| #2 batch/status 死路由 | Rust 實作正確版(靜態段優先於 :id) | 400 分支/批次 UPDATE affected/單筆不受影響 |
| #3 reset-admin 正式環境是活的 | fail-safe:預設 404,ENABLE_RESET_ADMIN=1 才開 |
未設 flag → 404 |
| collection 欄名注入面 | 14 欄白名單(忽略未知、全非法 400) | id/evil_column 注入被擋 |
| PUT posts 缺 key 誤刪 | category CASE-flag、tags contains_key | 只帶 title 時 category/tags 不動 |
已在移植期修掉:#4 ghFetch 亂碼、#5 Trakt refresh race、#7 multer 500 stack trace、#9 記憶體 jar 掏空(anigamer 守門)。 Express 端一律不修(將拋棄)。前端相容性:PostEditor 恆送全欄位,以上變更零影響。
上線記錄(2026-07-14)
- compose
backend-rs上線:nginx/api/→ Rust:3002。Express 仍服務:proxy 目標(quote/daily、 spotify/callback)、/uploads/static、= /rss、cron workers(Trakt/bahamut 寫者)。 - 前端 SSR 仍直連 Express(serve.mjs
BACKEND_URL=http://backend:3001容器直連不經 nginx)—— 瀏覽器端 fetch 走 nginx→Rust、SSR 走 Express,混合但行為一致(byte-identical 保證)。 - 退役 Express 前的殘留清單:①quote/daily ②spotify/callback ③/uploads static(建議 nginx 直接 serve 檔案)④/rss ⑤SSR BACKEND_URL 改指 rust ⑥workers 切換(ENABLE_*_SYNC=1 + DISABLE_WATCH_CRON=1, 同時做避免雙寫)⑦db migration(bug #1)⑧sites-available/enabled 已收斂 symlink。
🪦 Express 退役(2026-07-14,commit 611eabd)
- 最後三端點移植:quote/daily(四語系+opencc S2tw+當日快取+fallback pool)、/rss(app-level; pubDate 修正為 UTC 解析——原 Express 在 TZ 下偏 8h)、spotify/callback(簡版 setup HTML)。
- 退役模式:EXPRESS_UPSTREAM 未設 → fallback 回 404 'Not Found'(對齊原 catch-all)。
- 執行序列:db 備份(db-backup volume
db.sqlite.bak-pre-express-retire-20260714)→ live migration(bug #1):comments.post_id 已 nullable、index 重建、fk OK → compose:backend 移入 legacy profile、frontend SSR→backend-rs:3002、workers 開 → Express stop → nginx:/rss→3002、/uploads→alias 直 serve(仿 /nas-images)。 - 驗證:13 端點 200、/rss 8 items、/uploads 200、退役 404、Trakt sync Rust 首跑成功(151 列)。
- ⚠️ bahamut session 死(NO_LOGIN;7/11 的 deleted Set-Cookie 是真註銷,守門保住的 jar 已無效)
——待使用者瀏覽器擴充重推 cookie(
POST /admin/bahamut/cookie就緒、收到即同步)。 - Rollback:
docker compose --profile legacy up -d backend+ nginx 備份檔還原。 - 現況:koimsurai.com 全站(/api、/rss、SSR)由 Rust 服務;Express 容器停用保留定義; 純靜態(/uploads、/nas-images)nginx 直 serve。