密钥管理
本文档将介绍 APISIX 中密钥管理的基本概念以及为什么需要它们。
在文档末尾探索其他资源，以获取有关相关主题的更多信息。
概述
在 APISIX 中，密钥（Secret）对象用于设置与外部密钥管理器的集成，以便 APISIX 可以在运行时动态地建立连接并从密钥管理器获取密钥。
下图使用一个示例说明了密钥对象的概念，其中为用户 John 启用了 key-auth，并且用户凭证存储在 HashiCorp Vault 服务器中：
如演示所示，当 APISIX 与外部密钥管理器结合使用时，密钥字段被定义为一个以固定前缀 $secret:// 开头的变量，后跟密钥管理器名称、APISIX 密钥对象 ID、用户名和其他详细信息。
具体来说，如果使用 Vault 作为密钥管理器，APISIX 密钥对象应指定：
uri：托管 Vault 服务器的位置prefix：对应于 Vault 应路由流量的密钥引擎的路径前缀token：APISIX 对 Vault 进行身份认证并建立连接的Token
这些配置确保 John 可以向 APISIX 发送请求并使用正确的密钥访问后端服务。来自未通过身份认证用户的请求将 被 APISIX 拒绝。
除 Vault 外，APISIX 还集成了 AWS Secrets Manager 和 Google Cloud Secret Manager。Secret 引用使用 $secret://...，环境变量引用使用 $env://... 或 $ENV://...。
支持的字段与解析行为
以下字符串字段可以使用 Secret 和环境变量引用：
- HTTP 和 Stream 插件配置字段；
- 消费者身份认证插件字段；
- SSL 资源中的
cert、key、certs、keys和client.ca。
SSL 资源引用会在 HTTP 和 Stream TLS 握手期间解析。因此，上游客户端 SSL 资源可在 cert 和 key 中保存 $secret://... 或 $env://... 引用，并通过 upstream.tls.client_cert_id 用于 HTTP 或 Stream 上游 mTLS。
APISIX 会在普通字符串校验前识别引用，因此占位符可以绕过 enum、pattern、minLength 和 maxLength 等约束。解析后的值不会再次依据这些约束进行校验。请确保密钥管理器中存储的值符合目标字段的格式和长度要求。
插件引用会在插件执行前立即解析。APISIX 会缓存解析结果，并在缓存值发生变化时刷新已解析的插件配置。成功查询和失败查询分别使用 config.yaml 中 apisix.lru.secret 下的缓存容量和 TTL 配置。
如果 APISIX 无法解析引用，它会记录 failed to resolve secret reference 等错误，并通常将原始引用字符串保留在传给插件的配置中。最终的请求行为取 决于具体字段和插件，可能表现为上游连接错误或其他插件特定错误。
消费者身份认证采用失败关闭策略。如果消费者凭证缺失，或者仍包含未解析的 Secret 引用，APISIX 会将该消费者排除在凭证查找之外。客户端不能通过发送字面量 $secret://... 或 $env://... 引用来通过身份认证，而会收到身份认证插件正常的无效凭证响应。
请监控解析错误，并在依赖新值前测试 Secret 轮换。
解析名称中包含斜杠的 AWS Secret
AWS Secrets Manager 的 Secret 名称可以包含斜杠，因此 Secret 名称与可选 JSON 字段的边界可能不明确。APISIX 会先尝试最长的 Secret 名称。只有 AWS 返回 ResourceNotFoundException 时，才会从右侧依次将路径段移入字段名称，并尝试较短的 Secret 名称。
例如，$secret://aws/1/john/secret/john-key-auth 会依次尝试以下解释：
- Secret 为
john/secret/john-key-auth，没有 JSON 字段。 - Secret 为
john/secret，JSON 字段为john-key-auth。 - Secret 为
john，JSON 字段为secret/john-key-auth。
最长的匹配 Secret 名称优先。除 ResourceNotFoundException 外的 AWS 错误会停止解析，不会再尝试较短的名称。
有关配置示例，请参阅在 HashiCorp Vault 中管理密钥。有关 Vault、AWS 和 Google Cloud 集成使用的 Secret 对 象 Schema，请参阅 Admin API 参考。