快速上手

简介

本文指导完成 Xray-core 的编译、基本配置和运行验证，以及 REALITY 配置的快速搭建。

本文回答

• 如何编译 Xray-core
• 如何编写最小配置文件
• 如何生成 REALITY 所需的密钥
• 如何验证服务正常运行

本文在项目中的位置

本文处于文档集的"上手层"，应在理解项目基本概念后阅读。建议先阅读 index.md。

适合读者

所有需要实际操作 Xray-core 的读者。

前置知识

Go 语言编译流程，基本的命令行操作，JSON/YAML 配置文件格式。

文章理解难度

入门。

重点

• 编译命令的参数含义
• REALITY 密钥对和 ShortId 的生成
• 最小化配置的结构

难点

• REALITY 的服务端/客户端密钥配对
• 回落（fallback）配置的概念

上级文档和相关文档

• index.md：项目概述
• protocols/reality.md：REALITY 协议详解
• reference/config.md：完整配置参考

---

环境要求

• Go 1.21 或更高版本
• Git
• 操作系统：Linux / macOS / Windows（支持交叉编译）

编译

基础编译

设置 CGO_ENABLED=0 可生成纯静态二进制文件（无 C 依赖）：

Linux / macOS：

CGO_ENABLED=0 go build -o xray -trimpath -buildvcs=false -ldflags="-s -w -buildid=" -v ./main

Windows (PowerShell)：

$env:CGO_ENABLED=0
go build -o xray.exe -trimpath -buildvcs=false -ldflags="-s -w -buildid=" -v ./main

编译参数说明：

参数	说明
CGO_ENABLED=0	禁用 CGO，生成纯 Go 静态二进制
-trimpath	去除编译路径信息，增强可复现性
-buildvcs=false	不在二进制中嵌入 VCS 信息
-ldflags="-s -w"	-s 去除符号表，-w 去除 DWARF 调试信息（减小体积）
-buildid=	清空 Build ID

可复现编译

如果需要生成与官方发布版本一致的二进制文件：

CGO_ENABLED=0 go build -o xray -trimpath -buildvcs=false -gcflags="all=-l=4" \
  -ldflags="-X github.com/xtls/xray-core/core.build=REPLACE -s -w -buildid=" -v ./main

其中 REPLACE 替换为 7 位 git commit hash。

生成密钥

REALITY 配置需要以下密钥材料：

1. 生成 UUID（VLESS 用户 ID）

./xray uuid
# 输出示例：9be4c7bb-7d3b-4e1d-8f71-46f55d4092e0

2. 生成 X25519 密钥对（REALITY 密钥）

./xray x25519
# 输出示例：
# Private key: MBpO2ao_iQZLQ6NWs9DythpoKkkt0pUPVLXJyUPKF1w
# Public key:  ZFzvQyu6FYGN7iE_lOBg4n_aoHOiCmZ2QNYLgy9DBzA

• Private key（私钥）：配置在服务端的 privateKey 字段
• Public key（公钥）：配置在客户端的 publicKey（在客户端配置中称为 password，即"密码"）

3. 生成 ShortId（可选）

openssl rand -hex 8
# 输出示例：0123456789abcdef

ShortId 长度必须是 2 的倍数，最大 16 字节。用于区分不同的客户端。

4. 生成 ML-DSA-65 种子（可选，后量子安全）

./xray mldsa65

对证书进行后量子安全的额外签名。

最小服务端配置

以下是一个完整的 REALITY 服务端最小配置（JSON 格式），保存为 config.json：

{
  "log": {
    "loglevel": "warning"
  },
  "inbounds": [
    {
      "listen": "0.0.0.0",
      "port": 443,
      "protocol": "vless",
      "settings": {
        "clients": [
          {
            "id": "你的UUID",
            "flow": "xtls-rprx-vision"
          }
        ],
        "decryption": "none"
      },
      "streamSettings": {
        "network": "tcp",
        "security": "reality",
        "realitySettings": {
          "show": false,
          "target": "www.microsoft.com:443",
          "serverNames": [
            "www.microsoft.com",
            "microsoft.com"
          ],
          "privateKey": "你的私钥",
          "shortIds": [
            "",
            "0123456789abcdef"
          ]
        }
      },
      "sniffing": {
        "enabled": true,
        "destOverride": ["http", "tls"]
      }
    }
  ],
  "outbounds": [
    {
      "protocol": "freedom",
      "tag": "direct"
    }
  ]
}

配置说明

配置项	说明
inbounds[0].port	监听端口，REALITY 通常使用 443
inbounds[0].protocol	入站协议，vless 是推荐选择
settings.clients[0].id	VLESS 用户 UUID，客户端需保持一致
settings.clients[0].flow	XTLS 流控模式，xtls-rprx-vision 是当前推荐值
streamSettings.security	传输安全层，reality 表示使用 REALITY 代替 TLS
realitySettings.target	回落目标（可指向任何国外网站），当连接非 REALITY 客户端时，流量会被转发到此目标
realitySettings.serverNames	客户端可用的 SNI 列表
realitySettings.privateKey	X25519 私钥
realitySettings.shortIds	允许的 ShortId 列表
sniffing.enabled	启用流量嗅探，自动识别 HTTP/TLS 等协议

最小客户端配置

{
  "inbounds": [
    {
      "listen": "127.0.0.1",
      "port": 10808,
      "protocol": "socks",
      "settings": {
        "udp": true
      }
    }
  ],
  "outbounds": [
    {
      "protocol": "vless",
      "settings": {
        "vnext": [
          {
            "address": "你的服务器IP或域名",
            "port": 443,
            "users": [
              {
                "id": "与服务端一致的UUID",
                "flow": "xtls-rprx-vision",
                "encryption": "none"
              }
            ]
          }
        ]
      },
      "streamSettings": {
        "network": "tcp",
        "security": "reality",
        "realitySettings": {
          "fingerprint": "chrome",
          "serverName": "www.microsoft.com",
          "publicKey": "你的公钥（即password）",
          "shortId": ""
        }
      }
    }
  ]
}

运行

./xray run -c config.json

如果配置文件在当前目录且名为 config.json，可以直接运行：

./xray run

验证

1. 确认服务启动

查看日志输出，应看到类似：

Xray 1.x.x started

2. 从客户端测试连接

客户端配置代理后，尝试访问任意网站。如果配置正确，应该能正常访问。

3. 确认 REALITY 伪装生效

最直接的方式是使用 TLS 测试工具（如 openssl s_client）直接连接服务端口：

openssl s_client -connect 服务器IP:443 -servername www.microsoft.com

如果看到 www.microsoft.com 的真实证书，说明回落正常工作——openssl 的连接被识别为普通 HTTPS，并被转发到了微软的服务器。

4. 查看调试信息

在客户端或服务端配置中将 show 设为 true，可以看到 REALITY 握手的调试信息：

"realitySettings": {
  "show": true,
  ...
}

调试输出示例：

REALITY localAddr: 192.168.1.100:54321  uConn.AuthKey[:16]: [...]
REALITY localAddr: 192.168.1.100:54321  uConn.Verified: true

常见问题

时间不同步

REALITY 在 Session ID 中嵌入时间戳。如果客户端和服务端的时间差超过 maxTimeDiff 配置值（默认 0 表示不校验），连接会失败。确保服务器时间准确（使用 NTP）。

目标网站选择

target 指向的网站需要：

• 位于国外（服务端所在网络可达）
• 支持 TLS 1.3 和 HTTP/2
• 主域名不会跳转到其他域名（如 www.microsoft.com 而不是 microsoft.com，因为后者可能重定向到前者）

指纹不匹配

客户端 fingerprint 必须与实际使用的 uTLS 指纹匹配。常用值：chrome、firefox、safari、ios、android、edge、360、qq。

下一步阅读

• 架构概览：理解项目整体设计
• REALITY 协议详解：深入理解握手流程和认证机制
• 配置参考：所有配置项的完整说明