Maintenance

維護手冊

日常維運所需的指令與注意事項。完整部署細節見 repo 根目錄的 plan-for-deploy-r2.md(已跑過全量資料的 runbook)。

先決條件

• 工具:python3、bun、wrangler(已 wrangler login)、rclone
• 憑證:複製 .env.example → .env、frontend/.env.production.example → frontend/.env.production,填入 account id、網域、token。這些檔案不進版控。
• 原始影像資料:~/ash-image-bank/data(含 index.jsonl + collection/ + atlas/ + reference-cases/,約 1.3 GB),只在特定機器上,不在 repo。

標準流程:更新資料並重新部署

# 1. 從爬取結果重建 feed
python3 prep/build_feed.py --in ~/ash-image-bank/data/index.jsonl --out frontend/public/feed.json

# 2. 上傳影像到 R2(先填好 .env;DRY_RUN=1 可預覽)
./prep/upload_r2.sh

# 3. 建置並部署前端
cd frontend && bun install && bun run build
wrangler pages deploy dist --project-name hematok

關鍵不變量:feed.json 的 image key == R2 object key(collection/<id>/<id>.jpg 等)。上傳採 rclone copy … --include "**.jpg",不搬 sidecar(caption.txt、metadata.json、page.html)。若 key 對不上,前端影像會 404。

推薦服務(worker/)

• Worker 名稱:hematok-rec-api,程式在 worker/src/index.ts,設定在 worker/wrangler.toml
• 向量索引由 prep/build_embeddings.py 產生(Vectorize + Workers AI embeddings)
• 部署:cd worker && wrangler deploy
• 資料更新後(新增/移除影像)需重跑 embeddings,否則推薦會指到不存在的影像

Owner 登入後端(frontend/functions/)

• Pages Functions 隨前端一起部署(wrangler pages deploy),不需另外部署
• 狀態存 KV,binding 名 STATE(設定在 frontend/wrangler.toml),key 格式 u:<email>
• Secrets:OWNER_TOKEN(Pages secret)— bearer token 登入用。更換方式: wrangler pages secret put OWNER_TOKEN --project-name hematok
• Allow-list 目前寫死為 hsieh.ting.lin@gmail.com(frontend/pages-lib/gate.ts)

驗證部署是否成功

1. 開 https://hematok.hsiehting.com,捲動數張卡片,確認影像載入(無 404)
2. 點標題開 Details sheet,抽查一個 reference case 的臨床描述
3. 按 like 後確認推薦有變化(/recommend 回應 200)
4. 登入 owner(bearer token),按 like 後 GET /api/state 應包含該影像

常見問題

症狀	可能原因	處理
影像 404	feed key 與 R2 key 不一致	檢查 build_feed.py 的 keys_for() 與 rclone 來源,重跑上傳
推薦回傳空或錯誤	Vectorize 索引與 feed 不同步	重跑 prep/build_embeddings.py 並重佈 worker
登入失敗	OWNER_TOKEN 未設或 token 不符	重設 Pages secret 後重新登入
PWA 沒更新	Service Worker 快取	重新整理兩次或等 SW 自動更新

升級注意

• 前端套件管理用 bun(bun.lock);repo 其他 Python 工具用系統 python3,無 lock 檔
• fork 上游為 upstream(IsaacGemal/wikitok),但已大幅改寫,合併上游變更前先評估衝突面