3x-ui 这个名字玩 Linux 服务器的人应该不陌生。最近我又重新部署了一台机器翻了一圈开源管理面板最后还是装回了 3x-ui。很多朋友第一次听说它都是奔着“安装 3x-ui”这个关键词来的想找一篇能照着一步步做完的文章。这篇就把我从环境准备、脚本安装、面板安全设置到后续用户管理和常见故障排查的完整过程整理出来给你一份可以直接抄作业的实战笔记。3x-ui 本质上是一个基于 Xray 内核的 Web 管理面板用浏览器就能操作不需要天天 SSH 上去改配置、敲命令。它的核心价值在于把 Linux 服务器上那些杂乱的流量入口、用户账号、流量数据全部集中到一个界面里管理。适合谁用如果你手里有一台云服务器需要管理多个访问入口、给不同使用者分配额度、查看每天的数据进出情况那这个面板会非常顺手。哪怕你只是刚入门 Linux只要能跟着步骤操作也能在半小时内把它跑起来。1. 3x-ui 的核心设计思路它到底解决了什么痛点1.1 从命令行到面板化省的不只是操作时间在没有这类面板之前管理服务器上的流量入口是一件很拧巴的事。每加一个入口都要去编辑配置文件、重启服务、检查日志命令一长串稍不留神写错一个缩进或逗号服务直接起不来还得回头一行一行排查。要是同时管着多个入口、多台服务器那基本就是靠脑子硬记出了问题上手很慢。3x-ui 把这一切搬到了浏览器里。添加入口、改参数、重启内核都是点几下按钮的事配置统一写到数据库里不用再去跟裸配置文件搏斗。我当时看中它的另一个原因是用户隔离同一台服务器上可以分给不同的人独立的使用时长和流量额度互不干扰这在多人共用一个服务器入口的场景下非常实用。1.2 模块化结构面板、内核、数据库各司其职3x-ui 的进程架构其实很清晰。一个 Web 面板进程负责处理浏览器请求、读写数据库另一个独立的内核主进程负责实际的数据转发和流量统计。两者分开有个好处面板挂了不影响流量转发内核出问题也不会让 Web 界面完全失控排查故障时能快速定位到具体环节。它采用 SQLite 数据库存储配置包括入站、用户、设置、流量日志等全部打包在一个数据库文件里。这意味着备份极其简单——直接拷贝那个文件就行。没有复杂的数据库依赖对一台轻量服务器来说非常友好装完几乎不占额外资源。1.3 什么场景下不建议硬上 3x-ui3x-ui 适合大多数个人和中小规模使用场景但也不是银弹。如果你要管理的是企业级、上百个入口的复杂网络服务可能需要更完整的权限体系和审计功能面板方案并不合适。另外CentOS 7 这类老系统虽然能装但内核版本旧后续有机率出现兼容问题能用较新的 Debian 系或 Ubuntu 系就尽量用新的。我自己的经验是别为了迁就旧服务器而牺牲稳定性和更新便利性该换系统就换。2. 部署前的准备工作这些细节直接决定安装成败2.1 系统要求与硬件基线先说系统。3x-ui 官方脚本主要支持 Debian、Ubuntu、CentOS 系系统个人建议优先选择 Debian 11 或 Ubuntu 20.04。这类系统的 systemd 管理完善脚本跑起来基本不会有幺蛾子。硬件门槛其实很低内存 512MB 以上就能跑磁盘剩余空间建议预留 5GB 以上毕竟除了面板本身系统、日志、数据库都要占空间。我之前在一台只有 1G 内存的机器上装过运行起来很流畅说明资源占用确实控制得不错。但如果你打算同时跑多个高流量入口内存还是给到 1GB 以上更稳妥毕竟流量转发本身也需要一定的缓冲区。2.2 端口规划与防火墙检查提前做能省很多事安装前最重要的一件事就是想好面板要用哪个端口。3x-ui 默认面板端口是 54321这个端口在安装完成后会直接打印出来。问题在于默认端口在网上非常容易被扫描器盯上被别人拿字典爆破管理密码的案例我见过不少。所以强烈建议安装后第一时间改掉默认端口选一个不常用的高位端口比如 10000 以上的某个端口。除了面板端口你计划开放的流量入口端口也最好提前规划好。比如打算开 443 端口跑 HTTPS 相关的流量入口要提前确认这个端口没有被其他服务占用。检查命令很简单ss -tlnp | grep -E 443|54321没有输出说明端口是空闲的可以继续安装。如果有输出说明端口被占用了先处理占用服务或者换端口别等装完才发现冲突。2.3 时间同步和 SSH 会话准备这一步很容易被忽略但影响很大。服务器时间不准会引发两类问题一是证书签发时校验不通过二是流量统计的日期记录错乱。装完系统后建议先确认时间date如果时间偏差大用 chrony 或 ntpdate 同步一下。另外整个安装过程建议用 SSH 连接到服务器操作不要在网页终端里来回切避免中断。如果你是 Windows 用户用系统自带的终端或 PowerShell 连都行只要能正常执行远程命令即可。3. 安装 3x-ui 全流程从脚本到容器我各跑了一遍3.1 官方脚本一键安装新手最稳的路径官方提供了一键安装脚本这也是绝大多数人装 3x-ui 的方式。命令如下bash (curl -Ls https://raw.githubusercontent.com/MHSanaei/3x-ui/main/install.sh)执行之后脚本会自动检测系统、下载依赖和内核文件、创建服务、生成默认配置。整个安装过程可能持续一两分钟视服务器到 GitHub 的连通性而定。安装完成后终端会输出类似这样的信息面板访问地址、端口、默认用户名和密码默认一定是 admin / admin。请把这几行字截图或记下来不要直接关掉终端后面登录要用。验证安装是否成功用这个命令systemctl status x-ui看到active (running)就说明服务在跑。再用 curl 试探面板端口curl -I http://你的服务器IP:54321返回 HTTP 状态码就代表面板页面已经可以访问了。这里要注意如果你的服务器有防火墙记得放行面板端口不然外部浏览器根本连不上# Debian/Ubuntu 用 ufw 的话 ufw allow 54321/tcp3.2 Docker 方式安装适合喜欢容器化的用户不喜欢在宿主机上跑服务的可以用 Docker 安装 3x-ui。官方提供了镜像一条命令拉起来docker run -itd \ -e XRAY_PANEL_PORT54321 \ -v $PWD/db/:/x-ui/db/ \ -v $PWD/cert/:/x-ui/cert/ \ --network host \ --restartalways \ ghcr.io/mhsanaei/3x-ui:latest注意我用的是--network host也就是宿主机网络模式。这个模式的好处是端口管理跟宿主机完全一致不用再额外做端口映射新开一个端口就能直接用省了很多容器网络转发的麻烦。坏处是容器的隔离性弱一些但作为管理面板来说这种取舍是合理的。Docker 方式的备份也更简单把整个项目目录打包带走就行。我个人在自己的主力机器上用 Docker 方式跑原因就是迁移方便换服务器时直接把目录搬过去再执行一次docker compose up -d就能恢复。3.3 升级与卸载两个命令搞定3x-ui 更新频率不低升级可以直接在面板后台点击升级按钮也可以走命令行x-ui upgrade卸载更简单脚本自带卸载入口x-ui uninstall执行后会提示确认输入 y 回车即可。卸载会移除服务、面板文件和数据目录所以卸载前务必确认数据库已经备份。我见过不少人误触卸载后数据全部丢失那叫一个痛。4. 首次登录与安全加固这几步一分钟都不能省4.1 第一次登录先改默认密码打开浏览器访问http://服务器IP:端口输入默认账号 admin 和密码 admin就能进入面板。登录进去之后第一件事绝对不是去看各种花里胡哨的功能而是到面板设置里改掉默认密码。默认的 admin/admin 相当于你把家门钥匙挂在门口网上扫到这种面板的脚本会直接尝试登录一分钟能试几百次不改密码就是在裸奔。改密码的同时把登录用户名也改掉不要继续用 admin。很多暴力破解工具就是死磕 admin 这个用户名换一个自定义用户名能过滤掉大部分扫描流量。4.2 改面板端口和访问路径降低被扫描的概率密码改完后立刻去改面板监听端口。我通常的做法是关闭原端口默认 54321开启一个新端口比如 25000 左右的随机端口记住新端口同时更新防火墙放行规则面板设置里还有“访问路径”这一项默认是/也就是根路径。建议改成一个只有自己知道的复杂路径访问地址就变成了http://IP:端口/自定义路径。这样即使端口被猜到访问器也会优先撞上无效路径进一步减少被爆破的可能性。注意改完之后浏览器要用新地址访问收藏夹里的老地址就废了。4.3 面板级 SSL 证书能上就上面板页面本身走的是 HTTP不加密。如果你的面板暴露在公网登录密码、流量数据都是明文传输这在网络环境复杂的情况下是很大的风险。解决办法是给面板套一层 HTTPS。3x-ui 的面板设置里提供了证书管理功能支持从文件导入证书也支持 ACME 自动签发。我用得比较多的是 ACME 方式填上自己的域名设置邮箱点击申请它自动去验证域名所有权并签发证书快的话几十秒就完成。配置完成后用https://域名:端口/路径访问面板地址栏出现小锁图标说明面板已经走加密通道了。这里要特别提醒如果你没有域名或者域名没有解析到这台服务器ACME 方式申请会失败。这是在申请前就要确认好的前提条件别等报错了再去找原因。4.4 给面板再加一层保险源 IP 白名单如果你日常使用面板的 IP 地址是固定的比如公司出口 IP 或家庭宽带公网 IP可以在防火墙层面把面板端口限制为仅允许这几个 IP 访问。这是我认为最有效的一招比改密码改端口都硬——别人连包都送不到面板端口。以 ufw 为例ufw allow from 203.0.113.10 to any port 25000 proto tcp然后再拒绝其他来源访问该端口ufw deny 25000/tcp执行完一定要先确认本地 IP 能访问面板再退出 SSH 会话否则把自己锁在外面就尴尬了。我之前在机房调试时干过这种事修改防火墙规则后忘了放行当前 SSH 来源结果远程直接断了最后只能从另一条物理通道进去救场。5. 用户与流量入口管理把权限细节抠到位5.1 添加入口实例核心操作在面板左侧菜单点击“入站列表”这里管理的就是所有对外开放的流量入口。点击“添加入站”按钮会进到一个配置表单。需要关注几个关键字段协议类型下拉框里有多项可选具体选哪种取决于你的使用场景监听端口不要跟已有端口冲突传输方式常见的有 TCP 和基于 WebSocket 的模式选哪种要看你的网络环境客户端连接数上限合理设置一个值防止被滥用我一般这样规划一个入口实例绑定一个独立端口这样某个入口出问题时其它入口不受影响。比如我开 443 端口给 HTTPS 相关的入口再开一个 8443 端口做备用入口两个入口互不干扰排查问题时也很清晰。5.2 添加用户与配额设置有效期、流量、限制一把梭3x-ui 的亮点在于用户维度的精细化控制。每个入口下面可以添加多个用户每个用户单独设置有效期和流量配额。操作路径入口列表里点“查看”或“编辑”进入用户管理页再添加用户。需要填写的核心参数用户备注给自己看的写清楚使用者身份比如“办公网”“宿舍网”有效期设置一个截止日期到期后该用户自动失效不用手动操作流量上限按 GB 为单位设置超过之后该用户立刻不可用限额策略可以选择流量用完后直接禁止或者仅记录不限制这里建议配额给充足一点但也不要无限量。实测下来合理设置阈值的用户基本不需要频繁干预反倒是那些无限配额的用户往往几天后流量就爆了还得半夜爬起来查看是谁在拖着跑。5.3 在线用户与流量统计别放过异常数据面板首页提供实时流量图表和在线用户列表。你可以看到每个用户当前是否在线、最近消耗了多少流量。我习惯每周看一次数据重点观察两种情况一是某个用户的流量消耗曲线突然陡增大概率是账号信息泄露或使用场景发生了变化二是某个入口的总流量异常偏高检查一下是不是被大量异常连接冲刷。如果需要重置某个月或某个用户的历史流量数据入口或用户编辑页里都有“重置流量”按钮。注意这个操作不可逆点之前想清楚最好先截个图留存。6. 配置分发、备份恢复与自动化辅助6.1 配置分发功能批量导入的利器当入口和用户都建好之后给使用者发配置是个麻烦事。手工复制一个个参数拼接链接容易出错。3x-ui 的“订阅”功能就是解决这个问题的系统提供一个统一的配置链接使用者把这个链接放进客户端就能自动拉取服务器上所有分配给自己的入口配置。使用路径是入站列表 - 选中某用户 - 生成订阅链接。拿到链接后我一般会把它发到使用者的聊天工具里对方导入后就能一键连接不用手把手教配置参数。订阅链接包含了使用者的身份信息泄露就等于泄露了使用权所以务必提醒使用者不要把链接公开贴到论坛或群里。6.2 面板的通知功能实时掌握状态3x-ui 支持接入 Telegram 机器人推送登录通知、流量报告、服务异常告警。配置方式面板设置 - 通知设置填入机器人的 Token 和接收消息的账号 ID保存后可以发一条测试消息验证。机器人通知最大的价值不是看流量数字而是及时发现异常登录。我配置完之后有一次凌晨三点收到一条陌生 IP 登录面板失败的告警立刻去检查了安全策略确认没有被突破后才放心。这种安全感是刷面板页面刷不出来的。6.3 备份与恢复数据无价备份是很多人最容易忽略的环节等数据丢了才后悔。3x-ui 的所有配置数据都在一个 SQLite 数据库文件里备份思路很简单把数据库文件复制走。面板后台提供了在线备份功能点击“备份”就能生成一个备份文件并下载到本地。也可以直接定时复制数据库文件cp /etc/x-ui/x-ui.db /path/to/backup/x-ui-$(date %F).db恢复时把备份的数据库文件放回原路径重启面板服务即可systemctl restart x-ui这里有个坑如果备份时面板正在写入数据数据库文件可能处于不一致状态。稳妥的做法是先停止面板服务再复制文件或者用 SQLite 自身的备份命令sqlite3 /etc/x-ui/x-ui.db .backup /path/to/backup/x-ui.db我用这个命令做过多次定时备份没有再出现过文件损坏的问题。7. 我踩过的那些坑常见问题与排查实录7.1 装完面板打不开先排查端口和进程最常见的故障就是“面板装好了浏览器却打不开”。按顺序排查三步systemctl status x-ui # 1. 服务是否存活 ss -tlnp | grep 54321 # 2. 端口是否在监听 curl -I http://127.0.0.1:54321 # 3. 本机是否返回 HTTP 响应本机能通、外网不通基本就是防火墙拦截检查云服务商的安全组和服务器本机的防火墙规则。服务没起来看日志journalctl -u x-ui -e日志里通常会有具体的错误原因比如端口被占用、数据库文件权限不对、配置文件语法错误等。照着日志提示改比瞎重启有用得多。7.2 忘了面板密码重置手法面板密码忘了这种事我干过不止一次。重置密码不需要重装系统执行x-ui reset按提示选择重置管理账号密码脚本会输出新的默认账号密码。重置完成后立刻登录并修改新密码别再用默认密码顶着运行。7.3 端口冲突与内核进程异常新增的入口接不上第一反应查端口ss -tlnp | grep 端口号如果端口已经被其它进程占用要么停掉旧服务要么换个新端口。还有一种情况面板上显示内核进程运行正常但实际流量不通这时要尝试重启内核进程。面板上有对应的重启按钮命令行也有systemctl restart x-ui如果重启后仍然异常去查看内核日志重点看报错堆栈里的关键字对照错误信息去搜索解决方案基本都能解决。7.4 SSL 证书续签失败ACME 证书是有有效期的3x-ui 会自动续期但不是每次都成功。续签失败的常见原因域名解析指向发生了变动、DMCA 等导致申请接口临时不可用、服务器时间出现偏差。排查时先确认 DNS 解析正确dig 你的域名 short再确认服务器时间同步正常最后手动触发一次续签请求观察报错信息。如果提示域名验证失败检查域名有没有正确解析到当前服务器 IP这个错误最常见也最容易漏掉。最后再分享一个小技巧用 3x-ui 这么长时间踩过的坑不少最深刻的一条经验是每次改完关键配置改端口、改密码、添加入口都要立刻验证一次服务状态再离开电脑。很多时候问题不是出在配置本身而是改完没重启、没放行端口白白折腾半天。还有一个习惯也推荐养成把面板地址、端口、账号密码、恢复命令记录在一个本地加密笔记里。别指望自己能记住那些毫无规律的端口号和路径真出问题时翻笔记比回忆高效太多。3x-ui 本身不复杂但运维工具再顺手也扛不住人的随手操作养成好习惯才能长期稳定省心。