中文 | English · 文档 · 快速开始 · 插件参考
面向复杂网络的高性能 DNS 策略编排引擎。
OxiDNS 是一个使用 Rust 构建、面向软路由、OpenWrt、Homelab 和高级自建网络的插件化 DNS 引擎。它通过声明式策略组合匹配、缓存、转发、回退、改写、本地应答和系统联动，并提供 WebUI、管理 API、查询记录、Prometheus 指标和实时日志。
项目受 mosdns 启发，但不止于规则分流：OxiDNS 将 DNS 请求、上游响应和网络副作用放进同一条可组合、可解释的策略管线，让复杂行为仍然能够被配置、验证和追踪。
- 策略可编排：
sequence将 matcher、executor 和 provider 组合成可复用的条件分支、跳转和回退链，load_balance支持执行链轮询、随机和加权随机。 - 决策可解释：查询记录、执行路径、结构化日志和指标可以回答一次查询匹配了什么、执行了什么、为何选择当前结果。
- 接入与出口统一：同一策略可服务 UDP、TCP、DoT、DoQ 和 DoH，并统一管理上游解析、连接复用、并发裁决与代理出口。
- DNS 驱动网络行为：解析结果可以直接联动 Linux
ipset/nftset、RouterOS 地址列表与静态路由、HTTP webhook 和外部脚本。
OxiDNS 使用自有 DNS 消息模型与 wire 编解码层，并把规则编译、依赖分析和连接初始化尽可能移出请求热路径；设计方法和历史测试结果见性能与基准。
核心请求路径保持清晰：
client -> server -> sequence (matcher + executor + provider)
|-> upstream / local answer -> response
`-> side effects
下面的配置把 corp.lan 交给内网 DNS，其余域名使用加密上游。Provider、matcher、executor 和 server 通过 tag 组合，不需要把策略写进协议入口：
plugins:
- tag: internal_domains
type: domain_set
args:
exps: ["domain:corp.lan"]
- tag: forward_internal
type: forward
args:
upstreams:
- addr: "udp://192.168.1.1:53"
- tag: forward_public
type: forward
args:
upstreams:
- addr: "tls://dns.quad9.net:853"
bootstrap: "9.9.9.9:53"
- tag: main
type: sequence
args:
- matches: "qname $internal_domains"
exec: "$forward_internal"
- matches: "!has_resp"
exec: "$forward_public"
- exec: accept
- tag: dns_server
type: udp_server
args:
entry: main
listen: ":5335"
| 类别 | 能力 |
|---|---|
| 协议接入 | UDP、TCP、DoT、DoQ、DoH（HTTP/1.1、HTTP/2、HTTP/3） |
| 策略编排 | sequence、条件匹配、执行器组合、跳转、回退链与 load_balance |
| 上游与出口 | 多协议上游、并发响应裁决、连接复用、bootstrap、SOCKS5、统一 network.outbound |
| 响应处理 | TTL 感知缓存与负缓存、ECS 与 ECS 客户端地址映射、本地记录、重定向、响应构造、双栈与 IP 优选 |
| 规则数据 | 域名与 IP 集、GeoIP、GeoSite、AdGuard 规则、动态域名学习 |
| 系统联动 | Linux ipset / nftset、RouterOS address-list / static route、HTTP webhook、外部脚本 |
| 可观测性 | 查询审计与执行路径、实时日志、Prometheus 指标、上游探测、健康检查 |
| 运行时管理 | 配置校验与热重载、matcher 基础结果固定、provider 定向重载、缓存与升级管理 |
| 部署能力 | 多平台构建、Debian 包、OpenWrt LuCI 插件、内置 WebUI 与管理 API、服务化安装 |
完整的内置组件和配置字段见插件参考。
直接编辑 YAML 配置，通过插件索引快速定位插件定义。
以依赖图查看插件引用、sequence 分支和执行器组合。
从查询记录查看响应详情、匹配结果和实际执行路径。
除了内置 WebUI，也推荐体验社区开发者独立维护的管理界面：
- YoPilot：由 yyhoworks 开发的中文管理前端，提供解析拓扑、插件配置和双皮肤界面。
- OxiDNS Dashboard：由 Luke-Lab666 开发的轻量管理面板，构建为单个 HTML 文件，支持多种主题、查询日志和配置管理。
感谢社区开发者的贡献！部署方法和适配版本请参阅各项目说明。
一条命令安装最新 release，并默认注册和启动为系统服务：
curl -fsSL https://oxidns.org/install.sh | sudo sh
Windows 管理员 PowerShell：
irm https://oxidns.org/install.ps1 | iex
默认情况下，安装脚本会下载对应平台的 release、安装 WebUI，并注册和启动系统服务。
安装完成后，可以验证管理端和默认 DNS 服务：
curl -fsS http://127.0.0.1:9199/api/health
dig @127.0.0.1 example.com
dig @127.0.0.1 example.com +tcp
WebUI 默认地址为 http://服务器IP:9199/。允许其他设备访问前，请启用 api.http.auth 并通过防火墙或反向代理限制来源。修改配置后，请先使用 oxidns check 校验。
OpenWrt 会通过同一个安装脚本安装 luci-app-oxidns。完成首次查询见快速开始；手动下载、Docker、Debian 包、便携安装和卸载见文档中的“安装与部署”；按需裁剪协议和插件见自定义编译。
OxiDNS 适合需要长期运行、精细控制和完整可观测性的 DNS 环境，例如：
- 家庭网关、旁路由、OpenWrt、NAS 和 Homelab
- 按域名、客户端、查询类型或响应结果进行策略路由
- 多上游并发、主备回退、加密 DNS 与自定义出口
- 广告过滤、本地覆盖、双栈偏好、ECS 和动态规则学习
- 由 DNS 结果驱动防火墙集合、地址列表或策略路由
它不是权威 DNS 服务，也不是无需理解配置模型的一键广告过滤面板。如果你的首要需求是开箱即用的图形化管理，其他面向该场景的产品可能更合适；OxiDNS 更适合愿意用一定配置复杂度换取控制力和可解释性的用户。
- 开始使用：快速开始 · 配置总览 · 常见场景 · 从 mosdns 迁移
- 参考手册：插件总览 · 管理 API · 命令行工具 · DNS 编码速查
- 部署运维：运维与故障排查 · 安全加固 · WebUI · OpenWrt
- 了解项目：架构与设计 · 性能与基准 · 文档版本 · 版本更新 · 路线图
- 参与社区：贡献指南 · 支持项目开发 · GitHub Discussions · Telegram
OxiDNS 仍在持续开发，适合高级家庭网络、软路由、Homelab 和其他可控的自建网络环境。用于生产或关键网络前，请完成配置与回退验证、容量评估和监控建设。DNS 配置会直接影响网络可用性，请在变更前保留可恢复的配置和旁路方案。
欢迎提交 Issue、反馈真实场景、改进文档或贡献插件。
OxiDNS 主要由 Sven Shi 创建和维护。
项目基于 Rust 开发，涉及 DNS、异步网络编程、系统架构与基础设施工程，持续关注性能优化、工程质量及实际应用场景。
欢迎交流相关技术问题、分享使用经验或探讨技术合作。如果你对这些领域感兴趣，欢迎通过 Email 与我联系。
欢迎加入 Telegram 群与作者和其他用户交流：@OXIDNS · https://t.me/oxidns
如果 OxiDNS 对你有帮助，可以通过微信或支付宝支持项目的持续开发与维护。支持完全自愿，感谢每一份认可。
| 微信支付 | 支付宝 |
|---|---|
 |
 |
资金支持不会建立商业服务关系，也不会影响功能规划或问题处理的优先级。其他支持方式请参阅贡献指南。
本项目基于 GNU General Public License v3.0 or later 开源。
独立的自有库 oxidns-proto 和
oxidns-macros 采用 MIT OR Apache-2.0 双重许可证，
使用者可以任选其一。其他 workspace crate 的许可证见各自的 Cargo.toml
和许可证文件。