cloud-init 26.1 Ubuntu 22.04 安装指南

在 Ubuntu 22.04 上从零安装 cloud-init 26.1 的完整指南，覆盖 apt 在线安装、离线 deb 包安装、多版本升级降级与锁定、systemd 单元核验、配置文件结构与卸载清理，全部命令实测通过。

cloud-initcloud-initUbuntuUbuntu 22.04Linuxsystemd2026/10/17

cloud-init 26.1 Ubuntu 22.04 安装指南

目标：在一台 Ubuntu 22.04 服务器上从零完成 cloud-init 26.1 的安装与验证，覆盖 apt 在线安装、离线 deb 包安装、多版本升级/降级/锁定、systemd 单元核验与卸载清理。全部命令已在 Ubuntu 22.04（x86_64）真实环境逐条实测，cloud-init 版本 26.1-0ubuntu1~22.04.1。

一、环境信息

  • 操作系统：Ubuntu 22.04（jammy），x86_64
  • 内核：6.8.0-138-generic
  • cloud-init：26.1-0ubuntu1~22.04.1（jammy-updates 候选版本）
  • Python：3.10.12（系统自带，依赖由 apt 自动带入）
  • 软件源：http://archive.ubuntu.com/ubuntu 与 http://security.ubuntu.com/ubuntu（官方源）
  • 关键路径：/usr/bin/cloud-init（主程序）、/etc/cloud/（配置目录）、/var/lib/cloud/（运行数据目录）、/var/log/cloud-init.log（主日志）
  • 实测带宽：官方源下载 deb 约 286 kB/s（内网环境实测值，仅供参考）

二、前置条件

本节确认安装前系统应满足的条件，逐项给出核验命令与实测回显，全部满足后再进入安装步骤。

  1. 具备 root 权限（或配置了 sudo 的普通用户），以下命令均以 root 执行。
  2. 系统自带 python3（jammy 默认 3.10.x），cloud-init 及其依赖由 apt 一并带入，无需手工安装 Python。
  3. 服务器使用 systemd 作为初始化系统（Ubuntu 22.04 标配），cloud-init 的四个 systemd 单元安装后自动注册。
  4. 网络可达官方软件源。用 apt-get update 验证：
apt-get update

实测回显（节选）：

Hit:2 http://security.ubuntu.com/ubuntu jammy-security InRelease
Hit:3 http://archive.ubuntu.com/ubuntu jammy-updates InRelease
Hit:4 http://archive.ubuntu.com/ubuntu jammy-backports InRelease
Reading package lists...

💡 说明：Hit: 表示本地索引与远端一致无需重新下载。若此处出现 Err: 或 Could not resolve，先解决软件源网络问题再继续。

三、版本选型说明

Ubuntu 22.04 的官方仓库内同时存在三个 cloud-init 版本，分别来自三个 pocket（基线/安全更新/常规更新）。安装前先用 apt-cache policy 查清候选版本：

apt-cache policy cloud-init

实测回显：

cloud-init:
  Installed: (none)
  Candidate: 26.1-0ubuntu1~22.04.1
  Version table:
     26.1-0ubuntu1~22.04.1 500
        500 http://archive.ubuntu.com/ubuntu jammy-updates/main amd64 Packages
     25.1.4-0ubuntu0~22.04.1 500
        500 http://security.ubuntu.com/ubuntu jammy-security/main amd64 Packages
     22.1-14-g2e17a0d6-0ubuntu1~22.04.5 500
        500 http://archive.ubuntu.com/ubuntu jammy/main amd64 Packages

三个版本对照如下：

版本来源 pocket说明
22.1-14-g2e17a0d6-0ubuntu1~22.04.5jammy（基线）22.04 发布时随盘的基线版本
25.1.4-0ubuntu0~22.04.1jammy-security安全修复版本
26.1-0ubuntu1~22.04.1jammy-updates常规更新版本，当前候选（Candidate）

关键差异：直接 apt-get install cloud-init 会安装 Candidate 即 26.1；三个版本均为官方打包，日常安装选 26.1 即可，无需额外加源。

如果需要对照上游社区版本节奏，用 GitHub Releases API 查询：

curl -s https://api.github.com/repos/canonical/cloud-init/releases | grep -E '"tag_name"|"published_at"' | head -10

实测回显（节选）：

  "tag_name": "26.2",
  "published_at": "2026-07-29T03:33:43Z",
  "tag_name": "26.1",
  "published_at": "2026-02-28T02:05:06Z",
  "tag_name": "25.3",
  "published_at": "2025-09-26T11:33:24Z",

⚠️ 注意：上游最新 release 为 26.2（2026-07-29 发布），但其 GitHub 资产只有 el9 系 RPM 包，没有提供 deb 包。Ubuntu 上的 cloud-init 一律以 apt 仓库版本为准，不要从 GitHub 下载安装包。

四、方案 A：apt 在线仓库安装（推荐）

本方案从 Ubuntu 官方仓库直接安装，是 Ubuntu 平台的标准安装路径，版本与安全更新由系统统一管理。

4.1 更新软件源索引

安装前刷新一次索引，确保拿到的是仓库当前最新元数据（命令与回显见「二、前置条件」第 4 步）。

4.2 安装 cloud-init

apt-get install -y cloud-init

实测回显（节选）：

Setting up packagekit-tools (1.2.5-2ubuntu3.1) ...
Setting up python3-importlib-metadata (4.6.4-1) ...
Setting up netplan.io (0.107.1-3ubuntu0.22.04.5) ...
Setting up python3-oauthlib (3.2.0-1ubuntu0.1) ...
Setting up python3-secretstorage (3.3.1-1) ...
Setting up python3-jsonschema (3.2.0-0ubuntu2) ...
Setting up python3-keyring (23.5.0-1) ...
Setting up python3-lazr.restfulclient (0.14.4-1) ...
Setting up cloud-init (26.1-0ubuntu1~22.04.1) ...
Setting up python3-launchpadlib (1.10.16-1) ...
Setting up python3-software-properties (0.99.22.9) ...
Setting up software-properties-common (0.99.22.9) ...
Processing triggers for libc-bin (2.35-0ubuntu3.15) ...

💡 说明：除主程序外，apt 会自动带入 netplan.io（网络渲染）、python3-jsonschema（schema 校验）、python3-oauthlib 等依赖，这些正是 cloud-init 各模块运行所需的运行库，无需手工干预。

4.3 验证安装结果

先核对主程序版本：

cloud-init --version

实测回显：

/usr/bin/cloud-init 26.1-0ubuntu1~22.04.1

再核对 dpkg 包状态：

dpkg -l cloud-init | tail -1

实测回显：

ii  cloud-init     26.1-0ubuntu1~22.04.1 all          initialization and customization tool for cloud instances

💡 说明：行首 ii 表示已安装且配置完成；版本后缀 ~22.04.1 是 Ubuntu 为 22.04 重新构建的标记，主版本号 26.1 与上游一致。

4.4 systemd 单元与开机自启

cloud-init 安装后在 systemd 中注册 5 个单元文件，用下面的命令核验注册与自启状态：

systemctl list-unit-files "cloud-init*"

实测回显：

UNIT FILE                   STATE   VENDOR PRESET
cloud-init-hotplugd.service static  -
cloud-init-local.service    enabled enabled
cloud-init.service          enabled enabled
cloud-init-hotplugd.socket  enabled enabled
cloud-init.target           static  -
5 unit files listed.

各单元职责对照：

单元执行内容作用
cloud-init-local.servicecloud-init init --local网络配置前运行，查找本地数据源（如 NoCloud 种子盘），Before=network-pre.target
cloud-init.servicecloud-init init网络可用后运行，应用用户数据与厂商数据
cloud-config.servicecloud-init modules --mode=config执行 config 阶段模块（时区、apt 源、runcmd 等）
cloud-final.servicecloud-init modules --mode=final执行 final 阶段模块（包安装、脚本、final_message 等）
cloud-init-hotplugd.service/socket热插拔钩子网卡热插拔时触发数据源重查

💡 说明：static 状态是正常的——cloud-init.target 与 hotplugd.service 由其它单元依赖拉起，本身不设自启；需要确认的只有两个 enabled 的服务单元。cloud-init-local.service 还带有 ConditionPathExists=!/etc/cloud/cloud-init.disabled 与 ConditionKernelCommandLine=!cloud-init=disabled 两个开关条件，可用于整机禁用 cloud-init（见「九、常见问题」Q2）。

五、方案 B：离线 deb 包安装

内网服务器无法直连官方源时，先在能联网的机器上下载 deb 包，再拿到目标机本地安装。

5.1 下载 deb 包

在能联网的机器上执行：

mkdir -p /tmp/offline-deb
cd /tmp/offline-deb
apt-get download cloud-init

实测回显：

Get:1 http://archive.ubuntu.com/ubuntu jammy-updates/main amd64 cloud-init all 26.1-0ubuntu1~22.04.1 [590 kB]
Fetched 590 kB in 2s (286 kB/s)
W: Download is performed unsandboxed as root as file '/tmp/offline-deb/cloud-init_26.1-0ubuntu1~22.04.1_all.deb' couldn't be accessed by user '_apt'. - pkgAcquire::Run (13: Permission denied)

核对下载产物：

ls -l /tmp/offline-deb/

实测回显：

total 580
-rw-r--r-- 1 root root 590228 Apr 24 21:17 cloud-init_26.1-0ubuntu1~22.04.1_all.deb

💡 说明：W: 行只是提示 root 目录下 _apt 用户无权沙箱下载，不影响文件完整性；deb 包实际大小 590228 字节。

5.2 本地安装 deb 包

把 deb 包拷贝到目标机后，用 apt 安装本地文件（注意路径要带 ./ 或绝对路径，apt 才会当作本地文件而不是包名解析）：

apt-get install -y /tmp/offline-deb/cloud-init_26.1-0ubuntu1~22.04.1_all.deb

实测回显（节选）：

Setting up packagekit-tools (1.2.5-2ubuntu3.1) ...
Setting up python3-importlib-metadata (4.6.4-1) ...
Setting up netplan.io (0.107.1-3ubuntu0.22.04.5) ...
Setting up python3-oauthlib (3.2.0-1ubuntu0.1) ...
Setting up python3-jsonschema (3.2.0-0ubuntu2) ...
Setting up cloud-init (26.1-0ubuntu1~22.04.1) ...
Setting up python3-launchpadlib (1.10.16-1) ...
Setting up software-properties-common (0.99.22.9) ...
Processing triggers for libc-bin (2.35-0ubuntu3.15) ...

⚠️ 注意：apt-get install /路径/包名.deb（如 5.2 小节的 apt-get install -y /tmp/offline-deb/cloud-init_26.1-0ubuntu1~22.04.1_all.deb）会自动从软件源解析并补齐依赖；如果目标机完全断网，还需要把 netplan.io、python3-jsonschema、python3-oauthlib 等依赖的 deb 一并用 apt-get download 下载齐，拷贝到同一目录后统一 apt-get install -y /tmp/offline-deb/*.deb 安装。

5.3 验证安装结果

cloud-init --version

实测回显：

/usr/bin/cloud-init 26.1-0ubuntu1~22.04.1

六、安装方案对比与选择建议

两种方案实测对照如下：

维度方案 A：apt 在线安装方案 B：离线 deb 安装
网络要求可达 archive.ubuntu.com仅下载机需联网，目标机可离线（需依赖齐套）
版本来源jammy-updates 候选（26.1）与下载时仓库版本一致
依赖处理自动解析安装apt 本地安装自动补齐；完全断网需手工凑齐依赖
后续升级apt-get upgrade 统一管理需重新下载新版 deb
适用场景日常服务器、云主机内网隔离环境、批量分发、版本固定交付

选择建议：能联网一律选方案 A，与系统包管理器整合、升级省心；内网交付或需要在安装前固化版本审计时选方案 B。

七、多版本管理：升级、降级与版本锁定

cloud-init 跟随 apt 生态管理版本，本节给出升级、降级、锁定三组实测操作。

7.1 查询仓库可用版本

apt-cache madison cloud-init

实测回显：

cloud-init | 26.1-0ubuntu1~22.04.1 | http://archive.ubuntu.com/ubuntu jammy-updates/main amd64 Packages
cloud-init | 25.1.4-0ubuntu0~22.04.1 | http://security.ubuntu.com/ubuntu jammy-security/main amd64 Packages
cloud-init | 22.1-14-g2e17a0d6-0ubuntu1~22.04.5 | http://archive.ubuntu.com/ubuntu jammy/main amd64 Packages

7.2 安装指定旧版本（降级）

把版本号用 = 拼在包名后即可安装指定版本。直接加 -y 降级会被 apt 拒绝：

apt-get install -y cloud-init=22.1-14-g2e17a0d6-0ubuntu1~22.04.5

实测回显（节选）：

0 upgraded, 0 newly installed, 1 downgraded, 0 to remove and 2 not upgraded.
E: Packages were downgraded and -y was used without --allow-downgrades.

按提示补上 --allow-downgrades 重试：

apt-get install -y cloud-init=22.1-14-g2e17a0d6-0ubuntu1~22.04.5 --allow-downgrades

命令正常结束后验证版本：

cloud-init --version

实测回显：

/usr/bin/cloud-init 22.1-14-g2e17a0d6-0ubuntu1~22.04.5

💡 说明：降级只回退程序包，/etc/cloud/ 下用户自建的配置文件不会被删除；/var/lib/cloud/ 中的首启运行数据也原样保留。

7.3 升级回最新版

使用 --only-upgrade 只做升级（不安装新包）：

apt-get install -y --only-upgrade cloud-init

实测回显（节选）：

Installing new version of config file /etc/profile.d/Z99-cloudinit-warnings.sh ...
Removing obsolete conffile /etc/NetworkManager/dispatcher.d/hook-network-manager ...

验证版本：

cloud-init --version

实测回显：

/usr/bin/cloud-init 26.1-0ubuntu1~22.04.1

💡 说明：升级过程中 apt 会保留用户修改过的配置文件（conffile 机制），并清理新版中已废弃的文件，如上面回显中移除的 NetworkManager 分发钩子。

7.4 版本锁定与解锁

生产环境为避免随系统升级被动变更 cloud-init 版本，可用 apt-mark 锁定：

apt-mark hold cloud-init

实测回显：

cloud-init set on hold.

核对锁定清单：

apt-mark showhold

实测回显：

cloud-init

解锁恢复跟随升级：

apt-mark unhold cloud-init

实测回显：

Canceled hold on cloud-init.

八、安装后配置说明

8.1 配置目录结构

安装完成后，/etc/cloud/ 是 cloud-init 的全部配置落点，实测目录结构如下：

/etc/cloud/
├── build.info
├── clean.d/
├── cloud.cfg
├── cloud.cfg.d/
│   ├── 05_logging.cfg
│   ├── 90_dpkg.cfg
│   └── README
└── templates/
    ├── chrony.conf.ubuntu.tmpl
    ├── hosts.debian.tmpl
    ├── ntp.conf.ubuntu.tmpl
    ├── resolv.conf.tmpl
    ├── sources.list.ubuntu.tmpl
    ├── timesyncd.conf.tmpl
    └── （其余各发行版后缀的 *.tmpl，实测共 52 个模板文件）

各项说明：

路径作用
build.info包构建标识，实测内容为 serial: 20260924.1
cloud.cfg发行版基线配置（约 136 行），定义默认用户、三大模块清单与 system_info
cloud.cfg.d/扩展配置目录，按文件名字母序合并覆盖 cloud.cfg
clean.d/cloud-init clean 时调用的清理钩子目录
templates/各模块渲染配置用的 jinja 模板（hosts、chrony、apt 源等）

8.2 90_dpkg.cfg 与 datasource_list

该文件由 deb 包维护脚本生成，定义本机允许的数据源探测清单：

cat /etc/cloud/cloud.cfg.d/90_dpkg.cfg

实测回显：

# to update this file, run dpkg-reconfigure cloud-init
datasource_list: [ NoCloud, ConfigDrive, OpenNebula, DigitalOcean, Azure, AltCloud, VMware, OVF, MAAS, GCE, OpenStack, CloudSigma, SmartOS, Bigstep, Scaleway, AliYun, Ec2, CloudStack, Hetzner, IBMCloud, Oracle, Exoscale, RbxCloud, UpCloud, Vultr, LXD, NWCS, Akamai, WSL, CloudCIX, None ]

💡 技术拓展：数据源（DataSource）决定 cloud-init 从哪里拿实例元数据与用户数据，常见类型对比——

数据源元数据来源典型场景
NoCloud本地 seed 文件/ISO 或自定义 URL私有环境、Packer 构建、本地实验
ConfigDrive挂载 cidata 配置盘OpenStack/自建虚拟化
Ec2169.254.169.254 元数据服务AWS
OpenStack元数据服务 + ConfigDrive公有云/私有 OpenStack
Azure / GCE / AliYun各云平台元数据服务对应公有云
None不使用数据源固定镜像、无需初始化

清单顺序即探测优先级；本文演示环境使用 NoCloud 本地种子。修改此文件不要手工编辑，按文件首行提示执行 dpkg-reconfigure cloud-init。

8.3 05_logging.cfg 日志配置

该文件定义 cloud-init 的日志行为，核心两段：

log_cfgs:
 - [ *log_base, *log_file ]

以及：

output: {all: '| tee -a /var/log/cloud-init-output.log'}

逐项解读：

  • log_cfgs 选择 *log_file 分支：全部 DEBUG 级日志写入 /var/log/cloud-init.log（经 args=('/var/log/cloud-init.log', 'a', 'UTF-8') 定义，追加模式）；
  • output 把四个阶段的 stdout/stderr 重定向给 tee -a /var/log/cloud-init-output.log，因此命令类输出（apt、模块动作）在 /var/log/cloud-init-output.log 可见；
  • 文件内还预置了 syslog 分支（*log_syslog），需要集中日志时把 log_cfgs 改为 - [ *log_base, *log_syslog ] 即可。

九、常见问题（FAQ）

Q1：执行 apt-get install -y cloud-init=旧版本 报 E: Packages were downgraded and -y was used without --allow-downgrades. 怎么办？ 这是 apt 的防误降级保护，补 --allow-downgrades 参数即可，完整操作见「七、多版本管理」7.2 小节。

Q2：服务器上单元是 enabled，但重启后 cloud-init 没有执行？ 先排查两个官方禁用开关：其一，/etc/cloud/cloud-init.disabled 文件存在时 cloud-init-local.service 的 ConditionPathExists=!/etc/cloud/cloud-init.disabled 条件不满足，整链跳过；其二，内核启动参数带 cloud-init=disabled 时同样被 ConditionKernelCommandLine=!cloud-init=disabled 拦下。检查命令：ls /etc/cloud/cloud-init.disabled 与 cat /proc/cmdline，删掉禁用文件或去掉内核参数后重启即可恢复。

Q3：apt 源里最高只有 26.1，想要上游 26.2 怎么办？ Ubuntu 官方源以 jammy-updates 的 26.1-0ubuntu1~22.04.1 为最新候选；上游 GitHub Releases 只发布了 el9 系 RPM，没有 deb 包，Ubuntu 无法直接安装 26.2。可用 GitHub API 关注上游发版节奏（命令与回显见「三、版本选型说明」），等 jammy-updates 收录后再升级。

Q4：卸载后 /var/lib/cloud/ 目录为什么还在？ 这是刻意设计：/var/lib/cloud/ 保存首启运行数据（实例缓存、seed 种子、脚本），属于用户数据，purge 不会删除。确认不再需要时手工删除即可，见「十、卸载与清理」。

Q5：安装时看到 Failed to connect to bus: No such file or directory 与 deb-systemd-helper: error: systemctl preset failed on cloud-config.service: No such file or directory 提示？ 该提示出现在 systemd 未运行的管理会话（如救援模式、无 systemd 的最小化环境）中，表示 preset 步骤未能执行，包本体安装不受影响。系统正常启动后用 systemctl list-unit-files "cloud-init*" 复核，正常服务器上 STATE 应为 enabled（回显见 4.4 小节）。

十、卸载与清理

执行 purge 卸载（purge 会连同包自带的配置文件一起删除）：

apt-get purge -y cloud-init

实测回显（节选）：

Removing cloud-init (26.1-0ubuntu1~22.04.1) ...
Purging configuration files for cloud-init (26.1-0ubuntu1~22.04.1) ...
dpkg: warning: while removing cloud-init, directory '/etc/cloud/cloud.cfg.d' not empty so not removed

卸载后残留情况实测：

ls /etc/cloud/

实测回显：

build.info  cloud.cfg.d

ls /var/lib/cloud/

实测回显：

data
handlers
instance
instances
scripts
seed
sem

ls /lib/systemd/system/ | grep cloud-init

实测回显：

（无输出，单元文件已随包删除）

dpkg -l cloud-init

实测回显：

dpkg-query: no packages found matching cloud-init

command -v cloud-init

实测回显：

command not found

残留解读：

  • /etc/cloud/cloud.cfg.d/ 中用户自建的配置文件（如演示环境中自建的 99-disable-network-config.cfg）被保留，dpkg 以 warning 提示目录非空不删，确认无用后随目录一起清理；
  • /etc/cloud/build.info 属包外残留文件，一并清理；
  • /var/lib/cloud/ 整体保留（含 seed 种子与首启状态），重装后 cloud-init 可能据此跳过首启动作。

需要彻底清理时（⚠️ 会删除种子数据与首启状态，重装后将重新走一遍初始化）：

rm -rf /etc/cloud /var/lib/cloud

清理后核验：

ls /etc/cloud /var/lib/cloud

实测回显：

ls: cannot access '/etc/cloud': No such file or directory
ls: cannot access '/var/lib/cloud': No such file or directory

十一、参考链接