keepalive/README.md

hf-keepalive 保活项目配置

本目录包含用于 GitHub Actions 的保活配置文件，用于防止 Hugging Face Space 因长时间无访问而休眠。

使用方法

1. 创建保活仓库

方式 A：Fork 现有项目（推荐）

1. Fork https://github.com/wankuzidi/hf-keepalive
2. 跳到步骤 2

方式 B：创建新仓库

1. 在 GitHub 创建新仓库（如 my-hf-keepalive）
2. 复制本目录下的文件到新仓库：
   • .github/workflows/keep-alive.yml
   • keepalive.py
   • spaces.txt

2. 配置 Space URL

方式 A：使用 GitHub Variables（推荐）

1. 进入仓库 Settings → Secrets and variables → Actions → Variables
2. 点击 "New repository variable"
3. 添加变量：
   • Name: HF_SPACES
   • Value: https://your-username-your-space-name.hf.space
   • 多个 Space 用逗号分隔

方式 B：编辑 spaces.txt 直接编辑 spaces.txt 文件，每行一个 Space URL：

https://your-username-grok2api.hf.space
https://your-username-another-space.hf.space

3. 配置 HF Token（仅私有 Space 需要）

如果你的 Space 是私有的：

1. 获取 HF Token：https://huggingface.co/settings/tokens
2. 进入仓库 Settings → Secrets and variables → Actions → Secrets
3. 添加 Secret：
   • Name: HF_TOKEN
   • Value: 你的 Hugging Face Access Token

4. 调整保活频率

编辑 .github/workflows/keep-alive.yml：

on:
  schedule:
    # 推荐配置（每 12 小时）
    - cron: "0 */12 * * *"
    
    # 其他选项：
    # - cron: "0 */6 * * *"   # 每 6 小时
    # - cron: "0 * * * *"     # 每小时
    # - cron: "*/30 * * * *"  # 每 30 分钟（不推荐）

5. 启用 GitHub Actions

1. 进入仓库的 "Actions" 标签
2. 如果看到提示，点击 "I understand my workflows, go ahead and enable them"
3. （可选）点击 "Run workflow" 手动测试一次

注意事项

⚠️ 频率建议

• 推荐：每 12 小时（0 */12 * * *）
• 最低：每 6 小时（0 */6 * * *）
• 不推荐：少于 30 分钟（可能被视为滥用）

⚠️ GitHub Actions 配额

• 公开仓库：无限制
• 私有仓库：每月 2000 分钟免费

⚠️ Hugging Face 政策

• 遵守 HF 的使用条款
• 不要过度频繁访问
• 建议配合 Persistent Storage 使用

监控保活状态

在仓库的 "Actions" 标签中可以查看：

• 最近的运行记录
• 成功/失败状态
• 详细日志

故障排查

Workflow 未运行

• 检查 Actions 是否已启用
• 检查 cron 表达式是否正确

访问失败

• 检查 Space URL 是否正确
• 私有 Space 需要配置 HF_TOKEN
• 查看 Actions 日志了解具体错误

Space 仍然休眠

• 确认保活项目正常运行
• 检查 Space 是否启用了 Persistent Storage
• 考虑增加访问频率（但不要太频繁）