Numa 是一款以单一二进制文件形式发布的便携式 DNS 解析器。它将本地开发域名映射、临时 DNS 覆盖、广告过滤以及加密查询等功能集中于一体。
该工具完全在本地设备上运行，无需依赖云账户或额外的硬件（如 Raspberry Pi）。其核心代码使用 Rust 从头构建，未依赖现成的 DNS 库，底层的 DNS 线协议解析器均为手写实现，后续代码则由 AI 辅助起草并经人工严格审查，以确保运行效率与安全性。
核心架构与隐私保护机制
Numa 默认集成 Hagezi Pro 规则列表，用于屏蔽广告与跟踪器，并支持每日自动刷新。为满足不同网络环境的需求，它提供了四种可配置的解析模式：
- Forward（转发模式，默认）：将请求转发至现有的系统 DNS，在此基础上叠加本地缓存与广告屏蔽功能。此模式可确保强制门户、VPN 及企业 DNS 策略继续正常工作。
- Recursive（递归模式）：直接从根服务器发起解析。此模式下没有单一的上游解析器能够掌握用户的全部查询记录。若需验证解析结果的真实性，可手动开启 DNSSEC 验证。
- Auto（自动模式）：启动时自动探测根服务器。若根服务器响应，则使用递归解析；若无响应，则回退至通过 DoH 转发至 Quad9，若 Quad9 失败则重试 Cloudflare。
- ODoH（隐匿 DNS-over-HTTPS，RFC 9230）：利用 HPKE 技术对每个查询进行加密，并通过中继节点转发。中继节点仅能看到用户的 IP 和密文，而目标服务器仅能看到查询内容与中继的 IP。这种设计切断了查询者与查询内容之间的关联，且 Numa 会拒绝共享可注册域的中继和目标，以防止元数据泄露。
灵活部署：从容器测试到系统级接管
Numa 提供了多种部署路径，用户可根据实际需求选择最合适的运行方式。
1. Docker 隔离运行（推荐用于测试）
无需在主机安装任何文件，即可体验完整功能。通过映射 5553 端口可避免与主机现有的 53 端口冲突。
docker run -d --name numa -p 127.0.0.1:5553:53/udp -p 127.0.0.1:5553:53/tcp -p 127.0.0.1:5380:5380 ghcr.io/razvandimescu/numa
运行后可通过 dig @127.0.0.1 -p 5553 example.com 进行测试，并使用 docker exec numa numa token 获取 API Token 以登录本地仪表板（http://localhost:5380）。
2. 前台运行（不改变系统 DNS）
通过包管理器（如 macOS 的 Homebrew、Arch 的 pacman 或 Cargo）安装二进制文件后，可直接在前台运行。
sudo numa
此模式下，系统原有的 DNS 设置保持不变，但局域网内的其他设备仍可向 Numa 发起查询。用户可通过配置文件中的 [server] allow_from 限制允许查询的网络范围。
3. 系统级 DNS 接管
通过 numa install 命令，Numa 会注册系统服务、将系统 DNS 指向自身，并将本地 CA 证书添加至系统信任存储。
- macOS / Linux：需使用
sudo numa install。在 Linux 环境下，该命令会通过 drop-in 文件重新配置 systemd-resolved。 - Windows：需以管理员身份运行
numa install并重启设备。
安装完成后，访问 http://numa.numa 若可正常加载仪表板，即表示接管成功。升级时只需更新二进制文件并重新运行 install 命令，原有的 Token 和 CA 证书将被保留。
移动端支持与加密通信
Numa 支持作为 DNS-over-TLS (DoT, RFC 7858) 服务器运行，监听 853 端口，为 iOS Private DNS、systemd-resolved 或 stubby 等客户端提供加密查询服务。
- 证书管理：默认采用自签名模式，
numa install会自动将本地 CA 添加至主流操作系统的信任存储中。用户也可选择自带公开信任的证书（如通过 Let’s Encrypt 获取），以便客户端无需额外配置即可连接。 - 移动端快捷配置：在配置文件中启用
[mobile] enabled = true并重启服务后，在同一局域网内的手机上运行numa setup-phone。该命令会生成一个 QR 码，手机扫码后即可自动完成 TLS DNS 的配置流程。
与主流 DNS 方案的横向对比
与 Pi-hole、AdGuard Home 和 Unbound 等传统方案相比，Numa 在特定工程场景下具有差异化优势，但也明确了自身的能力边界。
Numa 的独有特性：
- 支持本地服务代理与自动 TLS（提供 .numa 域名、HTTPS 及 WebSocket 支持）。
- 内置 mDNS 支持，可实现局域网服务发现（通过
numa lan on开启）。 - 提供带自动回滚机制的 REST API，便于脚本化临时覆盖主机名。
- 支持请求对冲（Request Hedging），可并行向上游发起 UDP、DoH、DoT 查询以降低延迟。
- 支持 Serve-stale 与预取机制（RFC 8767），在上游不可用时提供缓存的过期记录。
Numa 明确不提供的功能：
- 不提供 DHCP 服务器功能。
- 不支持多实例集群或实例间的配置自动同步。
- 大多数高级设置需通过配置文件（numa.toml）完成，而非完全依赖 Web 管理 UI。
数据清理与系统痕迹移除
执行 numa uninstall 会恢复系统原有的 DNS 设置，但会保留数据目录，以便重新安装时复用相同的 Token 和 CA 证书。
若需彻底移除所有痕迹，需在卸载后手动删除以下路径：
- macOS：二进制文件、
/usr/local/var/numa目录及/usr/local/var/log/numa.log。 - Linux：二进制文件（含
/usr/local/bin/numa副本）及/var/lib/numa目录。 - Windows：二进制文件及
%PROGRAMDATA%\numa目录。 - iPhone：进入“设置 → 通用 → VPN 与设备管理”，移除“Numa DNS”配置文件。
此外，若曾创建用户级配置文件或自定义了 [server] data_dir，也需手动清理对应的 ~/.config/numa 或指定路径。
