Clawline — 04-02~04 开发站点部署¶

概述¶

三天内完成了 Clawline Web 开发环境的部署、排障和流程规范化。过程中踩了"部署成功 ≠ 服务可用"的多个典型坑，最终沉淀出标准部署流程和 Service Worker 更新机制。

04-02：首次完整部署（21:35–21:37）¶

Dad 决策："提交所有代码并更新开发环境"

部署方案： - client-web：本地构建后同步 dist 到 Owl 静态目录 - Channel 插件：同步后重启 gateway - 关键发现：Owl 上 Web 端是 Caddy 直接 serve dist，不是 pm2 跑 dev server，更新 dist 后无需重启 pm2

21:37 部署完成，channel 插件同步并重启 gateway。

04-03 上午：部署了但站点不可用（08:12–08:30）¶

08:28 Dad 反馈：看不到变化，slash 命令报错
根因：pm2 在运行但没有任何进程——典型的"部署成功 ≠ 服务可访问"
解决：pm2 start + pm2 save（防止重启后进程列表丢失），08:30 服务恢复

04-03 上午：移动端缓存问题（08:33–08:47）¶

Dad 手机上看到版本 f7131a49，无法强制刷新，功能与最新代码不一致
根因：PM2 服务挂掉导致 sw.js 更新检查失败，旧 SW 继续控制页面
SW 缓存策略：index.html → network-first，JS/CSS → cache-first
解决：重新构建生成新 hash（f7131a49 → 69205d70），08:47 Dad 确认更新

04-03 晚：更新错实例（20:33–20:35）¶

Dad 反馈管理面板没更新，Bot 发现部署目标搞错了
Bot 更新了 relay 服务器上的 dist，但 gw.dev.dora.restry.cn 实际指向本机 pm2 serve 的另一份 dist
解决：同步到真正被 serve 的目录
经验：部署前必须确认域名 → 反向代理 → 进程 → 文件目录的映射关系

04-03：缓存策略确认¶

JS/CSS:     Cache-Control: max-age=31536000, immutable
index.html: Cache-Control: no-cache

新构建必须依赖文件名 hash 变化来更新缓存，构建产物必须完整替换。

04-04：部署流程规范化（10:53）¶

Dad 决策：以后不要再用 rsync 直接部署源码，走标准流程；把更新手册写进 README。

新标准流程：

本地 commit + push
SSH 到测试服务器 git pull
同步到 extensions（如需要）
清 jiti 缓存 → 重启 Gateway

按 README 重装时遇到 Cannot find module 'ws'（clone 后忘装依赖），npm install 后成功。10:57 验证通过。

04-04：SW 更新机制改造（23:24）¶

Dad 决策：SW 有更新时弹出更新窗口，手动点击更新。

问题：install 阶段直接 skipWaiting() 导致 usePWAUpdate 检测不到 updateAvailable。

方案：移除自动 skipWaiting()，改为监听 SKIP_WAITING 消息后才触发：

// 新逻辑：仅在用户确认时 skipWaiting
self.addEventListener('message', (event) => {
  if (event.data?.type === 'SKIP_WAITING') {
    self.skipWaiting()
  }
})

支持"检测新版 → 弹 Banner → 用户点击更新"。23:26 部署完成。

04-04：全链路验证（12:39–12:44）¶

Dad 要求完整检查本地代码、Owl 插件、浏览器缓存/SW、全链路。验证结果：页面登录正常，消息发送 → WS 传输 → agent 回复 → 客户端接收，全链路通过。

踩坑总结¶

坑	现象	根因	方案
服务没跑	页面打不开	pm2 无进程	`pm2 start` + `pm2 save`
更新错实例	Bot 说更新了 Dad 说没变	域名指向另一份 dist	核对域名→代理→目录映射
旧缓存	hash 变了手机端仍异常	SW/浏览器缓存	重新 build + 检查 SW
版本对但功能坏	版本号一致功能异常	代码 bug 非缓存	排查逻辑而非归因缓存

里程碑总览¶

日期时间	事件
04-02 21:37	Owl 开发环境首次完整部署
04-03 08:30	修复"部署了但服务没跑"
04-03 08:47	移动端版本号确认更新
04-03 20:35	修复"更新错实例"
04-04 10:55	部署流程规范化（告别 rsync 直传）
04-04 10:57	按 README 重装插件成功
04-04 12:44	全链路联合验证通过
04-04 23:26	SW 手动更新机制上线

关键环境¶

开发站点：web.dev.dora.restry.cn
管理面板：gw.dev.dora.restry.cn
版本号演进：f7131a49 → 69205d70 → ee52a853