NGINX_SETUP.md

Nginx 反向代理部署指南

本文档说明如何在 Nginx 反向代理后部署 Z.AI2API,支持自定义路径前缀。

问题说明

在使用 Nginx 反向代理时,如果需要将服务部署在自定义路径前缀下(例如 http://domain.com/ai2api), 需要正确配置 ROOT_PATH 环境变量,否则会出现以下问题:

• 后台管理页面跳转错误(缺少路径前缀)
• API 接口请求 404(路径不完整)
• 静态资源加载失败

解决方案

1. 配置环境变量

在 .env 文件中设置 ROOT_PATH 变量,值为 Nginx 配置的 location 路径:

# 示例:部署在 /ai2api 路径下
ROOT_PATH=/ai2api

重要: ROOT_PATH 必须与 Nginx 配置中的 location 路径完全一致。

2. 配置 Nginx

参考 deploy/nginx.conf.example 文件,选择合适的配置模板。

基础配置示例

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

    location /ai2api {
        # 代理到后端服务
        proxy_pass http://127.0.0.1:7860;

        # 传递原始请求信息
        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;

        # SSE 流式响应支持
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_buffering off;
        proxy_cache off;

        # 超时设置
        proxy_read_timeout 300s;
    }
}

3. Docker Compose 配置

如果使用 Docker 部署,需要在 docker-compose.yml 中添加 ROOT_PATH 环境变量:

version: '3.8'
services:
  ai2api:
    image: z-ai2api:latest
    environment:
      - ROOT_PATH=/ai2api
      - LISTEN_PORT=7860
      # ... 其他环境变量
    ports:
      - "7860:7860"

4. 重启服务

# 重载 Nginx 配置
sudo nginx -t
sudo systemctl reload nginx

# 重启应用(Docker)
docker-compose restart

# 或重启应用(直接运行)
# 停止服务后重新启动

访问地址

配置完成后,服务访问地址如下:

• API 端点: http://your-domain.com/ai2api/v1/chat/completions
• 模型列表: http://your-domain.com/ai2api/v1/models
• 管理后台: http://your-domain.com/ai2api/admin/login
• 根路径: http://your-domain.com/ai2api/

配置示例

示例 1: 部署在 /api 路径下

.env 配置:

ROOT_PATH=/api

Nginx 配置:

location /api {
    proxy_pass http://127.0.0.1:7860;
    # ... 其他配置
}

访问地址: http://domain.com/api/admin/login

示例 2: 部署在根路径(无前缀)

.env 配置:

ROOT_PATH=

Nginx 配置:

location / {
    proxy_pass http://127.0.0.1:7860;
    # ... 其他配置
}

访问地址: http://domain.com/admin/login

示例 3: 多级路径前缀

.env 配置:

ROOT_PATH=/services/ai/chat

Nginx 配置:

location /services/ai/chat {
    proxy_pass http://127.0.0.1:7860;
    # ... 其他配置
}

访问地址: http://domain.com/services/ai/chat/admin/login

常见问题排查

1. 404 错误

现象: 访问页面或 API 时返回 404

可能原因:

• ROOT_PATH 配置与 Nginx location 路径不匹配
• Nginx 配置错误或未重载

解决方法:

• 检查 .env 中的 ROOT_PATH 是否与 Nginx location 完全一致
• 确认 Nginx 配置无误: sudo nginx -t
• 重载 Nginx: sudo systemctl reload nginx
• 重启应用服务

2. 静态资源加载失败

现象: 管理后台页面样式错乱,控制台显示 CSS/JS 404

可能原因:

• ROOT_PATH 未配置或配置错误
• 静态文件路径未包含前缀

解决方法:

• 确保 ROOT_PATH 正确配置并重启服务
• 检查浏览器开发者工具中的资源请求路径

3. 流式响应中断

现象: SSE 流式响应提前终止或无法正常工作

可能原因:

• Nginx 启用了缓冲
• 超时时间设置过短

解决方法: 在 Nginx 配置中添加:

proxy_buffering off;
proxy_cache off;
proxy_read_timeout 300s;

4. CORS 错误

现象: 浏览器控制台显示跨域请求被阻止

可能原因:

• Nginx 未正确传递请求头

解决方法: 确保 Nginx 配置中包含:

proxy_set_header Host $host;
proxy_set_header X-Forwarded-Proto $scheme;

验证配置

配置完成后,可以通过以下方式验证:

1. 访问健康检查端点:

   curl http://your-domain.com/ai2api/v1/models
   

2. 访问管理后台: 在浏览器打开 http://your-domain.com/ai2api/admin/login

3. 测试 API 请求:

   curl -X POST http://your-domain.com/ai2api/v1/chat/completions \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer your-api-key" \
     -d '{
       "model": "GLM-4.6",
       "messages": [{"role": "user", "content": "Hello"}],
       "stream": false
     }'
   

进阶配置

HTTPS 配置

server {
    listen 443 ssl http2;
    server_name your-domain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location /ai2api {
        proxy_pass http://127.0.0.1:7860;
        proxy_set_header X-Forwarded-Proto https;
        # ... 其他配置
    }
}

负载均衡

upstream ai2api_backend {
    server 127.0.0.1:7860;
    server 127.0.0.1:8081;
    server 127.0.0.1:8082;
}

server {
    listen 80;
    location /ai2api {
        proxy_pass http://ai2api_backend;
        # ... 其他配置
    }
}

参考资料

• FastAPI Behind a Proxy
• Nginx Proxy Module
• 完整配置示例: deploy/nginx.conf.example