上線驗收與日常維護

部署指令碼結束後，還要在正式環境驗證使用者實際會走過的流程。驗收時，請使用正式環境中新建立的測試帳號，不要假設本機帳號和測試訂單已存在於遠端資料庫。

依自己的功能開關選擇檢查項目。尚未啟用的 OAuth、部落格、聯盟行銷或收費功能，不需要臨時開啟，但頁面也不應顯示無法使用的入口。

一、先記錄驗收環境

記錄正式網址、程式碼版本、部署時間和測試帳號。涉及付款時，再記錄使用的是 Stripe 測試模式或正式模式，以及對應的連線識別字。

首次上線應完整檢查下表。後續更新可以著重於受影響的功能，同時保留首頁、登入和核心業務的基本驗證。

二、驗證使用者流程

如果跟著收藏連結教學操作，請分別用兩個帳號建立和查詢收藏，確認使用者資料隔離。如果跟著 WebpageToPDF 教學操作，請依教學檢查匿名體驗、註冊使用者、Pro 使用者的轉換和額度規則。

不要將使用者看到的成功提示當成唯一證據。寫入操作完成後，請再讀取一次結果。非同步工作則要繼續查看執行狀態。

三、驗證付款與權益

先在獨立的測試設定和資料環境中，完成 Checkout、Webhook、購買紀錄與權益發放流程。正式網站的驗收使用正式設定，不能只替換 Secret Key，卻保留測試 Price 或測試端點的簽章金鑰。

依下列順序檢查：

1. 購買入口對應正確的產品和 Plan，顯示價格與付款頁面一致。
2. 取消付款並返回後，不會只因返回網址而取得權益。
3. 付款成功後，檢查訂單或訂閱紀錄，以及後續權益狀態。
4. 實際呼叫受保護業務，確認權限或額度已生效。
5. 開啟 Billing Portal，確認管理的是目前使用者的客戶與訂閱。
6. 在測試環境驗證週期結束、取消、付款失敗和退款等相關狀態。

設定「週期結束時取消」，不代表立即失去所有權益，應依訂閱有效期間和權益來源判斷。退款也不應直接等同於「所有權限都已自動撤銷」，驗收結果要與產品實際的退款規則一致。

正式模式下的購買會產生實際交易。如果確實需要完成正式交易驗收，請依自己的收款與退款安排操作，並記錄對應訂單，不要使用測試卡，或將測試交易的結論當成正式驗收結果。

如果付款平台已收到款項，但網站權益沒有變更，請先檢查 Webhook 投遞、簽章驗證、付款同步和 Reaction 執行，再檢查方案的 access 設定。不要讓使用者反覆付款來觸發修復。

四、驗證檔案、客服案件與背景工作

依啟用情況完成下列操作：

• 上傳一張測試圖片或一個業務檔案，再透過回傳網址讀取，確認使用的是正式環境儲存資源。
• 一般使用者建立客服案件，管理員讀取並回覆，確認狀態與附件可用。
• 在公開頁面產生一次造訪，再檢查統計資料是否進入後台。
• 觸發一項正常業務事件，檢查 Reaction 事件與命令的執行結果。
• 查看 Queue 取用、重試或積壓情況，以及 Cron 的設定和執行記錄。

Reaction 紀錄可從管理後台的對應入口查看，例如：

/dashboard/reaction/events
/dashboard/reaction/commands

佇列成功接收訊息，只表示訊息已加入佇列，Cron 觸發成功也只表示入口已被呼叫。最終仍要檢查命令執行紀錄與業務資料，不能只看觸發次數。

統計資料可能經過佇列非同步處理，不必在重新整理頁面後立刻判定蒐集失敗。請依流量統計的流程，檢查請求、佇列和統計資料庫。其他背景流程請見背景工作與排程工作。

五、上線後觀察什麼

正式開放後，優先觀察會中斷使用者流程的訊號：

若要查看即時 Worker 記錄，可以在專案根目錄執行：

npx wrangler tail

搭配 Cloudflare 中的 Worker、Queue 和 D1 狀態，以及網站管理後台的記錄進行判斷。分享排查資訊時，保留請求、事件和訂單識別字，隱藏權杖、簽章金鑰和不相關的使用者資料。

如果已設定通知管道，可以將重要業務失敗的通知寄送到實際有人查看的目標。設定方式請見通知，不要只建立目標，卻從未驗證是否送達。

六、常見問題應依哪個流程排查

首頁正常，註冊失敗

先檢查 Turnstile 與郵件設定，再查看資料庫和 Reaction。首頁通常不需要完整經過這些模組，能開啟首頁，不代表註冊所依賴的服務已準備完成。

OAuth 返回網址錯誤或反覆重新導向

核對正式的 VITE_SITE_URL、應用程式允許的主機、OAuth Client ID 對應的應用程式，以及平台儲存的 Callback URL。確認瀏覽器不是從舊 Origin 進入，也沒有將語言路徑加入 API 回呼。

付款成功，後台狀態沒有更新

先檢查事件是否送達正式端點、簽章金鑰是否屬於該端點，再檢查同步與後續命令。確認失敗原因已修復後，使用供應商或專案既有的重試方式，並驗證不會產生重複的業務結果。

文件或部落格 404

先確認功能已啟用，而且該語言確實存在對應文章，再檢查 MAIN_KV 和同步輸出。文章已刪除，但側邊欄仍保留時，也要檢查 meta.json，不要只重新建置首頁。

資料庫出現 no such table 或 no such column

確認錯誤請求使用的繫結，與遷移操作指向同一個資料庫，再檢查遷移紀錄和實際欄位。不要為了恢復存取而執行正式環境 Reset，也不要只在遠端手動修改資料表，卻沒有補上遷移檔案。

七、發布出錯時如何恢復

先判斷影響範圍，必要時暫停受影響的購買或業務入口，再保留錯誤記錄、事件狀態和本次發布紀錄。優先修復具體失敗環節，避免一併修改不相關的模組。

如果考慮回復到舊 Worker 版本，請先確認它仍能讀取目前的資料庫結構和資料格式。回復 Worker 版本不會還原 D1、KV 或 R2 的內容，繫結變更和 Durable Objects 遷移也可能限制版本回復。實際條件請見 Cloudflare 版本回復說明。

資料庫還原則是另一項操作，應依正式環境資料庫與內容中準備的紀錄評估。還原到過去的時間點後，付款平台、郵件、已寄送通知和已取用的佇列訊息，不會自動跟著回到過去，需要另外核對。

例如付款已成功，但資料庫被還原到付款前的狀態，不能只因本機訂單消失，就認為這筆交易不存在。應依付款平台紀錄與專案的等冪處理方式，完成對帳和補償。

八、讓驗收結果成為下次發布的依據

保存一份簡短紀錄即可：本次版本、變更內容、遷移和設定變更、已完成的驗收項目，以及暫時未啟用的功能。後續更新時，用它確認哪些行為必須維持。

日常更新繼續使用 npm run deploy:update。新增業務功能請參考常見開發情境，調整內建模組請參考常用功能。備份是否能還原、通知是否有人接收，也應定期實際檢查，而不是只保留一段設定。