🚀 使用 Docker Compose 部署 3x ui（Xray 可视化代理管理面板）

🚀 使用 Docker Compose 部署 3X-UI

本文将详细介绍如何使用 Docker Compose 部署 3X-UI——一个功能强大的 Xray 可视化Web管理面板。通过容器化部署，可以简化安装流程，统一环境配置，并方便后续的迁移和维护。

📝 项目简介

3X-UI 是一款基于 Xray 内核的现代化代理管理面板，支持多种协议，并提供了友好的 Web 界面用于管理和配置代理服务。它最初源于 x-ui 项目，由伊朗开发者维护和魔改，后续出现了多个优化版本，例如本次部署将使用的 汉化优化版。

核心特点：

• 📊 友好的 Web 管理界面：通过网页可视化地管理代理账号、入站协议和流量，无需手动编辑繁琐的配置文件。
• 🛡️ 支持丰富的代理协议：支持 VMess、VLESS、Trojan、Shadowsocks、Dokodemo-door 等多种协议，并深度支持 XTLS（包括 REALITY）等高级特性。
• 👥 多用户管理：可以方便地创建和管理多个用户，并为他们分配不同的入站配置和流量限制。
• 📈 系统状态监控：在面板首页直观展示服务器状态、实时网络流量和总流量消耗等信息。
• 🔧 灵活的路由与出站规则：支持设置路由规则、屏蔽广告/特定网站、流量分流（链式代理）和负载均衡等高级功能。
• 🌍 多语言与主题：支持多语言（优化版提供了完善的中文支持）和深色/浅色主题切换。

🔧 部署前准备

系统环境要求

在开始部署前，请确保您的服务器满足以下最低要求：

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

citation:

环境检查

1. 检查 Docker 服务 确保 Docker 已安装并正在运行。 bash systemctl status docker 如果状态不是 active (running)，你需要先安装或启动 Docker。

2. 检查 Docker Compose 确认 Docker Compose 可用。 bash docker compose version

创建部署目录

建议创建一个独立的目录来存放所有部署文件，便于管理。

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

⚙️ 配置 Docker Compose

配置文件详解

在部署目录 (/home/compose/3x-ui) 下，创建名为 docker-compose.yml 的文件，内容如下：

#version: "3"

services:
  3x-ui:
    #image: ghcr.io/mhsanaei/3x-ui:latest
    # 镜像选择：xeefei 优化版（兼容更多场景，官方原版为 ghcr.io/mhsanaei/3x-ui:latest）
    image: 'ghcr.io/xeefei/3x-ui:latest'
    container_name: 3x-ui  # 容器名称，便于管理（如停止/查看日志）
    hostname: yourhostname  # 宿主机名（可自定义，如 3x-ui-server，不影响功能）
    volumes:
      # 核心挂载1：配置目录（本地 ./config → 容器 /etc/x-ui，存储所有节点/用户配置）
      - ./config/:/etc/x-ui/
      # 核心挂载2：证书目录（本地 ./cert → 容器 /root/cert，存储 SSL 证书）
      - ./cert/:/root/cert/
    environment:
      # XRAY_VMESS_AEAD_FORCED: "false"
      #X_UI_ENABLE_FAIL2BAN: "true"
      # 关键参数：关闭 VMESS AEAD 强制加密，兼容旧版客户端（如不兼容可改为 true）
      - XRAY_VMESS_AEAD_FORCED=false
      # 可选参数：启用 fail2ban（防暴力破解面板登录，需取消注释并配置）
      # - X_UI_ENABLE_FAIL2BAN: "true"
    tty: true   # 保持容器交互模式（Xray 运行必需，不可删除）
    #ports:
      #- "2053:2053"
    network_mode: host  # 关键！使用宿主机网络，代理节点直接使用宿主机 IP/端口
    #restart: unless-stopped
    restart: always  # 容器退出后自动重启（保障代理服务稳定，避免意外中断）

关键配置说明

1. 镜像选择 (image)：

   • 我们使用了 ghcr.io/xeefei/3x-ui:latest，这是一个由社区维护的 汉化优化版 镜像，对中文用户更友好。
   • 如果你希望使用原版，可以替换为 ghcr.io/mhsanaei/3x-ui:latest。

2. 网络模式 (network_mode: host)：

   • 使用 host 模式意味着容器直接共享宿主机的网络命名空间，无需在 ports 部分进行繁琐的端口映射。
   • 容器内应用监听的端口（如面板的 54321，代理服务的 443 等）将直接在宿主机上开放。
   • 优点：性能更好，配置简单。
   • 注意：需确保宿主机这些端口没有被其他进程占用。

3. 数据持久化 (volumes)：

   • ./config/:/etc/x-ui/：这是最关键的挂载。将容器内的配置目录映射到宿主机，确保面板设置、用户数据等在容器重建后不会丢失。
   • ./cert/:/root/cert/：用于存放自定义的SSL证书，方便为面板或代理服务配置HTTPS。

4. 环境变量 (environment)：

   • XRAY_VMESS_AEAD_FORCED=false：设置此环境变量可以关闭 VMESS AEAD 的强制验证，在某些特定客户端兼容性场景下可能需要。

5. 重启策略 (restart: always)：

   • 设置为 always 可以确保在 Docker 守护进程启动或容器意外退出时，容器会自动重新启动，提高服务可用性。

🚀 启动与验证

启动服务

在 docker-compose.yml 文件所在目录执行以下命令：

docker compose up -d

参数 -d 表示在后台运行容器。

验证服务状态

1. 检查容器运行状态 bash docker ps 你应该能看到名为 3x-ui 的容器状态为 Up。

2. 查看服务日志 bash docker compose logs -f 3x-ui 可以观察启动过程是否有异常错误。

3. 访问 Web 管理界面

   • 在浏览器中输入：http://你的服务器IP地址:54321。
   • 如果服务正常启动，你将看到 3X-UI 的登录页面。
   • 优化版默认界面为中文。如果是原版或其他版本，可在页面下方切换语言。

初始登录与安全设置

• 默认凭证：首次登录，请尝试使用常见的默认用户名和密码（如 admin/admin），具体请查阅你所使用镜像版本的文档。
• 立即修改：登录后，第一要务是前往"面板设置"修改默认的用户名和密码。
• 考虑开启面板SSL：为提高面板访问安全性，建议后续配置SSL证书，通过 https 访问面板。

🔌 基础配置与使用

添加首个代理入站

1. 登录面板后，在左侧菜单找到 "入站列表"，点击 "添加入站"。
2. 在弹出的表单中配置你的代理：
   • 备注：为这个节点起一个容易识别的名字。
   • 协议：选择你需要的协议，例如 VLESS 或 VMess。对于追求高性能和安全的新用户，推荐尝试 VLESS + Reality。
   • 端口：设置代理服务监听的端口，例如 443。
   • 传输协议和流控：根据选择的协议进行配置，例如 Reality 通常使用 tcp，流控可选择 xtls-rprx-vision。
3. 配置完成后点击 "添加"。

配置 REALITY 协议 (推荐)

REALITY 是一种新型协议，无需域名且能有效隐藏代理特征，非常推荐使用。 在"添加入站"时： - 协议 选择 vless。 - 端口 建议设置为 443。 - 传输 选择 tcp。 - 安全 选择 reality。 - 点击下方的 "Get New Cert" 按钮，系统会自动生成一对公钥和私钥。 - Dest 和 Proxy Protocol 等选项可以保持默认或根据推荐进行修改。

管理用户与客户端

• 在添加入站时或入站设置中，你可以为该入站添加多个用户（客户端）。
• 可以为不同用户设置不同的流量限制和过期时间。
• 在入站列表，点击节点操作栏的"..."，可以选择"导出链接"或"生成二维码"，方便分享给客户端使用。

🛠️ 维护与管理

日常维护

• 服务启停：

  # 停止服务
  docker compose down
  # 启动服务
  docker compose up -d
  # 重启服务
  docker compose restart

• 数据备份： 定期备份部署目录下的 config 和 cert 文件夹至关重要。

  tar -czf 3x-ui-backup-$(date +%Y%m%d).tar.gz ./config ./cert

• 服务更新： 若要更新到新版本的 3X-UI 镜像：

  # 进入部署目录
  cd /home/compose/3x-ui
  # 拉取最新镜像
  docker compose pull
  # 重启服务
  docker compose down
  docker compose up -d

数据迁移

如果需要将 3X-UI 迁移到新的服务器： 1. 将整个部署目录（包含 docker-compose.yml, config, cert）拷贝到新服务器。 2. 在新服务器上确保 Docker 环境就绪。 3. 执行 docker compose up -d 即可。

监控与日志

• 查看容器日志： bash docker compose logs -f 3x-ui

• 面板内监控：

• 面板首页展示了服务器的实时流量、总流量消耗和连接数等信息。
• 在"入站列表"可以查看每个节点的流量使用情况和在线用户。

🐛 常见问题排查

1. 无法通过浏览器访问管理面板 (http://IP:54321)

   • 检查防火墙：确保服务器的 54321 端口已放行。例如，使用 UFW 防火墙：ufw allow 54321。
   • 检查容器状态：运行 docker ps 确认容器是否正常运行。如果状态异常，使用 docker compose logs 查看详细错误日志。
   • 确认端口占用：检查宿主机 54321 端口是否被其他程序占用：netstat -tulpn | grep 54321。

2. 客户端无法连接代理节点

   • 检查防火墙：确保代理节点使用的端口（如 443, 2053 等）已在服务器防火墙和安全组中开放。
   • 检查面板设置：确认入站配置正确，特别是端口、协议和传输设置。
   • 域名与证书：如果使用了 TLS 并配置了域名，请确保域名已正确解析到服务器 IP，且证书有效。

3. 修改配置后不生效

   • 重启 Xray 服务：在 3X-UI 面板上，通常保存配置后会自动重启 Xray 服务。如果没有，可以尝试在面板上手动重启 Xray，或者直接重启整个 Docker 容器：docker compose restart。

4. 关于 Inbound ID 的注意事项

   • 在面板中，每个入站（Inbound）都有一个唯一的 ID。请避免直接修改这个 ID，因为这可能导致数据关联错误、流量统计失效或客户端配置出错。如果需要调整配置，建议通过编辑入站设置或重建入站来实现。

5. 面板提示证书错误或无法开启 HTTPS

   • 如果使用自签证书或从面板申请证书，请确保证书文件已正确放置在 ./cert/ 目录，并且在面板设置中填写的证书路径正确。

---

希望这篇教程能帮助你顺利完成 3X-UI 的部署和使用！如果遇到更复杂的问题，可以参考项目的官方文档或在相关的技术社区寻求帮助。