阿里云效 Flow 初学者如何将制品部署到 ECS 主机并排查部署失败

内容总结生成中

你看见的，不仅是一个总结

阿里云云效 Flow 的主机部署，核心是把流水线构建出的制品，通过主机组里的 Runner 发布到一台 ECS 或可访问公网的主机上。本文要完成的任务是：接入一台目标主机、在流水线中添加主机部署任务、配置部署参数，并在部署失败时能看懂状态、查看日志，必要时用部署历史回滚。

适用环境：你已经有一台可用的 ECS 或公网主机，主机能正常登录；流水线的构建阶段已经配置好，能够产出制品。本文只覆盖云效 Flow 的主机部署路径，不涉及容器或 Kubernetes 等其他部署方式，也不涉及价格和账号开通。

准备事项：

• 确认主机操作系统为 Linux、Windows 或 macOS 之一。Linux 需支持 Systemd、Upstart 或 System V 之一，Windows 需支持 Windows service。
• 确认主机能够访问云效流水线服务端的公网地址。若使用“手动安装 Runner”方式，主机需能访问 devops-build-new.aliyuncs.com 与 gray-devops-build.aliyuncs.com。
• 如果主机是阿里云 ECS，且位于北京、杭州、张家口、深圳、上海、青岛、呼和浩特、新加坡、河源、广州、乌兰察布、成都等支持内网端点的区域，并使用“阿里云 ECS”方式接入，主机本身可以不具备公网访问能力。但若将主机加入构建集群，仍需要公网访问，因为构建时可能拉取公网镜像。
• 在目标主机上准备一个有 root 或管理员权限的登录账号，用于执行安装命令。

第一步：新建主机组并接入新主机

主机组是部署任务的目标范围，Runner 必须归属于某个主机组才能接收部署任务。

1. 进入流水线 Flow 首页，单击“全局设置”，再进入“主机组管理”。
2. 单击“新建主机组”，填写主机组名称后保存。
3. 在主机组详情页单击“添加新主机”。
4. 添加方式选择“手动安装 Runner”，操作系统类型选择 Linux（其他系统按页面提示操作）。

页面会生成一条安装命令。这条命令包含 Runner 版本、Token、AccessKey 等参数，并且有过期时间限制。请复制后尽快在目标主机上执行，不要长时间停留在页面上。如果命令已过期，关闭对话框重新生成即可，不要使用旧命令。

在目标主机终端中粘贴并执行该命令。执行成功后，回到页面单击“我知道了”。随后在主机组列表中，该主机的 Runner 状态应为正常。

预期结果：主机组中出现该主机，状态为正常。如果显示离线或安装失败，先检查主机能否访问公网地址，再检查命令是否已过期。

如果同一台 ECS 需要加入多个主机组，无需重复安装 Runner。把它添加到第二个主机组时，状态会短暂显示为“安装中”，随后恢复正常。

常见接入问题

• 同一台机器已通过其他方式接入，无法再次添加：Runner 的添加方式不可互换。需要先在主机上卸载 Runner（停止对应 systemd 服务、删除服务配置文件与该租户相关的 Runner 配置目录），再用新的方式重新接入。
• 通过镜像创建的 ECS 安装 Runner 异常：自定义镜像或共享镜像会把旧的 Runner 进程和安装目录一并带入新服务器，重新安装时会冲突。应先清理旧 Runner，再重新安装。
• 两台主机的 config.yml 内容相同：不要把一台主机上的 config.yml 复制到另一台并启动服务，否则两个 Runner 会同时拉取任务，导致不可预期的部署行为。

第二步：向流水线添加主机部署任务

1. 进入流水线 Flow，打开你要配置的流水线并进入编排页面。
2. 在部署阶段中单击添加任务，打开任务组面板。
3. 在左侧分类中选择与主机部署相关的任务类型，在右侧选择“主机部署”任务，并添加到阶段中。

预期结果：部署阶段中出现一个主机部署任务节点。此时它还未配置参数，直接运行会失败。

第三步：配置部署任务参数

打开刚添加的主机部署任务，按界面要求填写以下内容。每一项只需确认一个设置，不要同时修改多个参数，便于出错时定位。

1. 目标主机组：选择第一步中创建的主机组。
2. 制品来源：选择上游构建阶段产出的制品，确保路径与构建输出一致。
3. 部署目录与部署动作：填写制品在目标主机上的存放位置，并按需要配置部署脚本或启动命令。
4. 保存配置，并运行一次流水线。

这里最容易出错的是制品路径与部署脚本中的路径不一致。例如构建产出为 target/app.jar，部署脚本却去找 app.jar 所在的其他目录，就会在部署阶段报文件不存在。修改前先在构建日志中确认制品的真实输出路径。

第四步：查看部署详情与使用部署历史回滚

流水线运行后，部署会在运行详情页中显示。

1. 在流水线运行详情页，找到部署阶段的主机部署任务。
2. 单击右侧的“部署详情”按钮，进入部署详情页。
3. 在页面中查看当前部署状态和日志。

如何读懂部署状态

部署失败后的排查顺序

1. 先看状态是否为“已失败”，再进入部署日志。日志中通常能看到失败的步骤和报错信息。
2. 确认是连接问题还是执行问题。如果日志中没有任何执行记录，多半是 Runner 未在线或主机无法访问服务端，回到主机组管理检查 Runner 状态。
3. 确认是脚本问题还是路径问题。若日志显示命令执行失败，在目标主机上手动执行同样的命令，观察真实报错。
4. 修正后重试。在卡片视图上直接重试发起部署，无需重新运行整条流水线。

如果主机部署失败且没有详细日志，先确认主机是否为通过镜像生成的旧 Runner。若是，建议先卸载旧 Runner，再重新添加主机后重试。

使用部署历史回滚

部署成功的版本会保留在部署历史中。当新版本出现问题时，可以在部署历史中选择之前的成功版本，执行回滚，把主机上的应用恢复到该版本。回滚后建议立即检查应用是否正常启动，并查看回滚部署的日志确认状态为“已成功”。

常见报错与进一步调整

• Runner 显示离线：检查主机网络和进程状态。Linux 上可通过 systemd 查看 Runner 服务是否运行，必要时重启服务。
• 安装命令执行失败：多数是命令已过期或主机无法访问公网地址，重新生成命令并确认网络。
• 部署一直处于待部署：检查主机组是否绑定到了部署任务上，以及 Runner 是否在线。
• 部署日志报文件不存在：核对构建产出路径与部署任务中的制品路径、部署脚本路径是否一致。
• 同一台机器无法切换接入方式：先卸载 Runner，再用新的方式接入。

调整建议：先用一台测试主机跑通完整流程，确认部署状态、日志和回滚都符合预期，再扩展到更多主机。每次只修改一项配置，修改后重新运行一次，便于快速定位问题来源。