TDNS

外观

14 - CLI 管理工具 ​

概述 ​

TDNS 提供两个命令行工具：

工具功能说明
tdnsDNS 服务器主程序启动服务、配置验证
tdnsctl管理控制工具远程管理运行中的 TDNS 实例

tdns — 服务器主程序 ​

用法 ​

bash
tdns [OPTIONS]

参数 ​

参数短选项类型默认值说明
--config-c路径etc/tdns.toml配置文件路径
--validateflagfalse仅验证配置，不启动服务
--log-level字符串配置中的值覆盖日志级别
--root-hints路径无覆盖 root.hints 文件路径

配置验证 ​

启动前验证配置文件，检查语法和逻辑：

bash
tdns --validate --config /etc/tdns/tdns.toml

验证通过输出：

configuration is valid: /etc/tdns/tdns.toml

验证失败输出错误信息并返回非零退出码。

启动服务 ​

bash
# 使用默认配置
tdns

# 指定配置文件
tdns --config /etc/tdns/tdns.toml

# 指定配置 + 日志级别
tdns --config /etc/tdns/tdns.toml --log-level debug

# 指定 root.hints（递归模式）
tdns --config /etc/tdns/tdns.toml --root-hints /etc/tdns/root.hints

日志级别 ​

级别说明适用场景
error仅错误生产环境
warn警告 + 错误生产环境
info常规信息生产环境（默认）
debug调试信息测试/排障
trace全量追踪深度排障

--log-level 参数覆盖配置文件中的 [server] log-level 设置，用于临时调试。

root-hints 查找顺序 ​

递归模式下，root.hints 文件的查找优先级：

  1. --root-hints <path> CLI 参数（最高）
  2. <working-directory>/root.hints（如 /var/lib/tdns/root.hints）
  3. etc/root.hints（相对于当前工作目录）

信号处理 ​

信号行为
SIGINT (Ctrl+C)优雅关闭：停止接受新连接，等待活跃连接完成
SIGTERM优雅关闭（同 SIGINT）
SIGHUP热重载：重新读取配置和 Zone 文件
bash
# 优雅关闭
sudo kill -TERM $(cat /var/run/tdns/tdns.pid)

# 热重载
sudo kill -HUP $(cat /var/run/tdns/tdns.pid)

tdnsctl — 管理控制工具 ​

tdnsctl 通过 REST API 远程管理运行中的 TDNS 实例。

全局参数 ​

参数说明默认值
--apiTDNS API 端点http://127.0.0.1:8080
--tokenAPI Bearer Token从环境变量 TDNS_API_TOKEN 读取

Token 认证 ​

通过环境变量传递 Token（推荐）：

bash
export TDNS_API_TOKEN="your-secure-token"
tdnsctl status

通过命令行参数传递：

bash
tdnsctl --token "your-secure-token" status

子命令总览 ​

子命令功能
status查看服务器状态
stats缓存统计
flush清空全部缓存
flush-name <name>清空指定域名缓存
reload热重载配置和区域
validate [config]验证配置文件

status — 查看服务器状态 ​

bash
tdnsctl status
# 远程管理
tdnsctl --api http://10.0.0.1:8080 --token mytoken status

输出示例：

TDNS Server Status
  Version:    0.1.1
  Mode:       Hybrid
  Port:       53
  Uptime:     86400s
  Zones:      3
  Cache:      true
  Recursion:  true
  Forwarders: 8.8.8.8, 1.1.1.1

stats — 缓存统计 ​

bash
tdnsctl stats

输出示例：

Cache Statistics
  Hits:      85234
  Misses:    14766
  Inserts:   15000
  Evictions: 234
  Hit rate:  85.2%
  Positive:  12000
  Negative:  3000

flush — 清空全部缓存 ​

bash
tdnsctl flush

输出示例：

Cache flushed
  Positive: 12000
  Negative: 3000

flush-name — 清空指定域名缓存 ​

bash
tdnsctl flush-name www.example.com

输出示例：

Flushed cache for: www.example.com

reload — 热重载配置和区域 ​

bash
tdnsctl reload

输出示例：

Configuration reloaded
  Zones reloaded: 3

validate — 验证配置文件 ​

bash
# 验证默认配置
tdnsctl validate

# 验证指定文件
tdnsctl validate /etc/tdns/tdns.toml

验证通过：

configuration is valid: etc/tdns.toml

验证失败：

configuration validation failed: recursion enabled but allow-recursion is empty

常用操作流程 ​

验证并启动 ​

bash
# 1. 验证配置
tdns --validate --config /etc/tdns/tdns.toml

# 2. 验证通过后启动
tdns --config /etc/tdns/tdns.toml

修改配置后热重载 ​

bash
# 1. 先验证新配置
tdnsctl validate /etc/tdns/tdns.toml

# 2. 热重载（不中断服务）
tdnsctl reload

# 3. 确认状态
tdnsctl status

排障流程 ​

bash
# 1. 检查服务器状态
tdnsctl status

# 2. 检查缓存命中率
tdnsctl stats

# 3. 如果缓存污染，清空缓存
tdnsctl flush

# 4. 查看特定域名缓存并清理
tdnsctl flush-name problem-domain.com

# 5. 重新加载配置
tdnsctl reload

远程管理 ​

bash
# 管理远程 TDNS 实例
tdnsctl --api http://10.0.0.1:8080 --token "$TDNS_API_TOKEN" status
tdnsctl --api http://10.0.0.1:8080 reload
tdnsctl --api http://10.0.0.1:8080 flush-name bad-record.example.com

自动化脚本示例 ​

bash
#!/bin/bash
# deploy-zone.sh — 部署 Zone 文件后自动重载

set -euo pipefail

ZONE_FILE="$1"
ZONE_NAME="$2"

# 复制 Zone 文件
cp "$ZONE_FILE" "/etc/tdns/zones/${ZONE_NAME}.zone"

# 验证配置
tdnsctl validate /etc/tdns/tdns.toml

# 热重载
tdnsctl reload

# 确认
echo "Zone $ZONE_NAME deployed and reloaded"
tdnsctl status

编译安装 ​

bash
# 编译 tdns 和 tdnsctl
cargo build --release

# 安装到系统路径
sudo cp target/release/tdns /usr/local/bin/
sudo cp target/release/tdnsctl /usr/local/bin/

# 验证安装
tdns --version
tdnsctl --version