Linux 单机迁移与运行

本手册记录当前采用的直接迁移流程：冻结源端写入，数据库和对象经 SSH 流传输，主密钥通过平台命令管道传输，在目标完成核验后启动系统服务。本流程不新建备份、不运行迁移演练，也不保留数据库 dump 文件。已有 circle-hub-backup@3 备份及演练流程仍是平台的历史能力，本次不使用它们。实际服务器地址、机器路径、账号授权状态和业务数据只记录在受控的仓库外交接材料中。

示例中的尖括号为占位说明，不可直接当作命令执行；命令由所有者或指定管理员在确认目标身份、权限和路径后填写和执行。代码和服务必须先具备 Linux 支持；本手册不能单独证明部署或业务验证成功。

环境和边界

  • 登录前先核验 SSH 主机密钥，仅以非交互公钥认证检查访问；拒绝时停止，不尝试密码或重复登录。登录后读取 /etc/os-release，用 uname -m 核对架构，再按实测系统准备 Node 24、bubblewrap、AppArmor、systemd 和与嵌入式服务端同主版本的 PostgreSQL 客户端。不能用 SSH banner 推断操作系统版本。
  • Hub 以专用服务用户运行；数据目录和密钥文件由该用户持有，密钥目录 0700、主密钥文件 0600。目标安装适合本机架构的依赖和 Node，不使用 macOS 的 node_modules。跨机设置中旧 Node 绝对路径不自动替换；平台命令需要时显式指定已经核对的目标 Node 路径。
  • Linux 使用 bubblewrap 与 AppArmor 叠加隔离；按目标发行版配置用户命名空间和相应策略。策略由 node hub/rules/sandbox/linux.ts 生成，由管理员核对并装载；Node 或 shell 路径变化时在服务停止、写入冻结后重装。Ubuntu 26 的现场兼容处理可能需要由管理员设置 kernel.apparmor_restrict_unprivileged_userns=0，否则 bubblewrap 设置回环接口可能被拒绝；这会放宽全机非特权用户命名空间限制，不是仅对 Hub 的例外，必须在交接中如实记录。AppArmor 策略仍装载，不能把该设置称为 AppArmor 已关闭。当前兼容代码接受引擎实际返回的 //&unconfined 叠加标签；不据此声称所有发行版均已验证。Linux 隔离要求 process.permission.drop：Node 24.20.0 发行说明记载了该接口，目标实际运行时仍必须进行功能探测；不可用时拒绝执行。
  • 服务可以显式监听所有者批准的内网地址，必须同时提供精确允许主机名单；未指定时默认回环。防火墙来源由所有者决定，文档中的示例地址只使用 192.0.2.0/24。HTTP 直连的令牌和数据在传输路径上可能被观察；是否用反向代理终止 TLS 由所有者决定。

冻结与迁移

  1. 切换前确认：确定停写窗口，通知使用者停止新请求和调度，核对没有未结束或效果未知的 job、lease 和派发，处理其他写入者。停止本机服务前，负责迁移的主代理必须先回报“即将切换”。
  2. 冻结源端：管理员停止并卸载源端 Hub 服务，确认它不会随登录或机器重启自行启动；核对所有写者已停止。停止本地进程不证明远端效果停止，未知作业必须先按现有对账流程处理。保留源端原数据，不建立新的备份或演练目录。
  3. 准备目标：在目标本地磁盘放置已核对的 Linux 代码和与本机架构相符的依赖；以专用服务用户初始化目标数据根和仅使用 Unix socket 的 PostgreSQL。核对目标数据库、角色、数据根和源端一致性，不把数据库开放为 TCP 服务。
  4. 流式迁移数据库：使用与源、目标服务端同主版本的 pg_dump 和 pg_restore；源端执行 pg_dump -Fc，通过无伪终端的 SSH 管道交给目标 pg_restore --no-owner --single-transaction，让目标进程以预定服务用户连接目标数据库。启用 shell 的 pipefail，分别检查两端退出状态；不得把 dump 重定向到文件或留下未加密中间件。目标若拒绝或恢复失败，保持 Hub 服务关闭并处理失败，不宣称数据已完整。
  5. 流式迁移对象与密钥库：将源数据根的 objects/ 和加密的 vault/ 以 tar 流经认证 SSH 传至目标数据根；核对目标属主、目录权限与传输结果。不复制源端 releases/、packs/、set-aside/、backups/ 或 logs/，其中 packs/ 为可从对象重建的派生内容。资源、连接器和其他必要设置按平台支持的配置方式处理，不把真实地址或配置内容写进仓库。
  6. 传输主密钥：源端 circle-hub key export --confirm 将原始 32 字节写到管道，SSH 不分配伪终端，目标服务用户从标准输入运行 circle-hub key import。导出和导入只接受管道或 socket，不接受终端或普通文件；目标已有主密钥时拒绝覆盖。传输前完成目标管理员授权，切换服务用户的命令不得从承载密钥的标准输入读取 sudo 口令。密钥不得进入屏幕、参数、环境变量、日志、终端录屏或明文临时文件。操作令牌不迁移。
  7. 核验后启动：在写者冻结时按平台支持的命令执行 circle-hub records verify 与 circle-hub records verify --vault；前者核记录，后者逐条做 AEAD 核验，不输出条目明文或密文，空密库返回未知。数据库和流传输没有备份清单时，不能声称已完成备份清单比较或行数摘要核对。核验缺失、未知或失败时保持服务关闭并写明下一步。
  8. 启动与连接：目标使用管理员管理的 systemd 系统级服务，单元运行用户和组均为专用服务用户；确认单元的路径、监听地址、允许主机和服务账号后启动并查状态。恢复的数据库已有管理员时不要运行只适用于首个管理员的 init-admin；使用受控的 circle-hub operator-token reissue --as <已有管理员> 重新建立操作令牌。先核健康端点和权限，再由指定同事用 Circle 连接并完成经授权的只读运行；不得以此声称真实设备或写操作经过验证。由所有者确认放行时间并指定目标为唯一写入源。

回退与后续维护

  • 若目标未放写，先停止并禁用目标服务，确认没有其他目标写者或在途效果，再确认源端是唯一写入源，重新安装、启动源服务并恢复访问。
  • 若目标已放写，不能直接恢复源端访问：先冻结目标所有写者、停止并禁用目标服务、对账新增记录和在途作业，由所有者决定受控的数据反向迁移或调和；不能擅自丢弃任一侧记录或形成双写。
  • 迁移结果分别记录数据库流传输、对象流传输、密钥导入、逐条密库核验、服务健康和 Circle 只读连接。任何缺少证据的环节保持未知并写明下一步；不把备份格式验证、合成测试或一次健康检查当成真实业务运行的证明。
  • 日常的升级、令牌签发、备份、恢复或其他平台能力依其各自命令与授权办理；本次迁移没有新建备份，也没有开展独立演练。