diff --git a/docs/zh/latest/upgrade-guide-from-2.15.x-to-3.0.0.md b/docs/zh/latest/upgrade-guide-from-2.15.x-to-3.0.0.md index dfa78e089c67..20c47d9c93a4 100644 --- a/docs/zh/latest/upgrade-guide-from-2.15.x-to-3.0.0.md +++ b/docs/zh/latest/upgrade-guide-from-2.15.x-to-3.0.0.md @@ -28,7 +28,7 @@ description: 本文档将引导你了解如何升级 APISIX 版本。 ## APISIX 的版本升级方式 -APISIX 的版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。 +APISIX 的版本号遵循[语义化版本](https://semver.org/lang/zh-CN/)。 升级到 APISIX 3.0.0 是一个重大的版本升级,我们建议您先升级到 2.15.x,然后再升级到 3.0.0。 @@ -36,7 +36,7 @@ APISIX 的版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。 ### 升级注意事项和重大更新 -在升级之前,请查看 [3.0.0-beta](./CHANGELOG.md#300-beta) 和 [3.0.0](./CHANGELOG.md#300) 中的 Change 部分以了解 3.0.0 版本的不兼容的修改与重大更新。 +在升级之前,请查看 [3.0.0-beta](./CHANGELOG.md#300-beta) 和 [3.0.0](./CHANGELOG.md#300) 中的 Change 部分,以了解 3.0.0 版本的不兼容的修改与重大更新。 #### 部署 @@ -45,28 +45,28 @@ APISIX 的版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。 目前,我们提供了: - 基于 debian/centos 的镜像,你可以在 [DockerHub](https://hub.docker.com/r/apache/apisix/tags?page=1&ordering=last_updated) 上找到它们 -- CentOS 7 和 CentOS 8 的 RPM 包,支持 amd64 和 arm64 架构,参考 [通过 RPM 仓库安装](./installation-guide.md#通过-rpm-仓库安装) -- Debian 11(bullseye) 的 DEB 包,支持 amd64 和 arm64 架构,参考 [通过 DEB 仓库安装](./installation-guide.md#通过-deb-仓库安装) +- CentOS 7 和 CentOS 8 的 RPM 包,支持 AMD64 和 ARM64 架构,可参考文章[通过 RPM 仓库安装](./installation-guide.md#通过-rpm-仓库安装) +- Debian 11(bullseye) 的 DEB 包,支持 AMD64 和 ARM64 架构,可参考文章[通过 DEB 仓库安装](./installation-guide.md#通过-deb-仓库安装) -3.0.0 对部署模式做了重大更新,具体如下: +3.0.0 对部署模式进行了重大更新,具体如下: -- 支持数据面与控制面分离的部署模式,请参考 [Decoupled](../../en/latest/deployment-modes.md#decoupled) -- 如果需要继续使用原来的部署模式,那么可以使用部署模式中的 `traditional` 模式,并且更新配置文件,请参考 [Traditional](../../en/latest/deployment-modes.md#traditional) -- 支持 Standalone 模式,需要更新配置文件,请参考 [Standalone](../../en/latest/deployment-modes.md#standalone) +- 支持数据面与控制面分离的部署模式,具体可参考 [Decoupled](../../en/latest/deployment-modes.md#decoupled) +- 如在使用中仍需沿用原来的部署模式,那么可以使用部署模式中的 `traditional` 模式,并且更新配置文件,具体可参考 [Traditional](../../en/latest/deployment-modes.md#traditional) +- 支持 Standalone 模式,需要更新配置文件,具体可参考 [Standalone](../../en/latest/deployment-modes.md#standalone) #### 依赖项 -如果你使用提供的二进制包(Debian 和 RHEL),或者镜像,则它们已经捆绑了 APISIX 所有必要的依赖项,你可以跳过本节。 +如果你使用提供的二进制包(Debian 和 RHEL)或者镜像,则它们已经捆绑了 APISIX 所有必要的依赖项,你可以跳过本节。 APISIX 的一些特性需要在 OpenResty 中引入额外的 NGINX 模块。如果要使用这些功能,你需要构建一个自定义的 OpenResty 发行版(APISIX-Base)。你可以参考 [api7/apisix-build-tools](https://github.com/api7/apisix-build-tools) 中的代码,构建自己的 APISIX-Base 环境。 -如果你希望 APISIX 运行在原生的 OpenResty 上,那么只支持 OpenResty 1.19.3.2 及以上的版本。 +如果你希望 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`。 +APISIX 的配置方式是用自定义的 `conf/config.yaml` 中的内容覆盖默认的 `conf/config-default.yaml`,如果某个配置项在 `conf/config.yaml` 中不存在,那么就使用 `conf/config-default.yaml` 中的配置。在 3.0.0 中,我们调整了 `conf/config-default.yaml` 配置文件中的部分细节,具体内容如下。 ###### 移动配置项 @@ -74,9 +74,9 @@ APISIX 的配置方式是用自定义的 `conf/config.yaml` 中的内容覆盖 调整内容: - * `config_center` 功能改由 `deployment` 下面的 `config_provider` 实现 - * `etcd` 字段整体搬迁到 `deployment` 下面 - * 以下的 Admin API 配置移动到 `deployment` 下面的 `admin` 字段 + * `config_center` 功能改由 `deployment` 中的 `config_provider` 实现 + * `etcd` 字段整体迁移到 `deployment` 中 + * 以下的 Admin API 配置移动到 `deployment` 中的 `admin` 字段 - admin_key - enable_admin_cors - allow_admin @@ -93,9 +93,9 @@ APISIX 的配置方式是用自定义的 `conf/config.yaml` 中的内容覆盖 调整内容: - * 去除 `apisix.ssl.enable_http2` 和 `apisix.ssl.listen_port`,使用 `apisix.ssl.listen` 替代 + * 去除 `apisix.ssl.enable_http2` 和 `apisix.ssl.listen_port`,使用 `apisix.ssl.listen` 替代。 - 如果在 `conf/config.yaml` 中有这样的配置 + 如果在 `conf/config.yaml` 中有这样的配置: ```yaml ssl: @@ -103,7 +103,7 @@ APISIX 的配置方式是用自定义的 `conf/config.yaml` 中的内容覆盖 listen_port: 9443 ``` - 在 3.0.0 中需要转换成 + 则在 3.0.0 版本中需要转换成如下所示: ```yaml ssl: @@ -112,9 +112,9 @@ APISIX 的配置方式是用自定义的 `conf/config.yaml` 中的内容覆盖 enable_http2: true ``` - * 去除 `nginx_config.http.lua_shared_dicts`, 用 `nginx_config.http.custom_lua_shared_dict` 替代,这个配置用于声明自定义插件的共享内存 + * 去除 `nginx_config.http.lua_shared_dicts`,用 `nginx_config.http.custom_lua_shared_dict` 替代,这个配置用于声明自定义插件的共享内存。 - 如果在 `conf/config.yaml` 中有这样的配置 + 如果在 `conf/config.yaml` 中有这样的配置: ```yaml nginx_config: @@ -123,7 +123,7 @@ APISIX 的配置方式是用自定义的 `conf/config.yaml` 中的内容覆盖 my_dict: 1m ``` - 在 3.0.0 中需要转换成 + 则在 3.0.0 版本中需要转换成如下所示: ```yaml nginx_config: @@ -132,16 +132,16 @@ APISIX 的配置方式是用自定义的 `conf/config.yaml` 中的内容覆盖 my_dict: 1m ``` - * 去除 `etcd.health_check_retry`,用 `deployment.etcd.startup_retry` 替代,这个配置用于在启动时,重试连接 etcd 的次数 + * 去除 `etcd.health_check_retry`,用 `deployment.etcd.startup_retry` 替代,这个配置用于在启动时,重试连接 etcd 的次数。 - 如果在 `conf/config.yaml` 中有这样的配置 + 如果在 `conf/config.yaml` 中有这样的配置: ```yaml etcd: health_check_retry: 2 ``` - 在 3.0.0 中需要转换成 + 则在 3.0.0 版本中需要转换成如下所示: ```yaml deployment: @@ -149,16 +149,16 @@ APISIX 的配置方式是用自定义的 `conf/config.yaml` 中的内容覆盖 startup_retry: 2 ``` - * 去除 `apisix.port_admin`,用 `deployment.apisix.admin_listen` 替代 + * 去除 `apisix.port_admin`,用 `deployment.apisix.admin_listen` 替代。 - 如果在 `conf/config.yaml` 中有这样的配置 + 如果在 `conf/config.yaml` 中有这样的配置: ```yaml apisix: port_admin: 9180 ``` - 在 3.0.0 中需要转换成 + 则在 3.0.0 中需要转换成如下所示: ```yaml deployment: @@ -168,7 +168,7 @@ APISIX 的配置方式是用自定义的 `conf/config.yaml` 中的内容覆盖 port: 9180 ``` - * 修改 `enable_cpu_affinity` 的默认值为 `false`。原因:越来越多的用户通过容器部署 APISIX。由于 Nginx 的 worker_cpu_affinity 不计入 cgroup,默认启用 worker_cpu_affinity 会影响 APISIX 的行为,例如,多个实例会被绑定到一个 CPU 上。为了避免这个问题,我们在 `conf/config-default.yaml` 中默认禁用 `enable_cpu_affinity` 选项。 + * 修改 `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` 替代 ##### 数据迁移 @@ -177,18 +177,18 @@ APISIX 的配置方式是用自定义的 `conf/config.yaml` 中的内容覆盖 #### 数据兼容 -在 3.0.0 中,我们调整了部分数据结构,这些调整影响到 APISIX 的路由、上游、插件等数据。3.0.0 版本与 2.15.x 版本之间数据不完全兼容。不能用 3.0.0 版本的 APISIX 直接连接到 2.15.x 版本的 APISIX 使用的 ETCD 集群。 +在 3.0.0 中,我们调整了部分数据结构,这些调整影响到 APISIX 的路由、上游、插件等数据。3.0.0 版本与 2.15.x 版本之间数据不完全兼容。因此,你无法使用 3.0.0 版本的 APISIX 直接连接到 2.15.x 版本 APISIX 使用的 ETCD 集群。 为了保持数据兼容,有两种方式,仅供参考: 1. 梳理 ETCD 中的数据,将不兼容的数据备份然后清除,将备份的数据结构转换成 3.0.0 版本的数据结构,通过 3.0.0 版本的 Admin API 来恢复数据 2. 梳理 ETCD 中的数据,编写脚本,将 2.15.x 版本的数据结构批量转换成 3.0.0 版本的数据结构 -调整内容: +数据层面调整内容如下。 - * 将插件配置的元属性 `disable` 移动到 `_meta` 中 + * 将插件配置的元属性 `disable` 移动到 `_meta` 中。 - `disable` 表示该插件的启用/禁用状态,如果在 ETCD 中存在这样的数据结构 + `disable` 表示该插件的启用/禁用状态,如果在 ETCD 中存在这样的数据结构: ```json { @@ -201,7 +201,7 @@ APISIX 的配置方式是用自定义的 `conf/config.yaml` 中的内容覆盖 } ``` - 在 3.0.0 中,这个插件的数据结构应该变成 + 则在 3.0.0 版本中,这个插件的数据结构应该变成如下所示: ```json { @@ -216,11 +216,11 @@ APISIX 的配置方式是用自定义的 `conf/config.yaml` 中的内容覆盖 } ``` - 注意:`disable` 是插件的元配置,这个调整对所有插件配置生效,不仅仅是 `limit-count` 插件。 + 注意:`disable` 是插件的元配置,该调整对所有插件配置生效,不仅仅是 `limit-count` 插件。 - * 去除路由的 `service_protocol` 字段,使用 `upstream.scheme` 替代 + * 去除路由的 `service_protocol` 字段,使用 `upstream.scheme` 替代。 - 如果在 ETCD 中存在这样的数据结构 + 如果在 ETCD 中存在这样的数据结构: ```json { @@ -235,7 +235,7 @@ APISIX 的配置方式是用自定义的 `conf/config.yaml` 中的内容覆盖 } ``` - 在 3.0.0 中,这个路由的数据结构应该变成 + 则在 3.0.0 版本中,这个路由的数据结构应该变成如下所示: ```json { @@ -250,9 +250,9 @@ APISIX 的配置方式是用自定义的 `conf/config.yaml` 中的内容覆盖 } ``` - * 去除 authz-keycloak 插件中的 `audience` 字段,使用 `client_id` 替代 + * 去除 `authz-keycloak` 插件中的 `audience` 字段,使用 `client_id` 替代。 - 如果在 ETCD 中 authz-keycloak 的插件配置存在这样的数据结构 + 如果在 ETCD 中 `authz-keycloak` 的插件配置存在这样的数据结构: ```json { @@ -265,7 +265,7 @@ APISIX 的配置方式是用自定义的 `conf/config.yaml` 中的内容覆盖 } ``` - 在 3.0.0 中,这个路由的数据结构应该变成 + 则在 3.0.0 中,这个路由的数据结构应该变成如下所示: ```json { @@ -278,9 +278,9 @@ APISIX 的配置方式是用自定义的 `conf/config.yaml` 中的内容覆盖 } ``` - * 去除 mqtt-proxy 插件中的 `upstream`,在插件外部配置 `upstream`,并在插件中引用 + * 去除 `mqtt-proxy` 插件中的 `upstream`,在插件外部配置 `upstream`,并在插件中引用。 - 如果在 ETCD 中 mqtt-proxy 的插件配置存在这样的数据结构 + 如果在 ETCD 中 `mqtt-proxy` 的插件配置存在这样的数据结构: ```json { @@ -298,7 +298,7 @@ APISIX 的配置方式是用自定义的 `conf/config.yaml` 中的内容覆盖 } ``` - 在 3.0.0 中,这个插件的数据结构应该变成 + 则在 3.0.0 版本中,这个插件的数据结构应该变成如下所示: ```json { @@ -323,9 +323,9 @@ APISIX 的配置方式是用自定义的 `conf/config.yaml` 中的内容覆盖 } ``` - * 去除 syslog 插件中的 `max_retry_times` 和 `retry_interval` 字段,使用 `max_retry_count` 和 `retry_delay` 替代 + * 去除 `syslog` 插件中的 `max_retry_times` 和 `retry_interval` 字段,使用 `max_retry_count` 和 `retry_delay` 替代。 - 如果在 ETCD 中 syslog 的插件配置存在这样的数据结构 + 如果在 ETCD 中 `syslog` 的插件配置存在这样的数据结构: ```json { @@ -339,7 +339,7 @@ APISIX 的配置方式是用自定义的 `conf/config.yaml` 中的内容覆盖 } ``` - 在 3.0.0 中,这个插件的数据结构应该变成 + 则在 3.0.0 版本中,这个插件的数据结构应该变成如下所示: ```json { @@ -353,9 +353,9 @@ APISIX 的配置方式是用自定义的 `conf/config.yaml` 中的内容覆盖 } ``` - * 去除 proxy-rewrite 插件中的 `scheme` 字段,在配置上游时,用 `upstream.scheme` 替代 + * 去除 `proxy-rewrite` 插件中的 `scheme` 字段,在配置上游时,用 `upstream.scheme` 替代。 - 如果在 ETCD 中 proxy-rewrite 的插件配置存在这样的数据结构 + 如果在 ETCD 中 `proxy-rewrite` 的插件配置存在这样的数据结构: ```json { @@ -375,7 +375,7 @@ APISIX 的配置方式是用自定义的 `conf/config.yaml` 中的内容覆盖 } ``` - 在 3.0.0 中,这个插件的数据结构应该变成 + 则在 3.0.0 版本中,这个插件的数据结构应该变成如下所示: ```json { @@ -397,13 +397,11 @@ APISIX 的配置方式是用自定义的 `conf/config.yaml` 中的内容覆盖 #### Admin API -我们对 Admin API 进行了一些调整,这些调整是为了使 Admin API 更加易用,更加符合 RESTful 的设计理念。 - -具体内容: +在 3.0.0 版本中,我们对 Admin API 也进行了一些调整。使得 Admin API 更加易用,更加符合 RESTful 的设计理念,具体调整内容如下。 - * 操作资源时(包括查询单个资源和列表资源),删除了响应体中的 `count`、 `action` 和 `node` 字段,并且将 `node` 中的内容提升到响应体的根节点 + * 操作资源时(包括查询单个资源和列表资源),删除了响应体中的 `count`、`action` 和 `node` 字段,并将 `node` 中的内容提升到响应体的根节点。 - 在 2.x 版本中,通过 Admin API 查询 `/apisix/admin/routes/1` 的响应格式: + 在 2.x 版本中,通过 Admin API 查询 `/apisix/admin/routes/1` 的响应格式是这样的: ```json { @@ -418,7 +416,7 @@ APISIX 的配置方式是用自定义的 `conf/config.yaml` 中的内容覆盖 } ``` - 在 3.0.0 中,通过 Admin API 查询 `/apisix/admin/routes/1` 资源的响应格式: + 在 3.0.0 版本中,通过 Admin API 查询 `/apisix/admin/routes/1` 资源的响应格式调整为如下所示: ```json { @@ -429,9 +427,9 @@ APISIX 的配置方式是用自定义的 `conf/config.yaml` 中的内容覆盖 } ``` - * 查询列表资源时,删除 `dir` 字段,新增 `list` 字段,存放列表资源的数据,新增 `total` 字段,存放列表资源的总数 + * 查询列表资源时,删除 `dir` 字段,新增 `list` 字段,存放列表资源的数据;新增 `total` 字段,存放列表资源的总数。 - 在 2.x 版本中,通过 Admin API 查询 `/apisix/admin/routes` 的响应格式: + 在 2.x 版本中,通过 Admin API 查询 `/apisix/admin/routes` 的响应格式是这样的: ```json { @@ -458,7 +456,7 @@ APISIX 的配置方式是用自定义的 `conf/config.yaml` 中的内容覆盖 } ``` - 在 3.0.0 中,通过 Admin API 查询 `/apisix/admin/routes` 资源的响应格式: + 在 3.0.0 版本中,通过 Admin API 查询 `/apisix/admin/routes` 资源的响应格式调整为如下所示: ```json { @@ -481,32 +479,38 @@ APISIX 的配置方式是用自定义的 `conf/config.yaml` 中的内容覆盖 } ``` - * 调整 ssl 资源的请求路径,从 `/apisix/admin/ssl/{id}` 改为 `/apisix/admin/ssls/{id}` + * 调整 ssl 资源的请求路径,从 `/apisix/admin/ssl/{id}` 调整为 `/apisix/admin/ssls/{id}`。 - 在 2.x 版本中,通过 Admin API 操作 ssl 资源: + 在 2.x 版本中,通过 Admin API 操作 ssl 资源是这样的: ```shell curl -i http://{apisix_listen_address}/apisix/admin/ssl/{id} ``` - 在 3.0.0 中,通过 Admin API 操作 ssl 资源: + 在 3.0.0 版本中,通过 Admin API 操作 ssl 资源调整为如下所示: ```shell curl -i http://{apisix_listen_address}/apisix/admin/ssls/{id} ``` - * 调整 proto 资源的请求路径,从 `/apisix/admin/proto/{id}` 改为 `/apisix/admin/protos/{id}` + * 调整 proto 资源的请求路径,从 `/apisix/admin/proto/{id}` 调整为 `/apisix/admin/protos/{id}`。 - 在 2.x 版本中,通过 Admin API 操作 proto 资源: + 在 2.x 版本中,通过 Admin API 操作 proto 资源是这样的: ```shell curl -i http://{apisix_listen_address}/apisix/admin/proto/{id} ``` - 在 3.0.0 中,通过 Admin API 操作 proto 资源: + 在 3.0.0 版本中,通过 Admin API 操作 proto 资源调整为如下所示: ```shell curl -i http://{apisix_listen_address}/apisix/admin/protos/{id} ``` -我们也调整了 Admin API 的端口为 9180。 +除以上内容外,我们也将 Admin API 的端口调整为 9180。 + +## 总结 + +Apache APISIX 3.0.0 版本的发布,将产品的更多细节迭代了一大步。由于大版本的更新迭代会导致一些配置与数据也相应进行调整,为此我们为您整理了这份 APISIX 升级指南。希望对各位在使用 APISIX 的过程中,对于版本的更新操作也更得心应手。 + +如果您有任何问题或意见,欢迎随时在社区进行交流。