data-gen-bpu/docs/portability.md

125 lines
9.3 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 独立迁移与 Docker 控制面
本目录的 Docker 镜像只包含 bench 控制面 Python 源码和固定版本的 PyYAML。
它不包含授权编译器、模型运行环境、CUDA、Node、Pi、OpenCode、数据、权重、SSH 密钥或历史任务。
容器 `--help` / `capabilities` 成功只证明控制面可启动,不能代替真实编译、板端和 Agent 验收。
不修改现有安装,不重启现有进程;新机器或新目录从空白状态启用。
## 1. 打包和启动只读预检
在候选 bench 目录执行(需要 Python 3.10+;清单工具额外需要 PyYAML):
```sh
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>`,并保存已验收镜像。
```sh
docker save bench-control:convergence-20260920 -o ../bench-control.tar
# 将镜像及源码清单运到新机器;目标机使用兼容架构。
docker load -i ../bench-control.tar
```
`docker/config.yaml` 是新安装模板:端点未配置、OpenCode 禁用、并发保守、jail 保持开启。
Compose 默认网络关闭、根文件系统只读,不启动调度器,也不要求挂载任何现网数据。
本次工作仅测试独立容器;未切换现网,也未把全部业务迁到第二台机器。
## 2. 迁移清单与挂载
```sh
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 互相覆盖,也不要让两版重复领取相同任务。
本轮交付不执行上述生产切换。新版本的状态、测试原始证据和旧版发布包均保留;
后续包明确注明替代的源码提交,避免把不同批次的测试结果拼成一次验收。