wiki-book-gh-pages-deploy

name	wiki-book-gh-pages-deploy
description	Use when wiki-book 的 GitHub Pages 部署失败或 push 后无 run.

Wiki-Book GH Pages 部署修复

wiki-book (~/wiki-book, repo QianJinGuo/wiki-book) 的 GitHub Pages 站点 = wiki.jinguo.tech。 每次 push 到 main 触发 .github/workflows/deploy.yml（build → actions/upload-pages-artifact → deploy-pages@v4）。

两种失败模式（先区分）

1. build job 失败 → 代码/依赖问题，看 --log-failed 里的构建错误。
2. deploy job 卡死：日志循环 Current status: deployment_queued 约 12 分钟后 ##[error]Timeout reached, aborting! → GitHub Pages 后端队列问题，不是仓库问题。
3. push 后 0 个 run：commit 在 origin/main 上但 gh run list --commit <sha> 为空 → GitHub 丢了 push 事件（2026-08-07 实测：reflog 显示 update by push，但 0 run）。

诊断步骤

# 1. 最近 runs
gh run list --repo QianJinGuo/wiki-book --limit 6

# 2. 失败日志（定位是 build 还是 deploy 卡死）
gh run view <run_id> --repo QianJinGuo/wiki-book --log-failed | tail -40

# 3. 确认 push 是否到达 + 是否触发 run
git -C ~/wiki-book ls-remote origin main        # 远程 SHA
git -C ~/wiki-book rev-parse HEAD               # 本地 HEAD
gh run list --repo QianJinGuo/wiki-book --commit <sha>   # 空 = push 事件丢失

修复：workflow_dispatch 重跑

gh workflow run "Deploy to GitHub Pages" --repo QianJinGuo/wiki-book --ref main
# 轮询等待
gh run list --repo QianJinGuo/wiki-book --limit 3

验证

gh run view <new_run_id> --repo QianJinGuo/wiki-book --json jobs
# 期望 build:success + deploy:success（deploy 通常 16s，build ~3min）
curl -s -o /dev/null -w "%{http_code}" https://wiki.jinguo.tech/   # 200

预防（已内置）

~/.hermes/scripts/sync-wiki-book.sh 第 7b 段：push 后 60s 内轮询 gh run list --commit $head_sha，没 run 则自动 gh workflow run 兜底。

坑

• gh run list --commit <sha> 用 --json databaseId -q '.[0].databaseId // empty'， 空数组时 jq 输出空字符串（不是 "null"），避免误判。
• gh 认证走 keyring；cron 环境若 keyring 不可用，7b 段会打 WARN 并跳过，不崩。
• GH Pages 失败不影响 Docker(8002)/CF Pages(jinguo.tech)——三环境独立部署。
• GitHub 状态页 githubstatus.com 当时显示 All Systems Operational，状态页滞后， 别依赖它判断队列故障。