DeuKrom/cloudflare-zero-trust-adblock-updater
GitHub: DeuKrom/cloudflare-zero-trust-adblock-updater
该项目是一个自动化运维工具，用于将 OISD 广告拦截域名列表同步至 Cloudflare Zero Trust DNS 网关并创建对应的拦截规则。
Stars: 5 | Forks: 2
# cf-zt-oisd-sync
本程序会下载官方的 `OISD small` 列表，并将其包含的域名添加到 Cloudflare Zero Trust Gateway 中，作为可复用的 DOMAIN 列表。随后，它会创建一条 DNS Gateway 规则来拦截这些域名。
除非是由本程序创建的策略，否则程序不会修改现有的 Cloudflare 策略。
## 最快上手路径
如果您希望程序能“直接运行”，整体流程如下：
1. 在终端中打开项目文件夹。
2. 安装 Python 及相关依赖。
3. 运行 `python run.py`。
4. 选择选项 `1` 来创建 `.env`。
5. 选择选项 `2` 来检查连接。
6. 选择选项 `3` 在不进行任何更改的情况下预览计划。
7. 如果计划无误，选择选项 `4`。
8. 以后需要更新时，再次运行 `python run.py` 并选择选项 `4` 即可。
您可以依次执行以下命令。
## 安装依赖
在项目文件夹中，运行：
```
python3 -m pip install -e .
```
在 Windows PowerShell 中，通常可以使用以下命令：
```
python -m pip install -e .
```
## 通过菜单轻松启动
安装好依赖后，运行：
```
python run.py
```
在 WSL/Ubuntu 中，该命令可能名为 `python3`：
```
python3 run.py
```
您将看到如下菜单：
```
1. Initial setup (.env)
2. Check Cloudflare and OISD connection
3. Dry-run: show plan without changes
4. Create or update lists and blocking rule
5. Show status
6. Delete created objects
7. Diagnose problems
8. Language / Язык
0. Exit
```
输入选项编号并按 `Enter` 键。例如，常见的首次运行流程如下：
```
1 -> 2 -> 3 -> 4 -> 5
```
这意味着：配置、检查、预览计划、应用更改，然后检查状态。
如果该程序已作为 CLI 命令安装，您可以通过以下命令打开同样的菜单：
```
cf-zt-oisd-sync menu
```
## 应该打开哪个文件夹
请打开项目文件夹本身：
```
C:\Users\MAESTRO\Downloads\cloudflare zero trust adblock updater
```
如果您在 WSL/Linux 环境下操作，相同的路径显示如下：
```
/mnt/c/Users/MAESTRO/Downloads/cloudflare zero trust adblock updater
```
该文件夹应包含：
```
README.md
pyproject.toml
.env.example
cf_zt_oisd_sync/
tests/
```
## 如何打开文件夹
以下任何方式均可：
- Windows Terminal；
- PowerShell；
- Ubuntu/WSL 终端；
- VS Code：选择 `File -> Open Folder`，然后打开 `Terminal -> New Terminal`。
如果您不确定，最简单的方法是打开 VS Code，选择项目文件夹并打开内置终端。
## 如何进入项目文件夹
在 WSL/Ubuntu 中：
```
cd "/mnt/c/Users/MAESTRO/Downloads/cloudflare zero trust adblock updater"
```
在 PowerShell 中：
```
cd "C:\Users\MAESTRO\Downloads\cloudflare zero trust adblock updater"
```
## 安装 Python
检查是否已安装 Python：
```
python3 --version
```
或者在 Windows PowerShell 中：
```
py --version
```
需要 Python 3.11 或更高版本。
如果尚未安装 Python，请从官方网站下载安装：
```
https://www.python.org/downloads/
```
在 Windows 上，安装过程中请务必勾选 `Add python.exe to PATH` 复选框。
## 安装依赖
### 选项 A：WSL/Ubuntu
首先安装 `pip` 和虚拟环境模块：
```
sudo apt-get update
sudo apt-get install -y python3-pip python3-venv
```
然后在项目文件夹中运行：
```
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install -e '.[dev]'
```
执行 `source .venv/bin/activate` 后，终端提示符的开头通常会出现 `(.venv)`。这是正常现象：表示已为该项目激活了独立的 Python 环境。
### 选项 B：Windows PowerShell
在项目文件夹中运行：
```
py -m venv .venv
.\.venv\Scripts\Activate.ps1
py -m pip install -e ".[dev]"
```
如果 PowerShell 不允许激活 `.venv`，请运行：
```
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
```
然后重试：
```
.\.venv\Scripts\Activate.ps1
```
## 配置 Cloudflare
程序需要以下两个值：
- `CLOUDFLARE_ACCOUNT_ID`；
- `CLOUDFLARE_API_TOKEN`。
### 在哪里找到 Account ID
1. 打开 Cloudflare dashboard。
2. 选择您要使用的账户。
3. `Account ID` 通常显示在右侧边栏或账户/个人资料部分。
4. 复制完整的值。
### 如何创建 API token
1. 打开 Cloudflare dashboard。
2. 进入 `My Profile -> API Tokens`。
3. 点击 `Create Token`。
4. 创建一个具有 Cloudflare Zero Trust Gateway Lists 和 Gateway Rules 权限的 token。
5. token 创建完成后，请立即复制。
Cloudflare 仅会显示一次 token。如果您在没有复制的情况下关闭了页面，通常重新创建一个新 token 会更方便。
## 创建 `.env`
最简单的方法：
```
cf-zt-oisd-sync setup
```
程序会提示：
```
Enter Cloudflare Account ID:
Enter Cloudflare API Token:
OISD small source [https://small.oisd.nl]:
List prefix [oisd-small-auto]:
Rule name [OISD Small Auto Block]:
List chunk size [1000]:
```
对于大多数问题，您可以直接按 `Enter` 键保留默认值。您只需要手动输入 `Account ID` 和 `API Token`。
完成后，该文件夹中会生成一个 `.env` 文件。这是一个包含设置的常规文本文件。您可以使用 VS Code 或记事本打开它，但请勿将其发布到网络上：因为它包含敏感的 API token。
## 运行前检查
运行：
```
cf-zt-oisd-sync check
```
如果一切正常，您会看到带有 `[OK]` 的行。
如果您看到关于 token 或权限的错误，请检查：
- `CLOUDFLARE_API_TOKEN` 是否粘贴正确；
- `CLOUDFLARE_ACCOUNT_ID` 是否粘贴正确；
- 该 token 是否具有 Gateway Lists 和 Gateway Rules 的权限。
## 安全预览
在创建实际对象之前，运行：
```
cf-zt-oisd-sync dry-run
```
此命令不会对 Cloudflare 中的任何内容进行更改。它只会显示将要创建的列表数量以及将会生效的规则。
## 首次正式运行
如果 `dry-run` 的结果无误：
```
cf-zt-oisd-sync init
```
程序会要求您确认。确认后，它将创建：
- 若干 Cloudflare DOMAIN 列表；
- 一条 DNS Gateway 规则；
- 一个本地状态文件，即 `.cf-zt-oisd-state.json`。
在创建过程中，您将看到 Cloudflare 列表和 DNS Gateway 规则的进度指示。如果列表较多，这也是正常现象：Cloudflare 会分批次接受它们。
该状态文件用于让程序记住它创建了哪些对象。您无需手动编辑此文件。
## 如何检查一切是否正常
运行：
```
cf-zt-oisd-sync status
```
成功的结果大致如下：
```
[OK] Local state matches Cloudflare
```
您也可以打开 Cloudflare Zero Trust dashboard，手动检查 Gateway 列表/规则。
## 如何更新列表
常规更新：
```
cf-zt-oisd-sync update
```
无需确认的自动更新：
```
cf-zt-oisd-sync update --yes
```
在更新过程中，程序也会显示进度：一个指示列表的进度，另一个指示拦截规则的进度。
## 如何删除程序创建的所有内容
交互式删除：
```
cf-zt-oisd-sync delete
```
程序会要求您输入：
```
DELETE
```
自动删除（无需确认）：
```
cf-zt-oisd-sync delete --yes
```
仅会删除由此程序管理的对象：带有已配置前缀的列表、状态文件中的对象，以及标记有 `Managed by cf-zt-oisd-sync` 的对象。
## 每天需要运行的内容
如需定期更新，请使用：
```
cf-zt-oisd-sync update --yes
```
### Windows 任务计划程序
供计划程序使用的命令：
```
python -m cf_zt_oisd_sync.cli update --yes
```
其工作文件夹必须为项目文件夹：
```
C:\Users\MAESTRO\Downloads\cloudflare zero trust adblock updater
```
### Linux cron
每天 04:00 运行的示例：
```
0 4 * * * cd "/mnt/c/Users/MAESTRO/Downloads/cloudflare zero trust adblock updater" && . .venv/bin/activate && cf-zt-oisd-sync update --yes
```
## 常见问题
### 我应该打开哪个文件？
打开 `README.md` 查看说明。
打开 `.env` 修改设置。
打开 `.cf-zt-oisd-state.json` 检查状态，但通常不需要编辑它。
### 应该如何打开 `.env`？
使用 VS Code、记事本、Notepad++ 或任何文本编辑器均可。通常 VS Code 最为方便。
### 为什么看不到 `.env` 文件？
以点开头的文件有时会被视为隐藏文件。它们在 VS Code 中通常是可见的。在 Windows 资源管理器中，需要启用显示隐藏文件功能。
### 如果找不到 `cf-zt-oisd-sync` 命令怎么办？
最可能的原因是未激活虚拟环境。
在 WSL/Ubuntu 中：
```
source .venv/bin/activate
```
在 PowerShell 中：
```
.\.venv\Scripts\Activate.ps1
```
然后重试：
```
cf-zt-oisd-sync --help
```
### 如果出现 `python3: No module named pip` 怎么办？
在 WSL/Ubuntu 中，请安装 `pip`：
```
sudo apt-get update
sudo apt-get install -y python3-pip python3-venv
```
然后重新安装依赖。
### 如果 Cloudflare 返回 `403 Forbidden` 怎么办？
这几乎总是意味着 API token 缺少所需的权限。请创建或更新具有 Zero Trust Gateway Lists 和 Gateway Rules 访问权限的 token。
### 如果我担心破坏现有配置怎么办？
请先运行：
```
cf-zt-oisd-sync dry-run
```
此命令不会更改任何内容。它只会展示计划。
### 我可以更改 `CHUNK_SIZE` 吗？
通常，保持 `1000` 即可。对于 Standard/免费类型的 Cloudflare 计划来说，这是一个安全的值。
### 什么是状态文件？
即 `.cf-zt-oisd-state.json` 文件。程序会将创建的 Cloudflare 列表和规则的 ID 记录在其中。程序正是通过它来判断需要更新或删除哪些内容的。
### 我可以删除状态文件吗？
最好不要删除。如果它丢失了，请运行：
```
cf-zt-oisd-sync doctor
```
### 我怎么确定程序不会删除多余的内容？
`delete` 命令仅会查找并删除明显由本程序创建的对象：
- 它们被列在状态文件中；
- 或者它们具有已配置的前缀；
- 或者它们的描述中包含 `Managed by cf-zt-oisd-sync`。
## 命令参考
```
cf-zt-oisd-sync --help
cf-zt-oisd-sync setup
cf-zt-oisd-sync check
cf-zt-oisd-sync dry-run
cf-zt-oisd-sync init
cf-zt-oisd-sync update
cf-zt-oisd-sync status
cf-zt-oisd-sync delete
cf-zt-oisd-sync doctor
```
## 开发者检查
如果已安装开发依赖：
```
pytest
```
标签：Cloudflare, DNS, Docker 部署, MITRE ATT&CK, Python, 广告拦截, 数字取证, 文档结构分析, 无后门, 网络运维, 自动化脚本, 逆向工具