配置客户端和 APISIX 之间的 HTTPS
TLS (传输层安全性协议) 是一种旨在保护两个实体之间通信的加密协议。在客户端和 APISIX 之间强 制执行 HTTPS 可提高数据传输过程中的安全性和真实性。
本指南将向你展示如何在客户端应用程序和 APISIX 之间配置 HTTPS。

前置条件
- 安装 Docker。
- 安装 cURL 以向服务发送请求进行验证。
- 按照 快速入门教程 在 Docker 或 Kubernetes 中启动一个新的 APISIX 实例。
- 安装 jq 将 PEM 文件编码为 JSON 字符串。
- 如果使用 Admin API 示例且启用了身份验证,请将管理员角色的密钥导出为
ADMIN_API_KEY。请在deployment.admin.admin_key下配置该密钥。Docker 快速入门为了便于本地评估而禁用了身份验证;生产环境中请保持启用。
创建路由
创建一个将所有发往 /ip 的请求转发到上游 httpbin.org 的路由:
- Admin API
- ADC
curl -i "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
"id": "quickstart-client-ip",
"uri": "/ip",
"upstream": {
"nodes": {
"httpbin.org:80":1
},
"type": "roundrobin"
}
}'
HTTP/1.1 200 OK 响应验证了路由已成功创建。
为本示例使用独立的服务名称。ADC 按名称匹配服务,因此即使标签不同,复用 httpbin Service 也会更新既有服务。如果此前已同步过本示例,请在完成同步后删除 httpbin Service 上旧的 quickstart-client-ip 路由,并保留该服务上的其他所有路由。
services:
- name: Downstream HTTPS Service
labels:
docs-example: downstream-https
routes:
- uris:
- /ip
name: quickstart-client-ip
upstream:
type: roundrobin
nodes:
- host: httpbin.org
port: 80
weight: 1
ADC 将服务协调为期望状态。仅预览本示例带标签的服务,并确认差异中没有非预期的更新或删除:
adc diff -f adc-service.yaml \
--include-resource-type service \
--label-selector docs-example=downstream-https
同步已审查的服务配置:
adc sync -f adc-service.yaml \
--include-resource-type service \
--label-selector docs-example=downstream-https
生成证书和密钥
生成证书颁发机构 (CA) 密钥和证书:
openssl genrsa -out ca.key 2048
openssl req -new -x509 -days 36500 -sha256 \
-key ca.key \
-out ca.crt \
-subj "/CN=MyTestCA" \
-extensions v3_ca \
-config <(printf "[req]\ndistinguished_name=req\n[v3_ca]\nbasicConstraints=critical,CA:TRUE\nkeyUsage=critical,keyCertSign,cRLSign\nsubjectKeyIdentifier=hash\nauthorityKeyIdentifier=keyid:always,issuer")
为 APISIX 生成私钥和证书签名请求(CSR):
openssl genrsa -out server.key 2048
openssl req -new -sha256 \
-key server.key \
-out server.csr \
-subj "/CN=test.com"
使用 CA 证书签署服务器 CSR。证书的主题备用名称(SAN)使其对 DNS 名称 test.com 有效:
openssl x509 -req -days 36500 -sha256 \
-in server.csr \
-CA ca.crt -CAkey ca.key -CAcreateserial \
-out server.crt \
-extensions v3_req \
-extfile <(printf "[v3_req]\nbasicConstraints=CA:FALSE\nkeyUsage=digitalSignature,keyEncipherment\nextendedKeyUsage=serverAuth\nsubjectAltName=DNS:test.com")
为 APISIX 配置 HTTPS
ADC 示例使用环境变量将 PEM 内容插入资源文件:
export server_cert=$(cat server.crt)
export server_key=$(cat server.key)
- Admin API
- ADC
创建 SSL 对象,并将 SNI 设置为与证书中的 DNS 名称 test.com 匹配。jq 会读取 PEM 文件,并将其中的换行符编码为有效 JSON:
jq -n --rawfile cert server.crt --rawfile key server.key \
'{id: "quickstart-tls-client-ssl", sni: "test.com", cert: $cert, key: $key}' \
| curl -i "http://127.0.0.1:9180/apisix/admin/ssls" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-H "Content-Type: application/json" \
--data-binary @-
ssls:
- labels:
docs-example: downstream-https
snis:
- test.com
certificates:
- certificate: ${server_cert}
key: ${server_key}
❶ sni:test.com,与服务器证书的 DNS 名称相同
❷ cert:服务器证书
❸ key:服务器证书的私钥
在同一示例范围内预览 SSL 和服务变更:
adc diff -f adc-ssl.yaml -f adc-service.yaml \
--include-resource-type ssl \
--include-resource-type service \
--label-selector docs-example=downstream-https
同步已审查的 SSL 和服务配置:
adc sync -f adc-ssl.yaml -f adc-service.yaml \
--include-resource-type ssl \
--include-resource-type service \
--label-selector docs-example=downstream-https
验证客户端和 APISIX 之间的 HTTPS
服务器证书对 DNS 名称 test.com 有效。验证时应使用该主机名,并将其解析到本地 APISIX 地址。
向路由发送请求。--cacert 会验证 APISIX 的证书链,--resolve 则将 test.com 连接到 127.0.0.1,同时保留主机名验证:
curl -iv --cacert ca.crt \
--noproxy test.com \
--resolve "test.com:9443:127.0.0.1" \
"https://test.com:9443/ip"
请求应成功并返回 HTTP 2xx 响应。基于 OpenSSL 的 curl 构建,其相关输出可能如下:
* subjectAltName: host "test.com" matched cert's "test.com"
* SSL certificate verify ok.
< HTTP/2 200
具体输出取决于 curl 使用的 TLS 后端和协商得到的 HTTP 版本。请确认输出同时表明证书主机名匹配且验证成功;不能仅根据 HTTP 状态判断。
下一步
你可以在 SSL 证书 中了解更多关于 TLS 和 APISIX SSL 对象的信息。
APISIX 还支持客户端和 APISIX 之间的 mTLS 连接。有关更多详细信息,请参阅 配置客户端和 APISIX 之间的 mTLS。