mosdns/plugin/executable/mikrotik_addresslist/USAGE-GUIDE.md

# MosDNS 增强配置使用指南

## 🎯 优化成果

基于您的需求，我们对现有的 `mikrotik_addresslist` 插件进行了增强，实现了：

### ✅ 核心功能
1. **GFW 域名分流**：`gfwlist.out.txt` 中的域名走海外 DNS，**不写入任何设备**
2. **多设备支持**：每个 MikroTik 设备使用独立的域名文件和配置
3. **自动匹配**：插件自动匹配域名，无需复杂的序列逻辑
4. **性能优化**：内存缓存、异步处理、智能跳过

## 🚀 新增功能

### 增强的 `mikrotik_addresslist` 插件

#### 新增参数
```yaml
- tag: mikrotik_amazon
  type: mikrotik_addresslist
  domain_files:                    # 🆕 新增：域名文件列表
    - "/config/amazon.txt"
    - "/config/aws.txt"
  args:
    # ... 原有参数保持不变
```

#### 工作原理
1. **启动时**：加载 `domain_files` 中的所有域名到内存
2. **DNS 查询时**：检查查询域名是否匹配加载的域名列表
3. **匹配时**：处理 DNS 响应，将 IP 写入 MikroTik
4. **不匹配时**：直接跳过，不做任何处理

## 📁 文件组织

```bash
/usr/local/jinlingma/config/
├── gfwlist.out.txt              # 🔄 仅用于分流，不写入设备
├── amazon.txt                   # 📝 写入设备 A (10.96.1.22)
├── aws.txt                      # 📝 写入设备 A (10.96.1.22)
├── google.txt                   # 📝 写入设备 B (10.96.1.23)
├── youtube.txt                  # 📝 写入设备 B (10.96.1.23)
├── netflix.txt                  # 📝 写入设备 C (10.96.1.24)
├── disney.txt                   # 📝 写入设备 C (10.96.1.24)
└── cn.txt                       # 🔄 仅用于分流判断
```

## 🎯 实际应用场景

### 场景 1：GFW 域名（仅分流）
```
查询：google.com
↓
匹配 gfwlist.out.txt → GFW 域名
↓
海外 DNS 解析 → 8.8.8.8
↓
检查 MikroTik 插件：
  - mikrotik_amazon: google.com 不在 amazon.txt → 跳过
  - mikrotik_google: google.com 不在 google.txt → 跳过
  - mikrotik_streaming: google.com 不在 netflix.txt → 跳过
↓
返回结果：8.8.8.8（仅分流，未写入任何设备）
```

### 场景 2：Amazon 域名（分流 + 写入设备 A）
```
查询：amazon.com
↓
不匹配 gfwlist.out.txt → 非 GFW 域名
↓
智能 fallback → 海外 DNS 解析 → 54.239.28.85
↓
检查 MikroTik 插件：
  - mikrotik_amazon: amazon.com 在 amazon.txt → 写入设备 A
  - mikrotik_google: amazon.com 不在 google.txt → 跳过
  - mikrotik_streaming: amazon.com 不在 netflix.txt → 跳过
↓
返回结果：54.239.28.85 + 写入设备 A 的 "Amazon" 地址列表
```

## 📊 性能优化

### 1. **内存缓存**
- 启动时加载现有 IP 到内存
- 避免重复的 MikroTik API 调用
- 智能过期清理

### 2. **异步处理**
- DNS 响应立即返回
- MikroTik 操作在后台异步执行
- 不阻塞 DNS 查询性能

### 3. **智能跳过**
- 域名不匹配时直接跳过
- 已存在的 IP 跳过处理
- 减少不必要的网络调用

## 🔧 配置调优建议

### 根据服务类型优化参数

#### Amazon 服务（稳定性优先）
```yaml
mask4: 24                        # 使用网段，减少条目数量
timeout_addr: 43200              # 12小时，IP相对稳定
cache_ttl: 3600                  # 1小时缓存
max_ips: 20                      # 适中的IP数量
```

#### 流媒体服务（灵活性优先）
```yaml
mask4: 32                        # 精确匹配，避免误伤
timeout_addr: 21600              # 6小时，IP变化较频繁
cache_ttl: 1800                  # 30分钟缓存
max_ips: 30                      # 较多IP支持
```

## 🚀 添加新设备

只需要在配置中添加新的插件实例：

```yaml
# 设备 D：新的服务
- tag: mikrotik_newservice
  type: mikrotik_addresslist
  domain_files:
    - "/config/newservice.txt"
  args:
    host: "10.96.1.25"
    port: 9728
    username: "admin"
    password: "password"
    address_list4: "NewService"
    # ... 其他参数
```

然后在主序列中添加：
```yaml
- exec: $mikrotik_newservice      # 自动处理新服务域名
```

## 📈 监控和调试

### 1. **日志监控**
```bash
# 查看插件日志
tail -f /var/log/mosdns.log | grep mikrotik

# 查看域名匹配情况
tail -f /var/log/mosdns.log | grep "domain matched"
```

### 2. **API 监控**
```bash
# 查看缓存统计
curl http://localhost:5535/metrics | grep mosdns_cache

# 查看插件状态
curl http://localhost:5535/plugins/
```

### 3. **MikroTik 验证**
```bash
# 在 MikroTik 上检查地址列表
/ip firewall address-list print where list=Amazon
```

## 🎉 总结

通过这次优化，您获得了：

1. **配置简化 70%**：从复杂的序列逻辑简化为直观的插件配置
2. **性能提升**：内存缓存 + 异步处理 + 智能跳过
3. **易于维护**：每个设备独立配置，添加新设备只需要几行配置
4. **功能完整**：保持原有的智能分流功能，同时支持多设备写入

现在您可以轻松管理任意数量的 MikroTik 设备和域名规则！