升级指南
APISIX 的版本升级方式#
APISIX 的版本号遵循语义化版本。
升级到 APISIX 3.0.0 是一个重大的版本升级，我们建议您先升级到 2.15.x，然后再升级到 3.0.0。
从 2.15.x 升级到 3.0.0#
升级注意事项和重大更新#
在升级之前，请查看 3.0.0-beta 和 3.0.0 中的 Change 部分，以了解 3.0.0 版本的不兼容的修改与重大更新。
部署#
基于 alpine 的镜像已不再支持，如果你使用了 alpine 的镜像，那么你需要将镜像替换为基于 debian/centos 的镜像。
目前，我们提供了：
- 基于 debian/centos 的镜像，你可以在 DockerHub 上找到它们
- CentOS 7 和 CentOS 8 的 RPM 包，支持 AMD64 和 ARM64 架构，可参考文章通过 RPM 仓库安装
- Debian 11(bullseye) 的 DEB 包，支持 AMD64 和 ARM64 架构，可参考文章通过 DEB 仓库安装
3.0.0 对部署模式进行了重大更新，具体如下：
- 支持数据面与控制面分离的部署模式，具体可参考 Decoupled
- 如在使用中仍需沿用原来的部署模式，那么可以使用部署模式中的
traditional模式，并且更新配置文件，具体可参考 Traditional - 支持 Standalone 模式，需要更新配置文件，具体可参考 Standalone
依赖项#
如果你使用提供的二进制包（Debian 和 RHEL）或者镜像，则它们已经捆绑了 APISIX 所有必要的依赖项，你可以跳过本节。
APISIX 的一些特性需要在 OpenResty 中引入额外的 NGINX 模块。如果要使用这些功能，你需要构建一个自定义的 OpenResty 发行版（APISIX-Runtime）。你可以参考 api7/apisix-build-tools 中的代码，构建自己的 APISIX-Runtime 环境。
如果你希望 APISIX 运行在原生的 OpenResty 上，这种情况下将只支持运行在 OpenResty 1.19.3.2 及以上的版本。
迁移#
静态配置迁移#
APISIX 的配置方式是用自定义的 conf/config.yaml 中的内容覆盖默认的 conf/config-default.yaml，如果某个配置项在 conf/config.yaml 中不存在，那么就使用 conf/config-default.yaml 中的配置。在 3.0.0 中，我们调整了 conf/config-default.yaml 配置文件中的部分细节，具体内容如下。
移动配置项#
从 2.15.x 到 3.0.0 版本，在 conf/config-default.yaml 有一些配置项的位置被移动了。如果你使用了这些配置项，那么你需要将它们移动到新的位置。
调整内容：
config_center功能改由deployment中的config_provider实现etcd字段整体迁移到deployment中- 以下的 Admin API 配置移动到
deployment中的admin字段- admin_key
- enable_admin_cors
- allow_admin
- admin_listen
- https_admin
- admin_api_mtls
- admin_api_version
你可以在 conf/config-default.yaml 中找到这些配置的新的确切位置。
更新配置项#
某些配置在 3.0.0 中被移除了，并被新的配置项替代。如果你使用了这些配置项，那么你需要将它们更新为新的配置项。
调整内容：
去除
apisix.ssl.enable_http2和apisix.ssl.listen_port，使用apisix.ssl.listen替代。如果在
conf/config.yaml中有这样的配置：ssl:
enable_http2: true
listen_port: 9443则在 3.0.0 版本中需要转换成如下所示：
ssl:
listen:
- port: 9443
enable_http2: true去除
nginx_config.http.lua_shared_dicts，用nginx_config.http.custom_lua_shared_dict替代，这个配置用于声明自定义插件的共享内存。如果在
conf/config.yaml中有这样的配置：nginx_config:
http:
lua_shared_dicts:
my_dict: 1m则在 3.0.0 版本中需要转换成如下所示：
nginx_config:
http:
custom_lua_shared_dict:
my_dict: 1m去除
etcd.health_check_retry，用deployment.etcd.startup_retry替代，这个配置用于在启动时，重试连接 etcd 的次数。如果在
conf/config.yaml中有这样的配置：etcd:
health_check_retry: 2则在 3.0.0 版本中需要转换成如下所示：
deployment:
etcd:
startup_retry: 2去除
apisix.port_admin，用deployment.apisix.admin_listen替代。如果在
conf/config.yaml中有这样的配置：apisix:
port_admin: 9180则在 3.0.0 中需要转换成如下所示：
deployment:
apisix:
admin_listen:
ip: 127.0.0.1 # 替换成实际暴露的 IP
port: 9180修改
enable_cpu_affinity的默认值为false。主要是因为越来越多的用户通过容器部署 APISIX，由于 Nginx 的 worker_cpu_affinity 不计入 cgroup，默认启用 worker_cpu_affinity 会影响 APISIX 的行为，例如多个实例会被绑定到一个 CPU 上。为了避免这个问题，我们在conf/config-default.yaml中默认禁用enable_cpu_affinity选项。去除
apisix.real_ip_header，用nginx_config.http.real_ip_header替代
数据迁移#
如果你需要备份与恢复数据，可以利用 ETCD 的备份与恢复功能，参考 etcdctl snapshot。
数据兼容#
在 3.0.0 中，我们调整了部分数据结构，这些调整影响到 APISIX 的路由、上游、插件等数据。3.0.0 版本与 2.15.x 版本之间数据不完全兼容。因此，你无法使用 3.0.0 版本的 APISIX 直接连接到 2.15.x 版本 APISIX 使用的 ETCD 集群。
为了保持数据兼容，有两种方式，仅供参考：
- 梳理 ETCD 中的数据，将不兼容的数据备份然后清除，将备份的数据结构转换成 3.0.0 版本的数据结构，通过 3.0.0 版本的 Admin API 来恢复数据
- 梳理 ETCD 中的数据，编写脚本，将 2.15.x 版本的数据结构批量转换成 3.0.0 版本的数据结构
数据层面调整内容如下。
将插件配置的元属性
disable移动到_meta中。disable表示该插件的启用/禁用状态，如果在 ETCD 中存在这样的数据结构：{
"plugins":{
"limit-count":{
... // 插件配置
"disable":true
}
}
}则在 3.0.0 版本中，这个插件的数据结构应该变成如下所示：
{
"plugins":{
"limit-count":{
... // 插件配置
"_meta":{
"disable":true
}
}
}
}注意：
disable是插件的元配置，该调整对所有插件配置生效，不仅仅是limit-count插件。去除路由的
service_protocol字段，使用upstream.scheme替代。如果在 ETCD 中存在这样的数据结构：
{
"uri":"/hello",
"service_protocol":"grpc",
"upstream":{
"type":"roundrobin",
"nodes":{
"127.0.0.1:1980":1
}
}
}则在 3.0.0 版本中，这个路由的数据结构应该变成如下所示：
{
"uri":"/hello",
"upstream":{
"type":"roundrobin",
"scheme":"grpc",
"nodes":{
"127.0.0.1:1980":1
}
}
}去除
authz-keycloak插件中的audience字段，使用client_id替代。如果在 ETCD 中
authz-keycloak的插件配置存在这样的数据结构：{
"plugins":{
"authz-keycloak":{
... // 插件配置
"audience":"Client ID"
}
}
}则在 3.0.0 中，这个路由的数据结构应该变成如下所示：
{
"plugins":{
"authz-keycloak":{
... // 插件配置
"client_id":"Client ID"
}
}
}去除
mqtt-proxy插件中的upstream，在插件外部配置upstream，并在插件中引用。如果在 ETCD 中
mqtt-proxy的插件配置存在这样的数据结构：{
"remote_addr":"127.0.0.1",
"plugins":{
"mqtt-proxy":{
"protocol_name":"MQTT",
"protocol_level":4,
"upstream":{
"ip":"127.0.0.1",
"port":1980
}
}
}
}则在 3.0.0 版本中，这个插件的数据结构应该变成如下所示：
{
"remote_addr":"127.0.0.1",
"plugins":{
"mqtt-proxy":{
"protocol_name":"MQTT",
"protocol_level":4
}
},
"upstream":{
"type":"chash",
"key":"mqtt_client_id",
"nodes":[
{
"host":"127.0.0.1",
"port":1980,
"weight":1
}
]
}
}去除
syslog插件中的max_retry_times和retry_interval字段，使用max_retry_count和retry_delay替代。如果在 ETCD 中
syslog的插件配置存在这样的数据结构：{
"plugins":{
"syslog":{
"max_retry_times":1,
"retry_interval":1,
... // 其他配置
}
}
}则在 3.0.0 版本中，这个插件的数据结构应该变成如下所示：
{
"plugins":{
"syslog":{
"max_retry_count":1,
"retry_delay":1,
... // 其他配置
}
}
}去除
proxy-rewrite插件中的scheme字段，在配置上游时，用upstream.scheme替代。如果在 ETCD 中
proxy-rewrite的插件配置存在这样的数据结构：{
"plugins":{
"proxy-rewrite":{
"scheme":"https",
... // 其他配置
}
},
"upstream":{
"nodes":{
"127.0.0.1:1983":1
},
"type":"roundrobin"
},
"uri":"/hello"
}则在 3.0.0 版本中，这个插件的数据结构应该变成如下所示：
{
"plugins":{
"proxy-rewrite":{
... // 其他配置
}
},
"upstream":{
"scheme":"https",
"nodes":{
"127.0.0.1:1983":1
},
"type":"roundrobin"
},
"uri":"/hello"
}
Admin API#
在 3.0.0 版本中，我们对 Admin API 也进行了一些调整。使得 Admin API 更加易用，更加符合 RESTful 的设计理念，具体调整内容如下。
操作资源时（包括查询单个资源和列表资源），删除了响应体中的
count、action和node字段，并将node中的内容提升到响应体的根节点。在 2.x 版本中，通过 Admin API 查询
/apisix/admin/routes/1的响应格式是这样的：{
"count":1,
"action":"get",
"node":{
"key":"\/apisix\/routes\/1",
"value":{
... // 配置内容
}
}
}在 3.0.0 版本中，通过 Admin API 查询
/apisix/admin/routes/1资源的响应格式调整为如下所示：{
"key":"\/apisix\/routes\/1",
"value":{
... // 配置内容
}
}查询列表资源时，删除
dir字段，新增list字段，存放列表资源的数据；新增total字段，存放列表资源的总数。在 2.x 版本中，通过 Admin API 查询
/apisix/admin/routes的响应格式是这样的：{
"action":"get",
"count":2,
"node":{
"key":"\/apisix\/routes",
"nodes":[
{
"key":"\/apisix\/routes\/1",
"value":{
... // 配置内容
}
},
{
"key":"\/apisix\/routes\/2",
"value":{
... // 配置内容
}
}
],
"dir":true
}
}在 3.0.0 版本中，通过 Admin API 查询
/apisix/admin/routes资源的响应格式调整为如下所示：{
"list":[
{
"key":"\/apisix\/routes\/1",
"value":{
... // 配置内容
}
},
{
"key":"\/apisix\/routes\/2",
"value":{
... // 配置内容
}
}
],
"total":2
}调整 ssl 资源的请求路径，从
/apisix/admin/ssl/{id}调整为/apisix/admin/ssls/{id}。在 2.x 版本中，通过 Admin API 操作 ssl 资源是这样的：
curl -i http://{apisix_listen_address}/apisix/admin/ssl/{id}在 3.0.0 版本中，通过 Admin API 操作 ssl 资源调整为如下所示：
curl -i http://{apisix_listen_address}/apisix/admin/ssls/{id}调整 proto 资源的请求路径，从
/apisix/admin/proto/{id}调整为/apisix/admin/protos/{id}。在 2.x 版本中，通过 Admin API 操作 proto 资源是这样的：
curl -i http://{apisix_listen_address}/apisix/admin/proto/{id}在 3.0.0 版本中，通过 Admin API 操作 proto 资源调整为如下所示：
curl -i http://{apisix_listen_address}/apisix/admin/protos/{id}
除以上内容外，我们也将 Admin API 的端口调整为 9180。
总结#
Apache APISIX 3.0.0 版本的发布，将产品的更多细节迭代了一大步。由于大版本的更新迭代会导致一些配置与数据也相应进行调整，为此我们为您整理了这份 APISIX 升级指南。希望对各位在使用 APISIX 的过程中，对于版本的更新操作也更得心应手。
如果您有任何问题或意见，欢迎随时在社区进行交流。