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

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

2025-05-15 23:25:49作者:霍妲思

问题背景

在使用 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 配置选项。

登录后查看全文
热门项目推荐
相关项目推荐

热门内容推荐

最新内容推荐

项目优选

收起
docsdocs
OpenHarmony documentation | OpenHarmony开发者文档
Dockerfile
144
1.94 K
kernelkernel
deepin linux kernel
C
22
6
ohos_react_nativeohos_react_native
React Native鸿蒙化仓库
C++
192
274
openGauss-serveropenGauss-server
openGauss kernel ~ openGauss is an open source relational database management system
C++
145
189
RuoYi-Vue3RuoYi-Vue3
🎉 (RuoYi)官方仓库 基于SpringBoot,Spring Security,JWT,Vue3 & Vite、Element Plus 的前后端分离权限管理系统
Vue
930
554
nop-entropynop-entropy
Nop Platform 2.0是基于可逆计算理论实现的采用面向语言编程范式的新一代低代码开发平台,包含基于全新原理从零开始研发的GraphQL引擎、ORM引擎、工作流引擎、报表引擎、规则引擎、批处理引引擎等完整设计。nop-entropy是它的后端部分,采用java语言实现,可选择集成Spring框架或者Quarkus框架。中小企业可以免费商用
Java
8
0
openHiTLSopenHiTLS
旨在打造算法先进、性能卓越、高效敏捷、安全可靠的密码套件,通过轻量级、可剪裁的软件技术架构满足各行业不同场景的多样化要求,让密码技术应用更简单,同时探索后量子等先进算法创新实践,构建密码前沿技术底座!
C
887
394
金融AI编程实战金融AI编程实战
为非计算机科班出身 (例如财经类高校金融学院) 同学量身定制,新手友好,让学生以亲身实践开源开发的方式,学会使用计算机自动化自己的科研/创新工作。案例以量化投资为主线,涉及 Bash、Python、SQL、BI、AI 等全技术栈,培养面向未来的数智化人才 (如数据工程师、数据分析师、数据科学家、数据决策者、量化投资人)。
Jupyter Notebook
75
66
CangjieCommunityCangjieCommunity
为仓颉编程语言开发者打造活跃、开放、高质量的社区环境
Markdown
1.11 K
0
openHiTLS-examplesopenHiTLS-examples
本仓将为广大高校开发者提供开源实践和创新开发平台,收集和展示openHiTLS示例代码及创新应用,欢迎大家投稿,让全世界看到您的精巧密码实现设计,也让更多人通过您的优秀成果,理解、喜爱上密码技术。
C
64
512