云端部署Node 后端PM2PWA生产环境

向既有生产后端安全增补模块(cloud-module-safe-deploy)

把新功能模块挂进你云服务器上「已经在跑业务」的 Node 后端目录,全程零破坏;并在上线后排查「设备连不上 / 页面登录失败」。

一、这个 skill 是做什么的

很多用户的云服务器上早就有一个正在跑核心业务 Node 后端目录(名字常叫 cloud-backend、server、app)。当你想给这个后端「加一个新功能模块」时,最大的风险不是写不出代码,而是手一抖把用户正在跑的线上业务覆盖或删掉。

这个技能就是一套「安全增补」流程:只允许你新增一个自己的子目录 + 在入口文件加一行 require,其余一个字节都不碰。上传时只传你自己的子目录,绝不传父目录,从根上杜绝误删风险。

除此以外,它还给出一套「上线后故障的分层定位法」:用两条简单的访问请求把问题锁死在「服务端坏了 / 端口没放行 / 客户端缓存」中的某一层,避免瞎猜;并专门讲解 PWA(带 Service Worker 的网页)缓存把用户永久锁在旧版这个经典坑。

二、什么时候用它

三、前置条件 / 准备

四、具体用法(步骤)

第 1 步:先取证,摸清真实结构(只读,零风险)

在给出任何「目录不对 / 该删」的结论之前,必须先把这组只读命令跑一遍、拿到输出。pm2 describe 里的 script path 和 exec cwd 是唯一权威——它决定 PM2 从哪儿启动、相对路径基准,别靠目录名直觉猜。

pm2 describe <appname> | grep -E "script path|exec cwd|status|restarts" ls -la /opt/<app>/ ls -la /opt/<app>/<backend>/

第 2 步:只新增子目录 + guarded require

本项目只允许「新增一个自己的子目录」+「在入口文件加一行受保护引用」。这样即使模块缺失,既有业务也不受影响:

# ✅ 只传自己的子目录,不传父目录 scp -r ./my-module root@HOST:/opt/app/backend/ # 入口文件用 guarded require(模块缺失也不影响既有业务) let myModule = null; try { myModule = require('./my-module/index'); } catch (e) { myModule = null; }

第 3 步:从最温和的重启开始

先 pm2 restart,无效才升级为 delete + start(后者不删任何文件,只重建进程记录,安全)。

cd /opt/<app>/<backend> # 必须先进正确的 cwd pm2 restart <appname> --update-env pm2 logs <appname> --lines 30 --nostream

第 4 步:上线后故障分层定位

用两条 curl 把问题锁到某一层(见第五节示例)。再确认接口返回的 version 字段是不是你刚传的版本——版本号对不上 = 传的还是旧文件。

第 5 步:PWA 缓存坑处理

若手机端仍报旧版错误、清历史记录无效、换无痕窗口却正常,多半是 sw.js 用了 cache-first 且缓存名恒定。改法是:① 每次发布把缓存名改名;② 接口永不缓存;③ 改成 network-first(断网才回缓存)。给用户的话术:删桌面图标 → 浏览器设置清除该网站数据 → 重新打开;或先用无痕窗口验证。

五、可直接照用的示例

你直接对 AI大模型或AI智能体 说:「帮我把这个新模块挂到我服务器上那个 /opt/app/backend 的后端里,千万别动我原来的业务。」

AI大模型或AI智能体 会:先 pm2 describe 看清真实结构 → 把你的模块只放进 backend/my-module/ 子目录 → 只在 server.js 加一行 try{require('./my-module')} → 只 scp 这个子目录上去 → 用温和的 pm2 restart 重启。全程不碰你原来的任何文件。

你直接对 AI大模型或AI智能体 说:「模块上线后手机页面登录失败,但服务端好像正常。」

AI大模型或AI智能体 会:用两条请求定位——

curl http://127.0.0.1:<PORT>/api/<module>/ # ① 本机 curl http://<公网IP>:<PORT>/api/<module>/ # ② 公网

判读:①✅②✅=服务正常,问题在客户端;①✅②❌=端口未放行,去云控制台安全组加规则;①❌②❌=模块没挂载或进程崩了,看 pm2 logs。再查接口返回的 version 对不对得上。

你直接对 AI大模型或AI智能体 说:「服务端都升级了,手机端还是报旧版的登录错误。」

AI大模型或AI智能体 会:判断是 PWA Service Worker 缓存作祟。先让你用「无痕窗口」打开一次:能进就确认是缓存问题。然后改 sw.js 为 network-first 并每次发布改名缓存,并指导你把桌面图标删掉、清除该网站数据后重新打开。

六、常见注意 / 避坑

最高红线:绝对禁止 rm -rf <后端目录>、把后端目录往上层摊平、或 scp 父目录去覆盖。只传自己的子目录,其余一个字节都不碰。不要仅凭「目录名像脚手架」就断言用户放错了位置。

七、相关 skill / 延伸

← 返回 SKILL 库