03 - 安装指南

环境要求

项目	最低要求	推荐配置
操作系统	Linux (kernel ≥ 4.9)	Debian 12 / Ubuntu 22.04 / CentOS 8+
CPU	1 核	2 核+
内存	128 MB	512 MB+（高 QPS 场景 2 GB+）
磁盘	50 MB（二进制 + 配置）	1 GB+（含日志和 SQLite 存储）
Rust 工具链	≥ 1.75.0（仅编译时需要）	stable latest

Windows 和 macOS 平台可编译运行，但无内核态优化路径（如 io_uring/sendmmsg），性能上限低于 Linux。

---

方式一：一句话安装（推荐）

自动检测 curl / wget，下载并执行安装脚本，自动配置 systemd 服务并启动：

if [ -f /usr/bin/curl ];then curl -sSO https://tdns.taozi.pub/install.sh;else wget -O install.sh https://tdns.taozi.pub/install.sh;fi;sudo bash install.sh

安装脚本自动完成：编译/下载二进制 → 创建 tdns 用户 → 放置配置到 /etc/tdns/ → 注册 systemd 服务 → 授予 CAP_NET_BIND_SERVICE 以绑定 53 端口。安装完成后按提示编辑 /etc/tdns/tdns.toml 即可。

查看安装脚本支持的选项

sudo bash install.sh --help

常用选项：

选项	说明
--mode <mode>	指定运行模式（recursive/authoritative/forwarder/hybrid）
--port <port>	监听端口（默认 53）
--no-start	安装但不启动服务
--upgrade	升级已安装的 TDNS

---

方式二：Docker 安装

docker run -d --name tdns \
  --restart=unless-stopped \
  --cap-add=NET_BIND_SERVICE \
  -p 53:53/udp -p 53:53/tcp \
  -p 853:853 \
  -p 443:443 \
  -p 8080:8080 \
  -v /etc/tdns:/etc/tdns:ro \
  -v /var/lib/tdns:/var/lib/tdns \
  -e TDNS_API_TOKEN=your-secret \
  tdns/tdns:latest

853/443 端口仅在启用 DoT/DoH 时需要映射。Docker Compose 编排见 05-部署指南。

---

启动与验证

启动服务

# systemd 方式（推荐，自动授权 53 端口）
sudo systemctl start tdns

# 手动启动（绑定 53 端口需 root 或 CAP_NET_BIND_SERVICE）
sudo ./target/release/tdns --config /etc/tdns/tdns.toml

CLI 启动参数

参数	说明	默认值
-c, --config <PATH>	配置文件路径	etc/tdns.toml
--validate	仅验证配置文件，不启动服务	—
--log-level <LEVEL>	覆盖配置文件中的日志级别	—
--root-hints <PATH>	覆盖根提示文件路径	—

# 仅验证配置，不启动
tdns --config /etc/tdns/tdns.toml --validate

# 正常启动
tdns --config /etc/tdns/tdns.toml

# 指定 root.hints + 调试日志
tdns --config /etc/tdns/tdns.toml --root-hints /etc/tdns/root.hints --log-level debug

验证

# DNS 解析验证
dig @127.0.0.1 example.com

# 健康检查
curl http://127.0.0.1:8080/api/v1/health

# 查看服务状态（需启用 API）
tdnsctl status

---

环境变量覆盖

TDNS 支持通过环境变量覆盖配置文件中的部分值，容器化场景友好：

环境变量	覆盖的配置项	说明
TDNS_LISTEN_PORT	server.listen-port	覆盖监听端口
TDNS_LOG_LEVEL	server.log-level	覆盖日志级别
TDNS_API_TOKEN	api.auth-token	覆盖 API 认证令牌

# 容器环境中通过环境变量设置 API Token
export TDNS_API_TOKEN=my-secret-token
tdns --config /etc/tdns/tdns.toml

# tdnsctl 也可通过环境变量传递 Token
export TDNS_API_TOKEN=my-secret-token
tdnsctl status

---

下一步

• 配置文件怎么写 → 04-配置参考手册
• 生产环境怎么部署 → 05-部署指南
• 不确定选哪种模式 → 06-运行模式详解