Nginx 反向代理配置

使用 Nginx 作为 Data Agent 的反向代理，可以提供负载均衡、SSL 终止、静态文件服务等能力。

基础配置

以下是一个完整的 Nginx 反向代理配置示例：

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://127.0.0.1:3000;

        # 禁用所有缓冲（流式响应必需）
        proxy_buffering off;
        proxy_request_buffering off;

        # 增加读取超时，SSE 是长连接（默认 60s）
        proxy_read_timeout 3600s;

        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        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;
        proxy_cache_bypass $http_upgrade;
    }
}

关键配置说明

参数	默认值	建议值	说明
`proxy_buffering`	on	off	禁用响应缓冲，LLM 流式输出必需
`proxy_request_buffering`	on	off	禁用请求缓冲，适合大文件上传
`proxy_read_timeout`	60s	3600s	后端响应超时，SSE 长连接需要调大

子路径部署

如果需要将 Data Agent 部署到子路径（如 https://your-domain.com/data-agent/），需要同时配置环境变量和 Nginx。

环境变量配置

在 docker-compose.yml 中添加 APP_PUBLIC_PATH 环境变量：

services:
  app:
    environment:
      - APP_PUBLIC_PATH=/data-agent/  # 替换为您的子路径

Nginx 配置

server {
    listen 80;
    server_name your-domain.com;

    location /data-agent/ {
        proxy_pass http://127.0.0.1:3000/data-agent/;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";
        proxy_set_header Host $host;

        # 禁用缓冲（流式响应必需）
        proxy_buffering off;
        proxy_request_buffering off;

        # 增加读取超时，SSE 是长连接（默认 60s）
        proxy_read_timeout 3600s;
    }
}

注意：APP_PUBLIC_PATH 的值必须与 Nginx location 的路径保持一致，且必须以 / 开头和结尾。

Kubernetes Ingress 配置

在 Kubernetes 环境中使用 Nginx Ingress Controller 时，需要在 Ingress 资源的 annotations 中添加以下配置来支持 SSE 流式响应：

annotations:
  # 关闭代理缓冲，让响应数据实时转发，不等待缓冲区填满
  nginx.ingress.kubernetes.io/proxy-buffering: "off"

  # 关闭请求体缓冲，让客户端请求数据实时发送到后端（需要控制器版本 >= 0.21.0）
  nginx.ingress.kubernetes.io/proxy-request-buffering: "off"

  # 延长读取超时，SSE 长连接需要（单位：秒）
  nginx.ingress.kubernetes.io/proxy-read-timeout: "3600"

参数说明

参数	作用	对应 Nginx 指令
`proxy-buffering`	关闭响应缓冲，数据实时转发给客户端	`proxy_buffering off;`
`proxy-request-buffering`	关闭请求缓冲，客户端数据实时发往后端	`proxy_request_buffering off;`
`proxy-read-timeout`	两次读取操作之间的最长间隔，默认 60 秒	`proxy_read_timeout 3600s;`

注意事项

配置项 proxy-request-buffering 需要 ingress-nginx 控制器版本 >= 0.21.0
proxy-read-timeout 的值 3600 表示 3600 秒（1 小时），可根据业务实际需求调整
如果后端应用可能覆盖缓冲设置，建议额外添加以下配置：

nginx.ingress.kubernetes.io/configuration-snippet: |
  add_header X-Accel-Buffering no;

完整示例

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: data-agent-ingress
  annotations:
    nginx.ingress.kubernetes.io/proxy-buffering: "off"
    nginx.ingress.kubernetes.io/proxy-request-buffering: "off"
    nginx.ingress.kubernetes.io/proxy-read-timeout: "3600"
spec:
  rules:
    - host: your-domain.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: data-agent-service
                port:
                  number: 3000

阿里云 ALB Ingress 配置

如果你使用的是阿里云 ALB（Application Load Balancer）Ingress，超时配置方式与 Nginx Ingress 不同——ALB Ingress 没有对应的 annotations 配置项，需要通过与其关联的 AlbConfig 自定义资源中的 listeners 字段来设置。

配置方式

在 AlbConfig 资源的 spec.listeners 下修改或添加 requestTimeout 和 idleTimeout 字段：

apiVersion: alibabacloud.com/v1
kind: AlbConfig
metadata:
  name: <your-albconfig-name>  # 替换为你的 AlbConfig 名称
spec:
  config:
    # ... 实例配置 ...
  listeners:
    - port: 80
      protocol: HTTP
      requestTimeout: 600   # 请求超时时间，最大 600 秒（默认60）
      idleTimeout: 120       # 空闲连接超时时间（秒）

参数说明

参数	作用	建议值
`requestTimeout`	请求超时时间，SSE 长连接需要调大	`600`（最大值）
`idleTimeout`	空闲连接超时时间，连接无数据传输时的保持时长	`120`

注意事项

requestTimeout 的最大值为 600 秒（1 小时），建议设为最大值以支持长时间的 SSE 流式响应
修改 AlbConfig 后保存即可，变更会自动生效，无需重启任何服务
可以使用 kubectl get albconfig 查看已有的 AlbConfig 资源

配置生效

修改配置后，检查语法并重载：

# 检查配置语法
sudo nginx -t

# 重载配置
sudo nginx -s reload

常见问题

流式输出仍然不生效

如果禁用 proxy_buffering 后流式输出仍不生效，检查：

确认配置已生效：nginx -t && nginx -s reload
检查是否有其他缓存层（如 CDN）
确认后端应用未启用缓冲

#Nginx 反向代理配置

#基础配置

#关键配置说明

#子路径部署

#环境变量配置

#Nginx 配置

#Kubernetes Ingress 配置

#参数说明

#注意事项

#完整示例

#阿里云 ALB Ingress 配置

#配置方式

#参数说明

#注意事项

#配置生效

#常见问题

#流式输出仍然不生效

Nginx 反向代理配置

基础配置

关键配置说明

子路径部署

环境变量配置

Nginx 配置

Kubernetes Ingress 配置

参数说明

注意事项

完整示例

阿里云 ALB Ingress 配置

配置方式

参数说明

注意事项

配置生效

常见问题

流式输出仍然不生效