Apache APISIX 中配置 ApisixTls 实现 SSL 上游服务的实践指南

问题背景

在使用 Apache APISIX 作为 API 网关时，我们经常需要处理上游服务启用 SSL/TLS 的情况。当尝试通过 ApisixTls 资源配置 SSL 连接时，可能会遇到 "tlsv1 alert internal error" 的错误提示。这种错误通常表明 SSL 握手过程中出现了问题，可能是由于证书配置不当或双向认证(mTLS)验证失败导致的。

错误现象分析

典型的错误表现为客户端在尝试建立 TLS 连接时，服务器返回了内部错误：

TLSv1.3 (OUT), TLS handshake, Client hello (1):
TLSv1.3 (IN), TLS alert, internal error (592):
error:14094438:SSL routines:ssl3_read_bytes:tlsv1 alert internal error

这种错误可能出现在以下场景中：

1. 客户端证书验证失败
2. 服务器证书链不完整
3. 双向认证配置不正确
4. SNI(服务器名称指示)不匹配

ApisixTls 配置解析

Apache APISIX 提供了 ApisixTls 自定义资源来管理 TLS 配置。一个典型的配置示例如下：

apiVersion: apisix.apache.org/v2
kind: ApisixTls
metadata:
  name: my-tls
spec:
  hosts:
  - example.com
  secret:
    name: app-secret
    namespace: default
  client:
    caSecret:
      name: app-ca-secret
      namespace: default
    depth: 10

这个配置定义了：

• 主机名(SNI)为 example.com
• 使用 default 命名空间中的 app-secret 作为服务器证书
• 启用客户端证书验证，使用 app-ca-secret 作为 CA 证书
• 设置证书链验证深度为 10

解决方案：实现部分路径的 mTLS 豁免

在某些场景下，我们可能希望对特定路径豁免双向认证(mTLS)要求。Apache APISIX 支持通过正则表达式匹配 URI 来实现这一功能。

虽然 ApisixTls CRD 目前不支持直接配置 skip_mtls_uri_regex 字段，但可以通过以下两种方式实现：

方法一：使用 Admin API 直接配置

通过 APISIX 的 Admin API 可以直接创建包含 skip_mtls_uri_regex 的 SSL 配置：

curl http://127.0.0.1:9180/apisix/admin/ssls/1 \
-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
    "sni": "example.com",
    "cert": "<证书内容>",
    "key": "<私钥内容>",
    "client": {
        "ca": "<CA证书内容>",
        "depth": 10,
        "skip_mtls_uri_regex": ["^/api/health$", "^/public/.*"]
    }
}'

方法二：修改 APISIX 配置

在 config.yaml 中添加全局配置：

apisix:
  ssl:
    ssl_trusted_certificate: /path/to/ca.crt
    skip_mtls_uri_regex: ["^/api/health$", "^/public/.*"]

最佳实践建议

1. 证书管理：确保证书链完整，包括中间证书
2. SNI 匹配：检查客户端请求中的 SNI 是否与配置匹配
3. 测试验证：使用 openssl s_client 命令进行详细诊断
4. 渐进式部署：先测试非生产环境，再应用到生产
5. 监控告警：配置适当的监控以捕获 TLS 握手失败

总结

处理 Apache APISIX 中的 TLS 配置需要仔细检查证书链、SNI 匹配和双向认证设置。对于需要部分豁免 mTLS 的场景，虽然 ApisixTls CRD 目前不支持直接配置，但可以通过 Admin API 或修改配置文件实现。随着 APISIX 的版本更新，未来可能会在 CRD 中增加更多灵活的 TLS 配置选项。