You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
virt/docs/IMAGE_STARTUP_SCRIPTS.md

3.6 KiB

镜像首次启动脚本

管理员可在「云镜像模版」中点击对应镜像的「设置启动脚本」,为不同镜像保存不同的 Bash 脚本。超级管理员可保存,普通管理员只读。保存空字符串停用;最大 32 KiB UTF-8,Windows CRLF 换行在保存时转换为 LF。

生效范围

  • 仅新建云镜像实例的首次启动执行。引擎在准备该次创建的镜像副本时读取配置,将脚本封装进这个实例的 NoCloud seed;已经生成的 seed 不随目录设置变化。
  • 现有实例、普通重启、改密码、改主机名、换公网 IP 和加入/退出 VPC 不会重新领取镜像目录里的新脚本。
  • 本功能不在系统重装、救援 ISO 或用户 ISO 安装时注入脚本。
  • 脚本通过 /bin/bash 在来宾内以 root 身份执行。镜像需要预装并启用 cloud-init 和 Bash;依赖网络的命令还需要有效网络及软件源。它不依赖 QGA,也不会在面板或宿主机执行。
  • 脚本和设置只通过管理员接口提供,用户创建请求不能覆盖。脚本会写入来宾,来宾 root 可以读取,因此不要写入平台密钥或其他租户的凭据。

执行与排查

cloud-init 的 final 阶段通过 runcmd 调用面板生成的启动包装脚本。普通 runcmd 会在实例标识改变后重新运行,而现有密码和主机名设置会改变 NoCloud 的 instance-id,因此包装脚本在系统盘中使用独立、原子创建的 started 目录记录首次尝试。

首次尝试失败或中断也不会自动重跑任意管理员脚本。管理员确认现场状态后,可在来宾内人工处理;不要仅为重跑而清除标记。如果镜像是从已有实例制作的,应在制模板阶段清理 /var/lib/virt-cloud/startup/ 的运行记录,避免克隆继承已执行标记。

来宾内相关路径:

路径 用途
/var/lib/virt-cloud/startup.sh 封存的管理员脚本,root:root 0600
/var/lib/virt-cloud/startup-runner.sh 一次执行包装脚本,root:root 0700
/var/lib/virt-cloud/startup/started/ 已开始尝试的标记
/var/lib/virt-cloud/startup/output.log 本次脚本 stdout/stderr
/var/lib/virt-cloud/startup/exit-code 退出码;0 表示成功,非 0 表示失败,存在 started 但无退出码表示仍运行或被中断

示例脚本内容:

#!/bin/bash
set -e
mkdir -p /opt/example
printf '%s\n' '初始化完成' > /opt/example/initialized.txt

脚本运行不属于引擎创建完成条件:VM 创建成功不代表初始化脚本成功。脚本失败不会制造电源任务锁。本版结果仅保存在来宾,尚未增加面板脚本状态回报。

存储与并发

配置使用引擎现有加密镜像目录记录,不新增数据库表。保存携带镜像 created_at 和脚本 expected_revision;旧编辑页面不能覆盖另一管理员的修改或删除后重新导入的镜像。删除镜像同时移除脚本设置;普通镜像目录、导入任务及租户响应不携带脚本正文。

官方依据与验证边界

回归测试覆盖脚本保存、权限和版本冲突、创建派发、seed 改写、成功/失败/中断后的重复执行保护。模拟 libvirt 和本地包装脚本测试不能替代真实镜像的 cloud-init 验收;上线后应分别用实际支持的发行版检查脚本、网络和日志。