WorkBuddy 官网部署实战白皮书

1. 摘要与关键指标

本白皮书记录一次完全由 WorkBuddy 驱动的官网部署实战：交付物是一个多页面 Web 应用 （昆仑洞天 · 国风创作工坊 Ω⁷，含完整交互版本与七个历史版本归档）， 目标是把作品同时发布到 WorkBuddy 应用通道与 自有官网 huodouai.com。 全过程无人工敲命令、无 SSH 交互，全部通过 Agent 调用云 API 完成。

实战最有价值的部分不是成功路径，而是十四个真实踩中的坑——它们全部具备「单元测试通过、 代码逻辑正确，但在真实环境里依然失败」的共同特征。这些坑位已固化为 元法则 META-AXIOM-E2E-VERIFICATION-V1。

2. 场景：一条链接为什么不够

「把作品部署到官网」这句话在实操中会分裂成两个诉求，而它们的技术路径完全不同：

3. 通道选型：应用发布 vs 官网自建

3.1 应用发布通道（一分钟上线）

调用站点部署能力即可完成，产物与应用卡片一一对应：

deploy(directory, language="static|node", startCmd, domainPrefix, appName)

3.2 官网自建通道（TAT 远程执行）

本地无 SSH 配置，官网文件只能通过腾讯云 TAT（远程助手）写入实例：

4. 传输层：分块、校验与解包

整站体积 tar.gz 后约 336 KB，base64 膨胀至 454 KB，远超单命令上限，必须分块：

# 本地：打包 → base64 → 每块 40KB
tar -czf site.tar.gz kunlun projects
base64 -w0 site.tar.gz            # 454 KB

# 远端：逐块追加（顺序敏感，必须串行）
printf '%s' '<40KB chunk>' >> /tmp/site.b64
# ... 共 12 块 ...

# 远端：解码 → 解压 → 落地
base64 -d /tmp/site.b64 | gunzip | tar -xzf - -C /www/wwwroot/huodouai.com

5. 十四个真实坑位

以下每一条都是本次实战真实撞上的，现象、根因与解法均可复现。

6. 验证体系：端到端真值律

本次采用三层验证，每层都用真实环境而非推断：

回归清单（本次实际执行）

7. 可复用脚本骨架

7.1 一条命令的执行与回读

def fire(name, script, timeout=120):
    req = models.CreateCommandRequest()
    req.CommandName = name
    req.CommandType = "SHELL"
    req.Content = base64.b64encode(script.encode()).decode()
    req.Timeout = timeout
    cid = client.CreateCommand(req).CommandId

    inv = models.InvokeCommandRequest()
    inv.CommandId = cid
    inv.InstanceIds = [INSTANCE]
    inv.Username = "root"
    iid = client.InvokeCommand(inv).InvocationId
    return iid   # 不轮询状态，改由 HTTP 回读日志校验

7.2 分块传输与落地

def deploy(tar_path, remote_root, log_path, chunk=40000):
    b64 = base64.b64encode(open(tar_path, "rb").read()).decode()
    fire("init", f"rm -f /tmp/site.b64; : > {log_path}")
    for i in range(0, len(b64), chunk):
        fire(f"c{i}", f"printf '%s' '{b64[i:i+chunk]}' >> /tmp/site.b64")
    fire("extract",
         f"base64 -d /tmp/site.b64 | gunzip | tar -xzf - -C {remote_root}; "
         f"echo EXTRACT_RC=$? >> {log_path}")

7.3 用 HTTP 回读校验

curl -s "https://<host>/<path>/_deploy.log"   # 远端命令的真实输出

要点：让远端命令把结论写进公网可读的文件，是绕过「无状态轮询」与「异步调度不确定性」的最省事解法， 且校验路径与用户实际访问路径完全一致。

7.4 小文件直写：heredoc 优于超长单参数

# 单个 ≤ ~30KB 的文件：一条命令搞定，绕开单参数长度与 base64 二次膨胀
cat > /www/wwwroot/huodouai.com/whitepaper/report.html <<'EOF_DOC'
<!DOCTYPE html> ... </html>
EOF_DOC
wc -c < /www/wwwroot/huodouai.com/whitepaper/report.html

注意 heredoc 定界符要用带引号的形式（<<'EOF'），否则内容里的 $、反引号会被 shell 展开。

8. 时间与成本实测

可复用资产：site.tar.gz（全站快照）、deploy_to_huodouai.py（分块部署）、e2e/（可复跑的端到端脚本集）。

9. 元法则：交付即验证

本次十个坑位共同指向一条规则，已固化为最高位阶元法则并写入本体：

该法则同时被写入核心公理集（新增第 9 组 E2E-VERIFICATION）与哈希账本，使其可被审计与复算。

10. 落地检查清单

1. 投放前：目标目录 ls 一遍，确认不覆盖既有内容；优先选择全新路径。
2. 传输前：确认云 SDK 可用（换镜像源）；优先官方 SDK，不自造签名。
3. 传输中：分块 ≤ 40 KB，串行追加，每块留日志。
4. 落地时：解码 / gzip / tar 三步校验全绿再落地；先备份再覆盖。
5. 落地后：① 作品路由逐条探针；② 既有页面全量回归；③ 真实浏览器打开首屏；④ 产物回读数值。
6. 缓存：静态资源加版本号 + no-cache，否则「已修复」无法被验证。
7. 导航：在官网首页与相关列表页加入口，并回读确认链接真实可达。
8. 留痕：锁档事件写本体、哈希入账本、成果同步云端活版本。

附录 A · 命令速查

# 一、应用通道部署（Node 服务端）
deploy(directory=..., language="node", startCmd="node server.js",
      domainPrefix="<slug>", appName="...")      # → https://<slug>.app.workbuddy.host/?sharecode=XXXX

# 二、官网落盘（TAT）
base64 -w0 site.tar.gz | split -b 40000 -           # 本地分块
# 远端逐块：
printf '%s' '<chunk>' >> /tmp/site.b64
# 远端落地：
base64 -d /tmp/site.b64 | gunzip | tar -xzf - -C /www/wwwroot/huodouai.com

# 三、校验
curl -s "https://<host>/<path>?sharecode=XXXX" | head -c 200   # 判定内容而非状态码
curl -s "https://<host>/<path>/_deploy.log"                  # 回读远端命令结论

# 四、回归
for p in / /a.html /b.html; do curl -s -o /dev/null -w "%{http_code} $p\n" "https://<host>$p"; done