common-skills/skills/xui-deploy/references/lessons-learned.md

x-ui Deploy — 经验沉淀

本文件记录在实际部署和使用过程中积累的问题解决方案、最佳配置和注意事项。 每次遇到新问题或发现更好的配置时，由 agent 询问用户后追加到对应章节。

---

已知问题与解决方案

暂无记录

---

推荐配置

暂无记录

---

VPS 环境备注

暂无记录

---

已知问题与解决方案

[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 二进制 解决:

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 前缀） 解决:

# 正确路径（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 不是有效字段名，导致前端渲染异常 解决: 删除无效字段并重启

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 封锁外部访问

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 路径不安全" 配置内容:

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：

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：

{"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 里硬编码头部值，不依赖客户端传入：

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;
}