> ## Documentation Index
> Fetch the complete documentation index at: https://docs.avibe.bot/llms.txt
> Use this file to discover all available pages before exploring further.

# 反向代理与自定义域名

> 在自定义域名上用你自己的反向代理承载本地 Avibe Web UI —— 把代理登记为可信来源,让转发的 host 与 origin 校验通过。

# 反向代理与自定义域名

Avibe 的 Web UI 跑在你自己的机器上,默认监听 `127.0.0.1:5123`。从别处访问它最简单的方式是 [avibe.bot 隧道](/zh/concepts/remote-ui)。如果你想自己承载 —— 比如用 **nginx 挂在你自己的域名上** —— Avibe 需要知道它可以信任你的代理转发过来的 host。

## 为什么裸反向代理会被挡下

Avibe 会校验每个请求的 origin 是否与它实际被访问的地址一致。正是这道校验挡住了恶意页面伪造请求打到你本地的控制台。

自 **PR #781** 起,Avibe **默认不再信任 `X-Forwarded-Host` 头**。除非请求来自你显式登记过的代理,否则 Avibe 会忽略转发来的 host,改用它看到的直连连接来算 origin —— 例如 `http://127.0.0.1:5123`。

于是,如果 nginx 对外提供 `https://avibe.example.com`,但代理没被登记:浏览器发来的是 `avibe.example.com`,而 Avibe 仍以为自己是 `127.0.0.1`。两者不一致,请求被拒:

* 状态变更类操作返回 **`403`(`invalid origin`)**;
* 视你的 avibe.bot 远程访问配置而定,页面本身的加载可能返回 **`503`(host 不匹配)**。

## 让它跑起来

需要做两件事:把代理的 IP 登记为可信,并转发正确的头。

### 1. 把代理登记为可信

把 `VIBE_UI_TRUSTED_PROXY_IPS` 设为 Avibe 看到你的代理**从哪个地址连进来** —— 是直连的对端,不是浏览器:

* **nginx 与 Avibe 同机**,反代到 Avibe 的回环监听 → `127.0.0.1`
* **nginx 在另一台主机或容器** → 它的真实 IP,或一个 CIDR 段

多个条目用逗号分隔;纯 IP 和 CIDR 段都支持:

```bash theme={null}
VIBE_UI_TRUSTED_PROXY_IPS=127.0.0.1
# 或者,代理在局域网:
VIBE_UI_TRUSTED_PROXY_IPS=10.0.0.0/24,192.168.1.5
```

把它设在运行 `vibe` 服务的环境里 —— 你的 shell 配置、服务管理器单元,或容器环境 —— 然后重启 Avibe。当该值为空(默认),不信任任何代理,转发来的 host 一律被忽略。

<Note>
  后续版本可能会允许你在 Web UI 设置里配置可信代理,而不必用环境变量。在那之前,请使用 `VIBE_UI_TRUSTED_PROXY_IPS`。
</Note>

### 2. 在 nginx 侧转发这些头

可信代理必须把浏览器的 host 与 scheme 透传过来,否则 Avibe 无从可信:

```nginx theme={null}
proxy_set_header Host              $host;
proxy_set_header X-Forwarded-Host  $host;
proxy_set_header X-Forwarded-Proto $scheme;
```

如果你对外使用非标准端口,请一并转发 `proxy_set_header X-Forwarded-Port $server_port;`。

### 完整 nginx 示例

```nginx theme={null}
server {
    listen 443 ssl;
    server_name avibe.example.com;

    # ssl_certificate / ssl_certificate_key ...

    location / {
        proxy_pass http://127.0.0.1:5123;   # 你的 Avibe Web UI 地址

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

        # 实时更新走 WebSocket
        proxy_http_version 1.1;
        proxy_set_header Upgrade    $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}
```

<Warning>
  **只有在你没有运行 avibe.bot 隧道时,才可以信任 `127.0.0.1`。**

  隧道的 `cloudflared` 同样是从 `127.0.0.1` 连进 Avibe 的。如果你在隧道开着的时候把回环设为可信,那么任何经隧道进来的请求都能伪造 `X-Forwarded-Host` —— 这等于把 PR #781 修复的那个 origin 伪造漏洞重新打开,这次是对着你对外的隧道。

  如果你**同时**需要反向代理和隧道,应让 nginx 通过一个**非回环**地址访问 Avibe(把 Avibe 绑到局域网或网桥接口,并让 nginx 指向那里),然后只把那个地址登记进 `VIBE_UI_TRUSTED_PROXY_IPS`。不要放 `127.0.0.1`。
</Warning>

## 验证

重启 Avibe,然后在你的自定义域名上打开 Web UI 并登录。如果仍然遇到 `403 invalid origin` 或 `503` host 不匹配:

* 确认浏览器地址与 nginx 转发的 host(`$host`)一致;
* 确认代理的真实来源 IP 就是你登记的那个 —— 格式不合法的值会被跳过,并在 Avibe 日志里留下 `Ignoring invalid VIBE_UI_TRUSTED_PROXY_IPS entry` 警告;
* 确认你在设置变量之后重启了 Avibe。

## 从 PR #781 之前的版本升级

对于把 Avibe 挂在自定义域名反向代理后面的自建部署,这是一个**破坏性变更**。PR #781 之前,Avibe 会接受任何来源的 `X-Forwarded-Host`;之后,除非代理被登记,转发来的 host 一律被忽略 —— 所以升级会让原本能用的自定义域名变成 `403`/`503`,直到你完成迁移。

迁移步骤:

1. 把 `VIBE_UI_TRUSTED_PROXY_IPS` 设为你的代理 IP(见上),并注意回环/隧道那条警告。
2. 确保 nginx 转发了 `Host`、`X-Forwarded-Host` 和 `X-Forwarded-Proto`。
3. 重启 Avibe。

avibe.bot 隧道([`vibe remote`](/zh/concepts/remote-ui))不受影响、无需改动 —— 它校验的是自己那套对外 origin,并不依赖 `X-Forwarded-Host`。