# 镜像首次启动脚本 管理员可在「云镜像模版」中点击对应镜像的「设置启动脚本」,为不同镜像保存不同的 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 但无退出码表示仍运行或被中断 | 示例脚本内容: ```bash #!/bin/bash set -e mkdir -p /opt/example printf '%s\n' '初始化完成' > /opt/example/initialized.txt ``` 脚本运行不属于引擎创建完成条件:VM 创建成功不代表初始化脚本成功。脚本失败不会制造电源任务锁。本版结果仅保存在来宾,尚未增加面板脚本状态回报。 ## 存储与并发 配置使用引擎现有加密镜像目录记录,不新增数据库表。保存携带镜像 `created_at` 和脚本 `expected_revision`;旧编辑页面不能覆盖另一管理员的修改或删除后重新导入的镜像。删除镜像同时移除脚本设置;普通镜像目录、导入任务及租户响应不携带脚本正文。 ## 官方依据与验证边界 - [cloud-init 启动命令](https://docs.cloud-init.io/en/latest/reference/yaml_examples/boot_cmds.html):`runcmd` 首次启动执行,`bootcmd` 默认每次启动执行。 - [user-data script](https://docs.cloud-init.io/en/latest/explanation/format/user-data-script.html):用户脚本在 final 阶段运行。 回归测试覆盖脚本保存、权限和版本冲突、创建派发、seed 改写、成功/失败/中断后的重复执行保护。模拟 libvirt 和本地包装脚本测试不能替代真实镜像的 cloud-init 验收;上线后应分别用实际支持的发行版检查脚本、网络和日志。