MVP Deployer

轻量 MVP 部署控制面：AI 写完代码 → zip 打包 → POST → 秒级 HTTPS 上线。

概述

quokka 设计的极简部署系统，PM2 跑业务进程、Caddy 动态反代、共享 Postgres 容器（mvp-postgres super user mvpadmin）。RESTful API 收 zip + manifest，自动解压 / 装依赖 / 启进程 / 绑域名 / 签 TLS。

双环境

	内网（claw-bot）	云端（Azure China）
主机	192.168.31.141	163.228.243.161
API	https://deploy.nexora.restry.cn	https://deploy.mvp.restry.cn
泛域名	*.nexora.restry.cn	*.mvp.restry.cn
Token	`/opt/mvp-deployer/.credentials`	vault `MVP_DEPLOYER__TOKEN`
SSH（管理员）	—	`ssh claw@163.228.243.161`（key auth）

角色边界：普通 agent / 调用方 永远走 HTTPS API + Bearer token；管理员 才 SSH。

当前 8 个服务（packsmith 05-09 删）

#	项目	host	端口
1	cspy	cspy.mvp.restry.cn	3791
2	echo	echo.mvp.restry.cn	3795
3	image-studio	design.mvp.restry.cn	3789
4	image-studio-test	test.design.mvp.restry.cn	3790
5	packhorizon	packhorizon.mvp.restry.cn	3793
6	shutiao-world	shutiao-world.mvp.restry.cn	3456
7	wx-gateway	wx.mvp.restry.cn	3794
8	menshen-ui	menshen.mvp.restry.cn	3812

mvp-deployer 自身不进列表（不能自部署）。realtime-voice 04-28 删除 —— manifest 缺失 / 没 Caddy 路由 / arphan PM2 进程，DELETE /api/deploy/realtime-voice 一并清 PM2 + 文件。packsmith 05-09 删除 —— 业务下线，DELETE /api/deploy/packsmith?removeFiles=true 一把清进程 + Caddy 路由 + /opt/mvp-apps/packsmith/，剩 8 个活跃服务 + 1 个新加的 menshen-ui 共 9 槽。

2026-05-14 — `vault-to-manifest-env.py` + 第 11 铁律「env 值级 fp diff」（fries）

承接 5-11 P0-B vault 集成上线后第一次实战，发现 vault export -p <project> 输出是给 shell source 用的而非给 dotenv 解析器读的，含 3 种 shell-quoting，mvp-deployer / dotenv 加载都不解：

Quoting	例	表象
`\` backslash escape	`DATABASE_URL=postgresql://...?schema=public` → `\?schema=public`	URL 多了反斜杠，Prisma 报无效 connection string
`$'...'` ANSI-C quote	`INSTANCE_LABEL=$'Nexura M-h\216\206M-i\230M-3'`	中文变 mojibake (`Nexura è��é�³`)
`M-h` latin-1 字节	UTF-8 续字节 `0x8E 0x86` 在 ANSI-C 内被显示为 `\216\206`，但前导字节 `0xE8` 显示成 `M-h`	parser 没把 `M-h` 当字节序列前导，整字符串 UTF-8 decode 失败

新脚本 ~/.hermes/skills/mvp-deployer/scripts/vault-to-manifest-env.py 一次性处理三种 quoting：unescape \? \[ \"、decode $'...' 内嵌 \nnn 八进制、把 M-h latin-1 字节并入字节序列后整体 UTF-8 decode。处理后 19 个变量 DATABASE_URL / APPS_JSON / INSTANCE_LABEL 等全部干净。配套：

vault export 本地超时从 10s 改 30s（mac 上较慢）
Python 3.14 docstring 里 \? SyntaxWarning fix
ANSI-C 输出含 raw 字节，不能 utf-8 decode，需 binary capture 后再统一 decode

「mvp-deployer 回滚把 .env 重置成默认推导名」复现 + 启示

5-14 部署期间 deploy 失败 + 回滚后，第二次 deploy 的 .env 里 DATABASE_URL 变成 wx-gateway-pucs（中划线，指向不存在的库），而真值是 wx_gateway_pucs（下划线）。中划线版本是 mvp-deployer 从 project name 推导出来的默认值——rollback 时把 .env 重置成它认为的”应该”。手动改 .env + pm2 delete + start 重读才恢复，期间 pm2 reload 不重新读 .env。已加入 wx-gateway 排查清单。

新铁律 11：env 必须做值级 SHA256 fp diff，不只是 key 存在性

5-14 部署 wx-gateway 时 daddy 当场骂：“上次让你检查 19 个变量，结果只比 key 不比值，照样翻车。” 复盘成立——“key 存在” ≠ “值正确”。补做：写 fp 对比脚本逐项把 vault 值 vs prod .env 真值 SHA256 fp 比对，19 项 fp 全 match 才放行 deploy。沉淀进 mvp-deployer skill 第 11 条铁律：

任何 deploy 前 env 校验，必须 fp 比对值，而不是只看 key 存在性。 误报场景（如本次 DATABASE_URL 里 user 名 image_studio 是历史共用 role）由 fp 一致直接洗清，省去人脑猜测。

同时教训：诊断时不要看 image_studio 这种名字就喊”vault 串了”，先 fp 对比拿事实再说。

2026-05-10 部署轮询日志泄露 prod secrets（cspy 部署事故）

cspy 5-10 部署期间，task 轮询接口回的 phase log 把整 zip 解压后的 33 条 prod env（含 NEXTAUTH_SECRET / OAUTH_STATE_SECRET / WX_GATEWAY_SECRET / INTERNAL_TOKEN_SECRET / SEED_ADMIN_PASSWORD / RELAY_ADMIN_TOKEN / KUMA_PASSWORD / WECHAT_APPSECRET / MM_USER_TOKEN 等）以明文喷到了发起方（Discord/Hermes 流）。

短期处置：发起方把这批 secret 全部轮换 + 重启业务进程。deployer 侧待修：phase log 输出经过的所有 env / 文件内容必须 mask *_SECRET / *_TOKEN / *_PASSWORD / WECHAT_APPSECRET 等模式，至少把值替换为 <redacted>，参考 audit log 的脱敏处理。当前 inventory 已脱敏，但部署 task log 路径漏了。

铁律：高敏感 secret 进 vault 走 Path B（服务器 ~/.credentials/.env），发起方 manifest 不包含。但即便如此，部署 task 的 build/postDeploy 阶段如果 echo 了 .env 或 printenv，仍会回流。修 deployer 之前，调用方能做的就是：部署完立刻 grep task log 看是否泄露，发现就立刻轮换。

2026-05-09 XMRig 入侵事件 + 4 层硬化（ottor）

⚠️ 安全事件复盘 —— 仅描述行为与防御响应，不复现攻击代码。

检测

ottor 例行扫 deploy.mvp.restry.cn 主机时发现 /var/tmp/cpu-logind 一个 ELF 二进制：

项	值
文件	`/var/tmp/cpu-logind`
程序	XMRig 6.26.0（Monero CPU miner）
sha256	`b20f39fc...`（已记入 IOC）
mtime	2026-03-28（说明潜伏 ~6 周）
运行时	2026-05-08 起拉满 CPU
pool	`185.132.53.73:443`
钱包	XMR 地址记入 IOC，未在此存档

根因

mvp-deployer 的 POST /api/exec/<project> 端点本质是 RCE-as-a-service：任何持有 DEPLOYER_TOKEN 的人都能在服务器 spawn 任意 bash
API 端口 9800 当时绑 0.0.0.0，外网可达
token 短期内有过 leak 嫌疑（多 agent 上下文流转、未轮换）
攻击者拿到 token → 调 /api/exec 下载 + 落地 + 启动 XMRig

处置（同日完成）

kill -9 cpu-logind，rm /var/tmp/cpu-logind
mount -o remount,noexec,nosuid /var/tmp（固化到 fstab）
iptables -A INPUT -p tcp --dport 9800 -s 127.0.0.1 -j ACCEPT + 默认 DROP；iptables-persistent 持久化
轮换 DEPLOYER_TOKEN 到 8b4413f7…f12e4b（新值进 vault，撤旧值）

4 层硬化（commits）

commit	内容
`d09175e`	`lib/audit.js` —— NDJSON 审计日志，每个 `/api/exec` / `/api/deploy` / `/api/deploy/<name>` / `/api/db/provision` / `/api/status` / `/api/inventory` / `/api/logs/<name>` 调用写一行（ts / ip / ua / tokenFp(sha256 前 12 位) / route / 完整 cmd / exitCode / fileSha256+fileSize），失败鉴权写 `tokenFp:"INVALID"` + `badTokenPrefix`（前 8 位）。落 `/var/log/mvp-deployer/audit-YYYY-MM-DD.log`（CST 日期分文件，daily logrotate ×90 留存），写不进去回落 `~/.mvp-deployer-audit/`；新增 `GET /api/audit?date=YYYY-MM-DD&limit=200&grep=xxx` 返 ndjson
`b522231`	拆 `AUDIT_READ_TOKEN`（独立于 `DEPLOYER_TOKEN`，只能读审计日志、不能 exec/deploy）+ `TRUST_PROXY=true` 让 Express 信任 Caddy `X-Forwarded-For`，审计日志记真 client IP 而不是 `127.0.0.1`
`31358cf`	`lib/ipAllowlist.js` —— CIDR 白名单中间件；非白名单返 403 + body `{"error":"forbidden","yourIp":"<x.x.x.x>"}` 方便误拦排查；当前白名单 `[1.202.55.49, 116.147.250.4]`（Daddy 两条家宽出口）
`70dbefd`	`ecosystem.config.js` env 注入新增 `AUDIT_READ_TOKEN` / `TRUST_PROXY` / `IP_ALLOWLIST`，pm2 重启走标准流程

Hermes 出口 IP ≠ Azure VM IP（IP_ALLOWLIST 验证踩坑，fries→ottor 联调）

合上白名单后从 hermes-vm（Azure 中国，自报 20.196.210.217）调 /api/exec/cspy 反复 200——一度怀疑白名单中间件没套到 /api/*。打开 TRUST_PROXY 让 Express 信任 Caddy X-Forwarded-For 后，403 body 回显的 yourIp 是 1.202.55.49（家宽出口），而不是 hermes vm 自己的公网 IP。说明 hermes 的 outbound 又过了一层家宽 NAT/代理（copilot-proxy / 出口隧道）。结论：白名单生效正确，但运维侧要看的是反代上游报上来的真实 client IP，而不是发起进程自报的 IP；调试时把 403 + yourIp 当唯一真值即可。当前白名单 [1.202.55.49, 116.147.250.4] 即两条家宽出口。

PM2 env 注入坑（同日踩）

pm2 delete + pm2 start ecosystem.config.js 不会重新读 .env —— pm2 把上次 ~/.pm2/dump.pm2 里的 env 当真。新加的 AUDIT_READ_TOKEN / IP_ALLOWLIST 写进 ecosystem.config.js 后 pm2 reload 显示 ok 但 /proc/$PID/environ 里仍是旧 env，所有 audit-read 请求 401、IP 白名单未生效。

修法：

pm2 delete mvp-deployer
pm2 start ecosystem.config.js --update-env   # 关键 flag
pm2 save                                      # 覆盖 dump.pm2
# verify
tr '\0' '\n' < /proc/$(pgrep -f mvp-deployer)/environ | grep -E 'AUDIT_READ_TOKEN|IP_ALLOWLIST'

铁律：env 改动后 pm2 必须 --update-env，并且立刻读 /proc/$PID/environ 验证，不要相信 pm2 list/show 的 env 字段（那个读的是 dump 不是进程实况）。

仍待办

5432 PG / 9800 deployer / pm2 web 等”内网用”端口统一过 iptables
token 改成短期签发（JWT + ip pin）替代长期静态 bearer
/api/exec 加白名单命令（仅 prisma migrate / pnpm install / npm rebuild 等 N 条），杜绝任意 shell

顺手：deploy.mvp.restry.cn 新 SVG 图标

Dashboard 站标改成浅色背景 SVG 图标，避免暗色 favicon 在浅色浏览器主题里糊。同 commit 顺手发，不影响安全主线。

2026-05-12 v2 硬化上线（P0-B/C/D 全部 done，commit `71abf42` + `f835c9c`）

ottor 一次性把 fries 5-11 整理的 P0 三项 + smoke test + host 守门统一打成 v2 上线。Claude 4.7 跑（先升级 claude-code CLI 2.1.114 → 2.1.138 才支持 thinking.type:adaptive，否则 4.7/4.6 一律 400），36/36 测试 pass，rsync 到 claw + pm2 delete && pm2 start ecosystem.config.js --update-env。生效项：

改造	落点	备注
host 字段必填 + Caddy 路由 diff 回滚（替代旧 `<project>.mvp.restry.cn` 默认 fallback）	`lib/builder.js` host 守门 + `.caddy-routes.json` 快照	丢失任何已有 host 视为回归 → fail + 自动回滚 PM2 + Caddy；首次部署无快照时 fallback 到 `listRoutes` live 查询
取消自动 `prisma migrate deploy`（P0-C done）	`prisma` phase 只跑 `generate`	schema 同步交给项目 `postDeploy`（用 manifest.env 自家 DATABASE_URL），根除 mvpadmin 跨库 P1000
删 `--preserve-env` flag（P0 done）	`skill/scripts/deploy.py` 移除 flag + `SERVER_SSH` 常量；`--host` 改 required	替代姿势：调用方自己 `POST /api/exec/<p>` 跑 `cat .env \| base64` 解析后塞 manifest.env Path A 全量传
smoke test 强制	builder 末尾新 `smoke` phase	默认探 host `/`（接受 200/204/301/302/307/308），失败回滚；可选 `manifest.smokePaths: [...]` 多路径或 `smokeDisabled: true` 关掉
vault 集成（P0-B done）	`lib/vault.js`：启动 + 每次 deploy 前 `vault export -p <project>` 拉门神	env 三层合并优先级 `manifest > vault > ~/.credentials/.env`；缺 vault CLI fallback 旧行为 + warn
rollback	builder 失败时切回 PM2 旧版本 + Caddy 路由切回	`cp -a` 备份保留 3 份，磁盘高峰 ×3，`/opt/mvp-apps` 15G 可用足够

白名单更新：当前 [1.202.55.49, 116.147.250.4, 116.147.251.112]（前两个家宽 + 第三个）。

真实项目数 8 个（之前 P0 清单口头说 13 个不准）：cspy / echo / image-studio / image-studio-test / menshen-ui / shutiao-world / wx-gateway / wx-gateway-pucs。8 个全有 host 字段、全部站点都有 UI（smoke 默认探 / 安全），无需补 smokePaths/smokeDisabled。

调用方迁移入口

让所有调用方刷一下：

curl https://deploy.mvp.restry.cn/install-instruction

顶部新加 v2 BREAKING CHANGES 横幅（commit f835c9c）：5 条 breaking 改 + 重新 /skill.zip 解压覆盖即可。Hermes 本地 skill ~/.hermes/skills/devops/mvp-deployer/SKILL.md 也要同步（commit 只更新了 deployer 仓库的 skill/SKILL.md）。

同 NAT 出口 IP 误判陷阱（已写进 admin runbook §7.6）

合白名单后 ottor 从 hermes-vm（Azure，自报 20.196.210.217）调 /api/exec 反复 200 → 第一时间怀疑白名单中间件失效，深查后才发现：hermes outbound 又过了一层家宽 NAT，到 deployer 时真实 client IP 是 1.202.55.49（本来就在白名单）。诊断真值姿势：临时把白名单改成假 IP 9.9.9.9 再请求，看是否真的被 403 + yourIp 回显，证明中间件本身工作；恢复后再加真 IP。运维侧只看反代上报的 client IP，不要信发起进程自报。

v2 还存在的次要风险（review 留底）

vault export 输出格式 deployer 假设是 dotenv/JSON，门神实际格式不同要改 lib/vault.js；当前 fallback 到 ~/.credentials/.env 不阻塞业务
rollback 用 pm2 restart --update-env + 目录交换，逻辑上对但生产首次回滚时人肉再 review 一眼
smoke 默认探 /，未来新接入纯 API（webhook 等）项目必须显式 smokePaths 或 smokeDisabled，否则首次 v2 redeploy → 404 → 自动回滚

2026-05-11 改造需求清单（fries 整理 P0×4 + P1×3）+ `~/.credentials/.env` token 失效

5-10 phase log 泄露事件 + 5-11 wx-gateway P1000 复盘后，fries 整理一份可独立 PR 的 deployer 改造清单，写成 /tmp/mvp-deployer-改造需求.md 给 daddy（deployer 仓库 self-hosted on Tiger host，非 daddy 不可达）。

Pri	改造	动机
P0-A	phase log mask `_SECRET` / `_TOKEN` / `*_PASSWORD` / `WECHAT_APPSECRET` / `DATABASE_URL`（值替成 `<redacted>`，与 inventory 同套规则）	5-10 cspy 部署 33 条 prod env 明文喷回发起方 Discord/Hermes 流
P0-B ✅ done 2026-05-12	deployer 集成门神 vault 作为 secret 唯一真源；env 三层合并 `manifest > vault > ~/.credentials/.env`	5-11 wx-gateway P1000 ticking bomb 根因 = `~/.credentials/.env` ↔ vault ↔ PG 三方密码漂移
P0-C ✅ done 2026-05-12	prisma phase 不强跑 `migrate deploy`；只跑 `generate`，`postDeploy` 显式声明 `prisma migrate deploy` 或 `prisma db push` 业务方决定	强跑 migrate deploy 用 `MVP_DEPLOYER__PG_USER`(mvpadmin) 凭据 → 跨业务库密码不匹配必 P1000
P0-D	`/api/exec` 加白名单命令模式（默认只允许 prisma migrate / pnpm install / npm rebuild / pnpm prisma db seed 等 N 条），杜绝任意 shell 即 RCE-as-a-service	5-09 XMRig 入侵根因
P1-E	task log 加 `secrets[]` 字段单独记录 mask 命中位置，方便审计	—
P1-F	preserveData 默认包含 `data/` + `public/uploads/` + `public/payment/qr/`，业务方 opt-out 而非 opt-in	历次 redeploy 吞文件踩坑
P1-G	dashboard 加「立即 redeploy（保 manifest）」按钮，省 zip 重打	调试热修便利

`MVP_DEPLOYER__TOKEN` 凭据失效（5-11 复测确认）

服务器 ~/.credentials/.env 里的 MVP_DEPLOYER__TOKEN（48 字符）已废，调 /api/exec 直接 Unauthorized；真值在门神 vault mvp-deployer/TOKEN（64 字符）。旧 .env 没清，下次别的 agent 从凭据池抽前缀拿到的就是旧 token，会以为 deployer 挂了。临时绕开：始终从 vault 取 token，不信 ~/.credentials/.env；根治走 P0-B 让 vault 镜像回写 .env。

`/api/exec` 容器无 psql + shell 转义稳定姿势

5-11 wx-gateway 排查 PG 密码漂移时验证：

容器内没装 psql — psql: command not found，因为 deployer 跑的是 next.js runtime 镜像，不带 PG client tools。要查 DB 改用 node -e "..." 走项目自带的 @prisma/client（每个 mvp app 都有）
shell 转义地狱：/api/exec body {"command": "..."} 命令里再嵌 SQL/JS，反斜杠+引号几乎不可能写对，常见 Bad escaped character JSON parse 失败或 bash 反引号被解析。稳定姿势：本地落 .js/.sh 文件 → base64 -w0 → python3 -c json.dumps 拼 payload → curl --data-binary @-。绕开所有 shell 转义层。已写进 P1-E 改造单（task log 加 secrets[] 字段那条同批）作为提示

deployer skill 第 6 表「zip -x prisma/migrations/*」实测不充分

skill 写的 workaround 是「zip 排除 prisma/migrations/」绕过 deployer 强跑 migrate deploy。5-11 wx-gateway 实测不起作用：deployer 看的是项目目录里残留的 migrations（zip 解压是增量，旧版部署留下的目录还在），不是 zip 内容。完整修法是先 /api/exec 删服务器 /opt/mvp-apps/<project>/prisma/migrations/ 再 redeploy。已写进 wx-gateway / cspy 项目级 memory，等 P0-C 做完该 workaround 整段过期可删。

04-29 部署踩坑（来自 image-studio WeChat Pay 接入）

--preserve-env 静默 fallback：当 deployer 没有目标机的 SSH key 时，--preserve-env 不报错，直接用空 env 部署 → 业务 app 起来连不到 DB / 缺 secret。Workaround：base64 抓服务器现有 .env → 多个 --env KEY=VAL 显式注入
deploy.py 不支持 --post-deploy flag：postDeploy 阶段会自动跑 prisma migrate deploy（manifest 里写 postDeploy: 也无效），不要在 CLI 上指定

04-28：apex 域名 `mvp.restry.cn` 落地

之前 mvp.restry.cn 裸根没路由 → 微信公众号 / 校验文件没法挂。

修：Caddy 加 mvp-route-apex 静态 file_server，root /opt/mvp-deployer/public/root/，往里丢任何文件即可挂到根域名。验证文件 MP_verify_3lJy8k1UnlqLETkk.txt → 200。/ 默认返 OK。本地 dig 拿 198.18.140.142 是 fake DNS / VPN 拦截，跟服务器无关，从服务器侧 curl 确认 200。

04-28：shutiao-world manifest `domain` → `host`

historic manifest 用 domain 字段，新 deployer schema 已统一 host。当前线上路由是手动建的 Caddy route 还在 → 不影响访问。修法只能 redeploy（manifest 是 deploy 时写入，无原地编辑）：重打包 ~/projects/shutiao-world 带 host: shutiao-world.mvp.restry.cn + preserveData: ["data"]（保 SQLite）→ task 成功 + HTTP/2 200。

技术架构

AI Agent → zip + manifest.json → POST /api/deploy
    ↓
MVP Deployer API (Express, port 9800)
    ├── 解压 → /opt/mvp-apps/<project>/
    ├── credentials.extractForProject(<APP_PREFIX>__) → finalEnv = {...credEnv, ...manifestEnv}
    ├── npm/pnpm install + build + initOnce + postDeploy
    ├── PM2 启动（claw 用户，端口 4000-4999 自动分配 / manifest 指定）
    ├── Caddy: PATCH /id/<rid>... + reload（上游 172.18.0.1）
    └── HTTPS 自动签发

端点（10 个）

POST /api/deploy · GET /api/deploy/tasks/<id> · GET /api/deploy/tasks · GET /api/status · GET /api/inventory · POST /api/exec/<project> · POST /api/db/provision · GET /api/logs/<name> · DELETE /api/deploy/<name> · GET /skill.zip + GET /install-instruction

Manifest 字段

{
  "project": "my-app", "type": "node", "port": 3801, "run": "pnpm start",
  "host": "my-app.mvp.restry.cn",
  "build": "pnpm install --frozen-lockfile && pnpm build",
  "env": { "NEXT_PUBLIC_APP_URL": "..." },
  "initOnce": "pnpm prisma db seed",
  "postDeploy": "pnpm prisma migrate deploy",
  "postDeployTimeoutMs": 120000,
  "preserveData": ["data", "public/uploads", "public/payment/qr"]
}

initOnce — 首次成功后写 .deployer-initialized，幂等不要求
postDeploy — 每次部署跑，必须幂等
preserveData — 解压时保留指定目录，路径要写真实库位置（吃过 SQLite 在 prisma/data/ 而非 data/ 的亏）
host —（旧字段 domain 已弃用，shutiao-world 04-28 修正后正式统一）

Secrets 双路径

Path	来源	推荐场景
A	`manifest.env` 整包传	外部 agent 默认
B	服务器 `~/.credentials/.env` 抽 `<APP_PREFIX>__` 前缀	Daddy 自用 / 高敏感（DATABASE_URL / _SECRET / _TOKEN）

lib/builder.js:118 合并规则：finalEnv = {...credEnv, ...manifestEnv} —— manifest 后写永远赢。前缀转换：wx-gateway → WX_GATEWAY__，image-studio → IMAGE_STUDIO__。

04-29：wx-gateway DATABASE_URL P1000 复盘 → 高敏感 key 改服务器侧唯一真源

旧 manifest 还塞着失效的 DB 密码 → manifest 优先级压过 credentials → Prisma P1000 Authentication failed for wx_gateway。修法：

rotate wx_gateway DB 密码（真值不进 stdout/log）
写 WX_GATEWAY__DATABASE_URL 到服务器 ~/.credentials/.env（chmod 600）
manifest 移除 DATABASE_URL，只留应用配置 + WX_* env
redeploy task 40e3ad14da1a7aa4 succeeded → wx.mvp.restry.cn 200

约定：DB 密码 / 第三方 key 这类高敏感 secret 一律走 Path B，调用方只声明”我要用这个项目”，不传密码本身。当前 wx-gateway 的 postDeploy 保留 pnpm prisma db push --skip-generate --accept-data-loss（migration 状态历史不干净，migrate deploy 会撞 WxLoginToken already exists）。

04-26 v3：纯 API 闭环（exec + db.provision）

POST /api/exec/<project> —— lib/exec.js 在项目 cwd 下 spawn bash，注入 credEnv，60s 默认超时。body 字段 command（不是 cmd）。替代所有”agent 跑 migration / seed / cat .env 必须 SSH”的场景。

POST /api/db/provision —— 一次调用建 PG role + db。同名再调默认 ifExists:"skip"；传 dbPassword 已存在 → ALTER 轮换；ifExists:"error" → 409。名字 sanitize [a-z0-9_]（my-app → my_app）。响应取 database / user 字段，不要自己拼。销毁性操作（DROP/RENAME）不进 API，仍走 admin-runbook + SSH。

⚠️ 5432 当时 0.0.0.0 公网监听，Azure NSG 拦了外网，弱密码暴露面待收。

v3.1（04-27）4 大修

lib/builder.js env 序列化 — serializeEnvValue() 处理 object/array → JSON.stringify，避免 [object Object] 写进 .env
multer 上限 100MB → 500MB
远程仓库 — 新建 bochub/mvp-deployer 私有，主分支 master → main
双 PM2 收敛 — 服务器有 root pm2 + claw pm2 两套，root pm2 吞了 4 个孤儿（realtime-voice errored、shutiao-world 重启 425 次）跟 claw pm2 同名进程抢端口 → 删 root 孤儿、pm2-claw.service EnvironmentFile=/home/claw/.credentials/.env、新部署默认进 claw pm2

v3 v.s. CC 那份 SKILL.md（差 5KB）

~/.hermes/skills/mvp-deployer/SKILL.md (23KB) 比 ~/.claude/skills/mvp-deployer/SKILL.md (18KB) 多 5KB 关键内容，CC 看不到 → 04-28 后两边同步：

pnpm packages field missing / ETIMEDOUT registry
Drizzle .env.local 卡 spinner 救法
porsager/postgres 的 ?schema=public GUC 陷阱
Prisma P1000 deployer 强跑 migrate deploy 用 mvpadmin 凭据
PM2 env 缓存救场（pm2 delete + set -a）
pnpm start -- -p PORT 不透传陷阱
§6.5 Prisma migrate baseline 陷阱
--preserve-env 对普通 agent 静默失效（zip 必须 -x .env*）

v2（04-23）异步管线 + Inventory 接口

端点	行为
`POST /api/deploy`	立即返 202 `{ taskId, status: 'queued' }`
`GET /api/deploy/tasks/:id`	轮询 `{ status, phase, logs, result }`

builder 阶段顺序：extract → install → build → PM2 reload。build: true 让服务器侧 pnpm install + 构建（zip 不打 node_modules）。

GET /api/inventory 返脱敏全配（cwd / port / host / env keys / PM2 / Caddy 路由 / 磁盘）。skill §2.5 铁律：部署前 5 项 checklist 必先查 inventory（端口冲突 / host 一致 / <APP_PREFIX>__ 前缀齐 / cwd 期望 / envKeys 满足）。

v1 → v2 改进

组件	v1	v2
Caddy 路由	Admin API `:2019`	修 Caddyfile + `docker exec caddy caddy reload`
PostgreSQL	新建容器	复用 `mvp-postgres` + `mvpadmin`
Bootstrap	全量	轻量（只装 PM2 + deployer）
反代上游	`127.0.0.1`	`172.18.0.1`（Docker 网桥）
端口	手动	自动 4000-4999

04-20 重构发布 3 大坑（shutiao-world Stage 0–4）

Caddy PUT 是插入不是替换 — lib/caddy.js 用 PUT /id/<rid> 每次重发都再插一个同 @id 路由，第二次起 400。改 PATCH，清重复历史。lib/caddy.js.bak 备份
deployer root unzip → SQLite 只读 — data/ 属主变 root，PM2 跑 claw 写库崩。必须 chown -R claw:claw <project>/data
PM2 缓存老 script 路径 — ecosystem.config.js 的 script 改了 pm2 restart 不切，必须 pm2 delete && pm2 start ecosystem.config.js

zip 增量解压不清旧文件 → 旧 public/play/ / server/routes/parent.js 残留，必要时先 undeploy。

通用部署故障速查

pnpm-workspace.yaml 缺 packages → pnpm 当空 workspace 拒装 → 删之，挪到 package.json 的 pnpm.ignoredBuiltDependencies
服务器拉 registry.npmjs.org 超时 → .npmrc 走 npmmirror
drizzle-kit 写死读 .env.local（部署机只有 .env）→ build 命令前 cp .env .env.local 或改 drizzle.config.ts 显式读
postgres JS 库不接受 ?schema=public → strip
pm2 restart --update-env 不刷新 → pm2 delete && pm2 start
inventory 推荐端口被占（echo 连撞 3794/3795）→ 部署前 lsof -iTCP:<port>
drizzle migrate spinner 卡 → fallback psql -f
Next.js public/ build-time prerender 缓存：上传文件 _selftest_dummy.png build 时存在能取，运行时新上传 → 404，且下次 deploy zip 覆盖直接丢 → 改存 data/qr/ + GET /payment/qr/[file]/route.ts dynamic handler 绕过 prerender + preserveData 保留
--preserve-env 对新项目无效 —— 第一次部署需先 SSH 推 .env 到 /opt/mvp-apps/<project>/.env + chown claw:claw
必须显式 --host —— 漏 --host deployer fallback 到 <project>.mvp.restry.cn，会替换原 host 的 Caddy 路由 → TLS 失效
test 环境约定 —— <project>-test 独立端口 + <db>_test 独立库 + /var/lib/<project>-test/，只发 test 默认；prod 走显式触发
PM2 cwd 错位 —— pm2 reload 不更新 cwd，redeploy 后跑 /opt/mvp-deployer/ 读错 .env → builder 强制写 cwd: '/opt/mvp-apps/<project>'
zip exclude 不全 —— -x 'data/*' 不够，Prisma SQLite 真库在 prisma/data/ 被覆盖。结论：不要再用 SQLite + 项目内路径
Caddy admin API reload 丢路由 —— systemd override.conf 改启动命令为 caddy run --resume 从 autosave.json 恢复（详见 caddy-reverse-proxy）
next start -p <PORT> 硬编码覆盖 manifest.env.PORT —— 05-03 menshen-ui 部署 deploy.py 报 succeeded 但 502：manifest 期望 3812、Caddy 也指 3812，但 package.json 的 start: "next start -p 3000" 把 PORT env 覆盖。修：start: "next start"（去掉 -p）让 PORT env 生效。新铁律：所有框架的 start 命令别带端口参数，让 manifest 注入的 PORT env 走

05-03 部署后自检铁律

deploy.py / mvp-deployer skill 报 succeeded 不等于站点活着（PM2 起来 ≠ HTTP 通）。部署后必须 curl 一下首页确认非 502/500。05-03 menshen-ui 因端口写死被静默 502 后定的规则，已写入 mvp-deployer skill memory。

Dashboard 删按钮”没反应”

UI 报 200 实际未删，后端 EACCES：/opt/mvp-apps/<...>.old-<ts>/.env 是 root pm2 时代留的备份目录，claw deployer 删不掉。UI 层 bug：所有 ops 失败必须前端可见，不能静默 200。手动 chown 该目录后 DELETE 成功。

自更新铁律

deployer 不能用自身平台部署自己 —— zip 解压会覆盖 /opt/mvp-deployer/ 的 SKILL.md / skill / inventory.js。自身更新只能 ssh + rsync + pm2 delete && pm2 start ecosystem.config.js 绕过平台流程。

Skill 公开镜像

GET /skill / /skill.html / /skill.zip — SKILL.md 原文 / 渲染版 / 全包下载（约 6 文件 / 20.4KB）
GET /install-instruction — 多步指引（Hermes / CC / Desktop / OpenCode / Codex 各自 skill 目录示例）
Dashboard 顶部 📘 链接 + 底部 Install 卡片含 📋 复制 + zip 下载
0 secret 泄漏：所有 token 引用走 $DEPLOYER_TOKEN

OpenClaw Skill 集成

~/.openclaw/skills/mvp-deployer/：

/mvp-deploy --project demo-api --type node --port 3050 --run "node index.js"

经验沉淀

写大文件用 patch 分块 —— >3KB Markdown 用 write_file 整文件容易 “Stream stalled mid tool-call”
Hermes mask 陷阱 —— 显示层 mask 成 xxx...yyy，文件里是真值。绝不能把 mask 字符串当 old_string 喂给 patch
改 deployer 源码必须走 Claude CLI —— 04-27 用 Hermes patch 直接改源码（surgical fix）违反硬约束，留 commit 但日后引以为戒

🔮 Dora's Wiki

探索

MVP Deployer

MVP Deployer

概述

双环境

当前 8 个服务（packsmith 05-09 删）

2026-05-14 — vault-to-manifest-env.py + 第 11 铁律「env 值级 fp diff」（fries）

「mvp-deployer 回滚把 .env 重置成默认推导名」复现 + 启示

新铁律 11：env 必须做值级 SHA256 fp diff，不只是 key 存在性

2026-05-10 部署轮询日志泄露 prod secrets（cspy 部署事故）

2026-05-09 XMRig 入侵事件 + 4 层硬化（ottor）

检测

根因

处置（同日完成）

4 层硬化（commits）

Hermes 出口 IP ≠ Azure VM IP（IP_ALLOWLIST 验证踩坑，fries→ottor 联调）

PM2 env 注入坑（同日踩）

仍待办

顺手：deploy.mvp.restry.cn 新 SVG 图标

2026-05-12 v2 硬化上线（P0-B/C/D 全部 done，commit 71abf42 + f835c9c）

调用方迁移入口

同 NAT 出口 IP 误判陷阱（已写进 admin runbook §7.6）

v2 还存在的次要风险（review 留底）

2026-05-11 改造需求清单（fries 整理 P0×4 + P1×3）+ ~/.credentials/.env token 失效

MVP_DEPLOYER__TOKEN 凭据失效（5-11 复测确认）

/api/exec 容器无 psql + shell 转义稳定姿势

deployer skill 第 6 表「zip -x prisma/migrations/*」实测不充分

04-29 部署踩坑（来自 image-studio WeChat Pay 接入）

04-28：apex 域名 mvp.restry.cn 落地

04-28：shutiao-world manifest domain → host

技术架构

端点（10 个）

Manifest 字段

Secrets 双路径

04-29：wx-gateway DATABASE_URL P1000 复盘 → 高敏感 key 改服务器侧唯一真源

04-26 v3：纯 API 闭环（exec + db.provision）

v3.1（04-27）4 大修

v3 v.s. CC 那份 SKILL.md（差 5KB）

v2（04-23）异步管线 + Inventory 接口

v1 → v2 改进

04-20 重构发布 3 大坑（shutiao-world Stage 0–4）

通用部署故障速查

05-03 部署后自检铁律

Dashboard 删按钮”没反应”

自更新铁律

Skill 公开镜像

OpenClaw Skill 集成

经验沉淀

相关

关系图谱

目录

反向链接

2026-05-14 — `vault-to-manifest-env.py` + 第 11 铁律「env 值级 fp diff」（fries）

2026-05-12 v2 硬化上线（P0-B/C/D 全部 done，commit `71abf42` + `f835c9c`）

2026-05-11 改造需求清单（fries 整理 P0×4 + P1×3）+ `~/.credentials/.env` token 失效

`MVP_DEPLOYER__TOKEN` 凭据失效（5-11 复测确认）

`/api/exec` 容器无 psql + shell 转义稳定姿势

04-28：apex 域名 `mvp.restry.cn` 落地

04-28：shutiao-world manifest `domain` → `host`