快速开始

本页只完成一件事：安装 OxiDNS，并确认第一次 DNS 查询成功。版本选择、便携模式、卸载和生产部署等细节请进入对应安装文档。

选择安装方式

使用场景	推荐入口
Linux / macOS / Windows 主机	本机安装脚本
Docker / Compose	Docker 部署
OpenWrt 路由器	OpenWrt 与 LuCI
手动 archive、Debian 包或源码	Release、Debian 与源码安装
裁剪插件和协议	自定义编译

1. 安装

Linux / macOS

curl -fsSL https://oxidns.org/install.sh | sudo sh

Windows

在管理员 PowerShell 中运行：

irm https://oxidns.org/install.ps1 | iex

Docker

先准备配置：

mkdir -p oxidns && cd oxidns
docker run --rm --entrypoint /bin/cat \
  svenshi/oxidns:latest /etc/oxidns/config.yaml > config.yaml

再启动容器：

docker run -d --name oxidns --restart unless-stopped \
  -p 53:53/udp -p 53:53/tcp -p 127.0.0.1:9199:9199/tcp \
  -v "$(pwd)/config.yaml:/etc/oxidns/config.yaml:ro" \
  svenshi/oxidns:latest

OpenWrt

curl -fsSL https://oxidns.org/install.sh | sh

没有 curl 时使用 wget -O- https://oxidns.org/install.sh | sh。

OpenWrt 还需要安装内核

OpenWrt 脚本只安装 luci-app-oxidns。安装完成后进入 Services → OxiDNS → Core 安装并启动 OxiDNS 内核，再进行下面的验证。

2. 验证

Linux / macOS

oxidns --version
oxidns build-info
curl -fsS http://127.0.0.1:9199/api/readyz
dig @127.0.0.1 example.com

Windows

oxidns.exe --version
oxidns.exe build-info
Invoke-RestMethod http://127.0.0.1:9199/api/readyz
Resolve-DnsName example.com -Server 127.0.0.1

Docker

docker ps --filter name=oxidns
docker logs --tail 50 oxidns
curl -fsS http://127.0.0.1:9199/api/readyz
dig @127.0.0.1 example.com

OpenWrt

在 LuCI 状态页确认内核运行，再从路由器终端或局域网设备查询：

nslookup example.com 127.0.0.1

同时满足以下条件即表示首次启动成功：

• 版本与 build-info 能正常输出；
• /api/readyz 返回成功，或 LuCI 状态显示运行中；
• DNS 查询返回有效结果。

WebUI 默认地址为 http://服务器IP:9199/。如果 readiness 正常但 DNS 查询失败，按运维与故障排查检查监听端口、配置和上游。允许其它设备访问 WebUI/API 前，请先启用认证并阅读安全加固。

3. 下一步

• 用场景配置选择家庭、旁路由或服务端模板。
• 阅读配置指南，理解插件和执行链。
• 通过插件参考查找具体能力和参数。
• 上线前完成运维与故障排查中的部署检查。