# 🚀 MosDNS 一键部署

> 在任意服务器上 3 步快速部署智能 DNS 服务器

---

## 💡 核心特性

✅ **一键初始化** - 自动生成配置文件和目录结构  
✅ **零配置门槛** - 无需手动编写 YAML 配置  
✅ **智能保护** - 自动检测已有文件，避免误删  
✅ **完整指引** - 提供详细的后续操作说明  
✅ **跨平台支持** - Linux/Windows/macOS/ARM 全平台  

---

## 🎯 快速开始（3步部署）

### 第 1 步：下载程序
```bash
# 下载最新版本
wget https://github.com/your-repo/mosdns/releases/latest/download/mosdns-linux-amd64
chmod +x mosdns-linux-amd64
```

### 第 2 步：初始化配置
```bash
# 运行 init 命令
./mosdns-linux-amd64 init
```

**输出示例：**
```
========================================
  🚀 MosDNS 初始化向导
========================================

✅ 配置文件已创建: config.yaml
📁 创建目录结构...
   ✅ ./data
   ✅ ./config.d
   ✅ ./config.d/rules
   ✅ ./logs
📄 检查数据文件...
   ✅ 已创建: ./data/chn_ip.txt
   ✅ 已创建: ./data/geosite_china-list.txt

========================================
  🎉 初始化完成！
========================================
```

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

# 或使用 root 权限（使用默认端口 53）
sudo ./mosdns-linux-amd64 start -c config.yaml
```

**🎉 完成！** 现在可以访问：
- Web 管理界面: http://localhost:5555
- API 接口: http://localhost:8080
- DNS 服务: localhost:53 (或 5310)

---

## 📁 生成的文件结构

```
.
├── mosdns-linux-amd64          # 可执行文件
├── config.yaml                 # 主配置文件 ⭐
├── data/                       # 数据文件目录
│   ├── chn_ip.txt             # CN IP 地址段（示例）
│   └── geosite_china-list.txt # CN 域名列表（示例）
├── config.d/                   # 配置目录
│   └── rules/                  # 规则文件目录（空）
├── logs/                       # 日志目录
└── cache.dump                  # DNS 缓存（运行后生成）
```

---

## ⚙️ init 命令详解

### 基本语法
```bash
./mosdns-linux-amd64 init [flags]
```

### 可用参数
| 参数 | 短参数 | 说明 |
|------|--------|------|
| `--force` | `-f` | 强制覆盖已存在的配置文件 |
| `--help` | `-h` | 显示帮助信息 |

### 使用示例

**1. 首次初始化**
```bash
./mosdns-linux-amd64 init
```

**2. 强制重新初始化（覆盖配置）**
```bash
./mosdns-linux-amd64 init --force
```

**3. 在指定目录初始化**
```bash
mkdir /opt/mosdns && cd /opt/mosdns
./mosdns-linux-amd64 init
```

---

## 🔧 配置说明

### 生成的 config.yaml 包含：

| 配置项 | 说明 | 默认值 |
|--------|------|--------|
| **日志** | 日志级别和文件 | level: info |
| **API** | 管理接口地址 | 0.0.0.0:8080 |
| **Web UI** | Web 管理界面 | 0.0.0.0:5555 |
| **国内 DNS** | 阿里云/腾讯云 DNS | 223.5.5.5, 119.29.29.29 |
| **国外 DNS** | Cloudflare/Google DoH | 1.1.1.1, 8.8.8.8 |
| **缓存** | DNS 缓存配置 | 10万条目 |
| **DNS 服务器** | UDP/TCP 监听 | :53 |

### 常用修改

**修改 DNS 端口（非 root）：**
```bash
sed -i 's/:53/:5310/g' config.yaml
```

**修改 Web UI 端口：**
```bash
sed -i 's/5555/8888/g' config.yaml
```

**修改 API 端口：**
```bash
sed -i 's/8080/9090/g' config.yaml
```

---

## 🌐 部署场景

### 场景 1: 家庭/办公室 DNS 服务器

```bash
# 1. 初始化
./mosdns-linux-amd64 init

# 2. 下载完整数据（可选）
wget -O data/chn_ip.txt \
  https://raw.githubusercontent.com/17mon/china_ip_list/master/china_ip_list.txt

# 3. 启动（需 root）
sudo ./mosdns-linux-amd64 start -c config.yaml

# 4. 配置路由器 DNS 为服务器 IP
```

### 场景 2: VPS/云服务器

```bash
# 1. SSH 登录
ssh user@your-server

# 2. 创建工作目录
mkdir -p /opt/mosdns && cd /opt/mosdns

# 3. 下载并初始化
wget https://github.com/.../mosdns-linux-amd64
chmod +x mosdns-linux-amd64
./mosdns-linux-amd64 init

# 4. 配置 systemd 服务（见下文）
```

### 场景 3: Docker 容器

**Dockerfile:**
```dockerfile
FROM debian:12-slim

# 安装依赖
RUN apt-get update && apt-get install -y ca-certificates && rm -rf /var/lib/apt/lists/*

# 复制程序
COPY mosdns-linux-amd64 /usr/local/bin/mosdns
RUN chmod +x /usr/local/bin/mosdns

# 初始化配置
WORKDIR /opt/mosdns
RUN mosdns init

# 暴露端口
EXPOSE 53/udp 53/tcp 5555/tcp 8080/tcp

# 启动服务
CMD ["mosdns", "start", "-c", "config.yaml"]
```

**构建并运行：**
```bash
docker build -t mosdns:latest .
docker run -d -p 53:53/udp -p 53:53/tcp -p 5555:5555 -p 8080:8080 mosdns:latest
```

---

## 🔄 生产环境部署

### 使用 systemd 管理服务

**1. 创建服务文件：**
```bash
sudo tee /etc/systemd/system/mosdns.service > /dev/null <<EOF
[Unit]
Description=MosDNS DNS Server
Documentation=https://github.com/your-repo/mosdns
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/opt/mosdns
ExecStart=/opt/mosdns/mosdns-linux-amd64 start -c config.yaml
Restart=on-failure
RestartSec=5s

# 安全加固
NoNewPrivileges=true
PrivateTmp=true

[Install]
WantedBy=multi-user.target
EOF
```

**2. 启动并启用服务：**
```bash
sudo systemctl daemon-reload
sudo systemctl enable mosdns
sudo systemctl start mosdns
```

**3. 管理服务：**
```bash
sudo systemctl status mosdns    # 查看状态
sudo systemctl stop mosdns      # 停止服务
sudo systemctl restart mosdns   # 重启服务
journalctl -u mosdns -f         # 查看日志
```

---

## ✅ 验证部署

### 1. 检查服务状态
```bash
sudo systemctl status mosdns
```

### 2. 测试 DNS 解析
```bash
# 国内域名
dig @127.0.0.1 -p 5310 baidu.com

# 国外域名
dig @127.0.0.1 -p 5310 google.com
```

### 3. 访问 Web 界面
浏览器打开: http://服务器IP:5555

### 4. 测试 API
```bash
curl http://localhost:8080/api/server/info | jq
```

---

## 📚 高级功能

### 热加载配置（无需重启）
```bash
curl -X POST http://localhost:5555/api/config/reload
```

### 查看缓存统计
```bash
curl http://localhost:8080/api/cache/stats | jq
```

### 清空 DNS 缓存
```bash
curl -X POST http://localhost:8080/api/cache/flush
```

### 添加自定义规则
通过 Web 界面 → 规则管理 → 添加规则

---

## 🛠️ 故障排查

### 问题 1: 端口被占用
```
bind: address already in use
```

**解决：**
```bash
# 检查占用端口的进程
sudo lsof -i :53
sudo lsof -i :5555

# 修改配置文件端口
sed -i 's/:53/:5310/g' config.yaml
```

### 问题 2: 权限不足
```
bind: permission denied
```

**解决：**
```bash
# 使用 sudo 运行
sudo ./mosdns-linux-amd64 start -c config.yaml

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

### 问题 3: 配置文件已存在
```
⚠️  配置文件已存在: config.yaml
```

**解决：**
```bash
# 方式1: 备份后重新初始化
mv config.yaml config.yaml.bak
./mosdns-linux-amd64 init

# 方式2: 强制覆盖
./mosdns-linux-amd64 init --force
```

---

## 📖 相关文档

- [快速部署指南](./快速部署指南.md) - 完整部署流程
- [init 功能说明](./init功能说明.md) - 命令详细说明
- [YLTX-DNS 二次开发总结](./YLTX-DNS智能防污染系统-二次开发总结.md) - 项目总结

---

## 💡 小贴士

1. **定期更新数据文件**
   ```bash
   # 更新 CN IP 列表
   wget -O data/chn_ip.txt \
     https://raw.githubusercontent.com/17mon/china_ip_list/master/china_ip_list.txt
   
   # 热加载配置
   curl -X POST http://localhost:5555/api/config/reload
   ```

2. **监控服务运行**
   ```bash
   # 实时日志
   journalctl -u mosdns -f
   
   # 服务状态
   curl http://localhost:8080/api/server/info
   ```

3. **备份配置**
   ```bash
   tar -czf mosdns-backup-$(date +%Y%m%d).tar.gz \
     config.yaml data/ config.d/
   ```

---

**🎉 恭喜！您已成功部署 MosDNS 智能 DNS 服务器！**

*如有问题，请访问 [GitHub Issues](https://github.com/your-repo/mosdns/issues)*