Komodo 容器部署实战：一份 Deployment 配置搞定 Docker 容器全生命周期管理

【免费下载链接】komodo🦎 a tool to build and deploy software on many servers 🦎项目地址: https://gitcode.com/gh_mirrors/komo/komodo

在 Komodo 的容器部署体系里，Deployment 资源是管理单个 Docker 容器的核心：你写一份声明式 TOML 配置，系统会自动把它翻译成 docker run 命令，并在目标服务器上执行。本文带你从第一份配置写起，覆盖字段速查、镜像来源、生命周期操作，一直到 Swarm 服务化部署与镜像自动更新。读完你能独立写出可运行的 Deployment，并讲清从 deploy 到 destroy 的完整执行链路。

别再手写 docker run 了

一条完整的 docker run 往往要串起 --name、--network、--restart、-e、-v、-p 等十几个参数，一行超过 200 字符并不稀奇。手写下这种命令，拼错一个参数前缀就要重新排查，复制给同事还可能漏掉环境变量，十几台服务器各写各的，配置迟早漂移。

Komodo 的思路是：你声明"容器长什么样"，命令的拼装交给系统。下面的表格直观展示 TOML 字段与最终执行的 docker 命令之间的对应关系：

执行链路分两段：触发部署后，Core 侧把 Deployment 配置序列化为执行请求；请求经由部署在目标服务器上的 Periphery agent 送达；Periphery 真正执行 docker 命令，并把日志与结果回传。

第一份 Deployment 配置（5 分钟上手）

最小可运行的配置长这样，可直接用于 komodo CLI 或 ResourceSync 的 TOML 清单：

[[deployment]] name = "my-app" [deployment.config] server = "server-prod" image.type = "Image" image.params.image = "nginx:1.27" network = "host" restart = "on-failure" environment = """ LOG_LEVEL = info """ volumes = """ /data/my-app:/var/www """

保存后对这条 Deployment 执行 Deploy，Komodo 会先在目标服务器拉取镜像，再用当前配置创建并启动容器。如果同名容器已经在跑，旧容器会被先停掉、删除，再按新配置重建——所以任何配置变更都要靠重新部署才生效。

另外记住两个名称字段：custom_name是本次配置指定的容器名，deployed_name记录的是上一次实际部署时用的名字。改容器名后重新部署，系统会自动匹配并接管旧容器，不用你手动清理。

配置字段速查表

补充说明，实现中还有几个文档没展开的默认值：

• termination_timeout默认 10 秒，即停止容器时的宽限时间；
• replicas默认 1，且只在 Swarm 模式下生效；
• swarm_id与server_id同时设置时，Swarm 部署模式优先。

像ports、volumes、environment、labels这类字段都支持多行书写，最终会被解析成结构化对象再拼装进 docker 命令，源码可见对应的反序列化逻辑。

镜像从哪里来

镜像来源只有两种，选其一即可：

拉取前 Komodo 会从镜像名推断 registry 域名：首段包含.时视为域名（例如ghcr.io/...），否则回退到docker.io，这个规则同样用于登录与拉取流程。

生命周期操作速查

⚠️ 关键区别：Stop / Start 只改变运行状态，不会应用任何配置变更——想让新配置生效，必须 Redeploy。另一个容易踩的点：恢复一个 paused 状态的容器，unpause 是唯一途径。

多服务场景下，BatchDeploy 支持通配符与正则模式匹配多条 Deployment 并行部署，还能按 tag 过滤范围，做滚动发布时很顺手。

进阶——Swarm 部署与镜像自动更新

把配置里的server换成swarm，Deployment 就进入 Swarm 模式：底层命令从docker run切换为docker service create，replicas字段此时生效，还可以给服务挂接 Swarm 的 configs 与 secrets。

[[deployment]] name = "my-svc" [deployment.config] swarm = "production-swarm" image.type = "Image" image.params.image = "ghcr.io/myorg/my-svc:latest" replicas = 3

镜像更新由两个字段分工：

• poll_for_updates = true：定期检查同 tag 镜像的 digest，发现新 digest 时只在 UI 显示更新指示，不碰容器；
• auto_update = true：发现新 digest 时自动触发 Redeploy，该字段会隐式启用轮询，两者无需同时开启。

一句话区分：前者"只提醒"，后者"自动拉新版"。

Swarm 模式下状态机还会多出Unhealthy状态，表示部分 task 未达期望状态；状态流转与更新指示都可以在下面这类监控视图里看到。

避坑清单

📌 四条最常见的问题：

• 改了 image 却只做了 Stop/Start，没有 Redeploy → 容器还是旧版本；
• 网络设为 host 后写了ports，映射不会生效，别误以为是配置错误；
• swarm和server同时设置时 Swarm 优先，部署位置可能和你预期不同；
• 私有镜像忘了配置 registry 账户，拉取阶段直接失败。

小结

• 声明式配置：一份 TOML 描述完整容器，替代手写 docker run；
• 生命周期闭环：deploy / start / stop / restart / pause / destroy 全量覆盖，还支持批量并行操作；
• 可观测：状态机、digest 轮询与告警，容器漂移一目了然；
• Swarm 就绪：同一份配置换个字段就能升级为多副本 service。

延伸阅读：

• 变量与 secret 插值：docsite/docs/configuration/variables.md
• Swarm 部署细节：docsite/docs/swarm.md
• Compose 多服务部署：docsite/docs/deploy/compose.md

【免费下载链接】komodo🦎 a tool to build and deploy software on many servers 🦎项目地址: https://gitcode.com/gh_mirrors/komo/komodo