项目地址

https://github.com/iougemini/CF-HF-Waker

🤗 hf-waker (Cloudflare Workers Edition)

全自动巡检并唤醒你的 Hugging Face Spaces，告别冷启动与 GitHub Actions 60 天停用限制！内置 Web 可视化控制台、多账号多 Space 并发管理、智能状态检测、Cloudflare KV 历史审计与 Telegram 通知。

💡 项目说明：本项目借鉴自 oversizexl/hf-waker（原版基于 Python + GitHub Actions），在此基础上完全重构并迁移至 Cloudflare Workers 无服务器架构，新增了智能状态检测、多账号 Token 并发支持、可视化 Web 控制台以及 Cloudflare KV 历史日志审计等功能。

✨ 核心特性

⚠️ 风险提示与防封号指南 (必读)

本项目通过 Hugging Face 官方开放的 Hub API 进行状态查询与按需唤醒，且默认开启 **“运行中跳过 (RUNNING Skip)”** 保护机制，正常使用下非常安全。但为了保护你的 Hugging Face 账号安全，请务必遵守以下准则：

1. 严禁保活违规应用（封号头号原因）：
   请勿将本工具用于保活违反 Hugging Face 内容准则 的 Space（例如：代理 / VPN 节点、加密货币挖矿、恶意爬虫、未授权商业 API 转发等）。此类应用在 24 小时不间断运行下极易触发官方算力风控，从而导致账号被封禁。
2. 合理设置 Cron 巡检频率：
   免费版 Hugging Face Space 默认在连续无交互 48 小时后才会进入 SLEEPING 状态。建议将 Cron 设置为每天 1~4 次（如 0 */6 * * * 或 0 0 * * *）即可，切勿设置成每分钟级别的高频轮询。
3. 避免滥用强制重启 (force=true)：
   日常定时任务请保持默认的智能唤醒模式（仅在休眠时重启）。频繁强制重启正在运行的容器会大量消耗官方构建资源，可能触发 API 速率限制。
4. 控制单 Worker 挂载的账号数量：
   多 Token 功能旨在方便开发者管理自己的工作号与个人号（建议控制在 2~3 个账号以内）。请勿在单个 Worker 中配置大量批量注册的小号，以免被识别为矩阵滥用（Sybil Attack）。

免责声明：本项目仅供学习交流与合规 AI/Web 演示项目的自动化运维使用。因违反 Hugging Face 服务条款或不当配置导致的账号受限，需由使用者自行承担责任。

📸 控制台截图

🚀 3 分钟网页端快速部署指南

无需本地配置命令行环境，直接在 Cloudflare 网页后台复制粘贴即可完成部署：

第一步：创建并部署 Worker

1. 登录 Cloudflare Dashboard，进入 Workers & Pages。
2. 点击 Create application (创建应用程序) → Create Worker (创建 Worker)。
3. 将名称设为 hf-waker，点击 Deploy (部署)。
4. 点击右上角 Edit code (编辑代码)，将本项目的 worker.js 代码完整粘贴进去，点击右上角 Deploy 保存。

第二步：配置环境变量 (Variables and Secrets)

进入 Worker 的 Settings (设置) → Variables and Secrets (变量和机密)，点击 Add 添加以下变量（敏感字段建议选择 Secret 加密类型）：

🔑 HF_TOKEN 获取地址：前往 Hugging Face Settings - Access Tokens，新建一个 Token 并确保勾选对应 Space 的 Write 权限。

第三步：配置多账号 / 多 Token（三种写法任选其一）

本项目完全兼容单账号与多账号管理，你可以根据习惯选择以下任意一种配置格式：

• 方式 A：在 SPACE_REPO_ID 中直接内联绑定（最推荐，清晰直观）
  无需填写 HF_TOKEN 变量，直接按 Token:Space1,Space2 格式填写，多个账号之间用分号 ; 或换行分隔：

  hf_tokenAAA:alice/space1,alice/space2;hf_tokenBBB:bob/space3
  

• 方式 B：双变量按分号 ; 分组一一对应
  • HF_TOKEN: hf_tokenAAA;hf_tokenBBB
  • SPACE_REPO_ID: alice/space1,alice/space2;bob/space3,bob/space4
• 方式 C：单账号管理多个 Space（经典写法）
  • HF_TOKEN: hf_tokenAAA
  • SPACE_REPO_ID: alice/space1,alice/space2,alice/space3

第四步：绑定 Cloudflare KV 开启历史日志（可选）

若希望在网页控制台下方查看最近 10 次唤醒记录，请按以下步骤绑定（不绑定也可正常使用所有唤醒功能）：

1. 在 Cloudflare 左侧菜单进入 Storage & Databases (存储和数据库) → KV。
2. 点击 Create a namespace，名称填写 hf-waker-logs，点击 Add。
3. 回到 Worker 的 Settings → Bindings (绑定)，点击 Add → KV Namespace：
   • Variable name (变量名称)：严格填写 WAKE_KV
   • KV namespace (命名空间)：选择 hf-waker-logs
4. 点击 Deploy 保存即可。

第五步：设置 Cron 定时自动巡检

1. 进入 Worker 的 Settings → Triggers (触发器) → Cron Triggers。
2. 点击 Add Cron Trigger，输入 Cron 表达式（注意 Cloudflare 采用 UTC 时间）：
   • 每 6 小时自动巡检一次（最推荐，温和且及时）：0 */6 * * *
   • 每天北京时间 00:00（午夜）巡检：0 16 * * *
   • 每天北京时间 08:00（早上）巡检：0 0 * * *

🖥️ Web 可视化控制台与 API 接口说明

部署完成后，直接通过浏览器访问你的 Worker 域名（如 https://hf-waker.yourname.workers.dev/）即可进入控制台。

API 路由一览

若设置了 SECRET_KEY，调用以下 API 时需在 URL 参数中携带 ?key=你的密码 或在请求头中携带 X-Secret-Key: 你的密码。

常用 API 调用示例

1. 智能唤醒全部休眠中的 Space（跳过正在运行的 Space）：

   curl "[https://hf-waker.yourname.workers.dev/wake?key=my_super_secret_123&user=Admin&reason=日常巡检](https://hf-waker.yourname.workers.dev/wake?key=my_super_secret_123&user=Admin&reason=日常巡检)"
   

2. 指定单独唤醒某一个 Space：

   curl "[https://hf-waker.yourname.workers.dev/wake?key=my_super_secret_123&repo=alice/space1](https://hf-waker.yourname.workers.dev/wake?key=my_super_secret_123&repo=alice/space1)"
   

3. 无视运行状态，强制重启某一个卡死的 Space：

   curl "[https://hf-waker.yourname.workers.dev/wake?key=my_super_secret_123&repo=alice/space1&force=true&reason=容器卡死强制重启](https://hf-waker.yourname.workers.dev/wake?key=my_super_secret_123&repo=alice/space1&force=true&reason=容器卡死强制重启)"
   

📲 Telegram 通知预览

🤖 自动巡检通知

🤖 HF Space 自动巡检保活

⏰ 北京时间 2026-10-14 08:00:02
🛰 Space 状态明细：
 • alice/space1 🟢 运行中 (RUNNING，已跳过)
 • alice/space2 🔄 已唤醒 (原状态: SLEEPING)
 • bob/space3 🟢 运行中 (RUNNING，已跳过)

📊 统计：唤醒 1 个 | 跳过 2 个 | 失败 0 个
✅ 巡检保活 完成 🎉

🖐 手动操作通知

🖐 HF Space 手动保活 (强制重启)

👤 触发人: WebDashboard
📝 原因: Web面板-强制重启
⏰ 北京时间 2026-10-14 14:35:10
🛰 Space 状态明细：
 • alice/space1 🔄 已唤醒 (原状态: RUNNING)

📊 统计：唤醒 1 个 | 跳过 0 个 | 失败 0 个
✅ 操作 完成 🎉

🙏 致谢与灵感来源 (Acknowledgements)

• 感谢 @oversizexl 开源的原项目 oversizexl/hf-waker 提供的核心设计思路与通知模板。本项目在其基础上完成了向 Cloudflare Workers Serverless 架构的移植与功能扩展。

📄 License

本项目基于 MIT License 开源。如果这个项目帮到了你，欢迎给本项目及原项目点个 🌟 Star 支持一下！