allistercyber/Control-D-Automation
GitHub: allistercyber/Control-D-Automation
通过 GitHub Actions 定时任务将 hagezi DNS 屏蔽列表自动同步并推送到 Control D API，实现 DNS 过滤规则的无人值守更新。
Stars: 3 | Forks: 1
# 🚀 Control D x Hagezi-Sync
通过 Control D API 自动将来自 [hagezi/dns-blocklists](https://github.com/hagezi/dns-blocklists) 的 DNS 屏蔽列表文件夹同步到您的 [Control D](https://controld.com) 账户中。
通过 GitHub Actions 定时任务运行。
## 🔧 功能
- ✅ 通过 cron 定时任务每天自动同步两次（UTC 时间上午 5 点和下午 5 点）
- 🐍 基于 Python 的同步脚本，内置重试逻辑
- 🔒 依赖版本固定，并使用提交哈希锁定的 Actions
- ✉️ 如果文件发生更改，会发送包含差异摘要的电子邮件
- 📁 保持 `controld/` 文件夹与上游同步
- 🌐 自动将域名更改推送到 Control D API
- 🔄 幂等协调 —— 在重试或部分运行时实现自愈
## ⚙️ 工作原理
工作流每天运行两次（UTC 时间 05:00 和 17:00），分为两个阶段：
1. 📥 **阶段 1 —— 文件同步** (`scripts/controld_sync.py`)
从 hagezi 上游仓库下载目标 JSON 文件，将它们与本地副本进行差异对比，并将任何更改提交回此仓库。为下一阶段设置一个 `changed` 标志。
2. 🌐 **阶段 2 —— API 推送** (`scripts/controld_api_push.py`)
仅在阶段 1 检测到更改时运行。读取更新后的 JSON 文件，并根据期望状态协调每个映射的 Control D 文件夹 —— 添加新域名并移除过期域名。协调始终基于 **实时的 API 状态**，因此脚本是幂等的，并且如果上一次运行被中断，它可以实现自愈。
✉️ 在阶段 2 之后会发送一封电子邮件报告，总结每个配置文件和文件夹中添加、删除或跳过的每个域名。
## 🚀 快速开始
### 1. Fork 本仓库
### 2. 设置所需的 secret
前往 **Settings → Secrets and variables → Actions → New repository secret** 并添加以下内容：
#### 🔑 必需的 Secret
| Secret | Value | Description |
|--------|-------|-------------|
| `GITHUB_TOKEN` | *(自动提供)* | 由 GitHub Actions 自动提供 |
| `CTRLD_API_TOKEN` | 您的 Control D API token | 需要 **写入 (write)** 权限。可以在 Control D 面板的 **API** 下找到。 |
#### ✉️ 电子邮件通知 Secret（可选）
当检测到更改时，工作流可以发送电子邮件报告。省略相关配置即可跳过电子邮件发送：
| Secret | Value | Description |
|--------|-------|-------------|
| `EMAIL_USERNAME` | 您的 Gmail 地址 | 例如 `you@gmail.com` — 用于 SMTP 认证、发件人和收件人 |
| `EMAIL_PASSWORD` | 您的 Gmail 应用密码 | 在 [myaccount.google.com/apppasswords](https://myaccount.google.com/apppasswords) 生成 — **不是**您的常规 Gmail 密码 |
仅在阶段 2 运行时（即文件确实发生更改时）才会发送电子邮件。
### 3. 配置您的配置文件和文件夹映射
编辑 `scripts/controld_api_push.py` 并更新 `FILE_MAPPINGS`，以匹配您的 Control D 配置文件和文件夹名称。有关详细信息，请参阅 [CONFIGURATION.md](CONFIGURATION.md)。
如果您想跟踪不同的文件子集，还需要更新 `scripts/controld_sync.py` 中的 `TARGET_FILES`。
### 4. 手动运行以进行验证
前往 **Actions → Sync Control D folders from upstream → Run workflow** 以触发立即运行，并在等待定时任务之前验证一切是否正常。
## 📂 仓库结构
```
.github/
dependabot.yml # weekly auto-updates for Actions & pip deps
workflows/
sync-controld.yml # workflow orchestrator
scripts/
controld_sync.py # Stage 1: file sync
controld_api_push.py # Stage 2: Control D API push
requirements.in # direct Python dependencies (source of truth)
requirements.txt # fully pinned deps with SHA-256 hashes (generated)
CONFIGURATION.md # detailed setup & configuration reference
.gitignore
controld/ # synced JSON files (created on first run)
```
## 🌐 上游来源
所有屏蔽列表 JSON 文件均来自 [hagezi/dns-blocklists](https://github.com/hagezi/dns-blocklists/tree/main/controld)。向 hagezi 维护这些列表致敬。
标签：API集成, DNS过滤, GitHub Actions, Python, 可观测性, 无后门, 网络调试, 自动化, 自动笔记, 逆向工具