跳转至

快速开始

本章给出一组最小 server/client 配置。示例地址使用文档网段，部署时需要替换为真实公网地址、域名和 X25519 key。

前提

  • Linux 主机，能够加载 out-of-tree kernel module。
  • qre-tool 已安装在 /usr/local/bin/qre-tool 或 PATH 中。
  • qre.ko 已安装到当前运行内核可发现的位置，或通过 QRE_MODULE_PATH 指向构建产物。
  • 服务端公网 UDP 端口可达，例如 0.0.0.0:443。
  • 服务端与客户端配置中的 ServerName、key 和 short id 一致。

从源码开发时，常用验证命令是：

cargo fmt --all -- --check
cargo check --workspace
cargo test --workspace
make -C kernel/qre

文件位置

QRE 把全局策略和接口 profile 分开：

/etc/qre/qre.conf          # 全局配置，可不存在；不存在时使用默认值
/etc/qre/dev/qre0.conf     # 一个 server 或 client profile
/var/lib/qre/              # 状态目录，默认值

profile 名称来自文件名。/etc/qre/dev/qre0.conf 对应 qre-tool daemon qre0 和 qred@qre0.service。

服务端配置

/etc/qre/dev/qre0.conf
[Server]
Device = qre0
Address = 10.44.0.1/32
Listen = 0.0.0.0:443
MTU = 1280

Dest = www.example.com:443
ServerName = www.example.com
RealityPrivateKey = AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=
RealityShortIds = 0123456789abcdef
RealityMaxTimeDiff = 120

关键点：

  • Listen 是服务端接收 REALITY/QUIC 握手的 UDP 地址。
  • Dest 是伪装目标，服务端会根据它获取目标侧行为特征。
  • ServerName 是客户端握手使用的 SNI 名称。
  • RealityPrivateKey 是服务端 32 字节 X25519 私钥的 base64 编码。示例值不能用于生产。
  • RealityShortIds 是允许的 short id 列表，用逗号分隔。

客户端配置

/etc/qre/dev/qre0.conf
[Client]
Device = qre0
Address = 10.44.0.2/32
MTU = 1280

Endpoint = 203.0.113.10:443
ServerName = www.example.com
RealityPublicKey = AQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQE=
RealityShortId = 0123456789abcdef
PersistentKeepalive = 25

关键点：

  • Endpoint 指向服务端公网 ip:port 或 host:port。
  • ServerName 必须与服务端配置一致。
  • RealityPublicKey 是服务端 X25519 公钥的 base64 编码。客户端必须固定真实公钥。
  • RealityShortId 必须包含在服务端 RealityShortIds 中。
  • PersistentKeepalive = 0 表示不主动保活。

全局配置

全局配置可先使用默认值。如果需要状态目录、Dest cache 或 TLS passthrough，可以创建：

/etc/qre/qre.conf
[Global]
StateDir = /var/lib/qre
DestCacheRefreshSeconds = 300
DestCacheExpirySeconds = 900
DefaultDestTransport = auto
AllowStaleOnStartup = false
FallbackFlowTimeoutMs = 30000
FallbackRateWindowMs = 1000
MaxFallbackFlowsPerWindow = 64
FallbackByteRateLimitBps = 1000000
InvalidProbeRateWindowMs = 1000
MaxInvalidProbesPerWindow = 128

校验配置

showconf 接受全局配置或接口 profile，并输出标准化 JSON：

qre-tool showconf /etc/qre/qre.conf
qre-tool showconf /etc/qre/dev/qre0.conf

如果只想按 profile 名称读取 /etc/qre/dev/<profile>.conf，使用：

qre-tool strip qre0

启动

使用 systemd：

sudo systemctl start qred@qre0
sudo systemctl status qred@qre0

直接运行：

sudo qre-tool daemon qre0

daemon 模式会先执行等价于 qre-tool up qre0 的准备动作，然后根据 profile 角色进入 server 或 client 持久循环。停止 daemon 或 systemd unit 时会清理设备地址、内核设备状态、ready file 和相关会话。

查看状态

sudo qre-tool show
sudo qre-tool show qre0
sudo qre-tool --json show qre0

常用观察点：

  • role：设备角色。
  • session 或 session 相关字段：内核是否已有安装的会话。
  • connection_id、adopted_cid_count：CID 分流状态。
  • shared_socket_count、shared_program_count、shared_socket_array_count：共享端口分流状态。
  • bpf_map_count、bpf_map_sync_failures：CID 路由 map 同步状态。

热更新

修改 profile 后：

sudo systemctl reload qred@qre0

或直接：

sudo qre-tool reload qre0

reload 只同步该 profile 的内核配置和地址；如果需要重建长连接控制面，重启对应 daemon。