Magpie 跨设备同步设计
本文用于把一套 Magpie 设计同步到多台电脑,或排查已启用的 WebDAV、S3、GitHub 同步。目标是同步逻辑配置,不是复制一台电脑的完整数据目录。
先运行 magpie --version,并读取当前安装版的 magpie webdav help、magpie s3 help、magpie github help 与 magpie backup --help。命令字段、默认值、文件预算和恢复语义随版本变化;本文只给决策框架,不替代安装版帮助。
1. 先划数据域,不整目录复制
| 数据域 | 内容 | 跨设备建议 | 风险边界 |
|---|---|---|---|
| Providers / models | 供应商、模型目录、API key | 常规同步;key 只在密封同步或备份中携带 | API key 是可消费凭据,必须确认存储端与 passphrase 策略 |
| Settings / profiles / agents | 网关设置、模型 profile、各 Agent 指向 | 常规同步 | 地址、代理、自启和本机路径可能需要按设备覆盖 |
| Library | 指令、MCP、Skills、subagents | 常规同步,但要控制体积 | Skill 目录中的运行缓存、归档和本机 registry 可能被同步;.gitignore 不是 Magpie Library 的过滤合同 |
| Memory | Magpie Memory | 按隐私边界显式选择 | 可能携带长期工作偏好或业务线索 |
| Usage | 用量账与请求统计 | 可选同步,便于汇总观察 | 体积较大,可能含项目、会话和模型使用画像 |
| Sign-ins | 订阅与插件登录态 | 默认不同步 | 任何拿到密封文件与 passphrase 的人可能使用账号;同一账号在多设备续期可能互相踢下线 |
不要用通用文件同步工具直接同步 Magpie 的 config/cache 目录。这些目录通常混有锁文件、运行索引、本机身份、缓存、用量流水、凭据和登录态;两台活跃机器同时写入容易产生冲突或把一台机器的运行状态覆盖到另一台。
2. 选择承载方式
| 方式 | 适合场景 | 前置检查 |
|---|---|---|
| 内置 WebDAV | 已有可信私有 WebDAV 服务或 NAS | 所有设备可达、传输可信、路径可写、服务端认证独立于同步 passphrase |
| 内置 S3 | 已有私有对象存储、NAS 的 S3 兼容服务或云 bucket | endpoint、路径风格、权限、版本/保留策略和泄漏后果 |
| 内置 GitHub | 接受私有仓库承载加密配置,并需要历史版本 | 仓库必须私有;token 权限最小化;历史中旧密封文件仍会保留 |
| 一次性 backup/restore | 新机初始化、灾备或临时迁移 | 不是持续同步;restore 后仍需按设备补本机设置与登录 |
优先使用 Magpie 内置同步,而不是外层文件同步。选择后端时按顺序确认:
- 存储端是否只为同步对象授予最小权限。
- 传输是否可信;公网明文 HTTP 不应使用,私网/Overlay 网络也要确认实际加密与暴露面。
- 每台电脑是否能解析并连到同一端点,且代理、VPN、本地网络权限和地址族不会拦截。
- 服务端是否支持当前同步所需的读写方法;部分 WebDAV 服务根路径不可写或不允许客户端创建子目录,应使用明确的可写父路径。
- 是否需要版本保留、历史回滚和误删恢复。
3. 信任与凭据
- 服务端登录凭据和同步 passphrase 是两件事。passphrase 用于密封同步内容,不得与 WebDAV/S3/GitHub 凭据相同。
- passphrase 丢失后,远端密封文件不可恢复。应保存在用户认可的密码管理器或其他离线受控备份中;不要写入公开示例、任务卡或聊天。
- 同步 API key 前确认远端文件加密、访问控制和 passphrase 强度。同步订阅登录态必须单独授权,并说明账号被复用和互相续期的影响。
- 远端只应保存密封同步对象。验证时确认对象存在即可,不把密封文件当明文配置检查。
4. 首次收敛顺序
冻结 writer:指定一台权威机器;其他机器在收敛前不做配置修改。
本机留证:每台机器先做各自可恢复的密封备份,并记录版本、启用的数据域和预期差异。
统一版本:所有机器使用可互通的 Magpie 版本;版本差异以安装版帮助和回读为准。
权威端初始化:在权威机器先用最小数据域启用后端;
on会立即完成一次初始同步。后续扩大数据域时先修改配置,再 preview,最后now。命令示例:magpie webdav on https://dav.example/magpie-parent/ \ user=<user> keys=no agents=no library=no magpie webdav set memory=<yes|no> usage=<yes|no> sign-ins=<yes|no> magpie webdav preview magpie webdav auto <minutes> magpie webdav nowS3 与 GitHub 使用对应子命令;地址、bucket、prefix、repo 和凭据均使用实际环境的受控占位,不写入 Skill。
** follower 接入**:其他电脑接入同一端点。首次同步时本地不同部分通常被服务端版本替换;必须保留 CLI 提示的本机备份位置,不要手工覆盖。
确定写入策略:
- 权威机 + follower:follower 开启 follow,只接收服务端配置,适合多数“多机使用同一网关设计”的场景。
- 双向同步:仅在确有多 writer 需求时使用,并约定变更窗口;不要在两台机器同时改同一数据域。
按设备补差:登录订阅账号、设置本机代理/自启/端口、处理体积超限 Skill,再执行一次同步和真实请求验证。
地址、账号、证书、路径或端口变化可能让已保存凭据失效。重新认证不改变同步 passphrase,也不应触发整目录覆盖。
5. 验收矩阵
| 断言 | 方法 | 通过口径 |
|---|---|---|
| 网关健康 | 每台机器运行 status/healthcheck | 运行的是预期版本和本机网关 |
| 同步状态 | 每台机器读取对应 sync 状态 | 最后一次成功时间明确;失败不被 now 的后续输出掩盖 |
| 数据域回读 | providers、groups、models、library 状态 | 只比较本次声明的数据域;不把本机-only 差异当失败 |
| 登录边界 | 检查 sign-ins 设置和账号列表 | sign-ins=no 时订阅 provider 缺登录是预期,不是同步失败 |
| 大文件边界 | 查看 Skill missing/left 提示 | 明确哪些文件只留在源机器,不误称完整 Skill 已同步 |
| 真实落点 | 通过同步后的具名组发起最小代表性请求 | 请求成功且 served/usage 落点可解释 |
| 回滚路径 | 记录 undo/restore/backup 位置 | 能说明恢复到哪台机器的哪个时点;不删除远端旧对象 |
验证输出不得展开 key、token、账号明文或密封文件内容。
6. 常见故障分层
| 症状 | 优先检查 | 处置边界 |
|---|---|---|
| HTTP 401/403 | 服务端用户、权限、应用密码、bucket policy、repo token | 换最小凭据;不要把密码放进命令历史 |
| HTTP 404/405 | 后端地址、父路径、写方法、目录创建权限 | 改用明确的可写父路径或预先创建容器;不要强行覆盖远端 |
| 超时/no route | DNS、代理/TUN 排除、VPN 路由、地址族、防火墙 | 用同一端点做只读连通性对照;不因一次超时改全局路由 |
| 证书失败 | 证书链、主机名、私有 CA、时间 | 优先修受信证书;不为完成同步禁用校验 |
| Skill 提示过大/missing | Skill 目录中的归档、缓存、生成物和二进制 | 把运行产物移出 Skill、改用远端 source,或整 Skill off-here;不要假设 .gitignore 会生效 |
| 首次同步差异异常 | 权威机是否唯一 writer、follower 是否误开双向 | 停止写入,使用 CLI 的 undo/备份;不手工拼回 config 目录 |
| 远端空/疑似损坏 | 是否新端点、权限误判、历史对象或恢复命令 | 先保留现场和远端对象;只有在确认替换目标并留备份后才 restore/upload |
| passphrase 无效 | 是否误用服务端密码、大小写/输入法、密钥管理器版本 | 无法恢复旧文件;从权威机重新建立新密封版本 |
7. 维护约定
- 公开文档只保留抽象方案和占位命令;主机名、内网地址、账号、bucket、repo、真实 passphrase 与本地路径属于本机私有记录。
- 每次扩大同步域都是配置变更:先 preview、再授权、再执行,并记录各机器回读。
- 版本升级后重新核对 help、预算、follow/undo 语义和 Library 文件过滤行为,再处理历史
missing/left项。 - 新增机器按 follower 收敛,不把新机器的空配置或本机实验配置推成权威版本。