docs/PUSH_DEBUG.md

# Push → 远端部署 → 监控 → 测试（循环直到远端成功）

**原则**：只有 **push 上去** 才会触发 HF 部署；只有 **远端** 构建成功、应用 RUNNING、且压力测试全部通过，才算完成。本地改完必须不断 push、用远端日志和测试结果 debug，直到远端成功才能停。

---

## 1. 循环流程

```
修代码 → git add / commit → git push
         ↓
HF 开始构建/部署
         ↓
实时监控远端：--logs build / --logs run，或 --wait-running
         ↓
跑压力测试：--test（必要时 --url 与 --expect）
         ↓
全部通过？ → 停
有失败？   → 根据日志/现象修代码 → 回到「修代码」再 push
```

---

## 2. 轮询方式（正确做法）

用 **HF API** 看远端状态和日志，不要只轮询应用 URL：

- **Runtime 状态**：`get_space_runtime`（脚本里 `--wait-running` / `--until-ok` 会轮询）。
- **构建日志**：`GET .../spaces/<SPACE_ID>/logs/build`（需 `Authorization: Bearer $HF_TOKEN`）。
- **运行日志**：`GET .../spaces/<SPACE_ID>/logs/run`（同上）。

一轮流程：push → 用 API 等 RUNNING（或看 build 失败）→ 跑测试 → 失败则看 run/build 日志尾修代码 → 再 push，循环直到测试全过。

### 2.1 推送（触发部署）

```bash
git add -A
git commit -m "fix: 简短描述"
git push origin main
```

（若 Space 在别的分支，把 `main` 换成该分支。）

### 2.2 持续看远端状态（不退出）

用 curl + Bearer token 周期性拉 run 日志并查应用 URL，适合观察部署过程：

```bash
# 从 .env 读 HF_TOKEN 时直接运行（脚本会自动加载 .env）
python3 scripts/monitor_and_test.py --watch

# 每 30 秒轮询一次
python3 scripts/monitor_and_test.py --watch --watch-interval 30
```

会循环打印：当前 stage、GET APP_URL 结果、run 日志尾部。Ctrl+C 结束。

### 2.3 用 API 看远端日志（debug 用）

```bash
# 流式拉取构建日志（推送后看）
HF_TOKEN=你的token python3 scripts/monitor_and_test.py --logs build

# 流式拉取运行日志（看容器输出）
HF_TOKEN=你的token python3 scripts/monitor_and_test.py --logs run
```

等价 curl（便于脚本里用）：

```bash
# Get container logs (SSE)
curl -N -H "Authorization: Bearer $HF_TOKEN" \
  "https://huggingface.co/api/spaces/tao-shen/HuggingRun/logs/run"

# Get build logs (SSE)
curl -N -H "Authorization: Bearer $HF_TOKEN" \
  "https://huggingface.co/api/spaces/tao-shen/HuggingRun/logs/build"
```

`--until-ok` 在 build/run 或测试失败时会自动拉取并打印日志尾部，无需单独跑上面命令。

### 2.4 等 RUNNING / 等 URL 就绪后跑完整测试（一键「远端是否成功」）

**方式 A：有 HF_TOKEN 时**（推荐，可看 API 状态）

```bash
# Demo 或默认 Space
HF_TOKEN=你的token python3 scripts/monitor_and_test.py --wait-running --test

# 自定义 expect 内容
HF_TOKEN=你的token python3 scripts/monitor_and_test.py --wait-running --test \
  --url https://你的用户名-你的Space名.hf.space \
  --expect "ttyd"
```

**方式 B：无 HF_TOKEN 时**（只轮询 URL 直到页面出现期望内容）

```bash
python3 scripts/monitor_and_test.py --wait-url --test \
  --url https://你的用户名-你的Space名.hf.space \
  --expect "ttyd" --max-wait 900
```

脚本会先轮询直到 GET 200 且 body 含你给的 `--expect`，再跑：基础 GET、压力请求、多轮持久化检查。**全部通过才 exit 0**，任一失败则 exit 1。

### 2.5 不等待、直接测当前页面（Space 已 RUNNING 时）

```bash
python3 scripts/monitor_and_test.py --test
# 或
python3 scripts/monitor_and_test.py --url https://xxx.hf.space --test --expect "ttyd"
```

---

## 3. 建议用法（复制粘贴循环）

1. **推送后**：开一个终端拉构建日志，确认无报错。
   ```bash
   HF_TOKEN=xxx python3 scripts/monitor_and_test.py --logs build
   ```

2. **构建完成后**：另一个终端等 RUNNING 并跑测试。
   ```bash
   HF_TOKEN=xxx python3 scripts/monitor_and_test.py --until-ok --url https://tao-shen-huggingrun.hf.space --expect "ttyd"
   ```

3. 若 **测试失败或一直 503**：用 `--logs run`（以及 `--logs build`）看容器内报错，修代码后：
   ```bash
   git add -A && git commit -m "fix: ..." && git push origin main
   ```
   然后重复 1–2，直到测试全部通过。**只有远端全部通过才算数。**

---

## 4. 环境变量速查

| 变量 | 说明 |
|------|------|
| `HF_TOKEN` | 拉日志、查 runtime 状态、等 RUNNING 时必填 |
| `SPACE_ID` | 默认 `tao-shen/HuggingRun`，也可用 `--space-id` |
| `APP_URL` | 默认 `https://tao-shen-huggingrun.hf.space`，也可用 `--url` |

所有「成功」以 **远端** 为准：构建成功 + 应用 RUNNING + 压力测试全部通过。