Nginx 反向代理路由说明文档

适用于：同一域名下，根据不同 Path 转发到不同后端服务
示例域名：example.com

1. 背景说明

当前后端服务部署在不同端口，例如：

需要通过 同一个域名 https://example.com
根据不同路径（Path）转发到不同后端接口。

2. 最终 Nginx 配置示例（推荐）

以下是推荐的 Nginx 配置模板：

server {
    listen 80;
    server_name example.com;

    # 默认服务
    location / {
        proxy_pass http://127.0.0.1:3000/;
        proxy_set_header Host              $host;
        proxy_set_header X-Real-IP         $remote_addr;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # agent-dev 服务
    location /agent-dev/ {
        proxy_pass http://127.0.0.1:6001/;
        proxy_set_header Host              $host;
        proxy_set_header X-Real-IP         $remote_addr;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # agent-prod 服务
    location /agent-prod/ {
        proxy_pass http://127.0.0.1:6003/;
        proxy_set_header Host              $host;
        proxy_set_header X-Real-IP         $remote_addr;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

3. 代理路径规则说明（重要）

✔️ 配置中代理以 / 结尾：

proxy_pass http://127.0.0.1:6001/;

代表：

• 会移除匹配到的前缀 /agent-dev/
• 然后把后面路径拼到后端服务

4. 请求路径与实际转发说明

4.1 默认服务（3000）

前端请求

POST https://example.com/v1/message/memory

实际转发

http://127.0.0.1:3000/v1/message/memory

4.2 Agent Dev 服务（6001）

前端请求

POST https://example.com/agent-dev/v1/message/memory

实际转发

http://127.0.0.1:6001/v1/message/memory

4.3 Agent Prod 服务（6003）

前端请求

POST https://example.com/agent-prod/v1/message/memory

实际转发

http://127.0.0.1:6003/v1/message/memory

5. 后端接口请求示例（前端代码）

JavaScript / Axios 示例

axios.post('https://example.com/agent-dev/v1/message/memory', {
    userId: 123,
    content: "Hello"
})
.then(res => console.log(res.data))
.catch(err => console.error(err));

Curl 测试示例

curl -X POST https://example.com/agent-dev/v1/message/memory \
     -H "Content-Type: application/json" \
     -d '{"msg":"hello"}'

6. 常见问题 FAQ

Q1: 为什么访问 /agent-dev/ 要加最后的斜杠？

因为：

location /agent-dev/ { ... }
proxy_pass http://127.0.0.1:6001/;

表示：
移除路径前缀 /agent-dev/ 并转发后续路径

Q2: 不加 / 会怎么样？

比如：

proxy_pass http://127.0.0.1:6001;

则不会自动剥离 /agent-dev/，转发路径会变成：

http://127.0.0.1:6001/agent-dev/v1/message/memory

大多数后端不希望带这个前缀，所以推荐加 /。

Q3: 要怎么确保配置生效？

执行：

nginx -t     # 检查配置
systemctl reload nginx   # 重载