版本：Dev

TLS 与 mTLS

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

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

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

配置监听器 TLS

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

proxy.tls 用于配置 proxy.addr 所描述的那一个监听器，使该监听器提供 HTTPS 而非明文 HTTP：

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

如果还需要同时保留一个明文端口，请显式声明全部监听器，参阅同时提供 HTTPS 和 HTTP。

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

同时提供 HTTPS 和 HTTP

一个网关可以同时响应 HTTPS 和明文 HTTP。配置 proxy.listeners，每个端口一个条目，并把证书放在应当提供该证书的条目上：

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

仅通过环境变量配置网关的部署，需要把整个列表作为一个 JSON 数组传入。AISIX_PROXY__LISTENERS__0__ADDR 这类带下标的变量不起作用：

AISIX_PROXY__LISTENERS='[{"addr":"0.0.0.0:3443","tls":{"cert_file":"/etc/aisix/tls/proxy.crt","key_file":"/etc/aisix/tls/proxy.key"}},{"addr":"0.0.0.0:3000"}]'

该字段遵循三条规则：

proxy.listeners 就是代理监听器的完整集合。 只有列表中的地址会被绑定。proxy.addr 仍然是必填字段，但不会被绑定，网关会在启动时记录一行日志说明这一点：proxy.addr is ignored because proxy.listeners is set — proxy.listeners is the complete set of proxy listeners。
proxy.tls 不能与 proxy.listeners 同时使用。 它属于 proxy.addr 所描述的那个监听器，而该监听器已被 proxy.listeners 取代，因此一份不会被任何监听器使用的证书会让启动失败并报告 proxy.tls cannot be combined with proxy.listeners，而不是被静默丢弃。请把证书移到应当提供它的那个条目上。
两个条目不能使用同一个地址。 地址重复会让启动失败并报告 proxy.listeners[i].addr … is already bound by proxy.listeners[j]，因为监听器会设置 SO_REUSEPORT，否则它们会同时绑定成功，并随机以 TLS 或明文响应。

不配置 proxy.listeners 或将其留空，则保持 proxy.addr 加 proxy.tls 的单监听器行为不变。

每个监听器提供相同的路由，并共享同一份配置与状态：认证、限流、MCP、A2A，以及 /livez 和 /readyz 健康检查路由。TLS 以及通过 ALPN 协商的 HTTP/2 按监听器生效。每个监听器在绑定时都会记录一行日志，aisix listening (http) 或 aisix listening (https)，并带上它的 addr，因此启动日志会明确显示哪些端口已就绪、各自使用哪种协议。

注意

明文监听器上传输的调用方 API 密钥和提示词内容都是明文。请只把它绑定到可信的网络接口，其他流量继续使用 HTTPS 监听器。

这是网关启动配置，而不是 AISIX Cloud 控制面下发的资源，因此需要在每个网关上分别设置。admin 监听器不受影响，仍然使用自己的 admin.addr 和 admin.tls 设置。

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

AISIX 会使用平台的证书颁发机构验证出站连接。由自有证书颁发机构签发证书的自托管端点不在默认信任范围内，因此对它的请求会失败：

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`	客户端证书和密钥	`verify: false`
HTTP 模型服务提供方、HTTP 安全护栏、MCP 和 A2A 上游、OIDC 和 JWKS 请求，以及 OTLP、SLS 和 Datadog 导出器	生效	生效	生效
Realtime WebSocket	生效	忽略	生效
Amazon Bedrock 模型和安全护栏	生效	忽略	忽略；Bedrock 始终验证服务器证书
对象存储导出器	生效	忽略	生效

每个模型服务提供方 Key 的 tls 设置适用范围更窄。它们适用于 HTTP 提供方分发，包括兼容 REST 端点和透传请求，但不适用于 Amazon Bedrock 或 Realtime WebSocket。Realtime 应使用部署级 CA 和验证设置；Bedrock 仅应用部署级 ca_file 设置。

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

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

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

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

提供客户端证书

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

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"

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

Realtime、Bedrock 和对象存储导出器连接不会提供该客户端证书。不要将这些字段用作上述传输的 mTLS 控制。

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

添加以下模型服务提供方 Key 条目，为单个端点信任不同的证书颁发机构。证书随资源保存，而不是保存在网关配置中：

resources.yaml（模型服务提供方 TLS）
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 部分。

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

Bedrock 和 Realtime 会接受模型服务提供方 Key 来选择凭证和端点，但其分发传输不会读取该 Key 的 tls 配置块。请改用上表中适用的部署级设置。

在测试环境中跳过验证

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

config.yaml
upstream:
  tls:
    verify: false

危险

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

upstream.tls.verify: false 适用于 HTTP 请求路径、Realtime WebSocket 和对象存储导出器，但不适用于 Amazon Bedrock。AWS SDK 支持添加信任根，但不允许 AISIX 禁用证书验证。因此 Bedrock 仍会验证服务器证书，网关会在首次构建 Bedrock 客户端时记录警告。每个模型服务提供方 Key 的 tls.verify 字段同样不适用于 Bedrock 或 Realtime。

改用环境变量

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

这些变量作用于整个进程，因此无法表达“仅此端点信任此证书颁发机构”。如需显式指定部署级证书颁发机构，请使用 upstream.tls.ca_file；如需为一个受支持的 HTTP 模型服务提供方端点指定证书颁发机构，请使用模型服务提供方 Key 的 tls.ca_cert。

备注

使用 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 或对应 proxy.listeners 条目上的 tls 块、证书和私钥可读性，以及面向客户端的主机名。

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

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

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

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

下一步

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

配置监听器 TLS​

同时提供 HTTPS 和 HTTP​

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

提供客户端证书​

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

在测试环境中跳过验证​

改用环境变量​

配置 Redis 后端​

配置 etcd mTLS​

配置 AISIX Cloud mTLS​

检查正确连接​

下一步​