# 反向代理 (/docs/deploy/reverse-proxy)

## 为什么需要反向代理

Mix Space 默认运行在本地端口（后端 `2333`，前端 `2323`），反向代理可以将域名请求转发到对应端口，并提供 HTTPS、WebSocket 支持。

## 图形化面板

现代服务器面板（如 1Panel、宝塔面板）自带的反向代理已足以满足 Mix Space 的需求（包括 WebSocket），非高级用户建议使用图形化界面操作。

### 宝塔面板

进入 `网站`，在 `反向代理` 栏目下点击 `添加反代`。

- `域名` 填入你将要使用的域名
- `目标` 填写 `URL 地址` + `http://127.0.0.1:2333`

### 1Panel

进入 `网站 > 网站`，创建一个新网站，选择 `反向代理`。

- `主域名` 填入你将要使用的域名，并勾选 `监听 IPV6`
- 代理类型选择 `http`，地址填入 `127.0.0.1:2333`

## Cloudflare Tunnel

<Callout type="warn">
除非你在非完整服务器环境（如 Sealos 或 Huggingface Space）部署，否则不推荐在容器内使用 Cloudflare Tunnel，而应在宿主机配置以避免管理不便。
</Callout>

<Callout type="error">
**Mix Space 镜像不再内置 cloudflared。** 早期版本曾通过 `ENABLE_CLOUDFLARED` 和 `CF_ZERO_TRUST_TOKEN` 两个环境变量由容器内拉起隧道，这两个变量在当前版本的服务端源码中**已不存在**，设置不会有任何效果，启动日志也不会再出现 `Starting Cloudflared Tunnel` 的横幅。
</Callout>

现在需要在**宿主机**自行运行 cloudflared 并回源到 `2333`：

### 详细步骤

1. 在宿主机安装并登录 cloudflared
2. 申请 Cloudflare Zero Trust
3. 添加一条隧道，回源选择 HTTP，端口选择 `2333`
4. 添加一个 Public Hostname 指向该隧道

宿主机上的 cloudflared 进程与容器生命周期无关，重启服务器后需要自行确保它常驻（如 systemd 服务）。

## Nginx 手写配置

<Callout type="warn">
手写配置文件需要较高的技术功底，请量力而行。
</Callout>

<Callout type="info">
自 mx-core **v14** 起，实时通道由 socket.io 迁移为原生 WebSocket，路径为 `/ws/web` 与 `/ws/admin`；以下配置使用 `/ws/` 前缀。若仍在运行 v13 及更早版本，请将对应 location 换回 `/socket.io`。
</Callout>

### 双域名配置

假定前端域名为 `www.example.com`，后端为 `server.example.com`。

后端配置：

```nginx
server {
    location /ws/ {
      proxy_pass http://127.0.0.1:2333;
      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 Upgrade $http_upgrade;
      proxy_set_header Connection "upgrade";
      proxy_buffering off;
      proxy_http_version 1.1;
      proxy_read_timeout 300s;
      proxy_send_timeout 300s;
      add_header Cache-Control no-cache;
    }

    location / {
      proxy_pass http://127.0.0.1:2333;
      proxy_set_header Host $host;
      proxy_set_header X-Real-IP $remote_addr;
      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
      add_header X-Cache $upstream_cache_status;
    }
}
```

前端配置：

```nginx
server {
    location ~* \.(gif|png|jpg|css|js|woff|woff2)$ {
      proxy_pass http://127.0.0.1:2323;
      proxy_set_header Host $host;
      proxy_set_header X-Real-IP $remote_addr;
      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
      expires 30d;
    }

    location / {
      proxy_pass http://127.0.0.1:2323;
      proxy_set_header Host $host;
      proxy_set_header X-Real-IP $remote_addr;
      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
      add_header X-Cache $upstream_cache_status;
      add_header Cache-Control no-cache;
      proxy_intercept_errors on;
    }
}
```

<Callout type="info">
使用双域名配置时：
- API 地址为 `https://server.example.com/api/v3`
- 前端地址为 `https://www.example.com`
- Gateway 为 `https://server.example.com`
- 后台为 `https://server.example.com/proxy/qaqdmin`
</Callout>

### 单域名配置

```nginx
server {
    listen 80;
    listen 443 ssl http2;
    server_name www.example.com;
    index index.html;

    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Host $server_name;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";

    location /ws/ {
        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-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 300s;
        proxy_send_timeout 300s;
        proxy_pass http://127.0.0.1:2333;
    }

    location /api/v3 {
        proxy_pass http://127.0.0.1:2333/api/v3;
    }

    location /render {
        proxy_pass http://127.0.0.1:2333/render;
    }

    location / {
        proxy_pass http://127.0.0.1:2323;
    }

    location /qaqdmin {
        proxy_pass http://127.0.0.1:2333/proxy/qaqdmin;
    }

    location /proxy {
        proxy_pass http://127.0.0.1:2333/proxy;
    }

    ssl_certificate /path/to/fullchain.pem;
    ssl_certificate_key /path/to/privkey.pem;
    ssl_protocols TLSv1.3 TLSv1.2;
    error_page 497 https://$host$request_uri;
}
```

<Callout type="info">
使用单域名配置时：
- API 地址为 `https://www.example.com/api/v3`
- 前端地址为 `https://www.example.com`
- Gateway 为 `https://www.example.com`
- 后台为 `https://www.example.com/proxy/qaqdmin`
</Callout>