Maintenance

維運指南

已部署系統的日常維運與疑難排解。更完整的指令範例見 repo 內的 Operations Playbook。

自動化排程一覽

元件	位置	頻率	工作
Durable Object	Cloudflare Worker	常駐	持有 TeamPlus WS,擷取訊息 → Turso、檔案 → R2,自我修復
Keepalive cron	Worker scheduled	每 5 分鐘	若 DO 的 alarm 鏈中斷,提醒它重連
refresh-cookies	GitHub Actions(私有 repo)	每 12 小時	重新登入、上傳新 cookies 到 worker
worker-healthcheck	GitHub Actions(私有 repo)	每天 09:00(台北)	探測 worker、發 Telegram 報告,異常時 fail(寄信)

每天早上應該收到一則 Telegram 健康報告 — 這是系統存活的主要訊號。沒收到就要查。

日常操作

讀訊息紀錄

./scripts/logs.mjs                 # 近 24h(預設)
./scripts/logs.mjs --days 7       # 7 天 = 伺服器上限
./scripts/logs.mjs --from 某人    # 依傳送者過濾(子字串)
./scripts/logs.mjs --files --url  # 只看附件,附檢視連結
./scripts/logs.mjs --ids          # 印出訊息 id(供 quote-reply 用)

發訊息

./scripts/send.mjs --to 1344 --text "晚點回你"          # DM(peer userNo = log 的 sender_id)
./scripts/send.mjs --chat-id <group-guid> --text "…"   # 群組(自動判別)
./scripts/send.mjs --to 1344 --reply <id> --text "收到"  # 引用回覆

走雲端 worker,筆電關機也能發。

手動健康檢查

./scripts/cf_worker_request.mjs GET /v1/sessions/default/status   # 即時狀態
gh workflow run healthcheck.yml --repo htlin222/team-plus-server-live      # 立即跑雲端健檢
gh workflow run refresh-cookies.yml --repo htlin222/team-plus-server-live  # 立即更新 cookie

本機 daemon(Telegram 橋接)

make start    # launchd 管理
make stop
make logs     # tail 日誌

疑難排解

症狀	可能原因	處置
Telegram 報告顯示 🔴 / connected:false	WS 斷線且未自動恢復	cf_worker_request.mjs POST /v1/sessions/default/nudge '{}';還是不行就查 cookie 年齡
報告出現 cookie stale (>36h)	更新 cron 停擺	gh run list --repo …/team-plus-server-live;重跑 refresh-cookies.yml
refresh-cookies Action 紅燈	TeamPlus 密碼變更,或驗證碼 OCR 連續失敗	密碼變了就更新 TEAMPLUS_PASSWORD secret;OCR 會重試最多 8 次,查 run log
lastError 提到 websocket/getToken	cookie 過期/失效	跑一次 refresh;下次 cookie 上傳時 DO 會重連
安靜、沒新訊息	離峰時段屬正常	確認 connected:true 即可
API 回 Cloudflare 1101	worker 執行期丟例外	cd worker && pnpm exec wrangler tail 邊重現邊看
沒收到每日 Telegram 報告	bot token/chat_id 變了,或 Action 被停用	檢查 TELEGRAM_* secrets 與私有 repo 的 Action 狀態
附件沒存到 R2	下載當下失敗(非致命,文字列仍在)	cf_worker_request.mjs POST /v1/sessions/default/backfill-attachments '{"limit":50}'

密鑰存放與輪替

各密鑰的存放位置:

Secret	Worker(wrangler)	worker/.dev.vars	.cf-worker.env	.env	GH Actions(私有)
TURSO_URL / TURSO_AUTH_TOKEN	✓	✓			✓(healthcheck)
COOKIE_UPLOAD_SECRET(管理)	✓	✓	作為 CF_TEAMPLUS_UPLOAD_SECRET		✓
TEAMPLUS_BASE	✓	✓		✓	✓
TEAMPLUS_DB_KEY(讀取 API)	✓	✓
TEAMPLUS_ACCOUNT / TEAMPLUS_PASSWORD				✓	✓
TELEGRAM_BOT_TOKEN / TELEGRAM_CHAT_ID				(.telegram.json)	✓

輪替讀取 API 金鑰(TEAMPLUS_DB_KEY)

NEW=$(openssl rand -hex 32)
sed -i '' "s/^TEAMPLUS_DB_KEY=.*/TEAMPLUS_DB_KEY=$NEW/" worker/.dev.vars
cd worker && ./scripts/push_secrets.sh && cd ..

輪替管理密鑰(COOKIE_UPLOAD_SECRET)

在 worker/.dev.vars 重新產生,並把同一個值鏡射到 .cf-worker.env(CF_TEAMPLUS_UPLOAD_SECRET)與私有 repo 的同名 Action secret,然後 push_secrets.sh + wrangler deploy。

TeamPlus 密碼變更

同步更新本機 .env 與私有 repo 的 TEAMPLUS_PASSWORD Action secret。

部署變更

# worker 程式碼
cd worker && pnpm exec tsc --noEmit && pnpm exec wrangler deploy

# workflow 變更(現行 workflow 不進公開 repo)
git checkout live && git merge main
#   編輯 .github/workflows/*.yml
git commit -am "…" && git push private live:main && git checkout main

雙 repo 佈局

• 公開 — htlin222/team-plus-server:全部程式碼,workflow 只留 .example 範本
• 私有 — htlin222/team-plus-server-live:現行 workflow + 9 個 Action Secrets;其 main 分支就是 cron 實際執行的版本。本機對應 private remote 的 live 分支