marcoodistefano/CTFTimeBot

# 🕛 CTFTime Notifier Bot **[➕ 添加到 Discord](https://top.gg/bot/1217196592046538993) | [⭐ 在 TOP.GG 投票](https://top.gg/bot/1217196592046538993)** 一款高级且可靠的 Discord 机器人，可自动将 CTFtime.org 上即将举办的夺旗赛 (CTF) 活动发布到您的服务器。 保持井然有序，绝不错过任何比赛，并让您的 CTF 团队自动获取最新信息！ ## 🆕 **近期重大更新 (2025)** - **🔥 Firebase Realtime Database 集成**：完全从本地 JSON 文件迁移至基于云的持久化存储 - **☁️ 持久化配置**：所有设置在机器人重启、崩溃和重新部署后均会自动保留 - **多服务器支持**：每个服务器（guild）都有自己独立的日程安排和配置 - **强大的 scheduler 管理**：scheduler 任务现在按 guild 通过全局注册表进行追踪，确保状态可靠并能重启 - **自动重启 scheduler**：对日程频道、时间或时区的任何更改都会立即取消并重启该服务器的 scheduler - **重启时自动恢复**：机器人在启动时会自动从 Firebase 恢复所有服务器配置和 scheduler - **scheduler 状态与日志**：`/scheduler_logs` 和 `/debug` 现在能显示每个服务器准确、实时的 scheduler 和配置信息 - **清理帮助命令**：`/help_ctf` 现在只列出可用且正常的命令 - **高级 debug 工具**：改进了 `/debug` 输出，包含配置、权限和脚本检查 - **更安全的任务处理**：机器人防止出现重复或僵尸 scheduler 任务，并始终反映最新的配置 - **改进的错误处理**：为所有命令提供更健壮的反馈和错误消息 - **更清晰的代码与文档**：所有命令和帮助文本均已更新，反映了机器人的真实功能 - **全天候托管就绪**：针对 Render.com 进行了优化，支持自动 keep-alive 和环境变量 ## 🚀 主要功能 * ⏰ **自动每日更新** 机器人每天会在您首选的时间获取并发布即将举行的 CTF 活动列表。 * 🔥 **Firebase 云存储** 所有配置都存储在 Firebase Realtime Database 中——在重启、崩溃和重新部署后自动保留。 * ☁️ **零数据丢失** 您的设置将永久保存在云端，没有本地文件依赖。 * 🌍 **全面的时区支持** 可针对全球任何时区进行配置（Europe/Rome、America/New_York、Asia/Tokyo 等）。 * 🕐 **可自定义的日程时间** 设置您首选的每日消息发送时间（不限于午夜！）。 * 🗑️ **自动清理频道** 在发送更新之前自动清除以前的消息。 * 📅 **一目了然的 CTF 赛事** 显示每场即将举行的比赛的赛事名称、日期、持续时间和直接链接。 * 🔧 **高级 debug 工具** 为管理员提供完整的监控和诊断系统。 * 🌐 **来自 CTFtime.org 的数据** 使用直接来自 CTFtime 网站的官方数据，始终保持最新。 * 🏢 **支持多服务器** 每个 Discord 服务器都有自己独立的配置和 scheduler。 * 🔄 **自动重启 scheduler** 对频道、时间或时区的任何更改都会重启该服务器的 scheduler。 * 🔁 **自动恢复** 机器人在任何重启后会自动恢复所有配置并重启所有 scheduler。 * 🛡️ **可靠的 scheduler 状态/日志** `/scheduler_logs` 和 `/debug` 始终反映 scheduler 和配置的真实状态。 * 🧹 **清晰且最新的帮助** `/help_ctf` 仅显示正常运行的命令。 ## 📋 可用命令 (2025) ### 📢 主要命令 | 命令 | 描述 | |---------|-------------| | `/upcoming` | 立即显示即将举行的 CTF 赛事 | | `/events` | 搜索并过滤即将举行的活动（格式、线上、权重） | | `/eventinfo ` | 获取特定 CTF 的详细信息 | | `/teaminfo ` | 获取特定 CTF 战队的详细信息 | | `/topbycountry ` | 获取特定国家/地区的顶级战队 | | `/topteams [year] [limit]` | 获取当前或特定年份的顶级战队 | | `/results [year] [limit]` | 获取全球 CTF 结果 | | `/help_ctf` | 显示所有可用命令 | ### ⚙️ 日程配置 | 命令 | 描述 | |---------|-------------| | `/set_schedule_channel` | 设置用于接收每日消息的当前频道（重启 scheduler） | | `/unset_schedule_channel` | 移除计划频道（停止 scheduler） | | `/schedule_status` | 显示当前 scheduler 状态 | ### 🕐 时间管理 | 命令 | 示例 | 描述 | |---------|---------|-------------| | `/set_schedule_time [minute]` | `/set_schedule_time 8 30` | 设置消息时间（重启 scheduler） | | `/get_schedule_time` | - | 显示当前设置的时间 | | `/reset_schedule_time` | - | 将时间重置为午夜（重启 scheduler） | ### 🌍 时区管理 | 命令 | 示例 | 描述 | |---------|---------|-------------| | `/set_timezone ` | `/set_timezone Europe/Rome` | 设置时区（重启 scheduler） | | `/get_timezone` | - | 显示当前设置的时区 | | `/list_timezones [region]` | `/list_timezones Europe` | 列出可用时区 | | `/reset_timezone` | - | 重置为 Europe/Rome（重启 scheduler） | ### 🔧 管理员命令 | 命令 | 描述 | |---------|-------------| | `/test_schedule` | 测试计划发送（包含频道清理） | | `/force_schedule` | 强制立即发送计划消息 | | `/test_now` | 不删除消息的快速测试 | | `/clear_channel` | 清除计划频道中的所有消息 | | `/debug` | 显示详细的 debug 信息（按服务器） | | `/scheduler_logs` | 检查日程任务状态（按服务器，始终准确） | | `/restart_scheduler` | 重启此服务器的日程任务 | ## 🎯 快速入门指南（多服务器，2025） ### 1️⃣ 初始设置 ``` 1. /set_schedule_channel # In the channel where you want messages (restarts scheduler) 2. /set_schedule_time 8 0 # Set time (e.g., 08:00, restarts scheduler) 3. /set_timezone Europe/Rome # Set your timezone (restarts scheduler) ``` ### 2️⃣ 验证配置 ``` /schedule_status # Check that everything is configured ``` ### 3️⃣ 测试功能 ``` /test_now # Quick test /force_schedule # Complete test with cleanup ``` ## 🌍 支持的时区 该机器人支持所有标准时区。以下是一些示例： **欧洲：** - `Europe/Rome`（意大利） - `Europe/London`（英国） - `Europe/Paris`（法国） - `Europe/Berlin`（德国） **美洲：** - `America/New_York`（美国东部） - `America/Los_Angeles`（美国西部） - `America/Chicago`（美国中部） - `America/Toronto`（加拿大） **亚洲：** - `Asia/Tokyo`（日本） - `Asia/Shanghai`（中国） - `Asia/Mumbai`（印度） - `Asia/Dubai`（阿联酋） **大洋洲：** - `Australia/Sydney` - `Pacific/Auckland` 使用 `/list_timezones` 查看所有可用时区，或使用 `/list_timezones [region]` 查看特定区域。 ## ➕ 将机器人添加到您的服务器 **[🎯 从 TOP.GG 邀请 CTFTime Notifier Bot](https://top.gg/bot/1217196592046538993)** 该机器人全天候托管，随时可用！只需点击上方链接将其添加到您的 Discord 服务器。 ### 🚀 快速开始 一旦受邀加入您的服务器： 1. **设置您的频道**：在您希望接收每日更新的频道中运行 `/set_schedule_channel` 2. **自定义（可选）**： - `/set_schedule_time 9 0` - 设置时间（例如 09:00） - `/set_timezone Europe/Rome` - 设置您的时区 3. 大功告成！机器人将每天自动发布 CTF 活动 🎉 ### 🔐 所需的机器人权限 确保机器人具有以下权限： - ✅ **Send Messages** - 用于发布更新 - ✅ **Manage Messages** - 用于清除旧消息 - ✅ **Embed Links** - 用于显示格式化的事件卡片 ## 🛠️ 故障排除 ### 📋 前置条件 1. **Discord Bot Token**：在 [Discord Developer Portal](https://discord.com/developers/applications) 创建一个机器人 2. **Firebase Project**：设置 Firebase Realtime Database（参见 [FIREBASE_SETUP.md](FIREBASE_SETUP.md)） 3. **托管平台**：推荐：[Render.com](https://render.com)（提供免费层） ### ☁️ 在 Render 上部署（推荐 - 免费 24/7 托管） #### 1. Fork/克隆此仓库 ``` git clone https://github.com/Mrk756/CtfTimeBot.git cd CtfTimeBot ``` #### 2. 设置 Firebase 按照 [FIREBASE_SETUP.md](FIREBASE_SETUP.md) 中的完整指南进行操作，以： - 创建一个 Firebase 项目 - 启用 Realtime Database - 下载服务账号凭据 - 获取您的数据库 URL #### 3. 部署到 Render 1. 前往 [Render Dashboard](https://dashboard.render.com/) 2. 点击 **"New +"** → **"Web Service"** 3. 连接您的 GitHub 仓库 4. 配置： - **Name**：`ctftime-bot`（或您自定义的名称） - **Environment**：`Python 3` - **Build Command**：（留空，从 `requirements.txt` 自动检测） - **Start Command**：（从 `Procfile` 自动检测：`python main.py`） - **Plan**：Free #### 4. 添加环境变量 在 Render 中，转到 **Environment**（环境）选项卡并添加： | 变量 | 值 | 在哪里查找 | |----------|-------|---------------| | `DISCORD_TOKEN` | 您的 Discord 机器人 token | [Discord Developer Portal](https://discord.com/developers/applications) | | `FIREBASE_DATABASE_URL` | `https://your-project.firebaseio.com/` | Firebase Console → Realtime Database | | `FIREBASE_CREDENTIALS` | 凭据文件中的完整 JSON | 从 Firebase 下载（粘贴完整的 JSON） | **重要提示**：对于 `FIREBASE_CREDENTIALS`，请粘贴您 Firebase 凭据 JSON 文件的**完整内容**。 #### 5. 部署！ 点击 **"Create Web Service"** - Render 将自动： - 从 `requirements.txt` 安装依赖项 - 使用 `Procfile` 启动机器人 - 保持其 24/7 运行 ### 🖥️ 本地开发 #### 1. 克隆并安装 ``` git clone https://github.com/Mrk756/CtfTimeBot.git cd CtfTimeBot pip install -r requirements.txt ``` #### 2. 配置环境 创建一个 `.env` 文件： ``` DISCORD_TOKEN=your_discord_bot_token FIREBASE_DATABASE_URL=https://your-project-default-rtdb.firebaseio.com/ FIREBASE_CREDENTIALS_PATH=firebase-credentials.json ``` 将您的 Firebase 凭据 JSON 文件作为 `firebase-credentials.json` 放在项目根目录中。 #### 3. 运行 ``` python main.py ``` ### 🔧 保持机器人 24/7 在线（可选但推荐） Render 免费层在 15 分钟不活动后会休眠。使用 [UptimeRobot](https://uptimerobot.com/)（免费）每 5 分钟 ping 一次您的机器人： 1. 在 [UptimeRobot](https://uptimerobot.com/) 注册 2. 创建一个新的监控： - **Monitor Type**：HTTP(s) - **URL**：您的 Render URL（例如 `https://ctftime-bot.onrender.com`） - **Monitoring Interval**：5 分钟 3. 保存 - 您的机器人将永远不会休眠！ 🎉 ### 📦 依赖项 ``` python-dotenv # Environment variables nextcord # Discord API wrapper aiohttp # Asynchronous HTTP requests flask # Keep-alive web server firebase-admin # Firebase Realtime Database ``` 所有依赖项都会从 `requirements.txt` 自动安装。 ### 🔐 安全说明 - ✅ 切勿将 `.env` 文件或 Firebase 凭据提交到 Git - ✅ 对所有密钥使用环境变量 - ✅ Firebase 凭据已包含在 `.gitignore` 中 - ✅ 配置 Firebase 安全规则（参见 [FIREBASE_SETUP.md](FIREBASE_SETUP.md)） ## 🛠️ 故障排除 (2025) ### 机器人没有发送计划消息？ 1. 使用 `/scheduler_logs` 检查任务是否处于活动状态（按服务器，始终最新） 2. 使用 `/debug` 验证配置（按服务器） 3. 如有必要，尝试使用 `/restart_scheduler`（可靠，按服务器） ### 时区错误？ 1. 使用 `/list_timezones` 查看有效的时区 2. 使用 `/get_timezone` 检查当前时区 3. 如有必要，使用 `/reset_timezone` 进行重置 ### 权限问题？ 机器人需要以下权限： - ✅ Send Messages - ✅ Manage Messages（用于清理频道） - ✅ Embed Links ### Firebase 连接失败？ 1. 检查 `FIREBASE_DATABASE_URL` 是否正确（末尾没有 `/` 的问题） 2. 验证 `FIREBASE_CREDENTIALS` 包含有效的 JSON 3. 确保 Firebase 安全规则允许服务账号访问 4. Render 日志以获取具体的错误消息 ### 重启后配置未保留？ 使用 Firebase **绝不**应发生这种情况！机器人在重新上线时会自动恢复所有配置。 如果您遇到问题： - 使用 `/debug` 检查您当前的配置 - 尝试使用 `/restart_scheduler` 手动重启 scheduler - 如果问题持续存在，请联系支持 ## 📸 示例输出  ## 🔄 更新与功能 **2025 年重大更新：** - 支持多服务器，具备基于 guild 的配置和日程安排 - 全局 scheduler 任务注册表，确保状态稳健且易于重启 - 每次配置更改（频道、时间、时区）时自动重启 scheduler - `/scheduler_logs` 和 `/debug` 始终反映真实状态 - `/help_ctf` 已清理且始终保持最新 - 改进了错误处理和反馈 - 不再有僵尸或重复的 scheduler 任务 ## 👩‍💻 面向开发者 想要自托管或为机器人做贡献吗？以下是您需要了解的内容： ### 🛠️ 技术栈 - **语言**：Python 3.13+ - **Discord 库**：[nextcord](https://github.com/nextcord/nextcord) - **数据库**：Firebase Realtime Database - **Web Scraping**：BeautifulSoup4 + Requests - **托管**：Render.com（或任何 Python 托管平台） - **Keep-Alive**：Flask Web 服务器 ### 📦 安装与设置 #### 1. 克隆仓库 ``` git clone https://github.com/Mrk756/CtfTimeBot.git cd CtfTimeBot pip install -r requirements.txt ``` #### 2. Firebase 设置 按照 **[FIREBASE_SETUP.md](FIREBASE_SETUP.md)** 中的完整指南进行操作，以： - 创建一个 Firebase 项目 - 启用 Realtime Database - 下载服务账号凭据 - 配置安全规则 #### 3. 环境变量 创建一个 `.env` 文件： ``` DISCORD_TOKEN=your_discord_bot_token FIREBASE_DATABASE_URL=https://your-project-default-rtdb.firebaseio.com/ FIREBASE_CREDENTIALS_PATH=firebase-credentials.json ``` 或者对于云部署（例如 Render）： ``` DISCORD_TOKEN=your_discord_bot_token FIREBASE_DATABASE_URL=https://your-project-default-rtdb.firebaseio.com/ FIREBASE_CREDENTIALS= ``` #### 4. 在本地运行 ``` python main.py ``` ### ☁️ 部署到 Render 1. Fork 此仓库 2. 在 [Render](https://render.com) 上创建一个新的 **Web Service** 3. 连接您的 GitHub 仓库 4. 添加环境变量（参见上面的第 3 步） 5. 部署！`Procfile` 和 `requirements.txt` 将处理其余部分 **Render 配置：** - **Build Command**：（从 `requirements.txt` 自动检测） - **Start Command**：`python main.py`（来自 `Procfile`） - **Environment**：Python 3 ### 🔧 项目结构 ``` CtfTimeBot/ ├── main.py # Main bot logic & schedule management ├── ctftime_commands.py # Advanced CTFTime API commands ├── firebase_db.py # Firebase database abstraction ├── webserver.py # Flask keep-alive server ├── requirements.txt # Python dependencies ├── Procfile # Render deployment config ├── .env # Environment variables (local) ├── .gitignore # Git ignore rules ├── README.md # This file └── FIREBASE_SETUP.md # Firebase setup guide ``` ### 🔐 安全说明 - ✅ 切勿提交 `.env` 或 `firebase-credentials.json` - ✅ 对所有密钥使用环境变量 - ✅ 配置 Firebase 安全规则（参见 `FIREBASE_SETUP.md`） - ✅ 保持依赖项更新 ### 🤝 贡献 欢迎各种贡献！如需贡献： 1. Fork 该仓库 2. 创建一个功能分支 (`git checkout -b feature/AmazingFeature`) 3. 提交您的更改 (`git commit -m 'Add AmazingFeature'`) 4. 推送到该分支 (`git push origin feature/AmazingFeature`) 5. 发起一个 Pull Request **欢迎贡献的领域：** - Bug 修复 - 新功能（例如更多 CTF 平台） - 文档改进 - 代码优化 ### 📚 更多开发者文档 - **[FIREBASE_SETUP.md](FIREBASE_SETUP.md)** - 完整的 Firebase 设置指南 - **[requirements.txt](requirements.txt)** - Python 依赖项 - **[Procfile](Procfile)** - 部署配置 ### 📄 许可证 该项目是开源的，并在 MIT 许可证下可用。 ## 💬 支持与社区 - **需要帮助？** 在 Discord 中使用 `/help_ctf` - **Bug 报告**：[GitHub Issues](https://github.com/Mrk756/CtfTimeBot/issues) - **为机器人投票**：[TOP.GG](https://top.gg/bot/1217196592046538993) ⭐ ## 🙏 鸣谢 - CTF 赛事数据来自 [CTFtime.org](https://ctftime.org/) - 使用 [nextcord](https://github.com/nextcord/nextcord) 构建 - 由 [Firebase](https://firebase.google.com/) 提供持久化存储 - 托管于 [Render](https://render.com/) - 在 [TOP.GG](https://top.gg/bot/1217196592046538993) 上发布 **让您的 CTF 团队时刻保持更新！ 🚀** **[➕ 添加到 Discord](https://top.gg/bot/1217196592046538993) | [⭐ 在 TOP.GG 投票](https://top.gg/bot/1217196592046538993) | [🐛 报告问题](https://github.com/Mrk756/CtfTimeBot/issues)** **需要帮助？** 查看 [FIREBASE_SETUP.md](FIREBASE_SETUP.md) 获取详细的设置说明，或在 GitHub 上提交一个 issue。

标签：Discord机器人, Firebase, Webhooks, 任务调度, 网络调试, 自动化, 逆向工具