XHTTP 配置：为单台 Xray 迁移入口并保留回退

XHTTP 配置：为单台 Xray 迁移入口并保留回退

Marcus Reid
2026年10月11日· 7 分钟阅读

XHTTP 配置意味着建立新的传输路径，不只是给字段改名。应先添加独立入口，确认一个客户端能经它上传和下载，同时保留原入口供回退。本文限定双端 Ubuntu 24.04 LTS x64、Xray v26.3.27，使用直连 TLS、HTTP/2 和显式 stream-up。［1］［2］

关键要点

  • 试验入口独占程序、服务、配置、TCP 端口和 UUID。
  • 验收期间保留旧服务及客户端配置。
  • 双端匹配传输路径、模式、TLS 服务名和凭据。
  • 分别检查上传、下载、长请求、拒绝和回退。
  • 首次迁移不增加 CDN、反向代理、REALITY、H3 或上下行分流。

上述版本是文档适用版本，未完成完整端到端实测。以下检查描述方法和预期行为，不是测得的结果。先用自建任务与恢复清单划定验收范围。

Xray XHTTP 迁移应保留哪些旧配置？

保留原监听、服务身份、证书流程、防火墙规则和客户端配置。记录旧单元的程序路径、配置路径及端口归属。旧配置和客户端导出文件只存于管理员可读的备份，不公开 UUID、密钥、地址或目的地日志。

只操作自有或明确授权服务器，保留控制台恢复能力，并通过独立可信渠道核验 SSH 主机密钥。采用严格校验及专用 known_hosts；遇到不匹配、撤销或未验证密钥即停止。代理试验不能成为唯一管理通道。

需要运营 Xray、研究传输行为时，这条路线才有价值。若维护升级与证书无助于实际任务，修改可用入口前先比较 VPS 与 VPN 的责任。XHTTP 也不会取代协议、传输和混淆的分层。

固定试验身份

选空闲 TCP 端口，本文为 8443，并使用自有域名 xhttp.example.com。检查 sudo ss -lntup 和供应商防火墙。预留独立单元 xray-xhttp.service、本地入口 127.0.0.1:1081 和新 UUID；另保留一个客户端进程或应用观察旧路径。

条件允许时仅对预期客户端放行 TCP 8443。本路线无须 UDP 监听。保留 SSH 规则和既有证书验证端口；新 TLS 入口不意味着可以关闭防火墙或接管原 ACME 服务。

步骤 1：准备固定版本和受信任证书

从官方 v26.3.27 发行下载 Linux 64 位归档，核对说明与已发布的验证材料，在本地解包。以 root 将程序安装到 /opt/xray-xhttp/v26.3.27/xray，权限 0755；归档若提供配套数据文件，同样保留在该目录。在 Ubuntu 客户端重复安装。［1］

双端执行 /opt/xray-xhttp/v26.3.27/xray version，私密记录输出。不换成预发行版本，也不静默混用不同核心。运行 /opt/xray-xhttp/v26.3.27/xray uuid 生成新身份，保存到私密笔记和双端配置中。

创建无登录 shell 的系统账号 xray-xhttp，将 /etc/xray-xhttp 设置为 root:xray-xhttp、0750。通过现有授权 ACME 流程获取覆盖 xhttp.example.com 的公开受信任证书。把完整链和私钥副本放在此目录，归属 root:xray-xhttp、0640；仅授予这些副本的读取权，不开放无关证书库。

原续期流程须原子更新副本，验证后只重启试验服务。迁移日常客户端前先明确这个 hook。若服务器还没有证书流程，应先单独建立，不在此启动第二个争用 TCP 80、443 的 ACME 守护进程。

步骤 2：编写 XHTTP stream-up 配置

用 sudoedit 创建 /etc/xray-xhttp/server.json，将 REPLACE_NEW_UUID 换成新生成值。固定版本的 VLESS 入站使用 clients，出站使用 users；不要照搬新版文档的入站字段。［3］

{
  "log": {"loglevel": "warning"},
  "inbounds": [{
    "tag": "xhttp-trial",
    "listen": "0.0.0.0",
    "port": 8443,
    "protocol": "vless",
    "settings": {
      "clients": [{"id": "REPLACE_NEW_UUID"}],
      "decryption": "none"
    },
    "streamSettings": {
      "network": "xhttp",
      "security": "tls",
      "tlsSettings": {
        "alpn": ["h2"],
        "certificates": [{
          "certificateFile": "/etc/xray-xhttp/fullchain.pem",
          "keyFile": "/etc/xray-xhttp/privkey.pem"
        }]
      },
      "xhttpSettings": {
        "path": "/migration-stream/",
        "mode": "stream-up"
      }
    }
  }],
  "outbounds": [{"tag": "direct", "protocol": "freedom"}]
}

示例仅监听 IPv4。域名 A 记录指向正确服务器，不发布尚未配置的 IPv6 入口。VLESS 的 none 字段不提供传输加密，这里由 TLS 提供该边界；不配置 Vision flow。

客户端在权限 0700 的用户目录中保存权限 0600 的 client.json：

{
  "log": {"loglevel": "warning"},
  "inbounds": [{
    "listen": "127.0.0.1",
    "port": 1081,
    "protocol": "socks",
    "settings": {"auth": "noauth", "udp": false}
  }],
  "outbounds": [{
    "tag": "new-entry",
    "protocol": "vless",
    "settings": {
      "vnext": [{
        "address": "xhttp.example.com",
        "port": 8443,
        "users": [{"id": "REPLACE_NEW_UUID", "encryption": "none"}]
      }]
    },
    "streamSettings": {
      "network": "xhttp",
      "security": "tls",
      "tlsSettings": {
        "serverName": "xhttp.example.com",
        "alpn": ["h2"],
        "allowInsecure": false
      },
      "xhttpSettings": {
        "path": "/migration-stream/",
        "mode": "stream-up"
      }
    }
  }]
}

相同路径和显式模式限制了试验范围。stream-up 使用流式上传及独立下载路径，真正的 TLS 终点必须支持 H2。给 gRPC 字段换名不能建立这些行为。［2］［4］

步骤 3：检查双端文件并启动独立服务

将 server.json 设为 root:xray-xhttp、0640。服务端以服务账号检查，客户端以当前用户检查：

sudo -u xray-xhttp /opt/xray-xhttp/v26.3.27/xray run -test -config /etc/xray-xhttp/server.json
/opt/xray-xhttp/v26.3.27/xray run -test -config ./client.json

双端均须正常退出。这不能证明在线证书信任、远端认证或传输成功；真实配置中也不能留示例占位符。

以 root 创建 /etc/systemd/system/xray-xhttp.service：

[Unit]
Description=Independent Xray XHTTP trial
After=network-online.target
Wants=network-online.target

[Service]
User=xray-xhttp
Group=xray-xhttp
WorkingDirectory=/opt/xray-xhttp/v26.3.27
ExecStart=/opt/xray-xhttp/v26.3.27/xray run -config /etc/xray-xhttp/server.json
Restart=on-failure
RestartSec=5
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
UMask=0077

[Install]
WantedBy=multi-user.target

执行 sudo systemctl daemon-reload 和 sudo systemctl start xray-xhttp。确认该单元 PID 持有 TCP 8443，旧单元仍持有原监听。启动失败时查看受限 journal。试验阶段暂不要求开机自启。

用固定版本的完整程序路径执行 xray run -config ./client.json，保持前台。仅把试验应用设为 SOCKS5 127.0.0.1:1081，同时确认另一应用或客户端仍使用旧入口。排障时不要停止所有 Xray 进程。

如何验证 XHTTP 配置的双向迁移效果？

准备自己管理的 HTTPS 测试端点，提供已知下载内容、上传回执和刻意延长的响应。使用无敏感数据的文件，并限定时长和体积；未经许可，不向第三方诊断站点上传。

curl --fail --show-error --noproxy '' --proxy socks5h://127.0.0.1:1081 https://check.example.net/download -o ./download.bin
curl --fail --show-error --noproxy '' --proxy socks5h://127.0.0.1:1081 --data-binary @./trial.bin https://check.example.net/upload

替换为受控 URL，将下载内容、上传回执与已知文件核对。再经旧客户端真实的本地端口运行相同任务，记录完成情况、方向、持续时间和失败；首屏很快不能证明持续上传可用。

每次用客户端副本做负例时，先停止上一个前台试验客户端，再仅用修改后的副本启动同一回环端口，确认监听属于该进程。一次只改一个条件；进入下一项前恢复正确文件，并重做正例请求。

单项改动或检查预期行为停止或恢复措施
UUID、TLS 名称、路径和模式正确上传与下载均正确完成切换前先定位失败方向
复制客户端配置，只换成另一新 UUID新代理请求认证失败若成功，查绕过、进程身份及服务端用户列表
将 serverName 换成证书外的自有域名证书名称校验失败恢复正确名称，保留 allowInsecure: false
客户端路径改为 /different-trial/试验请求匹配失败恢复准确路径；仅改后缀仍可能匹配服务端前缀
只将客户端模式设为 packet-up显式 stream-up 服务端拒绝 packet-up 上传恢复模式；模式检查不能代替 UUID 认证
新入口运行长请求，另行观察旧入口新路径可用，旧服务保留监听及既有任务旧流量受影响就停止试验
只重启试验服务新路径的新请求恢复核对持久配置和证书权限

固定实现检查路径前缀，并区分 packet-up 与 stream-up 上传处理。某些其他模式组合可能被接受，因此不能宣称任意模式差异都必然拒绝。［5］采用上面的无共同前缀路径与 packet-up 负例，每项之后恢复正常配置。

在已配置的浏览器打开IP 地址工具，比较该请求与预期出口。这不验收全部 DNS、IPv6、UDP 或所有应用。旧 gRPC 路径仍有独立故障时，参考gRPC 超时排查，不要把新入口可用等同于旧故障已修复。核心职责另见Xray 与 V2Ray 的作用。

何时切换客户端，如何回退？

只有双向传输、持续请求、负例、证书续期处理和试验重启均满足验收条件，才修改一个客户端保存的应用设置。旧配置保持可用。现有连接不会自动迁移，可让它们结束，或有意重连；改设置后用新请求验证。

回退从客户端开始：恢复旧配置或本地 SOCKS 入口，验证新请求，然后停止前台试验客户端。服务端运行 sudo systemctl disable --now xray-xhttp，不改原单元。保存私密恢复证据后，仅删除试验防火墙规则、UUID、配置和不再需要的证书副本。确认该服务不再持有 TCP 8443，旧入口仍可用。

后续升级先准备另一个版本目录，改此单元前检查双端配置，并重复相同矩阵。短期保留兼容回退副本，但不永久冻结有漏洞的核心。一个客户端迁移成功，不能成为删除其他人仍在使用的旧入口的理由。

总结

安全迁移保留原工作路径，并增加可独立观察的试验入口。双端匹配、双向数据、明确拒绝和可执行恢复构成验收条件；示例不声称作者部署已经通过实测。

常见问题

能把 gRPC 设置直接重命名成 XHTTP 吗？

不能。应安装兼容核心，双端建立匹配的传输配置，并分别验证实际上传与下载行为，而非只改字段。

为什么 XHTTP 试验需要另一个端口和服务？

独立归属使你能停止试验而不重启原入口，也更容易识别监听、配置选择及回退对象的错误。

配置检查成功能证明 UUID 可用吗？

不能。语法检查不验证远端授权，应先用正确 UUID 访问受控目的地，再用另一个有效 UUID 检查拒绝。

所有 XHTTP 模式不匹配都应失败吗？

不是。是否接受取决于固定实现；本文使用 packet-up 客户端与显式 stream-up 服务端的特定组合检查拒绝。

下载成功一次就能完成迁移验收吗？

不能。还需检查上传、持续请求、负例、重启和恢复；一个客户端达到验收条件前应保留旧入口。

旧连接会随着设置切换到新入口吗？

已建立连接保持原路径。应有意修改客户端设置，并用新请求确认新入口，再考虑退役旧服务。

迁移后可以直接删除原服务端配置吗？

须先核对剩余用户和恢复要求。本文只迁移一个客户端，不授权删除其他客户端仍在使用的入口。

来源:

  1. Xray-core release v26.3.27 — https://github.com/XTLS/Xray-core/releases/tag/v26.3.27
  2. Project X: XHTTP mode discussion — https://github.com/XTLS/Xray-core/discussions/4113
  3. Pinned Xray VLESS configuration implementation — https://github.com/XTLS/Xray-core/blob/v26.3.27/infra/conf/vless.go
  4. Project X: transport configuration — https://xtls.github.io/en/config/transport.html
  5. Pinned Xray XHTTP server implementation — https://github.com/XTLS/Xray-core/blob/v26.3.27/transport/internet/splithttp/hub.go

Sources checked 2026 年 10 月 11 日。

延伸阅读：

开启 3 天免费试用

注册即可免费体验全部高级功能。

*仅限新用户；每位用户只能获得一次试用。

免费试用

相关文章

XHTTP 配置：为单台 Xray 迁移入口并保留回退 | AethoVPN