HashiCorp 配置
概述
本节说明如何配置 Zabbix，以便从 HashiCorp Vault KV Secrets Engine - Version 2 检索密钥。
应按照官方 HashiCorp 文档 中的说明部署并配置 vault。
要了解如何在 Zabbix 中配置 TLS，请参见 密钥存储。
获取数据库凭据
要成功检索包含数据库凭据的密文，需要同时配置以下两项：
- Zabbix 服务器/proxy
- Zabbix 前端
服务器/proxy
要配置 Zabbix 服务器 或 proxy， 请在配置文件中指定以下配置参数：
Vault- 应使用的 vault 提供程序；VaultToken- vault 认证令牌（详情请参见 Zabbix 服务器/proxy 配置文件）；不能与VaultAppRoleID一起使用；VaultAppRoleID和VaultAppSecretID- vault 认证角色 ID 和 secret ID（详情请参见 Zabbix 服务器/proxy 配置文件）；不能与VaultToken一起使用；VaultURL- vault 服务器 HTTP[S] URL；VaultDBPath- 包含数据库凭据的 vault 密文路径（仅当未指定 DBUser 和 DBPassword 时可使用）；Zabbix 服务器或 proxy 将通过键 "password" 和 "username" 检索凭据；VaultPrefix- 根据 vault 不同而定的 vault 路径或查询自定义前缀；如果未指定，将使用最合适的默认值。
Vault、VaultToken（或 VaultAppRoleID/VaultAppSecretID）、VaultURL 和 VaultPrefix 配置参数也会在 Zabbix 服务器处理密文 vault 宏时用于 vault 认证（如果 Zabbix proxy 已配置，则 proxy 也会使用）。Zabbix 服务器和 proxy 不会打开包含来自 VaultDBPath 的数据库凭据的 vault 密文宏。
强烈建议为不同的 proxy 使用不同的令牌。
Zabbix 服务器和 Zabbix proxy 在启动时会从 zabbix_server.conf 和 zabbix_proxy.conf 中读取与 vault 相关的配置参数。
此外，Zabbix 服务器和 Zabbix proxy 会在启动时读取一次 VAULT_TOKEN 环境变量，并将其取消设置，以便 fork 出的脚本无法访问；如果 VaultToken 和 VAULT_TOKEN 参数都包含值，则会报错。
示例
- 在
zabbix_server.conf中，指定以下参数。
使用 VaultToken：
Vault=HashiCorp
VaultToken=hvs.CAESIIG_PILmULFYOsEyWHxkZ2mF2a8VPKNLE8eHqd4autYGGh4KHGh2cy5aeTY0NFNSaUp3ZnpWbDF1RUNjUkNTZEg
VaultURL=https://127.0.0.1:8200
VaultDBPath=database
VaultPrefix=/v1/secret/data/zabbix/或者，使用 VaultAppRoleID：
Vault=HashiCorp
VaultAppRoleID=6f1567f1-538d-7d70-e8e4-5d3e59471b2e
VaultAppSecretID=89dac8b1-f7d6-96a7-2ecf-f94d2de3d6f1
VaultURL=https://127.0.0.1:8200
VaultDBPath=database
VaultPrefix=/v1/secret/data/zabbix/- 运行以下 CLI 命令，在 vault 中创建所需的 secret：
# 如果尚未启用，请启用 "secret/" 挂载点；注意必须使用 "kv-v2"。
vault secrets enable -path=secret/ kv-v2
# 在挂载点 "secret/" 和路径 "zabbix/database" 下，使用键 username 和 password 写入新的 secret。
vault kv put -mount=secret zabbix/database username=zabbix password=<password>
# 测试 secret 是否已成功添加。
vault kv get secret/zabbix/database
# 最后使用 Curl 进行测试；注意需要在挂载点后手动添加 "data"，并在挂载点前添加 "/v1"，另请参见 --capath 参数。
curl --header "X-Vault-Token: <VaultToken>" https://127.0.0.1:8200/v1/secret/data/zabbix/database- 结果是，Zabbix 服务器将检索以下用于数据库认证的凭据：
- 用户名: zabbix
- 密码: <password>
前端
Zabbix 前端可以在前端 安装 期间，或通过更新前端配置文件（zabbix.conf.php）来配置为从 vault 中检索数据库凭据。
如果自上次前端安装以来 vault 凭据已发生更改，请重新运行前端安装，或更新 zabbix.conf.php。另请参见：更新现有配置。
在 前端安装 期间，必须在 Configure DB Connection 步骤中指定连接参数。
使用 token 认证的配置示例：
使用 AppRole 认证的配置示例：
| Parameter | Mandatory | Default value | Description |
|---|---|---|---|
| Store credentials in | no | 选择 HashiCorp Vault。 | |
| Vault API endpoint | yes | https://localhost:8200 | 指定用于连接 vault 的 URL，格式为 scheme://host:port |
| Vault prefix | no | /v1/secret/data/ | 为 vault 路径或查询提供自定义前缀。如果未指定，则使用默认值。 示例： /v1/secret/data/zabbix/ |
| Vault secret path | yes | 用于检索数据库凭据的 secret 路径，凭据将通过键 "password" 和 "username" 获取。 示例： database |
|
| Vault authentication type | no | 选择 vault 认证类型： Token - 使用 token 认证； AppRole - 使用 AppRole 认证方法。 |
|
| Vault authentication token | yes | 提供一个用于只读访问 secret 路径的认证 token。 有关创建 token 和 vault 策略的信息，请参见 HashiCorp 文档。 仅当选择 Token 作为 vault 认证类型时，此字段才可用。 |
|
| Vault authentication role ID | yes | 提供 AppRole 的 role ID。 有关 AppRole 的信息，请参见 HashiCorp 文档。 仅当选择 AppRole 作为 vault 认证类型时，此字段才可用。 |
|
| Vault authentication secret ID | yes | 提供针对 AppRole 签发的 secret ID。 有关 AppRole 的信息，请参见 HashiCorp 文档。 仅当选择 AppRole 作为 vault 认证类型时，此字段才可用。 |
获取用户宏值
要使用 HashiCorp Vault 存储 Vault secret 用户宏值，请确保：
- Zabbix 服务器/proxy 已配置为可与 HashiCorp Vault 配合工作。
- Administration > General > Other 中的 Vault provider 参数已设置为 "HashiCorp Vault"（默认）。
Zabbix 服务器（以及 Zabbix proxy，如果已配置）需要能够从 vault 访问 Vault secret 宏值。 Zabbix 前端不需要此类访问权限。
宏值应包含一个引用路径（格式为 path:key，例如 macros:password）。
在 Zabbix 服务器/proxy 配置期间指定的认证令牌（通过 VaultToken 参数）必须对该路径提供只读访问权限。
有关 Zabbix 如何处理宏值的详细信息，请参见 Vault secret macros。
路径语法
正斜杠（"/"）和冒号（":"）是保留字符。
正斜杠只能用于分隔挂载点和路径（例如，secret/zabbix，其中挂载点为 "secret"，路径为 "zabbix"）。对于 Vault 宏，冒号只能用于分隔路径/查询和键。
如果需要创建一个名称中包含正斜杠分隔符的挂载点（例如，foo/bar/zabbix，其中挂载点为 "foo/bar"，路径为 "zabbix"，可以编码为 "foo%2Fbar/zabbix"），或者挂载点名称或路径中需要包含冒号，则可以对正斜杠和冒号进行 URL 编码。
示例
- 在 Zabbix 中，添加一个类型为 "Vault secret" 的用户宏 {$PASSWORD}，其值为
macros:password
- 运行以下 CLI 命令，在 vault 中创建所需的 secret：
# 如果尚未启用，请启用 "secret/" 挂载点；注意必须使用 "kv-v2"。
vault secrets enable -path=secret/ kv-v2
# 在挂载点 "secret/" 和路径 "zabbix/macros" 下，使用键 "password" 放入新的 secret。
vault kv put -mount=secret zabbix/macros password=<password>
# 测试 secret 是否已成功添加。
vault kv get secret/zabbix/macros
# 最后使用 Curl 测试；注意需要在挂载点后手动添加 "data"，并在挂载点前添加 "/v1"，另请参见 --capath 参数。
curl --header "X-Vault-Token: <VaultToken>" https://127.0.0.1:8200/v1/secret/data/zabbix/macros- 结果是，Zabbix 将把宏 {$PASSWORD} 解析为以下值：<password>
更新现有配置
要更新用于从 HashiCorp Vault 获取密钥的现有配置：
-
按照 Database credentials 部分中的说明，更新 Zabbix 服务器或 proxy 配置文件参数。
-
通过重新配置 Zabbix 前端并指定所需参数来更新 DB 连接设置，具体请参见 Frontend 部分。 要重新配置 Zabbix 前端，请在浏览器中打开前端设置 URL：
- 对于 Apache: http://<server_ip_or_name>/zabbix/setup.php
- 对于 Nginx: http://<server_ip_or_name>/setup.php
或者，也可以在 前端配置文件（zabbix.conf.php）中设置这些参数。
使用 Vault token：
$DB['VAULT'] = 'HashiCorp';
$DB['VAULT_URL'] = 'https://localhost:8200';
$DB['VAULT_DB_PATH'] = 'database';
$DB['VAULT_TOKEN'] = 'hvs.CAESIIG_PILmULFYOsEyWHxkZ2mF2a8VPKNLE8eHqd4autYGGh4KHGh2cy5aeTY0NFNSaUp3ZnpWbDF1RUNjUkNTZEg';
$DB['VAULT_PREFIX'] = '/v1/secret/data/zabbix/';或者，使用 Vault AppRole 方法：
$DB['VAULT'] = 'HashiCorp';
$DB['VAULT_URL'] = 'https://localhost:8200';
$DB['VAULT_DB_PATH'] = 'database';
$DB['VAULT_APP_ROLE_ID'] = '6f1567f1-538d-7d70-e8e4-5d3e59471b2e';
$DB['VAULT_APP_SECRET_ID'] = '89dac8b1-f7d6-96a7-2ecf-f94d2de3d6f1';
$DB['VAULT_PREFIX'] = '/v1/secret/data/zabbix/';- 如有必要，按照 User macro values 部分中的说明配置用户宏。
要更新用于从 CyberArk Vault 获取密钥的现有配置，请参见 CyberArk configuration。
故障排除
- 在 Zabbix 服务器/proxy 日志文件中：
237839:20260729:130916.425 Vault token renew started to fail: cannot login into HashiCorp vault with AppRole method: unsuccessful response code "503"可能原因：HashiCorp Vault 已经（重新）启动，但尚未 unseal（在默认配置中这是必需的；如果配置了 Auto Unseal，则不需要）。
- 在 Zabbix 服务器/proxy 日志文件中：
235545:20260729:125617.944 Vault token renew started to fail: cannot login into HashiCorp vault with AppRole method: unsuccessful response code "400"或
235545:20260729:125718.537 Vault token renew failed: cannot login into HashiCorp vault with AppRole method: unsuccessful response code "400"可能原因：VaultAppSecretID 已在 HashiCorp vault 中过期，或已达到其使用次数上限。