Docker Compose secrets 與 configs 怎麼選？從環境變數改成檔案掛載

先分清四種設定邊界#

secrets 和 configs 的名稱先在 Compose 頂層宣告，再由每個 service 的同名欄位明確 grant。只宣告 secrets 不會讓所有服務自動看得到它；這個預設阻擋了「新增一個 secret 後整個 Compose project 都能讀」的錯誤假設。

最小的 runtime secrets 與 configs 範例#

下面的例子讓 api 同時取得資料庫密碼和一般設定檔：

1
services:
2
  api:
3
    image: ghcr.io/example/api:1.0
4
    environment:
5
      APP_CONFIG_FILE: /etc/myapp/app.conf
6
      DB_PASSWORD_FILE: /run/secrets/db_password
7
    secrets:
8
      - db_password
9
    configs:
10
      - source: app_config
11
        target: /etc/myapp/app.conf
12

13
secrets:
14
  db_password:
15
    file: ./secrets/db_password.txt
16

17
configs:
18
  app_config:
19
    file: ./config/app.conf

啟動後，Compose 只把 db_password 掛到這個 service 的 /run/secrets/db_password；app_config 則掛到指定的 /etc/myapp/app.conf。DB_PASSWORD_FILE 不是 Compose 的特殊語法，它只有在映像內的應用程式或官方映像支援 _FILE 慣例時才會真的讀取該檔案。若程式只接受 DB_PASSWORD，應修改程式的啟動邏輯，而不是把秘密再複製回 environment。

如果不需要自訂路徑，也可以用短語法：

1
services:
2
  api:
3
    secrets:
4
      - db_password
5
    configs:
6
      - app_config

短語法會使用資源名稱作為容器內的檔名。Linux container 的 config 預設路徑是 /<config-name>；secret 則是 /run/secrets/<secret_name>。需要讓既有程式使用固定路徑時，改用上面的 long syntax 明確寫 target。

secrets 與 configs 真正的差別#

Docker 文件把 secret 定義成不應放進 Dockerfile、source code 或未加密儲存的敏感資料；Compose 以檔案方式提供它，並用 service-level grant 限制可見範圍。Config 也會以檔案掛載，但目的只是讓 service 不必重建 image 就能換一般設定，預設檔案權限可能是 world-readable 0444。

因此不要只因為兩者都「掛成檔案」就混用：

• app.conf 如果包含 host、port、feature flag 或公開的服務設定，可以放 configs。
• db_password.txt、OAuth client secret、TLS private key 或 registry token 應放 secrets。
• 一份混合檔案同時包含公開設定和秘密時，最好拆成兩個輸入，讓 service 只取得實際需要的部分。
• 需要在 image build 階段登入私有 registry 時，請看 Docker Build secrets 與 ARG、ENV 的差異，不要把 build secret 誤當成啟動後的 runtime secret。

file: 不代表本機 secret 已被加密#

本機 Compose 常見的 file: 寫法，實際上仍會由執行 Compose 的使用者讀取 host 檔案。Docker 的 trust model 也提醒，secrets／configs 的 file:、env_file、include 等欄位會讀取 host 可存取的內容，內容還可能在 Compose 載入或 docker compose config 輸出時出現。

這表示要同時做三件事：

1. 將 ./secrets/ 放進 .gitignore，並用最小的 host 檔案權限限制誰可以讀。
2. 不要在公開 CI log 執行會把完整 model 印出來的 docker compose config；要驗證語法時優先用 docker compose config -q。
3. 在 production 優先使用平台已建立的 external secret／config，或由部署平台在啟動時注入，而不是把正式 secret file 放在 application repository。

external: true 的意思是 Compose 不負責建立資源，會向 container platform 查找既有名稱；找不到就失敗。它能把資源生命週期交給平台，但不等於你已經確認平台的加密、備份、權限與 rotation policy，這些仍要另外驗證。

啟動前做不洩漏內容的驗證#

先檢查 Compose model 是否能解析：

1
docker compose config -q

接著在不輸出 secret 內容的前提下，確認路徑與可讀性：

1
docker compose run --rm api sh -eu -c '
2
  test -r /run/secrets/db_password
3
  test -r /etc/myapp/app.conf
4
  printf "%s\n" "runtime files are readable"
5
'

如果 service 看不到檔案，按這個順序查：

1. top-level 名稱是否和 service grant 完全一致。
2. source 是否引用了實際存在的 secret／config。
3. long syntax 的 target 是否和應用程式啟動參數相同。
4. container user 是否具備讀取掛載檔案的權限；不要為了快速通過而把整個容器改成 privileged。
5. 這份 Compose 是否由另一個 -f override 合併，意外移除了 secrets 或 configs。

這和 Docker Compose include 拆分設定檔時的路徑問題是同一種排錯習慣：先看 Compose 最終解析出的 model，再看容器內的實際 mount，不要只讀單一 YAML 檔猜測。

結論是：secrets 解決的是 runtime credential 的傳遞邊界，configs 解決的是不必重建 image 的一般設定；兩者都不能代替 secret manager，也不能抵消 host、Compose CLI、容器內程式與 log 的存取風險。先依資料敏感度拆分，再用 explicit grant 和不洩漏內容的檢查命令驗證，才是可維護的 Compose 設計。

常見問題#