跳到主要内容

TLS 与 mTLS

AISIX AI 网关会在四个不同位置使用 TLS。请配置部署连接所涉及的每个区域。

连接配置区域用途
调用方到 AISIXproxy.tls在代理监听器上终止 HTTPS
AISIX 到上游upstream.tls、provider_key.tls决定 AISIX 调用上游时信任哪些证书
AISIX 到 etcdetcd.tls验证 etcd 服务器并提供 AISIX 客户端身份
AISIX 网关到控制面managed.* 证书包字段向 AISIX Cloud 控制面认证 AISIX 网关

这些设置彼此独立。在代理监听器上启用 HTTPS 不会配置 etcd mTLS；信任上游的私有证书颁发机构不会影响 etcd；AISIX Cloud 证书包也不会替代监听器 TLS。

配置监听器 TLS​

当 AISIX 需要直接在代理监听器上终止 HTTPS 时，请使用监听器 TLS。

在代理监听器上配置 TLS：

config.yaml
proxy:
  addr: "0.0.0.0:3000"
  tls:
    cert_file: "/etc/aisix/tls/proxy.crt"
    key_file: "/etc/aisix/tls/proxy.key"

监听器 TLS 保护进入该监听器的入站流量，但不能证明 AISIX 可以连接 etcd、访问 AISIX Cloud 控制面或向上游模型服务提供方认证。

信任使用私有证书颁发机构的上游​

AISIX 在请求路径上建立的每条连接——模型端点、安全护栏服务、MCP 和 A2A 上游、OIDC 发现与 JWKS 获取、Realtime WebSocket、Amazon Bedrock，以及日志导出对象存储——都会使用平台证书颁发机构进行验证。由自有证书颁发机构签发证书的自托管端点不在默认信任范围内，因此对它的请求会失败：

transport error: error sending request for url (https://internal-llm.example:8443/v1/chat/completions):
client error (Connect): invalid peer certificate: UnknownIssuer

将 upstream.tls.ca_file 指向该证书颁发机构的证书，可以为整个部署解决此问题：

config.yaml
upstream:
  tls:
    ca_file: "/etc/aisix/tls/private-ca.pem"

该文件使用 PEM 编码，可以包含多个证书，因此可在一个 bundle 中提供完整证书链。这些证书会在平台自带证书之外额外受信任，因此添加私有证书颁发机构不会导致公共模型服务提供方不可达。

如果 AISIX 无法读取该文件，或文件中不包含证书，启动会失败并在消息中指出路径，而不是等到每个请求建立连接时才失败。

提供客户端证书​

部分上游还要求调用方使用证书进行身份认证。请同时设置以下两个字段：

config.yaml
upstream:
  tls:
    ca_file: "/etc/aisix/tls/private-ca.pem"
    client_cert_file: "/etc/aisix/tls/client.crt"
    client_key_file: "/etc/aisix/tls/client.key"

只设置其中一个字段会在启动时被拒绝。

为每个端点信任不同的证书颁发机构​

如果部署面对多个私有证书颁发机构，请在携带端点的模型服务提供方密钥上声明信任，而不是在部署级统一声明。端点是在资源中声明的，因此证书以内联方式提供，而不是在网关配置文件中提供：

resources.yaml
provider_keys:
  - display_name: internal-llm
    provider: openai
    api_key: "sk-..."
    api_base: "https://internal-llm.example:8443/v1"
    tls:
      ca_cert: |
        -----BEGIN CERTIFICATE-----
        MIIB...
        -----END CERTIFICATE-----

在 AISIX Cloud 中，相同设置位于控制台中模型服务提供方密钥的 Endpoint TLS 部分。

在某个模型服务提供方密钥上配置的证书只适用于该密钥的端点。各密钥不会合并为一个信任存储，因此由不同证书颁发机构签发的两个端点需要分别配置。

在测试环境中跳过验证​

可以在部署级或单个模型服务提供方密钥上关闭证书验证：

config.yaml
upstream:
  tls:
    verify: false
危险

这会接受受影响连接的任何证书，包括已过期证书、为其他主机签发的证书，以及拦截者提供的证书。任何能够拦截连接的人都可以读取和改写经过连接的提示词、响应和上游 API Key。在需要防范这些风险的环境中，请使用 ca_file 或 ca_cert。

Amazon Bedrock 不遵循此设置。 AWS SDK 的 HTTP 栈只公开信任根，因此无论 verify 如何设置，Bedrock 证书仍会被验证，并且也无法提供客户端证书。如果存在该设置，网关会在启动时记录警告，避免让它看起来已经生效。ca_file 适用于 Bedrock。

改用环境变量​

AISIX 会采用 SSL_CERT_FILE 和 SSL_CERT_DIR，并将其添加到平台证书颁发机构之外。无需修改配置文件时，可以通过这种方式信任私有证书颁发机构。

这些变量作用于整个进程，因此无法表达“仅此端点信任此证书颁发机构”。这种场景应使用 upstream.tls.ca_file 和 provider_key.tls。

备注

使用 update-ca-certificates 将证书安装到容器的系统信任存储不会生效。镜像以非特权 aisix 用户运行，因此该命令会因权限错误而失败，bundle 保持不变，网关仍会拒绝证书，但表面上看起来证书颁发机构已经安装。

配置 Redis 后端​

共享缓存和限流后端使用独立的信任设置，因为它通常位于你的部署内部，且证书颁发机构与模型端点不同。其字段与 upstream.tls 相同，并且只适用于 rediss:// URL：

config.yaml
ratelimit:
  backend: redis
  redis:
    mode: single
    url: "rediss://redis.internal:6379"
    tls:
      ca_file: "/etc/aisix/tls/redis-ca.pem"

在 Sentinel 模式下，ca_file 不生效。客户端库不接受为其发现的主节点配置自定义信任根，因此请将证书放入系统信任存储，或改为通过 SSL_CERT_FILE 指定。该模式下设置 ca_file 时，网关会在启动时记录警告。verify 在 Sentinel 模式下仍然生效。

配置 etcd mTLS​

当配置存储要求 mTLS 时，请使用 etcd.tls。AISIX 要求同时提供 CA 证书、客户端证书和客户端密钥。

配置 etcd 信任和客户端身份：

config.yaml
etcd:
  endpoints:
    - "https://etcd.internal.example.com:2379"
  prefix: "/aisix"
  tls:
    ca_cert_file: "/etc/aisix/etcd/ca.crt"
    client_cert_file: "/etc/aisix/etcd/client.crt"
    client_key_file: "/etc/aisix/etcd/client.key"

AISIX 使用 CA 文件验证 etcd 服务器证书，并向 etcd 提供客户端证书和私钥。三个文件都必须在启动时可被 AISIX 进程读取。

当 etcd 证书使用的服务器名称与端点主机名不同时，请显式设置 domain_name：

config.yaml
etcd:
  endpoints:
    - "https://10.0.0.10:2379"
  tls:
    ca_cert_file: "/etc/aisix/etcd/ca.crt"
    client_cert_file: "/etc/aisix/etcd/client.crt"
    client_key_file: "/etc/aisix/etcd/client.key"
    domain_name: "etcd.internal.example.com"

如果省略 domain_name，AISIX 会从第一个 etcd 端点推导。

配置 AISIX Cloud mTLS​

AISIX 网关使用证书包向控制面进行身份认证。这与开源 AISIX 网关的监听器 TLS 和 etcd mTLS 相互独立。

将 managed.enabled 设置为 true，提供控制面连接设置和证书包：

config.managed.yaml
managed:
  enabled: true
  cp_base_url: "https://dpm.example.com:7944"
  mtls_dir: "/var/lib/aisix/mtls"
  dp_id_file: "/var/lib/aisix/dp_id"
  cp_cert_file: "/etc/aisix/mtls/client.crt"
  cp_key_file: "/etc/aisix/mtls/client.key"
  cp_ca_file: "/etc/aisix/mtls/ca.crt"

AISIX Cloud 证书包必须包含证书、私钥和 CA bundle。示例使用文件路径；AISIX 也接受内联 PEM 值。请用同一种形式提供三个值，并且不要为同一个证书、密钥或 CA 角色同时设置内联和文件路径变体。

大多数 AISIX 网关会从 cp_base_url 推导控制面 etcd 端点。只有当控制面部署公开了单独且已知的 etcd 端点时，才设置 cp_etcd_endpoint。

AISIX 会将证书包实体化到 mtls_dir，并在重启时复用持久化 bundle。运行时状态目录必须可被网关进程写入。

有关完整的 AISIX Cloud 连接流程，请参阅连接 AISIX 网关。

检查正确连接​

请从失败连接开始，检查对应配置区域。

如果进程运行时 HTTPS 调用方流量失败，请检查 proxy.tls、证书和私钥可读性，以及面向客户端的主机名。

如果启动时连接 etcd 失败，请检查 etcd.tls、etcd 网络可达性和证书信任。如果启动后预期配置变更停止应用，请继续检查 etcd 连接和配置监听的健康状态。

如果对模型服务提供方的请求因 invalid peer certificate: UnknownIssuer 失败，说明端点证书由 AISIX 不信任的证书颁发机构签发。请检查 upstream.tls.ca_file；如果只影响一个端点，请检查该模型服务提供方密钥自己的 tls.ca_cert。

如果 AISIX Cloud 心跳、遥测、预算检查或证书轮换失败，请检查证书包、信任根、运行时状态目录和 managed.cp_base_url。

每个 TLS 区域都使用独立的证书上下文。监听器证书、上游信任设置、etcd 客户端证书和 AISIX Cloud 控制面证书会分别配置和验证。

下一步​

继续阅读配置传播，了解已验证的更新如何成为生效的网关快照。