前言¶
DeepSeek Harness (DSH) 的 credentials-local 插件將 API 密鑰存儲在 agent 主機上的文件中。文件權限雖然能限制普通用戶，但無法防止模型進程本身訪問密鑰，且難以在多臺機器間統一輪換或審計。
dsh-credentials-vault 插件通過對接 HashiCorp Vault，解決了上述問題。它將提供者密鑰從主機移至 Vault，通過 AppRole 機制提供機器認證，支持無需重啓的密鑰輪換，並利用 Vault 的審計設備記錄所有讀取行爲。
是什麼¶
dsh-credentials-vault 是一個爲 DSH credential seam (ctx.credentials) 提供的 HashiCorp Vault 後端。它由用戶 tancheng33 維護，許可證爲 MIT。
該插件的核心作用是替代 credentials-local，使 DSH 在無頭環境、容器或 CI 代理中運行時，能夠安全地獲取和輪換密鑰，而無需在 agent 主機上保存長期有效的密鑰文件。
核心功能¶
根據已覈實的事實，該插件具備以下能力：
- 集中化輪換：在 Vault 中修改密鑰後，DSH 代理即可生效。
- AppRole 機器認證：代理主機持有的是 AppRole 的 Role ID 和 Secret ID，用於獲取臨時令牌，而非長期密鑰。
- 無需重啓的密鑰輪換：通過 KV v2 的 CAS 機制和實時讀取（默認配置），修改 Vault 中的值後，下一次 LLM 請求即可使用新密鑰，無需重啓 agent 進程。
- 審計支持：利用 Vault 的審計設備記錄所有密鑰讀取操作。
- 環境兼容：支持無頭模式、容器環境以及 CI 代理。
- 併發控制：使用 KV v2 的 Compare-and-Swap (CAS) 機制防止併發寫入衝突。
安裝與啓用¶
安裝該插件需要使用 DSH 的插件管理命令。
dsh plugin --profile <name> add dsh-credentials-vault
安裝後，需要在 DSH 的配置文件中覆蓋默認行爲。DSH 的插件機制通過 cordis.patch.yml 文件來定義實現。
典型用法¶
配置文件（如 cordis.patch.yml）中需要聲明 id 爲 credentials-vault，並填入 Vault 的連接信息。
- id: credentials-vault
config:
address: https://vault.internal:8200
mount: secret
path: dsh
kvVersion: 2
approleMount: approle
roleIdRef: VAULT_ROLE_ID
secretIdRef: VAULT_SECRET_ID
environmentWins: true
cacheTtlMs: 0
timeoutMs: 10000
在 Vault 中，密鑰以扁平映射的形式存儲在指定的路徑下。DSH 會根據憑證引用（如 DEEPSEEK_API_KEY）作爲鍵名讀取。
vault kv put secret/dsh DEEPSEEK_API_KEY=sk-... OPENAI_API_KEY=sk-...
配置說明¶
安裝與配置主要涉及以下參數：
| 配置項 | 說明 |
|---|---|
address |
Vault 服務地址，默認爲 http://127.0.0.1:8200。 |
namespace |
Vault Enterprise 命名空間，空字符串表示不使用。 |
mount |
KV secrets engine 的掛載點，默認爲 secret。 |
path |
密鑰存儲的子路徑，默認爲 dsh。 |
kvVersion |
KV 引擎版本，默認爲 2，支持 CAS 和版本控制。 |
tokenRef |
環境變量名，用於存儲靜態 Token。 |
roleIdRef / secretIdRef |
環境變量名，用於存儲 AppRole 的 Role ID 和 Secret ID。 |
readOnly |
是否拒絕寫入操作，默認爲 false。 |
environmentWins |
環境變量是否覆蓋 Vault 配置，默認爲 true。 |
cacheTtlMs |
緩存時間，0 表示每次請求都讀取 Vault，無緩存。 |
timeoutMs |
請求超時時間，默認爲 10000。 |
注意：配置文件中不應包含任何實際的密鑰。機密信息（如 Token、Role ID、Secret ID）必須通過環境變量注入，由插件讀取。
適用場景與注意¶
該插件適合需要嚴格審計、密鑰集中管理或在 CI/CD 環境中運行的場景。
在使用前，需注意以下限制與特性：
- 僅支持 KV Secrets Engine：插件目前僅支持 HashiCorp Vault 的 KV secrets engine，不支持數據庫、PKI 或 transit 等其他類型的動態密鑰引擎。
- 單一路徑與扁平映射：所有憑證引用必須存儲在同一路徑下的扁平 Key-Value 映射中。
- AppRole 機制：AppRole 認證模式下，插件不支持令牌的自動續約（Renewal），僅支持定期重新登錄。這對於高頻調用的場景影響極小。
- 外部修改無感知：如果通過其他方式（非插件）修改了 Vault 中的密鑰，DSH 代理不會自動感知並更新緩存，除非緩存過期或重啓。
- 運行時權限：該插件不阻止正在運行的 agent 進程使用其已獲取的授權密鑰進行網絡請求。這是密鑰安全邊界的問題，屬於網絡層（如
dsh-egress-guard）的職責，而非憑證加載插件的職責。
總結¶
dsh-credentials-vault 提供了將 DeepSeek Harness 的憑證管理從本地文件遷移至 HashiCorp Vault 的能力。通過 AppRole 機制和無頭支持，它滿足了現代 DevOps 和安全審計的需求。所有配置項和源碼可參考 GitHub 倉庫。
