Team
881fbf6dbb
- lessons-learned: add two critical issues from first real deployment 1. client enable:false causes auto-removal by x-ui scheduler 2. CF proxy strips Connection header, nginx must hardcode WS headers - xray-inbound-config.md: fix API path, add enable:true to client, hardcode Upgrade/Connection headers in nginx WS location
164 lines
6.2 KiB
Markdown
164 lines
6.2 KiB
Markdown
# x-ui Deploy — 经验沉淀
|
||
|
||
本文件记录在实际部署和使用过程中积累的问题解决方案、最佳配置和注意事项。
|
||
每次遇到新问题或发现更好的配置时，由 agent 询问用户后追加到对应章节。
|
||
|
||
---
|
||
|
||
## 已知问题与解决方案
|
||
|
||
<!-- 格式：
|
||
### [日期] 问题标题
|
||
**环境**: OS / 安装方式（Docker/native）
|
||
**现象**: 描述问题
|
||
**原因**: 根本原因
|
||
**解决**: 具体命令或步骤
|
||
-->
|
||
|
||
_暂无记录_
|
||
|
||
---
|
||
|
||
## 推荐配置
|
||
|
||
<!-- 格式：
|
||
### 配置名称
|
||
**适用场景**: 什么情况下使用
|
||
**配置内容**: 具体参数或命令
|
||
**备注**: 注意事项
|
||
-->
|
||
|
||
_暂无记录_
|
||
|
||
---
|
||
|
||
## VPS 环境备注
|
||
|
||
<!-- 记录特定 VPS 的特殊情况，如端口限制、ISP 封锁、已知可用配置等 -->
|
||
<!-- 格式：
|
||
### <host/domain>
|
||
- 系统: Ubuntu 22.04
|
||
- 安装方式: Docker
|
||
- 可用协议: VLESS+WS+TLS
|
||
- 特殊情况: ...
|
||
-->
|
||
|
||
_暂无记录_
|
||
|
||
---
|
||
|
||
## 已知问题与解决方案
|
||
|
||
### [2026-04-25] x-ui setting 子命令参数不生效（Docker 容器）
|
||
**环境**: Ubuntu 20.04 aarch64 / Docker (ghcr.io/mhsanaei/3x-ui:latest)
|
||
**现象**: `docker exec x-ui x-ui setting -port 54321` 显示帮助菜单而非执行设置
|
||
**原因**: 容器内 `x-ui` 是 shell 脚本包装器，需直接调用 `/app/x-ui` 二进制
|
||
**解决**:
|
||
```bash
|
||
docker exec x-ui /app/x-ui setting -port 54321
|
||
docker exec x-ui /app/x-ui setting -username 'user' -password 'pass' # 用户名和密码必须同时传入
|
||
docker exec x-ui /app/x-ui setting -webBasePath /xui/
|
||
```
|
||
|
||
### [2026-04-25] x-ui panel API 路径与文档不符
|
||
**环境**: Ubuntu 20.04 / Docker (ghcr.io/mhsanaei/3x-ui:latest)
|
||
**现象**: `/xui/API/inbounds/add` 返回 404
|
||
**原因**: 该版本实际 API 路径为 `/xui/panel/api/inbounds/add`（含 base_path 前缀）
|
||
**解决**:
|
||
```bash
|
||
# 正确路径（base_path=/xui/）
|
||
POST http://127.0.0.1:54321/xui/panel/api/inbounds/add
|
||
GET http://127.0.0.1:54321/xui/panel/api/inbounds/list
|
||
```
|
||
|
||
### [2026-04-25] 写入错误的 settings 字段导致面板设置页空白
|
||
**环境**: Ubuntu 20.04 / Docker
|
||
**现象**: 向 settings 表写入 `subURI` 字段后，面板设置页面内容消失
|
||
**原因**: `subURI` 不是有效字段名，导致前端渲染异常
|
||
**解决**: 删除无效字段并重启
|
||
```bash
|
||
docker exec x-ui sqlite3 /etc/x-ui/x-ui.db "DELETE FROM settings WHERE key='subURI';"
|
||
docker restart x-ui
|
||
```
|
||
**正确字段**: 订阅路径只需写入 `subPath`
|
||
|
||
### [2026-04-25] --network host 模式导致面板端口对外暴露
|
||
**环境**: Ubuntu 20.04 / Docker
|
||
**现象**: 容器以 `--network host` 启动，`ss -tlnp` 显示 54321 监听在 `*:54321`
|
||
**原因**: host 网络模式绕过了 Docker 端口绑定，无法用 `-p 127.0.0.1:port:port` 限制
|
||
**解决**: 用 iptables 封锁外部访问
|
||
```bash
|
||
sudo iptables -I INPUT -p tcp --dport 54321 ! -s 127.0.0.1 -j DROP
|
||
sudo netfilter-persistent save # 持久化（如已安装）
|
||
```
|
||
|
||
---
|
||
|
||
## 推荐配置
|
||
|
||
### VLESS + WebSocket + TLS + Cloudflare CDN（中国大陆优化）
|
||
**适用场景**: 有域名、域名托管在 Cloudflare、中国大陆用户
|
||
**配置内容**:
|
||
- Nginx 监听 443，反向代理面板（/xui/）和 WS 入站（/ws/）
|
||
- x-ui inbound: VLESS, listen 127.0.0.1:10000, WS path /ws/
|
||
- Cloudflare: 橙云代理开启，SSL 模式 Full(strict)，WebSocket 开启
|
||
- 客户端: 地址填 CF 优选 IP，SNI 和 Host 填域名
|
||
**备注**: CF 免费版 WebSocket 有并发限制；优选 IP 用 CloudflareSpeedTest 工具测速
|
||
|
||
### 订阅路径安全配置
|
||
**适用场景**: 消除面板安全警告"订阅默认 URI 路径不安全"
|
||
**配置内容**:
|
||
```bash
|
||
RAND=$(cat /proc/sys/kernel/random/uuid | tr -d '-' | head -c 12)
|
||
docker exec x-ui sqlite3 /etc/x-ui/x-ui.db "INSERT OR REPLACE INTO settings (key, value) VALUES ('subPath', '/$RAND/');"
|
||
docker restart x-ui
|
||
```
|
||
**备注**: 只写 `subPath`，不要写 `subURI`（会导致设置页空白）
|
||
|
||
---
|
||
|
||
## VPS 环境备注
|
||
|
||
### 168.138.188.177 (proxy.157301.xyz)
|
||
- **系统**: Ubuntu 20.04 aarch64
|
||
- **云平台**: Oracle Cloud 新加坡
|
||
- **SSH**: 端口 2222，用户 ubuntu，密钥 ~/.ssh/id_ed25519
|
||
- **安装方式**: Docker (--network host)
|
||
- **面板**: https://proxy.157301.xyz/xui/ (端口 54321，iptables 封锁外部访问)
|
||
- **可用协议**: VLESS+WS+TLS，WS 路径 /ws/，经 Nginx 代理
|
||
- **CDN**: Cloudflare 橙云已开启
|
||
- **防火墙**: Oracle Cloud 安全组管理，不使用 ufw
|
||
- **KeePass 条目**: x-ui
|
||
|
||
### [2026-04-25] 客户端创建后被自动移除导致无法连接
|
||
**环境**: Ubuntu 20.04 / Docker (ghcr.io/mhsanaei/3x-ui:latest) / Xray 26.4.17
|
||
**现象**: 入站配置正确，Nginx 返回 101，但代理无法使用，Xray 日志反复出现 `Remove Inbound User due to expiration or traffic limit`
|
||
**原因**: 通过 API 创建客户端时未显式设置 `"enable": true`，x-ui 默认写入 `enable: false`。x-ui 有定时任务会扫描并从 Xray 运行时移除禁用/过期客户端，导致 UUID 被删除，所有连接被拒绝
|
||
**解决**: 通过 API 更新客户端，显式设置 `enable: true`：
|
||
```bash
|
||
curl -s -b /tmp/xui.cookie \
|
||
-X POST http://127.0.0.1:54321/xui/panel/api/inbounds/updateClient/<uuid> \
|
||
-H 'Content-Type: application/json' \
|
||
-d '{"id":<inbound_id>,"settings":"{\"clients\":[{\"id\":\"<uuid>\",\"flow\":\"\",\"enable\":true,\"expiryTime\":0,\"totalGB\":0}]}"}'
|
||
```
|
||
**预防**: 创建客户端时 `addClient` API 的 settings 里必须包含 `"enable":true`：
|
||
```json
|
||
{"id": <inbound_id>, "settings": "{\"clients\":[{\"id\":\"<uuid>\",\"flow\":\"\",\"enable\":true}]}"}
|
||
```
|
||
|
||
### [2026-04-25] Nginx 转发 WebSocket 时 Connection 头丢失
|
||
**环境**: Ubuntu 20.04 / Nginx 1.18 / Cloudflare 橙云代理
|
||
**现象**: Xray 日志 `websocket: the client is not using the websocket protocol: 'upgrade' token not found in 'Connection' header`
|
||
**原因**: Cloudflare 回源时不传递 `Connection: upgrade` 头；若 Nginx 用 `proxy_set_header Connection $http_upgrade` 则当变量为空时传空值
|
||
**解决**: Nginx WS location 里硬编码头部值，不依赖客户端传入：
|
||
```nginx
|
||
location /ws/ {
|
||
proxy_pass http://127.0.0.1:<inbound_port>;
|
||
proxy_http_version 1.1;
|
||
proxy_set_header Upgrade websocket;
|
||
proxy_set_header Connection upgrade;
|
||
proxy_set_header Host $host;
|
||
proxy_read_timeout 86400s;
|
||
}
|
||
```
|