data-gen-bpu/docs/portability.md

9.3 KiB
Raw Permalink Blame History

独立迁移与 Docker 控制面

本目录的 Docker 镜像只包含 bench 控制面 Python 源码和固定版本的 PyYAML。 它不包含授权编译器、模型运行环境、CUDA、Node、Pi、OpenCode、数据、权重、SSH 密钥或历史任务。 容器 --help / capabilities 成功只证明控制面可启动,不能代替真实编译、板端和 Agent 验收。 不修改现有安装,不重启现有进程;新机器或新目录从空白状态启用。

1. 打包和启动只读预检

在候选 bench 目录执行(需要 Python 3.10+;清单工具额外需要 PyYAML):

python3 scripts/package_release.py --output ../bench-source.tar.gz
# 输出 archive SHA256;包内 RELEASE_MANIFEST.json 列出每个源码文件的 SHA256。
mkdir -p ../release-check
cd ../release-check
tar -xzf ../bench-source.tar.gz
cd bench
docker build --build-arg SOURCE_SHA256=<上一步SHA256> -t bench-control:convergence-20260920 .
docker run --rm --cpus=1 --memory=1g --network=none --read-only \
  --tmpfs /tmp:size=64m bench-control:convergence-20260920 --help
docker run --rm --cpus=1 --memory=1g --network=none --read-only \
  --tmpfs /tmp:size=64m bench-control:convergence-20260920 capabilities --target s100p
docker compose -f docker/compose.yaml run --rm bench
# 使用其他已验证的镜像标签时,设置 BENCH_IMAGE;默认标签与本次交付一致。

源码包、同步和漂移检查共用 scripts/release_files.py 的文件规则;源码包可含模型表快照, 同步单独保护远端生成的模型表。采用目录、文件扩展名白名单;不跟随任何软链,排除 .git、.env*、密钥文件、 state/runs/data/cache/datasets/reports、虚拟环境和 node_modules。文件哈希由实际入包字节计算。 直接重复同一输入可以得到相同压缩包哈希;已有输出文件不覆盖。 不要把凭证硬编码到源码、配置或文档。.dockerignore 提供第二道排除,推荐始终从源码包构建。

基础镜像 python:3.12-slim 与 apt 软件包仍随仓库变化;这不是逐位可复现镜像。 交付时保留源码包哈希、Docker image ID、基础 image digest 和构建日志;需要固定环境时传入 --build-arg PYTHON_IMAGE=python@sha256:<已验证digest>,并保存已验收镜像。

docker save bench-control:convergence-20260920 -o ../bench-control.tar
# 将镜像及源码清单运到新机器;目标机使用兼容架构。
docker load -i ../bench-control.tar

docker/config.yaml 是新安装模板:端点未配置、OpenCode 禁用、并发保守、jail 保持开启。 Compose 默认网络关闭、根文件系统只读,不启动调度器,也不要求挂载任何现网数据。 本次工作仅测试独立容器;未切换现网,也未把全部业务迁到第二台机器。

2. 迁移清单与挂载

python3 scripts/migration_inventory.py --config docker/config.yaml --require control > inventory.json
# 在已准备的目标环境检查实际所需作用域;缺项退出码为 2。
python3 scripts/migration_inventory.py --config docker/config.yaml \
  --require control --require compile --require storage > target-inventory.json

清单只读取白名单源码与配置;对依赖位置仅检查元数据,不执行编译器,不读取 .env.local、 私钥、SQLite、权重或数据文件,也不遍历 data/cache/state。输出环境变量名称和是否已设置, 不输出其值。静态绝对路径引用带文件、行号和用途分类,需要按所选 recipe 确认是否使用。 present 只表示元数据可见,不证明 ABI、授权、版本、连接和业务兼容。

清单与运行时共用路径解析:root 为显式 --root、BENCH_ROOT、源码根依次取值;config 为显式 --config、BENCH_CONFIG、所选 root 的 config.yaml 依次取值;state 由 BENCH_STATE_DIR 或所选 root 的 state 决定。相对 override 相对于调用时工作目录,输出均显示 resolved 路径。 BENCH_CONFIG 只更换配置文件,不更换 registry;registry 来自 BENCH_ROOT/registry。 新安装应让源码导入路径、BENCH_ROOT 与 registry 属于同一发布版本。

内容 容器位置 / 配置 迁移方式
运行配置 BENCH_CONFIG / /opt/bench/docker/config.yaml 从模板生成目标配置,以只读文件挂载
板卡注册与数据源 /opt/bench/registry 独立副本;检查 boards.yaml 槽号及 datasets.yaml 的源路径
授权编译器及通用模型 Python /opt/toolchains / paths.venv / toolchains.*.venv 合法安装匹配版本后只读挂载;不在镜像内自动安装闭源包
特定模型运行环境 model_runtimes.<model_id> 使用显式目标 Python 路径;与注册的模型匹配
Pi 与 Node paths.pi_bin / paths.node_bin 兼容 Linux 运行环境,单独安装并只读挂载
OpenCode runners.opencode.bin 独立安装固定 CLI 版本;保持禁用直到原生适配验收
OpenCode 插件依赖 /opt/bench/agent/opencode/node_modules 在独立副本用已提交 lock 执行 npm ci,再只读挂载
技能文件 paths.horizon 新副本只读挂载;不能自动继承宿主机目录
状态与证据 /opt/bench/{state,runs,reports,datasets} 新建独立可写目录;SQLite 放本地盘,不能与现网共用
权重与数据 /opt/bench/{cache,data} 单独迁移并核对清单;确保配置引用的源目录可见
编译临时目录 paths.work_root,默认 /var/lib/bench/work 独立本地可写盘
凭证与 SSH 环境变量名见 inventory / boards.yaml 目标机单独供应,私钥只读挂载;不进入镜像、源码包和版本库

注意:现有 adapter 仍可能引用 /home/...、/mnt/data/... 或带原始路径的虚拟环境。 仅改 paths.venv 不能保证这些模型已迁移。优先用已有 model_runtimes / source 环境变量配置; 尚无配置入口的 recipe 可以在新容器提供相同路径的只读挂载,或单独完成最小配置化再验收。 Python venv、动态库和 CUDA 通常不能随意改路径或跨系统复制;应在兼容目标环境重建。

需要真实执行时创建单独的 Compose override,明确上述只读/可写挂载、网络、设备和 命令;不要在默认文件里加入现网路径、自动收集器或 privileged: true。 容器中的 unshare -Urmpf 是否可用取决于宿主机、内核及容器安全策略,默认配置不承诺支持。 先在新目录运行 scripts/jail_probe.sh;失败时停止启用 Agent,由管理员配置允许的隔离运行环境, 不得通过关闭 jail 把检查变成成功。迁移清单不是这个内核隔离检查的替代物。

3. 逐层验收与恢复

顺序为源码哈希 → 配置/挂载清单 → CLI 能力预检 → 环境版本/隔离探测 → 单模型单板真实执行 → Agent 原始轨迹与证据校验 → 逐步放大。S100/S100P/S600 的注册可配置并不等于每块板已验收; X5 与新工具链需提供真实支持、阶段实现和验证后才启用。

本次采用源码发布包与新 tag,不覆盖现有目录或容器。停止新目录里的新进程即可退出试运行; 旧系统继续使用原来的源码和配置。新 state 的本地锁也独立:若新旧部署连接同一物理板, 这些独立锁不能互相排队。真实运行前须等待旧部署自然结束,或分配不重叠的板卡资源; 需要共同调度时应先明确设计共享锁,不能把独立 state 当作同板并行安全的证明。 已有运行数据库不直接复制迁移:先完成独立备份、一致性 检查与 continuation 计划审核,再针对所需历史记录设计切换。

4. 收敛到唯一主线

后续开发源是当前候选的 fix/engineering-convergence-20260920 分支;隔离目录只是验证位置, 不另建一套产品。原本地工作树和远端在跑工作树分别保留其既有变动,不把新包直接覆盖上去。

  1. 在原任务自然收尾且确定切换窗口后,重新保存原本地与远端的 Git 身份、脏补丁、未跟踪源码、 资源登记及配置摘要。仅有本次早先的快照不足以证明部署时前像没变。
  2. 用临时 Git 分支审查并合入候选提交与这两处既有差异,逐项解决冲突,特别保留板卡的启停与 slot。 以合并后的单一提交重新测试、打包和记录哈希;已有验证不能自动转移到不同字节的包。
  3. 在新的版本目录解包,从模板准备该机器配置,核对依赖/数据、目标板和隔离能力。 同一物理板的所有测试参与者须共用 state 锁域及板端 runtime_dir,或者使用不重叠的资源。
  4. 若选择同步,先显式目标 preview 写一份新的本地 baseline,再审查并 apply;--files 也受同样约束。 本地/远端任何受管内容变化均需重新预览;自动同步拒绝源码删除,不处理运行数据。
  5. 切换只启动新目录的进程。保留旧源码包、配置与只读状态备份;退回时先等新在途工作结束, 再使用旧版本与其匹配状态。不要把新旧 SQLite 互相覆盖,也不要让两版重复领取相同任务。

本轮交付不执行上述生产切换。新版本的状态、测试原始证据和旧版发布包均保留; 后续包明确注明替代的源码提交,避免把不同批次的测试结果拼成一次验收。