前言¶
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 仓库。
