pi WebDAV 备份扩展

把 pi 的插件、扩展、模型配置自动备份到任意 WebDAV 服务（坚果云 / Nextcloud / 群晖 / 自建 rclone）。

零第三方依赖，只用 Node 内置模块。密钥默认不明文落盘（DPAPI / 环境变量 / 命令）。

安装

一行命令（pi 官方包机制）：

pi install git:github.com/ddldxiacan/pi-webdav-backup@v1        # 永远装最新的 1.x 正式版

@v1 是移动主版本 tag，始终指向最新的 1.x 正式版。以后升级不用改命令：

pi update --extensions     # 自动升到最新的 v1.x（然后 /reload）

只想试一下、不安装（仅本次运行生效）：

pi -e git:github.com/ddldxiacan/pi-webdav-backup

其他方式 / 更细的版本控制：

pi install git:github.com/ddldxiacan/pi-webdav-backup@v1.1.0   # 钉死某个版本（不自动升级）
pi install git:github.com/ddldxiacan/pi-webdav-backup          # 不钉 ref，直接跟 main 分支
pi install npm:pi-webdav-backup                                # 已发布到 npm 时
pi install /path/to/pi-webdav-backup                           # 本地目录（下载 ZIP 解压后）

@<ref> 可以是移动 tag（@v1）、具体版本 tag（@v1.1.0）、分支或 commit SHA：

• @v1 → pi update --extensions 会跟到最新的 1.x，推荐
• @v1.1.0 / commit SHA → 钉死不动；升级需重新 pi install ...@<新版本>
• ref 必须真实存在，写错（如不存在的 tag）会 clone/checkout 失败

手动安装：把 extensions/webdav-backup.ts 与 extensions/webdav-backup/ 拷到 ~/.pi/agent/extensions/。

装好后在 pi 里运行 /reload 加载。

本包带 pi-package 关键字，会出现在 pi.dev 包画廊。

运行时产生的文件：

~/.pi/agent/webdav-backup.json        ← 备份配置（/backup-setup 生成）
~/.pi/agent/secrets.dpapi.json        ← DPAPI 加密的密钥（自动创建，0600）

快速开始

/backup-setup       # 向导：填地址、账号、密码（默认 DPAPI 加密保存），自动测连接
/backup             # 立即备份
/backup verify      # 体检：密钥来源 / 明文告警 / 连接性
/backup check       # 单独测连接
/backup list        # 看远端已有备份
/backup restore     # 选一个备份恢复到临时目录

配置写入 ~/.pi/agent/webdav-backup.json。

命令一览

命令行也可直接用：

node ~/.pi/agent/extensions/webdav-backup/cli.mjs backup --json
node ~/.pi/agent/extensions/webdav-backup/cli.mjs doctor --json
node ~/.pi/agent/extensions/webdav-backup/cli.mjs migrate --method dpapi
node ~/.pi/agent/extensions/webdav-backup/cli.mjs restore --list
node ~/.pi/agent/extensions/webdav-backup/cli.mjs restore --file pi-agent-20260924-120000.tar.gz --to D:\restore
node ~/.pi/agent/extensions/webdav-backup/cli.mjs plugins --json [--dir D:\pi-restore]
node ~/.pi/agent/extensions/webdav-backup/cli.mjs repair-plugins --dry-run [--dir D:\pi-restore]
node ~/.pi/agent/extensions/webdav-backup/cli.mjs apply-extras --dir D:\pi-restore [--dry-run] [--force]
node ~/.pi/agent/extensions/webdav-backup/cli.mjs restore-apply --dir D:\pi-restore [--dry-run] [--force]
node ~/.pi/agent/extensions/webdav-backup/cli.mjs detect-legacy --json

输出末行固定是 JSON 汇总（--json 时只输出该行，人类模式则前面还有日志行），脚本可直接解析；退出码 0 成功 / 1 失败。

密钥不明文落盘

remote.password 与 encryptKey 不直接写明文，而是写引用：

该语法与 pi 自身的 resolve-config-value 约定一致，auth.json 的 key 字段也支持 $ENV_VAR 与 !命令。

⚠️ 要跨 Windows / Linux / macOS 多机同步，用 file: 或 $ENV，不要用 dpapi:——同 DPAPI 密文只能在本机本用户解密。 详见下文「跨平台密钥（多机同步）」。

推荐做法

{
  "remote": {
    "url": "https://dav.jianguoyun.com/dav/",
    "username": "you@example.com",
    "password": "dpapi:webdav-password"      // 不是明文
  },
  "encrypt": true,
  "encryptKey": "dpapi:backup-key"           // 不是明文
}

密钥本身这样存：

/backup keys set webdav-password      # 提示输入，DPAPI 加密入库
/backup keys set backup-key
/backup keys list                     # 只看名称与时间，不显示明文

已有明文配置？一条命令迁走（自动备份原文件）：

/backup keys migrate

非 Windows 或偏好环境变量：

node cli.mjs migrate --method env    # 写入用户环境变量（setx）
node cli.mjs migrate --method file   # 写入 0600 权限的 secrets/ 目录

体检

/backup verify

输出密钥来源、是否明文、DPAPI 是否可用、连接是否通过。有明文会直接标 ⚠️。

DPAPI 的边界：防御的是「配置文件/备份被拷走或误传到云端」。不防御已经能以你的身份运行代码的本机恶意程序。若需更强隔离，用 !命令 对接外部密码管理器。

环境变量方式也支持

不想改配置文件时，仍可用环境变量（优先级低于配置里的值）：

setx PI_WEBDAV_BACKUP_PASSWORD "你的应用密码"
setx PI_WEBDAV_BACKUP_KEY "你的加密口令"

跨平台密钥（多机同步）

dpapi: 只能在 Windows 本机本用户解密，同一份配置在 Linux 上会解析失败。要在 Windows/Linux/macOS 多机共用一套配置，改用 file:（推荐，无需改 shell）或 $ENV。

方案：file: 相对引用（配置里写相对 agentDir 的路径，各平台写法一致）

{
  "remote": { "password": "file:secrets/webdav-password.txt" },
  "encrypt": true,
  "encryptKey": "file:secrets/backup-key.txt"
}

每台机器各创建一次密钥文件（内容相同）：

mkdir -p ~/.pi/agent/secrets
printf '%s' '你的加密口令'   > ~/.pi/agent/secrets/backup-key.txt
printf '%s' '你的应用密码'   > ~/.pi/agent/secrets/webdav-password.txt
chmod 600 ~/.pi/agent/secrets/*.txt      # Windows 可忽略

secrets/** 默认被排除，密钥不会随备份上传。所以新机器必须手动做一次这步（这是唯一的手动环节）。 读取时会自动去掉行尾换行，echo/printf 都可以。

方案：$ENV

配置里写 "encryptKey": "$PI_WEBDAV_BACKUP_KEY"，然后各机器设同名环境变量（值相同）：

# Linux / macOS：~/.bashrc 或 ~/.zshrc
export PI_WEBDAV_BACKUP_KEY="你的加密口令"

# Windows PowerShell（需新开终端生效）
setx PI_WEBDAV_BACKUP_KEY "你的加密口令"

从现有 dpapi: 迁移：node cli.mjs migrate --method file（写入 secrets/）或 --method env（写入用户环境变量）。

备份什么

默认备份 ~/.pi/agent/ 下除以下内容外的所有文件：

包含：extensions/（你写的扩展）、models.json、models-store.json、settings.json、trust.json、auth.json、npm/package.json 等。

想换机一键还原？ 打开 includePlugins: true，把插件实现代码（node_modules）也备份进去， 新电脑恢复后插件即可直接用，无需联网重装。详见下文「换机一键还原」。

插件数据写在 ~/.pi/agent 之外怎么办（extraScope）

有些插件把配置/数据写在 agent 目录之外，默认 scope: ["."] 够不到：

用 extraScope 把这些**绝对路径（或 ~/...）**一并备份；归档内统一放在 extra/ 前缀下：

{
  "extraScope": [
    "~/.pi/settings.json",
    "~/.pi/web-search.json",
    "~/.config/rpiv-todo"
  ]
}

• 备份时：extra/ 内的 JSON/配置会按字段名（key/token/password/apiKey…）脱敏
• 恢复时：默认只解到恢复目录；/backup restore 会询问是否归位到真实路径，也可手动 node cli.mjs apply-extras --dir <恢复目录>
• 跨机可移植：备份时会把每个文件的归属记成“锚点 + 尾巴”（home / config(XDG) / appdata）， 恢复时按当前机器的锚点重算目标。换用户名、换盘符、Linux↔Windows 都能正确归位：
  • 旧机 /home/alice/.pi/settings.json → 新机 /home/bob/.pi/settings.json
  • 旧机 C:/Users/alice/.pi/settings.json → 新机 D:/Users/carol/.pi/settings.json
  • 不在任何锚点下的绝对路径（如 /etc/foo）保持原样，并在结果里标为 unmapped 以便你核对
• 安全：若本地已存在“真实值”、而归档里是 __REDACTED__，归位会跳过该文件（除非加 --force）， 以免把真密钥覆盖成占位符；覆盖前会把原文件存为 <name>.bak-extras-<时间戳>
• 探测遗留配置：/backup-setup 会自动检测并询问是否纳入；也可 node cli.mjs detect-legacy

归档里的 extra-manifest.json 记录了源机器的 platform/hostname/home 与各锚点， 归位时会打印出来，便于确认“这次恢复来自哪台机器”。

插件（install 装的包）会怎样

插件是否连同**实现代码（node_modules）**一起备份，由 includePlugins 决定：

开启 includePlugins: true 时，会保留 npm/node_modules/**、git/**/node_modules/**，仅排除其中运行时用不到、 体积大的内部数据（**/.git/**、node_modules/.cache、.vite、.turbo、.bin）。

取舍：true 能实现真正的一键还原，代价是体积变大（有原生依赖时可能几百 MB，且同一份备份在 不同平台间可能带入不兼容的二进制）。false 体积小，但恢复后必须联网补装。

无论哪种模式，/backup restore 都不再强制联网：开启 includePlugins 后，恢复流程会检测到 备份里已含插件代码并跳过补装提示。

敏感文件脱敏（重要）

备份时（加密与否都会），auth.json、webdav-backup.json 以及 extraScope 下的 JSON/配置会先脱敏再上传：

• 按字段名匹配：key / token / secret / password / credential / cookie / apiKey / private …
• 未加密时还额外按值的形状匹配：sk-…、ghp_…、AIza…、JWT、32 位以上随机串
• 命中替换为 __REDACTED__，结构保留；密钥引用（$ENV / dpapi: / file:）不会被抹
• 解析失败时整文件替换为占位符，绝不原样上传

因为加密备份同样会脱敏，用明文写的 API key / 密码无法从备份恢复（会变成 __REDACTED__）。 建议一律用 $ENV / dpapi: 引用（引用会被保留，恢复后仍可用）。 脱敏是「尽力而为」的防泄漏措施，真正的安全做法是开启 encrypt。

配置项

{
  "enabled": true,

  "remote": {
    "url": "https://dav.jianguoyun.com/dav/",   // 见下方各服务填法
    "username": "you@example.com",
    "password": "dpapi:webdav-password",        // 密钥引用，见上文；留空则读 $PI_WEBDAV_BACKUP_PASSWORD
    "remoteDir": "pi-backup",                    // 远端目录
    "remoteName": "pi-agent"                     // 文件名前缀
  },

  "scope": ["."],                  // 相对 ~/.pi/agent 的路径，可写 ["extensions", "models.json"]
  "exclude": [],                   // 额外 glob 排除规则
  "extraScope": [],                // agentDir 之外的额外备份路径（绝对路径或 ~/...），见上文「插件数据」
  "includePlugins": false,         // 是否把插件实现（node_modules）一起备份（换机一键还原的关键），见上文
  "includeSessions": false,        // 是否备份会话历史
  "snapshot": false,               // 见下文「两种模式」

  "encrypt": false,                // AES-256-GCM 加密
  "encryptKey": "dpapi:backup-key",  // 密钥引用（≥16 位）：dpapi:名称 / $ENV_VAR / file:路径；见上文「密钥」

  "backupOnExit": true,            // 退出 pi 时自动备份
  "backupOnExitMinIntervalMinutes": 30,   // 两次自动备份最小间隔
  "backupOnExitTimeoutMs": 600000,        // 自动备份等待上限

  "keepVersions": 10,              // 保留最近 N 个归档（0 = 不清理）
  "timeoutMs": 60000,
  "insecureTls": false             // 自签名证书时才设 true
}

各服务 URL 填法

⚠️ 密码建议用引用而非明文（多机同步请用 file: / $ENV，不要用 dpapi:）：

/backup keys set webdav-password          # Windows DPAPI
# 跨平台："password": "file:secrets/webdav-password.txt"

也可用环境变量：setx PI_WEBDAV_BACKUP_PASSWORD "你的应用密码"

两种备份模式

归档模式（默认，snapshot: false）

每次打包成一个 pi-agent-<时间戳>.tar.gz（可选 .pibak 加密）上传。

• ✅ 单个文件，下载/归档方便
• ✅ 天然有版本历史
• ⚠️ 每次全量上传

快照模式（snapshot: true）

逐文件上传到 pi-backup/pi-agent/，用远端 manifest.json 做增量比对。

• ✅ 只传变化的文件，第二次起非常快
• ✅ 能单独恢复某一个文件
• ⚠️ 只保留最新状态，无历史版本

建议：日常用快照模式（省流量），配合每周一次归档（可另配一个 remoteName）。

退出自动备份怎么工作

session_shutdown（reason: quit）触发时：

1. 检查 enabled / backupOnExit
2. 距上次自动备份不足 backupOnExitMinIntervalMinutes → 跳过（避免反复开关 pi 重复上传）
3. 否则 spawn 一个分离子进程执行上传，立刻返回

用分离进程的原因：pi 退出时若被 SIGTERM/关窗打断，留在主进程的上传会被中断；分离进程不受影响，且不会卡住退出。

日志写在 ~/.pi/agent/webdav-backup.log。

每日定时备份

# 在 pi 里：/backup-cron 03:00     或命令行：
node "$env:USERPROFILE\.pi\agent\extensions\webdav-backup\cli.mjs" install-cron --time 03:00

需要管理员权限（创建计划任务）。移除：/backup-cron remove。

恢复

/backup restore          # 选择备份 → 恢复 → 询问是否写回当前 pi

恢复分两步：先解到临时目录（不会直接动你的现有配置），再由你确认后才写回 ~/.pi/agent。 写回前每个被覆盖的旧文件都会另存为 <名字>.bak-apply-<时间戳>。

换机一键还原（推荐）：新电脑装好 pi → /backup-setup 配好同一 WebDAV → /backup restore -y：

/backup restore
  ├─ 选备份（`-y` 直接取最新）→ 解压到临时目录
  ├─ 本机已装插件时选【合并 / 替换】（见下）
  ├─ 询问是否【写回当前 pi】（restore-apply）
  │    ├─ 是：把配置/扩展/插件实现写回 ~/.pi/agent（覆盖前自动备份）
  │    └─ 否：只留在临时目录，你自己拷
  ├─ 如含 extra/ 额外数据（~/.pi/settings.json 等）→ 询问是否归位
  └─ 若备份已含插件代码 → 完成；否则体检并询问联网补装
/reload                  # 重启 pi 后插件即可用

前置条件：备份时开启了 includePlugins: true，插件实现才会在备份里；否则写回后仍需联网补装。

本机已经装了插件时，写回（合并 vs 替换）

新电脑往往已经装过一些插件——可能和备份里同名但版本不同，也可能多装了备份里没有的。 直接覆盖会把同名插件降级、把本机多装的声明抹掉、留下版本混合的“缝合”目录。所以写回有两种模式：

为何要合并 npm/package.json：pi 启动时会拿它与 node_modules 做协调（npm install）。 若直接覆盖成备份版，本机独有的插件会被 npm 当成多余包【卸载】。所以合并模式会保留本机已有依赖。

• 交互式 /backup restore：本机有插件声明时会先让你选（默认合并）
• 命令行：--mode merge（默认）/ --mode replace

“合并”对已安装的插件只保声明与代码、不升级也不降级；备份里本机没有的插件则连代码一起补入。 想完全回到旧机器状态（含同名降级）用“替换”。两种模式都不会删除本机多装的插件代码， 只会（在替换时）从其 settings.json 声明里移除。

手动写回某个已恢复目录（不重新下载）：

/backup restore-apply <目录>
# 或命令行：
node cli.mjs restore-apply --dir D:\pi-restore [--dry-run] [--force] [--mode merge|replace]

写回的安全规则：

• 只写回 agent 目录内的内容；extra/（agentDir 之外）由 apply-extras 单独处理
• 自动跳过备份/恢复产生的元数据（manifest、state、log）
• 目标已存在且内容不同时，先备份旧文件再覆盖（.bak-apply-*）
• 归档里是 __REDACTED__ 而本地有真实值时跳过（除非 --force），避免把真密钥抹掉
• 合并模式下，本机已装插件的目录整体保留，不写入备份里的同名文件（避免版本混合）

若只想解到指定目录、不写回：

node cli.mjs restore --file pi-agent-20260924-120000.tar.gz --to D:\pi-restore

恢复后把插件装回来（仅瘦备份需要）

如果备份时没有开启 includePlugins，插件实现代码 node_modules 不在备份里，需要联网补装。 恢复后跑（--dir 指向刚恢复出来的目录，不加则看当前 ~/.pi/agent）：

/backup plugins          # 看哪些插件没装好
/backup repair-plugins   # 补装

node cli.mjs plugins --json --dir D:\pi-restore        # 命令行同理
node cli.mjs repair-plugins --dir D:\pi-restore

会做的事（安装命令与 pi 自身的安装逻辑保持一致）：

--dry-run 只列将执行的命令，不落盘；单个包失败不影响其余，结果里会分开报 repaired / failed。

来源解析与 pi 的 parseGitUrl 完全对齐：支持 git: 简写、https://… URL、git@host:path scp 形式， ref 可含 /（如 feature/x），.git 后缀自动去掉（否则会装到 pi 找不到的目录）。

/backup restore 在未写回时会自动体检刚恢复出来的目录并询问是否立即补装（体检的是临时目录， 而不是当前 ~/.pi/agent，因为声明还在临时目录里）；若已写回当前目录，则看点目录。 /backup restore -y 只略过「恢复哪个」的询问，写回与补装仍会各自询问一次。

加密备份的恢复

需要 encryptKey 一致（配置文件或 $PI_WEBDAV_BACKUP_KEY）。密钥不对会明确报错，不会写出损坏文件。

解包过程会拒绝绝对路径与 .. 穿越，防止恶意归档写出到目标目录之外。

多机同步（Windows ↔ Linux）

⚠️ 先认清本质：这是"备份/恢复"，不是实时双向同步。

两台机器各自 /backup 会互相覆盖，建议以一台为主机，其他机器只做 /backup restore。

一、旧机（主机）：先备份

/backup dry        # 确认扫描结果（开了 includePlugins 会含几百 MB 插件代码）
/backup            # 正式备份

二、新机：安装 + 恢复

# 1. 装插件（GitHub / npm 二选一）
pi install git:github.com/ddldxiacan/pi-webdav-backup@v1
# 然后重启 pi

# 2. 创建密钥文件（内容与旧机一致；secrets/ 不入备份，故需手动一次）
mkdir -p ~/.pi/agent/secrets
printf '%s' '你的加密口令' > ~/.pi/agent/secrets/backup-key.txt
printf '%s' '你的应用密码' > ~/.pi/agent/secrets/webdav-password.txt
chmod 600 ~/.pi/agent/secrets/*.txt

# 3. 写配置 ~/.pi/agent/webdav-backup.json（与旧机相同，密钥用 file:）

配置文件模板（Windows/Linux 通用）：

{
  "enabled": true,
  "remote": {
    "url": "https://你的.webdav/dav",
    "username": "you@example.com",
    "password": "file:secrets/webdav-password.txt",
    "remoteDir": "pi-backup",
    "remoteName": "pi"
  },
  "scope": ["."],
  "includePlugins": true,
  "extraScope": ["~/.pi/settings.json"],
  "encrypt": true,
  "encryptKey": "file:secrets/backup-key.txt",
  "includeSessions": false
}

# 4. 测连接 + 恢复
/backup check
/backup restore -y     # 选备份 → 解密解压 → 选合并/替换 → 写回 → 归位 extra → 完成
/reload

三、关键约束

四、常见坑

测试

cd pi-webdav-backup
npm test
# 等价于：node extensions/webdav-backup/run-tests.mjs

扩展契约校验（模拟 pi 加载器导入入口文件）：

node extensions/webdav-backup/verify-load.mjs

11 个测试文件、450+ 项断言，用内置的内存 WebDAV 服务端做真实 HTTP 往返：

版本历史

发新版时：打新 tag（如 v1.1.1）后把移动 tag v1 一并指过去，让 pi install …@v1 始终装最新： git tag -f v1 v1.1.1 && git push -f origin v1

故障排查