命令行工具

本页按使用任务介绍 OxiDNS 的命令行工具。日常部署时，最常用的是先 check 校验配置，再 start 启动服务。

主程序只有一个二进制：oxidns。

可用顶层命令如下：

• start
• check
• build-info
• export-dat
• probe
• service
• upgrade

常用任务

目标	命令
校验配置	oxidns check -c config.yaml
前台启动	oxidns start -c config.yaml
临时开启调试日志	oxidns start -c config.yaml -l debug
查看插件依赖图	oxidns check -c config.yaml --graph
查看当前二进制编译能力	oxidns build-info
探测上游连通性和并发行为	oxidns probe upstream tcp://1.1.1.1:53
安装系统服务	sudo oxidns service install -d /var/lib/oxidns -c /etc/oxidns/config.yaml
检查新版本	oxidns upgrade check
从 dat 导出规则文件	oxidns export-dat --file ./rules/geosite.dat --kind geosite --selector cn --out-dir ./rules/exported

查看帮助

可先查看顶层帮助：

oxidns --help

查看某个子命令的帮助：

oxidns start --help
oxidns check --help
oxidns build-info --help
oxidns export-dat --help
oxidns probe --help
oxidns probe upstream --help
oxidns service --help
oxidns upgrade --help

start

前台启动 OxiDNS 服务。

典型用法：

oxidns start -c config.yaml
oxidns start -c config.yaml -l debug
oxidns start -c /etc/oxidns/config.yaml -d /var/lib/oxidns

参数说明：

• -c, --config <PATH>
  • 配置文件路径。
  • 默认值：config.yaml
• -d, --working-dir <PATH>
  • 启动前切换到指定工作目录。
  • 所有运行期相对路径都以该目录为基准，包括日志、SQLite、规则文件和 api.http.webui.root。
  • Debian 默认布局中，配置放在 /etc/oxidns/config.yaml，运行期相对路径资源放在 /var/lib/oxidns。
• -l, --log-level <LEVEL>
  • 临时覆盖配置文件中的日志级别。
  • 支持：off trace debug info warn error

适用场景：

• 本地调试
• 前台运行
• 容器内直接启动

check

静态检查配置文件是否有效，但不会真正启动 OxiDNS。

典型用法：

oxidns check -c config.yaml
oxidns check -c /etc/oxidns/config.yaml
oxidns check -c /etc/oxidns/config.yaml -d /var/lib/oxidns
oxidns check -c config.yaml --graph

参数说明：

• -c, --config <PATH>
  • 配置文件路径。
  • 默认值：config.yaml
• -d, --working-dir <PATH>
  • 校验前切换到指定工作目录。
  • 适合配置里使用相对路径时配合使用。
  • 建议与实际启动时的 -d 保持一致，避免校验和运行看到不同的相对路径。
• --graph
  • 校验成功后打印插件依赖图。

行为说明：

• 只做静态校验：
  • YAML 解析
  • 配置结构校验
  • 插件类型和依赖关系校验
• 不会初始化插件，不会绑定监听端口，也不会启动运行时。
• 校验成功时返回退出码 0，并输出简短成功信息。
• 传入 --graph 时，会额外按插件初始化顺序输出纯文本依赖图。
• 校验失败时返回非零退出码，并输出具体错误原因。

probe

主动探测运行时外部目标。当前提供 probe upstream，用于检查单个 DNS 上游的连通性、基础响应信息、域名解析结果，以及并发 / pipeline 行为。

probe upstream

典型用法：

oxidns probe upstream udp://1.1.1.1:53
oxidns probe upstream tcp://1.1.1.1:53
oxidns probe upstream tls://dns.google:853 --qname example.com. --qtype A
oxidns probe upstream https://dns.google/dns-query --json
oxidns probe upstream tcp://dns.example.com:53 -c config.yaml --outbound remote

参数说明：

• <addr>
  • 要探测的 upstream 地址。
  • 支持与 forward upstream 一致的地址写法，例如 udp://、tcp://、tcp+pipeline://、tls://、tls+pipeline://、https://、doh://、h3://、quic://、doq://。
  • 不带 scheme 时按 UDP 处理。
• -c, --config <PATH>
  • 可选读取配置文件，只复用其中的 network.outbound profile。
  • 未指定时不会读取运行配置。
• -d, --working-dir <PATH>
  • 读取配置前切换工作目录。
• --outbound <NAME>
  • 使用指定 outbound profile 的 resolver / proxy 设置。
• --dial-addr <IP>
  • 直接连接指定 IP，同时保留 <addr> 中的主机名用于 TLS SNI 和 HTTP Host。
• --bootstrap <ADDR>
  • 使用指定 bootstrap DNS 解析域名型 upstream。
• --bootstrap-version <4|6>
  • bootstrap 解析时偏好的 IP 版本。
• --socks5 <ADDR>
  • 对支持代理的上游连接使用 SOCKS5。
• --port <PORT>
  • 覆盖 upstream 端口。
• --insecure-skip-verify
  • 跳过 TLS 证书校验，仅建议测试时使用。
• --timeout <DURATION>
  • 单次查询超时。
  • 默认值：5s
• --qname <NAME>
  • 串行基线查询域名。
  • 默认值：example.com.
• --qtype <TYPE>
  • 查询类型。
  • 默认值：A
• --serial-samples <N>
  • 串行基线查询次数。
  • 默认值：2
• --pipeline-concurrency <N>
  • 并发探测的查询数量；TCP / DoT 会强制在同一条连接上发送这些查询。
  • 默认值：16
• --pipeline-rounds <N>
  • 并发探测轮数。
  • 默认值：2
• --json
  • 输出结构化 JSON 报告。

输出内容：

• 目标信息：地址、协议、服务名、端口、超时。
• 域名型 upstream 的解析结果：resolved_ip 和 resolution_source，来源可能是 literal、dial_addr、configured、bootstrap、system 或 proxy。
• 串行基线：reachable / unreachable、平均延迟、rcode、answer 数量、TC / RA 标志和错误摘要。
• 并发探测：supported / unsupported / unstable / inconclusive、成功数、超时数、响应 ID / question / qtype 不匹配数、其它错误和建议。
• 非 JSON 模式会在探测过程中向 stderr 输出进度，最终报告输出到 stdout；JSON 模式只向 stdout 输出报告。

协议行为：

• UDP、DoH、DoH3 和 DoQ 使用对应 upstream 实现发起并发查询，用来评估该协议下的并发或多路复用表现。
• TCP 和 DoT 会额外强制使用同一条连接发送并发查询，用来发现开启 pipeline 后可能出现的超时、连接关闭、协议错误、响应 ID 错乱或 question 串线。
• 如果串行基线失败，并发结论会是 inconclusive，避免把基础连通性问题误判成 pipeline 问题。

build-info

输出当前 oxidns 二进制的编译期能力信息。

典型用法：

oxidns build-info

行为说明：

• 不读取配置文件，不启动运行时，也不会绑定端口。
• 输出格式为格式化 JSON。
• 输出内容包括：
  • version：当前包版本。
  • bundle：当前二进制的主编译组合包，可能为 minimal、standard、full 或 custom。
  • enabled_bundles：编译进当前二进制的 bundle feature。
  • enabled_features：公开的 Cargo feature 列表。
  • supported_plugins：当前二进制支持的 server、executor、matcher 和 provider 插件类型。
• 返回的编译能力对象与管理 API GET /api/build 响应中的 build 字段一致。

适用场景：

• 确认当前安装的是 minimal、standard、full 还是自定义构建。
• 排查某个协议、插件或 upgrade 子命令是否被编译进当前二进制。
• 在自定义构建、发布包验证或升级前后对比能力差异。

export-dat

从 geosite.dat 或 geoip.dat 中导出指定 selector 到文本规则文件。

这些导出的文本文件可直接给 domain_set.files 或 ip_set.files 使用。

典型用法：

oxidns export-dat \
  --file ./rules/geosite.dat \
  --selector cn \
  --selector geolocation-\!cn \
  --out-dir ./rules/exported

额外生成并集文件：

oxidns export-dat \
  --file ./rules/geosite.dat \
  --kind geosite \
  --selector cn \
  --selector mastercard@cn \
  --out-dir ./rules/exported \
  --merged-file geosite_union.txt

导出 geoip.dat：

oxidns export-dat \
  --file ./rules/geoip.dat \
  --kind geoip \
  --selector cn \
  --out-dir ./rules/exported

不传 selector，直接导出整份 dat：

oxidns export-dat \
  --file ./rules/geosite.dat \
  --kind geosite \
  --out-dir ./rules/exported

指定原始格式导出：

oxidns export-dat \
  --file ./rules/geosite.dat \
  --kind geosite \
  --format original \
  --selector cn \
  --out-dir ./rules/exported

参数说明：

• --file <PATH>
  • dat 文件路径。
• --kind <KIND>
  • 指定 dat 类型。
  • 可选值：auto geosite geoip
  • 默认值：auto
• --format <FORMAT>
  • 指定文本导出格式。
  • 可选值：oxidns original
  • 默认值：oxidns
• --selector <SELECTOR>
  • 要导出的 selector。
  • 可重复传入多个，按输入顺序分别导出。
  • 不传时表示直接导出整份 dat。
• --out-dir <DIR>
  • 输出目录。
  • 不存在时会自动创建。
• --merged-file <NAME>
  • 可选。
  • 在输出目录中额外生成一个并集文件。
• --overwrite
  • 可选。
  • 允许覆盖已存在的目标文件。

行为说明：

• 默认按 selector 分别生成文件，例如 cn.txt、geolocation-!cn.txt。
• 不传 selector 时，会直接生成单个整表导出文件；默认文件名分别为 geosite.txt 或 geoip.txt。
• geosite 输出为 OxiDNS 域名规则格式，例如 full:、domain:、keyword:、regexp:。
• oxidns 格式会在导出文件头加入注释行，例如 # selector: cn；不传 selector 时为 # selector: all。
• geosite 在 original 格式下会保留原始类型语义，输出如 plain:、regex:、root_domain:、full:。
• geosite 的 original 格式会按 code 分组输出；如果域名带 attribute，会追加在域名后面，例如 @cn、@ads=1。
• geoip 输出为 IP / CIDR 纯文本规则。
• geoip 的 oxidns 格式同样会加入 selector 注释行。
• geoip 的 original 格式会按 code 分组输出，组头形式为 [code]。
• geosite selector 支持 code@attribute，例如 mastercard@cn。
• 任一 selector 没有匹配结果时，命令会直接失败，不会静默跳过。

service

管理系统服务安装与运行状态。

支持以下子命令：

• service install
• service start
• service stop
• service restart
• service uninstall

service install

安装系统服务定义，但不会立即启动。

sudo oxidns service install -d /var/lib/oxidns -c /etc/oxidns/config.yaml

参数说明：

• -d, --working-dir <PATH>
  • 服务工作目录，也是服务内所有运行期相对路径的基准。
  • 必须为绝对路径。
  • 生成的服务会通过 ExecStart ... -d <PATH> 传给 OxiDNS；自定义 systemd unit 若额外设置 WorkingDirectory=，请保持二者一致。
• -c, --config <PATH>
  • 服务启动时使用的配置文件路径。

service start

启动已安装的系统服务。

sudo oxidns service start

service stop

停止已安装的系统服务。

sudo oxidns service stop

service restart

重启已安装的系统服务。

sudo oxidns service restart

service uninstall

卸载已安装的系统服务。

sudo oxidns service uninstall

upgrade

检查、下载或应用 GitHub Release 中的 OxiDNS 升级包。

支持以下子命令：

• upgrade check
• upgrade download
• upgrade apply

典型用法：

oxidns upgrade
oxidns upgrade --force
oxidns upgrade check
oxidns upgrade download --target latest
sudo oxidns upgrade apply
sudo oxidns upgrade apply --no-restart

通用参数：

• --target <TAG|latest>
  • Release tag 或 latest。
  • 默认值：latest
• --repository <OWNER/REPO>
  • GitHub 仓库。
  • 默认值：svenshi/oxidns
• --asset <NAME|auto>
  • Release asset 名称；auto 会按当前平台和编译版本选择 archive。
  • 默认值：auto
• -c, --config <PATH>
  • 运行配置文件路径，用于在未显式指定 --webui-dir 时读取 api.http.webui.root。
  • 未指定时，优先使用当前目录的 config.yaml；Linux 打包安装环境中，如果存在 /etc/oxidns/config.yaml，会用它推导 WebUI 路径。
• -d, --working-dir <DIR>
  • 运行期相对路径的基准目录，语义与 start -d/--working-dir 一致。
  • 未指定且检测到 Linux 打包配置时，默认使用 /var/lib/oxidns；否则使用当前目录。
• --bundle <auto|full|standard|minimal>
  • 当 --asset auto 时选择 release 编译版本。
  • 默认值：auto，跟随当前二进制的编译版本。
  • full 使用旧资产名，例如 oxidns-x86_64-unknown-linux-musl.tar.gz；standard / minimal 使用 slim 资产名，例如 oxidns-standard-x86_64-unknown-linux-musl.tar.gz。
• --cache-dir <DIR>
  • 升级文件缓存目录。
  • 默认值：./upgrade-cache
• --backup-dir <DIR>
  • apply 替换前的二进制备份目录。
  • 默认值：./upgrade-backups
• --webui-dir <DIR>
  • apply 时安装 WebUI 静态资源的目录；相对路径按 -d/--working-dir 解析，应与 api.http.webui.root 一致。
  • 未指定时，优先从运行配置的 api.http.webui.root 推导；没有配置时使用 ./webui。
• --skip-webui
  • apply 时跳过 WebUI 目录升级，仅替换二进制文件。
• --no-restart
  • apply 成功后跳过服务重启。默认会通过系统服务管理器（systemd / launchd / Windows SCM）自动重启已安装的服务。
• --allow-prerelease
  • 允许使用 prerelease。
• --force
  • apply 时即使目标 release 不比当前版本更新，也继续下载、校验并替换。
• --timeout <DURATION>
  • HTTP 请求超时，例如 30s、2m。
• --socks5 <ADDR>
  • 可选 SOCKS5 代理。
• --insecure-skip-verify
  • 跳过 TLS 证书校验。
• --github-token <TOKEN>
  • GitHub 个人访问令牌，用于提高 API 速率限制或访问私有仓库。

行为说明：

• check 只查询 release 并判断版本是否更新。
• download 下载 archive，并使用 GitHub release asset 的 digest 字段校验 SHA256。
• 显式传入 --asset 时优先使用指定 asset，不再根据 --bundle 推导。
• 不写子命令时默认执行 apply。
• apply 默认只有检测到新版本才会更新；--force 会强制更新。
• apply 在 Unix 平台会解包 .tar.gz、备份当前二进制并替换；Windows 会解包 .zip、备份并替换二进制，同样支持 WebUI 目录升级。
• apply 默认在替换二进制后，将 archive 中的 webui/ 目录备份并安装到 --webui-dir；--skip-webui 可跳过；archive 不含 webui/ 时跳过且不影响二进制升级。
• Debian 打包安装的默认布局中，直接运行 sudo oxidns upgrade apply 会按 /etc/oxidns/config.yaml 和 /var/lib/oxidns 推导 WebUI 目录；/var/lib/oxidns/webui 是符号链接时，会更新其指向的真实目录。
• apply 成功后默认通过系统服务管理器重启服务；如果不想自动重启，传 --no-restart。
• apply 成功后会询问是否清理缓存目录和备份目录，默认选择 Y。

页面范围

本页覆盖上面这些命令。需要确认本机二进制的完整参数时，可运行 oxidns <subcommand> --help 查看。