--- title: "3x-ui 安装与首次连接" source: https://www.iowill.com/blog/2026/10/3x-ui-installation-first-connection/ date: 2026-10-18 updated: 2026-10-18 tags: [3x-ui, Linux, REALITY, Xray] categories: [系统与运维] --- # 3x-ui 安装与首次连接 安装 3x-ui，能打开后台只是第一步。还需要创建入站、导入客户端，并让一次真实请求经过节点，才能确认从客户端到目标网站的路径可用。 这里按这个顺序完成首次配置。如果面板已经能登录，而节点持续超时、握手失败或连上后无法访问，可以直接阅读[3x-ui 面板正常但节点不可用的排查方法](https://www.iowill.com/blog/2026/10/3x-ui-panel-works-node-unusable/)。 ## 安装环境与端口 本文以 Debian 12、systemd 和官方脚本安装为例，命令使用 Bash。安装示例固定为 3x-ui `v3.10.2`；2026 年 10 月 18 日核对时，该发布页列出的 Xray-core 为 `v26.10.10`，实际运行版本仍需在自己的面板中确认。[版本记录](https://github.com/MHSanaei/3x-ui/releases/tag/v3.10.2) 3x-ui 管理账号、入站和配置，Xray 处理代理流量。面板端口和节点端口分别检查： | 用途 | 本文示例 | 应如何验证 | | --- | --- | --- | | 管理面板 | 2053 | 使用实际协议、端口和路径登录 | | VLESS/REALITY 节点 | 443 | 确认 Xray 监听，再从客户端发起请求 | | 客户端本地 SOCKS 代理 | 10808 | 以客户端实际设置为准，用代理请求验证 | 公网 IP `203.0.113.10` 属于文档保留地址，不能用于实际连接。请将 IP、域名、端口和访问路径替换为自己的配置；`127.0.0.1` 表示执行命令那台机器的回环地址。 ![3x-ui 管理面板访问与节点代理请求的独立路径](https://img.iowill.com/file/系统与运维/3x-ui安装与首次连接/body1.png) 面板端口、节点端口和本地代理入口分别检查，示例端口需替换为实际值。 ## 在 Debian 上安装 3x-ui 先确认系统和架构： ```bash cat /etc/os-release uname -m ``` 安装下载所需的工具： ```bash sudo apt update sudo apt install -y curl ca-certificates ``` 已有业务的服务器，系统升级另行安排。这里先完成必要工具的准备。 官方支持直接运行安装脚本，也支持指定发布版本。下面先把对应标签的脚本下载到本地，确认下载成功后再执行：[官方安装说明](https://github.com/MHSanaei/3x-ui/blob/v3.10.2/docs/content/docs/en/guide/installation.mdx) ```bash curl -fL --retry 3 --connect-timeout 15 \ -o 3x-ui-install.sh \ https://raw.githubusercontent.com/MHSanaei/3x-ui/v3.10.2/install.sh ``` 检查文件，阅读脚本后运行： ```bash less 3x-ui-install.sh sudo bash 3x-ui-install.sh v3.10.2 ``` 如果下载阶段已经报错，先保留错误信息，暂时不要继续执行本地文件。`curl` 的退出码能帮助区分失败阶段： | 退出码 | 先检查什么 | | --- | --- | | 6 | 下载域名能否解析 | | 7 | 是否能连接目标地址及端口 | | 28 | 哪个阶段超时，网络是否可达 | | 35 | TLS 握手错误详情 | | 60 | 证书信任、系统时间与 CA 配置 | 这些代码说明的是失败阶段，具体原因还要结合错误文字。安装脚本与发布压缩包来自不同 URL，脚本下载成功后，也可能在下载发布文件时失败。[curl 退出码](https://curl.se/docs/manpage.html#exit-codes) 安装完成后，保存实际的用户名、密码、面板端口、访问协议和 Web Base Path。脚本安装会生成随机值，访问地址可能形如： ```text https://203.0.113.10:2053/实际生成的路径/ ``` 端口后的路径也是地址的一部分。只输入 IP 和端口，可能得到 404。HTTP 还是 HTTPS，以安装结果及当前证书设置为准。 遗失这些信息时，可以在服务器运行 `sudo x-ui`，使用查看当前设置的入口核对。设置输出可能含敏感信息，截图或分享前先脱敏。[首次登录说明](https://github.com/MHSanaei/3x-ui/blob/v3.10.2/docs/content/docs/en/guide/first-login.mdx) 首次登录后设置独立密码，配置 HTTPS，并按需要限制管理入口。面板的访问控制与节点对外提供服务所需的端口，应分别处理。 ## 创建一个用于验证的入站 在面板的入站列表新增一个入站，选择 VLESS、TCP 和 REALITY，并添加一个客户端。先把这一组配置验证清楚，再扩展其他协议。保存前逐项核对： | 项目 | 要确认的内容 | | --- | --- | | 入站端口 | 选一个未被占用、准备对外开放的端口 | | 传输方式 | 客户端与服务端一致，界面可能显示 TCP 或 RAW 等版本相关名称 | | 安全模式 | 两端都使用 REALITY | | 客户端 UUID | 使用面板中实际启用的客户端记录 | | Flow | 使用 XTLS-Vision 时，两端对应为 `xtls-rprx-vision` | | 目标与 SNI | 按官方要求选择可达的 TLS 目标，SNI 与目标证书匹配 | | 密钥与 Short ID | 在面板生成，客户端使用对应公钥和 Short ID | REALITY 私钥留在服务端，客户端使用公钥。保存入站后，确认入站和客户端均已启用，并在面板查看 Xray 是否成功应用配置。客户端支持的字段和指纹，需要与其版本对应。[REALITY 配置说明](https://github.com/MHSanaei/3x-ui/blob/v3.10.2/docs/content/docs/en/config/reality.mdx) 这里使用 `443` 作为后续节点端口示例。如果 Nginx 或其他服务已经占用它，需要调整端口或设计共存方式；不能把两个独立监听器直接放到同一个地址和端口上。 ## 确认节点监听和端口放行 在服务器检查示例节点端口： ```bash sudo ss -lntp 'sport = :443' ``` 确认监听进程属于预期的 Xray，且监听地址适合客户端的访问方式。没有输出、只监听回环地址或端口被其他程序占用时，先处理入站配置或冲突。 主机防火墙和云平台安全组也要允许这个节点的实际端口及协议。面板端口已放行，不代表节点端口也放行；需要修改规则时，先确认机器使用哪种规则管理工具。具体检查见[节点排错篇](https://www.iowill.com/blog/2026/10/3x-ui-panel-works-node-unusable/)。 从客户端所在的 Windows 电脑用 PowerShell 探测： ```powershell Test-NetConnection -ComputerName 203.0.113.10 -Port 443 ``` `TcpTestSucceeded: True` 说明这次 TCP 建连成功，继续导入配置并验证真实请求。它还不能证明 VLESS 或 REALITY 握手成功。 ## 导入客户端并验证真实请求 在面板获取这个入站下对应客户端的分享链接或订阅，导入支持相应协议和握手能力的客户端。检查导入后的地址、端口、UUID、传输、安全模式、公钥、Short ID、SNI 和 flow，与面板当前配置一致。 启动客户端核心，选中刚导入的节点。先查看本地 SOCKS 端口，再确认测试目标会经过这个节点。假设 SOCKS 入口为 `127.0.0.1:10808`，在客户端所在电脑执行： ```bash curl --noproxy "" --proxy socks5h://127.0.0.1:10808 --connect-timeout 5 --max-time 20 -sS -o proxy-probe.html -w "HTTP %{http_code}\n" https://example.com/ ``` Windows 使用 `curl.exe`。如果本地只有 HTTP 代理端口，应先核对客户端提供的入口，不能把 HTTP 端口直接当作 SOCKS 端口。 命令将响应保存到当前目录的 `proxy-probe.html`。`socks5h` 将目标域名交给代理处理；客户端内部仍可能按规则选择直连，所以还要查看客户端日志，确认请求确实经过选中的节点。[curl 代理选项](https://curl.se/docs/manpage.html#--socks5-hostname) 检查 HTTP 状态和保存的内容，区分正常目标页面、目标站错误和中间组件返回的错误。随后让浏览器使用客户端的系统代理或 TUN 等接管方式，访问相同目标，并检查页面资源是否正常加载。 ![服务器监听、客户端 TCP 建连和真实代理请求的三层验证](https://img.iowill.com/file/系统与运维/3x-ui安装与首次连接/body2.png) 监听正常、TCP 可达和真实请求可用是不同层次的验证。 首次连接可以这样确认： - 入站启用，Xray 成功应用配置，节点端口由预期进程监听。 - 客户端的真实请求经过选定节点，并拿到预期内容。 - 浏览器接管后可访问目标，客户端和服务端没有对应的握手或出站错误。 如果代理命令可用但浏览器失败，继续检查浏览器、系统代理和接管规则；如果命令本身失败，按照[节点排错篇](https://www.iowill.com/blog/2026/10/3x-ui-panel-works-node-unusable/)区分本地入口、握手、DNS 和出站问题。 ## 面板访问和证书的简要检查 面板打不开时，先核对安装输出中的协议、端口及 Web Base Path，再检查面板服务和监听。反代返回 502 时检查上游地址、端口及 HTTP/HTTPS；404 则核对路径与实际响应服务。[官方排错](https://docs.sanaei.dev/docs/help/troubleshooting/) 启用 Cloudflare 代理后，面板端口必须符合其支持范围；随机生成的端口不一定可用。[代理端口说明](https://developers.cloudflare.com/fundamentals/reference/network-ports/) 面板 HTTPS 证书与 REALITY 入站分开配置。REALITY 不要求为该入站自行申请普通 TLS 证书，管理面板仍应使用合适的 HTTPS。申请证书时先分清 HTTP-01、DNS-01 或 TLS-ALPN-01，再检查相应端口、DNS 记录和验证服务；签发后也要安排续期。[验证方式](https://letsencrypt.org/docs/challenge-types/) 首次验证通过后，保存系统、面板、服务端核心及客户端核心版本，导出配置并备份数据库和实际使用的证书。分享日志或截图前去除账号密码、订阅链接、UUID、私钥及真实服务器地址。[备份说明](https://docs.sanaei.dev/docs/operations/backup-restore/) ## 参考资料 - [3x-ui v3.10.2 发布说明](https://github.com/MHSanaei/3x-ui/releases/tag/v3.10.2) - [官方安装说明](https://github.com/MHSanaei/3x-ui/blob/v3.10.2/docs/content/docs/en/guide/installation.mdx)与[首次登录](https://github.com/MHSanaei/3x-ui/blob/v3.10.2/docs/content/docs/en/guide/first-login.mdx) - [REALITY 配置说明](https://github.com/MHSanaei/3x-ui/blob/v3.10.2/docs/content/docs/en/config/reality.mdx) - [科技小露的基础安装文章](https://www.kejixiaolu.com/djvps/dj09.html)