跳转至

排障指南

先跑这几条

qre-tool showconf /etc/qre/qre.conf
qre-tool showconf /etc/qre/dev/qre0.conf
sudo qre-tool --dry-run up qre0
sudo qre-tool show qre0
journalctl -u qred@qre0 -e

如果是握手或伪装问题，再生成 capture：

qre-tool session-capture valid-client \
  /etc/qre/dev/server.conf /etc/qre/dev/client.conf /tmp/qre-valid.pcap

配置解析失败

常见错误：

现象 原因 处理
config must contain exactly one ... section 文件没有 [Global]、[Server] 或 [Client] 补齐正确 section。
config cannot mix [Global], [Server], and [Client] 全局配置和接口配置混在一个文件中 拆成 /etc/qre/qre.conf 与 /etc/qre/dev/<profile>.conf。
duplicate field 同一字段重复 删除重复项。hooks 可重复，普通字段不可重复。
field ... is not valid for ... config server/client 字段混用 检查 Listen、Dest 只在 server，Endpoint、RealityPublicKey 只在 client。
hostname labels must not contain '_' hostname 中有下划线 换成合法 DNS hostname。
RealityShortId hex length must be between 2 and 16 short id 长度错误 使用 1 到 8 字节，也就是 2 到 16 个 hex 字符。

权限不足

涉及 netlink 修改、kernel module、BPF map、socket 注册和 session 安装的命令通常需要 root：

sudo qre-tool up qre0
sudo qre-tool daemon qre0
sudo qre-tool install-session qre0 ...

只读命令通常不需要 root：

qre-tool showconf /etc/qre/dev/qre0.conf
qre-tool strip qre0
qre-tool session-plan server.conf client.conf
qre-tool session-capture valid-client server.conf client.conf /tmp/qre.pcap

找不到 qre.ko

错误形态通常包含：

qre module cannot be found; set QRE_MODULE_PATH or install qre.ko for kernel ...

处理：

make -C kernel/qre
sudo QRE_MODULE_PATH=$PWD/kernel/qre/qre.ko qre-tool --dry-run up qre0
sudo QRE_MODULE_PATH=$PWD/kernel/qre/qre.ko qre-tool up qre0

如果模块由系统服务预加载，可禁用自动加载：

sudo QRE_MODULE_LOAD=false qre-tool up qre0

设备或地址异常

检查：

ip link show qre0
ip addr show dev qre0
sudo qre-tool show qre0

常见原因：

  • Device 超过 15 字符或不符合 Linux netdev 名称限制。
  • Address CIDR 与现有路由策略冲突。
  • up 失败后部分外部 hook 修改没有回滚。
  • reload 后旧地址未删除，检查 state dir 中 profiles/<profile>.state。

可先执行：

sudo qre-tool down qre0
sudo qre-tool --dry-run up qre0
sudo qre-tool up qre0

握手失败

服务端和客户端必须一致：

字段 检查点
ServerName server/client 完全相同，且是合法 hostname。
RealityPublicKey 客户端使用服务端私钥对应的公钥。
RealityShortId 客户端 short id 在服务端 RealityShortIds 中。
RealityMaxTimeDiff 双方系统时间差在允许范围内。
Endpoint/Listen 客户端能访问服务端 UDP 监听地址。
Dest 服务端能访问伪装目标。

用用户态命令隔离问题：

qre-tool session-plan server.conf client.conf
qre-tool session-capture valid-client server.conf client.conf /tmp/qre-valid.pcap
qre-tool session-capture invalid-short-id server.conf client.conf /tmp/qre-invalid-short-id.pcap
qre-tool session-capture wrong-sni server.conf client.conf /tmp/qre-wrong-sni.pcap

valid-client 被拒绝时，优先检查 key、short id 和 SNI。无效场景被接受时，应视为高优先级问题。

共享端口异常

先看内核状态：

sudo qre-tool show qre0

关注：

  • shared_socket_count
  • shared_program_count
  • shared_socket_array_count
  • bpf_map_count
  • bpf_map_sync_failures
  • adopted_cid_count

用 loader check 验证 eBPF 控制片：

sudo qre-tool shared-port-loader-check \
  BpfElf=/usr/lib/qre/libqre_ebpf.so \
  Listen=127.0.0.1:1443 \
  ConnectionId=00112233445566778899aabbccddeeff00 \
  Device=qre0

注意 ConnectionId 长度必须和 RoutedCidLen 一致；未显式指定时，shared-port-loader-check 使用 ConnectionId 长度作为 routed CID 长度。

BPF pin 或 map 问题

常见处理：

mount | grep /sys/fs/bpf
sudo ls -la /sys/fs/bpf
sudo qre-tool create-cid-map BpfMapPath=/sys/fs/bpf/qre-cid-routes
sudo qre-tool show-cid-map BpfMapPath=/sys/fs/bpf/qre-cid-routes

如果测试异常退出，可能留下临时 pin。确认没有活跃 daemon 后再清理相关 qre_tool_shared_port_* pin。

Cloudflare Pages 部署失败

文档 workflow 需要两个 secrets：

CLOUDFLARE_API_TOKEN
CLOUDFLARE_ACCOUNT_ID

本地先确认 MkDocs 构建通过：

mkdocs build --strict

然后检查 workflow 日志中的 Wrangler 输出。部署目标项目名固定为 qre-docs，上传目录是 site/。