备份、恢复与升级

Desktop 的本机钥匙缓存与 Server 备份分别保管。账号钥匙可从服务器重新同步；pending_upload（仅在本机 · 待确认上传）和 local_only 的值只在该电脑，Server 备份不包含它们。Desktop 迁移及旧值更新在当前空间 env-import-backups 留下加密恢复副本，包含值、元数据、选择策略、同意/拒绝和迁移标记；不要在确认升级正常前清理。

本机缓存由 SkillHub 自己保管数据密钥：当前空间 keys/<账号>/unified/data-key.bin（32 随机字节），后续代位于 key-material/<代号>/data-key.bin。目录 0700、文件 0600，Windows 私有 ACL；不依赖 macOS 钥匙串或 Windows DPAPI。备份须同时包含正确代号的密钥文件和密文，能读取两者的人可以解密，请作为秘密保管。密钥丢失时报告 VAULT_KEY_MISSING，值备份也需要该密钥；原密钥或事先导出的口令加密密钥丢失后不保证恢复。核对实例后可用 skillhub keys reset-cloud --confirm --json 重置云端缓存与绑定，保留待上传/仅本机数据和密钥；失钥换代另用 keys rotate-data-key --confirm，保留旧资料。迁移备份通过 keys restore 恢复到独立私有目录，用完以 keys recovery-delete 明确删除。详见钥匙指南。

升级到包含后台 Skill 分析的版本后，启动入口会自动迁移任务表，并补扫未分析、无图片的作者 Skill。无需增加环境变量；配置 AI 或 fal 后才执行对应任务。已继承分析资料或头像的副本保持原状。升级前仍须按下文备份；已有手动编辑痕迹的历史资料会保留。

备份

在 deploy/selfhost 目录运行：

./skillhub-server backup

交互输入至少 12 字符的口令并确认。工具暂停原本运行的 Server，完成或失败后尝试恢复；public 还短暂停止 Caddy，本地 SeaweedFS 叠加会短暂停止对象服务。原本停止的服务保持停止。

也可创建口令文件供 backup、verify、restore、upgrade 的 --passphrase-file 使用：

mkdir -p ~/private
chmod 700 ~/private
# 只在该文件尚不存在时执行，避免覆盖已有口令。
install -m 600 /dev/null ~/private/skillhub-backup-pass

随后用编辑器打开 ~/private/skillhub-backup-pass，写入一行至少 12 字符的口令，末尾换行可以。文件须归当前用户所有、为普通文件、权限恰为 0600；不把口令写进命令参数。例如：

./skillhub-server backup --passphrase-file ~/private/skillhub-backup-pass

若还没创建管理员，初始化码在 Server 启动后 30 分钟过期；每次重启（包括 stop/up、backup、upgrade 中的重启）会签发新码，旧码立即失效。操作后使用新码，见 初始化码过期。已初始化实例不再签发码。

输出两份配套材料：

材料	内容	保管方式
数据目录	manifest 与加密的数据库、媒体、卡片等分片	保存完整目录，不只保存 manifest
.skr 恢复文件	口令加密的数据密钥、配置原文与摘要	移到另一台设备，与数据目录分开保管

两份材料和口令缺一不可；口令遗失无法恢复。 manifest 不含密钥，但包含实例身份、版本和统计。默认目录为仓库中的 deploy/selfhost/backups/ 与 deploy/selfhost/backups/recovery/，均已被 Git 忽略；可用 --out DIR --recovery-out DIR 指定不同位置。失败留下 .partial 目录供排查，不能当成完成备份。

备份含数据库、整个媒体卷和头像历史、卡片包、.env、当前与历史加密密钥、实例身份私钥；public 另含证书状态，本地 SeaweedFS 另含对象卷。外部 S3 不包含在内，须独立备份 bucket。

统一钥匙的全部修订、所有者、共享名单、个人选择和旧团队钥匙迁移映射也随数据库备份。实例管理员负责保管当前与历史 KEK（钥匙加密密钥），并在恢复时带回原配置；重新生成密钥无法解开旧值。恢复文件含这些材料，请与数据目录分开保管。Server 运营者持有解密材料，云端加密存储并不对运营者保密。

验证

把下面占位路径换成实际配套材料路径：

./skillhub-server verify --backup /备份目录/skillhub-时间-ID --recovery /另一设备/skillhub-recovery-时间-实例.skr

刚备份后、材料还在默认位置时，可在 deploy/selfhost 使用相对路径（替换为本次实际名称）：

./skillhub-server verify --backup backups/skillhub-时间-ID --recovery backups/recovery/skillhub-recovery-时间-实例.skr --passphrase-file ~/private/skillhub-backup-pass

验证后将恢复文件移到另一台设备，不长期和数据备份放在一起。

验证完全离线，不启动服务、不修改备份，需要本地已有 skillhub-selfhost-server 工具镜像。空机可先在 deploy/selfhost 构建：

docker build -t skillhub-selfhost-server -f ../../server/Dockerfile ../..

空机恢复

1. 请使用公开仓库的实际地址，并选择已发布的版本标签。

git clone https://github.com/billzhuang6569/zsir-skillhub
cd zsir-skillhub
git checkout <发布 tag>
cd deploy/selfhost

不要先运行 install.sh，不要创建 .env 或项目数据卷。 2. 带入数据目录与对应 .skr，执行：

./skillhub-server restore --backup /备份目录/skillhub-时间-ID --recovery /恢复材料/skillhub-recovery-时间-实例.skr

3. 工具先构建镜像并完整验证材料，再写配置和恢复。配置保留原 APP 地址；公网域名需要指向新主机。
4. 看到“恢复完成”后，用原账号登录 APP，检查历史图片、卡片与团队钥匙实际运行。身份、密文、文件和健康检查通过不能替代这一步。

恢复检查会认证新旧钥匙全部历史修订的密文，并核对共享和迁移映射。错误或缺失 KEK、损坏密文、缺少迁移都会失败，只显示计数或脱敏原因；请保留日志并恢复原材料。旧备份仍可读取，所选新版先执行数据库迁移后验证；未确认的旧团队钥匙仍需原提供者确认，不会自动转移所有权。

已有 .env 或任一项目数据卷会被拒绝，工具不删除它们；换全新主机。写入后失败时保留现场与日志，另建空环境重试。Postgres 主版本必须匹配，不能直接用新大版本挂旧卷。

升级

新版 APP 的账号钥匙同步需要 Server 提供统一钥匙能力。旧 Server 下保留本人旧本机值的更新和运行路径，不能创建或共享新账号钥匙；旧团队接口不能安全更新时会提示升级。升级 Server 也不会自动上传旧本机值，仍须确认目标实例、账号和范围。仅本机空间不受 Server 版本影响。

新版钥匙页可勾选遗留值并明确确认上传范围。账号钥匙由 Server 加密保存，其运营者持有解密材料，本机仅保留加密缓存；只有创建者可以更新、共享、删除和查看使用记录。创建者退团后，其钥匙对该团队的共享失效，团队需要提前安排留任成员提供替代钥匙。遇到「服务器需升级」，管理员可从钥匙提示定位当前实例的 Server 更新区，成员联系管理员；该跳转不自动检查或升级，也不改变实际业务能力。

运行会保留有效的具体钥匙选择，不按个人或团队来源决定优先级；首次匹配等待完整授权清单。本人已有选择可离线使用最后成功缓存，共享钥匙运行前必须在线复验。选择可经统一接口同步；持续使用同意目前保存在各台电脑，「仅这次」不跨设备。旧团队来源仍按原运行接口核权，升级后不会静默换成同名账号钥匙。

在 APP 中检查 Server 更新

自部署实例管理员可打开「设置 → 实例管理 → Server 更新」，检查当前实例版本、正式新版、累计变化、迁移与人工步骤。普通成员请联系实例管理员；官方服务和仅本机空间不显示此区域。旧 Server 无需新增更新检查接口。

APP 直接访问其编译渠道官网的公共发布记录，这会向官网暴露 APP 所在网络的出口 IP，不会附带实例账号或钥匙。进入页面时，本次 APP 运行中从未获取记录或记录超过 24 小时才自动检查；可关闭「进入页面时自动检查」，仍保留手动「检查更新」。APP 不运行时不会检查，也不会自动升级服务器。网络失败时旧信息显示检查时间，不能据此确认当前已是最新。

版本路径受支持只表示标准发行版之间的路径已验证，不代表主机、定制构建或备份已验收。构建摘要不同可能来自换行、本地修改或构建条件，请先确认；开发版本或高于公开版本时不要降级。需要中间版本时逐段核对并升级；说明不完整、路径未知或有人工步骤时先查看对应发布说明，不直接跳到最终版。不根据目标版本推断实例的 APP 最低版本政策。

在原安装仓库手动升级

macOS 的 WorkBuddy AI.app 使用新的兼容 Agent 标识 workbuddy-ai；workbuddy 在 Mac/Windows 都表示 WorkBuddy。使用新版 APP 时，请同步升级 Server，再保存包含新标识的 Skill 资料；旧 Server 会拒绝未知标识。本机安装仍可使用，历史 AI 目录安装自动归属 WorkBuddy AI，链接与内容保持不变，见 Agent 能力列表。

在原安装仓库原地更新，不另 clone 新目录，否则 .env 与默认备份仍留在旧目录。若当前在 deploy/selfhost，先用 cd ../.. 返回原仓库根目录，运行 git status --short 检查本地修改，并确认备份空间和维护窗口；再将下面的 <新 tag> 占位替换为选定的正式 vX.Y.Z 标签后执行，不要原样复制：

git fetch --tags &&
git checkout <新 tag> &&
cd deploy/selfhost &&
./skillhub-server upgrade

命令链任一步失败都应停止，先解决原因。不要用 git reset --hard 丢弃本地修改；定制部署需人工适配，不承诺标准脚本通用。原升级脚本不会 fetch Git 源码。升级会停机，先成功备份，再更新镜像类服务、构建 Server、启动与检查健康；备份失败则停止升级。仍须移走恢复文件并分开保管数据、恢复文件与口令。升级后重新检查实际健康状态，并用原账号验证图片、Skill 与团队钥匙等真实业务。

数据库迁移后不能只回退镜像。需要回退时，用升级前完整备份在空环境恢复。不要执行 docker compose down -v，也不要删除 .env 或重建 KEK 等密钥。

统一钥匙已有新写入后，也不能只降级二进制。先核对备份之后的新增与修改，优先修复当前版本；回退需要同时恢复数据库、密文、加密材料、共享、选择及迁移状态，不能覆盖后来有效更新。建议先以假值在空环境演练从上一 tag 升级、备份、验证、恢复，再登录检查本人和接收者是否能按权限取值。

具体拒绝原因见 恢复排查。