跳到主要内容

TLS 与 mTLS

AISIX AI 网关会在三个不同位置使用 TLS。请根据要保护的连接配置对应 TLS。

连接配置区域用途
调用方或 Admin 客户端到 AISIXproxy.tls 或 admin.tls在代理或 Admin 监听器上终止 HTTPS
AISIX 到 etcdetcd.tls验证 etcd，并可选择提供客户端证书
托管网关到 AISIX Cloudmanaged.* 证书包字段将托管网关认证到 AISIX Cloud

这些设置彼此独立。在代理监听器上启用 HTTPS 不会配置 etcd TLS，托管证书包也不会替代监听器 TLS。

配置监听器 TLS​

当 AISIX 需要直接在代理或 Admin 监听器上终止 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"

单独为自托管 Admin 监听器配置 TLS：

config.yaml
admin:
  addr: "127.0.0.1:3001"
  admin_keys:
    - "YOUR_ADMIN_KEY"
  tls:
    cert_file: "/etc/aisix/tls/admin.crt"
    key_file: "/etc/aisix/tls/admin.key"

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

配置 etcd TLS​

当配置存储要求 TLS 或 mTLS 时，请使用 etcd.tls。

配置 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 端点推导。

配置托管 mTLS​

托管网关使用证书包向 AISIX Cloud 认证。这与自托管部署中的监听器 TLS 和 etcd TLS 是独立配置。

选择托管模式，提供 Cloud 连接设置，并提供证书包：

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"

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

大多数托管网关会从 cp_base_url 推导托管 etcd 端点。只有当 AISIX Cloud 提供单独的 etcd 端点用于托管引导时，才设置 cp_etcd_endpoint。

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

完整托管引导流程请参见托管网关设置。

检查正确连接​

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

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

如果自托管模式下 HTTPS Admin 流量失败，请检查 admin.tls、Admin 监听器绑定和私有 Admin 主机名。

如果启动时连接 etcd 失败，请检查 etcd.tls、etcd 网络可达性和证书信任。如果启动后配置新鲜度停滞，请继续聚焦 etcd 连接和配置 watch 健康状态。

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

每个 TLS 区域都有自己的证书上下文。监听器证书、etcd 客户端证书和托管 Cloud 证书会分别配置和验证。

下一步​

你已经了解各类 TLS 和 mTLS 连接应在哪里配置。接下来阅读健康检查，验证进程和配置健康状态。