E EmDash CMS Everything Guides, use cases, plugins, templates
繁體中文

金鑰與金鑰管理

本頁內容

EmDash 在預覽、留言、認證、儲存和外掛中使用少量金鑰。本頁是完整清單：每個金鑰的來源、儲存位置、輪換方法以及遺失後的影響。

概覽

金鑰來源儲存位置遺失影響
EMDASH_ENCRYPTION_KEY維運人員 (emdash secrets generate)僅環境變數 / Worker 金鑰加密的外掛金鑰變得不可恢復（靜態加密上線後）
預覽金鑰自動產生（env 覆蓋）options 表 (emdash:preview_secret)已發放的預覽連結失效；新連結正常
IP 鹽值自動產生（env 覆蓋）options 表 (emdash:ip_salt)留言速率限制連續性重設
工作階段和 API 權杖按工作階段/權杖產生工作階段儲存 / 資料庫（僅雜湊值）無影響 — 明文從不儲存
OAuth 提供者憑證您（Google/GitHub 主控台）環境變數該提供者的登入停止直到替換
Turnstile 金鑰您（Cloudflare 儀表板）環境變數留言 CAPTCHA 驗證失敗
S3 憑證您（儲存提供者）環境變數或設定媒體上傳/下載失敗直到替換
外掛金鑰您（管理後台設定 UI）資料庫（外掛設定/儲存）在管理後台重新輸入
CLI 憑證emdash login / emdash plugin publish 裝置流程~/.config/emdash/auth.json（模式 0600）重新執行裝置流程
登錄檔 CLI 憑證emdash-plugin atproto OAuth~/.emdash/oauth/、~/.emdash/credentials.json（模式 0600）重新登入；身分存於您的 PDS

加密金鑰

EMDASH_ENCRYPTION_KEY 是網站用於靜態加密外掛金鑰的金鑰。它由維運人員提供，從不儲存在資料庫中 — 資料庫只包含密文，因此洩漏的備份不會暴露金鑰。

產生一個並設為環境變數（或 Worker 金鑰）：

npx emdash secrets generate
# emdash_enc_v1_<43 個 base64url 字元>

# Cloudflare:
wrangler secret put EMDASH_ENCRYPTION_KEY

格式為 emdash_enc_v1_ 後接 32 位元組隨機資料的無填充 base64url 編碼。金鑰在執行時啟動時驗證；格式錯誤的值會記錄面向維運人員的錯誤，但不會中斷請求路徑。

輪換

變數接受逗號分隔的金鑰列表。第一個項目是主金鑰，用於新的寫入；所有項目都會嘗試用於解密。每個加密值都標記了 8 字元的金鑰指紋（kid，可透過 emdash secrets fingerprint <key> 列印），因此執行時會自動選擇正確的金鑰。

輪換方法：產生新金鑰，新增到列表前面（EMDASH_ENCRYPTION_KEY="新金鑰,舊金鑰"），重新部署，在現有值重新加密後移除舊金鑰。

產生的網站金鑰

兩個金鑰在首次使用時自動產生並持久化到 options 表中，因此在請求、部署和隔離區間保持穩定。產生是原子性的 — 並行的冷啟動會收斂到一個值。

預覽金鑰

簽署預覽 URL（HMAC）。儲存為 emdash:preview_secret；32 位元組隨機資料，base64url。

  • 覆蓋： 如果需要跨多個程序使用相同金鑰或出於稽核原因固定金鑰，請設定 EMDASH_PREVIEW_SECRET（舊別名：PREVIEW_SECRET）。環境變數始終優先於儲存值。
  • 輪換： 刪除 emdash:preview_secret 列（或變更 env 變數）並重新部署。影響：之前發放的預覽連結停止驗證。其他不受影響 — 下次預覽請求時會產生新金鑰（或從 env 讀取）。
  • 遺失時： 無不可恢復的內容。預覽連結設計上就是短期的。

參閱預覽指南了解預覽 URL 的建構和驗證方式。

IP 鹽值

為留言速率限制中使用的留言者 IP 位址 SHA-256 雜湊（留言上的 ip_hash）加鹽。儲存為 emdash:ip_salt。網站特定，因此雜湊在 EmDash 安裝之間不可關聯。

  • 覆蓋： 設定 EMDASH_IP_SALT。為向後相容，也會查詢 EMDASH_AUTH_SECRET / AUTH_SECRET — 歷史上從這些值推導鹽值的安裝保持穩定的雜湊。
  • 輪換： 變更 env 變數或刪除 emdash:ip_salt 列。影響：新留言提交產生不同的雜湊值，所有人的速率限制計數重新開始。現有留言及其儲存的雜湊不受影響。
  • 遺失時： 無資料遺失。僅速率限制連續性重設。

工作階段和 API 權杖

  • 工作階段使用 Astro 的工作階段儲存（Cloudflare 上的 Workers KV，Node 上的檔案系統）。Cookie 攜帶不透明的工作階段 ID；沒有需要管理的簽署金鑰。登出以結束工作階段，或清除工作階段儲存（例如 KV 命名空間）以強制所有人重新登入。
  • API 權杖（ec_pat_、ec_oat_、ec_ort_ 前綴）是不透明的 256 位元隨機值；僅儲存其 SHA-256 雜湊。明文在建立時顯示一次。透過在管理後台撤銷並重新建立來輪換。
  • 邀請、魔法連結和恢復權杖是單一用途的，以 SHA-256 雜湊形式儲存在 auth_tokens 中，且有時間限制（邀請 7 天，魔法連結 15 分鐘）。

無需主動備份或輪換：資料庫洩漏僅暴露雜湊值，每個權杖都可以從管理後台撤銷或重新發放。

使用者提供的服務憑證

外部服務的憑證從環境變數讀取，從不寫入資料庫。在提供者處輪換，更新變數，重新部署。

服務變數
Google 登入EMDASH_OAUTH_GOOGLE_CLIENT_ID、EMDASH_OAUTH_GOOGLE_CLIENT_SECRET（或無前綴別名）
GitHub 登入EMDASH_OAUTH_GITHUB_CLIENT_ID、EMDASH_OAUTH_GITHUB_CLIENT_SECRET（或無前綴別名）
Marketplace 發佈（CI）EMDASH_MARKETPLACE_TOKEN
Turnstile（留言）EMDASH_TURNSTILE_SECRET_KEY（或 TURNSTILE_SECRET_KEY）
S3 相容儲存S3_ACCESS_KEY_ID、S3_SECRET_ACCESS_KEY、S3_ENDPOINT、S3_BUCKET、S3_REGION

在 Cloudflare 上使用 wrangler secret put 設定；本機放在 .env 中。透過繫結使用 R2 無需憑證 — 存取由 wrangler.jsonc 中的繫結授權，這是 Workers 上推薦的設定。參閱儲存選項。

外掛金鑰

外掛用 type: "secret" 宣告的設定（郵件提供者 API 金鑰、表單 CAPTCHA 等）在管理 UI 中輸入並儲存在資料庫中 — 在 options 表的 plugin:<id>:settings:<key> 下，或在外掛的鍵值儲存中。儲存的金鑰是否回傳到管理 UI 取決於外掛；編寫良好的外掛僅回傳「值已設定」旗標而非金鑰本身（內建的表單外掛就是這樣做的）。

  • 輪換： 在提供者處輪換金鑰並將新值貼到外掛的設定頁面。立即生效。
  • 遺失時： 在管理後台重新輸入值。無其他相依。

CLI 憑證

emdash CLI 持有兩種憑證，都在 ~/.config/emdash/auth.json（遵循 XDG_CONFIG_HOME）中，以僅擁有者權限（0600）建立：

  • 網站權杖 — emdash login 透過 OAuth 裝置流程對您的 EmDash 實例進行認證，並將結果權杖按實例 URL 索引儲存。emdash logout 將其移除；每次呼叫時 --token 或 EMDASH_TOKEN 覆蓋儲存的權杖。
  • Marketplace 權杖 — emdash plugin publish 透過 GitHub 裝置流程對 EmDash Marketplace 進行認證，並將結果 JWT 以 marketplace:<origin> 索引儲存。對於 CI 發佈，請設定 EMDASH_MARKETPLACE_TOKEN — 它優先於儲存的憑證。

遺失檔案是無害的：重新執行 emdash login（或 emdash plugin publish，它會重新執行裝置流程）。

外掛登錄檔 CLI 憑證

獨立的 emdash-plugin CLI（套件 @emdash-cms/plugin-cli）面向實驗性的 AT Protocol 登錄檔。在那裡發佈與您的 AT Protocol 身分（您的發佈者 DID）繫結 — 網站本身不持有發佈憑證，安裝會根據歸屬於該 DID 的發佈記錄中的校驗和驗證製品。

  • 透過 atproto OAuth 認證。OAuth 工作階段/狀態 blob 存在於 ~/.emdash/oauth/，發佈者身分（DID、handle、PDS）快取在 ~/.emdash/credentials.json；兩者都以僅擁有者權限寫入。
  • 在 CI 中，透過 EMDASH_PUBLISHER_DID、EMDASH_PUBLISHER_HANDLE 和 EMDASH_PUBLISHER_PDS 提供身分；EMDASH_REGISTRY_URL 覆蓋登錄檔主機。CI 的自動 publish 仍需要執行器上 ~/.emdash/oauth/ 中的 OAuth 工作階段檔案 — 環境變數本身不攜帶 OAuth 工作階段。
  • 發佈存取的輪換或撤銷在您的 AT Protocol 帳戶（例如應用程式密碼）中進行，而非在 EmDash 中。參閱 Atmosphere auth。

輪換快速參考

我想要…操作方法
輪換加密金鑰在前面新增新金鑰：EMDASH_ENCRYPTION_KEY="新金鑰,舊金鑰"，重新部署，之後移除舊金鑰
使所有預覽連結失效刪除 emdash:preview_secret 選項列（或變更 env 覆蓋）
重設留言速率限制雜湊變更 EMDASH_IP_SALT（或刪除 emdash:ip_salt 選項列）
撤銷洩漏的 API 權杖管理後台 → 使用者 → API 權杖 → 撤銷，然後建立替代
終止所有工作階段清除工作階段儲存（Workers KV 命名空間 / 工作階段目錄）
替換提供者憑證在提供者處輪換，更新 env 變數，重新部署
替換外掛 API 金鑰在提供者處輪換，在外掛的管理後台設定中重新輸入