Alex Yang
187 lines
6.4 KiB
Markdown
187 lines
6.4 KiB
Markdown
# 域名信息远程列表功能实施计划
|
||
|
||
## 概述
|
||
在 DNS 服务器的屏蔽管理系统中增加三类域名信息的远程异步加载功能，用于增强日志详情 API 和威胁告警 API 的域名信息查询能力。
|
||
|
||
## 需要添加的远程域名信息
|
||
|
||
### 1. 域名信息列表
|
||
- **URL**: `https://gitea.amazehome.xyz/AMAZEHOME/domain-info/raw/branch/main/domains/domain-info.json`
|
||
- **用途**: 用于查询日志详情 API 中的域名信息
|
||
- **格式**: JSON
|
||
|
||
### 2. 威胁告警域名列表
|
||
- **URL**: `https://gitea.amazehome.xyz/AMAZEHOME/domain-info/src/branch/main/threats/threats-database.csv`
|
||
- **用途**: 用于威胁告警 API 的威胁域名信息
|
||
- **格式**: CSV
|
||
|
||
### 3. 跟踪器域名列表
|
||
- **URLs**:
|
||
- `https://gitea.amazehome.xyz/AMAZEHOME/domain-info/raw/branch/main/tracker/trackers.json`
|
||
- **用途**: 用于查询日志详情 API 中的跟踪器信息
|
||
- **格式**: JSON
|
||
|
||
## 实施步骤
|
||
|
||
### 步骤 1: 扩展配置文件结构
|
||
1.1 在 `config/config.go` 中添加新的配置结构：
|
||
- `DomainInfoConfig` - 域名信息配置
|
||
- 包含三个远程列表的配置条目（类似 `BlacklistEntry`）
|
||
- 添加更新间隔、启用状态等配置项
|
||
|
||
1.2 在 `Config` 结构体中添加 `DomainInfo DomainInfoConfig` 字段
|
||
|
||
1.3 实现配置解析函数：
|
||
- `parseDomainInfoLists()` - 解析域名信息列表配置
|
||
- 支持 INI 格式配置
|
||
|
||
### 步骤 2: 创建域名信息管理器
|
||
2.1 创建新文件 `shield/domain_info_manager.go`
|
||
|
||
2.2 实现 `DomainInfoManager` 结构体：
|
||
- 存储域名信息数据（JSON 格式）
|
||
- 存储威胁域名数据（CSV 格式）
|
||
- 存储跟踪器数据（JSON 格式）
|
||
- 缓存管理和过期检查机制
|
||
- 异步加载和更新逻辑
|
||
|
||
2.3 实现核心方法：
|
||
- `LoadDomainInfo()` - 加载所有域名信息
|
||
- `fetchRemoteDomainInfo()` - 获取远程域名信息
|
||
- `fetchThreatDatabase()` - 获取威胁数据库
|
||
- `fetchTrackerInfo()` - 获取跟踪器信息
|
||
- `shouldUpdateCache()` - 检查缓存是否需要更新
|
||
- `GetDomainInfo(domain)` - 查询域名信息
|
||
- `GetThreatInfo(domain)` - 查询威胁信息
|
||
- `GetTrackerInfo(domain)` - 查询跟踪器信息
|
||
- `GetAllDomainInfo()` - 获取所有域名信息（用于 API）
|
||
|
||
2.4 实现缓存机制：
|
||
- 使用内存缓存存储加载的数据
|
||
- 定期后台刷新（根据配置的更新间隔）
|
||
- 支持手动刷新
|
||
|
||
### 步骤 3: 实现后端 API
|
||
3.1 在 `http/server.go` 中添加新的 API 路由：
|
||
- `/api/shield/domain-info` - 获取域名信息列表（GET）
|
||
- `/api/shield/domain-info/update` - 手动更新所有域名信息（POST）
|
||
- `/api/shield/domain-info/{type}/update` - 更新指定类型的域名信息（POST）
|
||
- `/api/domain/info` - 查询单个域名的详细信息（GET）
|
||
|
||
3.2 实现 API 处理函数：
|
||
- `handleDomainInfo()` - 处理域名信息列表的获取
|
||
- `handleUpdateDomainInfo()` - 处理手动更新请求
|
||
- `handleDomainInfoQuery()` - 处理域名信息查询
|
||
|
||
3.3 在服务器初始化时：
|
||
- 创建 `DomainInfoManager` 实例
|
||
- 启动后台定期更新任务
|
||
|
||
### 步骤 4: 实现前端界面
|
||
4.1 创建 `static/js/modules/domain-info.js` 模块：
|
||
- `loadDomainInfoLists()` - 加载域名信息列表
|
||
- `updateDomainInfo(type)` - 更新域名信息
|
||
- `renderDomainInfoLists()` - 渲染域名信息列表表格
|
||
- `showDomainInfoDetails()` - 显示域名信息详情
|
||
|
||
4.2 在 `static/js/shield.js` 中添加：
|
||
- `loadRemoteDomainInfoLists()` - 异步加载远程域名信息列表
|
||
- `updateDomainInfoListsTable()` - 更新域名信息列表 UI
|
||
- 添加状态指示器和通知逻辑
|
||
|
||
4.3 创建前端管理界面 `static/domain-info.html`（或集成到现有 shield.html）：
|
||
- 域名信息列表管理表格
|
||
- 显示各列表的状态、规则数量、最后更新时间
|
||
- 手动更新按钮
|
||
- 启用/禁用切换
|
||
|
||
### 步骤 5: 集成到日志详情 API
|
||
5.1 修改日志详情查询接口：
|
||
- 在返回的日志详情中添加域名信息字段
|
||
- 添加跟踪器信息字段
|
||
- 如果域名在威胁数据库中，添加威胁告警信息
|
||
|
||
5.2 优化查询性能：
|
||
- 使用缓存避免重复查询
|
||
- 批量查询优化
|
||
|
||
### 步骤 6: 集成到威胁告警 API
|
||
6.1 修改威胁告警查询接口：
|
||
- 使用远程威胁数据库进行匹配
|
||
- 返回威胁类型、风险等级等详细信息
|
||
|
||
### 步骤 7: 测试和文档
|
||
7.1 功能测试：
|
||
- 测试远程列表加载
|
||
- 测试缓存机制
|
||
- 测试 API 接口
|
||
- 测试前端界面
|
||
|
||
7.2 更新文档：
|
||
- 更新 README.md
|
||
- 添加配置示例
|
||
- 更新 API 文档
|
||
|
||
## 技术要点
|
||
|
||
### 异步加载机制
|
||
- 使用 goroutine 进行后台异步加载
|
||
- 使用 channel 或 context 控制加载流程
|
||
- 支持并发加载多个远程列表
|
||
|
||
### 缓存策略
|
||
- 内存缓存 + 文件缓存双重机制
|
||
- 基于时间的过期策略
|
||
- 支持手动刷新和自动刷新
|
||
|
||
### 错误处理
|
||
- 网络错误的重试机制
|
||
- 加载失败时的降级处理（使用缓存）
|
||
- 详细的错误日志记录
|
||
|
||
### 性能优化
|
||
- 批量处理减少锁竞争
|
||
- 使用 RWMutex 优化读写性能
|
||
- 延迟加载和按需加载
|
||
|
||
## 文件清单
|
||
|
||
### 新增文件
|
||
- `shield/domain_info_manager.go` - 域名信息管理器
|
||
- `static/js/modules/domain-info.js` - 前端域名信息管理模块
|
||
- `static/domain-info.html` - 域名信息管理界面（可选，如集成到现有页面则不需要）
|
||
|
||
### 修改文件
|
||
- `config/config.go` - 添加域名信息配置
|
||
- `http/server.go` - 添加 API 路由和处理函数
|
||
- `shield/manager.go` - 集成域名信息管理（可选）
|
||
- `static/js/shield.js` - 添加前端加载逻辑
|
||
- `README.md` - 更新文档
|
||
|
||
## 配置示例
|
||
|
||
```ini
|
||
[domainInfo]
|
||
; 域名信息列表配置
|
||
; 格式：name = url,enabled
|
||
domainInfoList = https://gitea.amazehome.xyz/AMAZEHOME/domain-info/raw/branch/main/domains/domain-info.json,true
|
||
threatDatabase = https://gitea.amazehome.xyz/AMAZEHOME/domain-info/src/branch/main/threats/threats-database.csv,true
|
||
trackerList = https://gitea.amazehome.xyz/AMAZEHOME/domain-info/raw/branch/main/tracker/trackers.json,true
|
||
|
||
; 更新间隔（秒）
|
||
updateInterval = 3600
|
||
|
||
; 是否启用自动更新
|
||
enableAutoUpdate = true
|
||
```
|
||
|
||
## 时间估算
|
||
- 步骤 1: 配置文件扩展 - 30 分钟
|
||
- 步骤 2: 域名信息管理器 - 2 小时
|
||
- 步骤 3: 后端 API 实现 - 1 小时
|
||
- 步骤 4: 前端界面实现 - 1.5 小时
|
||
- 步骤 5-6: API 集成 - 1 小时
|
||
- 步骤 7: 测试和文档 - 1 小时
|
||
|
||
**总计**: 约 7-8 小时
|