跳到主要内容

连接托管网关

本指南将说明如何使用 AISIX Cloud 签发的证书包（bundle），将托管网关连接到 AISIX Cloud。

证书包用于标识网关及其所属环境。网关启动后，会通过双向 TLS 上报健康状态和遥测、接收投射配置、轮换证书，并检查托管预算。

托管网关连接​

托管网关启动时需要证书包和 Cloud 管理端 URL。网关在本地处理代理流量，AISIX Cloud 则管理投射到该网关的资源配置。

请使用与托管网关所服务环境一致的证书包。该证书包包含客户端证书、私钥和 CA bundle。三者需要一起提供，可以使用内联 PEM 值，也可以使用文件路径。

准备工作​

请先准备 AISIX Cloud 为目标环境签发的以下内容：

  • Cloud 管理端 URL。
  • 网关证书、私钥和 CA bundle。
  • 网关可写状态目录。
  • 网关到 AISIX Cloud 的出站网络访问能力。

Cloud 管理端 URL 必须指向接受托管网关 mTLS 流量的端点。不要使用 AISIX Cloud Web 控制台 URL，也不要使用通用控制面 API URL。

状态目录也是托管连接的一部分。网关会在该目录下写入持久化 mTLS 文件、网关身份和本地配置快照，以便重启后复用同一身份，并从临时 Cloud 连接中断中恢复。

启动托管网关​

托管网关通常从已发布容器镜像启动，选择托管配置文件，并通过挂载文件提供证书包。

使用托管配置和证书包启动容器：

docker run --rm \
  -e AISIX_CONFIG_PATH=/etc/aisix/config.managed.yaml \
  -e AISIX_MANAGED__CP_BASE_URL="https://dpm.example.com:7944" \
  -e AISIX_MANAGED__CP_CERT_FILE="/etc/aisix/mtls/client.crt" \
  -e AISIX_MANAGED__CP_KEY_FILE="/etc/aisix/mtls/client.key" \
  -e AISIX_MANAGED__CP_CA_FILE="/etc/aisix/mtls/ca.crt" \
  -v "$PWD/mtls:/etc/aisix/mtls:ro" \
  -v aisix-state:/var/lib/aisix \
  ghcr.io/api7/aisix:0.1.0

请将示例 URL、证书路径和镜像标签替换为你的环境实际签发的值。

如果使用内联 PEM 值而不是文件，请同时提供证书、私钥和 CA PEM 变量。同一个证书角色不要混用内联 PEM 和文件路径。

托管配置默认将代理监听端口绑定到 3000，将专用指标监听端口绑定到 9090，不会绑定本地 Admin 监听端口。

如果直接运行二进制文件，请使用等效的 --config 标志或 AISIX_CONFIG 环境变量：

aisix --config /path/to/config.managed.yaml

请确保运行网关的同一用户可以写入状态目录。仅挂载证书子目录是不够的，因为进程还会在状态目录下写入网关身份和快照文件。

验证托管连接​

网关启动后，按顺序验证托管连接：

  • 进程启动时没有证书或信任链错误。
  • AISIX Cloud 能看到预期环境的心跳。
  • 投射资源已到达托管网关。
  • 通过托管网关端点发送的实时请求成功。
  • 该请求的用量或遥测信息出现在 AISIX Cloud 中。

如果心跳失败，请检查 Cloud 管理端 URL、证书包、信任根、文件权限、状态目录和出站网络访问。如果心跳健康，但资源或实时流量行为不符合预期，请继续阅读资源投射。

托管配置​

证书以文件方式挂载时，请使用文件路径变量。当 AISIX Cloud 或部署系统把 bundle 直接注入进程环境时，请使用内联 PEM 变量。

配置项使用变量
Cloud 管理端 URLAISIX_MANAGED__CP_BASE_URL
证书文件AISIX_MANAGED__CP_CERT_FILE
私钥文件AISIX_MANAGED__CP_KEY_FILE
CA bundle 文件AISIX_MANAGED__CP_CA_FILE
内联证书AISIX_MANAGED__CP_CERT_PEM
内联私钥AISIX_MANAGED__CP_KEY_PEM
内联 CA bundleAISIX_MANAGED__CP_CA_PEM

除非部署提供单独的 etcd 端点，否则托管配置会从 Cloud 管理端 URL 推导 Cloud etcd 端点。只有当 AISIX Cloud 为该环境提供独立 etcd 端点时，才需要使用 AISIX_MANAGED__CP_ETCD_ENDPOINT。

下一步​

你已经了解托管网关如何通过基于证书的 mTLS 连接到 AISIX Cloud。接下来阅读资源投射，了解 Cloud 资源如何到达网关。