環境變數
Environment Variables
什麼是環境變數?
- 存放在程式碼之外的設定值
- 安全保管 API 金鑰與密碼
- 依環境更換數值
開始使用環境變數後,程式碼的性質本身就會改變。移除金鑰的程式碼,就能成為可以對外公開的資產;開發、測試與正式的伺服器,即使上傳同一份程式碼,各伺服器也會讀取自身環境的數值來運作。每次部署時不必再打開檔案,手動修改伺服器位址或密碼,因此測試用設定原封不動被帶上正式伺服器的意外也會隨之減少。
環境變數裡存放的值,性質分為兩類。一類是 API 金鑰、資料庫密碼、權杖(Token)這類,一旦外洩就會連帶損失金錢與客戶資料的機密值;另一類則是伺服器位址、日誌等級、功能開關(on/off)等依環境而異的設定值。前者需要提高保管等級。一個人使用的階段用 .env 檔案就夠了,但團隊加入後,通常會改用 GitHub Actions Secrets 或部署平台的環境變數介面;若涉及客戶資料,則會進一步採用 AWS Secrets Manager 等專用保險箱,並規定每季更換一次金鑰的規則。
有一個需要留意的界線。.env 不是加密。它只是記錄名稱與值的純文字檔,任何能存取該伺服器或該筆電的人都能打開。因此實務上會將檔案分離與誰能進入該伺服器同等看待管理,並為每把金鑰設定每月用量上限與呼叫通知,讓即使外洩,損失也能控制在上限之內。
現場最常出錯的地方,就是'建立了 .env 檔,現在就安全了'這種想法。即使之後才加上 gitignore,已經上傳的金鑰會留在提交紀錄裡,即使把儲存庫設為私人,翻閱過去的紀錄仍能找到。瀏覽器端使用的前端變數(如 NEXT_PUBLIC_ 系列),名稱雖是環境變數,但對所有使用者都是公開的,這點也常被忽略;另外,把錯誤紀錄整段貼進 AI 對話視窗的那一刻,金鑰也會一併送出。外洩的金鑰不是刪除就好,唯一的解法是廢棄並重新發行。
這是作業系統向程式傳遞設定的古老方式,後來演變為將程式碼與設定、機密值分離的實務原則。
以下以虛構案例說明。員工約 140 人規模的化妝品通路商 A 公司,沒有開發人員的行銷團隊,邊問 AI 邊在兩週內做出了商品諮詢聊天機器人。為了讓團隊成員互相試用,他們把程式碼上傳到 GitHub 公開儲存庫。十天後,原本每月約 KRW 180,000 (≈ US$135) 的 AI API 使用費,被收取了 KRW 4,700,000 (≈ US$3,520)。
- 行銷團隊的朴代理看到付款通知後回報:'我們的聊天機器人,試用過的人不到 300 人吧?',IT 團隊則在日誌中確認了來自海外 IP 約 4 萬次的呼叫。
- IT 營運部金副理在30分鐘內就廢棄了舊金鑰並重新發行新金鑰,但為了清除仍留在提交紀錄(commit history)中的金鑰,最後不得不整個重建儲存庫。
- 之後團隊將金鑰移到 .env 檔案並加入 gitignore,同時在儲存庫中保留只列出變數名稱的 .env.example,讓新成員 15 分鐘內就能完成設定。
- 金次長將開發用與正式用的金鑰分開,並為每個帳號設定每月 KRW 300,000 (≈ US$225) 的上限與用量通知,讓超過上限時呼叫自動停止。
- 對 26 名非開發人員進行 40 分鐘的內部教育後,六個月內金鑰外洩為 0 件,API 費用也從每月 KRW 4,700,000 (≈ US$3,520) 降至 KRW 210,000 (≈ US$155)。
Ja-ryong Gu
金鍾赫