不用 SSH 到处救火：用 Komodo 把多台 Docker 主机与 Compose 部署收进可审计控制面
一两台机器时，docker compose up -d 加 SSH 已经足够顺手；服务增加到多台 VPS、办公室小主机和云 VM 后，问题却不再是“怎么启动容器”。真正难维护的是：某个 Compose 项目究竟在哪台机器运行、谁在什么时候执行了重启、推送代码后要不要发布、环境变量散在哪个目录，以及故障发生时怎样取得可追溯的操作记录。
Komodo 是一个 GPL-3.0 开源的自托管部署控制面。它并不替换 Docker 或 Compose，而是把已有的 Docker 主机接入同一套控制面：中心端 Core 提供 Web UI 与 API；每台被管理主机运行 Periphery，实际执行容器、Compose Stack、日志和资源采集操作。对于不想把全部部署逻辑交给外部 SaaS、又不想持续在 SSH 历史里找答案的团队，这是一种介于“纯脚本”与“大型平台”之间的选择。
先判断：你缺的是编排器，还是操作上下文
Komodo 适合解决的是多主机上的部署可见性与变更治理，不应被理解为 Kubernetes 的直接替代。若你的服务需要弹性调度、跨节点服务发现、复杂网络策略和大规模多租户隔离，Kubernetes 仍是更匹配的运行时；若服务基本是若干 Compose 项目，且机器边界已经明确，先把“谁、在哪台机、以什么配置、何时变更”治理好，往往更实际。
它的核心模型有两层：
- Core：控制面，承载 UI、REST/WebSocket API、资源配置、自动化与变更审计。
- Periphery：安装在每台受管服务器的无状态 agent。它在本机执行 Docker 操作、收集系统利用率、读取容器日志，再与 Core 双向通信。
这样做的价值不是多一个面板，而是把原本隐含在个人终端中的上下文变为团队可检查的资源：一个 Stack 属于哪台 Server、使用哪些 Compose 文件、从哪个 Git 仓库获取、最近一次部署是谁触发的，均可以回到控制面追溯。
接入前先盘点已有 Compose 项目
迁移既有服务时，第一步不要急着复制 YAML。先在目标主机执行：
docker compose ls
这个列表里的 project name 很重要。Komodo 导入运行中的 Compose 项目时，会用 Compose 项目名做匹配；若 Stack 名称与原项目名不同，应在 Stack 配置中显式指定 project_name。否则控制面可能把同一组容器视为另一套资源，后续的启停、刷新和观察都会变得难以解释。
接下来确认运行目录、Compose 文件组合和 .env 的归属。许多生产项目不是单个 compose.yaml，而是基础文件叠加 compose.prod.yaml。Komodo 的 file_paths 对应 Compose 的多个 -f 文件；environment 则会写入 .env，并作为 --env-file 的输入。也就是说，导入时应复现原本的启动语义，而非为了接入平台重新手改一份简化 YAML。
下面是将 Git 中的 Compose 项目声明为 Stack 的简化结构。账号名、仓库和路径都需换成自己的实际值：
[[stack]] name = "orders-prod" [stack.config] server = "edge-vm-01" project_name = "orders" run_directory = "/opt/komodo/stacks/orders" file_paths = ["compose.yaml", "compose.prod.yaml"] git_account = "deploy-bot" repo = "example-org/infra-stacks" environment = """ LOG_LEVEL=info """
示例故意没有放入数据库密码、API token 等真实机密。变量与密钥应由 Komodo 的变量/secret 机制或外部密钥系统注入，不能因为“配置集中”就把生产凭据提交到 Git。
每台主机运行 Periphery，而不是把 Docker Socket 暴露出去
Komodo 官方为 Periphery 提供安装脚本，并推荐 systemd 方式。以具备相应权限的 Linux 主机为例，创建 Core 端的 onboarding key 后，可按官方脚本接入：
curl -sSL https://raw.githubusercontent.com/moghtech/komodo/main/scripts/setup-periphery.py \ | python3 - \ --core-address="https://" \ --connect-as="$(hostname)" \ --onboarding-key="O-REPLACE-WITH-REAL-KEY" sudo systemctl enable periphery
这里的 onboarding key 只用于初次连接；Periphery 的私钥保留在服务器上，后续通信会经过加密握手和公钥校验。仍要把 Core 地址、初始密钥和本机配置视为敏感运维信息：不要贴进工单评论、终端录屏或仓库。
若采用非 root 的用户级 systemd 服务，还必须处理两个经常被遗漏的条件：运行用户要有无需 sudo 操作 Docker 的权限，也必须对 Periphery 配置的工作根目录有写权限。为了避免用户退出登录后服务被系统回收，可启用 linger：
sudo loginctl enable-linger "$USER"
这并不降低权限风险。Docker group 在很多发行版上具有接近主机高权限的能力，因此应把“谁能够控制 Periphery”当作生产权限边界来设计，而不是把它当成普通监控 agent。
从手动发布到 Git 驱动的可控发布
Stack 可以从 UI 内容、服务器既有文件或 Git 仓库取得 Compose 定义。对已经用 Git 管理基础设施的团队，Git 模式最容易形成可复盘流程：合并变更后，Core 取得更新，再在指定 Server 的运行目录执行相同的 Compose 组合。
这里要区分三个看似相近的行为。poll_for_updates 负责检查并显示是否有更新；auto_update 在发现镜像 digest 变化时可以自动重新部署；Git webhook 则是在代码平台事件发生时触发指定 Stack 的动作。把三者都打开并不总是更自动化、更安全。对数据库迁移或需要人工确认的服务，更合理的策略通常是“检测 + 审核 + 明确 deploy”；对无状态、可快速回滚的边缘服务，才考虑更积极的自动更新。
还要把“镜像更新”和“配置更新”拆开看。镜像 digest 的变化只说明基础镜像可能有新版本，并不能证明新的 Compose 参数、迁移脚本或依赖服务已准备好；反过来，Git 中的 Compose 变更也不应因为镜像未变化而被忽略。实际流程可以把 Git webhook 作为配置变更的入口，把镜像轮询仅作为待处理信号，再由明确的发布动作将两者收敛。这样，当一次发布失败时，排查人员能先判断失败来自仓库版本、运行时镜像还是目标机环境，而不是面对一个没有上下文的“自动更新失败”。
在首次把生产 Stack 交给 webhook 前，建议选一个无状态的测试服务，连续验证三件事：同一 commit 的重复回调是否幂等；故意写错环境变量时是否保留足够的失败日志；回退到上一个 commit 后能否恢复健康。这个小演练能提前暴露目录权限、Compose 文件相对路径和镜像拉取权限等问题，也比在真正故障时临时登录服务器更容易留下可审计证据。
Komodo 的 GitHub/GitLab webhook 会校验相应签名或 token；Stack 监听器可执行 /deploy 与 /refresh。私有 Core 若需要接收公网 Git webhook，推荐只经反向代理开放 /listener 所需入口，不要为了一个回调把整个管理 UI 和 API 暴露到公网。还应为仓库回调配置独立 secret，并在上线前验证：错误签名是否被拒绝、重复推送是否会造成不期望的并发部署、失败时告警落在哪里。
用 CLI 把发布动作纳入受控脚本
UI 适合诊断和审计，自动化仍需要稳定的命令入口。Komodo 提供 CLI，官方 README 列出 deploy-stack、stop-stack、destroy-stack 等执行动作。安装 Rust 工具链及构建依赖后，可安装 CLI：
sudo apt install build-essential pkg-config libssl-dev cargo install komodo_cli
将 API 凭据放在受限权限的本地配置或 CI secret 中，而不是写进仓库。随后，发布脚本可以显式调用：
komodo execute deploy-stack orders-prod
无人值守任务需要跳过确认时，使用 --yes，但只应出现在已经受分支保护、审批或变更窗口约束的流水线中：
komodo --yes execute deploy-stack orders-prod
一个实用的做法是让 CI 先运行镜像构建、配置校验和健康检查，再在最后一步调用该命令；部署完成后通过 Core 的事件记录与服务日志回读结果。这样 CLI 不是另一条绕过 UI 的“快捷通道”，而是与审计面共享同一资源模型的执行接口。
上线前的边界检查表
把 Compose 接入控制面并不会自动带来可靠性。至少应逐项确认：每个 Stack 是否对齐原 Compose project name；工作目录是否可恢复；密钥是否从 Git 与日志中隔离；Core 是否有强认证与最小网络暴露；webhook 是否校验签名；容器健康检查和失败回滚由谁负责。尤其是 destroy-stack 这类破坏性操作，要按角色收紧权限，并在非生产环境先演练。
Komodo 最适合把“多台机器上已经能跑的 Compose 服务”变成可见、可复现、可审计的日常运维流程。它不会替你设计部署策略，却能让策略不再只存在于某位同事的 SSH 命令历史中。