安装前置校验与故障预防

沉淀自 deploy-tool 的真实故障：双重拼接地址、amd64 包装到 arm64 狗、1883 被占 bind 失败、containerd 存储 save 崩、mosquitto 挂载源变目录。

校验分层：越早越便宜

参数校验（建连前，零成本）→ 目标机探测（上传前，秒级）→ 阶段校验（拉镜像/导入前）→ 运行时

• 必填项前置：目标专属必填（设备 ID/令牌/服务地址/证书）在建立连接前校验，缺什么列什么，不要连上目标机才报参数错；
• 架构校验（上传大包前）：包标注 platform，目标机 uname -m（x86_64→amd64，aarch64/arm64→arm64）；离线包不一致硬失败（防 exec format error），在线包仅告警（目标机按本机拉取天然正确）；旧包无标注跳过；
• 端口预检（拉镜像前）：解析编排对外发布端口（含 env 解析后的实际值；只看 ports:，忽略 expose/内部互访/命令行地址），ss -H -tln/-uln（mac 回退 lsof）探测占用；排除同项目旧容器占用的端口（重装会被 up 替换，不算冲突）；冲突时报出 服务/端口/持有者 + 可用的覆盖变量名。

错误必须可定位到元凶

• 批量操作（如 docker save a b c…）的守护进程报错不带对象名——失败时逐项重试定位（仅失败路径执行，输出丢弃防 GB 级进内存），报"问题镜像： xxx（原因）"；
• 报错文案带下一步动作：'在 .env 覆盖项添加 MQTT_PORT=<其他端口> 后重试'，而不是只描述现象。

Docker 高频陷阱（实战清单）

证书类输入

• 用户上传证书压缩包：固定文件名（基名匹配，可在子目录），忽略 __MACOSX/.DS_Store/readme 等杂项；缺失/重复逐一列出；
• 落盘到编排实际挂载路径（多种挂载约定就写多份冗余副本，以实际挂载生效）；
• 协议联动：传证书即 ssl、不传走 tcp；编排风格与证书有无冲突时给明确指引（如"tcp 拼接式编排不支持证书，请用支持 ssl 的包"）。

验证策略

• 每类校验至少三个用例：正确通过 / 缺失拒绝（错误文案含缺失项）/ 冲突拒绝（文案含元凶与动作）；
• 无法真机验证的路径（如目标机是 Linux 而开发机是 mac）用 docker/命令 shim（PATH 前置假命令返回成功与逼真输出）做流程级冒烟，并如实标注"真实环境待验"。