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`：

```yaml
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
- 考虑增加访问频率（但不要太频繁）