mosdns/README.md

YLTX-MosDNS - 智能防污染 DNS 服务器

基于 MosDNS v5 的增强版本 - 专注于智能防污染和易用性

功能特性 | 快速开始 | 文档 | 部署方式

---

🌟 项目简介

YLTX-MosDNS 是基于 MosDNS v5 的二次开发版本，在保留原有强大功能的基础上，增加了：

• 🛡️ 智能防污染系统 - 自动检测和切换 DNS，解决 DNS 污染问题
• 🎨 Web 管理界面 - Vue 3 可视化管理，无需编辑配置文件
• 🔄 配置热加载 - 零停机更新配置，服务不中断
• ⚡ 一键部署 - init 命令自动初始化，3 步快速启动
• 🧠 智能拓扑排序 - 自动分析插件依赖，支持任意配置顺序
• 📡 MikroTik 集成优化 - 自动同步 DNS 解析到路由器地址列表

适用场景: 家庭/办公室网络、VPS、软路由、树莓派、NAS

---

✨ 功能特性

🛡️ 智能防污染系统

核心功能: 自动检测 DNS 污染并切换上游

plugins:
  - tag: smart_fallback
    type: smart_fallback
    args:
      primary: forward_local      # 主上游（国内DNS）
      secondary: forward_remote   # 备用上游（国外DNS）
      china_ip: ["./data/chn_ip.txt"]  # CN IP 地址表
      timeout: 3000              # 超时时间（毫秒）
      verbose: true              # 详细日志

工作原理:

1. 优先使用国内 DNS 查询（速度快）
2. 检测返回的 IP 是否为国内 IP
3. 如果是污染 IP，自动切换到国外 DNS
4. 支持并行/顺序两种模式

🎨 Web 管理界面

特性:

• ✅ Vue 3 + TypeScript + Element Plus
• ✅ 实时监控 DNS 查询统计
• ✅ 可视化规则管理（添加/编辑/删除）
• ✅ 插件状态监控
• ✅ 配置文件在线编辑
• ✅ 一键热加载配置

访问地址: http://localhost:5555

🔄 配置热加载

零停机更新配置 - 无需重启服务

# 方式1: Web 界面点击"热加载配置"按钮
# 方式2: API 调用
curl -X POST http://localhost:5555/api/config/reload

特性:

• ✅ 自动验证新配置
• ✅ 失败自动回滚
• ✅ 保持 DNS 服务不中断
• ✅ 详细的加载日志

⚡ 一键部署 (init 命令)

3 步快速启动:

# 1. 初始化配置
./mosdns-linux-amd64 init

# 2. 修改端口（可选，非 root 用户）
sed -i 's/:53/:5310/g' config.yaml

# 3. 启动服务
./mosdns-linux-amd64 start -c config.yaml

自动生成:

• ✅ 完整的 config.yaml 配置文件
• ✅ 目录结构（data/, config.d/rules/, logs/）
• ✅ 示例数据文件（CN IP、域名列表）

🧠 智能拓扑排序

自动分析插件依赖关系 - 支持任意配置顺序

# ✅ 无需关心插件顺序，自动排序
plugins:
  - tag: udp_server      # 依赖 main
  - tag: main            # 依赖 cache, forward
  - tag: cache           # 无依赖
  - tag: forward         # 无依赖

特性:

• ✅ 自动检测 $plugin_name 引用
• ✅ 识别 entry: 字段依赖
• ✅ 循环依赖检测
• ✅ 详细错误提示

📡 MikroTik 集成

自动同步 DNS 解析到 MikroTik 路由器

plugins:
  - tag: mikrotik_sync
    type: mikrotik_addresslist
    args:
      host: "192.168.1.1"
      username: "admin"
      password: "password"
      address_list: "blocked_sites"
      mask: 32                # 单 IP 精确匹配
      max_ips: 10000          # 最大 IP 数量
      cache_ttl: 3600         # 缓存时间

应用场景:

• 🎯 自动添加特定域名的 IP 到地址列表
• 🎯 配合 MikroTik 防火墙规则
• 🎯 实现智能分流（游戏加速、广告拦截等）

🔌 完整的 RESTful API

管理接口: http://localhost:8080

端点	方法	说明
/api/server/info	GET	服务器信息
/api/plugins	GET	插件列表
/api/rules	GET/POST/PUT/DELETE	规则管理
/api/config/reload	POST	热加载配置
/api/cache/stats	GET	缓存统计
/api/cache/flush	POST	清空缓存

示例:

# 查看服务器状态
curl http://localhost:8080/api/server/info | jq

# 热加载配置
curl -X POST http://localhost:5555/api/config/reload

---

🚀 快速开始

方式 1: 一键部署（推荐）

# 1. 下载程序
wget https://git.ylcomm.cn/dengxiongjian/mosdns/releases/latest/download/mosdns-linux-amd64
chmod +x mosdns-linux-amd64

# 2. 初始化
./mosdns-linux-amd64 init

# 3. 启动（非 root 用户修改端口）
sed -i 's/:53/:5310/g' config.yaml
./mosdns-linux-amd64 start -c config.yaml

完成！ 访问:

• Web UI: http://localhost:5555
• API: http://localhost:8080
• DNS: localhost:53 (或 5310)

方式 2: systemd 服务

# 1. 复制程序到系统目录
sudo cp mosdns-linux-amd64 /usr/local/bin/mosdns
sudo chmod +x /usr/local/bin/mosdns

# 2. 创建配置目录
sudo mkdir -p /etc/mosdns
cd /etc/mosdns
sudo mosdns init

# 3. 创建 systemd 服务
sudo tee /etc/systemd/system/mosdns.service > /dev/null <<EOF
[Unit]
Description=MosDNS DNS Server
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/etc/mosdns
ExecStart=/usr/local/bin/mosdns start -c config.yaml
Restart=on-failure
RestartSec=5s

[Install]
WantedBy=multi-user.target
EOF

# 4. 启动服务
sudo systemctl daemon-reload
sudo systemctl enable mosdns
sudo systemctl start mosdns

方式 3: Docker 容器

# 构建镜像
docker build -t mosdns:latest .

# 运行容器
docker run -d \
  --name mosdns \
  -p 53:53/udp \
  -p 53:53/tcp \
  -p 5555:5555 \
  -p 8080:8080 \
  -v $(pwd)/config.yaml:/opt/mosdns/config.yaml \
  mosdns:latest

---

📦 下载

预编译版本

平台	架构	下载
Linux	AMD64	mosdns-linux-amd64
Linux	ARM64	mosdns-linux-arm64
Windows	AMD64	mosdns-windows-amd64.exe
macOS	Intel	mosdns-darwin-amd64
macOS	Apple Silicon	mosdns-darwin-arm64

从源码构建

# 克隆仓库
git clone https://git.ylcomm.cn/dengxiongjian/mosdns.git
cd mosdns

# 构建（交互式菜单）
bash build-all-platforms.sh

# 或直接编译当前平台
go build -o dist/mosdns .

---

📚 文档

核心文档

• 📖 一键部署指南 - 快速开始
• 📖 快速部署指南 - 完整部署流程
• 📖 init 命令说明 - 初始化命令详解
• 📖 构建脚本使用 - 编译指南
• 📖 架构设计文档 - 技术架构

配置示例

config.yaml              # 标准配置（智能防污染）
config-working.yaml      # 简化配置（快速测试）

API 文档

访问 Web UI 查看完整 API 文档: http://localhost:5555/api/docs

---

🎯 使用场景

场景 1: 家庭/办公室智能 DNS

# 自动识别国内外域名，智能分流
- 国内域名 → 国内 DNS（阿里云/腾讯云）
- 国外域名 → 国外 DNS（Cloudflare/Google）
- 自动防污染检测

场景 2: 软路由/NAS 部署

# 配合 MikroTik/OpenWrt
- DNS 解析
- 地址列表同步
- 智能分流
- 广告拦截

场景 3: VPS 公共 DNS 服务

# 高性能公共 DNS
- 智能缓存
- 防污染
- 多上游支持
- API 管理

---

🔧 配置说明

基础配置结构

# 日志
log:
  level: info

# API 接口
api:
  http: "0.0.0.0:8080"

# Web 管理界面
web:
  http: "0.0.0.0:5555"

# 插件列表
plugins:
  - tag: plugin_name
    type: plugin_type
    args:
      key: value

常用插件

插件类型	说明	示例
ip_set	IP 地址匹配	geoip_cn
domain_set	域名匹配	geosite_cn
forward	DNS 上游	forward_local
cache	DNS 缓存	main_cache
smart_fallback	智能防污染	smart_fallback
sequence	执行序列	main
mikrotik_addresslist	MikroTik 同步	mikrotik_sync
udp_server	UDP 服务器	udp_server
tcp_server	TCP 服务器	tcp_server

---

🛠️ 故障排查

常见问题

Q: 端口 53 绑定失败？

# 需要 root 权限
sudo ./mosdns start -c config.yaml

# 或修改为非特权端口
sed -i 's/:53/:5310/g' config.yaml

Q: 配置文件已存在？

# 强制重新初始化
./mosdns init --force

Q: Web UI 无法访问？

# 检查端口是否被占用
sudo lsof -i :5555

# 检查防火墙
sudo ufw allow 5555/tcp

Q: DNS 解析失败？

# 查看日志
journalctl -u mosdns -f

# 测试 DNS
dig @localhost -p 5310 baidu.com

---

📊 性能指标

指标	数值
启动时间	< 2 秒
内存占用	30-50 MB（空载）
DNS 延迟	20-30ms（国内）, 80-120ms（防污染）
缓存命中率	85%+
并发能力	3000+ qps（单核）
二进制大小	~26 MB（包含 Web UI）

---

🤝 贡献

欢迎贡献代码！请遵循以下步骤：

1. Fork 本仓库
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 开启 Pull Request

代码规范:

• 遵循 Go 语言规范
• 添加必要的测试
• 更新相关文档
• 每行代码添加中文注释

---

📄 许可证

本项目基于 MosDNS 进行二次开发

• 原项目: GPL v3 License
• 二次开发: GPL v3 License

详见 LICENSE 文件。

---

🙏 致谢

• 感谢 IrineSistiana 创建的原始 MosDNS 项目
• 感谢所有开源社区的贡献者

---

📞 联系方式

• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

⭐ 如果这个项目对你有帮助，请给个 Star！⭐

🌟 Star this project if it helps you! 🌟

Made with ❤️ by YLTX Team