muse-guardian
"在全新沙盒/新账号上从零部署一套「CF Server Monitor 探针 + 三层保活 + Hermes 微信机器人 + MuseAutoApprove(muse.ai 外联审批自动批准)」:Cloudflare Worker 后台、cf-probe 探针、持久化脚本布局、离线包缓存、Hermes 安装与模型 API 配置、微信扫码绑定、沙盒内看门狗、平台 hook 探针(检测/恢复拆分)、平台开机钩子、端到端验证。开工先问「全部安装 / 逐模块」(默认逐模块);全文按 5 个模块 + 收尾组织,同一模块内连续执行,只在用户必须输入/扫码/平台点击时打断;每步五段式(命令 / 话术 / 用户手动动作 / 做完的标志 / 排错表格),全部脚本完整代码直接内嵌,复制即可用。触发词:部署保活、给新账号也来一套、装探针、微信机器人、沙盒重建恢复、保活脚本、自动审批、审批卡片、MuseAutoApprove。"
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/bytehola--muse-guardian)HTML
<a href="/listings/bytehola--muse-guardian"><img src="/api/listings/bytehola--muse-guardian/badge.svg" alt="findsafeskills safety rating" /></a>Install
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 3,110 lines
- ---
- name: muse-guardian
- description: "在全新沙盒/新账号上从零部署一套「CF Server Monitor 探针 + 三层保活 + Hermes 微信机器人 + MuseAutoApprove(muse.ai 外联审批自动批准)」:Cloudflare Worker 后台、cf-probe 探针、持久化脚本布局、离线包缓存、Hermes 安装与模型 API 配置、微信扫码绑定、沙盒内看门狗、平台 hook 探针(检测/恢复拆分)、平台开机钩子、端到端验证。开工先问「全部安装 / 逐模块」(默认逐模块);全文按 5 个模块 + 收尾组织,同一模块内连续执行,只在用户必须输入/扫码/平台点击时打断;每步五段式(命令 / 话术 / 用户手动动作 / 做完的标志 / 排错表格),全部脚本完整代码直接内嵌,复制即可用。触发词:部署保活、给新账号也来一套、装探针、微信机器人、沙盒重建恢复、保活脚本、自动审批、审批卡片、MuseAutoApprove。"
- version: 2.6.0
- license: MIT
- metadata:
- hermes:
- tags:
- [
- sandbox,
- keepalive,
- disaster-recovery,
- cloudflare,
- probe,
- hermes,
- weixin,
- deployment,
- muse-auto-approve,
- ]
- related_skills: [weixin-instant-ack, sandbox-environment-recon]
- ---
- # 沙盒保活 + Hermes 微信机器人:一键部署手册
- ## 一、这套东西是什么
- 平台(Muse / hatch 沙盒)会不定期**重建**沙盒:整机从外部删掉重装,沙盒内的一切——
- 进程、systemd、cron、/tmp——全部消失,只有 `$HOME`(`/home/hatch`)会保留。
- 本手册部署的是一套**三层保活 + 微信机器人**:
- | 层 | 组件 | 对付的故障 | 恢复时间 |
- | ---------- | ---------------------------------------------------------------------------- | ---------------------------------------- | --------------------------- |
- | 探针 | `cf-probe`(systemd 服务)→ CF Server Monitor 后台 | 你想知道机器到底活着还是挂了 | 60 秒上报一次 |
- | Layer 1 | `watchdog.sh`(沙盒内 cron,每分钟) | 机器活着,但某个进程挂了 / 微信连接卡死 | 1 分钟内 |
- | Layer 2a | 平台 hook 探针(每 10 秒 bash 轮询,跑在沙盒外;健康零 token,连续异常才唤醒 agent 恢复) | 整机被重建,沙盒内 cron 全灭 | 10 秒级发现,约 2 分钟恢复 |
- | Layer 2b | 平台原生开机钩子(每次启动跑一次) | 同上,但更快(开机即恢复) | 开机后约 100 秒 |
- | Layer 3 | `restore-all.sh`(幂等一键恢复) | 被 1、2a、2b 调用 | 约 2 分钟 |
- | 审批自动化 | `MuseAutoApprove`(沙盒内 node 常驻;步骤 1–4 安装启动、第 15 步起接入保活) | 沙盒访问新域名时平台弹审批卡片、外联卡住 | 默认每 10 秒一轮询 |
- 平台重建无法阻止,本手册只保证「重建后自动恢复」。
- ## 二、怎么用这本手册(AI 必须遵守的行事规则)
- 1. **开工先问执行方式;默认逐模块。** 动手之前先问用户选哪种(话术见第三章开头):
- - **A. 全部安装**:一口气把 5 个模块 + 收尾全做完,只在下面 8 个介入点停。
- - **B. 逐模块(默认)**:每做完一个模块汇报一次,等用户说"继续"再做下一个。用户没明确选就按 B。
- - **同一模块内的步骤连着做完**,不要逐步确认;纯沙盒内的动作(跑脚本、装服务、写 cron、改文件)全部自己做完。
- - **只在用户必须到场时停**:需要用户输入(账号、密钥、策略)、扫码、或在平台/网页端点击时,才停下把话术发出去,等用户回复再往下。这些点见「必须用户介入的环节」。
- 2. **正文按五段式书写——这是文档结构,不是执行节奏。** 每个步骤五段固定顺序,便于排障与查证;**执行时同一模块内的步骤连着做完,不必逐步确认**,只在 ② 出现、或 ④ 判据不过时才打断用户:
- - **① 🤖 AI 执行**:你(AI)要跑的命令,精确到可以直接复制。不要写"类似这样",要写实际的命令。
- - **② 💬 对用户说**:可以**原样发给用户**的话术(可微调语气,不要改意思)。用户是技术型、直接、要求客观,话术要短、要具体、要说清"要他做什么"。
- - **③ 🙋 用户手动做**:用户必须在网页/手机/平台端点的动作。
- - **④ ✅ 做完的标志**:可验证的判据(命令 + 期望输出)。**做不到就不要往下走**,先解决问题。
- - **⑤ 🛠️ 常见失败与处理**:表格,现象 → 原因 → 处理。
- 3. **每条命令都要真跑过。** 报告结果时说清楚「跑了什么、看到什么」。跑不了就直说跑不了,不要编造输出。
- 4. **密钥纪律(四条铁律,违反必出事)**:
- - 真实 SECRET / API Key / Worker 域名 / API 地址**绝不写进任何文档、Skill、日志、记忆**——本手册里全用占位符:`<PROBE_ID>`、`<API_SECRET>`、`<WORKER_URL>`、`<API_BASE_URL>`、`<MODEL_NAME>`。
- - 密钥优先**让用户自己生成**,通过**安全页面**发给你;只有用户明确同意时才由 AI 生成并在聊天里**一次性**显示。(例外:MuseAutoApprove 的 muse.ai 账号密码——沙盒里没有可用安全入口,按用户要求**走聊天框明文**,见第六章。)
- - **先脱敏再打印**,不是"先打印再脱敏"。需要确认密钥存在,就只输出计数/长度/路径/布尔值,不输出值本身。
- - 含密钥的文件(`install-cf-probe.sh`、`~/.hermes/.env`)权限一律 600,且**不要用文件读取工具打开**(内容会进会话历史)。
- 5. **谁做什么**(重要,别硬揽):
- - 沙盒内的一切(跑脚本、装服务、写 cron、改文件)→ 任何有 shell 的 Agent 都能做。
- - **Layer 2a(平台 hook 探针)和 Layer 2b(平台开机钩子)跑在沙盒外面**:只有**平台侧 Agent**(Muse)或**用户在平台端**才能创建。如果你是在沙盒里跑的 Agent,这两步要**请求用户/平台侧 Agent 执行**,并把现成的 hook 脚本、hook 定义与恢复提示词交给他们(本手册第 13、14 步给了全文)。
- - 涉及 root 权限的操作(装包、写 systemd、启动 sshd、给 `init.sh` 加执行位)→ 沙盒里通常是 root,直接做,但要在报告里说明改了哪些系统路径。
- ### 模块地图(执行顺序)
- 整条流程分成 **5 个模块 + 收尾**,**顺序不可乱**(MAA 最先装:部署全程要出网,先让审批能自动批;保活补丁必须在脚本落盘〔步骤 7〕与看门狗 cron〔步骤 11〕之后)。**按 A/B 模式连着做,只在介入点停**:
- | 模块 | 干什么 | 步骤 | 章节 | 要用户做什么 |
- | -------------------- | --------------------------------------------------- | ----- | ----------- | ------------------------------------------------- |
- | **A|自动审批底座** | 装 MuseAutoApprove 并常驻,外联审批自动批 | 1–4 | 四~七 | 选策略 + 发 muse.ai 账号密码 + 首次装包点一次卡片 |
- | **B|监控与探针** | CF 监控后台 + cf-probe 探针 | 5–6 | 八~九 | 给 CF Token(或网页部署)+ 后台拿安装命令 |
- | **C|保活底座** | 保活脚本落盘 + 离线包缓存 | 7–8 | 十~十一 | 无(全自动) |
- | **D|微信机器人** | 装 Hermes + 接模型 API + 微信扫码绑定与配对 | 9–10 | 十二~十三 | 模型 API 地址/Key + 微信扫码 + 转配对码 |
- | **E|三层保活接入** | Layer 1 看门狗、平台授权、Layer 2a/2b、MAA 保活补丁 | 11–15 | 十四~十八 | 平台端点 3 项授权 |
- | **收尾|验收与运维** | MAA 验证/排障/交互/升级、最终验证 | 16–20 | 十九~二十三 | 微信发消息测试 + 决定是否做重建演练 |
- ### 必须用户介入的环节(只有这 8 处要停)
- 除下列各处,其余全程自动。到这些点才发话术、等用户回复:
- 1. **开工询问 + 平台设置**:先问执行方式(A 全部安装 / B 逐模块,默认 B);再在网页把「直接网络协议」全开、「连接器 → 浏览器」(除上传文件)全改为允许(第三章)。
- 2. **MAA 策略与账号**:选 A(永久允许)/ B(每次只批一次);把 muse.ai 邮箱密码发在聊天框(步骤 1、3)。
- 3. **首次装包卡片**:`git clone` / `npm install` 弹审批卡片时,用户手动点一次「允许」(步骤 2)。
- 4. **CF 后台**:给 Cloudflare API Token(或自己在网页部署);后台「添加服务器」把安装命令贴回来;定 `API_SECRET`(步骤 5)。
- 5. **模型 API**:接口地址 + API Key + 模型名(步骤 9)。
- 6. **微信扫码**:手机扫码 + 确认登录;之后把机器人回的**配对码**转给 AI(步骤 10)。
- 7. **平台授权**:平台端确认「保活探针 hook / 开机钩子 / root 执行」3 项(步骤 12)。
- 8. **最终验证**:微信给机器人发消息测试;决定是否做重建演练(步骤 20)。
- ## 三、开工前的询问与设置 + 两次探测
- ### 开工第一件事:问执行方式 + 两处平台设置(一条消息问完)
- 这是整条流程的**第一个动作**。在跑任何命令之前先发下面这条,一次把「执行方式」和「两处设置」都问掉,拿到答复再往下。两处设置在平台网页端,沙盒里**无法直接验证**,以用户确认为准。
- 💬 对用户说(可原样发送):
- > 开始部署前,先确认两件事:
- >
- > **一、执行方式**,你选一个:
- >
- > - **A. 全部安装(一次做完,推荐)**:我一口气把 5 个模块 + 收尾全做完,只在需要你输入、扫码或点平台时才来找你。
- > - **B. 逐模块(默认)**:每做完一个模块我汇报一次,你说"继续"我再做下一个。
- >
- > **二、两处平台设置**,在 Muse.AI 网页上做:
- >
- > **1. 设置 → 权限 → 直接网络协议**:把里面的开关**全部打开**。一个已知 Bug:点开关时滑块看起来没反应,**其实已经打开了**——每个开关点一次就行,不用管滑块动没动,也不要反复点。
- >
- > **2. 设置 → 权限 → 连接器 → 浏览器**:把里面的选项**全部改成「允许」**,但**「上传文件」不可更改**。
- >
- > 回复格式随意,比如"**A,都设好了**"或"**B**"。执行方式不回就按 **B(逐模块)**走。
- 做完的标志:用户回复执行方式(缺失则按 B)+ 确认两处设置已做。**探测 2 如果全是 000,第一怀疑对象是「直接网络协议」没开全。**
- ### 两次探测(不是前置条件,是事实确认)
- 这两条命令是给自己看的,**不要**把它们包装成"前置条件清单"去问用户:
- ```bash
- # 探测 1:我是谁、在哪、有没有 systemd / root
- whoami; echo "HOME=$HOME"; id -u; ls -d "$HOME/workspace" 2>/dev/null || echo "no workspace dir"
- systemctl --version 2>/dev/null | head -1 || echo "no systemd"
- # 探测 2:能不能出去(GitHub / Cloudflare / 模型 API 端点)
- curl -sS -m 8 -o /dev/null -w 'github %{http_code}\n' https://raw.githubusercontent.com/huilang-me/cfsm-agent/main/install.sh
- curl -sS -m 8 -o /dev/null -w 'cf %{http_code}\n' https://api.cloudflare.com/client/v4
- ```
- 期望:`whoami` 是 root 或可用 sudo 的用户;`HOME` 指向可持久化的家目录;systemd 存在;两个 HTTP 码不是 000(000 = 连不上)。若 GitHub 不通,第 8 步的离线缓存就是**必需**的,不是可选项。**探测 2 两个都是 000 时,先回头确认上面的「直接网络协议」已全部打开,再谈别的。**
- # 模块 A|自动审批底座(MuseAutoApprove,步骤 1–4)
- 先装这一模块并常驻:**后续全程出网(拉代码、装依赖、调模型)都不再卡审批卡片**。本模块要用户配合三次:定策略、发 muse.ai 账号密码、首次装包点一次卡片。
- ## 四、步骤 1:MuseAutoApprove 是什么(先定策略)
- **目标**:说清机制与副作用,让用户定决策策略。
- > 沙盒外联未被规则覆盖的域名会弹审批卡片(HITL)。本组件用 muse.ai 账号连 hatch 网关加密 RPC(`wss://hatch.metaaivm.com`)自动决策,默认 `allow_always + destination_domain` 落库永久规则。纯 Node 无浏览器,只与 muse.ai / hatch 通信;`data/` 含账号密码、会话、token,`log/` 含邮箱与审批记录,均在 `$HOME` 下(700/600),不外发不提交。
- | 事项 | 说明 |
- | -------- | ------------------------------------------------------------------------- |
- | 登录 | 邮箱+密码;服务端会发一封验证码邮件,**本工具不读邮件** |
- | 会话 | `hatch_sess` 30 天,每 5 分钟 token touch 滚动续期——30 天内跑过一次即永续 |
- | 轮询 | 默认 10 秒一轮 |
- | 默认决策 | `allow_always + destination_domain`;失败回退 `allow_once` |
- | 保守决策 | `--decision allow_once`:只批本次,不落永久规则 |
- | 生效范围 | 仅本账号、所连 VM 的审批流 |
- ### ① 🤖 AI 执行(命令)
- **开工检查**:用户还没确认第三章的两处平台设置——「设置 → 权限 → 直接网络协议」全部打开、「设置 → 权限 → 连接器 → 浏览器」除「上传文件」外全部改为允许——的,先回去做完再进本步骤。
- ```bash
- ls "$HOME/workspace/muse-guardian/MuseAutoApprove/muse-daemon.cjs" 2>/dev/null \
- && echo "已安装(升级见第二十二章)" || echo "尚未安装"
- ```
- 确认尚未安装后,按 ② 与用户确认策略,再进下一步。用户没明确表态就不要动。
- ### ② 💬 对用户说(可原样发送)
- > 🚦 装一个"自动点同意"的组件(MuseAutoApprove)。沙盒每次访问新域名,平台会弹卡片等你点"允许",不点就卡住;这个组件用你的 muse.ai 账号把这一步自动做掉。
- >
- > 要你定一个策略:
- >
- > - **A. 永久允许**(推荐):同域名批一次永久放行,之后基本不再看到卡片;
- > - **B. 每次只批一次**(保守):域名不被永久记住。
- >
- > 另外它需要你的 muse.ai 账号密码——下一步**直接在聊天框发我**即可。装的过程会弹一两次卡片(GitHub、npm),那两次请手动点允许。
- > 回"A"或"B",我就继续。
- ### ③ 🙋 用户手动做
- - 选策略 A 或 B。
- ### ④ ✅ 做完的标志
- - 用户明确回复 A 或 B(没回复不要往下走)。
- ### ⑤ 🛠️ 常见失败与处理
- | 现象 | 处理 |
- | ------------------------ | -------------------------------------------------------------------- |
- | 用户担心"自动同意"不安全 | 改 B(每次只批一次);或先不装 |
- | 用户不想把密码给 AI | MAA 只能明文聊天给(其他入口走不通);介意可落盘后自行改密,或先不装 |
- | 用户想只放行指定域名 | 本工具没有白名单:要么 B,要么继续手工点卡片 |
- ---
- ## 五、步骤 2:安装(Node + git clone + 依赖)
- **目标**:Node ≥ 20.18 就位、代码 clone 到 `~/workspace/muse-guardian`、依赖装齐、语法自检全过。
- > 全部装在 `$HOME` 下:代码、`node_modules`、Node 运行时、凭据、会话——重建后都在。
- ### ① 🤖 AI 执行(命令)
- ```bash
- # 1) Node ≥ 20.18:有就跳过;没有/过旧 → 装 $HOME/.local(重建不丢)
- command -v node && node -v || echo "no node"
- ```
- ```bash
- # 无 Node 或版本低时(示例版本,按需换 22.x 最新补丁号):
- case "$(uname -m)" in x86_64|amd64) A=x64;; aarch64|arm64) A=arm64;; *) echo "未知架构 $(uname -m)"; exit 1;; esac
- V=v22.16.0
- mkdir -p "$HOME/.local" /tmp/ni
- curl -fL -o /tmp/ni/node.tar.gz "https://nodejs.org/dist/$V/node-$V-linux-$A.tar.gz"
- tar -xzf /tmp/ni/node.tar.gz -C "$HOME/.local" --strip-components=1 --exclude='CHANGELOG.md' --exclude='LICENSE' --exclude='README.md'
- export PATH="$HOME/.local/bin:$PATH"; node -v && npm -v
- ```
- ```bash
- # 2) 克隆仓库(更新 = git pull),app 在仓库的 MuseAutoApprove/ 子目录
- cd ~/workspace
- [ -d muse-guardian/.git ] && git -C muse-guardian pull --ff-only \
- || git clone https://github.com/bytehola/muse-guardian.git
- ls muse-guardian/MuseAutoApprove/muse-daemon.cjs
- # 3) 装依赖 + 双自检
- cd muse-guardian/MuseAutoApprove
- npm install --no-audit --no-fund
- node -e "require('undici');require('ws');require('https-proxy-agent');require('sodium-native');console.log('deps OK')"
- for f in muse-daemon.cjs work/*.cjs; do node --check "$f" || echo "FAIL $f"; done; echo "语法检查完成"
- # 4) 目录与权限
- mkdir -p data log && chmod 700 data
- ```
- > **首次安装的鸡生蛋**:`git clone` / `npm install` 自己也要出网,可能弹审批卡片(`github.com`、`registry.npmjs.org`、`nodejs.org`)——此时自动审批还没起来,需要用户手动点一次"允许"。点过之后,同类请求就永久放行了。
- **装完后读一遍 `~/workspace/muse-guardian/MuseAutoApprove/README.md`**——里面有这个工具的目录结构、CLI 命令、环境变量和日志字段说明。后续排障和回答用户追问时用得上,不要只照本 SKILL.md 的模板复述。
- ### ② 💬 对用户说(可原样发送)
- > 📦 开始装。过程可能弹一两次审批卡片(GitHub、npm),**请手动点允许**——就这一次,之后同类请求自动审批组件会替你处理。
- > 装完我把自检结果给你看。
- ### ③ 🙋 用户手动做
- - 平台弹卡片时手动点允许。
- ### ④ ✅ 做完的标志
- ```bash
- cd ~/workspace/muse-guardian/MuseAutoApprove
- node -v # ≥ v20.18
- ls muse-daemon.cjs package.json work/*.cjs | wc -l # 期望 9
- node -e "require('undici');require('ws');require('https-proxy-agent');require('sodium-native');console.log('deps OK')"
- for f in muse-daemon.cjs work/*.cjs; do node --check "$f" || echo "FAIL $f"; done; echo "语法检查完成"
- ```
- ### ⑤ 🛠️ 常见失败与处理
- | 现象 | 处理 |
- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
- | `git clone` 超时/被拦 | 让用户放行 `github.com`;或本机打包 `MuseAutoApprove/` 整目录传进沙盒(走整包拷贝,别手抄单文件) |
- | `npm install` 超时/被拦 | 放行 `registry.npmjs.org`;或换镜像 `npm config set registry https://registry.npmmirror.com`;或用离线 `node_modules` 包 |
- | `sodium-native` 编译失败 | `apt-get install -y build-essential python3` 后重装;或用同架构的离线 `node_modules` |
- | `node --check` 某文件 FAIL | 文件截断/损坏:`git -C ~/workspace/muse-guardian checkout -- MuseAutoApprove/<file>` |
- | bash 报 `$'\r'` | 从文档复制时带上了 CRLF:`sed -i 's/\r$//' <文件>` |
- ---
- ## 六、步骤 3:凭据与自动登录
- **目标**:凭据落盘(文件方式,长期必须)、验证登录链路。
- > **凭据查找顺序**:环境变量 `MUSE_USER`/`MUSE_PASSWORD` > 文件 `data/credentials.json`。
- > **长期运行必须用文件**:cron、重建恢复拉起的进程读不到 shell 环境变量。**"会话过期后能否自动重登"完全取决于这个文件**。
- > **登录流程**:restart → send-otp(服务端会发一封验证码邮件,**工具不读它**)→ confirm-password(密码信封)→ `hatch_sess` 30 天。
- > **会话永续**:守护进程每 5 分钟 token touch 滚动续期——30 天内跑过一次就永续。
- > **自愈**:会话丢失/过期 → 下次连接自动重登(日志 `connect_retry ENOENT` → `auto_login_ok` 是正常路径)。
- ### ① 🤖 AI 执行(命令)
- **唯一方式:用户把账号密码直接发在聊天框,AI 落盘(不复述、不回显)**
- > MAA 的 muse.ai 账号是纯密码登录,沙盒里没有可用的安全入口——用户自己写文件、或走别的"安全"通道实测都走不通。**用户直接把邮箱和密码发在聊天框里,这是唯一可行的给法。**
- ```bash
- APP=~/workspace/muse-guardian/MuseAutoApprove; cd "$APP"
- mkdir -p data && chmod 700 data
- # 账号密码来自用户聊天框里的明文;值只经环境变量传入,不进 shell 历史、不写命令行参数
- MUSE_EM="<用户在聊天框给的邮箱>" MUSE_PW="<用户在聊天框给的密码>" node -e '
- require("fs").writeFileSync("data/credentials.json",
- JSON.stringify({email:process.env.MUSE_EM,password:process.env.MUSE_PW},null,2),{mode:0o600});
- console.log("written");
- '
- chmod 600 data/credentials.json
- ```
- > ⚠️ 落盘后**不要**复述、不 echo、不写进任何文档;密码只存在于 `data/credentials.json`(600)。用户介意聊天记录的话,可自行改一次 muse.ai 密码并更新这个文件。
- **验证(两步)**:
- ```bash
- cd "$APP"
- node muse-daemon.cjs --check # 离线体检:凭据来源 + 会话状态(不出网)
- node muse-daemon.cjs --smoke # 真登录一次:会发一封验证码邮件(无需读码)→ SMOKE OK
- ```
- ### ② 💬 对用户说(可原样发送)
- > 🔑 需要你的 muse.ai 账号密码——**直接在聊天框里发我就行**(邮箱 + 密码,一条消息发来即可)。
- >
- > 说明:MAA 登录是纯密码,沙盒里没有别的可用入口,**明文聊天是唯一走得通的给法**。我会把它写进沙盒里 600 权限的凭据文件,之后不回显、不复述、不写进任何文档。你要是介意,落盘后可以自行改一次 muse.ai 密码。
- >
- > 另外两点:登录时 muse.ai 会往你邮箱**发一封验证码邮件,不用读**(流程必需,工具不读码);会话 30 天滚动续期,**只要 30 天内跑过一次就永续**,平时不用重复登录。
- ### ③ 🙋 用户手动做
- - 在聊天框里直接把 muse.ai 邮箱和密码发给我。
- ### ④ ✅ 做完的标志
- ```bash
- cd ~/workspace/muse-guardian/MuseAutoApprove
- node muse-daemon.cjs --check; echo "rc=$?" # 期望:凭据 OK(来源 data/credentials.json),rc=0
- node muse-daemon.cjs --smoke; echo "rc=$?" # 期望 0 + SMOKE OK
- stat -c '%a %n' data data/credentials.json # 期望 700 / 600
- ```
- ### ⑤ 🛠️ 常见失败与处理
- | 现象 | 处理 |
- | ---------------------------------------------- | -------------------------------------------------------------------------- |
- | `凭据: 缺失 (无环境变量且无 credentials.json)` | 路径/文件名核对(不是 `.example`);用 `node -e 'JSON.parse(...)'` 验 JSON |
- | `来源: 环境变量+文件混合(可能不完整)` | 只留一处完整的 |
- | `--smoke` 在 `confirm-password` 失败 | 密码错或账号有额外验证(见"已知边界");让用户浏览器登录确认账号可用 |
- | `token 403` | cookie 陈旧:删 `data/cookies.json` 重跑 `--smoke`;或出网没放行 `muse.ai` |
- | `sodium-native 未安装` | 回步骤 2 装依赖 |
- | 权限不是 600/700 | `chmod 700 data && chmod 600 data/credentials.json` |
- ---
- ## 七、步骤 4:启动、停止
- **目标**:从演练到常驻,掌握停止/重启。
- > **顺序**:`--smoke`(真登录)→ `--once --dry`(连网关、只看不批)→ `--once`(真批一轮)→ 常驻(nohup)。
- > **默认参数**:不带参数就是 10 秒轮询 + `allow_always` + 失败回退 `allow_once`。策略 B 用 `--decision allow_once`。
- > **停止**:优雅停 `touch data/muse-daemon.stop`(≤10 秒退出,**保活不会拉起它**——维护模式);前台 Ctrl+C;强杀 `kill "$(cat data/muse-daemon.pid)"`。
- > **防重复**:已在跑时再启动会打印 `another muse-daemon is already running: pid X -> exit` 并退出 0(设计,不是故障)。
- ### ① 🤖 AI 执行(命令)
- ```bash
- APP=~/workspace/muse-guardian/MuseAutoApprove; cd "$APP"
- export PATH="$HOME/.local/bin:$PATH"
- # 1) 演练:连网关、拉列表、只看不批
- node muse-daemon.cjs --once --dry; echo "rc=$?"
- tail -n 10 log/daemon-log.ndjson
- # 2) 常驻(后台)
- mkdir -p log
- nohup node muse-daemon.cjs --loop 10000 --always --fallback-once >> log/muse-console.log 2>&1 &
- echo "pid=$!"; sleep 8
- pgrep -f "[m]use-daemon.cjs" >/dev/null && echo "在跑"
- tail -n 5 log/daemon-log.ndjson
- ```
- 期望日志依次出现 `daemon_start`(含 decision/scope/proxy)→ `connected` → `heartbeat`(每 10 秒一条,`pending` 为当前待批数)。`pending:0` 是常态,不是失败。
- **日常操作**:
- ```bash
- pgrep -f "[m]use-daemon.cjs" # 查进程
- tail -f log/daemon-log.ndjson # 实时日志
- touch data/muse-daemon.stop # 优雅停(维护模式)
- rm data/muse-daemon.stop # 恢复
- kill "$(cat data/muse-daemon.pid)" # 强停(接入保活后 1 分钟内拉回)
- cd "$APP" && node work/muse-rpc.cjs list # 审批列表
- node work/muse-rpc.cjs detail '<id>' # 单条详情
- ```
- ### ② 💬 对用户说(可原样发送)
- > ▶️ 启动分两步:先真登录验证一次(邮箱会收到一封验证码邮件,**不用管**),再做一次"只看不批"的演练;都过了我才挂后台。
- > 之后想停就跟我说(我放停止标记,保活也不会拉起它)。
- ### ③ 🙋 用户手动做
- - 无。
- ### ④ ✅ 做完的标志
- ```bash
- cd ~/workspace/muse-guardian/MuseAutoApprove
- pgrep -f "[m]use-daemon.cjs" >/dev/null && echo "在跑"
- tail -n 20 log/daemon-log.ndjson # 期望 daemon_start → connected → heartbeat
- ```
- ### ⑤ 🛠️ 常见失败与处理
- | 现象 | 处理 |
- | ------------------------------------------------------------------ | ------------------------------------------------------------------- |
- | `connect_retry ... ENOENT ... cookies.json` 后紧跟 `auto_login_ok` | 正常自愈(首次无会话),不用管 |
- | `token 403` 反复 | 出网没放行 `muse.ai`,或 cookie 陈旧(删 `data/cookies.json` 重登) |
- | `fetch failed` / 连不上 | 出网没放行或网络不通;需代理才设 `MUSE_PROXY`(默认直连) |
- | 退出码 2 + 中文提示 | 无凭据无会话,回步骤 3 |
- | `another muse-daemon is already running` | 已有实例(pid 守卫);重启先停 |
- | `DAEMON FATAL` | 看 console 日志里的具体错误;依赖缺失回步骤 2 |
- | 启动后没有 heartbeat | 看进程在不在;不在就回上一行 |
- ---
- # 模块 B|监控与探针(CF 后台 + cf-probe,步骤 5–6)
- 先把 Cloudflare 上的监控后台跑起来,再给沙盒装上探针每分钟上报心跳——**这是后面「重建后自动恢复」能不能被外部看见的前提**。后台部署可以 AI 全自动(要 CF Token),也可以用户自己在网页点。
- ## 八、步骤 5:部署 CF Server Monitor 后台(Cloudflare Workers)
- **目标**:把监控后台跑起来,拿到 Worker 域名。
- > 构建命令 `npm run build:frontend`,部署命令 `npx wrangler deploy`。
- > Worker 需要 **`API_SECRET`**(Variables and Secrets),它同时是「Agent 上报密钥」与「后台初始登录密码」。
- > `wrangler.toml` 已声明 D1 绑定 `DB`(库名 `server-monitor-db`)与 DO `MetricsBroadcaster`(首次部署自动创建)。
- ### ① 🤖 AI 执行(命令)
- **先问用户走哪条路**(话术见 ②):路径 A 你全自动做,路径 B 用户在网页上点几下。
- **路径 A:AI 用 wrangler 全自动部署(需要用户的 Cloudflare API Token)**
- ```bash
- # 1. Token 只放环境变量,绝不写文件(用户通过安全页面给你)
- export CLOUDFLARE_API_TOKEN='<用户提供的 Token>'
- export PROBE_API_SECRET='<用户生成的 API_SECRET>' # 用户生成后经安全页面给你;探针上报与后台初始密码都用它
- npx wrangler --version || npm i -g wrangler # 没有 wrangler 就装
- # 2. 取代码
- git clone https://github.com/huilang-me/CF-Server-Monitor /tmp/cf-server-monitor
- cd /tmp/cf-server-monitor
- # 3. 看 D1 库是否存在;不存在就建(wrangler.toml 里绑定名是 DB、库名是 server-monitor-db)
- npx wrangler d1 list || true
- npx wrangler d1 create server-monitor-db || true # 已存在会报 already exists,忽略
- # 4. 构建前端 + 部署(缺了 build:frontend 会部署出一个没有前端的 Worker)
- npm run build:frontend
- npx wrangler deploy
- # 5. 设置 Worker 密钥(Agent 上报密钥 = 后台初始密码);值从环境变量读,不进 shell 历史
- printf '%s' "$PROBE_API_SECRET" | npx wrangler secret put API_SECRET
- # 6. 立刻清理 Token
- unset CLOUDFLARE_API_TOKEN PROBE_API_SECRET
- ```
- **路径 B:用户在网页上部署(更省事,推荐给不想把 Token 交出来的用户)**
- - 一键部署:打开 `https://deploy.workers.cloudflare.com/?url=https://github.com/huilang-me/CF-Server-Monitor`,确认 Build command 是 `npm run build:frontend`,把 `API_SECRET` 改成随机强密码(不要用默认值);
- - 或:Fork 仓库 → Cloudflare Dashboard → Workers & Pages → 从 GitHub 仓库导入 → 构建命令 `npm run build:frontend`、部署命令 `npx wrangler deploy`;
- - 部署后在 Worker 的 **Settings → Variables and Secrets** 添加 `API_SECRET`(类型选 Secret),保存并等重新部署完成。
- ### ② 💬 对用户说(可原样发送)
- > ☁️ 第一步先把监控后台部署起来。它跑在 Cloudflare Workers 上,你账号的免费额度就够。
- >
- > 有两条路,你挑一条:
- >
- > **A. 我来部署**:需要一个 Cloudflare API Token,用一次就丢,不写任何文件。拿 Token:
- >
- > 1. 打开 https://dash.cloudflare.com/profile/api-tokens
- > 2. Create Token → 选 **Edit Cloudflare Workers** 模板
- > 3. Account Resources 选你的账号 → Continue → Create Token
- > 4. **通过安全页面发给我**(不要直接贴在聊天里)
- >
- > **B. 你在网页上点**:打开这个一键部署链接(我把链接发你),构建命令保持 `npm run build:frontend`,`API_SECRET` 换成随机强密码,部署完在 Worker 的 Variables and Secrets 里确认 `API_SECRET` 已保存。
- >
- > 另外要先定 **API_SECRET** 这个值(探针上报密钥,也是后台初始登录密码)。两种做法:
- >
- > - **推荐**:你自己用密码管理器生成一串 32 位随机串(只含字母数字),通过安全页面给我;
- > - 或者我生成、在聊天里只显示一次——但这样它会进聊天记录,你介意就别选这个。
- >
- > 部署成功后 wrangler / 网页会给出 Worker 域名(形如 `https://cf-server-monitor.<你的子域>.workers.dev`),把它告诉我。
- ### ③ 🙋 用户手动做
- - 选路径 A:创建 Token → 走安全页面发给你;选路径 B:在 Cloudflare 网页完成部署。
- - 自己生成或接收 `API_SECRET`。
- - 把 Worker 域名告诉你。
- ### ④ ✅ 做完的标志
- ```bash
- export WORKER_URL='https://cf-server-monitor.<你的子域>.workers.dev' # 真实值只放环境变量
- curl -sS -m 10 -o /dev/null -w 'HTTP %{http_code}\n' "$WORKER_URL/" # 期望 200(不是 404 / 1101)
- curl -sS -m 10 -o /dev/null -w 'admin HTTP %{http_code}\n' "$WORKER_URL/admin" # 期望 200
- ```
- 另外要用户确认:浏览器打开 `$WORKER_URL/admin#/admin`,用 **用户名 `admin` + 密码 = `API_SECRET`** 能登录进后台。
- 登录成功即视为这一步完成。**顺手提醒用户**:登录后立刻在后台把管理员用户名/密码改掉(后台密码可以和 `API_SECRET` 分离,但探针上报必须继续用 `API_SECRET`)。
- ### ⑤ 🛠️ 常见失败与处理
- | 现象 | 原因 | 处理 |
- | --------------------------------- | --------------------------------------------- | ----------------------------------------------------------------------------------- |
- | `Authentication error` / `10000` | Token 权限不对或已撤销 | 让用户按上面的模板重建一个;确认账户资源选的是目标账号 |
- | 部署成功但页面 404 | 没跑 `npm run build:frontend`,`dist/` 不存在 | 补跑构建再 `npx wrangler deploy` |
- | 接口返回 `API_SECRET is required` | Worker 没读到环境变量 | 在 Variables and Secrets 里删掉旧值重新添加 `API_SECRET`,保存后等重新部署 |
- | `D1 database already exists` | 以前部署过 | 正常,复用即可(`npx wrangler d1 list` 确认库名是 `server-monitor-db`) |
- | 部署卡住不动 | 网络问题 | Ctrl+C 重试一次;仍失败让用户看 Cloudflare 账号状态 |
- | `wrangler` 报 DO namespace 未创建 | 首次部署 | 重新 `npx wrangler deploy` 一次(`wrangler.toml` 的 `[[migrations]]` 会在部署时建) |
- ---
- ## 九、步骤 6:装 cf-probe 探针
- **目标**:让沙盒每 60 秒向 CF 后台报一次心跳,后台能看到这台机器在线。
- > 安装器 `install.sh`,服务名固定 `cf-probe`;root 路径:二进制 `/usr/local/bin/cf-probe`、配置 `/etc/config/cf-probe/config.conf`、日志 `journalctl -u cf-probe -f`。
- > 必填 `-id`(服务器 ID)、`-secret`(= Worker 的 `API_SECRET`)、`-url`(Worker 上报地址)。
- > **后台「添加服务器」可生成带全套参数的安装命令,直接用它的。**
- ### ① 🤖 AI 执行(命令)
- ```bash
- # 0. 先建目录(探针脚本要落在这里,$HOME 下才不会被重建带走)
- mkdir -p ~/workspace/setup/logs
- # 1. 让用户在 CF 后台「添加服务器」,把生成的安装命令发你。它会带齐 -id / -secret / -url 等参数。
- # 形如: cf-probe install -id=<服务器ID> -secret=<API_SECRET> -url=https://<worker>/update -interval=60 ...
- # 2. 落盘安装脚本(代码见下,三个占位符替换成真实值),权限 600
- # 写完后先自检:不能有残留占位符
- grep -q '<PROBE_ID>\|<API_SECRET>\|<WORKER_URL>' ~/workspace/setup/install-cf-probe.sh \
- && echo "ERROR: 占位符未替换" || echo "占位符已替换干净"
- chmod 600 ~/workspace/setup/install-cf-probe.sh
- # 3. 落盘启动器(完整代码见本节末尾「代码 2/13」;把那段代码原样写进文件,然后:)
- chmod +x ~/workspace/setup/run-probe-install.sh
- # 4. 用启动器安装(不要直接跑 install-cf-probe.sh)
- bash ~/workspace/setup/run-probe-install.sh; echo "rc=$?"
- tail -20 ~/workspace/setup/logs/probe-install.log
- # 5. 立刻缓存一份二进制(完整代码见本节末尾「代码 3/13」;写进文件后执行)
- chmod +x ~/workspace/setup/cache-cf-probe-bin.sh
- bash ~/workspace/setup/cache-cf-probe-bin.sh
- ```
- **为什么必须走 `run-probe-install.sh`**:cf-probe 的 Go 安装器在安装时会按 cmdline 关键字清理旧进程,直接调用 `install-cf-probe.sh` 会导致**调用者自己的 shell 被误杀**(因为你的命令行里出现了那个关键字)。启动器的对策是:把安装脚本复制到**不含关键字的临时路径**、用 `setsid` 放进**独立会话**再跑。
- ### ② 💬 对用户说(可原样发送)
- > 📡 现在装探针——它是整套系统的"眼睛",每 60 秒给 CF 后台上报一次这台机器的状态。
- >
- > 请做两件事:
- >
- > 1. 打开后台 `https://<worker域名>/admin#/admin`(用户名 `admin`,密码是你刚设的 `API_SECRET`),
- > 在「服务器管理」里**添加服务器**,名称可以填 `sandbox-main` 或你习惯的名字;
- > 2. 点「复制」拿安装命令(选对系统和版本),**整条命令贴给我**。
- >
- > 那条命令里会带 `-id=`、`-secret=`、`-url=` 这些参数,我把它写成安装脚本落到沙盒里。
- > 提示:这条命令里含你的密钥,贴给我的时候没关系(我会写进 600 权限的文件,不会写进任何文档或记忆)。
- ### ③ 🙋 用户手动做
- - 在 CF 后台添加服务器,把生成的安装命令贴给你。
- - 等 60–90 秒后,回后台看这台服务器是否**在线**、有没有数据上报。
- ### ④ ✅ 做完的标志
- ```bash
- systemctl is-active cf-probe # 期望 active
- systemctl status cf-probe --no-pager | head -5
- journalctl -u cf-probe -n 5 --no-pager -o cat # 期望看到 started / WSS connected
- ls -l /etc/config/cf-probe/config.conf # 期望存在(root 安装路径)
- ```
- 判据:`active` + 日志里有连接成功行 + **用户确认后台里这台机器在线**(三个都满足才往下走)。
- 注意日志里的域名属于用户资产,**不要**把它复制进任何文档。
- ### ⑤ 🛠️ 常见失败与处理
- | 现象 | 原因 | 处理 |
- | ---------------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
- | 后台看不到服务器 | `-secret` 与 Worker 的 `API_SECRET` 不一致 | 让用户核对两处值是否完全相同(大小写、有无引号) |
- | 安装脚本报"占位符未替换" | 三个占位符有残留 | 重新替换后用 `grep -q '<PROBE_ID>\|…'` 自检 |
- | 安装成功但服务不 active | 系统没有 systemd 或权限不足 | `systemctl --version` 确认;非 root 环境用 `systemctl --user`(非 root 安装时二进制在 `~/.cf-probe/`) |
- | 安装过程中调用者 shell 被杀 | 直接跑了 `install-cf-probe.sh` | 改用 `bash ~/workspace/setup/run-probe-install.sh` |
- | 下载 install.sh 失败 | GitHub 不通 | 有本地缓存 `cf-probe-install.saved.sh` 会自动兜底;没有缓存就先在能上网的机器上抓一份带过去 |
- | 探针报了但一直离线 | `-url` 少了 `/update` 或域名错 | 对照后台生成的命令核对 `-url=` |
- | 绑定/上报都正常,但流量/CPU 是空的 | 采集间隔为 0(`-collect_interval=0` 表示不额外采样) | 这是默认值,需要更细数据再在后台改参数(探针会自动拉取) |
- ### 代码 1/13:`install-cf-probe.sh`(含密钥,权限 600,模板含 3 个占位符)
- **目标路径**:`~/workspace/setup/install-cf-probe.sh`
- ```bash
- #!/usr/bin/env bash
- # install-cf-probe.sh — 安装/重装 cf-probe 探针(幂等,可反复执行)。
- #
- # 【本文件含真实密钥,权限必须 600】
- # - 不要提交到任何仓库、不要贴进聊天、不要复制到别处。
- # - 部署时把三个占位符换成真实值:<PROBE_ID>、<API_SECRET>、<WORKER_URL>。
- # 换完必须自检一次:grep 不到占位符才算换干净。
- # - 密钥只在这里(+ Cloudflare Worker 的 API_SECRET)落盘,不要再另存副本。
- #
- # 结构对照上游(huilang-me/cfsm-agent install.sh,2026-09-26 核对):
- # 1. 优先下载最新安装器,失败时用本地缓存 cf-probe-install.saved.sh,
- # 下载成功顺手更新缓存——重建时网络不可靠,本地兜底是必须的。
- # 2. 安装命令走 `install -id=… -secret=… -url=<worker>/update …`(参数名与上游一致)。
- # 3. 额外加固(本 SKILL 增加,已实测可用):
- # a. SETUP_DIR 支持 CF_PROBE_SETUP_DIR 覆盖 —— 因为探针安装必须经
- # run-probe-install.sh 启动器,而启动器会把脚本复制到 /tmp 运行,
- # 此时 dirname "$0" 会变成 /tmp,本地缓存就找错地方了。
- # b. 安装器与本地二进制缓存双兜底:无网时可直接跑缓存的 cf-probe 二进制
- # (releases/latest/download/cf-probe-linux-amd64,与安装器下载的同一个文件,
- # 已验证字节一致;该二进制支持 `install` 子命令)。
- set -euo pipefail
- SETUP_DIR="${CF_PROBE_SETUP_DIR:-$(cd "$(dirname "$0")" && pwd)}"
- SAVED="$SETUP_DIR/cf-probe-install.saved.sh"
- LATEST="$SETUP_DIR/cf-probe-install.latest.sh"
- INSTALL_SRC='https://raw.githubusercontent.com/huilang-me/cfsm-agent/main/install.sh'
- # ===== 部署时替换这三行 =====
- PROBE_ID='<PROBE_ID>'
- API_SECRET='<API_SECRET>'
- WORKER_URL='<WORKER_URL>'
- # ==========================
- # 可选:自定义网络质量测试节点(留空=用 agent 内置节点)。
- # CF 后台「添加服务器」生成的安装命令里会带这组参数,原样抄过来即可。
- CT_NODE=''
- CU_NODE=''
- CM_NODE=''
- # 本地二进制缓存(由 cache-cf-probe-bin.sh 生成;按当前架构命名)
- case "$(uname -m)" in
- x86_64|amd64) BIN_ARCH=amd64 ;;
- aarch64|arm64) BIN_ARCH=arm64 ;;
- armv7*|armv8l) BIN_ARCH=armv7 ;;
- *) BIN_ARCH=unsupported ;;
- esac
- BIN_CACHE="$SETUP_DIR/cf-probe-linux-${BIN_ARCH}"
- ARGS=(install "-id=${PROBE_ID}" "-secret=${API_SECRET}" "-url=${WORKER_URL}/update"
- -collect_interval=0 -interval=60 -connection_mode=auto -ping_mode=tcp
- -reset_day=1 -auto_update=0)
- [ -n "$CT_NODE" ] && ARGS+=("-ct=${CT_NODE}")
- [ -n "$CU_NODE" ] && ARGS+=("-cu=${CU_NODE}")
- [ -n "$CM_NODE" ] && ARGS+=("-cm=${CM_NODE}")
- # 占位符自检:没换干净就别装,免得装出个连不上后台的探针
- for v in "$PROBE_ID" "$API_SECRET" "$WORKER_URL"; do
- case "$v" in
- *'<'*'>'*)
- echo "[error] 占位符未替换:$v" >&2
- exit 1 ;;
- esac
- done
- installer=""
- if curl -fsSL "$INSTALL_SRC" -o "$LATEST" 2>/dev/null && [ -s "$LATEST" ]; then
- chmod 600 "$LATEST"
- cp -f "$LATEST" "$SAVED"
- chmod 600 "$SAVED"
- installer="$LATEST"
- echo "[info] 已下载上游安装器,并更新本地缓存 $SAVED"
- elif [ -f "$SAVED" ]; then
- installer="$SAVED"
- echo "[warn] 上游下载失败,使用本地缓存安装器 $SAVED" >&2
- else
- echo "[warn] 上游下载失败且本地无缓存安装器,尝试二进制缓存" >&2
- fi
- if [ -n "$installer" ]; then
- if sh "$installer" "${ARGS[@]}"; then
- echo "OK: cf-probe 安装完成(安装器路径)"
- exit 0
- fi
- echo "[warn] 安装器执行失败,回退到本地二进制缓存" >&2
- fi
- if [ -x "$BIN_CACHE" ]; then
- if "$BIN_CACHE" "${ARGS[@]}"; then
- echo "OK: cf-probe 安装完成(本地二进制缓存 $BIN_CACHE)"
- exit 0
- fi
- echo "[error] 本地二进制缓存安装失败" >&2
- exit 1
- fi
- echo "[error] 无法安装 cf-probe:网络不可达,且没有安装器/二进制缓存。" >&2
- echo "[error] 处理:联网后重跑本脚本,或先跑 cache-cf-probe-bin.sh 缓存二进制(该缓存每次部署都建议做一份)。" >&2
- exit 1
- ```
- ### 代码 2/13:`run-probe-install.sh`(安全启动器)
- **目标路径**:`~/workspace/setup/run-probe-install.sh` **权限**:`chmod +x`
- ```bash
- #!/usr/bin/env bash
- # run-probe-install.sh — 探针安装器的安全启动器。
- # 背景:cf-probe 的 Go 安装器在安装时会按 cmdline 关键字清理旧进程,
- # 直接跑 install-cf-probe.sh 会导致调用者自己的 shell 被误杀(cmdline 含 cf-probe)。
- # 对策:复制到无关键字临时路径 + setsid 独立会话运行,隔离两种误伤。
- #
- # 另一处坑(2026-09-26 复核发现并修掉):install-cf-probe.sh 内部用
- # `dirname "$0"` 定位 setup 目录。脚本被复制到 /tmp 后 $0 是 /tmp 里的临时文件,
- # dirname 会变成 /tmp —— 本地缓存路径(cf-probe-install.saved.sh)就指错了地方,
- # 离线兜底会失败、缓存也永远更新不到真目录。所以这里显式把真目录传下去:
- # 启动器 export CF_PROBE_SETUP_DIR,安装脚本优先读它。
- set -uo pipefail
- SETUP_DIR="${CF_PROBE_SETUP_DIR:-$(cd "$(dirname "$0")" && pwd)}"
- SRC="$SETUP_DIR/install-cf-probe.sh"
- LOG="$SETUP_DIR/logs/probe-install.log"
- mkdir -p "$SETUP_DIR/logs"
- TMP_RUN="$(mktemp /tmp/.sysinit-XXXXXXXX.sh)"
- cp "$SRC" "$TMP_RUN"
- chmod 600 "$TMP_RUN"
- # 独立会话(新进程组),安装器即使杀进程组也伤不到调用者
- export CF_PROBE_SETUP_DIR="$SETUP_DIR"
- setsid bash "$TMP_RUN" >"$LOG" 2>&1 < /dev/null &
- pid=$!
- if wait "$pid"; then
- rc=0
- else
- rc=$?
- fi
- rm -f "$TMP_RUN"
- exit "$rc"
- ```
- ### 代码 3/13:`cache-cf-probe-bin.sh`(二进制离线缓存)
- **目标路径**:`~/workspace/setup/cache-cf-probe-bin.sh` **权限**:`chmod +x`
- ```bash
- #!/usr/bin/env bash
- # cache-cf-probe-bin.sh — 把 cf-probe 二进制缓存到本地,供重建后无网时离线安装。
- #
- # 为什么需要它:install-cf-probe.sh 只缓存了「安装脚本」,而安装脚本本身还要去
- # GitHub releases 下载 8MB 左右的二进制。网络不可达时(国内沙盒常见)这一步会失败,
- # 探针就装不上。把二进制也缓存一份到 $HOME(沙盒重建不丢),恢复时零下载。
- #
- # 已验证(2026-09-26):该 URL 下回来的二进制与安装器装到 /usr/local/bin/cf-probe
- # 的文件字节完全一致(sha256 相同),且 `--help` 里能看到 `cf-probe install` 子命令。
- set -uo pipefail
- SETUP_DIR="${CF_PROBE_SETUP_DIR:-$(cd "$(dirname "$0")" && pwd)}"
- case "$(uname -m)" in
- x86_64|amd64) ARCH=amd64 ;;
- aarch64|arm64) ARCH=arm64 ;;
- armv7*|armv8l) ARCH=armv7 ;;
- *) echo "[error] 不支持的架构 $(uname -m)" >&2; exit 1 ;;
- esac
- URL="https://github.com/huilang-me/cfsm-agent/releases/latest/download/cf-probe-linux-${ARCH}"
- OUT="$SETUP_DIR/cf-probe-linux-${ARCH}"
- TMP="$OUT.tmp.$$"
- echo "[info] 下载 $URL"
- if ! curl -fL --connect-timeout 10 -m 300 -o "$TMP" "$URL"; then
- rm -f "$TMP"
- echo "[error] 下载失败,二进制缓存未更新" >&2
- exit 1
- fi
- chmod 755 "$TMP"
- # 自检:能识别 install 子命令才算是个能用的探针二进制
- if ! timeout 10 "$TMP" --help 2>&1 | grep -q 'cf-probe install'; then
- rm -f "$TMP"
- echo "[error] 下载的文件不像 cf-probe 二进制(自检失败),已丢弃" >&2
- exit 1
- fi
- mv -f "$TMP" "$OUT"
- sha256sum "$OUT" | awk '{print $1}' > "$OUT.sha256"
- echo "OK: 已缓存 $OUT ($(stat -c %s "$OUT") 字节)"
- echo " sha256=$(cat "$OUT.sha256")"
- ```
- ---
- # 模块 C|保活底座(脚本落盘 + 离线包,步骤 7–8)
- 把全部保活脚本落盘到 `$HOME`,再把 `cron`/`openssh` 依赖闭包和探针二进制缓存到本地——**重建后不依赖网络也能把系统组件装回来**。这一模块**全自动,不需要用户做任何事**。
- ## 十、步骤 7:持久化布局(把保活脚本全部落盘)
- **目标**:把 7 个保活脚本放到 `$HOME/workspace/setup/`,全部可执行、全部语法检查通过。
- > **重建后 `$HOME` 保留,系统目录全丢**。在:`~/workspace/`、`~/.hermes/`(程序与数据)、`~/.local/bin/`。不在:`/usr/local/bin/cf-probe`、`/etc/systemd/system/cf-probe.service`、`/etc/config/cf-probe/`、`/usr/sbin/sshd`、root crontab、`/tmp`。恢复脚本就是把这些按需重装。
- ### ① 🤖 AI 执行(命令)
- ```bash
- mkdir -p ~/workspace/setup/deb-cache ~/workspace/setup/logs
- mkdir -p ~/workspace/backups/hermes-home ~/workspace/tools ~/.hermes/memories
- # 把本节末尾的 7 个脚本按路径落盘,然后统一设置权限 + 语法检查
- chmod +x ~/workspace/setup/*.sh
- for f in ~/workspace/setup/*.sh; do bash -n "$f" && echo "OK $f" || echo "FAIL $f"; done
- ls -l ~/workspace/setup/*.sh
- ```
- ### ② 💬 对用户说(可原样发送)
- > 🧱 接下来装保活脚本。先跟你说清"什么会丢、什么不会丢",以后沙盒被重建你就知道发生了什么:
- >
- > - **重建后还在**:`~/workspace/` 里的脚本和离线包、`~/.hermes/` 里的 Hermes 程序和数据、备份。
- > - **重建后会丢**:探针二进制、systemd 服务、ssh/cron 这些系统组件、root 的定时任务、`/tmp` 里的东西。
- >
- > 丢掉的那些不需要你操心——恢复脚本会把它们重新装回来。你什么都不用做,我继续。
- ### ③ 🙋 用户手动做
- 无(这一步全自动)。
- ### ④ ✅ 做完的标志
- ```bash
- for f in watchdog.sh health-check.sh restore-all.sh lib-pkgs.sh \
- restore-hermes.sh backup-hermes.sh run-probe-install.sh; do
- [ -x "$HOME/workspace/setup/$f" ] && echo "OK $f" || echo "MISSING/NOT-EXEC $f"
- done
- bash -n ~/workspace/setup/restore-all.sh && echo "restore-all.sh 语法 OK"
- ```
- 判据:7 个脚本全部 `OK`,没有 `MISSING/NOT-EXEC`,语法检查无 FAIL。
- ### ⑤ 🛠️ 常见失败与处理
- | 现象 | 原因 | 处理 |
- | ------------------------------ | ----------------------------------------- | --------------------------------------------------------------------------------------- |
- | `bash -n` 报 `missing ']'` | 脚本被复制时丢了空格(如 `[ -f "$deb"]`) | 重新从本手册复制;本手册的代码是校验过语法的 |
- | 脚本落盘后权限不对 | 用了 `cp` 但源文件不可执行 | `chmod +x ~/workspace/setup/*.sh` |
- | `logs/` 不存在导致看门狗报错 | 没建目录 | 看门狗自己会 `mkdir -p`,但仍建议先建好 |
- | Hermes 在 `$HOME=/root` 下运行 | 平台注入的 HOME 异常 | 三个脚本都有 HOME 加固(HOME 下找不到 setup 但 `/home/hatch` 有就纠正),保持这段不要删 |
- ### 代码 4/13:`lib-pkgs.sh`(离线 deb 安装公共函数)
- **目标路径**:`~/workspace/setup/lib-pkgs.sh` **权限**:`chmod +x`
- ```bash
- #!/usr/bin/env bash
- # lib-pkgs.sh — 离线 deb 安装公共函数(被 watchdog.sh / restore-all.sh source)。
- # 策略:只安装缺失的包(避免降级镜像自带的新版本);
- # dpkg 跑两遍,第二遍解决 pre-depends 顺序问题(如 cron 依赖 cron-daemon-common 先 configure)。
- # 等待 dpkg/apt 锁释放。重建刚完成时平台自己的包 reconciliation 可能占着锁,
- # 直接 dpkg 会失败;最多等 10 分钟,每 15 秒检查一次(见 skill 避坑)。
- wait_for_dpkg_lock() {
- local waited=0
- while fuser /var/lib/dpkg/lock-frontend >/dev/null 2>&1 \
- || fuser /var/lib/dpkg/lock >/dev/null 2>&1; do
- if [ "$waited" -ge 600 ]; then
- return 1
- fi
- sleep 15
- waited=$((waited + 15))
- done
- return 0
- }
- # install_offline_debs <deb-cache-dir> [log-file]
- # 返回 0 表示成功(或无需安装),非 0 表示失败。
- install_offline_debs() {
- local cache_dir="$1" log_file="${2:-/dev/null}"
- local missing="" deb pkg
- for deb in "$cache_dir"/*.deb; do
- [ -f "$deb" ] || continue
- pkg="$(dpkg-deb -f "$deb" Package 2>/dev/null)"
- if [ -n "$pkg" ] && ! dpkg -l "$pkg" 2>/dev/null | grep -q "^ii"; then
- missing="$missing $deb"
- fi
- done
- if [ -z "$missing" ]; then
- return 0
- fi
- if ! wait_for_dpkg_lock; then
- echo "dpkg 锁等待超时" >>"$log_file"
- return 1
- fi
- # shellcheck disable=SC2086
- if DEBIAN_FRONTEND=noninteractive dpkg --force-confdef --force-confold -i $missing >>"$log_file" 2>&1; then
- return 0
- fi
- # 第一遍可能因 pre-depends 顺序失败:configure 已解包的包,再装一遍
- dpkg --configure -a >>"$log_file" 2>&1 || true
- # shellcheck disable=SC2086
- if DEBIAN_FRONTEND=noninteractive dpkg --force-confdef --force-confold -i $missing >>"$log_file" 2>&1; then
- dpkg --configure -a >>"$log_file" 2>&1 || true
- return 0
- fi
- dpkg --configure -a >>"$log_file" 2>&1 || true
- return 1
- }
- ```
- ### 代码 5/13:`watchdog.sh`(Layer 1 沙盒内看门狗)
- **目标路径**:`~/workspace/setup/watchdog.sh` **权限**:`chmod +x`
- ```bash
- #!/usr/bin/env bash
- # watchdog.sh — 每 1 分钟巡检:cf-probe 探针 / hermes 微信网关 / sshd。
- # 挂了就地修复;修不好写日志。设计遵循 awesome-skills/muse-reverse-ssh:
- # 原子 mkdir 单实例锁(不用 flock,避免 fd 被子进程继承导致锁死)、
- # pgrep 中括号技巧(避免匹配到检查进程自身)、/proc cmdline 校验。
- set -uo pipefail
- # HOME 加固:若当前 HOME 下找不到 setup 目录但 /home/hatch 下有,
- # 说明运行环境异常(如 HOME=/root),纠正后再继续(见 skill 避坑)
- if [ ! -d "$HOME/workspace/setup" ] && [ -d /home/hatch/workspace/setup ]; then
- export HOME=/home/hatch
- fi
- SETUP_DIR="$HOME/workspace/setup"
- LOG="$SETUP_DIR/logs/watchdog.log"
- LOCKDIR="$SETUP_DIR/.watchdog.lock"
- LOG_MAX_BYTES=$((10 * 1024 * 1024)) # 任何日志文件的上限:10MB
- # shellcheck disable=SC1091
- . "$SETUP_DIR/lib-pkgs.sh" 2>/dev/null || true
- export PATH="$HOME/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
- log() { echo "[$(date '+%F %T')] $*" >> "$LOG"; }
- # --- 日志裁剪:任何日志文件超过 10MB,只保留末尾 10MB ---
- # 覆盖本体系所有日志:脚本日志、MAA 日志、Hermes 网关日志、hook 探针日志。
- # 用 tail -c 取字节并 sed 丢掉首行(避免留下半行)。
- trim_log_file() {
- local f="$1" sz tmp
- [ -f "$f" ] || return 0
- sz="$(stat -c %s "$f" 2>/dev/null || echo 0)"
- [ "$sz" -gt "$LOG_MAX_BYTES" ] || return 0
- tmp="${f}.trim.$$"
- if tail -c "$LOG_MAX_BYTES" "$f" | sed '1d' > "$tmp" 2>/dev/null; then
- mv -f "$tmp" "$f"
- log "日志已裁剪至 10MB:$f"
- else
- rm -f "$tmp"
- fi
- }
- # --- 单实例锁(原子 mkdir;目录不会被子进程继承) ---
- if ! mkdir "$LOCKDIR" 2>/dev/null; then
- if [ -f "$LOCKDIR/pid" ]; then
- oldpid=$(cat "$LOCKDIR/pid" 2>/dev/null || true)
- if [ -n "$oldpid" ] && [ -f "/proc/$oldpid/cmdline" ] \
- && tr '\0' ' ' < "/proc/$oldpid/cmdline" 2>/dev/null | grep -q "[/]watchdog.sh"; then
- exit 0 # 另一个实例还活着,静默退出
- fi
- fi
- rm -rf "$LOCKDIR"
- mkdir "$LOCKDIR" 2>/dev/null || exit 0 # 抢锁失败就退出
- fi
- echo $$ > "$LOCKDIR/pid"
- trap 'rm -rf "$LOCKDIR"' EXIT
- mkdir -p "$SETUP_DIR/logs"
- # --- 1. cf-probe 探针 ---
- if [ -f /etc/systemd/system/cf-probe.service ]; then
- if ! systemctl is-active -q cf-probe 2>/dev/null; then
- log "cf-probe 未运行,尝试 systemctl restart"
- if systemctl restart cf-probe >>"$LOG" 2>&1; then
- log "cf-probe 重启成功"
- else
- log "cf-probe 重启失败"
- fi
- fi
- else
- log "cf-probe 服务文件丢失,执行重装"
- if bash "$SETUP_DIR/run-probe-install.sh" >>"$LOG" 2>&1; then
- log "cf-probe 重装成功"
- else
- log "cf-probe 重装失败"
- fi
- fi
- # --- 2a. hermes 微信网关:进程活着但连接卡死 ---
- # 对应 skill 的 "A live tunnel process does not mean a live tunnel":
- # 只查进程查不出微信 poll 卡死,看日志里 poll error 是否持续超过 5 分钟。
- WXLOG="$HOME/.hermes/logs/weixin-gateway.log"
- WX_RESTART_TS="$SETUP_DIR/.wx-wedged-restart-ts"
- if pgrep -f "hermes-agent.*[g]ateway" >/dev/null 2>&1 && [ -f "$WXLOG" ]; then
- since="$(date -d '10 minutes ago' '+%F %T')"
- mapfile -t wxerrs < <(awk -v since="$since" \
- 'index($0,"poll error")>0 && substr($0,1,19)>=since {print substr($0,1,19)}' "$WXLOG" 2>/dev/null)
- if [ "${#wxerrs[@]}" -ge 3 ]; then
- first_ts="${wxerrs[0]}"; last_ts="${wxerrs[$((${#wxerrs[@]}-1))]}"
- if [ "$(date -d "$last_ts" +%s)" -gt "$(( $(date -d "$first_ts" +%s) + 300 ))" ]; then
- # 15 分钟内只因卡死重启一次,避免全网故障时反复重启
- now="$(date +%s)"; last_restart=0
- [ -f "$WX_RESTART_TS" ] && last_restart="$(cat "$WX_RESTART_TS" 2>/dev/null || echo 0)"
- if [ "$((now - last_restart))" -ge 900 ]; then
- log "微信 poll 持续报错超过 5 分钟($first_ts ~ $last_ts),判定连接卡死,重启网关"
- # 精确 kill:优先 gateway.pid。注意该文件是 JSON({"pid":123,"kind":"hermes-gateway",...}),
- # 不能直接 cat 当数字用;解析出 pid 后还要校验 /proc/<pid>/cmdline 命中网关进程模式(hermes-agent.*[g]ateway)。
- # 拿不到有效 pid 才枚举 pgrep 命中进程,并排除自身与父进程——
- # 不用 `pkill -f`:一行命令里出现过网关关键字(比如包装它的 bash -c)也会被误杀。
- killed=0
- gpid=""
- if [ -f "$HOME/.hermes/gateway.pid" ]; then
- if command -v jq >/dev/null 2>&1; then
- gpid="$(jq -r '.pid // empty' "$HOME/.hermes/gateway.pid" 2>/dev/null || true)"
- fi
- if [ -z "$gpid" ]; then
- gpid="$(python3 -c 'import json,sys;print(json.load(open(sys.argv[1])).get("pid",""))' \
- "$HOME/.hermes/gateway.pid" 2>/dev/null || true)"
- fi
- if [ -n "$gpid" ] && [ -f "/proc/$gpid/cmdline" ] \
- && tr '\0' ' ' < "/proc/$gpid/cmdline" 2>/dev/null | grep -q "hermes-agent.*[g]ateway"; then
- kill -TERM "$gpid" 2>/dev/null && killed=1
- for _ in 1 2 3 4 5 6 7 8 9 10; do
- kill -0 "$gpid" 2>/dev/null || break
- sleep 1
- done
- if kill -0 "$gpid" 2>/dev/null; then
- kill -KILL "$gpid" 2>/dev/null || true
- sleep 1
- fi
- fi
- fi
- if [ "$killed" = 0 ]; then
- for p in $(pgrep -f "hermes-agent.*[g]ateway" 2>/dev/null); do
- [ "$p" = "$$" ] && continue
- [ "$p" = "$PPID" ] && continue
- kill -TERM "$p" 2>/dev/null || true
- done
- fi
- echo "$now" > "$WX_RESTART_TS"
- sleep 3
- else
- log "微信 poll 持续报错,但 15 分钟内已重启过,跳过"
- fi
- fi
- fi
- unset wxerrs
- fi
- # --- 2b. hermes 微信网关:进程缺失则重启 ---
- # 进程行有新老两种形态:`hermes gateway run` 与 `python3 -I -c` 包装(cmdline 里是 hermes-agent 路径)。统一用 hermes-agent.*[g]ateway 检测,两种都能命中;[g] 避免自匹配。
- if ! pgrep -f "hermes-agent.*[g]ateway" >/dev/null 2>&1; then
- log "hermes gateway 进程丢失,尝试重启"
- if compgen -G "$HOME/.hermes/weixin/accounts/*.json" > /dev/null 2>&1; then
- mkdir -p "$HOME/.hermes/logs"
- nohup hermes gateway run >> "$HOME/.hermes/logs/weixin-gateway.log" 2>&1 &
- sleep 3
- if pgrep -f "hermes-agent.*[g]ateway" >/dev/null 2>&1; then
- log "hermes gateway 重启成功"
- else
- log "hermes gateway 重启后仍无进程"
- fi
- else
- log "无微信账号凭据,跳过网关重启"
- fi
- fi
- # --- 3. sshd ---
- if [ ! -x /usr/sbin/sshd ]; then
- log "sshd 二进制丢失,尝试从离线缓存重装"
- if install_offline_debs "$SETUP_DIR/deb-cache" "$LOG" && [ -x /usr/sbin/sshd ]; then
- log "openssh-server 离线重装成功"
- else
- log "离线重装失败,回退到 apt"
- apt-get install -y openssh-server >>"$LOG" 2>&1 || log "openssh-server 安装失败"
- fi
- fi
- if [ -x /usr/sbin/sshd ]; then
- mkdir -p /run/sshd
- chown root:root /run/sshd; chmod 755 /run/sshd
- [ -f /etc/ssh/ssh_host_rsa_key ] || ssh-keygen -A >>"$LOG" 2>&1
- if ! pgrep -f "[/]usr/sbin/sshd" >/dev/null 2>&1; then
- log "sshd 未运行,尝试启动"
- if /usr/sbin/sshd >>"$LOG" 2>&1; then
- # 刚启动完立即检查在负载高时可能误判,重试 3 次 × 2 秒(见 skill 避坑)
- ok=0
- for i in 1 2 3; do
- sleep 2
- if pgrep -f "[/]usr/sbin/sshd" >/dev/null 2>&1; then ok=1; break; fi
- done
- [ "$ok" = 1 ] && log "sshd 启动成功" || log "sshd 启动后仍无进程(3 次重试)"
- else
- log "sshd 启动失败"
- fi
- fi
- else
- log "sshd 二进制仍缺失,本次跳过"
- fi
- # --- 4. 日志裁剪:把所有日志压回 10MB 以内 ---
- for f in "$LOG" \
- "$HOME/.hermes/logs/weixin-gateway.log" \
- "$HOME/workspace/muse-guardian/MuseAutoApprove"/log/*.ndjson \
- "$HOME/workspace/muse-guardian/MuseAutoApprove"/log/muse-console.log \
- "$HOME/hooks/logs"/*.jsonl \
- "$SETUP_DIR/logs"/*.log; do
- trim_log_file "$f"
- done
- log "巡检完成"
- ```
- ### 代码 6/13:`health-check.sh`(健康检查,0=健康 / 1=需恢复)
- **目标路径**:`~/workspace/setup/health-check.sh` **权限**:`chmod +x`
- ```bash
- #!/usr/bin/env bash
- # health-check.sh — 沙盒健康检查,供平台 hook 探针(keepalive-tripwire)与看门狗调用。
- # 退出码:0=健康;1=需要恢复(疑似重建或关键服务全挂)。实现只返回 0/1;
- # 调用方(hook 探针):rc=1 立即唤醒恢复;非 0/1 累计连续 3 次才唤醒。
- #
- # 检查项(与 watchdog.sh / restore-all.sh 保持一致):
- # 1. cf-probe systemd 服务 active
- # 2. hermes 微信网关进程存活
- # 3. sshd 进程存活
- # 4. cron 进程存活 且 crontab 里有看门狗
- # HOME 加固:若当前 HOME 下找不到 setup 目录但 /home/hatch 下有,
- # 说明运行环境异常(如 HOME=/root),纠正后再继续(见 skill 避坑)
- if [ ! -d "$HOME/workspace/setup" ] && [ -d /home/hatch/workspace/setup ]; then
- export HOME=/home/hatch
- fi
- SETUP_DIR="$HOME/workspace/setup"
- failures=""
- if [ "$(systemctl is-active cf-probe 2>/dev/null)" != "active" ]; then
- failures="$failures cf-probe"
- fi
- if ! pgrep -f "hermes-agent.*[g]ateway" >/dev/null 2>&1; then
- failures="$failures hermes-gateway"
- fi
- if ! pgrep -f "[/]usr/sbin/sshd" >/dev/null 2>&1; then
- failures="$failures sshd"
- fi
- if ! pgrep -f "[/]usr/sbin/cron" >/dev/null 2>&1; then
- failures="$failures cron-daemon"
- fi
- if ! crontab -l 2>/dev/null | grep -q "watchdog.sh"; then
- failures="$failures cron-entry"
- fi
- if [ -z "$failures" ]; then
- echo "OK: all services healthy"
- exit 0
- fi
- # 区分"重建"还是"普通故障":/usr 关键二进制都没了 => 重建
- if [ ! -x /usr/bin/crontab ] || [ ! -x /usr/sbin/sshd ] || [ ! -f /usr/local/bin/cf-probe ]; then
- echo "REBUILD_DETECTED: missing base binaries; failed:$failures"
- exit 1
- fi
- echo "DEGRADED: failed:$failures"
- exit 1
- ```
- ### 代码 7/13:`restore-all.sh`(Layer 3 一键恢复,幂等)
- **目标路径**:`~/workspace/setup/restore-all.sh` **权限**:`chmod +x`
- ```bash
- #!/usr/bin/env bash
- # restore-all.sh — 沙盒重建后一键恢复(幂等,可重复执行):
- # 基础包(cron/openssh, 优先离线缓存) → hermes → cf-probe → cron定时任务 → sshd → 看门狗
- # 锁:脚本内部原子 mkdir(不用外层 flock,避免 fd 被拉起的守护进程继承导致后续恢复被跳过)。
- set -uo pipefail
- # HOME 加固:若当前 HOME 下找不到 setup 目录但 /home/hatch 下有,
- # 说明运行环境异常(如 HOME=/root),纠正后再继续(见 skill 避坑)
- if [ ! -d "$HOME/workspace/setup" ] && [ -d /home/hatch/workspace/setup ]; then
- export HOME=/home/hatch
- fi
- SETUP_DIR="$HOME/workspace/setup"
- LOG="$SETUP_DIR/logs/restore.log"
- LOCKDIR="$SETUP_DIR/.restore.lock"
- MAX_RESTORE_SEC=1200 # 20 分钟:超时视为 stale 锁
- # shellcheck disable=SC1091
- . "$SETUP_DIR/lib-pkgs.sh"
- export PATH="$HOME/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
- export DEBIAN_FRONTEND=noninteractive
- mkdir -p "$SETUP_DIR/logs"
- log() { echo "[$(date '+%F %T')] $*" | tee -a "$LOG"; }
- # --- 单实例锁(带超时的 stale 回收;恢复是限时操作,年龄规则可用) ---
- if ! mkdir "$LOCKDIR" 2>/dev/null; then
- if [ -f "$LOCKDIR/pid" ] && [ -f "$LOCKDIR/started" ]; then
- oldpid=$(cat "$LOCKDIR/pid" 2>/dev/null || true)
- started=$(cat "$LOCKDIR/started" 2>/dev/null || echo 0)
- now=$(date +%s)
- alive=0
- if [ -n "$oldpid" ] && [ -f "/proc/$oldpid/cmdline" ] \
- && tr '\0' ' ' < "/proc/$oldpid/cmdline" 2>/dev/null | grep -q "[/]restore-all.sh"; then
- alive=1
- fi
- if [ "$alive" = 1 ] && [ $((now - started)) -lt "$MAX_RESTORE_SEC" ]; then
- log "已有恢复在进行中,本次退出"
- exit 0
- fi
- log "检测到 stale 锁(pid=$oldpid),回收后继续"
- fi
- rm -rf "$LOCKDIR"
- mkdir "$LOCKDIR" 2>/dev/null || { log "抢锁失败,退出"; exit 0; }
- fi
- echo $$ > "$LOCKDIR/pid"
- date +%s > "$LOCKDIR/started"
- trap 'rm -rf "$LOCKDIR"' EXIT
- log "===== 开始恢复 ====="
- # --- 0. 等 apt/dpkg 锁(重建后平台可能在做包 reconciling,最多等 10 分钟) ---
- for i in $(seq 1 20); do
- if ! fuser /var/lib/dpkg/lock-frontend >/dev/null 2>&1 \
- && ! fuser /var/lib/apt/lists/lock >/dev/null 2>&1; then
- break
- fi
- log "apt/dpkg 锁被占用,等待 30s ($i/20)"
- sleep 30
- done
- # --- 1. 基础包:cron(定时任务)、openssh-server(sshd) ---
- need_pkgs=0
- [ -x /usr/bin/crontab ] || need_pkgs=1
- [ -x /usr/sbin/sshd ] || need_pkgs=1
- if [ "$need_pkgs" = 1 ]; then
- log "安装基础包(优先离线缓存)"
- if install_offline_debs "$SETUP_DIR/deb-cache" "$LOG" \
- && [ -x /usr/bin/crontab ] && [ -x /usr/sbin/sshd ]; then
- log "离线缓存安装成功"
- else
- log "离线缓存不可用/不完整,回退 apt(可能较慢)"
- apt-get update -qq >>"$LOG" 2>&1
- apt-get install -y -o Dpkg::Options::="--force-confdef" -o Dpkg::Options::="--force-confold" \
- cron openssh-server >>"$LOG" 2>&1 || log "WARN: apt 安装基础包失败"
- fi
- else
- log "基础包已存在,跳过"
- fi
- # --- 2. hermes(现有脚本,幂等:重装 + 恢复用户数据 + 重启网关) ---
- log "恢复 hermes"
- bash "$SETUP_DIR/restore-hermes.sh" >>"$LOG" 2>&1 && log "hermes 恢复完成" || log "WARN: hermes 恢复失败"
- # --- 3. cf-probe 探针(安装脚本幂等) ---
- log "安装 cf-probe"
- bash "$SETUP_DIR/run-probe-install.sh" >>"$LOG" 2>&1 && log "cf-probe 安装完成" || log "WARN: cf-probe 安装失败"
- # --- 4. cron 定时任务:看门狗每 1 分钟(仓库推荐 1 分钟一轮询) ---
- if [ -x /usr/bin/crontab ]; then
- (crontab -l 2>/dev/null | grep -v "watchdog.sh"; echo "* * * * * $SETUP_DIR/watchdog.sh") | crontab -
- log "cron 定时任务已写入"
- # 确保 cron 守护进程在跑
- if ! pgrep -f "[/]usr/sbin/cron" >/dev/null 2>&1; then
- (service cron start >>"$LOG" 2>&1 || /usr/sbin/cron >>"$LOG" 2>&1) && log "cron 守护进程已启动" || log "WARN: cron 守护进程启动失败"
- fi
- else
- log "WARN: crontab 不可用,定时任务未写入"
- fi
- # --- 5. sshd ---
- if [ -x /usr/sbin/sshd ]; then
- mkdir -p /run/sshd
- chown root:root /run/sshd; chmod 755 /run/sshd
- [ -f /etc/ssh/ssh_host_rsa_key ] || ssh-keygen -A >>"$LOG" 2>&1
- if ! pgrep -f "[/]usr/sbin/sshd" >/dev/null 2>&1; then
- /usr/sbin/sshd >>"$LOG" 2>&1 && log "sshd 已启动" || log "WARN: sshd 启动失败"
- else
- log "sshd 已在运行"
- fi
- else
- log "WARN: sshd 二进制缺失"
- fi
- # --- 6. 立刻跑一次看门狗做最终校验 ---
- log "运行看门狗做最终校验"
- bash "$SETUP_DIR/watchdog.sh" >>"$LOG" 2>&1
- log "===== 恢复结束 ====="
- echo "OK: 恢复流程结束,详见 $LOG"
- ```
- ### 代码 8/13:`restore-hermes.sh`(Hermes 恢复:健康就什么都不做)
- **目标路径**:`~/workspace/setup/restore-hermes.sh` **权限**:`chmod +x`
- ```bash
- #!/usr/bin/env bash
- # restore-hermes.sh — 沙盒重建后恢复 Hermes Agent(幂等,可反复跑)。
- #
- # 原理:Hermes 的一切都在 $HOME 下(~/.hermes 程序+数据、~/.local/bin 启动器),
- # 沙盒重建只丢系统目录,所以通常只需重跑一次安装脚本即可恢复。
- #
- # 三条硬规则(2026-09-26 实测踩过,违反必然导致微信全链路静默失败):
- # 1. 健康时【完全跳过 installer】。installer 的 post-build maintenance 会动
- # ~/.hermes/state.db;网关正在运行、句柄在 state.db 上时被换掉文件,
- # 网关会抛 StateDbReplacedError 并拒绝一切写入(=所有微信回复失败)。
- # 所以:hermes 可用 且 数据完好 → 什么都不做,只确保网关在跑。
- # 2. 真正要动东西(缺 hermes / 缺数据)时,先【安全停网关】再动手,做完重新启动。
- # 停网关优先用 gateway.pid 里的 pid(该文件是 JSON,不是裸数字),
- # 校验 /proc/<pid>/cmdline 命中网关进程模式(hermes-agent.*[g]ateway)才 kill;拿不到就枚举
- # pgrep 命中的进程(排除自身与父进程),绝不用 `pkill -f` 一把梭。
- # 3. 账号判断必须用 `compgen -G`:`[ -f dir/*.json ]` 在匹配到多个文件时
- # 报 "too many arguments" 恒为假,症状就是"重建后网关起不来"。
- #
- # 退出码:0=一切就绪;1=有步骤失败(日志里能看到是哪一步)。
- set -uo pipefail
- # 允许测试夹具覆盖(生产不设此变量,走 $HOME/workspace/setup)
- SETUP_DIR="${HERMES_SETUP_DIR:-$HOME/workspace/setup}"
- SAVED="$SETUP_DIR/hermes-install.sh"
- LATEST="$SETUP_DIR/hermes-install.latest.sh"
- BACKUP="$HOME/workspace/backups/hermes-home"
- INSTALL_URL="https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh"
- GWLOG="$HOME/.hermes/logs/weixin-gateway.log"
- export PATH="$HOME/.local/bin:$PATH"
- log() { echo "[restore-hermes] $*"; }
- rc=0
- # --- 读 gateway.pid(JSON 格式:{"pid": 12345, "kind": "hermes-gateway", ...}) ---
- gateway_pid() {
- local f="$HOME/.hermes/gateway.pid" p=""
- [ -f "$f" ] || return 0
- if command -v jq >/dev/null 2>&1; then
- p="$(jq -r '.pid // empty' "$f" 2>/dev/null || true)"
- fi
- if [ -z "$p" ]; then
- p="$(python3 -c 'import json,sys;print(json.load(open(sys.argv[1])).get("pid",""))' "$f" 2>/dev/null || true)"
- fi
- [ -n "$p" ] && printf '%s' "$p"
- return 0
- }
- # --- 停网关:只杀真的是网关的进程 ---
- stop_gateway() {
- local pid mypid ppid_ pids p waited ok
- mypid=$$
- ppid_="$PPID"
- pid="$(gateway_pid)"
- if [ -n "$pid" ] && [ -f "/proc/$pid/cmdline" ] \
- && tr '\0' ' ' < "/proc/$pid/cmdline" 2>/dev/null | grep -q "hermes-agent.*[g]ateway"; then
- log "按 gateway.pid 精确停网关 pid=$pid"
- kill -TERM "$pid" 2>/dev/null || true
- waited=0
- while [ "$waited" -lt 30 ]; do
- kill -0 "$pid" 2>/dev/null || break
- sleep 1; waited=$((waited + 1))
- done
- if kill -0 "$pid" 2>/dev/null; then
- log "WARN 网关 ${waited}s 未退出,SIGKILL pid=$pid"
- kill -KILL "$pid" 2>/dev/null || true
- sleep 2
- fi
- kill -0 "$pid" 2>/dev/null && { log "ERROR 网关仍在运行"; return 1; }
- log "网关已停止"
- return 0
- fi
- # pidfile 不可用:枚举命中进程(排除自身和父进程,避免误杀调用者)
- pids=""
- for p in $(pgrep -f "hermes-agent.*[g]ateway" 2>/dev/null || true); do
- [ "$p" = "$mypid" ] && continue
- [ "$p" = "$ppid_" ] && continue
- pids="$pids $p"
- done
- [ -n "$pids" ] || { log "网关未在运行,无需停"; return 0; }
- log "pidfile 不可用,按 pgrep 命中停止:$pids"
- # shellcheck disable=SC2086
- kill -TERM $pids 2>/dev/null || true
- waited=0; ok=0
- while [ "$waited" -lt 30 ]; do
- ok=1
- for p in $pids; do
- kill -0 "$p" 2>/dev/null && ok=0
- done
- [ "$ok" = 1 ] && break
- sleep 1; waited=$((waited + 1))
- done
- if [ "$ok" = 0 ]; then
- log "WARN 仍有网关进程未退出,SIGKILL 剩余进程"
- for p in $pids; do kill -0 "$p" 2>/dev/null && kill -KILL "$p" 2>/dev/null || true; done
- sleep 2
- fi
- for p in $pids; do
- kill -0 "$p" 2>/dev/null && { log "ERROR 网关进程 $p 仍在运行"; return 1; }
- done
- log "网关已停止"
- return 0
- }
- # --- 启动网关:没在跑才启动(避免双实例) ---
- start_gateway_if_needed() {
- if pgrep -f "hermes-agent.*[g]ateway" >/dev/null 2>&1; then
- log "微信网关已在运行,无需启动"
- return 0
- fi
- if compgen -G "$HOME/.hermes/weixin/accounts/*.json" > /dev/null 2>&1; then
- mkdir -p "$HOME/.hermes/logs"
- nohup hermes gateway run >> "$GWLOG" 2>&1 &
- sleep 3
- if pgrep -f "hermes-agent.*[g]ateway" >/dev/null 2>&1; then
- log "微信网关已启动"
- return 0
- fi
- log "ERROR 网关启动后仍无进程,看 $GWLOG"
- return 1
- fi
- log "无微信账号凭据,跳过网关启动"
- return 0
- }
- # --- 安装/升级 hermes(只在真的需要时调用) ---
- install_hermes() {
- local install_sh=""
- if curl -fsSL "$INSTALL_URL" -o "$LATEST" 2>/dev/null; then
- install_sh="$LATEST"
- cp "$LATEST" "$SAVED"
- log "使用最新官方安装脚本(已更新本地缓存 $SAVED)"
- elif [ -f "$SAVED" ]; then
- install_sh="$SAVED"
- log "WARN 无法下载最新安装脚本,使用本地缓存 $SAVED"
- else
- log "ERROR 安装脚本不可用(无网且无本地缓存),无法安装 hermes"
- return 1
- fi
- if bash "$install_sh" --non-interactive --skip-browser; then
- export PATH="$HOME/.local/bin:$PATH"
- hermes --version || log "WARN hermes --version 返回非 0"
- log "hermes 安装/升级完成"
- return 0
- fi
- log "ERROR 安装脚本执行失败"
- return 1
- }
- # --- 从备份恢复用户数据(只在数据缺失时调用;调用方必须已停网关) ---
- restore_user_data() {
- if [ ! -d "$BACKUP" ]; then
- log "ERROR ~/.hermes 数据缺失,且没有备份目录 $BACKUP"
- return 1
- fi
- if command -v rsync >/dev/null 2>&1; then
- rsync -a "$BACKUP/" "$HOME/.hermes/"
- else
- cp -a "$BACKUP/." "$HOME/.hermes/"
- fi
- chmod 600 "$HOME/.hermes/.env" 2>/dev/null || true
- log "用户数据已从备份恢复"
- return 0
- }
- # ============================ 主流程 ============================
- hermes_ok=0
- if command -v hermes >/dev/null 2>&1 && hermes --version >/dev/null 2>&1; then
- hermes_ok=1
- fi
- data_ok=0
- if [ -f "$HOME/.hermes/config.yaml" ] && [ -f "$HOME/.hermes/state.db" ]; then
- data_ok=1
- fi
- gw_running=0
- pgrep -f "hermes-agent.*[g]ateway" >/dev/null 2>&1 && gw_running=1
- log "检查:hermes_ok=$hermes_ok data_ok=$data_ok gateway_running=$gw_running"
- if [ "$hermes_ok" = 1 ] && [ "$data_ok" = 1 ]; then
- log "hermes 与用户数据都完好:跳过 installer 与数据恢复(不动 state.db)"
- else
- # 有活要干:先确认网关停干净
- if [ "$gw_running" = 1 ]; then
- stop_gateway || { log "ERROR 网关未能停干净,为避免 state.db 被换掉,本次中止"; exit 1; }
- fi
- if [ "$hermes_ok" = 0 ]; then
- install_hermes || rc=1
- fi
- if [ "$data_ok" = 0 ]; then
- restore_user_data || rc=1
- fi
- fi
- start_gateway_if_needed || rc=1
- if [ "$rc" = 0 ]; then
- echo "OK: hermes 已就绪"
- else
- echo "FAIL: hermes 恢复未完成,详见上面的 [restore-hermes] 日志" >&2
- fi
- exit "$rc"
- ```
- ### 代码 9/13:`backup-hermes.sh`(手动备份,fail closed)
- **目标路径**:`~/workspace/setup/backup-hermes.sh` **权限**:`chmod +x`
- **重要**:这是**手动**脚本,**不要**加进 cron——它每次都会读三个活库,和恢复流程抢 IO 没有意义。
- ```bash
- #!/usr/bin/env bash
- # backup-hermes.sh — 把 ~/.hermes 里不可再生的用户数据备份到 workspace。
- #
- # 备份内容:config.yaml、.env(含 API Key)、memories/、skills/、sessions/、hooks/ 等
- # 排除内容:hermes-agent/(git 仓库可重下)、tools/(可重装)、cache/、installs/、logs/
- #
- # 安全规则(2026-09-26 复核后收紧为 fail closed):
- # ~/.hermes 里有三个 WAL 模式的活跃数据库(state.db / kanban.db / shared-state.db)。
- # 网关运行时用 rsync/cp 直接复制 db+WAL+SHM 会得到跨时刻的撕裂快照——
- # 压测实测单轮最多静默丢 38000 行,而且 `PRAGMA integrity_check` 对撕裂备份
- # 照样返回 ok,也就是说"拷完跑个 integrity_check"根本验证不出这个 bug。
- # 所以:三个库一律 `sqlite3 .backup` 在线热备;
- # **任何一步失败就地停手(exit 1),绝不回退到裸 cp**——
- # 回退裸 cp 会把一份可能撕裂的库盖到上一份好备份上,等于用坏备份换掉好备份。
- # 失败时保留上一份好备份,并打印明确错误让人来处理。
- #
- # 实现要点(都是实测踩出来的):
- # - 热备产物写到 DST 之外的 stage 目录。不能放在 DST 里:rsync --delete 会把
- # 源目录里不存在的文件删掉,临时文件正好会被它顺手清理掉(实测 mv 时文件已消失)。
- # - 全部成功后才把三个库 mv 进 DST(同文件系统 rename,原子);失败整次作废,
- # 三个库都保持上一份好备份。
- # - .last-success 只在整次成功时写,并被 rsync 排除,用来回答"到底哪次成功过"。
- # 退出码:0=全部成功;1=至少一个库失败(旧备份保持不变)。
- set -euo pipefail
- SRC="$HOME/.hermes"
- DST="$HOME/workspace/backups/hermes-home"
- STAGE="$HOME/workspace/backups/.hermes-db-stage"
- SQLITE_DBS="state.db kanban.db shared-state.db"
- failed=0
- err() { echo "[error] $*" >&2; failed=1; }
- mkdir -p "$DST"
- rm -rf "$STAGE"
- mkdir -p "$STAGE"
- # --- 0. 前置检查:有活库就必须有 sqlite3;没有就 fail closed,不做任何降级复制 ---
- need_sqlite=0
- for db in $SQLITE_DBS; do
- [ -f "$SRC/$db" ] && need_sqlite=1
- done
- if [ "$need_sqlite" = 1 ] && ! command -v sqlite3 >/dev/null 2>&1; then
- err "本机没有 sqlite3,无法为 3 个 WAL 活库做一致备份。请先装(apt-get install -y sqlite3)后重跑;本次未改动备份目录。"
- exit 1
- fi
- # --- 1. 数据库:在线热备到 stage(完全不碰 DST 里的旧备份) ---
- declare -A TMP_DB=()
- for db in $SQLITE_DBS; do
- [ -f "$SRC/$db" ] || { echo "[info] $SRC/$db 不存在,跳过"; continue; }
- tmp="$STAGE/$db"
- rm -f "$tmp"
- if ! sqlite3 "$SRC/$db" ".backup '$tmp'" 2>/dev/null; then
- rm -f "$tmp"
- err "$db 在线热备失败(sqlite3 .backup 返回非 0)。旧备份已保留,未做任何覆盖。"
- continue
- fi
- # 备份产物自身的可读性检查(注意:这发现不了"撕裂",撕裂是靠 .backup 本身避免的)
- if ! sqlite3 "$tmp" "PRAGMA quick_check;" 2>/dev/null | grep -q '^ok$'; then
- rm -f "$tmp"
- err "$db 热备产物 quick_check 未返回 ok。旧备份已保留。"
- continue
- fi
- TMP_DB["$db"]="$tmp"
- echo "[info] $db 在线热备完成(stage)"
- done
- # --- 2. 其它文件(排除三个库及其 WAL/SHM,它们走上面的热备路径) ---
- if command -v rsync >/dev/null 2>&1; then
- rsync -a --delete \
- --exclude 'hermes-agent/' \
- --exclude 'tools/' \
- --exclude 'cache/' \
- --exclude 'installs/' \
- --exclude 'logs/' \
- --exclude '.last-success' \
- --exclude 'state.db' --exclude 'state.db-wal' --exclude 'state.db-shm' \
- --exclude 'kanban.db' --exclude 'kanban.db-wal' --exclude 'kanban.db-shm' \
- --exclude 'shared-state.db' --exclude 'shared-state.db-wal' --exclude 'shared-state.db-shm' \
- "$SRC/" "$DST/" || err "rsync 复制非数据库文件失败"
- else
- # 无 rsync 时的降级方案:tar 管道到临时目录再合并
- rm -rf "$DST.new"
- mkdir -p "$DST.new"
- tar --exclude='hermes-agent' --exclude='tools' --exclude='cache' \
- --exclude='installs' --exclude='logs' \
- --exclude='state.db' --exclude='state.db-wal' --exclude='state.db-shm' \
- --exclude='kanban.db' --exclude='kanban.db-wal' --exclude='kanban.db-shm' \
- --exclude='shared-state.db' --exclude='shared-state.db-wal' --exclude='shared-state.db-shm' \
- -cf - -C "$HOME" .hermes | tar -xf - -C "$DST.new" --strip-components=1 \
- || err "tar 复制非数据库文件失败"
- (cd "$DST.new" && tar -cf - .) | (cd "$DST" && tar -xf -) || err "合并非数据库文件失败"
- rm -rf "$DST.new"
- fi
- # --- 3. 只有全部成功才把热备产物顶上去,并清理残留 WAL/SHM ---
- if [ "$failed" = 0 ]; then
- for db in $SQLITE_DBS; do
- [ -n "${TMP_DB[$db]:-}" ] || continue
- mv -f "${TMP_DB[$db]}" "$DST/$db"
- rm -f "$DST/$db-wal" "$DST/$db-shm"
- echo "[info] $db 已就位(原子替换)"
- done
- rm -rf "$STAGE"
- date -Is > "$DST/.last-success"
- echo "backup -> $DST"
- du -sh "$DST"
- exit 0
- fi
- # 失败:整次作废,明确保留上一份好备份
- rm -rf "$STAGE"
- echo "[error] 备份未完成:上一份好备份仍原样保留在 $DST(上次成功时间见 $DST/.last-success)" >&2
- exit 1
- ```
- ## 十一、步骤 8:离线包缓存(deb + 探针二进制)
- **目标**:把 `cron`、`openssh-server` 依赖闭包和 cf-probe 二进制都缓存到 `$HOME`,重建后**不依赖网络**也能装回系统组件。
- > 只缓存安装脚本不够:`install.sh` 还要去 GitHub releases 拉二进制,断网时照样装不上。
- > `releases/latest/download/cf-probe-linux-amd64` 与安装器装出的 `/usr/local/bin/cf-probe` sha256 一致,自带 `install` 子命令,可直接当安装器。
- ### ① 🤖 AI 执行(命令)
- **A. deb 依赖闭包(完整、可复现;不要只 `apt-get download cron openssh-server`)**
- ```bash
- cd ~/workspace/setup/deb-cache
- # 1) 算依赖闭包:从 cron + openssh 出发递归展开,去掉 recommends/suggests/conflicts 等分支
- apt-get update -qq
- apt-cache depends --recurse --no-recommends --no-suggests --no-conflicts \
- --no-breaks --no-replaces --no-enhances \
- cron openssh-server openssh-client openssh-sftp-server 2>/dev/null \
- | grep '^[a-z0-9]' | sort -u > /tmp/closure.txt
- # 2) 只保留"当前镜像里真实安装着"的包:
- # 闭包里会出现 systemd-standalone-sysusers / opensysusers / cdebconf 这类【互斥替代品】,
- # 而 lib-pkgs.sh 是"把缓存里缺的包一次性 dpkg -i",互相冲突的包会直接装失败。
- while read -r p; do dpkg -l "$p" 2>/dev/null | grep -q '^ii' && echo "$p"; done \
- < /tmp/closure.txt > /tmp/closure.installed.txt
- grep -vxE 'systemd-standalone-sysusers|opensysusers|cdebconf|libdebian-installer4|libtextwrap1' \
- /tmp/closure.installed.txt > /tmp/closure.final.txt
- # 3) 下载(注意用 apt-get download:它对"已安装"的包也照样下,不用先卸载;
- # 用 install --download-only 会因为"已是最新"而一个都不下)
- cd ~/workspace/setup/deb-cache
- xargs -a /tmp/closure.final.txt apt-get download
- # 4) 验证:数量、关键包、可解析
- ls *.deb | wc -l # 期望 ≥ 70(参考实现 74 个,约 21MB)
- for p in cron cron-daemon-common openssh-server openssh-client openssh-sftp-server; do
- ls ${p}_*.deb >/dev/null 2>&1 && echo "OK $p" || echo "MISSING $p"
- done
- for d in *.deb; do dpkg-deb -f "$d" Package >/dev/null 2>&1 || echo "BAD $d"; done; echo "全部 .deb 可解析"
- du -sh . # 期望 ~21M
- ```
- **B. 探针二进制缓存**
- ```bash
- bash ~/workspace/setup/cache-cf-probe-bin.sh
- ls -l ~/workspace/setup/cf-probe-linux-amd64 ~/workspace/setup/cf-probe-linux-amd64.sha256
- ```
- **C.(建议)Hermes 安装脚本缓存**:`restore-hermes.sh` 会在下载失败时用 `~/workspace/setup/hermes-install.sh`。首次装完 Hermes 后,确认它存在:
- ```bash
- ls -l ~/workspace/setup/hermes-install.sh # 不存在就见步骤 9,restore-hermes.sh 会自动落一份
- ```
- ### ② 💬 对用户说(可原样发送)
- > 💾 现在把"重建后要用的安装包"提前缓存到本地。这样沙盒被重建、网络又不好的时候,系统组件也能装回来:
- >
- > - `cron` + `openssh` 及其依赖(约 21MB,70 多个 .deb)
- > - 探针二进制(约 7.5MB)
- >
- > 你什么都不用做,我看完数量继续。
- ### ③ 🙋 用户手动做
- 无。
- ### ④ ✅ 做完的标志
- ```bash
- ls ~/workspace/setup/deb-cache/*.deb | wc -l # ≥ 70
- ls ~/workspace/setup/cf-probe-linux-amd64 >/dev/null && echo "二进制缓存 OK"
- cat ~/workspace/setup/cf-probe-linux-amd64.sha256 # 有值即可(这是校验和,不是密钥)
- ```
- 判据:deb 数量 ≥ 70、关键包五个都在、二进制缓存存在且带 sha256。
- ### ⑤ 🛠️ 常见失败与处理
- | 现象 | 原因 | 处理 |
- | ------------------------------------------------ | -------------------------------------------------------- | ------------------------------------------------------------- |
- | `apt-get download` 报 `Unable to locate package` | apt 列表为空 / 源不可达 | 先 `apt-get update`;仍失败就换源或从能上网的机器拷 .deb 过来 |
- | 一个 .deb 都没下下来 | 用了 `install --download-only`(已安装的包不会重复下载) | 改用 `apt-get download`(本手册的写法) |
- | 数量只有 5、6 个 | 只下了显式列出的包,没算闭包 | 用第 1 步的 `apt-cache depends --recurse` 生成完整列表 |
- | 装的时候 `dpkg` 报冲突 | 缓存里混进了互斥替代品(systemd-standalone-sysusers 等) | 用第 2 步的过滤规则重建列表 |
- | 二进制缓存自检失败 | 下载到的是错误页面(代理/网关拦截) | 删掉重下;确认 `curl -I` 拿到的是 `application/octet-stream` |
- | deb-cache 占空间大 | 闭包包含已装的运行时库(libc6、systemd 等) | 正常,约 21MB;不要为了省空间删依赖 |
- ---
- # 模块 D|微信机器人(Hermes + 模型 API + 扫码,步骤 9–10)
- 装 Hermes、接上用户自己的模型接口,再用手机扫码把微信绑到网关,最后过一遍首次私聊的配对。**用户介入**:给模型 API 地址与 Key、微信扫码并确认、把机器人回的配对码转给 AI。
- ## 十二、步骤 9:安装 Hermes + 配置模型 API
- **目标**:Hermes 装好、能跑,接上用户自己的 OpenAI 兼容模型接口。
- ### ① 🤖 AI 执行(命令)
- ```bash
- # 1. 安装/恢复 Hermes(幂等;健康时会自动跳过 installer,见脚本注释)
- bash ~/workspace/setup/restore-hermes.sh
- # 2. 确认可用
- export PATH="$HOME/.local/bin:$PATH"
- hermes --version
- # 3. 写模型配置(真实地址只写进 config.yaml,不进任何文档)
- # 幂等:已存在 my-api provider 就不重复追加(重跑不会写出第二份 model:/providers: 块)
- if ! grep -q 'my-api' ~/.hermes/config.yaml 2>/dev/null; then
- cat >> ~/.hermes/config.yaml <<'YAML_EOF'
- model:
- default: "<MODEL_NAME>"
- provider: "my-api"
- providers:
- my-api:
- base_url: "<API_BASE_URL>"
- key_env: "MY_API_KEY"
- YAML_EOF
- echo "模型配置已写入"
- else
- echo "模型配置已存在,跳过(要改地址/模型请手动编辑 ~/.hermes/config.yaml)"
- fi
- # 4. Key 写进 .env(600),值从环境变量来,不进 shell 历史
- # USER_MODEL_KEY 由用户经安全页面提供(值只经环境变量传入)
- # 幂等:已存在 MY_API_KEY= 就不重复追加(否则下面的 grep -c 期望 1 会失败)
- if ! grep -q '^MY_API_KEY=' ~/.hermes/.env 2>/dev/null; then
- printf 'MY_API_KEY=%s\n' "$USER_MODEL_KEY" >> ~/.hermes/.env
- echo "MY_API_KEY 已写入"
- else
- echo "MY_API_KEY 已存在,跳过(要换 Key 请先删掉该行再重跑)"
- fi
- chmod 600 ~/.hermes/.env
- unset USER_MODEL_KEY
- # 5. 自检:模型配置读得到、Key 存在(只打印布尔值和长度,不打印值)
- grep -q 'my-api' ~/.hermes/config.yaml && echo "provider 配置已写入"
- grep -c '^MY_API_KEY=' ~/.hermes/.env # 期望 1
- awk -F= '/^MY_API_KEY=/{print "MY_API_KEY 长度: " length($2)}' ~/.hermes/.env
- ```
- **连通性自检**(推荐做,避免"装好了但一问就报错"):
- ```bash
- hermes --non-interactive "只回复两个字:在线" 2>&1 | tail -5
- ```
- ### ② 💬 对用户说(可原样发送)
- > 🧠 现在装 Hermes(微信机器人的大脑)并接你的模型 API。需要你提供两样:
- >
- > 1. **接口地址**:形如 `http://<主机>:<端口>/v1`(OpenAI 兼容);
- > 2. **API Key**:**走安全页面**发我,别贴在聊天里。
- > 3. **模型名**:你那个接口上要用的模型标识(比如 `deepseek-v4.1-flash` 这类)。
- >
- > - 我写到 `~/.hermes/.env`(600 权限,只有本机能读);
- ### ③ 🙋 用户手动做
- - 通过安全页面提供 API 地址与 Key;提供模型名。
- ### ④ ✅ 做完的标志
- ```bash
- export PATH="$HOME/.local/bin:$PATH"
- hermes --version # 期望打印版本号
- grep -q 'my-api' ~/.hermes/config.yaml && echo "配置 OK"
- ls -l ~/.hermes/.env # 期望 -rw-------(600)
- hermes --non-interactive "只回复两个字:在线" 2>&1 | tail -3 # 期望有正常回复,不是鉴权/连接错误
- ```
- 判据:版本号能打印 + 配置里有 provider + `.env` 权限 600 + 一次真实调用成功。
- ### ⑤ 🛠️ 常见失败与处理
- | 现象 | 原因 | 处理 |
- | ------------------------------ | ------------------------------- | ------------------------------------------------------------------------------------------- |
- | `hermes: command not found` | `~/.local/bin` 不在 PATH | `export PATH="$HOME/.local/bin:$PATH"`;网关用 `nohup hermes gateway run` 启动时会自带 PATH |
- | 调用报 401/403 | Key 错、过期或没写进 `.env` | `grep -c '^MY_API_KEY=' ~/.hermes/.env`;值不要带引号 |
- | 调用超时 | 地址端口不通 | 让用户确认地址可从沙盒访问(`curl -m 8 <API_BASE_URL>/models`);国内机房注意出网策略 |
- | installer 反复重装、把网关搞挂 | installer 无条件跑会动 state.db | 用本手册的 `restore-hermes.sh`:健康时跳过 installer,需要时才停网关 |
- | `.env` 权限变成 644 | 复制/编辑时改了权限 | `chmod 600 ~/.hermes/.env`(里面是所有密钥) |
- ## 十三、步骤 10:绑定微信(扫码登录)
- **目标**:微信账号绑定到 Hermes 网关,用户能在微信里跟机器人对话。
- > iLink 机器人登录:取二维码 → 用户扫码确认 → 凭据落 `~/.hermes/weixin/accounts/<account_id>.json`(网关读它)。**限制**:私聊可用,普通群消息可能收不到(非故障)。**首次私聊需配对**:机器人先回 8 位配对码而非内容,`hermes pairing approve weixin <配对码>` 批准后再发一次才有回复。
- ### ① 🤖 AI 执行(命令)
- ```bash
- # 0. 依赖:二维码渲染需要 qrcode(含 PIL)
- python3 -c 'import qrcode' 2>/dev/null || python3 -m pip install "qrcode[pil]"
- # 1. 落盘两个辅助脚本(代码见下)到 ~/workspace/setup/
- # weixin-qr-fetch.py / weixin-qr-confirm.py
- # 2. 取二维码(生成 PNG)
- python3 ~/workspace/setup/weixin-qr-fetch.py # 输出:QR saved: <...>/weixin-login-qr.png
- # 3. 把 PNG 发给用户扫:在会话里用 MEDIA: 标记;如果需要在回合外发,用
- hermes send --to weixin:<chat_id> "MEDIA:$HOME/workspace/your_files/weixin-login-qr.png"
- # 4. 立刻开始轮询确认(180 秒内有效)
- python3 ~/workspace/setup/weixin-qr-confirm.py; echo "rc=$?"
- # 5. 确认成功后,把网关需要的两项写进 .env(值取自账号 json,不要打印出来)
- python3 - <<'PY'
- import json, glob, os, re
- p = glob.glob(os.path.expanduser("~/.hermes/weixin/accounts/*@im.bot.json"))[0]
- d = json.load(open(p))
- acct = os.path.basename(p).replace(".json", "")
- env = os.path.expanduser("~/.hermes/.env")
- text = open(env).read() if os.path.exists(env) else ""
- add = []
- if "WEIXIN_ACCOUNT_ID=" not in text:
- add.append(f"WEIXIN_ACCOUNT_ID={acct}")
- if "WEIXIN_TOKEN=" not in text:
- add.append(f"WEIXIN_TOKEN={d['token']}")
- if add:
- with open(env, "a") as f:
- f.write("\n" + "\n".join(add) + "\n")
- print("已写入 .env 的项:", [a.split('=')[0] for a in add], "(值不打印)")
- PY
- chmod 600 ~/.hermes/.env
- # 6. 启动网关(后台常驻)
- mkdir -p ~/.hermes/logs
- nohup hermes gateway run >> ~/.hermes/logs/weixin-gateway.log 2>&1 &
- sleep 3; pgrep -f "hermes-agent.*[g]ateway" >/dev/null && echo "网关已启动"
- # 7. 批准配对(关键一步,别漏):让用户先在微信里给机器人发一条消息,
- # 机器人回一个 8 位配对码(形如 3TNTE7PR)而不是内容——这是 Hermes 的 DM 配对安全机制。
- # 拿到码后批准(把 <配对码> 换成用户发来的那串):
- export PATH="$HOME/.local/bin:$PATH"
- hermes pairing list # 看待批准/已批准的人
- hermes pairing approve weixin <配对码> # 批准后该用户永久可用
- # 批准是幂等的,再确认一次:已批准列表里有他,就算配对完成。
- hermes pairing list
- # 备注:weixin 适配器的 DM 策略由 WEIXIN_DM_POLICY 控制(open / allowlist / disabled / pairing)。
- # 默认行为就是「配对」;我们不改它,只走一次性的 approve(比 open 更安全,比 allowlist 省事)。
- # 若日后想彻底免配对(不建议,等同放开所有人),可设 WEIXIN_DM_POLICY=open 后重启网关。
- ```
- ### ② 💬 对用户说(可原样发送)
- > 💬 Hermes 装好了,现在绑定微信。我马上把**二维码**发给你,请:
- >
- > 1. 用**手机微信扫码**;2. 手机上点**确认登录**;3. 扫完跟我说一声。
- >
- > 两点说明:
- >
- > - 二维码有效期约 3 分钟,过期我重新生成一张;
- > - 绑好后**私聊**可用;**普通微信群消息可能收不到**(iLink 的限制,不是故障)。
- >
- > 绑定完成后,请你**在微信里先给机器人发一条消息**。注意:第一次它**不会回内容**,只会回一个**8 位配对码**(比如 `3TNTE7PR`)——这是它的安全机制,不是坏了。
- >
- > 请把这个**配对码发给我**,我批准一下;批准后再给它发一次消息,这次就有正常回复了。
- ### ③ 🙋 用户手动做
- - 扫码 + 手机确认登录。
- - 在微信里给机器人发一条消息,把收到的 **8 位配对码**发给 AI。
- - 等 AI 批准后,再发一次消息确认有回复。
- ### ④ ✅ 做完的标志
- ```bash
- compgen -G "$HOME/.hermes/weixin/accounts/*.json" >/dev/null && echo "账号已绑定"
- python3 -c "import glob,os;print([os.path.basename(p) for p in glob.glob(os.path.expanduser('~/.hermes/weixin/accounts/*.json'))])"
- pgrep -f "hermes-agent.*[g]ateway" >/dev/null && echo "网关运行中"
- grep -c '^WEIXIN_TOKEN=' ~/.hermes/.env # 期望 1(只数条数,不看值)
- hermes pairing list # 期望:用户已在「已批准」列表里
- ```
- 判据:账号 json 存在 + 网关进程在 + `.env` 里有 `WEIXIN_TOKEN` + **用户已在 pairing 已批准列表** + **用户确认收到机器人正常回复**(不是配对码)。
- ### ⑤ 🛠️ 常见失败与处理
- | 现象 | 原因 | 处理 |
- | ------------------------------------- | ------------------------------------------- | -------------------------------------------------------------------------------------------------- |
- | `ModuleNotFoundError: qrcode` | 没装依赖 | `python3 -m pip install "qrcode[pil]"` |
- | 二维码过期 | 用户扫得太慢 | 重跑 `weixin-qr-fetch.py` 生成新码(`confirm` 脚本会返回 2=expired) |
- | 扫码后无反应 | 网络问题 | 看 `~/.hermes/logs/weixin-gateway.log` 尾部;确认沙盒能访问 iLink 域名 |
- | 能收不能回 / 回复全失败 | `state.db` 被换过(`StateDbReplacedError`) | 停网关 → 让恢复脚本用本手册版本重跑 → 重新起网关(**不要在网关运行时覆盖 `~/.hermes/` 里的数据**) |
- | 机器人只回配对码、不回内容 | 首次私聊未配对(Hermes 默认配对) | 让用户把配对码发来,`hermes pairing approve weixin <配对码>`;批准后再发消息即可 |
- | `hermes pairing list` 为空 | 用户还没发过消息 / 网关没连上 | 让用户先给机器人发一条消息,等它回配对码;确认网关在跑 |
- | 群里收不到消息 | iLink 机器人限制 | 如实说明:私聊可用,群聊可能收不到,不是配置问题 |
- | `hermes send` 报 Weixin token missing | `.env` 里缺 `WEIXIN_TOKEN` | 按 ① 的第 5 步补写(网关自身读的是账号 json,所以机器人能收消息但 `hermes send` 会失败) |
- ### 代码 10/13:`weixin-qr-fetch.py`(取二维码)
- **目标路径**:`~/workspace/setup/weixin-qr-fetch.py`
- ```python
- #!/usr/bin/env python3
- """取微信(iLink)登录二维码并渲染成 PNG,供用户扫码。
- 用法:
- python3 weixin-qr-fetch.py
- 产物:
- $HOME/workspace/your_files/weixin-login-qr.png ← 把这个 PNG 发给用户扫
- $HOME/workspace/setup/weixin-qr-state.json ← 供 weixin-qr-confirm.py 续用
- 依赖:python3 + qrcode(含 PIL)
- 没有的话先装:python3 -m pip install "qrcode[pil]"
- 或:uv pip install --python "$(command -v python3)" "qrcode[pil]"
- """
- import json
- import os
- import subprocess
- import sys
- try:
- import qrcode
- except ImportError: # 给出可执行的提示,别只抛 ModuleNotFoundError
- print('缺少 qrcode 模块。请先执行: python3 -m pip install "qrcode[pil]"', file=sys.stderr)
- sys.exit(4)
- HOME = os.path.expanduser("~")
- BASE_URL = "https://ilinkai.weixin.qq.com"
- APP_ID = "bot"
- CLIENT_VERSION = str((2 << 16) | (2 << 8) | 0)
- STATE_PATH = os.path.join(HOME, "workspace", "setup", "weixin-qr-state.json")
- PNG_PATH = os.path.join(HOME, "workspace", "your_files", "weixin-login-qr.png")
- def api_get(endpoint: str) -> dict:
- out = subprocess.run(
- [
- "curl", "-s", "-m", "30",
- "-H", f"iLink-App-Id: {APP_ID}",
- "-H", f"iLink-App-ClientVersion: {CLIENT_VERSION}",
- f"{BASE_URL}/{endpoint}",
- ],
- capture_output=True, text=True, check=True,
- )
- return json.loads(out.stdout)
- def main() -> int:
- data = api_get("ilink/bot/get_bot_qrcode?bot_type=3")
- qrcode_value = str(data.get("qrcode") or "")
- qrcode_url = str(data.get("qrcode_img_content") or "")
- if not qrcode_value:
- print(f"QR response missing qrcode: {data}", file=sys.stderr)
- return 1
- scan_target = qrcode_url or qrcode_value
- os.makedirs(os.path.dirname(PNG_PATH), exist_ok=True)
- os.makedirs(os.path.dirname(STATE_PATH), exist_ok=True)
- qr = qrcode.QRCode(box_size=10, border=4)
- qr.add_data(scan_target)
- qr.make(fit=True)
- qr.make_image(fill_color="black", back_color="white").save(PNG_PATH)
- with open(STATE_PATH, "w") as f:
- json.dump({"qrcode": qrcode_value, "qrcode_url": qrcode_url}, f)
- os.chmod(STATE_PATH, 0o600)
- print(f"QR saved: {PNG_PATH}")
- print("下一步:把这个 PNG 发给用户扫,然后跑 weixin-qr-confirm.py 等确认(180 秒内)")
- return 0
- if __name__ == "__main__":
Lines 2,001–3,110 are not shown. The link to the file on GitHub has every line.
README.md · README · 32 lines
- # muse-guardian
- 给 Muse.ai 沙盒装上探针、Hermes、保活和重建脚本,以及 **MuseAutoApprove**(自动允许审批)的 SKILL。
- ## 使用
- ```
- 帮我安装 `https://raw.githubusercontent.com/bytehola/muse-guardian/refs/heads/main/SKILL.md`并开始执行。
- ```
- 如遇拦截,打开侧边栏点击新旁路会话发送。
- ---
- 安装后 Agent 会按手册步骤部署以下组件:
- | 组件 | 作用 |
- |---|---|
- | cf-probe 探针 | 向 CF 后台上报沙盒状态 |
- | Hermes | 操控沙盒里的 AI Agent |
- | 三层保活 | 看门狗 + 平台 hook 探针 + 开机钩子,重建后自动恢复 |
- | **MuseAutoApprove** | 自动允许批准沙盒的外联审批卡片,访问新域名不再等人点"允许" |
- ## 效果
- <img width="843" height="636" alt="66695ffdbcaa3b97b3f7138644d2aead" src="https://github.com/user-attachments/assets/193a0521-b6d7-47b3-8ee3-2715f337dd60" />
- # 友好社区
- [LinuxDo](https://linux.do/)
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.