Apache APISIX 中 Nginx 配置迁移的注意事项与实践

在将 Nginx 配置迁移到 Apache APISIX 时，开发者可能会遇到一些意料之外的问题。本文将通过一个典型场景，详细分析配置迁移过程中的关键差异点，并提供解决方案。

问题背景

在 Nginx 配置中，我们通常会设置 upstream 和 server 块来处理请求转发。例如：

upstream gateway {
  server 127.0.0.1:3001;
}

server {
  listen 8888;
  server_name test.com;

  location / {
    proxy_set_header Host $host;
    proxy_pass http://gateway;
  }
}

当直接转换为 APISIX 配置时，可能会遇到请求返回 404 的问题，尽管相同的请求在 Nginx 中能正常返回 200。

配置差异分析

APISIX 的等效配置看似简单：

{
  "uri": "/*",
  "upstream_id": "xxxx",
  "name": "test"
}

{
  "type": "roundrobin",
  "nodes": [
    {
      "host": "127.0.0.1",
      "port": 3001,
      "weight": 1
    }
  ]
}

但实际运行中，这种配置可能导致请求失败。核心原因在于 Nginx 的 proxy_set_header Host $host 指令在 APISIX 中需要显式配置。

解决方案

要使 APISIX 正确转发请求，需要额外配置以下参数：

1. proxy-rewrite 插件：用于重写请求头
2. pass_host 参数：指定主机传递方式
3. upstream_host 参数：设置上游主机名

完整配置示例如下：

{
  "uri": "/*",
  "upstream_id": "xxxx",
  "name": "test",
  "plugins": {
    "proxy-rewrite": {
      "headers": {
        "Host": "实际域名"
      }
    }
  },
  "pass_host": "rewrite",
  "upstream_host": "实际域名"
}

技术原理

在 HTTP 协议中，Host 头字段至关重要，它决定了服务器如何响应请求。Nginx 默认会将客户端请求的 Host 头传递给上游服务器，而 APISIX 出于安全考虑，默认行为有所不同。

pass_host 参数有三种模式：

• pass：传递客户端原始 Host 头
• node：使用上游节点的主机名
• rewrite：使用自定义的主机名

在迁移场景中，我们通常需要设置为 "rewrite" 模式，并通过 upstream_host 指定具体值，以匹配 Nginx 的行为。

最佳实践

1. 在迁移配置时，始终检查 Host 头处理逻辑
2. 对于复杂的转发规则，建议使用 APISIX 的插件系统增强功能
3. 测试时使用 curl -v 命令验证请求头是否正确传递
4. 考虑使用 APISIX 的变量系统（如 $host）实现动态配置

通过理解这些差异点，开发者可以更顺利地将 Nginx 配置迁移到 APISIX，充分发挥 APISIX 作为云原生 API 网关的优势。