如何安全地在程式碼中管理 API 金鑰與機密
你提交程式碼、推送到 GitHub，然後繼續工作。幾天後你發現你的 API 金鑰從公開儲存庫被爬取，並被用來累積數千美元的雲端費用。這不是罕見的邊緣案例；這是現代開發中最常見且代價最高的安全錯誤之一。原始碼中的硬編碼機密是給攻擊者的禮物，而且避免它們出乎意料地容易。
為什麼硬編碼機密如此危險
當你將 API 金鑰、資料庫密碼或私有權杖直接嵌入程式碼中時，你就失去了對誰能看到它的控制。原始碼會傳播：它被複製、fork、放入 Docker 映像、貼到聊天應用程式，有時甚至被意外發布。一旦機密進入版本控制，它就會永遠留在 Git 歷史中，即使你在之後的提交中刪除它。
攻擊者會主動掃描公開儲存庫，尋找看起來像金鑰的模式。自動化機器人可以在幾分鐘內找到並利用洩漏的金鑰。即使在私有儲存庫中，硬編碼機密也違反了最小權限原則：每個具有讀取權限的開發人員都會自動獲得生產憑證。
規則 #1：絕不硬編碼機密
這聽起來很明顯，但它是基礎。第一步是從原始檔中移除任何機密。這不僅包括像 sk_live_... 這樣明顯的字串，還包括連接字串、私密金鑰和 webhook 簽署機密。
相反，你的程式碼應該在執行時從環境讀取機密。以下是 Python 中的簡單範例：
import os
api_key = os.environ.get("PAYMENT_API_KEY")
if not api_key:
raise RuntimeError("PAYMENT_API_KEY is not set")
在 Node.js 中，你會使用 process.env.PAYMENT_API_KEY。在 Go 中，os.Getenv("PAYMENT_API_KEY")。這個模式是通用的：程式碼期望機密從外部提供。
安全地使用環境變數
環境變數是一個很大的改進，但它們不是萬靈丹。它們可能透過錯誤報告、除錯日誌或程序列表外洩。請遵循以下做法：
- 絕不記錄環境變數。 避免在錯誤處理常式中傾印
process.env或os.environ。 - 僅在本地開發時使用
.env檔案。 從第一天起就將.env加入.gitignore。 - 提供一個包含佔位符值的
.env.example檔案，讓新開發人員知道需要設定什麼。 - 在啟動時驗證必要的機密。 如果缺少金鑰就快速失敗，而不是在生產環境中稍後崩潰。
對於本地開發，像 python-dotenv 或 Node.js 的 dotenv 等函式庫可以輕鬆載入 .env 檔案，而無需硬編碼任何內容。只需記住：該檔案絕不能被提交。
用於生產環境的集中式機密管理工具
環境變數對於小型專案運作良好，但當你有許多服務、多個環境和審計需求時，它們會變得難以管理。專用的機密管理工具透過以下方式解決這些問題：加密儲存機密、以精細策略控制存取，並提供審計軌跡。
常見選項包括：
- HashiCorp Vault – 自託管、高度靈活、支援動態機密。
- AWS Secrets Manager – 與 AWS 服務原生整合、自動輪換。
- Google Secret Manager – 適用於 GCP 的類似服務。
- Azure Key Vault – 適用於 Microsoft Azure 環境。
- Doppler、Infisical 或 1Password Secrets Automation – 跨平台 SaaS 選項。
你的應用程式在啟動時或按需從管理工具取得機密，通常使用 SDK。這將機密儲存與程式碼解耦，並讓你能夠輪換憑證而無需重新部署。
CI/CD 管道中的機密
你的建置和部署管道也需要機密，例如註冊表密碼或部署權杖。大多數 CI 系統（GitHub Actions、GitLab CI、CircleCI）提供加密的機密儲存。使用這些功能，而不是將機密放在管道配置檔案中。
例如，在 GitHub Actions 中，你在儲存庫設定中定義機密，並像這樣引用它們：
steps:
- name: Deploy
run: ./deploy.sh
env:
API_TOKEN: ${{ secrets.DEPLOY_API_TOKEN }}
小心來自 fork 的拉取請求：預設情況下，機密不會傳遞給由 fork PR 觸發的工作流程，這是好事。絕不在日誌中回顯機密；如果你的 CI 系統支援，請遮蔽它們。
定期輪換機密
即使儲存完美，機密也可能透過其他管道外洩：被入侵的筆記型電腦、配置錯誤的日誌服務或離職員工。輪換限制了暴露的時間窗口。
根據敏感性設定輪換排程。高價值金鑰（支付閘道、管理 API）可能每 30–90 天輪換一次。較低風險的金鑰可以較少輪換。盡可能自動化輪換：AWS Secrets Manager 和 Vault 可以自動輪換資料庫憑證。
輪換時，確保你的應用程式在過渡期間能處理多個有效機密。一個常見模式是在短時間內同時接受舊機密和新機密，然後停用舊機密。
偵測並防止外洩
預防勝於治療，但偵測是你的安全網。使用 pre-commit 掛鉤在提交前掃描機密。像 git-secrets、trufflehog 或 gitleaks 等工具可以捕捉意外提交。
同時在你的 Git 託管平台（GitHub、GitLab、Bitbucket 都提供此功能）上啟用機密掃描。如果機密確實漏掉了，立即撤銷並輪換。刪除提交是不夠的；假設機密一接觸遠端儲存庫就已經被洩露。
機密儲存方法比較
| 方法 | 最適合 | 風險 |
|---|---|---|
| 環境變數 | 小型應用、本地開發 | 透過日誌、程序檢查外洩 |
.env 檔案 |
本地開發 | 意外提交、無加密 |
| 機密管理工具 | 生產環境、團隊 | 複雜性、增加依賴 |
| CI/CD 機密儲存 | 建置和部署管道 | 僅限於管道範圍 |
常見問題
我可以將機密儲存在私有儲存庫中嗎？
不行。私有儲存庫仍有許多具有讀取權限的使用者和整合。機密可能透過 fork、CI 日誌或被入侵的帳戶外洩。即使對於私有程式碼，也始終使用環境變數或機密管理工具。
如果我意外提交了機密該怎麼辦？
立即撤銷並輪換該機密。僅僅刪除提交或重寫歷史是不夠的，因為機密可能已經被快取或複製。將其視為已洩露並替換它。
環境變數對生產環境來說足夠安全嗎？
它們比硬編碼好，但對於大規模生產環境並不理想。環境變數可能在崩潰轉儲、除錯端點或程序列表中暴露。對於生產環境，使用具有存取控制和審計的專用機密管理工具。
當你需要快速格式化或驗證包含非敏感設定的 JSON 配置檔案時，JSON Formatter 可以幫助你在語法錯誤破壞部署之前發現它們。記住：絕不將實際機密貼到線上工具中。