Apache APISIX 证书上传问题分析与解决方案

问题背景

在使用 Apache APISIX 网关系统时，用户通过 APISIX Dashboard 上传 SSL 证书后，APISIX Pod 会出现错误日志，提示"additional properties forbidden, found validity_end"等验证错误。这个问题主要影响通过 Dashboard 界面管理证书的用户体验。

问题现象

当用户执行以下操作时会出现问题：

1. 重启 APISIX 服务
2. 删除现有证书后重新上传
3. 通过 Dashboard 界面导入证书文件

错误日志中会显示类似内容：

config_etcd.lua:858: failed to fetch data from etcd: failed to check item data of [/apisix/ssls] err:additional properties forbidden, found validity_end

问题根源分析

经过深入分析，发现问题的根本原因在于：

1. 数据格式不兼容：APISIX Dashboard 在存储证书数据时，会自动添加"validity_start"和"validity_end"两个字段，记录证书的有效期时间戳
2. 版本兼容性问题：新版本的 APISIX 服务端对 etcd 中存储的数据格式有严格校验，不允许出现额外的字段
3. 组件版本不匹配：APISIX Dashboard 3.0.0 版本与 APISIX 3.9.1 版本之间存在数据格式兼容性问题

解决方案

临时解决方案

1. 使用 Admin API 直接上传证书： 可以通过 APISIX 的 Admin API 直接上传证书，这种方式不会产生额外的字段：

   CERT=$(awk 'NF {sub(/\r/, ""); printf "%s\\n",$0;}' your_domain.pem)
   KEY=$(awk 'NF {sub(/\r/, ""); printf "%s\\n",$0;}' your_domain.key)
   curl http://{APISIX_ADMIN}:9180/apisix/admin/ssls -X POST -d '{
       "cert": "'"$CERT"'",
       "key": "'"$KEY"'",
       "snis": ["your.domain"]
   }' -H 'X-API-KEY: {your_api_key}'
   

2. 手动清理 etcd 中的无效数据： 可以连接到 etcd 直接删除包含"validity_start"和"validity_end"字段的证书数据

永久解决方案

1. 升级 APISIX Dashboard： 该问题已在 APISIX Dashboard 的主分支中修复，建议从源码构建最新版本：

   cd apisix-docker/dashboard
   docker build \
     -f Dockerfile.alpine \
     --build-arg APISIX_DASHBOARD_TAG=master \
     -t apisix-dashboard:master \
     .
   

2. 等待官方发布修复版本： 官方正在准备兼容新版本 APISIX 的 Dashboard 发布版本

技术原理深入

这个问题实际上反映了分布式系统中常见的"数据契约"问题。APISIX 作为数据消费方，对 etcd 中存储的数据格式有明确的 schema 要求，而 Dashboard 作为数据生产方，产生了不符合约定的数据格式。

在微服务架构中，这类问题通常通过以下方式避免：

1. 使用共享的数据模型定义
2. 实现严格的前向/后向兼容
3. 采用 schema 验证机制

APISIX 项目组已经意识到这个问题，并在新版 Dashboard 中移除了不必要的字段，确保数据格式的兼容性。

最佳实践建议

1. 保持组件版本同步：确保 APISIX 核心与 Dashboard 使用官方测试过的版本组合
2. 优先使用 Admin API：对于自动化部署场景，建议直接使用 Admin API 管理证书
3. 监控 etcd 数据健康：定期检查 etcd 中的数据格式是否符合预期
4. 测试证书管理流程：在升级前充分测试证书的上传、更新和删除操作

总结

证书管理是 API 网关的重要功能，这次遇到的问题虽然影响用户体验，但通过理解其背后的技术原理，我们可以采取有效的应对措施。随着 APISIX 生态的不断完善，这类组件间的兼容性问题将得到更好的解决。建议用户关注官方发布公告，及时升级到修复版本。