Bohdan-Meshcheriakov/deploy-data-clerk

在 Data Clerk 上部署

此應用程式運行於 Data Clerk，這是一個由操作員（人類，聯絡方式請見 PROJECT.md）管理的小型 Kubernetes 叢集。此儲存庫的擁有者通常並非基礎架構人員。他們永遠不需要觸碰伺服器、Kubernetes 或雲端控制台：他們只需推送到 main 分支，叢集便會處理其餘事項。 你的職責是維持這個狀況：在儲存庫內工作，遵守以下合約，當真正需要叢集端處理時，請撰寫一個清晰的請求給操作員，而不是自行臨時應變。

用簡單的語言向使用者解釋事情（例如「你的網站大約五分鐘後會更新」），而不是使用 Kubernetes 術語。

從這裡開始

1. 閱讀 deploy-data-clerk/PROJECT.md。它包含了此專案的各項值：公開 URL、部署資料夾、映像檔名稱、連接埠、遷移指令、資源限制、操作員是誰。以下所有提到「從 PROJECT.md 取得」的地方都指該檔案。如果 PROJECT.md 中的資料夾名稱與 deploy-data-clerk/ 不同（舊專案使用 deploy/），請使用 PROJECT.md 中指定的名稱。
2. 沒有 PROJECT.md，或者它仍然包含 __PLACEHOLDER__ 值？表示該專案尚未入駐：請遵循 references/new-project.md。
3. 正在編寫或更改 Dockerfile、決定如何組織應用程式結構，或堆疊不是 Node？請閱讀 references/stacks.md（適用於任何語言、全端 vs 分離式前端+API、FastAPI、Go）。
4. 在機器上執行第一個機密相關任務之前，請確保工具能正常運作：執行 sops --version 以及測試解密（sops decrypt <deploy folder>/secrets.env > /dev/null）。如果任一指令失敗，請遵循 references/setup-tools.md。

變更如何到達正式環境

什麼變更	發生什麼事	正式環境生效時間
程式碼（推送到 main）	GitHub Actions 建置 Docker 映像檔並推送；叢集偵測到新的映像檔標籤並進行更新	~3-7 分鐘（建置時間 + ~1 分鐘）
secrets.env（推送到 main）	叢集每 5 分鐘重新讀取部署資料夾，解密它，更新應用程式的環境變數並重新啟動應用程式	~5 分鐘
migrations/ 中的新檔案	在新版本啟動前自動執行	伴隨程式碼部署
main 以外的任何變更	不會發生任何事。分支和 PR 不會被部署	—

更新過程很謹慎：新版本會與舊版本並行啟動，先執行遷移，只有當新版本通過健康檢查後流量才會切換。如果建置、遷移或健康檢查失敗，舊版本會繼續提供服務，網站維持正常運作。部署失敗代表「變更未生效」，而不是「網站已關閉」。

檢查部署狀態：gh run list --workflow "Deploy to cluster" --limit 3（或 GitHub 上的 Actions 標籤頁），然後開啟公開 URL。要在沒有程式碼變更的情況下重新部署：gh workflow run "Deploy to cluster"，這會建置一個全新的映像檔標籤，因此應用程式會以全新的環境重新啟動。

合約（維持部署運作的關鍵）

每個規則的存在都是因為違反它會默默失敗或導致資料遺失。請遵守這些規則，並在使用者提出可能違反規則的請求時告知他們。

• 監聽 $PORT（PROJECT.md 中的連接埠，由叢集設定），使用 0.0.0.0，而非 localhost。
• 映像檔從 <deploy folder>/Dockerfile 針對 linux/amd64 架構建置，並以非 root 使用者身份執行。不能是 root、不能使用 1024 以下的連接埠、不能有額外的 Linux 權限。
• 映像檔標籤格式為 YYYYMMDDHHMMSS-<shortsha>。 叢集會部署數字最大的標籤，並忽略任何不符合此格式的標籤。絕對不要更改 .github/workflows/deploy-cluster.yml 中的標籤步驟。
• 容器的磁碟在每次部署和重新啟動時都會被清除。 永遠不要將使用者上傳的檔案、SQLite 檔案或任何有價值的資料存放在本機磁碟中。將資料存放在資料庫中；對於檔案（照片、影片），請向操作員請求物件儲存空間。
• 健康檢查： 叢集會探測 PROJECT.md 中指定的健康檢查路徑（建議使用 /healthz）。使其能夠快速返回 200 狀態碼，不要進行資料庫呼叫或頁面渲染，否則緩慢的資料庫會讓叢集誤判應用程式已當機。
• DATABASE_URL 來自叢集本身。永遠不要將它放入 secrets.env（它會覆蓋真正的值），也永遠不要在映像檔建置時設定它。
• 運行時 vs 建置時。 secrets.env 僅在運行時才會傳遞給應用程式。映像檔在 GitHub Actions 中建置時沒有它。任何在建置時內嵌到前端程式碼中的變數（VITE_*、NEXT_PUBLIC_*、REACT_APP_*）都不能來自 secrets.env：請在運行時於伺服器端讀取這些值並傳遞給頁面，或者（如果不是機密）將它們提交到程式碼中。
• 應用程式在缺少時自行產生的機密（auth/session secret、加密鹽、推送金鑰）：請將它們設定在 secrets.env 中。否則每次重新啟動都會產生新的機密，導致使用者被登出、推送訂閱中斷等問題。
• 遷移必須對舊版本安全。 大約有一分鐘的時間，兩個版本會同時針對新的資料庫綱要運行。請自由地新增資料行和表格。重新命名或刪除則需要分兩次部署：首先停止使用它，然後再移除它。詳情請見 references/database.md。

環境變數與機密

所有運行時設定都存放在 <deploy folder>/secrets.env 中，並使用 sops 加密後提交。只有值被加密；金鑰名稱保持可讀。請使用 sops 本身來更改它。永遠不要將其解密到你可能會提交的檔案中，也永遠不要在聊天記錄或日誌中印出機密值。

sops set deploy-data-clerk/secrets.env '["STRIPE_SECRET_KEY"]' '"sk_live_..."'
sops unset deploy-data-clerk/secrets.env '["OLD_KEY"]'
sops decrypt deploy-data-clerk/secrets.env | cut -d= -f1

然後提交並推送到 main；大約 5 分鐘後生效。當使用者需要提供值（例如從某個儀表板取得的 API 金鑰）時，請讓他們自己執行 sops set 指令，或者只將值貼到他們自己的終端機中。完整指南（金鑰、存放位置、輪替、注意事項）在 references/secrets.md 中。

資料庫

Postgres 18，由操作員管理。應用程式透過 DATABASE_URL 取得自己的資料庫和使用者。綱要變更是透過遷移檔案處理，這些檔案會在部署時自動套用（references/database.md）。

備份： 每天 UTC 時間 03:00 進行完整備份，加上每次變更的連續日誌記錄，並存放在 Google Cloud Storage 中（非伺服器上）。操作員可以將資料庫還原到 過去 7 天內的任意時間點。因此，如果資料被刪除或遷移出錯，請不要驚慌或嘗試手動修復：記下事件發生的時間，並向操作員請求還原（模板在 references/troubleshooting.md 中）。還原會倒回整個資料庫，因此該時間點之後所做的變更將會遺失。

你的程式碼可能需要的網路資訊

• 流量路徑：訪客 → Cloudflare → Traefik（叢集入口）→ 應用程式。HTTPS 憑證是自動的。應用程式本身透過 $PORT 使用純 HTTP 通訊；X-Forwarded-Proto: https 標頭表示原始請求是 HTTPS。請信任代理伺服器標頭，並且不要在應用程式中重新導向到 HTTPS（會造成迴圈）。
• 真實訪客 IP： 讀取 CF-Connecting-IP 標頭。X-Forwarded-For 包含的是 Cloudflare 的位址，因此基於此標頭進行速率限制會將所有訪客歸為同一類。
• Traefik 會新增這些標頭：HSTS（2 年，preload）、X-Content-Type-Options: nosniff、X-Frame-Options: SAMEORIGIN（網站無法在其他網域中以 iframe 嵌入）。額外的標頭（CSP、用於 SharedArrayBuffer 的 COOP/COEP、允許 iframe）可根據請求由操作員設定。
• Ingress 不會壓縮回應。Cloudflare 會壓縮常見的文字類型；若要完全控制，請在應用程式中壓縮或提供預先壓縮的靜態檔案。
• 長連線（SSE、websocket）沒問題，但 Cloudflare 會中斷空閒約 100 秒的連線。請每 ~30 秒發送一次心跳訊號，並在客戶端進行重新連線。
• 對外連線： 應用程式可以呼叫任何公開網際網路端點（任何連接埠）。這包括 LLM API、Stripe、電子郵件、S3 以及使用其公開端點的受管資料庫或 Redis（如 Neon、Supabase、Atlas、Upstash）。它無法連線到私有網路（VPC peering、PrivateLink、私有 IP）或叢集上的其他專案。入站流量僅透過公開 URL 進入。
• 第三方服務： 將它們的金鑰和 URL 放入 secrets.env。如果服務需要 IP 允許清單，叢集有一個靜態對外 IP：請向操作員索取（未公開），並告知使用者該 IP 與叢集上的其他專案共享。伺服器位於美國中部，因此外部資料庫偏好選擇美國中部/美國東部區域（歐盟資料庫每次查詢會增加約 100 毫秒延遲）。外部資料庫是使用者自己的責任：Data Clerk 的備份不涵蓋它。對於慢速的 LLM 呼叫，請串流回應或將其作為背景任務執行；等待超過 ~100 秒的瀏覽器請求會被中斷。
• 資源有上限（PROJECT.md 中的記憶體/CPU）。超過記憶體限制會終止並重新啟動應用程式。如果發生這種情況，請向操作員請求更多資源，而不是在程式碼中硬撐。
• 應用程式只運行一個副本（一個 replica）。請不要依賴記憶體狀態能在部署後持續存在，並將會話儲存在資料庫或簽署的 cookie 中。

只有操作員才能做的事

使用者沒有叢集存取權限，這是設計使然。請為操作員撰寫一個簡短的請求（模板請見 references/troubleshooting.md），用於：

新網域或子網域 · 更多記憶體/CPU · 檔案/物件儲存 · 資料庫還原 · 應用程式日誌或當機原因 · 更改安全標頭 · 更改遷移或啟動指令、連接埠或健康檢查路徑 · 排程任務（cron） · 額外服務（Redis、佇列） · 同一個專案中的第二個應用程式 · 入駐新的儲存庫。

更多細節

• references/stacks.md：任何語言的通用合約；全端 vs SPA + API vs 靜態網站；Node、Python FastAPI、Go 及其他堆疊。
• references/new-project.md：入駐一個儲存庫（需要新增的檔案、要向操作員請求什麼、每個堆疊的 Dockerfile）。
• references/secrets.md：sops 深入說明、金鑰檔案、輪替、建置時變數。
• references/database.md：遷移、連線字串、備份、資料修正。
• references/setup-tools.md：在 macOS、Linux 和 Windows 上安全安裝 sops/git/gh。執行 scripts/install-tools.sh 或 scripts/install-tools.ps1。
• references/troubleshooting.md：「我的變更沒有生效」、「網站已關閉」、常見錯誤、操作員請求模板。
• assets/：Dockerfile 模板（Node、Python、Go）以及部署工作流程、kustomization.yaml、.sops.yaml、.gitattributes 和 PROJECT.md 的模板。