Skip to content

🚀 使用 Docker Compose 部署 x-ui

x-ui 是一款支持多协议多用户的 xray 可视化Web管理面板。它通过友好的 Web 界面，让用户能够轻松配置和管理代理服务，无需手动编辑复杂的配置文件。

📝 项目简介

x-ui 是一个开源的前端用户界面库，致力于提供丰富、美观、易于使用的 UI 组件。其设计理念基于模块化和组件化，让开发者能够以最小的工作量实现最佳的界面效果。

核心特点：

  • 组件丰富：x-ui 提供了包括按钮、表单、表格、下拉菜单、标签页、通知、轮播图等在内的多种 UI 组件
  • 响应式布局：支持多种设备屏幕，能够自动适应不同分辨率和屏幕大小
  • 主题定制：提供多种主题样式，且支持自定义主题，满足个性化设计需求
  • 易于集成：可以轻松与各种前端框架和库集成，如 React、Vue、Angular 等

📝 项目简介2

x-ui 是一款基于 Xray 核心 开发的开源可视化代理管理面板，专注于简化代理节点的创建、管理与监控。它支持 VMESS、VLESS、Trojan、Shadowsocks（含 2022 版本）等主流代理协议，通过 Web 图形界面即可完成节点配置、流量统计、日志查看等操作，无需手动编写 Xray 复杂配置文件。

x-ui 尤其适合个人或小型团队搭建私有代理服务，兼顾易用性与灵活性，核心优势如下：

  1. 多协议全面支持：覆盖 VMESS、VLESS、Trojan、Shadowsocks/ShadowsocksR/Shadowsocks 2022，适配不同场景（如绕过网络限制、加密传输）；
  2. 可视化管理零门槛：Web 面板直观展示节点列表、在线状态、实时流量，支持鼠标点击修改参数（端口、加密方式、流量限制），新手无需记命令；
  3. 数据持久化安全：节点配置、用户数据、SSL 证书通过本地目录挂载存储，容器删除后重启可无缝恢复，避免配置丢失；
  4. 灵活端口与协议：支持 TCP/UDP 双协议端口映射，可自定义代理端口范围（如配置中的 8100-8105），适配不同网络环境；
  5. 轻量低资源占用：容器镜像体积约 100MB，运行时内存占用 < 100MB，1 核 1GB 服务器即可稳定运行，兼容 x86/ARM 架构（如树莓派、NAS）；
  6. SSL 证书集成：支持自定义 SSL 证书（挂载 ssl_cert 目录），可启用 TLS 加密传输，提升代理安全性与抗检测能力。

🔧 部署前准备

系统环境要求

项目 最低配置 推荐配置
CPU 1核 2核及以上
内存 1GB 2GB及以上
磁盘空间 10GB 20GB SSD
操作系统 Linux (64位) Ubuntu 20.04/Debian 11

环境检查

  1. 检查 Docker 服务状态 bash systemctl status docker 确保 Docker 服务处于 active (running) 状态

  2. 检查 Docker 版本 bash docker --version

  3. 创建部署目录

   mkdir -p /home/compose/x-ui && cd /home/compose/x-ui

⚙️ 配置 Docker Compose

准备配置文件

创建 docker-compose.yml 文件：

#version: "3.2"
services:
  x-ui:
    # x-ui 官方镜像（enwaiax 维护版，稳定且更新及时）
    image: enwaiax/x-ui
    container_name: x-ui  # 容器名称，便于管理（如停止/查看日志）
    ports:
      # 管理面板端口：主机 8051 → 容器 54321（容器内默认面板端口不可改，主机端口可自定义）
      - 8051:54321 # 管理面板端口映射
      # 代理节点端口范围：主机 8100-8105 → 容器 8100-8105（TCP/UDP 双协议，支持多节点）
      - 8100-8105:8100-8105/tcp
      - 8100-8105:8100-8105/udp
      # 备用代理端口：主机 444 → 容器 444（TCP/UDP，如单独部署 Trojan 节点）
      - 444:443/tcp
      - 444:443/udp
    tmpfs:
      # 临时文件系统：提升容器性能，减少磁盘 IO（/tmp 临时文件、/run 进程 PID、/run/lock 锁文件）
      - /tmp
      - /run
      - /run/lock
    environment:
      TZ: 'Asia/Shanghai'  # 时区设置（确保面板日志时间与本地一致，避免时间错乱）
    volumes:
      # 系统控制组挂载：兼容 Linux 系统，确保容器内进程管理正常（只读，不可修改）
      - /sys/fs/cgroup:/sys/fs/cgroup:ro
      # 核心配置挂载：本地 ./x-ui → 容器 /etc/x-ui（存储节点配置、用户数据，必须挂载！）
      - ./x-ui/:/etc/x-ui
      # SSL 证书挂载：本地 ./ssl_cert → 容器 /root/cert（存储自定义证书，启用 TLS 需配置）
      - ./ssl_cert/:/root/cert/
    restart: unless-stopped  # 容器退出后自动重启（除非手动停止，保障代理服务稳定）

关键配置说明

  1. 镜像选择：使用 enwaiax/x-ui 镜像，这是一个稳定维护的版本

  2. 端口映射：

  3. 8051:54321：Web 管理面板端口
  4. 8100-8105：代理服务端口范围

  5. 444:443：HTTPS 代理端口

  6. 数据持久化：

  7. ./x-ui/:/etc/x-ui：x-ui 配置文件目录

  8. ./ssl_cert/:/root/cert/：SSL 证书目录

  9. 环境配置：

  10. TZ: 'Asia/Shanghai'：设置容器时区
  11. restart: unless-stopped：自动重启策略

🚀 启动与验证

启动服务

docker compose up -d

验证服务状态

  1. 检查容器运行状态 bash docker ps 应该看到 x-ui 容器处于 Up 状态

  2. 查看服务日志

   docker compose logs -f
  1. 访问 Web 界面 在浏览器中访问 http://你的服务器IP:8051

初始登录与安全设置

  • 默认登录信息：
  • 用户名：admin

  • 密码：admin

  • 安全设置：

  • 立即修改默认用户名和密码
  • 建议开启 HTTPS 访问
  • 设置面板根路径增强安全性

🚀 启动与验证2

验证部署状态

（1）检查容器是否正常运行

执行命令，若 x-ui 容器的 State 为 Up，说明启动成功：

docker compose ps
  • 若状态为 Exited（退出），执行以下命令查看错误日志（核心排查方法）：
    # 实时查看日志，按 Ctrl+C 退出，重点关注 "error" "failed" 关键词
    docker compose logs -f x-ui

[!常见错误]

- 常见错误：
    - `permission denied on /etc/x-ui`：`x-ui` 目录权限不足，重新执行 `sudo chmod -R 777 x-ui ssl_cert`；
    - `port is already allocated`：端口被占用（如 8051 被其他服务使用），修改 `ports` 中主机端口后重启；
    - `no such file or directory: /sys/fs/cgroup`：系统不支持 cgroup 挂载（少见，需确认 Linux 系统版本 ≥ 3.10）。

（2）访问 x-ui 管理面板

  1. 打开浏览器，输入 http://服务器IP:8051（如本地测试：http://localhost:8051，远程服务器：http://192.168.1.100:8051）；
  2. 首次登录使用 默认账号密码：
    • 用户名：admin
    • 密码：admin
  3. 登录后会强制跳转至 密码修改页面（安全要求），输入旧密码 admin，设置新密码（建议包含字母 + 数字 + 符号，如 Xui@2024!）；
  4. 完成密码修改后进入 x-ui 主界面（显示 “面板设置”“入站列表”“用户列表” 等菜单），说明面板部署成功。

（3）验证代理功能（创建测试节点）

  1. 点击左侧「入站列表」→「添加」，选择代理协议（如 VLESS，安全性高）；
  2. 填写关键配置（新手默认即可，重点修改端口）：
    • 端口：选择已开放的端口（如 8100，在 8100-8105 范围内）；
    • 加密方式：选择 none（VLESS 推荐无加密，通过 TLS 保障安全）；
    • TLS 配置：暂不启用（后续可添加证书后开启）；
    • 其他参数：默认即可；
  3. 点击「提交」，节点会显示在「入站列表」中，状态为「运行中」；
  4. 在本地设备（如电脑 / 手机）安装代理客户端（如 Clash、V2RayN），添加该节点（输入服务器 IP、端口、协议、ID 等信息）；
  5. 启用代理，访问测试网站（如 https://www.google.com），若能正常打开，说明代理功能正常。

🔌 基础配置与使用

面板基础配置

  1. 面板设置
  2. 面板监听 IP：默认留空即可
  3. 面板监听端口：确保端口不与其他服务冲突

  4. 面板根路径：可以随意设置，但不允许留空

  5. 用户设置

  6. 修改默认用户名和密码
  7. 定期更换密码增强安全性

代理协议配置

x-ui 支持多种代理协议：

  • VLESS：轻量级传输协议
  • VMess：功能丰富的代理协议
  • Trojan：模仿 HTTPS 流量的协议
  • Shadowsocks：经典的代理协议

SSL 证书配置

  1. 一键申请 SSL 证书
  2. 使用 acme 自动申请和管理 SSL 证书

  3. 确保证书路径正确配置

  4. 手动配置证书

  5. 将证书文件放置于 ./ssl_cert/ 目录
  6. 在面板中配置证书路径

🔌 基础配置与使用2

x-ui 核心功能是 “管理代理节点”，新手可从 “创建常用节点”“配置 SSL 证书”“查看流量统计” 入手，快速掌握使用方法：

1. 步骤 1：创建 VLESS 节点（推荐，安全性高）

VLESS 是主流代理协议，适合大多数场景，步骤如下：

  1. 左侧「入站列表」→「添加」→ 协议选择 VLESS；
  2. 配置关键参数：
    • 端口：选择未占用的开放端口（如 8101，需在 8100-8105 范围内）；
    • ID：自动生成（无需修改，客户端需填写此 ID 用于验证）；
    • 传输方式：选择 tcp（默认，稳定）；
    • TLS 配置：若已准备 SSL 证书，点击「启用 TLS」，「证书文件路径」选择 /root/cert/你的证书文件名.pem，「密钥文件路径」选择 /root/cert/你的密钥文件名.key；
  3. 点击「提交」，节点创建完成，状态显示「运行中」即可使用。

2. 步骤 2：配置 SSL 证书（启用 TLS 加密）

启用 TLS 可提升代理安全性，避免被网络检测，步骤如下：

  1. 获取 SSL 证书（两种方式）：
    • 方式 1：免费申请 Let's Encrypt 证书（通过 Acme.sh 工具，参考 Acme 官方文档）；
    • 方式 2：使用自签证书（仅用于测试，浏览器会提示不安全）；
  2. 将证书文件（如 fullchain.cer 证书、private.key 密钥）放入本地 ./ssl_cert 目录；
  3. 回到 x-ui 面板，编辑已创建的节点（如 VLESS 节点），启用「TLS」，选择证书与密钥路径（容器内路径为 /root/cert/xxx）；
  4. 点击「提交」，TLS 配置生效，客户端连接时需开启「TLS」选项。

3. 步骤 3：查看流量与日志

  1. 流量统计：点击左侧「流量统计」，可查看所有节点的日 / 周 / 月流量使用情况，支持设置单节点流量限制（如每月 100GB）；
  2. 运行日志：点击左侧「日志」，可查看 Xray 服务日志（如客户端连接记录、错误信息），便于排查代理连接问题。

🛠️ 维护与管理

日常维护操作

1.服务启停

   # 停止服务
   docker compose down

   # 启动服务
   docker compose up -d

2.数据备份

   # 备份配置文件
   tar -czf x-ui-backup-$(date +%Y%m%d).tar.gz ./x-ui

3.服务更新

   # 拉取最新镜像
   docker compose pull

   # 重启服务
   docker compose down
   docker compose up -d

监控与日志

1.查看实时日志

   docker compose logs -f

2.x-ui 系统日志 - 通过 x-ui 管理菜单查看详细日志 - 定期检查日志发现潜在问题

🐛 常见问题排查

1. 无法访问 Web 管理界面

问题现象：浏览器访问 http://IP:8051 无响应

解决方案： - 检查防火墙设置，确保端口已开放 - 验证容器状态：docker ps - 查看服务日志：docker compose logs

2. 登录后出现 404 错误

问题现象：登录后显示 "page not found 404"

解决方案： - 检查面板根路径配置 - 通过 x-ui 命令查看生成的根路径 - 使用正确的 URL 格式访问：http://IP:端口/根路径

3. SSL 证书申请失败

问题现象：无法申请 Let's Encrypt 证书

解决方案： - 确保域名解析正确 - 检查 Cloudflare API 配置 - 验证输入的二級域名格式正确

4. 配置文件错误

问题现象：重启后面板无法启动，提示配置文件错误

解决方案： - 检查配置文件语法：cat /etc/x-ui/config.json | jq . - 备份并恢复原始配置文件 - 如需要，重置配置文件

5. 客户端连接问题

问题现象：代理客户端无法连接

解决方案： - 检查端口映射配置 - 验证防火墙设置 - 确认代理协议配置正确

通过本教程，您应该已经成功部署并配置了 x-ui 服务。x-ui 的友好界面和丰富功能让代理服务管理变得更加简单高效。如果在使用过程中遇到其他问题，可以参考项目官方文档或社区支持资源。

🐛 常见问题排查2

1. 管理面板无法访问（ERR_CONNECTION_REFUSED）

  • 原因 1：8051 端口未开放或被占用。解决：

    1. 检查端口占用：sudo lsof -i :8051，若有占用，执行 sudo kill -9 进程ID 停止占用服务；
    2. 重新开放端口：sudo ufw allow 8051/tcp，云服务器需在安全组添加对应规则；
    3. 若端口冲突，修改 docker-compose.yml 中 8051:54321 为空闲端口（如 8080:54321），重启容器。
    4. 原因 2：容器未正常启动（State 为 Exited）。解决：查看日志 docker compose logs x-ui，修复权限或端口冲突问题后重启。

2. 代理节点连接失败（客户端提示 “无法连接”）

  • 原因 1：节点端口未开放或被占用。解决：确认节点使用的端口（如 8100）已开放，执行 sudo ufw allow 8100/tcp && sudo ufw allow 8100/udp，重启容器。

  • 原因 2：节点配置错误（如 ID 错误、TLS 未启用）。解决：

    1. 回到面板「入站列表」，编辑节点，核对「ID」是否与客户端配置一致（区分大小写）；
    2. 若启用了 TLS，确认证书文件路径正确（容器内路径为 /root/cert/xxx），客户端需同步开启「TLS」选项。
    3. 原因 3：服务器防火墙 / 安全组限制。解决：云服务器需在安全组中开放节点端口（如 8100-8105），本地服务器需关闭过度严格的防火墙规则。

3. 忘记 x-ui 登录密码（无法进入面板）

  • 原因：修改后忘记密码，无法登录管理界面。

  • 解决：通过容器命令行重置密码（默认重置为 admin）：

    bash

    ```bash

    1. 进入 x-ui 容器

    docker exec -it x-ui /bin/bash

    2. 执行密码重置命令（重置 admin 用户密码为 admin）

    x-ui reset-password

    3. 退出容器，重新登录面板（登录后需立即修改密码）

    exit ```

4. TLS 启用后连接失败（提示 “证书错误”）

  • 原因 1：证书文件路径错误或文件损坏。解决：

    1. 确认证书文件（如 fullchain.cer、private.key）已放入 ./ssl_cert 目录；
    2. 编辑节点时，核对「证书文件路径」为 /root/cert/fullchain.cer，「密钥文件路径」为 /root/cert/private.key（路径需完全匹配）；
    3. 若证书损坏，重新申请或生成证书后替换。
    4. 原因 2：客户端未启用 TLS 选项。解决：在代理客户端（如 Clash）中，找到对应节点，开启「TLS」选项，保存后重新连接。

通过以上步骤，新手可快速搭建 x-ui 代理管理面板，实现代理节点的可视化管理与安全访问。需注意：代理服务需遵守当地法律法规，禁止用于非法用途。如需探索更多功能（如多用户管理、自定义路由），可参考 x-ui 官方文档。