DEBUG.WIKI
京东云;让 AI 进入真实业务;零售 · 物流 · 客服 · 硬件;查看方案 →
ZgoCloud:多地区部署,按需选节点;日本、美国、香港、德国
Evoxt;最高 6.0GHz CPU;高频云服务器 · 免费每周备份;查看配置 →

systemctl unmask 后仍报 Unit is masked:检查实际 unit 文件

systemctl unmask 后仍被屏蔽时,查 unit 的实际路径、空文件或 /dev/null 链接,再区分管理员屏蔽、软件包策略与自建配置损坏。

执行 systemctl unmask kiosk.service 没有报错,但再次启用服务仍提示 unit 被屏蔽。如果错误明确指向 /lib/systemd/system/kiosk.service 或 /usr/lib/systemd/system/kiosk.service,先检查这个实际文件,不要继续反复 unmask 或重启机器。

systemd 会将指向 /dev/null 的 unit 文件视为 masked,零字节 unit 文件也会进入这个状态。它表示配置不能被激活,与“服务没有设置开机启动”或“进程启动后退出”不同。本文针对 systemd 的系统级服务;用户服务应在对应用户管理器中另行检查。

先定位屏蔽发生在哪一层

以下为只读示例,服务名须替换为实际名称:

systemctl status kiosk.service
systemctl show kiosk.service -p LoadState -p UnitFileState -p FragmentPath

结合错误、状态和文件路径判断。FragmentPath 可以帮助定位已识别的配置文件,但某些未加载或屏蔽状态下可能为空,不能把空输出解释为没有文件。

继续查看故障机器上的候选路径:

ls -l /etc/systemd/system/kiosk.service \
  /run/systemd/system/kiosk.service \
  /usr/lib/systemd/system/kiosk.service \
  /lib/systemd/system/kiosk.service

部分路径不存在是正常情况,发行版目录布局也可能使 /lib 与 /usr/lib 指向同一处。看清符号链接的目标和普通文件大小,不要因为两个路径都出现就认定有两份独立服务。还要查看错误所指的实际路径;生成器或其他加载目录中的配置,也不能只凭这四个位置排除。

若文件大小为零,可能是安装、写入或配置管理留下的空文件;若链接到 /dev/null,还需查它是谁提供的。仅看到 masked 不能证明有人执行过 systemctl mask,更不能确定某次升级就是原因。

管理员创建的屏蔽,与软件包提供的屏蔽不同

普通 systemctl mask 在 /etc/systemd/system/ 下创建屏蔽,带 --runtime 时使用 /run/systemd/system/。相应的 unmask 是撤销这类管理配置,不能指望它修改软件包目录中的 unit。

已确认 /etc 中的屏蔽属于本次要撤销的设置,且取消屏蔽符合服务管理要求时,可以使用:

sudo systemctl unmask kiosk.service

运行期屏蔽则要核对原操作范围,用对应的 --runtime 管理。先保存原状态和屏蔽的来源;取消屏蔽后服务可能又被依赖、定时器或其他入口触发,不能将它视为没有影响的纯查看动作。

如果实际 masked 文件在软件包目录,这条命令可能没有任何可撤销的管理员屏蔽,返回成功也不表示底层配置已经可用。此时应核对包归属、安装版本、升级记录和包提供的正确服务名。

软件包可能有意屏蔽旧的兼容服务,把职责移到其他原生 unit;也可能存在损坏文件或部署工具写入失败。前一种应使用当前版本支持的入口,后一种按已核对的包修复或配置恢复流程处理。不要直接删除 vendor unit 再复制一份旧配置,避免下次更新覆盖,或同时启动新旧服务。

自建服务应恢复可信配置,而不是填入任意内容

如果确实是自己的独立服务,且已经排除同名软件包及生成配置的冲突,应从版本管理或备份恢复完整 unit,并放在系统级本地管理目录,例如 /etc/systemd/system/。恢复时保留执行用户、工作目录、依赖、环境、权限与安装关系;仅写入几行非空内容,只能改变加载结果,不能保证业务配置正确。

不适合通过 drop-in 给一个 masked 的空主文件补启动命令:主配置本身尚未正常加载。也不要用另一个同名 unit 强行覆盖软件包的有意屏蔽,除非已审查该版本服务关系及升级影响。

更改磁盘上的 unit 后,让管理器重新加载:

sudo systemctl daemon-reload

这会重新加载 unit 配置及依赖关系,不等于重启业务进程。先检查加载状态与配置内容;确认启动影响、必要备份及维护窗口后,再按原服务管理流程启动和设置开机策略。enable 与 start 是两件事,不能把启用成功当作进程已运行。

分别验收加载和业务运行

修复后,目标 unit 应不再处于 masked,实际读取的文件、服务名和配置内容符合预期。然后检查服务是否正常启动、日志是否有新的错误,以及业务入口是否工作。若错误变成执行文件不存在或权限拒绝,说明已经进入另一阶段,应按新错误定位。

回退时恢复事先保存的配置或屏蔽策略,并重新加载管理器;若已启动了进程,还要按业务要求停止或恢复原服务,文件回退不会自动撤销进程产生的操作。若配置被自动化再次改回 masked,应修正它的管理入口,不能靠每次启动前重复 unmask 来维持服务。