mise bootstrap compose：用 [bootstrap.compose] 声明式管理 Docker Compose 项目生命周期

mise bootstrap compose用 [bootstrap.compose] 声明式管理 Docker Compose 项目生命周期【免费下载链接】misedev tools, env vars, task runner项目地址: https://gitcode.com/GitHub_Trending/mi/misemise bootstrap是 mise 内置的机器配置工具而[bootstrap.compose]负责其中长驻型 Docker Compose 项目的声明式管理它可以在包、特权文件、目录与系统服务收敛之后自动拉起、停止或拆除 Compose 项目并持续校验容器运行状态与 Compose 模型是否一致。读完本文你将掌握[bootstrap.compose]的完整配置语法、三种生命周期状态、收敛判定原理、镜像拉取/重建/等待策略以及如何接入 Podman 或远程 Docker 上下文等替代引擎。一、[bootstrap.compose]解决的问题自托管服务如缓存、数据库、反向代理通常需要四样东西协同Compose 文件、环境变量文件、Docker 安装、守护进程运行状态。[bootstrap.compose]的设计目标就是把这四样全部纳入同一份 bootstrap 配置中让一个mise bootstrap完成从装 Docker、写配置文件到拉起容器的全过程。从 bootstrap.md 记录的阶段顺序可以看到Compose 阶段位于第 7 步在 accounts、plugins、packages、files、services、firewall 之后在 repos、dotfiles 之前运行。也就是说当 Compose 项目被收敛时它所依赖的 Docker 包、compose.yaml文件、.env文件以及 Docker 系统服务都已经被处理完毕。二、一个完整的自托管服务示例下面这个示例针对 Debian/Ubuntu 主机其软件源提供了示例中列出的 Docker 包。它演示了 secrets、packages、services、directories、files 与 compose 六个模块如何协同[bootstrap.secrets] s3_access_key EXAMPLE_S3_ACCESS_KEY s3_secret_key EXAMPLE_S3_SECRET_KEY [bootstrap.packages] apt:docker.io latest apt:docker-compose-v2 latest [bootstrap.services.docker] state running enabled true [bootstrap.directories./opt/mise-cache] mode 0755 [bootstrap.files./opt/mise-cache/compose.yaml] source ./infra/mise-cache/compose.yaml mode 0644 [bootstrap.files./opt/mise-cache/.env] content S3_ACCESS_KEY{{ secret(names3_access_key) }} S3_SECRET_KEY{{ secret(names3_secret_key) }} template true owner root group root mode 0600 [bootstrap.compose.mise-cache] project_dir /opt/mise-cache files [compose.yaml] env_files [.env] project_name mise-cache state running sudo true depends_on [package:apt:docker.io, service:docker]示例中需要提前在infra/mise-cache/compose.yaml准备服务的 Compose 模型并在 apply 之前提供两个已声明的 secret 输入。.env的模板假设值都是单行形式符合 Compose.env格式要求如果值包含引号、换行等特殊字符需要按该格式自行编码——secret()函数只负责插入值不会为 shell、JSON、TOML 或 Compose 做任何转义参见 secrets.md。关键字段约束project_dir为必填项且必须是绝对路径否则会在配置加载阶段直接报错源码见 src/system/compose.rs。files与env_files中的相对路径都相对于project_dir解析。如果不提供filesCompose 会执行其正常的项目目录发现逻辑。mise 按声明顺序传递多个 Compose 文件与环境文件因此后面的条目保留 Compose 的覆盖override语义。三、先预览再执行在执行任何变更之前先看全量计划或仅针对相关阶段的 dry-runmise bootstrap plan mise bootstrap --only packages,files,services,compose --dry-run当 mise 需要先创建文件、再安装 Docker 时必须使用完整 bootstrap 或如上例包含所需阶段。需要注意mise bootstrap compose apply只收敛 Compose 项目不会应用其包与文件前置条件dry-run 无法证明某个镜像能在目标机上成功启动或通过健康检查——它只是打印将会运行哪些命令。bootstrap compose apply的 dry-run 输出形如would run docker compose ...且即使在引擎尚未安装时也能打印出将要执行的命令源码测试见 src/system/compose.rs。四、生命周期与收敛statestate字段控制项目生命周期对应源码中的ComposeState枚举src/system/compose.rsstate执行的命令行为running默认compose up --detach检查每个被选中服务的运行态与健康状态并比对 Compose 的 canonical config hash 与每个容器的com.docker.compose.config-hash标签stoppedcompose stop保留已配置的容器与项目数据若remove_orphans true会通过配置的容器引擎移除已从 Compose 模型中删除的容器absentcompose down可选附带卷volumes与镜像images的删除收敛的判定标准只有容器状态与渲染后的 Compose 模型同时匹配状态才算收敛。也就是说对 Compose 文件、插值输入interpolation inputs、profiles 或服务配置的任何改动都会被呈现为一次update而不会隐藏在一个仅仅在运行的容器背后。从源码的running_is_converged逻辑看src/system/compose.rs判定包含三层remove_orphans开启时不存在已不在模型中的孤儿容器每个目标服务至少有一个容器且运行时状态满足要求容器上的com.docker.compose.config-hash标签与docker compose config --hash*计算出的期望 hash 完全一致。源码中的单测plans_runtime_and_config_hash_drift验证了这一点hash 相同 →Noophash 变化 →Updatesrc/system/compose.rs。oneshot 服务oneshot列出那些成功退出exit code 0即视为收敛的服务。其他被选中的服务则必须处于运行状态且若定义了健康检查必须 healthy。此外一旦设置了services每个 oneshot 服务也必须出现在services列表中否则配置加载直接报错src/system/compose.rs。五、项目选择Project selection字段说明project_name显式指定 Compose 项目名。必须以小写字母或数字开头只能包含小写字母、数字、短横线和下划线。源码用validate_project_name强校验src/system/compose.rsfiles有序的 Compose 文件列表通过--file传递env_files有序的插值环境文件列表通过--env-file传递。敏感值应放在0600权限的托管文件中而不是直接写进 bootstrap 配置profiles通过--profile启用的 profilesservices可选的服务子集为空表示所选文件与 profiles 启用的全部服务oneshot允许成功退出后保持 exited 状态的服务设置services时每个 oneshot 服务也必须同时被选中depends_on必须先行收敛的额外 bootstrap 资源 ID例如package:apt:docker.io或service:docker自动依赖与显式依赖匹配project_dir、files、env_files的托管条目会被自动关联源码会为project_dir生成directory:path资源 ID为每个文件/环境文件生成file:path资源 IDsrc/system/compose.rs。显式depends_on条目必须真实存在拼写错误会在 plan 阶段直接失败。parse_dependency只接受package、file、directory、service、user、group六种类型src/system/compose.rs。六、Apply 策略字段可选值说明pullmissing默认、always、never镜像拉取策略buildauto默认、always等价--build、never等价--no-build构建策略recreateauto默认、always等价--force-recreate、never等价--no-recreate重建策略waittrue默认up之后等待服务 running/healthywait_timeout秒最长等待时间要求wait true且必须大于 0timeout秒stop/shutdown 超时remove_orphanstrue默认移除模型中已不存在的项目容器renew_anonymous_volumesfalse默认up期间更新匿名卷只允许与state running组合down_volumesfalse默认down时删除命名卷与匿名卷破坏性操作应审慎启用down_imageslocal或alldown时可选移除项目镜像同样是破坏性操作从源码的action_args实现src/system/compose.rs可以看到这些策略最终映射为具体的 Compose CLI 参数running 状态生成up --detach --pull policy并依条件追加--build/--no-build、--force-recreate/--no-recreate、--wait、--wait-timeout、--timeout、--remove-orphans、--renew-anon-volumesabsent 状态生成down并依条件追加--volumes、--rmi local|all。配置互斥校验这些组合并非任意可用源码在from_toml_with_origin中做了防御性校验src/system/compose.rsstate absent不能与services组合down作用于整个项目不接受服务名wait_timeout要求wait true且不能为 0down_volumes/down_images要求state absentrenew_anonymous_volumes要求state running。七、引擎与权限mise 在目标机上按以下顺序解析 Compose 命令源码见 src/system/compose.rs优先使用docker compose插件通过docker compose version探测回退到独立的 Docker Compose v2 可执行文件docker-compose通过version --short验证主版本号为 2不支持Compose v1——因为它缺少安全收敛所需的结构化 inspection 与生命周期 flags探测到 v1 时会直接报错提示安装 v2。command与engine_command接受 argv 数组可指向 Podman、远程 Docker context 或其他兼容前端且不会经过 shell[bootstrap.compose.edge] project_dir /srv/edge command [podman, compose] engine_command [podman]engine_command用于两件事检查容器上的 config-hash 标签inspect --format {{json .Config.Labels}}以及在收敛stopped项目时remove_orphans true移除孤儿容器。如果command形如docker --context remote composemise 会自动从其中推导引擎命令前缀docker --context remote源码测试derives_engine_command_with_global_options验证了这一点见 src/system/compose.rs。sudo 与权限当项目属于系统级 Docker 守护进程、而执行 bootstrap 的用户没有 socket 访问权限时设置sudo true。mise 在捕获状态输出之前先完成认证不会隐藏交互式 sudo 提示并遵循既有的system_packages.sudo策略。所有 compose 命令都在COMPOSE_ANSInever、COMPOSE_PROGRESSplain的环境中运行保证输出可被稳定解析src/system/compose.rs。八、命令行操作mise bootstrap compose status mise bootstrap compose status --json mise bootstrap compose apply --dry-run mise bootstrap compose apply --yesstatus会实际调用 Compose 进行 inspectionconfig --services、config --hash*、ps --all --format json--missing在项目未收敛时以退出码 1 结束apply --dry-run打印将会运行的命令而不执行apply --yes跳过确认提示适合无人值守场景交互终端下apply 会先弹出 compose projects: apply N change(s)? 确认若用户拒绝则记录compose projects: skippedsrc/system/compose.rs。聚合行为mise bootstrap plan会按依赖顺序把 Compose 项目排在 package、file、directory、system-service 资源之后聚合 apply 会在这些依赖完成后重新检查项目因此同一轮运行中才创建的 Compose 文件或 Docker 安装会被正确处理而无需执行期猜测若 Compose 项目的某个前置依赖在本轮发生了变化即使项目自身已收敛plan 也会将其升级为updateplan_with_dependency_change见 src/system/compose.rs。九、安全性设计要点profiles、services、oneshot中不允许空字符串、以-开头的值或 NUL 字节command/engine_command不允许空值或 NUL 字节src/system/compose.rs防止参数注入多个配置文件中出现冲突的同名 compose 声明会被拒绝并同时指出两个声明源src/system/compose.rs无法完成 inspection例如 Compose 命令缺失时计划动作记为Unknownapply 会拒绝执行不安全的变更提示先查看mise bootstrap plansrc/system/compose.rs处于stopped状态时若存在remove_orphans孤儿容器通过引擎命令rm --force id移除且 dry-run 也能在引擎尚未安装时正确打印这一步骤src/system/compose.rs。十、典型落地建议Compose 文件与.env分开管理Compose 文件走source从配置仓库同步.env用contenttemplate{{ secret(...) }}渲染权限设为0600。secret 值永远不会出现在 plan、dry-run、status 输出中。依赖写全depends_on至少包含 Docker 包与 Docker 服务两个条目并在[bootstrap.services.docker]中声明state running、enabled true保证守护进程就绪。用 plan 验证拼写显式依赖必须在规划阶段真实存在mise bootstrap plan能提前暴露拼写错误与校验失败如非法的project_name、services与absent的组合。破坏性选项显式化down_volumes与down_images只在state absent时生效且需要刻意开启避免误删数据。--only精确调试开发配置时用mise bootstrap --only packages,files,services,compose --dry-run缩小范围确认无误后再跑完整mise bootstrap --yes。延伸阅读原始文档docs/bootstrap/compose.md完整阶段顺序与其它 bootstrap 模块docs/bootstrap.md托管文件/目录的权限与原子写入细节docs/bootstrap/files.mdsecret 输入的声明与注入方式docs/bootstrap/secrets.md核心实现配置结构、inspection、收敛判定、命令构造与全部单测src/system/compose.rsCLI 命令定义bootstrap compose status/apply参数src/cli/bootstrap.rs【免费下载链接】misedev tools, env vars, task runner项目地址: https://gitcode.com/GitHub_Trending/mi/mise创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考