外部开发者指南¶

本章面向希望从源码构建、测试、打包或集成 QRE 的外部开发者。用户部署优先阅读“快速开始”和“配置文件”；开发者需要同时理解 Rust workspace、kernel module、eBPF 和 qre-tool 的边界。

仓库结构¶

QRE/
  Cargo.toml
  crates/
    qre-core/          配置、共享类型和数据包结构
    qre-tool/          CLI、daemon、lifecycle、netlink 和共享端口 runtime
    qre-ebpf/          共享端口 eBPF 程序
    qre-ebpf-smoke/    eBPF smoke 工具
    quinn-reality/     QUIC/REALITY 集成
    reality-io/        REALITY flow、session 和 Dest profile 逻辑
    reality-rust/      REALITY 协议和 TLS/QUIC primitive
  kernel/qre/          qre.ko Linux kernel module
  examples/            可解析的示例配置
  packaging/           Debian、RPM、systemd、logrotate 和 DKMS 包装
  tools/               CI、namespace 和诊断脚本
  docs/public/         发布到 Cloudflare Pages 的用户和开发者文档

开发环境¶

需要：

Rust stable，仓库当前使用 Rust 2024 edition。
Rust nightly 和 rust-src，用于 eBPF 构建。
bpf-linker。
Linux kernel headers，用于构建 qre.ko。
常规构建工具：build-essential、make、pkg-config 等。

安装 Rust 组件示例：

rustup toolchain install stable --component rustfmt
rustup toolchain install nightly --component rust-src
rustup default stable
cargo install bpf-linker --locked

构建¶

Rust workspace：

cargo fmt --all -- --check
cargo check --workspace
cargo test --workspace
cargo build --release --workspace

kernel module：

make -C kernel/qre

eBPF ELF：

tools/ci/check-qre-ebpf-build.sh

发布构建入口：

make release

安装到临时 root 目录检查包内容：

make install-dry-run
find target/install-root -maxdepth 5 -type f | sort

运行测试¶

基础测试：

cargo fmt --all -- --check
cargo check --workspace
cargo test --workspace
tools/ci/check-terminology.sh
tools/ci/check-qre-lifecycle.sh
tools/ci/check-userspace-capture-matrix.sh
tools/ci/check-install-dry-run.sh

需要 kernel 或 network namespace 的测试通常要求 Linux、root 权限、可加载 module，并且当前系统没有已有 qre module 干扰：

make netns-smoke-guard
make qre-tool-netns
make qre-tool-underlay-netns
make kernel-session-install
make qre-shared-port-loader-check

如果只想验证用户态握手和 pcap 形状，优先使用不加载内核的命令：

qre-tool session-plan examples/qre-server.conf examples/qre-client.conf
qre-tool session-capture valid-client \
  examples/qre-server.conf examples/qre-client.conf /tmp/qre-valid.pcap

模块边界¶

模块	应放入这里的逻辑	不应放入这里的逻辑
`qre-core`	严格配置解析、共享类型、稳定 JSON 输出	netlink、socket、文件系统副作用
`qre-tool`	CLI、daemon、profile lifecycle、session 安装、诊断命令	内核热路径 packet crypto
`reality-rust`	REALITY/TLS/QUIC 协议 primitive	QRE profile lifecycle
`reality-io`	Dest probe、session manager、fallback policy、flow 管理	Linux netdev 操作
`qre.ko`	QRE netdev、会话表、CID 表、计数器、快速路径加解密	配置解析、REALITY 私钥、Dest probe、fallback 策略
`qre-ebpf`	`SO_REUSEPORT` 共享端口分流	profile 读取和 session 派生

这条边界对安全性很重要：REALITY private key、Dest probing、fallback policy 和配置解析留在用户态，kernel module 只持有数据面需要的会话材料。

配置兼容性¶

配置解析是严格的：

未知字段失败。
重复普通字段失败。
[Global]、[Server]、[Client] 混用失败。
server/client 字段放错 section 失败。
数字、CIDR、hostname、base64 key 和 hex short id 都会在任何内核修改前校验。

外部集成建议先调用：

qre-tool showconf <path>

它会输出稳定 JSON，适合用于部署系统中的预检查。

CLI 兼容性¶

面向用户的稳定入口是：

qre-tool daemon <profile>
qre-tool up|reload|down <profile>
qre-tool show [device]
qre-tool showconf <config>
/etc/qre/qre.conf
/etc/qre/dev/<profile>.conf
qred@.service

shared-port-*、install-session、update-session、BPF map 和 shared socket 命令属于高级调试与集成接口。它们会尽量保持可诊断，但外部产品集成应优先使用 profile 和 daemon 模式。

生成文档¶

公开文档站点使用 Material for MkDocs：

python3 -m venv /tmp/qre-docs-venv
. /tmp/qre-docs-venv/bin/activate
pip install -r requirements-docs.txt
mkdocs build --strict
mkdocs serve

只把用户和外部开发者需要的页面放在 docs/public/。内部设计记录、历史讨论和仓库维护笔记不进入发布站点。

提交前检查¶

提交代码前至少运行：

cargo fmt --all -- --check
cargo check --workspace
cargo test --workspace
tools/ci/check-terminology.sh

修改 kernel、eBPF、packaging 或 network namespace 行为时，同时运行对应 tools/ci/ 脚本。性能结论需要附带命令、时长、namespace 拓扑和观测吞吐。