主机部署问题

如何解决自有主机显示离线？

服务器上确认下agent是否在线，如果是离线，则需要重启agent。附agent基础操作：

• 查看状态：

  /home/staragent/bin/staragentctl status

• 重启：

  /home/staragent/bin/staragentctl restart

• 卸载：

  /home/staragent/bin/staragentctl stop
  rm -rf /home/staragent
  rm /usr/sbin/staragent_sn

主机部署失败且没有失败的详情日志怎么办？

如果使用的是非阿里云ECS，确认下是否自有主机是通过镜像生成的，如果是建议先卸载agent，然后重新添加自有主机后重试。

主机组添加不了非阿里云ECS的自有主机怎么办？

非阿里云ECS的自有主机建议使用混合云托管模式，具体参考：https://help.aliyun.com/document_detail/201140.html。单击新建主机组，在弹出的自有主机·添加主机对话框中，将添加方式选择为混合云托管（将非阿里云机器注册为阿里云托管实例），然后选择服务授权和地域，即可在可添加的主机列表中查看并添加非阿里云ECS的自有主机。

创建主机组/构建集群报错或手动安装 Runner 报错

报错信息为实例 i-2ze99uh20nyrykgdobvb runner 安装失败!(3000005)。

目前 Flow 上创建主机组/私有构建集群支持通过 ECS 主机选择、自有主机安装两种方式，但对于同一台机器不可以在同一个云效组织中使用两种方式分别添加。

例如，你已经通过 ECS 主机选择的方式添加了主机 A，该主机无法再次通过自有主机方式添加进主机组。

• 只有将主机上的 Runner 卸载后，才可以更换添加方式，通过以下命令卸载 Runner 。

  #  停止指定的systemd服务。
  systemctl stop runner-{版本}-{租户名称}.service
  #  删除该服务的systemd配置文件。
  rm -rf /etc/systemd/system/runner-{版本}-{租户名称}.service
  #  删除与该租户相关的runner配置目录。
  rm -rf /root/yunxiao/{租户名称}/runner/config

• 部署命令可以在机器上手动执行成功，但在 Flow 流水线上执行失败。

  • 添加与命令相关的环境变量，例如：/source /root/.bash_profile; source /etc/profile。

  • 部署相关脚本使用绝对路径（例如/home/admin/app/deploy.sh），不要使用相对路径。

ECS镜像复制导致Runner 配置冲突，导致主机部署失败

在主机部署过程中，通过A机器的镜像复制了一台B机器，由于B机器复用了A机器的Runner的配置，从而导致了通道占用冲突:

• 部署目标错乱：本应部署到B机器的任务被错误下发至A机器。

• 根因分析：镜像复制后未重置Runner唯一标识（如注册信息），导致调度系统无法区分A/B机器。

• 关键影响：自动化流程中断，可能引发环境污染或服务重叠。

• 解决方案：

  说明

  如果采用镜像复制机器与Runner配置方式，建议在B机器上重新安装Runner时，务必确保A与B机器各自的Runner通道ID具有唯一性。

  # 在B机器上卸载Runner
  #查看 Runner 服务名称，通常 Runner 服务的名称为 runner-{版本}-{租户名称}.service
  ls -al /etc/systemd/system | grep runner
  systemctl stop runner-{版本}-{租户名称}.service
  rm -rf /etc/systemd/system/runner-{版本}-{租户名称}.service
  rm -rf /root/yunxiao/{租户名称}/runner/config
  # 删除B机器上与runner相关的目录及其下文件
  rm -rf /root/yunxiao/ 
  # 验证 Runner 是否已彻底清理
  ps -ef | grep runner

同一台 ECS 实例被添加到多个主机组导致部署失败或频繁断连怎么办？

同一台 ECS 实例被添加到多个主机组时，可能出现 Runner 离线、版本过旧或配置冲突，导致部署失败或 Runner 频繁断连。

快速恢复

1. 在服务器上查看 Runner 服务名称：

   ls -al /etc/systemd/system | grep runner

2. 重启对应的 Runner 服务：

   systemctl restart runner-{版本}-{租户名称}.service

彻底解决

如果重启后问题持续，建议卸载旧版 Runner 并安装最新版本（如 0.3.4）。操作步骤：

1. 停止 Runner 服务：

   systemctl stop runner-{版本}-{租户名称}.service

2. 删除 systemd 配置文件：

   rm -rf /etc/systemd/system/runner-{版本}-{租户名称}.service

3. 删除 Runner 配置目录：

   rm -rf /root/yunxiao

4. 在云效控制台重新安装最新版 Runner 插件。

流水线 Runner 问题排查方法

如何解决阿里云ECS提示deploy channel error或是离线？

• ECS上确认下云助手是否正常，重启下云助手，具体可以参考查看执行结果及修复常见问题。

• 如果云助手正常，确认下ECS的磁盘是否满了，如果是可以清理下磁盘。

主机部署之前运行正常，本次运行机器上的包不是最新或下载不到最新构建包怎么办？

根据提示日志检查服务器磁盘是否满了，如是请自行清理。

如果磁盘空间正常但仍然遇到制品包下载问题，按以下场景排查：

下载速度慢

制品包下载速度主要受服务器网络带宽和包大小影响。排查步骤：

1. 检查自建主机的带宽监控，确认带宽是否已打满。

2. 在目标服务器上直接执行 wget 命令测试下载速率，定位网络瓶颈：

   wget -O /dev/null {制品包下载URL}

3. 如带宽不足，建议增加服务器网络带宽。

MD5 校验失败（file md5 is incorrect）

此报错通常由以下原因导致：

• 其他流水线使用了相同的部署下载路径，导致文件被覆盖。

• 源码触发导致多条流水线并行运行，制品文件互相覆盖。

解决方案：

1. 更改部署下载路径，确保不同流水线使用独立的下载目录。

2. 检查流水线运行记录，确认是否存在并行运行的情况。

3. 在部署命令末尾添加删除旧包的命令，避免残留文件导致冲突：

   rm -f {部署路径}/{旧制品包文件名}

下载失败或权限不足

1. 检查磁盘空间是否充足。

2. 检查是否有多个部署单同时部署到同一台机器，导致文件互相覆盖。

3. 在目标机器上手动执行部署脚本中的 wget 命令，验证网络连通性和包下载是否正常：

   wget {制品包下载URL}

4. 若使用私有制品仓库，确认授权卡成员是否有下载权限。如权限不足，需在制品仓库控制台将该成员添加至对应仓库的授权列表。

部署脚本字符数限制

云效流水线部署脚本存在 2000 字符的长度限制。当 Python 部署或其他复杂脚本超过此限制时，勿直接在部署配置框中编写脚本，建议将脚本保存为 Shell 文件上传至代码库，然后在部署任务中通过执行该 Shell 脚本来完成部署。例如：

bash deploy.sh

怎么进行多任务回滚？

回滚是按照任务回滚的，如果配置了3个任务，那3个任务都需要分别回滚，建议您可以通过在部署历史的下拉菜单中选择切换回滚任务。

部署失败，服务没有启动起来怎么办？

直接在服务器上执行对应的命令调试下，确保自己的部署脚本没有问题。

1. 云效执行的部署逻辑是根据您部署配置中配置的命令去服务器上执行的，复制部署配置页面中配置的命令直接手动在服务器上执行，如果结果和云效执行的结果一样，需要你自行调试部署脚本，确认问题。比如：在服务器上新建一个sh文件，然后把云效上部署配置页面上的部署脚本框中的命令复制粘贴到新建的sh文件中，然后执行sh文件调试下，确保用户提供的脚本没有问题。

2. 如果在服务器上直接执行可以，在云效执行没启动，确认下脚本中是否使用了相对路径，将相对路径改成绝对路径后重试。

Docker 容器部署后无法访问

部署完成后如果 Docker 容器服务无法从外部访问，按以下步骤排查：

1. 确认 ECS 安全组已放行目标端口（如 80、443 等）。

2. 在服务器上检查端口监听及防火墙状态：

   # 检查端口监听
   netstat -ano | grep {端口号}
   # 检查防火墙状态
   systemctl status firewalld
   ufw status
   iptables -nvL

3. 对比本地与流水线构建镜像的 commit ID 及部署脚本是否一致，确认部署的是预期版本。

4. 在 ECS 上手动执行 docker run 命令验证服务可用性，区分是镜像问题还是环境问题。

docker-compose.yml 找不到

云效部署阶段不会自动同步代码库文件到目标 ECS。如果部署脚本中使用了 docker-compose，需确保 yml 文件已存在于目标机器上。解决方案：

• 手动上传 docker-compose.yml 文件至 ECS。

• 在流水线中增加步骤，先下载代码或制品到 ECS，再执行 docker-compose up。

• 改用 docker run 命令直接启动容器，无需依赖 compose 文件。

手动部署正常但云效部署失败

如果 Spring Boot 等应用在服务器上手动部署可以正常启动，但通过云效流水线部署时失败，检查以下内容：

1. 查看服务器上云效生成的临时部署脚本 /tmp/rdc_deploy_command_*.sh，确认应用在该脚本的执行上下文中是否能正常启动。

2. 重点排查以下差异：

   • 环境变量差异：手动执行时 Shell 会加载 .bash_profile 等配置文件，云效部署脚本的执行上下文可能缺少这些环境变量。建议在部署脚本开头添加 source /etc/profile && source ~/.bash_profile 加载环境变量。

   • 工作目录差异：确认脚本中引用的文件路径在云效执行上下文中是否正确。

   • 相对路径问题：脚本中使用的相对路径需改为绝对路径，避免因工作目录不同导致文件找不到。

Windows主机部署失败提示deploy channel error怎么办？

目前云效不支持添加Windows主机到云效。可以尝试以下两个替代方案：

1. 可以通过一台Linux服务器中转，在部署脚本中编写命令，通过在Linux上执行命令跟Windows交互。

2. 可以将构建产物通过云效的OSS上传组件传到你自己的OSS上，后续Windows主机从OSS下载包部署。

主机部署报错环境变量not a valid identifier怎么办？

+ export pause_strategy=FirstBatchPause
+ pause_strategy=FirstBatchPause
+ export rootMixActionCode=ENTER
+ rootMixActionCode=ENTER
+ export TIMESTAMP=1607427603743
+ TIMESTAMP=1607427603743
+ export appId=0
+ appId=0
+ export execute_user=root
+ execute_user=root
+ export ENGINE_PIPELINE_CREATOR_ALIYUN_PK=1218858987274713
+ ENGINE_PIPELINE_CREATOR_ALIYUN_PK=1218858987274713
+ export triggerMode=1
+ triggerMode=1
+ export abc=哈 哈哈哈
+ abc=哈
/tmp/rdc_deploy_command_1607427664248_globalParams.sh: line 16: export: '哈哈哈': not a valid identifier
[ERROR] 环境变量中含有特殊字符，请按照文档排查
https://thoughts.aliyun.com/sharespace/5e86a419546fd9001aee81f2/docs/5fbca20e550406001d388abc
------打印环境变量------
]
[2020-12-08 19:41:09]执行结果编码:[
exit 0
]
DeployCommand execution completed

因为环境变量中包含了特殊字符，需要通过以下操作对流水线进行配置才可正常使用环境变量：

1. 主机部署任务中，勾选 变量进行编码。

2. 在部署脚本中，把您需要使用的所有环境变量进行 Base 64 解码。比如要使用PIPELINE_ID的环境变量，在部署脚本最前面添加一行export PIPELINE_ID=$(echo $PIPELINE_ID | base64 -d)。

   + export PIPELINE_NAME=6aKE5Y+RYmFzZTY05rWL6K+V5rWB5rC057q/
   + PIPELINE_NAME=6aKE5Y+RYmFzZTY05rWL6K+V5rWB5rC057q/
   + export BUILD_NUMBER=Ng==
   + BUILD_NUMBER=Ng==
   + export FLOW_ENGINE_ENCODE_GLOBAL_PARAM=dHJ1ZQ==
   + FLOW_ENGINE_ENCODE_GLOBAL_PARAM=dHJ1ZQ==
   + export DATETIME=MjAyMC0xMi0wOC0yMC0yMi01MA==
   + DATETIME=MjAyMC0xMi0wOC0yMC0yMi01MA==
   + export parentMixFlowInstId=MA==
   + parentMixFlowInstId=MA==
   + export GIT_BRANCH=null
   + GIT_BRANCH=null
   + export CI_COMMIT_SHA=MmZhNThkMTk1OWFjYjcwZDQzNDZjZDBlM2E2YzhhYzQyNmE2MTE4NQ==
   + CI_COMMIT_SHA=MmZhNThkMTk1OWFjYjcwZDQzNDZjZDBlM2E2YzhhYzQyNmE2MTE4NQ==
   + export machine_group_id=MTE5MDA=
   + machine_group_id=MTE5MDA=
   + export ENGINE_PIPELINE_INST_ID=MjExNzYxMw==
   + ENGINE_PIPELINE_INST_ID=MjExNzYxMw==
   ------打印环境变量------
   哈 哈哈哈
   ]
   [2020-12-08 20:23:46]执行结果编码:[
   exit 0
   ]
   DeployCommand execution completed

主机部署报错 User.NoPermission怎么办？

在部署详情中，显示具体的部署错误码，不同的错误码对应的错误说明和错误排查如下：

User.NoPermission，用户没有调用某个API的权限。请检查部署组的服务连接是否正常。

主机部署报错 MachineGroupNotHaveMachine 怎么办？

该报错表示部署组中没有可用机器，导致部署任务无法下发到目标主机。

排查步骤：

1. 在云效控制台进入对应流水线的部署任务配置，检查关联的部署组是否已添加机器。如果部署组为空，需先添加目标主机。

2. 如果部署组中已有机器，检查机器是否处于在线状态。机器离线时，登录目标服务器排查 Runner 服务状态并重启。

3. 确认部署组中存在可用的在线机器后，重新触发部署任务。

主机部署服务已成功启动，但流水线仍持续显示“部署中”

主机部署脚本持续显示“部署中”通常由两个原因导致：返回码未正确传递或子进程未正常退出。

脚本示例demo：https://atomgit.com/flow-example/spring-boot/blob/master/deploy.sh

以下是具体排查步骤与解决方案：

1. 返回码验证

   • 在脚本关键步骤（如服务启动命令）后添加 echo $?，确保返回码为0。若返回非0值，需检查对应命令的异常处理逻辑。

   • 脚本末尾需显式声明 exit 0，避免隐式依赖最后一条命令的返回码。

2. 子进程管理

   • 若使用 nohup 启动后台进程（如Java服务），需确认采用规范写法：nohup java -jar ${JAR_NAME} > ${JAVA_OUT} 2>&1 &。末尾的 & 表示后台运行，避免阻塞主进程。

   • 检查其他可能创建子进程的命令（如 systemd 或 docker run -d），确保其正确分离进程上下文。

3. 超时机制强化

   • 若服务启动耗时较长，可在脚本中增加轮询检测（如HTTP健康检查），待服务就绪后再退出脚本，避免依赖固定超时阈值。

4. Windows .bat 脚本导致流水线假死

   在 Windows 环境下，如果部署配置中调用了 .bat 脚本（如 service-start.bat），可能因脚本以阻塞方式启动进程，导致 PowerShell 持续等待子进程结束，造成流水线假死。

   解决方案：

   • 将部署指令封装在脚本中，通过云效配置启动，确保进程以后台方式运行，不占用当前控制台。

   • 排查方法：减少执行脚本数量，逐个命令测试，定位具体卡住的命令，检查该命令是否启动了未正常退出的子进程。

示例修正逻辑：

# 启动服务并捕获返回码
nohup java -jar app.jar > log.txt 2>&1 &
echo "Service started with exit code: $?"
# 显式声明脚本成功退出
exit 0

若上述优化后问题仍然存在，则需检查当前阶段的流水线配置相关参数是否存在问题，或检查云效主机Runner Service状态是否异常。

主机部署阶段，清理工作区任务卡住怎么办？

如果您是手动安装的Docker服务，建议您按照以下流程检查服务状态并进行相关操作。

# 查看docker状态
systemctl status docker
###输出关键信息：
# Active: active (running)：服务正在运行
# Active: inactive (dead)：服务未启动
# Loaded: loaded (...)：服务已正确加载配置
#  查看Docker客户端和服务器的各种信息，包括镜像、容器、数据卷等详情。
docker ps
#  重启docker服务
sudo systemctl restart docker