升级指南

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-Base）。你可以参考 api7/apisix-build-tools 中的代码，构建自己的 APISIX-Base 环境。

如果你希望 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 集群。

为了保持数据兼容，有两种方式，仅供参考：

1. 梳理 ETCD 中的数据，将不兼容的数据备份然后清除，将备份的数据结构转换成 3.0.0 版本的数据结构，通过 3.0.0 版本的 Admin API 来恢复数据
2. 梳理 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 的过程中，对于版本的更新操作也更得心应手。

如果您有任何问题或意见，欢迎随时在社区进行交流。