yangxuan/openclaw-config
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
5328320396da5db3a76d1417680f423f94cbf414
openclaw-config/docs/openclaw-升级与维护.md
T

14 KiB
Raw Blame History

openclaw 升级与维护运维手册（bk02）

主机：bk02 / xuan-asus-nj（Debian 12 bookworm，192.168.3.14，tailscale 100.115.195.192） 组件：OpenClaw Gateway（用户级 systemd）+ tailscale serve（HTTPS 入口） 版本：OpenClaw 2026.8.1 → 2026.9.4；运行 Node /usr/bin/node 22.23.1 → nvm v26.8.2 更新：2026-09-16（本次为实测记录，含命令、证据与踩坑）

⚠️ 本文不写明文口令。凭据位置见 §7。

1. 架构总览

浏览器 / App
  ↓ https://bk02.baiji-algieba.ts.net   （tailscale serve，443 终止 TLS）
  ↓ 转发到本机回环
bk02: node 进程 127.0.0.1:18789  （openclaw gateway）
  ↓
存储：~/.openclaw/state/openclaw.sqlite（共享状态）
      ~/.openclaw/agents/<id>/agent/openclaw-agent.sqlite（每 agent 会话/记忆）
项 值
服务单元 openclaw-gateway.service（用户级 systemd，systemctl --user）
监听 127.0.0.1:18789（+ [::1]:18789），不直接对外
对外入口 gateway.tailscale.mode = serve → https://bk02.baiji-algieba.ts.net
启动命令 /home/yangxuan/.nvm/versions/node/v26.8.2/bin/node --max-old-space-size=3913 <openclaw>/dist/index.js gateway --port 18789
插件 8 个 enabled：dingtalk-connector、feishu、memory-core、ollama、openclaw-weixin、searxng 等
状态目录 ~/.openclaw（本次清理前 2.6G，清理后 1.5G）

2. 本次升级：2026.8.1 → 2026.9.4

2.1 阻塞点：Node 版本（先踩后解）

openclaw update 直接拒绝，原文：

Node 22.23.1 at /usr/bin/node is too old for openclaw@2026.9.4.
The requested package requires >=24.16.0 <25 || >=26.1.0

关键点：gateway 服务实际用的是系统 /usr/bin/node（22.23.1），而 nvm 里的 v25.9.0 也不被支持（要求排除整个 25.x）。

Node 版本 满足 2026.8.1 满足 2026.9.4
系统 /usr/bin/node（升级前在用） 22.23.1 ✅ ❌
nvm v25.9.0 ✅ ❌（25.x 被排除）
nvm v26.8.2（本次采用） — ✅

2.2 执行步骤（可复现）

# 1) 装 Node 26（用户级，不动系统 node —— 同机还有 VS Code Server 等依赖它）
export NVM_DIR=$HOME/.nvm; . $NVM_DIR/nvm.sh
nvm install 26                 # → v26.8.2
nvm alias default 26           # 让新 shell 与 gateway 版本一致

# 2) 全局安装新版本（必须放行 install scripts，否则原生模块不构建，见 §3.1）
nvm use 26
npm i -g openclaw@2026.9.4 \
  --allow-scripts=openclaw,@google/genai,koffi,tree-sitter-bash,protobufjs

# 3) 用官方命令重建服务定义，让 gateway 切到 Node 26
systemctl --user stop openclaw-gateway
openclaw daemon install        # 自动检测并替换不支持的 Node，见下

openclaw daemon install 会自己发现并修掉旧 Node，原文输出：

Node 22.23.1: node:sqlite truncates TEXT at embedded NUL (nodejs/node#61954); use 24.16+/26.1+
Replacing unsupported Gateway service Node 22.23.1 (/usr/bin/node) with ~/.nvm/versions/node/v26.8.2/bin/node
Previous unit backed up to: ~/.config/systemd/user/openclaw-gateway.service.bak

顺带修掉一个数据隐患：Node 22 的 node:sqlite 存在「TEXT 遇内嵌 NUL 被截断」的已知 bug（nodejs/node#61954）。 升级前每条含空字符的消息都可能被静默截断 —— 换到 Node 26 后不再发生（历史已截断的数据无法自动还原）。

# 4) 同步插件到同版本（doctor 会逐个点名）
openclaw plugins update feishu
openclaw plugins update @openclaw/searxng-plugin@2026.9.4
openclaw plugins update @openclaw/deepseek-provider@2026.9.4
openclaw gateway restart

2.3 验收证据（实测）

验证项 结果
版本 OpenClaw 2026.9.4 (3a9d69d)
运行 Node /proc/<pid>/exe → v26.8.2/bin/node
服务状态 active，NRestarts=0
启动日志 [gateway] ready、[tailscale] serve enabled: https://bk02.baiji-algieba.ts.net/
插件 6→8 个加载，feishu/searxng/deepseek 均 2026.9.4
远端首页 HTTP/2 200，ttfb ≈ 0.139s
前端资源 压缩后 348KB（原始 1387KB，Brotli），9 个资源并发 0.16–0.79s
WS 端点 200
数据完整性 12 个 agent 全在、36 个 SQLite 库、自动完成 v16/v17 状态迁移

3. 踩坑清单（复现时必读）

3.1 npm 11 会静默拦下 install scripts

首次 npm i -g openclaw@2026.9.4 虽然「成功」，但这些脚本没执行：

openclaw (postinstall: postinstall-bundled-plugins.mjs)
koffi (install: cnoke.cjs --prebuild)        ← 原生模块
tree-sitter-bash (install: node-gyp-build)   ← 原生模块
protobufjs / @google/genai

→ 必须带 --allow-scripts=... 重装，否则运行时才暴露缺模块。

3.2 服务里的 Node 路径是硬编码的

ExecStart 记录的是绝对路径与具体 Node 版本目录。手工改 systemd 容易漏（PATH 环境变量里也含版本号），优先用 openclaw daemon install 重建，它会连带更新 PATH、保留原有 Environment= 注入。

3.3 两个命令需要显式 --force

命令 不加 force 的表现
openclaw gateway stop 拒绝：「This stops the operator's running gateway service… re-run with --force」
openclaw plugins uninstall <id> 交互确认；非交互环境需 --force（没有 --non-interactive 这个参数）

4. 存储结论：只能用 SQLite（不能换 PG/MySQL）

官方文档 llms-full.txt 原文：

SQLite remains the supported runtime store. Preparation for PostgreSQL should improve the existing store owners and their tests before adding a driver or configuration option.

即 PG 支持连驱动和配置项都还没有，仅处于前瞻设计阶段。旁证：

检查 结果
官方文档 mysql / mariadb 命中 0 次 / 0 次
官方文档 postgres 命中 6 次，全在「Preparing for another database backend」一节
代码里 PostgreSQL/MySQL 字样来源 SQL 语法高亮方言（CodeMirror / kysely dialect）与报错文案，非存储后端
实际驱动 node:sqlite（Node 内置，无外部依赖）
存储位置 state/openclaw.sqlite + agents/<id>/agent/openclaw-agent.sqlite（共 36 个库）

但是：本机 docker 里的 pgsql / mysql 可以作为 agent 的工具数据源（配置里 "MySQL":{"enabled":true} + sql-toolkit），这与「openclaw 自身存储」是两层，互不影响。

结论：想提升存储层，升级 Node 比换数据库更实在（§2.2 的 NUL 截断 bug 就是典型）。

5. 清理历史版本配置 / 缓存 / 残留

5.1 官方清理入口

目标 命令 备注
迁移「回滚原始文件」 openclaw update cleanup --dry-run → 停机后 openclaw update cleanup 官方专用于清理 upgrade 残留
agent 库 VACUUM openclaw doctor --session-sqlite compact --session-sqlite-all-agents 需停机
共享状态库压缩 openclaw doctor --state-sqlite compact --json 需停机，会设置 auto_vacuum=INCREMENTAL
列表/删除历史会话 openclaw sessions
继承文件迁移 openclaw doctor --fix 会归档为 <源>.migrated.<sha256>.<id>
卸载插件（含目录） openclaw plugins uninstall <id> --force

停机维护的官方推荐顺序：

openclaw backup create --verify          # 先备份（必做）
openclaw gateway stop --force
openclaw doctor --session-sqlite compact --session-sqlite-all-agents
openclaw doctor --state-sqlite compact --json
openclaw gateway start

5.2 本次清理成效（实测）

项目 手段 释放
npm 缓存 npm cache clean --force 1.7 GB
旧版 Node 25（含 openclaw 2026.8.1） nvm uninstall 25.9.0 1.5 GB
memory-lancedb（disabled 插件） openclaw plugins uninstall memory-lancedb --force 950 MB
旧版本 UI 资源缓存 核对当前 build 引用后删旧 hash 目录 28 MB
SQLite 空闲页 上述两个 compact 2.9 MB
重复 skill 目录 全量比对后移出 20 KB
验证失败的备份包 删除 378 MB

根分区 26G/109G (26%) → 24G/109G (23%)；~/.openclaw 2.6G → 1.5G。

共享状态库 compact 实测输出（可作判据基线）：

{ "before": { "autoVacuum": 0, "dbSizeBytes": 15339520, "freelistPages": 435 },
  "after":  { "autoVacuum": 2, "dbSizeBytes": 12771328, "freelistPages": 0 },
  "reclaimedBytes": 2568192, "integrityCheck": "ok" }

5.3 不能动的东西（官方设计，删了会出问题）

路径 为什么保留
openclaw.json.bak + .bak.1~.bak.4 官方配置备份环：任何配置写入都会轮转（--fix 亦然）
openclaw.json.last-good 解析失败时的自动恢复源
openclaw.json.pre-update 升级前备份
agents/*/agent/*.sqlite 当前会话/记忆数据
~/.openclaw/.git 配置备份仓库（见 §6）

5.4 边界：update cleanup 拒绝清理的那 525MB

agents/*/session-sqlite-import-archive/ 下有 654 个 *.imported-*（约 525MB），是 2026-08-31 会话从 JSONL 迁入 SQLite 时的归档。官方 cleanup 拒绝清理：

Candidates: 0 bytes; verification required: 550782825; protected: 0; blocked: 0
原因: historical-manifest-without-import-proof
  • doctor --session-sqlite validate / dry-run 均返回 0 target(s)：没有待导入的遗留源
  • compact 报告 archived-unreferenced-jsonl=0：openclaw 认为这些归档仍被清单引用
  • 独立验证：session_transcript_archives 表用 archive_blob BLOB 把内容存在库内，全表不引用外部文件路径 ⇒ 这些 JSONL 确如文档所述「not runtime fallbacks」（非运行时依赖），删除不影响运行，但会永久失去降级回旧 JSONL 版本的能力

结论：暂不清理（保留 525MB 换历史恢复能力）。若将来确认不需要降级，可手动删除该目录 —— 但官方不背书，删前务必备份迁移凭证 session-sqlite-migration-runs/。

6. 备份、配置仓库与回滚

6.1 备份

openclaw backup create --verify --output ~/openclaw-backups

⚠️ 若 workspace 下存在仅大小写不同的重复目录（本次为 skills/Obsidian 与 skills/obsidian），--verify 会因 portable path collision 失败。处理方式：

diff -r skills/obsidian skills/Obsidian      # 确认内容一致（本次仅 .clawhub/origin.json 的安装元数据不同）
mv skills/Obsidian ~/openclaw-backups/removed-skills/   # 移出而非删除

6.2 配置仓库（Gitea）

项 值
仓库 ~/.openclaw（工作区内的 git 仓库，分支 314）
remote https://gitea.climbcube.cn/yangxuan/openclaw-config.git
自动提交 auto-commit-config.sh，每 6 小时 git add -A + commit + push，无变更则跳过
提交信息 auto: sync OpenClaw config <时间> / auto: agent DB backup <日期>

体积治理（本次）：.git 曾达 199M / 249 次提交。根因不是 SQLite（.gitignore 已忽略 *.sqlite），而是 workspace 里的大数据文件被自动提交并推送：

90.2 MB  workspace-juaner/data/私聊_王芳.json
36.9 MB  workspace-juaner/data/私聊_王芳.jsonl
11.7 MB  agents/*/session-sqlite-import-archive/*.imported-*

⚠️ 隐私提示：.gitignore 原未忽略 workspace-*/data/，导致私聊内容进入 git 历史并推送到 Gitea。

已加固 ~/.openclaw/.gitignore：

workspace-*/data/
agents/*/session-sqlite-import-archive/

并 git rm -r --cached（保留本地文件）使既有大文件脱离跟踪，后续提交不再增长。历史重写（filter-repo）未做，如需彻底清除需另行评估（会与 remote 冲突，需 force push）。

6.3 回滚

# 服务定义
cp ~/.config/systemd/user/openclaw-gateway.service.bak ~/.config/systemd/user/openclaw-gateway.service
nvm install 25.9.0 && nvm exec 25.9.0 npm i -g openclaw@2026.8.1
systemctl --user daemon-reload && systemctl --user restart openclaw-gateway

注意：本次已删除 nvm v25.9.0（1.5G）与 memory-lancedb，回滚需重新下载；~/openclaw-backups/ 内的验证备份（351MB，不含 workspace）仍可恢复数据。

7. 凭据与密钥位置（不含明文）

用途 位置
gateway 认证 ~/.openclaw/openclaw.json → gateway.auth（password 模式）
机主登录 由机主掌握；本机 ~ 用户 yangxuan
模型 / 渠道密钥 ~/.openclaw/.env 与 openclaw.json 的 secrets 段（systemd 以 OPENCLAW_SERVICE_MANAGED_ENV_KEYS 注入）
备份包 ~/openclaw-backups/*.tar.gz（含凭据，勿外发）

8. 遗留观察点

  1. .git 仍为 199M —— 索引清理只阻止未来增长，历史未重写。
  2. 525MB 迁移归档保留（§5.4），如需释放需人工决策。
  3. skill 重名冲突 5 条（weather/obsidian/blogwatcher/mcporter/baidu-text-translate）：workspace 覆盖 bundled，属设计内优先级行为，非错误，可不管。
  4. gateway 重启频率：升级前曾出现单日 5 次重启（2026-09-15），重启后 20 秒内 RPC 会达 1.5–4.4s（冷启动），稳态 0 次慢调用。若再遇「打开很慢」，先查是否落在重启窗口。
  5. 链路：wit01 ↔ bk02 走 DERP 中继（MappingVariesByDestIP: true，对称 NAT），实测首屏 0.16–0.79s，服务端本身 < 10ms。
Reference in New Issue View Git Blame Copy Permalink