说实话第一次遇到这个场景时很容易懵明明把user-data文件里的主机名改了、静态 IP 也改了甚至runcmd脚本都换了一轮重启虚拟机之后却像什么都没发生一样hostname还是旧值脚本也没有执行痕迹。最让人困惑的是user-data文件确实已经改过了虚拟机也确实重新启动了为什么 cloud-init 完全不买账这篇文章就来把这个坑彻底讲明白。我会从 cloud-init 的运行机制入手分析“修改 user-data 不重跑”的根本原因再给出完整的排障步骤、可复制的命令以及生产环境下推荐的操作习惯。无论你是在 VMware Workstation 里跑 Rocky 10 测试机还是在 vSphere 环境里维护模板虚拟机这篇文章都可以直接作为一份排障参考。1. 问题背景与核心概念1.1 踩坑现场user-data 改了却不重跑先描述一下最常见的踩坑现场。你在 VMware 里创建了一台 Rocky 10 虚拟机安装系统时挂载了一个名为seed.iso的种子盘里面放着user-data和meta-data两个文件用于 cloud-init 自动配置主机名、创建用户、设置静态 IP 等。第一次开机一切正常Rocky 10 按照user-data完成了初始化。过了一段时间你想调整配置把主机名从rocky10-dev改成rocky10-prod或者想在runcmd里追加一条命令。于是你生成了一份新的seed.iso挂载到虚拟机光驱里重启虚拟机结果发现主机名依然是旧值user-data里新增的脚本没有执行新写入的文件不存在查看/var/log/cloud-init.log日志里几乎没有新增内容。这就是典型的“user-data 改了虚拟机完全不重跑”问题。1.2 cloud-init 与 user-data 到底负责什么要定位问题先要把概念理清楚。cloud-init 是 Linux 发行版里非常常见的“云初始化工具”主要作用是在虚拟机或云主机“第一次启动”时完成基础配置。它读取数据源DataSource提供的配置内容然后调用各个模块完成主机名设置、用户创建、SSH 密钥注入、网络配置、软件包安装等操作。user-data是 cloud-init 最核心的输入文件之一。它本质上是一个用户自定义配置的聚合载体常见的格式有#cloud-configYAML 格式声明主机名、用户、写文件、执行命令等#!/bin/bash直接放一段 shell 脚本#include组合多个文件#cloud-boothook每次启动都会执行的钩子脚本。大多数人在 Rocky 10 虚拟机里使用的都是#cloud-config格式。它写起来直观可读性好也最容易排查。不过要注意一个关键点user-data的全名已经说得很明白了——它叫“用户数据”不叫“用户脚本”也不叫“每次启动执行的任务”。cloud-init 的设计目标里user-data的核心场景是“首次引导”而不是“持续配置管理”。1.3 NoCloud 数据源下的三个关键文件在 VMware Workstation 这类本地虚拟机环境里最常用的 cloud-init 数据源是 NoCloud。为了模拟云平台的 metadata 服务NoCloud 允许你把配置放到一个卷标为CIDATA的 ISO 镜像或目录里。一套完整的 NoCloud 数据源通常包含三个文件文件作用是否必填user-data用户自定义配置cloud-config 或 shell 脚本通常必填meta-data实例元数据如 instance-id、主机名部分场景可为空network-config网络配置V2 格式的 netplan 或旧版格式可选很多新手踩坑的第一个点就在这里文件命名不对、路径不对、ISO 卷标不对导致 cloud-init 根本没读到你的user-data。但本文要讨论的场景是“第一次能读到后来改了却不再生效”所以比“根本读不到”又多了一层机制上的原因。2. 环境准备与版本说明2.1 本次排障的实验环境由于 Rocky Linux 10 仍在快速迭代中不同镜像自带的 cloud-init 版本可能存在差异下面以一套常见的测试环境为例宿主机VMware Workstation Pro版本以你本机为准虚拟机系统Rocky Linux 10最小化安装或 Server 安装均可cloud-init镜像内置版本可通过cloud-init --version查看数据源NoCloud通过挂载CIDATAISO 模拟客户端工具mkisofs/genisoimage或cloud-localds来自cloud-image-utils包。我这里不会把某个具体版本号写死因为软件版本更新很快。重点是掌握排障思路同样的方法适用于 cloud-init 22.x、23.x、24.x 等主流版本。2.2 确认 cloud-init 是否已安装并正常接管在开始排障前先确认基础前提。# 查看 cloud-init 版本 cloud-init --version # 查看 cloud-init 当前状态 cloud-init status # 查看 cloud-init 主日志 sudo tail -n 100 /var/log/cloud-init.logcloud-init status的输出有几种status: donecloud-init 已完成初始化status: running正在运行中status: disabledcloud-init 被禁用常见于/etc/cloud/cloud.cfg.d/下有禁用配置status: error初始化过程出现错误。如果你执行cloud-init status后发现是disabled那改动user-data自然没有意义因为 cloud-init 整个服务都没参与系统初始化。这种情况下要先排查为什么被禁用常见原因包括镜像里写入了disable_ec2_metadata: true、cloud-init: disabled或者/etc/cloud/cloud.cfg里配置了datasource_list: []。如果状态是done说明 cloud-init 已经正常执行过一轮。接下来进入根因分析。3. 根因拆解为什么 user-data 不会“改了就跑”3.1 实例 ID判读“首次启动”的钥匙这是全文最核心的概念也直接回答文章标题的问题cloud-init 是否执行 user-data不是看你是否修改了 user-data而是看它认为当前是否是一台“新实例”。cloud-init 判断“新实例”的依据是 instance-id。这个 ID 由数据源提供在 NoCloud 数据源中instance-id 来自meta-data文件里的instance-id字段如果meta-data没有提供cloud-init 会使用默认值iid-local01在 AWS、OpenStack 等云平台中instance-id 通常由平台自动生成。cloud-init 在首次运行时会把当前实例的 instance-id 写入本地状态目录。后续每次开机它会先获取数据源里的 instance-id再和本地记录的 instance-id 做比较两者相同说明是同一台实例cloud-init 认为初始化已完成直接跳过user-data的重新执行两者不同说明这是一台“新实例”cloud-init 会重新读取并执行user-data。问题就在这里。你修改的是user-data文件但meta-data里的instance-id没变。在 cloud-init 看来“人还是那个人只是换了张纸条”自然不需要重新执行。3.2 cloud-init 的执行阶段cloud-init 不是一个“一个命令干到底”的工具它内部的执行流程大致分为几个阶段local 阶段寻找数据源生成实例 ID准备网络配置init 阶段解析user-data、vendor-data应用网络配置执行 early 模块config 阶段运行cloud-config中的各类配置模块final 阶段运行最终模块比如runcmd里注册的部分命令。在 systemd 环境下对应的是多个 cloud-init 服务单元例如cloud-init-local.service、cloud-init.service、cloud-config.service、cloud-final.service。你可以通过下面命令查看服务单元是否都已执行systemctl status cloud-init*或者查看开机启动时间线systemd-analyze blame | grep cloud理解了执行阶段就会更清楚user-data并不是一个被“反复读取”的文件而是在首次启动的固定阶段被消费一次之后结果被固化到本地状态里。这也是“改了不重跑”的另一个层面原因。3.3 修改 user-data 不等于触发重新初始化把上面的机制翻译成大白话cloud-init 是一个“一次性初始化器”不是“持续配置同步器”修改user-data文件本身不会让 cloud-init 觉得需要重新工作重新挂载 ISO、重新开机也不会让 cloud-init 觉得这是新实例只有 instance-id 变化或者本地状态被清除cloud-init 才会重新跑流程。这个设计在云平台里是合理的因为云平台一般不会让同一台虚拟机反复消费初始化配置。但在本地虚拟机测试场景里很容易造成误解。顺手改个user-data就想让它重新生效是完全不符合 cloud-init 设计预期的。3.4 缓存与持久化状态的作用cloud-init 会把运行结果持久化到本地目录最常见的路径是/var/lib/cloud/。可以查看这个目录的结构sudo ls -l /var/lib/cloud/ sudo ls -l /var/lib/cloud/instance/ sudo cat /var/lib/cloud/instance/instance-id不同版本路径可能略有差异但整体结构大同小异。/var/lib/cloud/instance/通常会保存instance-id 文件本次实例缓存的数据例如user-data.txt、cloud-config.txt等各个模块运行后的状态、结果、种子数据。这些缓存的作用是让 cloud-init 在后续启动时快速判断“我已经干过活了”并且提供日志和调试信息。也就是说即使你重新挂载了新的user-dataISO由于本地状态目录里还留着旧的 instance-idcloud-init 根本不会去深入读取你新挂载的 user-data 内容。它可能只是在日志里记录了一句“already ran”或类似信息就结束了。4. 排障实操让 user-data 重新跑起来既然已经定位到根因接下来就是具体操作。下面每一步都给出命令和预期结果。4.1 第一步判断 cloud-init 当前状态先明确当前机器的 cloud-init 状态cloud-init status --wait如果输出status: done说明初始化流程已经走完。如果输出status: error首要任务不是重跑user-data而是先解决当前的错误。继续确认 instance-idcat /var/lib/cloud/instance/instance-id再对比数据源里meta-data的instance-id。在 NoCloud 场景下可以挂载 ISO 后查看文件内容例如mkdir -p /tmp/cidata sudo mount /dev/cdrom /tmp/cidata cat /tmp/cidata/meta-data如果这两个 ID 一致那么基本可以断定cloud-init 认为当前实例已经初始化过不再消费新的user-data。4.2 第二步校验 user-data 语法在重跑之前先确保新的user-data本身没有语法问题否则重跑也是白跑。推荐使用 cloud-init 自带的 schema 校验工具# 针对单个文件校验 cloud-init schema --config-file user-data.yaml # 针对系统内已缓存的 user-data 校验 sudo cloud-init schema --system如果输出类似Valid cloud-config: user-data.yaml说明格式没问题。如果报错会提示具体的 YAML 路径或类型错误需要先修好再继续。另外要注意user-data第一行必须是#cloud-config不能有 BOM 头也不能在前面多加空行。有些 Windows 编辑器会偷偷加入 BOM导致 cloud-init 把它当成未知格式。4.3 第三步清理缓存并手动重跑这是本地测试环境最常用的手段本质是让 cloud-init 忘掉旧状态。方案一使用cloud-init clean清理状态并重启。sudo cloud-init clean --logs sudo rebootcloud-init clean会清除/var/lib/cloud下的实例缓存让 cloud-init 在下次启动时认为这是一台新实例从而重新读取user-data。--logs参数会同时清理旧日志便于观察全新一轮的执行过程。如果你希望清理后立即重启可以使用sudo cloud-init clean --reboot不同版本参数可能略有差异可以先用下面命令确认cloud-init clean --help方案二手动删除状态目录。sudo rm -rf /var/lib/cloud sudo reboot这个方法比较“暴力”在某些版本里也能达到效果但不够优雅不推荐在日常操作里使用。因为/var/lib/cloud里除了实例状态还有一些 seed 数据、缓存文件直接删除可能导致后续排查信息缺失。方案三手动按阶段执行 cloud-init 模块。这个方法适合不想重启机器的场景。但要注意手动执行模块的顺序很重要不能乱来。# 重新从数据源读取配置 sudo cloud-init init --local sudo cloud-init init # 执行 cloud-config 模块 sudo cloud-init modules -m config # 执行 final 模块 sudo cloud-init modules -m final这种方式的缺点是如果 user-data 里有幂等性较差的命令重复执行可能产生副作用。所以更推荐在测试机上用cloud-init clean --reboot来完整走一遍启动流程。4.4 第四步模拟“新实例”验证首次启动效果如果cloud-init clean后重跑成功说明问题已经解决。但如果你希望更贴近“从模板克隆出一台新虚拟机再初始化”的真实场景建议不要直接在一台已经跑过初始化任务的虚拟机上操作而是采用快照或克隆的方式。推荐做法在虚拟机完成首次初始化后制作一个“干净初始状态”的快照之后想验证新的user-data时恢复到该快照再挂载新的seed.iso以快照后的新状态启动虚拟机此时 cloud-init 会完整执行一轮初始化。这样既不会污染现有环境也能真正模拟首次启动。另外还有一个测试技巧修改meta-data里的instance-id为一个从未使用过的值。由于 instance-id 变化cloud-init 会认为这是一台新实例从而重新消费user-data。但要注意instance-id 变化可能带来额外行为比如 SSH host key 重新生成、主机名重新设置等。所以这个技巧更适合实验环境不建议在生产虚拟机里随意改动。4.5 VMware 虚拟机注入 user-data 的完整流程这里以 VMware Workstation 为例梳理一套完整的 NoCloud 数据源生成和挂载流程方便对照排查。先在宿主机上创建一个目录存放三个文件mkdir -p cidata创建user-data#cloud-config hostname: rocky10-dev manage_etc_hosts: true users: - name: admin sudo: ALL(ALL) NOPASSWD:ALL shell: /bin/bash ssh_authorized_keys: - ssh-rsa AAAAB3NzaC1yc2E... your-public-key write_files: - path: /etc/motd content: Welcome to Rocky 10 runcmd: - echo cloud-init runcmd executed /tmp/cloud-init-test.txt创建meta-datainstance-id: iid-rocky10-001 local-hostname: rocky10-dev创建network-config可选用于静态 IP 等网络配置version: 2 ethernets: ens192: dhcp4: true然后生成 ISO# 方法一使用 mkisofs / genisoimage mkisofs -o seed.iso -V CIDATA -J -R cidata/ # 方法二使用 cloud-localds来自 cloud-image-utils cloud-localds seed.iso user-data.yaml如果你使用cloud-localds它默认会生成一个meta-data。需要自定义network-config时可以参考工具的帮助文档这里不再展开。生成seed.iso后在 VMware 虚拟机设置里把该 ISO 挂载到 CD/DVD 光驱开机即可。注意 VMware 的 CD/DVD 设置里要勾选“启动时连接”。5. 常见问题与根因对照表问题现象常见原因解决思路修改 user-data 后重启主机名不变instance-id 未变化cloud-init 认为不是新实例清理/var/lib/cloud状态或修改 meta-data 中的 instance-iduser-data 语法错误重跑后部分配置丢失YAML 缩进错误或第一行缺失#cloud-config使用cloud-init schema --config-file校验重新挂载 ISO 后 cloud-init 没有读取新文件本地缓存了旧实例状态优先于新数据源执行sudo cloud-init clean --reboot日志中看不到 user-data 处理记录实例 ID 相同cloud-init 提前跳过查看cloud-init status和/var/lib/cloud/instance/runcmd命令在重启后没执行runcmd只在首次初始化时执行一次需要重复执行的命令放到 systemd 服务或 croncloud-init 状态为 disabledcloud.cfg 或内核参数禁用了 cloud-init检查/etc/cloud/cloud.cfg.d/和/proc/cmdline挂载的 ISO 无法被 NoCloud 识别卷标不是CIDATA或文件名大小写不对重新生成 ISO确保卷标为CIDATAcloud-init clean 执行失败cloud-init 服务仍在运行先systemctl stop cloud-init*再 clean6. 工程建议与最佳实践6.1 区分初始化工具与配置管理工具这是消解“为什么不重跑”困惑最重要的一点。user-data是初始化阶段的输入数据不是配置管理系统的声明式状态。如果你需要“每次开机都执行某个脚本”正确的工具是 systemd service、cron、Ansible、SaltStack 等而不是user-data里的runcmd。user-data最适合做的是首次创建虚拟机时的主机名、用户、SSH 密钥注入初始化时安装指定软件包写入特定业务配置文件在模板克隆场景下完成差异化配置。想清楚这一层你就不会再用“改配置 → 重启 → 看效果”的运维习惯去对待user-data了。6.2 修改和验证 user-data 的推荐流程建议把user-data当成代码来管理每次修改都走一遍验证流程。推荐顺序在编辑器中完成修改使用cloud-init schema --config-file user-data.yaml校验语法如果是针对“全新虚拟机”的配置先在克隆机或快照恢复后的虚拟机上验证验证通过后再批量使用生产环境使用前保留当前虚拟机快照或备份。特别是涉及网络配置时不要在生产机上直接重跑user-data。如果network-config写错可能导致虚拟机断网、失联。在 VMware 环境里操作还可以接受在远程机房或云平台上失联代价就很大了。6.3 生产环境操作红线下面几条是容易踩雷的高风险操作务必注意。不要随意在生产虚拟机上执行rm -rf /var/lib/cloud后重启。这个操作会清空 cloud-init 的运行状态可能导致 SSH host key 重新生成、hostname 意外修改等连锁反应不要在生产机上直接修改instance-id来触发重新初始化。instance-id 是虚拟机身份的组成部分随意变化可能影响监控、授权等系统涉及网络、用户、SSH 等敏感配置时先在克隆机和快照环境验证生产环境变更前必须先做好快照或备份确保可以快速回滚所有 cloud-init 相关操作尽量使用最小权限用户避免直接用 root 操作。7. 排障速查清单最后整理一份速查清单遇到类似问题可以直接对照执行。检查 cloud-init 是否启用cloud-init status --wait确认当前 instance-idcat /var/lib/cloud/instance/instance-id对比数据源 meta-data 中的 instance-idcat /tmp/cidata/meta-data校验 user-data 语法cloud-init schema --config-file user-data.yaml查看 cloud-init 日志sudo tail -n 200 /var/log/cloud-init.log journalctl -u cloud-init* --since today清理状态并重跑sudo cloud-init clean --logs sudo reboot验证是否重新执行cloud-init status ls -l /var/lib/cloud/instance/如果仍不生效检查数据源识别sudo cloud-init init --local --debug这套流程走下来绝大多数“改了 user-data 不重跑”的问题都能定位到具体环节。实际操作时优先在测试虚拟机里验证完整流程形成自己的排障模板。