云效Runner的作用与接入方式

云效 Flow 的主机部署，本质上是把流水线构建出的制品，经由主机组中的 Runner 送达目标主机。理解这一链路，比记住每个按钮更重要。Runner 是部署执行的代理，它必须归属某个主机组才能接收任务；主机组则决定部署任务的目标范围。因此，接入 Runner、配置主机组、再在流水线中设置部署任务，是三个环环相扣的环节。

接入环节的前提是目标主机已经具备可用条件。主机操作系统需为 Linux、Windows 或 macOS 之一，Linux 需支持 Systemd、Upstart 或 System V 之一，Windows 需支持 Windows service。主机还需能访问云效流水线服务端的公网地址；若采用“手动安装 Runner”方式，还需能访问相应的服务域名。如果目标是位于支持内网端点区域的阿里云 ECS，并采用“阿里云 ECS”方式接入，主机可以不具备公网访问能力。但若主机要加入构建集群，仍需公网访问，因为构建时可能拉取公网镜像。

接入时，先在流水线 Flow 的全局设置中进入“主机组管理”，新建主机组，再在主机组详情中添加主机，选择“手动安装 Runner”。页面生成的安装命令包含版本、Token 和 AccessKey 等参数，并有过期时间，应尽快在目标主机上执行，过期后重新生成即可。执行成功后，主机组列表中该主机的 Runner 状态应显示为正常。若显示离线，优先检查公网访问和命令是否过期。另外需要注意，Runner 的添加方式不可互换，通过镜像创建的 ECS 也可能带入旧的 Runner 进程和安装目录，此时应先清理旧 Runner，再重新安装。两台主机的 config.yml 也不应直接复制后同时启动，否则两个 Runner 会争抢任务，导致不可预期的部署结果。

在流水线中，部署阶段添加“主机部署”任务后，还需逐项配置目标主机组、制品来源以及部署目录与部署动作。每次只调整一项设置，便于出错时定位。其中最常见的问题是制品路径不一致：构建产出的真实路径与部署脚本中引用的路径若不同，部署就会因文件不存在而失败。因此修改前，应先在构建日志中确认制品的实际输出位置。

部署失败后，排查顺序大致如下。先看部署状态，再进入部署日志定位失败步骤。若日志中没有任何执行记录，多半是 Runner 不在线或主机无法访问服务端；若命令执行报错，可在目标主机上手动执行同样的命令，观察真实输出。修正后可在卡片视图直接重试，无需重新运行整条流水线。成功的版本则保留在部署历史中，新版本出现问题时，可选择之前的成功版本执行回滚，并确认回滚部署状态为已成功，同时检查应用能否正常启动。

建议先用一台测试主机跑通完整流程，确认部署状态、日志与回滚均符合预期，再逐步扩展到更多主机。