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 推送（触发部署）

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

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

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

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

# 从 .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 用）

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

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

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

# 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 状态）

# 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 直到页面出现期望内容）

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 时）

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

---

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

1. 推送后：开一个终端拉构建日志，确认无报错。

   HF_TOKEN=xxx python3 scripts/monitor_and_test.py --logs build
   

2. 构建完成后：另一个终端等 RUNNING 并跑测试。

   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）看容器内报错，修代码后：

   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 + 压力测试全部通过。