运维指南¶

systemd¶

打包安装后，qred@.service 是 qre-tool daemon %i 的模板包装：

sudo systemctl start qred@qre0
sudo systemctl status qred@qre0
sudo systemctl reload qred@qre0
sudo systemctl stop qred@qre0

profile 名来自 unit 实例名。qred@qre0 会读取 /etc/qre/dev/qre0.conf，除非 unit 环境覆盖了 QRE_CONFIG_DIR。

直接运行 daemon¶

sudo qre-tool daemon qre0

常用覆盖：

sudo qre-tool daemon qre0 \
  --config-dir /etc/qre/dev \
  --global-config /etc/qre/qre.conf \
  --state-dir /var/lib/qre \
  --bpf-elf /usr/lib/qre/libqre_ebpf.so \
  --pin-dir /sys/fs/bpf

--dry-run 可用于检查 daemon 启动计划：

sudo qre-tool --dry-run daemon qre0

reload 策略¶

配置变更分两类：

变更	建议操作
`Address`、`MTU`、内核 profile 字段	`qre-tool reload <profile>` 或 `systemctl reload qred@<profile>`
`Endpoint`、`ServerName`、REALITY key、short id、shared-port runtime 相关变更	重启 daemon
hooks 变更	根据 hook 的执行时机选择 `reload`、`restart` 或手动清理

reload 是窄范围同步，不会替用户重新设计路由策略。对长连接控制面有影响的变更应重启。

同端口多租户¶

目录示例：

/etc/qre/dev/
  tenant-a.conf
  tenant-b.conf
  tenant-c.conf

tenant-a.conf 与 tenant-b.conf 可以共享：

Listen = 0.0.0.0:443
ServerName = www.example.com
Dest = www.example.com:443

但每个 profile 应保持独立：

Device = qre-a
Address = 10.44.0.1/32
RealityShortIds = 0123456789abcdef

约束：

同一共享 front 中，short id 不能冲突。
多个 ServerName 可以共享同一个 Listen。
fallback TLS 规则放在全局 [SSLPreRead "..."] 中，不放在 profile 中。

状态目录¶

默认状态目录是 /var/lib/qre。常见内容：

路径	说明
`profiles/<profile>.state`	`up`/`reload` 保存的 profile device、address、role。
`daemon/<profile>.ready`	daemon 成功安装 session 或 server runtime ready 后写入的 ready file。
Dest profile cache	服务端 Dest probe 的持久 cache。

如果测试中需要隔离状态，可以使用：

QRE_STATE_DIR=/tmp/qre-state sudo -E qre-tool daemon qre0

或 daemon 选项：

sudo qre-tool daemon qre0 --state-dir /tmp/qre-state

Kernel module 加载¶

默认 qre-tool up 和 qre-tool daemon 会尝试加载 qre.ko。查找顺序包括当前内核模块目录和仓库开发路径 kernel/qre/qre.ko。

可用环境变量：

变量	说明
`QRE_MODULE_PATH`	指定 `qre.ko` 文件路径。
`QRE_MODULE_LOAD=false`	禁用自动加载，适合测试或由外部系统预加载模块。

升级¶

安全升级顺序：

停止活跃 profile：sudo systemctl stop qred@qre0 或 sudo qre-tool down qre0。
卸载或替换旧的 qre.ko 和 qre-tool。
安装新版本的 qre-tool、qre.ko 和 BPF ELF。
运行 qre-tool showconf 校验配置。
启动 profile：sudo systemctl start qred@qre0。

qre-tool 和 qre.ko ABI 应作为一个单元升级，不建议混用不同版本。

卸载¶

sudo systemctl stop qred@qre0
sudo qre-tool down qre0
sudo rm -f /usr/local/bin/qre-tool

如果是 DKMS/deb 安装，还需要按包管理器流程卸载包和 DKMS module。保留 /etc/qre 可以方便后续重新安装；彻底移除前先确认不再需要 profile 与状态文件。

文档站点发布¶

本文档使用 Material for MkDocs。公开站点源文件位于：

mkdocs.yml
requirements-docs.txt
docs/public/
.github/workflows/docs.yml

本地构建：

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

本地预览：

mkdocs serve

GitHub Actions 会在 docs/public/**、mkdocs.yml、requirements-docs.txt 或 workflow 自身变化时构建文档。push 到 main 时会把 site/ 部署到 Cloudflare Pages 项目 qre-docs。

需要在 GitHub 仓库 secrets 中配置：

Secret	说明
`CLOUDFLARE_API_TOKEN`	有 Cloudflare Pages deploy 权限的 API token。
`CLOUDFLARE_ACCOUNT_ID`	Cloudflare account id。