安装包设计规范

沉淀自平台/机器狗部署工具（deploy-tool）的完整演进：离线包、在线包、跨架构、证书交付、端口参数化。

核心原则：清单驱动（manifest-driven）

• 安装包必须自描述：根部一个 manifest（env/target/version/composeFile/profiles/镜像清单/组件 tag/类型标志如 online/platform），安装端只依赖它，不依赖打包时的任何外部状态；
• 清单字段只增不改：新能力用可选字段（omitempty），旧包/旧工具读新包不炸（如 online、mqttBrokerStyle、platform）；
• 打包端与安装端通过清单"协商"行为（如编排拼接风格探测），而不是安装端猜环境——猜环境是 bug 之源（曾因按 env 猜 MQTT 格式导致 tcp://tcp://host:p:p）。

单一产物与编排收敛

• 交付物压成单一 tar.gz，文件名承载人可读元数据（目标-环境-版本-[profile]-[online]-架构-时间戳）；
• 包内编排统一改名（如恒为 docker-compose.yml）：目标机人工操作无需分辨环境，也不泄漏其他环境编排；
• compose 可按需裁剪（如按所选 profile 删服务、剥 profiles 标记），使包自包含——安装端不再传 --profile；无 profile 的无条件服务保留（与 compose 语义一致）；所选 profile 不存在时打包即报错并列出可用值。

打包内容：白名单 + 自动引用收集

• 只带安装所需（编排、.env 模板、版本清单、运维脚本、编排引用的配置目录）；
• 不要硬编码引用目录清单——解析编排中所有 ./xxx 本地挂载引用自动收录（曾因硬编码漏了 mosquitto/，目标机 dockerd 把挂载源自动建成目录，服务静默起不来）；
• 维护运行时目录排除表（data / certs / host-meta / 运行产物目录）：dockerd/脚本/安装工具在目标机生成，绝不进包；certs 类尤其可能含打包机本机凭据；
• 仅识别短语法 volumes 时，注明长语法（type: bind）是已知盲区。

在线/离线双模

• 两种包由清单标志区分，安装端自动分支，用户无需选模式；版本语义（版本清单 → *_TAG → .env）两端完全同源。

版本与配置

• 版本清单是唯一事实源（主版本号 → 各组件 tag），打包、安装、运维脚本同读一份；
• 生成 .env 时：模板为底 + 清单 tag + 用户覆盖；用户显式值永远优先；被编排默认值"污染"的问题（如写死的开发 broker 地址）用"必填项 + 归一化"解决，不要相信编排里的默认值；
• 所有对外端口参数化（${VAR:-原值}，默认值逐字节不变 = 行为零变化），容器侧端口不动——为安装期端口冲突提供"重新指定"通道。