备份 · 迁移(Export / Import)

把 Blyck 迁到另一台电脑时(例如 Windows 笔记本 → macOS Mac mini),手动复制 userData 文件夹会导致聊天指向旧 PC 的绝对路径、密钥被绑在 OS 钥匙串里解不开、OS 相关二进制文件跑不起来。

备份 · 迁移用一个按钮打包(export)和解包(import),解包时自动转换路径,让聊天记录原样接续。Win↔Mac 四个方向全部可用。

为什么手动复制会坏

问题	内容
绝对路径不匹配	聊天指向 `D:\develope\…`,而新 PC 是 `/Users/…`
OS 相关密钥	DB/SSH 密码·GitHub 令牌用 OS 钥匙串(safeStorage)加密,在另一台 PC 无法解密
OS 相关二进制	python venv、LSP 服务器等即便复制过去也跑不起来
庞大的可再生缓存	检索/嵌入索引(`workspace.sqlite` ~226MB)整个跟着搬

搬什么、丢什么

🟢 迁移对象(包内含)

chats/ —— 聊天记录(含消息,自包含)
blyck-history.db —— 变更历史(VACUUM INTO 快照)
db-history.json · db-snippets.json —— DB 查询历史·片段
layout.json · blyck-locale.json · embeddings-settings.json —— 布局·语言·设置
connections.json —— DB/SSH 连接元数据(明文包中 strip 掉密钥)
attachments/ · changeSet-snapshots/ —— 可选

⚫ 排除 —— 在目标 PC 上重新生成

workspace.sqlite —— 检索/嵌入索引(~226MB)。大部分派生自代码库,整个排除可让包从 230MB → 几 MB,目标 PC 上索引器会自动重新建索引。
python-venvs/ · lsp-servers/ —— OS 二进制(重新生成)
Electron/Chromium 运行时缓存、日志等

包格式 `.blyckbundle`

ZIP 容器 + manifest.json(模式·应用版本·源 OS·路径根·每文件 sha256)。

backup-YYYY-MM-DD.blyckbundle
├── manifest.json
└── files/                       # userData 相对路径镜像
    ├── chats/index.json, chat_*.json
    ├── blyck-history.db
    ├── db-history.json, db-snippets.json
    ├── layout.json, blyck-locale.json, embeddings-settings.json
    ├── connections.json         # 明文包 strip 掉密钥
    ├── attachments/**           # 可选
    └── changeSet-snapshots/**   # 可选

路径重映射 —— 让聊天原样接续

import 时只替换聊天 JSON 中权威的路径字段。

字段	重映射
`projectRoot`	✅ 替换
`_lastSentProjectRoot`	✅ 替换
`extraRoots[]`	✅ 逐元素替换
`projectRootSftp`	❌ 不变(远程与 PC 无关)
`messages[]`	❌ 不变(保留历史)

规则是最长前缀匹配 —— 路径若以源根开头,则只把前缀替换为目标根,并转换其余分隔符。未映射的根原样保留(聊天能打开,只是项目未解析,由用户重新打开)。

跨 OS 四向(Win↔Mac 全组合)

remapPath 分别处理源分隔符(拆分)与目标分隔符(拼接)。源分隔符从源根自动检测(\/盘符 → Win,/ → POSIX),目标分隔符由目标 OS 决定。

方向	源路径示例	结果示例
Win→Win	`D:\dev\App\src\a.js`	`E:\work\App\src\a.js`
Win→Mac	`D:\dev\App\src\a.js`	`/Users/x/App/src/a.js`
Mac→Win	`/Users/x/dev/App/src/a.js`	`D:\work\App\src\a.js`
Mac→Mac	`/Users/x/dev/App/src/a.js`	`/Users/y/App/src/a.js`

与盘符/根无关 —— 由于是前缀替换,D:\ ↔ /Users/ 等任意根组合都能在映射表中 1:1 解决。

加密包 + 包含密钥

export 时指定密码即可加密整个包。

方式:整包 AES-256-GCM —— ZIP 内置加密(ZipCrypto)有缺陷故不采用,而是在生成 zip 之后用 Node 内置 crypto 整体加密(外部依赖为 0)。KDF 为 scrypt,加密为 AES-256-GCM(机密性 + 完整性)。
密码输错 = GCM auth tag 校验失败 →『密码错误』即时检出(无部分解密,数据不变)。
通过明文头(BLYCKENC1),无需密码也能先判别是否加密。

密钥与方向无关 —— Win safeStorage 解密 → 加密包 → Mac safeStorage 重新加密(反向亦同),因此 Win↔Mac 四向皆成立。

Export 流程

停止确认 —— 若有 busy 回合则拒绝(数据一致性)
blyck-history.db → 用 VACUUM INTO 生成单一快照(应用运行中也安全)
收集包含文件 + 每文件 sha256
扫描 chats → 把 distinct 路径根记入 manifest.pathRoots
密钥处理 —— 未指定密码:strip / 指定密码:包含明文密钥
ZIP 打包
指定密码时进行 AES-256-GCM 加密 → 写入 *.blyckbundle

Import 流程

inspect —— 用 magic 判别是否加密。若加密则弹出密码输入提示
解密 —— 密码 → scrypt → AES-256-GCM。auth tag 失败则中止(数据不变)
路径重映射 UI —— 按源根分别提供输入框(自动推荐 basename:D:\develope\Blyck_Web → ~/dev/Blyck_Web)
安全备份 —— 把当前 chats/·*.db 保存到 userData/_pre-import-<ts>/
提取 files/ → 写入 userData
应用重映射 —— projectRoot/_lastSentProjectRoot/extraRoots 做最长前缀替换 + 分隔符归一化(projectRootSftp·messages 不变)
恢复密钥 —— 加密包:用目标 OS safeStorage 重新加密 / 明文包:置『需重新输入』标志
没有 workspace.sqlite → 下次运行时自动重新建索引
重启提示

模式 —— 替换 vs 合并

模式	行为	用途
替换(replace)	把当前 `chats/`·`*.db` 备份到 `_pre-import-<ts>` 后用包替换	整体迁到新 PC
合并(merge)	在现有安装上按 chat id 合并(不替换,仅追加)	把两台 PC 的工作汇到一处

合并之所以安全,是因为 chats/ 是按 id 分立的 JSON,可无冲突地合并。

安全措施

import 前自动备份当前数据(_pre-import-<ts>)
manifest 模式/应用版本兼容门
每文件 sha256 完整性校验
聊天 busy 期间拒绝 import
替换前需用户明确确认
加密包密码输错 → 在解密阶段中止(数据不变)
明文包不含密钥(防泄露)

FAQ

Q. 聊天记录在新 PC 上能原样打开吗? → 能。import 时通过路径重映射把 projectRoot 等自动转换为新 PC 的路径,因此聊天与项目原样接续。

Q. DB/SSH 密码要重新输入吗? → 用加密包(指定密码)导出时,密钥会被包含并用目标 OS 重新加密,无需重新输入。明文包出于安全考虑会去掉密钥,故需重新输入。

Q. 在 Windows 上做的包能在 Mac 上解开吗? → 能。包含 Win→Mac、Mac→Win 的四向全部支持。路径分隔符(\↔/)与盘符/根会自动转换。

Q. 包为什么这么小? → 226MB 级的 workspace.sqlite(检索索引)可从代码库重新生成,故排除。目标 PC 上索引器会自动重新建索引,而聊天记录本身原样保留。

Q. 忘记密码怎么办? → 没有恢复手段。AES-256-GCM 没有密码无法解密,因此请妥善保管加密包的密码。

Q. 想合并到现有 PC 的工作上怎么办? → 请用合并模式。它按 chat id 合并,不删除现有聊天,仅追加。