这是一份关于一个能够自动封禁IP的具有GUI界面的python脚本的简易上手说明，写给具有一定cloudflare使用基础的用户。
重要提示：这份教程仅仅提供与使用本脚本相关的教程及其衍生出来的必要教程，诸如worker代码的编写等需求与本脚本无关，因此概不教学！！！
本人因为需要对cloudflare worker API的请求ip进行限制，防止滥用，但是cf免费版似乎难以在边缘对二级域名进行速率限制，将限制写在worker中还会消耗worker请求次数，因此我写了这个python脚本
这个脚本整合了cloudflare worker、KV存储（记录IP基本情况）、cf防火墙服务（用于封禁IP）所能实现的功能融合而成
需求我认为本身不那么小众，但是网上似乎（？）也没有什么现成的自动化工具可以实现它（或者只是我没发现）
所以我打算把它开源出来，供各位使用
它可以实现的功能包括但不限于：调用KV来检查访问IP总数、最近访问时间，批量、自动化封禁、解封IP，管理IP白名单等功能
由于本脚本的功能需要，你的worker代码的KV需要获取到IP的请求总数（具体是什么请求因你的需求而异，例如api请求次数等）、最近访问时间等，否则部分功能将不可用以及报错，若您确实不需要它们也可以无视并且修改源代码
本人技术有限，若代码有冗余、不完备之处，恳请各位点评、批判
安装 Python、创建 Cloudflare Token、配置 KV 这些步骤，直接去搜索引擎查教程即可，这里只给方向和示范。
代码有许多设置可以结合自身需要进行修改，本处的所有命名仅起到示例作用。您可以在源码中自定义它们（不建议没有一定技术水平的用户操作）。

事先声明

本脚本面向具有一定基础的用户，一些基本内容我这里不再赘述，或自行使用搜索工具

如果脚本因为某些刁钻、奇葩的问题不能运行，请先不要急着问候我祖宗十八代，请优先在“常见问题”板块中查阅！！！常见问题板块会不断扩充、更新！！

下载源码

直接获取源码文件（右键另存 / 点击下载）：
👉 点我下载

快速开始（3 步）

  1. 下载 kdyzsyyds.py
  2. 设置环境变量（至少 4 个是必须的，后文会提到）。
  3. 运行py文件

启动前准备

  • 一台装了 Python 的 Windows 电脑。
  • 一个 Cloudflare 账号，可以管理你要保护的站点。
  • Cloudflare API Token（只给最小权限，不要泄露）。
  • 一个 Workers KV 命名空间（脚本会从里面读取数据）。
  • 一个托管在 Cloudflare 的域名（能够实现对被封禁IP的全站屏蔽，该IP访问你的任何子域名也会被封禁）。

不会操作？自行搜索

1
2
如何安装 Python？
如何创建 Cloudflare账号？

（doge

cloudflare 令牌创建

打开cloudflare后，拖动到下方“管理账户”
打开账户 API 令牌选项卡
点击创建令牌
图片
选择创建自定义令牌
图片

  1. 令牌名称随便输入一个
  2. 在权限那里选择“账户”、选择”worker KV 存储“、选择编辑
  3. 同样的地方选择“区域”、选择“区域”、选择编辑
  4. 同样的地方选择“区域”、选择“防火墙服务”、选择“编辑”
  5. 下面的区域资源选择”包括“，选择”账户的所有区域“，右边选择你的需要使用的账号
    图片
    其它的不用动，点击继续以显示摘要，再点击创建令牌
    图片
    然后会显示一个令牌，复制它（要妥善保存，不外泄，一旦他人获取到你的API令牌，他就能控制你账户上刚刚设置的所有内容）
    图片

设置环境变量

先打开环境变量设置，然后点击新建：
图片
图片
脚本从系统环境变量里读取配置。必须设置这 4 个：

  • CF_AUTH_TOKEN – 填入Cloudflare API Token （你刚才生成的那个令牌）
  • CF_ZONE_ID – 填入你的域名Zone ID （打开cf，在概述中点击你的域名，滑动到最右下角的区域 ID就是）
  • CF_ACCOUNT_ID – 填入你的账户 ID （上一步中，区域ID的下面一个账户 ID就是）
    图片
  • TOTAL_KV – Workers KV ID（这个对应的是你worker代码中对应的“总IP”的KV，此处的命名和你在worker kv中设置的名称无直接关联，但是要确保环境变量中是TOTAL_KV，否则脚本无法运行
    打开cloudflare后，点击下方“存储与数据库”，展开后点击“Workers KV”，KV名右边的ID就是我们需要的ID。需要复制具有我上文提到的 能够获取到IP的请求总数、最近访问时间、最近访问的IP的KV的ID！否则部分功能可能无法使用）
    图片
    可选的是这两个：
  • THRESHOLD — 自动封禁阈值，单位为次（脚本已经默认为30次请求，默认请求次数可以在脚本中自行编辑）
  • BAN_HOURS — 超出阈值后封禁的时长，单位为小时（默认为24小时，封禁时长同样可以在脚本中自行编辑）

Windows（PowerShell）示例

1
2
3
4
setx CF_AUTH_TOKEN "你的_token"
setx CF_ZONE_ID "你的 区域 id"
setx TOTAL_KV "你的 kv id"
setx CF_ACCOUNT_ID "你的账号id"

设置好后关闭再重新打开命令行，就能生效。
然后执行：

1
python .\kdyzsyyds.py

或者使用IDE代码编辑器打开后运行

脚本运行

每当第一次运行时都会出现以下界面
图片
根据需求自行选择，选择后会前往主界面
图片
这时，如果配置正确，IP列表应该会在稍后自动刷新
脚本本身的使用操作我认为还是挺简单的，各位自行摸索吧
如果有bug，欢迎反馈！

常见疑惑、问题

  • 界面没数据显示 / 刷新失败：检查环境变量是否设置正确。下方日志中能看到错误提示。
  • 日志 返回 403：检查 API Token 是否有 Firewall 和 KV 的权限。
  • tkinter 报错：安装 Python 时没勾选 tkinter，可以重新安装，或者搜索 “python 如何安装 tkinter”。
  • IPv6 显示异常：如果发现 IPv6 显示不正常，可以在博客下方评论区反馈。
  • 多出的文件:运行脚本后，若你给ip添加了白名单，当前目录就会多出一个“whitelist.json”文件，它是用来在本地存放你可能设置的白名单IP的。若你把它删了，你的白名单会消失。
    每次执行封禁操作前都会检查这个json文件，若IP在这个白名单内，则不进行封禁操作，即使它已经超出了你阈值。
    若ip在被封禁时被添加进白名单，那么封禁会自动解除！
  • 运行脚本时选择自动封禁模式后等了很久？（已解决）:更新：目前源代码已经使用异步进程，通常来说不会再出现等待很久的问题。

安全提醒

  • API Token 千万别泄露。
  • 自动封禁有可能误判。不要忘记你可以在源代码、环境变量中设置阈值！！
  • 善用白名单功能，常见可信 IP（如同事、服务器等）请加入白名单！！

教程结束 🎉

到这里，你应该就能顺利用上这个工具了。
如果有问题，可直接在博客文章的评论区反馈。

结尾

本人水平有限，所以最好不要把这个工具直接用在正式生产、开发环境中。
你也可以考虑先debug一下再使用…
若因使用本工具造成的各种损失，后果自负~~

🪪 开源声明（Non-Commercial License）

本项目（Cloudflare API 自动封禁 Python GUI 脚本）已开源。
允许任何人免费使用、修改、分发本项目及其源代码，但禁止任何形式的商业用途。
若需再发布、转载或基于本项目进行二次创作，必须保留以下署名信息：

原作者：可达鸭战神
来源：https://blog.kdyzs.top/2025/10/03/%E8%A7%A3%E5%86%B3api%E6%BB%A5%E7%94%A8pythonGUI/

版权所有 (c) 2025 可达鸭战神

本软件由作者“可达鸭战神”创意和设计，其中所有功能、逻辑和需求均为作者原创。AI 工具仅在代码实现和调试过程中提供辅助作用，作者对代码的创意和最终实现承担全部责任。

特此免费授予任何获得本软件及相关文档（以下简称“本软件”）的人使用、复制、修改和分发本软件的权利，但须遵守以下条件：

  1. 本软件及其衍生作品不得用于任何商业用途。
  2. 在本软件的所有副本或重要部分中，必须保留上述版权声明和本许可声明。
  3. 在任何再分发中，必须保留对原作者“可达鸭战神”的署名。

本软件按“原样”提供，不提供任何形式的明示或暗示的保证，包括但不限于对适销性、特定用途适用性及不侵权的保证。在任何情况下，作者不对因使用本软件而产生的任何损失或责任承担责任。

Copyright (c) 2025 可达鸭战神

This software was designed and conceptualized by the author, “可达鸭战神”. All features, logic, and requirements are original contributions of the author. AI tools were only used as an aid for code implementation and debugging; the author retains full responsibility for the creative design and final implementation of the software.

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the “Software”), to use,
copy, modify, and distribute copies of the Software, subject to the following conditions:

  1. The Software and its derivatives shall not be used for any commercial purpose.
  2. The above copyright notice and this permission notice shall be included in
    all copies or substantial portions of the Software.
  3. Attribution to the original author (“可达鸭战神”) must be retained in any redistribution.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. In no event shall the
author be liable for any claim, damages, or other liability arising from, out of,
or in connection with the software or the use or other dealings in the Software.

简而言之：你可以自由使用、学习、修改和分享，但不得商用，并且在再发布时请保留作者署名「可达鸭战神」。