portablectl attach 怎么把服务镜像接入本机启动流程

portablectl attach 不是“把镜像复制到某个目录”这么简单，它会把 portable service image 中匹配的 unit 文件接入主机的 systemd 搜索路径，并为服务单元添加 RootDirectory= 或 RootImage= 指向镜像。要让它随开机进入启用状态，再根据需要组合 --enable；要在接入后立即启动，则加上 --now。

systemd portablectl 官方文档：https://www.freedesktop.org/software/systemd/man/latest/portablectl.html

最稳妥的顺序是先用 inspect 看清镜像中的 unit，再用 attach 接入；最后用 is-attached 判断是只接入、已启用，还是已经有服务运行。本文不讨论 portable image 的构建，只讨论 attach 后它如何进入本机启动流程。

先确认 portable image 能提供什么

portable image 可以是包含 /usr/、/etc/ 等目录的文件树、Btrfs 子卷，或带文件系统分区的 raw 磁盘镜像。它除了文件系统树，还应包含 systemd unit 信息。不要一上来就执行 attach，先检查镜像识别结果和将要匹配的单元：

# 先读取镜像元数据和可匹配的 unit，不会把它接入主机
portablectl inspect /var/lib/portables/demo_1.2.raw

# 如果镜像中有多个服务族，只查看指定前缀对应的 unit
portablectl inspect /var/lib/portables/demo_1.2.raw demo

inspect 会展示镜像的 os-release 信息以及匹配到的 unit。它的价值在于把“镜像存在”和“镜像能提供可接入服务”分开：路径写对并不代表 attach 后一定会得到你预期的服务单元。

attach 实际会把哪些东西接到主机

执行 attach 后，主机侧的变化可以分成四类。首先，匹配的 .service、.socket、.target、.timer 和 .path 文件会被复制到 /etc/systemd/system.attached/；使用 --runtime 时则落在 /run/systemd/system.attached/。其次，服务单元会得到指向镜像的根目录或根镜像设置。再次，profile drop-in 会带来额外的安全和运行限制。最后，如果镜像不在搜索路径中，systemd 会在 /etc/portables/ 或 /run/portables/ 建立链接。

这些动作表达的是“让服务管理器看见并知道如何运行这些单元”，不是把镜像内容散开安装到主机根文件系统。默认情况下，attach 完成后会重载服务管理器；只有显式使用 --no-reload 才会跳过这一步。

默认前缀不合适时显式指定

不提供前缀时，portablectl 会根据镜像文件名推导匹配前缀：去掉 .raw 等后缀，并在第一个下划线处截断。例如 demo_1.2.raw 默认会寻找以 demo-、demo. 或 demo@ 开头的 unit。镜像版本号放在下划线后，正是为了让不同版本仍共享同一组服务前缀。

# 使用镜像名 demo_1.2.raw 推导 demo 前缀
portablectl attach /var/lib/portables/demo_1.2.raw

# 只接入名为 demo-api.service 等 demo-api 前缀的单元
portablectl attach /var/lib/portables/demo_1.2.raw demo-api

显式前缀会覆盖隐式推导。这个参数适合一个镜像包含多组 unit，或镜像文件名与 unit 命名没有采用同一前缀的情况。不要因为看到一个 unit 文件就假设它会被接入，前缀匹配是 attach 的筛选边界。

用参数决定“接入”“启用”还是“立即启动”

三个状态容易混在一起：attached 表示 unit 文件已经对主机服务管理器可见；enabled 表示至少一个关联 unit 已设置为启用；running 才表示至少一个关联服务当前正在运行。参数的组合可以这样理解：

需要“开机继续运行且现在就启动”时，可以同时使用 --enable --now。如果只想做一次性验证，可使用 --runtime --now，但要记住 runtime 只改变接入文件的持久性，不会把服务变成另一种 unit。

attach 后怎样判断已经进入启动流程

不要只看 attach 命令返回成功就结束判断。可以用 is-attached 查看 portable image 的聚合状态：

# 输出镜像当前是 detached、attached、enabled 还是 running
portablectl is-attached /var/lib/portables/demo_1.2.raw

# 只依赖退出码做脚本分支，减少对人类可读文本的耦合
portablectl --quiet is-attached /var/lib/portables/demo_1.2.raw

可能看到 detached、attached、enabled、running，以及带 -runtime 后缀的临时状态。--quiet 会抑制额外输出，但成功仍返回 0；脚本应保留失败分支，不要把任何非空输出都当成运行中。

升级和撤销：重新接入或 detach

镜像文件被替换后，可以用 reattach 让 systemd 重新读取它。版本文件名只要在第一个下划线前保持同名，portablectl 就可以按同一服务族做部分匹配。撤销时使用相同镜像名或路径，detach 会移除 unit 副本、drop-in 和搜索路径链接；如果还要停止或禁用服务，再按需加 --now 或 --enable。

# 镜像内容已经更新时，重新接入同一服务族
portablectl reattach /var/lib/portables/demo_1.3.raw

# 停止并撤销接入，避免留下仍指向旧镜像的 unit
portablectl detach --now /var/lib/portables/demo_1.3.raw

如果只是想让镜像在本次启动周期可见，优先考虑 --runtime；如果要让它成为主机长期管理的一部分，则使用默认持久 attach，并明确是否需要 --enable。这样可以把镜像生命周期、unit 可见性和服务运行状态分别管理。

常见问题

attach 成功后为什么服务没有启动？因为 attach 默认只接入 unit，不等于启用或立即启动。分别检查是否需要 --enable 和 --now，再查看 is-attached 状态。

为什么 inspect 能看到 unit，attach 后却没有？优先检查默认前缀是否与 unit 名称匹配；对多服务镜像直接在镜像路径后给出明确前缀，并避免把路径中的版本号误当作 unit 前缀。

portablectl attach 会不会把整个镜像安装到主机？不会。它把匹配的 unit 接入主机，并让服务在镜像文件系统上下文中运行；镜像本身仍作为 portable image 被引用。