Linux 与服务器运维 / 知识点
systemd 服务管理与排障手册
手册条目
确认当前系统是否由 systemd 管理,并检查系统管理器的整体运行状态。
确认 systemd 运行状态
用于先判断当前环境是否由 systemd 作为系统管理器运行,再确认管理器是否处于可用状态。正常主机通常应看到 PID 1 为 systemd,且 systemctl is-system-running 返回 running;返回 degraded 时系统仍可能提供服务,但通常存在失败单元或启动顺序问题。
命令定位
先检查 PID 1,再查询 systemd 的整体状态。前者可区分普通主机与未使用 systemd 的容器或 chroot,后者适合启动后巡检、健康检查和故障入口判断。
printf 'PID 1: '
ps -p 1 -o comm=
printf 'Manager: '
systemctl is-system-running预期输出
PID 1: systemd
Manager: runningrunning 表示系统已完成启动且没有失败单元。命令返回非零退出码时不要只判定“systemd 不可用”,还要读取输出;degraded、starting 或 maintenance 都会导致非零退出码,但含义不同。
高频用法
仅用于脚本判断健康状态时,使用静默模式并依据退出码分支:
if systemctl is-system-running --quiet; then
echo "systemd manager is healthy"
else
state="$(systemctl is-system-running 2>/dev/null || true)"
printf 'systemd manager state: %s\n' "${state:-unknown}"
fi预期输出
systemd manager is healthy若整体状态为 degraded,立即列出失败的 service 单元:
systemctl --failed --type=service --no-pager预期输出
UNIT LOAD ACTIVE SUB DESCRIPTION
<SERVICE>.service loaded failed failed <DESCRIPTION>实际单元名和描述会不同。重点读取 ACTIVE 与 SUB;两列均为 failed 时,再对具体单元执行 systemctl status <SERVICE>.service 和 journalctl -u <SERVICE>.service -b。
风险与边界
在 Docker、chroot、WSL 或精简镜像中,宿主机可能使用 systemd,但当前环境的 PID 1 不是 systemd。此时 systemctl 常报无法连接总线;继续执行启动、停止命令没有意义,应改查容器入口进程、进程守护器或宿主机上的对应服务。
degraded 不等于整机宕机,它只说明存在失败单元或启动顺序问题。直接重启主机可能扩大影响;安全做法是先用 systemctl --failed 定位,再检查失败单元日志和依赖关系。
排障清单
ps -p 1 -o comm=不是systemd:确认是否处于容器、chroot 或其他 init 系统。- 报
Failed to connect to bus:检查 PID 1、DBus、权限以及是否误用了--user。 - 状态长期为
starting:检查等待中的启动任务和慢服务,可运行systemctl list-jobs。 - 状态为
degraded:先处理失败单元,不要仅用systemctl reset-failed清除表象。
速查:PID 1 确认管理器,is-system-running 判断整体状态,--failed 负责定位具体故障。
查看已加载、正在运行或全部已安装的 service 单元。
列出系统服务
用于区分“当前已加载或正在运行的服务”与“磁盘上已安装的 service 单元文件”。排查运行态时使用 list-units,盘点可启用服务或确认单元文件是否存在时使用 list-unit-files。
基本语法
systemctl list-units --type=service [--state=<STATE>] [--all]
systemctl list-unit-files --type=service [--state=<STATE>]list-units 查询 systemd 当前加载到内存中的单元;默认只显示活动、待处理或失败的单元,添加 --all 才包含已加载但处于 inactive 的服务。list-unit-files 查询已安装的单元文件及启用状态,并可显示尚未实例化的模板单元。
高频用法
列出当前正在运行的 service,适合快速确认核心守护进程是否存在:
systemctl list-units --type=service --state=running --no-pager --no-legend预期输出
systemd-journald.service loaded active running Journal Service
systemd-logind.service loaded active running User Login Management实际服务名和数量因发行版与主机角色而异。依次读取 UNIT、LOAD、ACTIVE、SUB 和 DESCRIPTION;对 service 来说,ACTIVE=active 且 SUB=running 通常表示主进程正在运行。
列出全部已加载 service,包括 inactive 与 failed:
systemctl list-units --type=service --all --no-pager预期输出
UNIT LOAD ACTIVE SUB DESCRIPTION
systemd-journald.service loaded active running Journal Service
<SERVICE>.service loaded inactive dead <DESCRIPTION>列出磁盘上已安装的 service 单元文件及启用状态:
systemctl list-unit-files --type=service --no-pager预期输出
UNIT FILE STATE PRESET
<ENABLED_SERVICE>.service enabled enabled
<STATIC_SERVICE>.service static -
<DISABLED_SERVICE>.service disabled disabledSTATE=enabled 表示已建立启用链接,不代表当前正在运行;static 通常表示单元没有可直接启用的安装信息,可能由依赖、socket、timer 或其他单元触发。
常用参数
| 参数 | 作用 | 使用时机 |
|---|---|---|
--type=service |
只保留 service 单元 | 避免 socket、timer、mount 混入结果 |
--state=running |
只看运行中的服务 | 快速核对守护进程 |
--state=failed 或 --failed |
只看失败单元 | 故障巡检 |
--all |
包含已加载但 inactive 的单元 | 查“为什么列表里没有” |
--no-pager |
禁用分页器 | 脚本、远程执行或复制结果 |
--full |
不截断长单元名和描述 | 输出被省略号截断时 |
输出字段说明
list-units 的 LOAD 表示定义是否成功载入,ACTIVE 是高层状态,SUB 是与单元类型相关的细分状态。list-unit-files 的 STATE 表示 enabled、disabled、static、masked 等启用状态;它与运行状态相互独立。
风险与边界
不要把 list-units 当成“全部已安装服务清单”,否则会漏掉未加载的 disabled 单元和模板文件;安全替代是使用 list-unit-files --type=service。反过来,也不要根据 STATE=enabled 推断服务正在运行,应再用 systemctl is-active <SERVICE>.service 验证。
脚本不应解析带颜色、分页或可能截断的交互式输出。至少添加 --no-pager --no-legend --full;需要稳定字段时,针对具体单元使用 systemctl show <SERVICE>.service --property=LoadState,ActiveState,SubState。
兼容性
系统级服务是默认范围;查看当前用户的服务时,在用户会话中执行 systemctl --user list-units --type=service。精简容器若没有运行 systemd 管理器,列表命令会失败,应改查容器进程或其专用守护器。较旧版本的输出可能没有 PRESET 列,以本机 systemctl --version 和手册为准。
速查:看运行态用 list-units,看安装与启用状态用 list-unit-files。
检查服务是否运行、最近退出原因、主进程 PID 和最新日志。
查看服务状态
当服务不可用、启动失败或行为异常时,用 systemctl status 快速确认单元是否已加载、当前运行状态、主进程 PID、最近退出结果和末尾日志。该命令适合人工排查;脚本判断应优先使用 systemctl is-active 或 systemctl show。
基本语法
SERVICE=nginx.service
systemctl status "$SERVICE" --no-pager --full预期输出:
● nginx.service - A high performance web server
Loaded: loaded (<PATH>/nginx.service; enabled; preset: enabled)
Active: active (running) since <TIME>; <DURATION> ago
Main PID: <PID> (nginx)
Tasks: 5
Memory: 8.4M
CPU: 120ms
CGroup: /system.slice/nginx.service
└─<PID> nginx: master process /usr/sbin/nginxLoaded 表示 unit 文件是否找到及是否开机启用;Active 是总体状态,括号中的 running、exited 或 failed 是子状态;Main PID 为 systemd 跟踪的主进程。<PATH>、<TIME>、<DURATION> 和 <PID> 会随机器变化。
高频用法
需要稳定字段而不是读取彩色状态页时,使用 systemctl show:
SERVICE=nginx.service
systemctl show "$SERVICE" --property=LoadState,ActiveState,SubState,Result,MainPID,ExecMainStatus预期输出示例:
LoadState=loaded
ActiveState=failed
SubState=failed
Result=exit-code
MainPID=0
ExecMainStatus=1Result=exit-code 表示进程以退出码结束并导致 unit 失败;ExecMainStatus=0 通常表示主进程最近一次正常退出,非零值需结合程序自身退出码解释。MainPID=0 表示当前没有被 systemd 跟踪的主进程。
查看本次启动后的最近日志:
SERVICE=nginx.service
journalctl -u "$SERVICE" -b -n 50 --no-pager -o short-iso预期输出示例:
<TIME> <HOST> systemd[1]: Starting nginx.service - A high performance web server...
<TIME> <HOST> nginx[<PID>]: nginx: configuration file <PATH> test is successful
<TIME> <HOST> systemd[1]: Started nginx.service - A high performance web server.-b 只看当前启动周期,-n 50 限制末尾 50 行;若故障发生在上次重启前,去掉 -b 或使用 -b -1 查看前一个启动周期。
输出字段说明
active (running):主进程仍在运行。active (exited):启动动作成功结束,但当前不一定存在常驻进程,常见于一次性任务。inactive (dead):未运行,可能是尚未启动或已正常停止。failed (Result: exit-code):启动命令或主进程以非零状态退出。activating:仍在启动;长时间停留时重点检查超时、依赖和程序就绪通知。
风险与边界
status 默认只展示少量末尾日志,终端宽度不足时还可能截断;使用 --full --no-pager 可避免字段被省略,但完整原因仍应从 journalctl 获取。不要仅凭 enabled 判断服务正在运行,也不要把 active (exited) 等同于业务已可用。用户级 unit 需改用 systemctl --user status <UNIT>。
排障清单
出现 Unit ... could not be found 时,核对完整 unit 名;若刚新增或修改 unit 文件,执行 systemctl daemon-reload 后重试。状态为 failed 时先读最早出现的错误和对应程序日志;状态反复在启动与失败间切换时,检查重启策略及启动频率限制。权限不足时使用具备授权的账户或 sudo,不要通过修改 unit 文件权限绕过 systemd 管理。
立即启动指定服务并确认启动结果。
启动服务
需要立即拉起一个已安装的 systemd 服务时,使用 systemctl start,随后读取结构化状态确认启动结果。start 只影响当前运行状态,不会自动设置开机启动。
基本语法
SERVICE=nginx.service
sudo systemctl start "$SERVICE"
systemctl show "$SERVICE" --property=ActiveState,SubState,MainPID预期输出:
ActiveState=active
SubState=running
MainPID=<PID>systemctl start 成功时通常不输出文本,因此示例继续读取状态。<PID> 是动态值;对于 Type=oneshot 服务,成功结果可能是 ActiveState=inactive,若配置了 RemainAfterExit=yes 则可能保持 active 状态。
启动后验证
只需在脚本中判断是否处于 active 状态时,使用 is-active,不要解析 status 的人类可读文本:
SERVICE=nginx.service
if systemctl is-active --quiet "$SERVICE"; then
echo "service is active"
else
echo "service is not active"
exit 1
fi预期输出:
service is active这只能证明 systemd 认为 unit 已进入 active 状态。对于 Type=simple,进程启动后可能很快被视为 active;数据库、Web 服务等仍应增加端口、健康检查接口或实际请求验证。
启动失败处理
启动失败时立即保留状态和当前启动周期日志,优先处理最早出现的根因:
SERVICE=nginx.service
sudo systemctl start "$SERVICE" || {
systemctl status "$SERVICE" --no-pager --full
journalctl -u "$SERVICE" -b -n 50 --no-pager
exit 1
}预期输出示例:
Job for nginx.service failed because the control process exited with error code.
● nginx.service - A high performance web server
Active: failed (Result: exit-code)
Process: <PID> ExecStartPre=<COMMAND> (code=exited, status=1/FAILURE)
<TIME> <HOST> systemd[1]: nginx.service: Failed with result 'exit-code'.实际命令、PID、时间和日志会不同。若提示 unit 被 masked,先确认屏蔽原因,再执行 sudo systemctl unmask <UNIT>;若因连续崩溃触发启动频率限制,修复根因后再执行 sudo systemctl reset-failed <UNIT> 并重新启动。
风险与边界
启动服务会立即执行 ExecStartPre、ExecStart 及相关依赖,可能监听端口、占用 CPU 或内存、挂载资源,或执行应用自带迁移。生产环境应先检查 systemctl cat <UNIT>、依赖服务和应用配置校验结果。不要使用 enable --now,除非同时确认需要“立即启动”和“开机自启”;也不要使用 --no-block 后立刻宣告成功,因为它只表示启动任务已排队。
常见失败定位
Access denied 表示当前账户无管理权限;Unit not found 通常是名称错误、软件未安装,或修改 unit 后尚未执行 daemon-reload;Dependency failed 应先查看失败依赖;长时间停在 activating 时检查 TimeoutStartSec、网络或挂载依赖,以及 Type=notify 程序是否正确发送就绪通知。
停止指定服务并确认相关进程是否已退出。
停止 systemd 服务
用于维护、摘流或故障隔离时停止指定服务,并确认主进程和服务控制组内的进程已经退出。优先使用 systemctl stop,不要只按进程名执行 kill,否则可能遗漏子进程,或被 systemd 的重启策略重新拉起。
停止并检查状态
将 nginx.service 替换为实际单元名。默认命令会等待停止作业完成;需要确认结果时不要使用 --no-block。
SERVICE=nginx.service
sudo systemctl stop "$SERVICE"
systemctl is-active "$SERVICE"
systemctl show "$SERVICE" \
-p ActiveState -p SubState -p MainPID -p Result \
--no-pager预期输出:
inactive
ActiveState=inactive
SubState=dead
MainPID=0
Result=successinactive、MainPID=0 表示主进程已退出,Result=success 表示停止作业未报错。systemctl is-active 在非活动状态通常返回退出码 3,放入启用 set -e 的脚本时应显式处理该返回码。
确认子进程已退出
主进程退出后,再检查服务控制组。下面适用于使用统一 cgroup 层级的常见 Linux 发行版。
SERVICE=nginx.service
CGROUP=$(systemctl show "$SERVICE" -p ControlGroup --value)
if [ -n "$CGROUP" ] && [ -r "/sys/fs/cgroup${CGROUP}/cgroup.procs" ]; then
PIDS=$(cat "/sys/fs/cgroup${CGROUP}/cgroup.procs")
[ -z "$PIDS" ] && echo "service cgroup is empty" || printf 'remaining PIDs: %s\n' "$PIDS"
else
echo "service cgroup removed"
fi预期输出:
service cgroup removed控制组被移除或 cgroup.procs 为空,表示 systemd 已不再跟踪该服务的进程。若仍有 PID,先查日志以及单元的 KillMode、TimeoutStopSec,不要立即强杀。
停止卡住或失败
SERVICE=nginx.service
systemctl list-jobs --no-pager
systemctl status "$SERVICE" --no-pager -l
journalctl -u "$SERVICE" -n 50 --no-pager停止仍在进行时,关键输出通常类似:
<JOB_ID> nginx.service stop running
Active: deactivating (stop)
<TIME> <HOST> <PROCESS>[<PID>]: <STOP_MESSAGE>先确认是否卡在 ExecStop、优雅退出或超时等待。只有日志确认无法正常退出,且业务允许丢失未落盘状态时,才使用 systemctl kill --kill-who=all --signal=SIGKILL <SERVICE>;更安全的方案是先摘流、保留现场并等待 SIGTERM 退出。带 RemainAfterExit=yes 的 oneshot 服务可能显示 active (exited),应按单元语义判断。cgroup v1 的挂载路径不同,进程检查需按发行版调整。
在配置或程序变更后重启服务并验证运行状态。
重启 systemd 服务
用于程序、环境变量或不支持热加载的配置变更后重新启动服务,并验证新进程已进入稳定运行状态。systemctl restart 会先停止再启动;服务原本未运行时也会被启动,因此执行前应确认本次操作允许拉起该单元。
重启并检查状态
将 nginx.service 替换为实际单元名。重启前应先运行应用自带的配置检查;修改过单元文件或 drop-in 时,还需先执行 sudo systemctl daemon-reload。
SERVICE=nginx.service
sudo systemctl restart "$SERVICE"
systemctl is-active "$SERVICE"
systemctl show "$SERVICE" \
-p ActiveState -p SubState -p MainPID \
-p ExecMainCode -p ExecMainStatus -p Result \
--no-pager预期输出:
active
ActiveState=active
SubState=running
MainPID=<PID>
ExecMainCode=0
ExecMainStatus=0
Result=successactive/running 表示服务已进入运行态,MainPID 应为非零动态值。ExecMainStatus=0 和 Result=success 只说明 systemd 未记录启动失败,仍需执行应用自己的 HTTP、TCP 或业务健康检查。
确认已切换到新进程
记录重启前后的主进程 PID,并查看进入活动状态的时间。
SERVICE=nginx.service
OLD_PID=$(systemctl show "$SERVICE" -p MainPID --value)
sudo systemctl restart "$SERVICE"
NEW_PID=$(systemctl show "$SERVICE" -p MainPID --value)
printf 'old=%s new=%s\n' "$OLD_PID" "$NEW_PID"
systemctl show "$SERVICE" -p ActiveEnterTimestamp --no-pager预期输出:
old=<OLD_PID> new=<NEW_PID>
ActiveEnterTimestamp=<TIME>常驻服务正常重启后,新旧 PID 通常不同,时间戳应接近操作时间。包装进程、派生工作进程或 socket 激活服务不能只凭 PID 判断,必须继续验证端口和实际请求。
重启失败排查
SERVICE=nginx.service
systemctl status "$SERVICE" --no-pager -l
journalctl -u "$SERVICE" --since "-5 min" --no-pager
systemctl show "$SERVICE" \
-p Result -p ExecMainStatus -p NRestarts \
--no-pager失败时关键输出通常类似:
Active: failed (Result: exit-code)
Result=exit-code
ExecMainStatus=<EXIT_CODE>
NRestarts=<COUNT>Result 常见为 exit-code、timeout 或 signal;NRestarts 持续增加表示可能进入自动重启循环。先修复配置、权限、端口占用或依赖,再执行 sudo systemctl reset-failed "$SERVICE" 并重新启动。重启会中断现有连接和处理中任务;支持热加载时优先使用 reload 或 reload-or-restart,生产环境应先摘流或滚动重启。
在不中断主进程的前提下请求服务重新读取自身配置。
重新加载服务配置
当服务进程支持热重载时,用 systemctl reload 请求它重新读取自身配置,主进程通常不会退出,现有连接也可继续处理。该命令针对服务自身配置;修改 .service 单元文件后应先执行 systemctl daemon-reload,两者不能互相替代。
命令定位
先检查单元是否声明了重载能力。CanReload=yes 表示 systemd 可以发起单元定义的重载动作,但不保证业务配置一定合法。
SERVICE=nginx.service
systemctl show "$SERVICE" -p CanReload --value预期输出
yes若输出 no,不要自行猜测信号。优先使用服务官方提供的重载命令,或在维护窗口执行重启。
基本语法
通用语法是 sudo systemctl reload <SERVICE>。成功时通常没有标准输出,退出码为 0。以下示例先校验 Nginx 配置,再发起热重载,避免把明显错误的配置交给运行进程。
SERVICE=nginx.service
sudo nginx -t &&
sudo systemctl reload "$SERVICE" &&
systemctl is-active "$SERVICE"预期输出
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful
active实际配置路径可能不同;active 只表示服务仍在运行,不等于新配置已完全生效。
高频用法
配置校验通过后,执行 sudo systemctl reload nginx.service;成功时通常无输出。服务不支持重载且允许短暂中断时,可用 sudo systemctl reload-or-restart nginx.service,它会在无法重载时改为重启。多个单元都明确支持热重载时,可一次执行 sudo systemctl reload nginx.service php-fpm.service。
reload-or-restart 可能终止并重新创建主进程,因此不能把它当作无损操作。批量重载时任一单元失败都应逐个检查状态和日志,避免只看最后一条结果。
验证与排障
重载后检查主进程状态和最近一次状态变化:
SERVICE=nginx.service
systemctl show "$SERVICE" -p ActiveState -p SubState预期输出
ActiveState=active
SubState=running再用 journalctl -u nginx.service --since "<TIME>" --no-pager -n 30 查看操作附近日志,重点查找 reload、syntax error、permission denied、unknown directive。<TIME> 替换为实际时间,例如 10 minutes ago。
若状态仍为 active 但配置未生效,检查配置文件是否为实际加载路径、是否修改了错误实例,以及服务是否只对新连接应用配置。若命令失败,先运行服务自带校验,再查看 systemctl status <SERVICE> 的退出原因。
风险与边界
触发条件是服务重载逻辑存在缺陷、配置虽可解析但语义错误,或重载期间资源不足;可能导致部分配置未应用、工作进程异常退出或短暂请求失败。安全做法是先运行服务自带校验命令、备份配置,并在低峰期观察日志和关键指标。
不要用 kill -HUP 代替 systemctl reload,除非服务官方明确要求且已确认主进程 PID。发错 PID 或信号可能终止进程;优先让 systemd 按单元定义执行 ExecReload=。
启用服务的开机启动链接,并按需立即启动服务。
设置开机启动
用 systemctl enable 根据单元文件的 [Install] 规则创建启动链接,使服务在目标启动阶段被拉起;加上 --now 可同时启动当前系统中的服务。仅执行 enable 不会立即启动,服务正在运行也不代表已经设置开机启动。
基本语法
只设置下次开机启动使用 sudo systemctl enable <SERVICE>;设置开机启动并立即启动使用 sudo systemctl enable --now <SERVICE>。主示例以 Nginx 为例,并分别验证启用状态和运行状态。
SERVICE=nginx.service
sudo systemctl enable --now "$SERVICE"
printf 'boot=%s\n' "$(systemctl is-enabled "$SERVICE")"
printf 'run=%s\n' "$(systemctl is-active "$SERVICE")"预期输出
Created symlink <PATH> → <PATH>.
boot=enabled
run=active不同发行版或已启用的服务可能不显示 Created symlink,链接路径也会不同;核心判断是 boot=enabled 和 run=active。
常用参数
--now 在修改启用关系后立即启动服务。若启动失败,启用链接仍可能已经创建,因此要分别检查 is-enabled 与 is-active。
--runtime 只在本次启动周期内创建临时启用关系,重启后失效,适合临时验证,不适合作为永久配置。
--force 会覆盖冲突链接。触发已有别名或链接冲突时可能改变其他单元关系,生产环境应先检查冲突来源,避免直接使用。
高频用法
查看是否已设置开机启动:
systemctl is-enabled nginx.service预期输出
enabled取消开机启动但保持当前进程运行:
sudo systemctl disable nginx.service
systemctl is-enabled nginx.service预期输出
Removed "<PATH>".
disabled链接路径可能不同,已禁用时也可能没有 Removed 提示。如需同时停止当前服务,执行 sudo systemctl disable --now nginx.service,随后用 systemctl is-active nginx.service 验证,预期为 inactive。
验证与排障
同时读取启用状态和运行状态,避免把“已启动”误判为“已设置开机启动”:
SERVICE=nginx.service
systemctl show "$SERVICE" -p UnitFileState -p ActiveState预期输出
UnitFileState=enabled
ActiveState=active若提示 The unit files have no installation config,该单元通常是 static,没有可直接启用的 [Install] 规则;应启用依赖它的上层单元或按软件文档操作。若状态为 masked,先确认屏蔽原因,再决定是否执行 systemctl unmask <SERVICE>。
启用后无法启动时,运行 systemctl status <SERVICE> --no-pager 和 journalctl -u <SERVICE> -b --no-pager -n 50,检查配置错误、依赖失败、端口占用与权限问题。
风险与边界
触发条件是服务配置错误、依赖未就绪或使用 enable --now 直接在生产机启动;可能造成启动失败、端口冲突或立即接管流量。安全做法是先运行配置校验、确认端口和依赖,再执行 enable --now,并检查日志与健康探针。
模板单元通常需要实例名,例如 worker@blue.service;启用不带实例的模板可能失败或不产生预期效果。disable 只移除启用链接,不保证停止服务,也不阻止其他单元依赖拉起它;需要彻底禁止启动时才考虑 mask,并先评估依赖影响。
移除服务的开机启动链接,并区分禁用与立即停止。
取消开机启动
用于移除服务的开机启动链接,并明确区分“禁用”和“停止”。systemctl disable 只改变下次启动时的拉起关系,默认不会终止当前进程;需要立即停服时才使用 --now。
命令定位
disable 删除由 enable 创建的符号链接,常见位置是 multi-user.target.wants/。它不修改单元文件本身,也不保证服务永远不会被手工启动、依赖单元拉起或由 socket、timer、path 等触发单元激活。
高频用法
只取消下次开机启动
UNIT=nginx.service
sudo systemctl disable --quiet "$UNIT"
systemctl is-enabled "$UNIT" || true
systemctl is-active "$UNIT" || true预期输出(服务原本仍在运行):
disabled
activedisabled 表示开机启动链接已移除,active 表示当前进程仍在运行。实际服务名应替换为目标单元。
取消开机启动并立即停止
UNIT=nginx.service
sudo systemctl disable --now --quiet "$UNIT"
systemctl is-enabled "$UNIT" || true
systemctl is-active "$UNIT" || true预期输出:
disabled
inactive--now 会执行禁用并同步停止当前单元,适合已确认可以立即中断的服务。
状态读取
systemctl is-enabled <UNIT> 关注开机配置,常见结果有 enabled、disabled、static、indirect 和 masked。systemctl is-active <UNIT> 关注当前运行状态,常见结果有 active、inactive、activating 和 failed;两类状态必须分别判断。
风险与边界
- 在生产服务仍承载流量时使用
--now,会立即中断进程并可能造成请求失败。安全做法是先单独执行disable,完成摘流、维护窗口和回滚准备后再执行stop。 - 服务由
.socket、.timer、.path或其他依赖单元触发时,仅禁用.service仍可能再次启动。先检查同名前缀的触发单元和反向依赖,再按需禁用对应触发源。 - 对
static单元执行disable通常没有可删除的链接,因为它由依赖关系启动。应调整真正启用它的上游单元;只有确认需要阻止任何启动路径时才考虑mask,且必须先评估依赖影响。
排障清单
发现重启后仍被拉起时,先核对完整单元名和 is-enabled 结果,再检查同名 .socket、.timer、.path 单元以及依赖关系。若显示 masked、static 或 indirect,不要反复执行 disable,应根据状态处理对应的上游或掩码配置。
通过脚本友好的命令判断服务是否已启用、运行或失败。
检查启用与运行状态
用于在脚本、巡检和发布流程中分别判断单元是否已启用、当前是否运行以及是否进入失败状态。优先使用 is-enabled、is-active、is-failed 的退出码,避免解析面向人工阅读且可能随版本或语言变化的 systemctl status 文本。
命令定位
systemctl is-enabled --quiet 成功表示单元已启用;systemctl is-active --quiet 成功表示当前为活动状态;systemctl is-failed --quiet 成功反而表示检测到失败。启用状态和运行状态相互独立,不能用其中一个替代另一个。
高频用法
获取稳定的键值快照
systemctl show nginx.service \
--property=LoadState \
--property=UnitFileState \
--property=ActiveState \
--property=SubState \
--property=Result预期输出(已启用且运行正常的典型服务):
LoadState=loaded
UnitFileState=enabled
ActiveState=active
SubState=running
Result=successshow 输出适合日志采集和键值解析;实际 SubState、Result 会随单元类型和当前状态变化。
用退出码生成脚本判定
bash -s -- nginx.service <<'BASH'
set -u
unit="${1:-nginx.service}"
load_state="$(systemctl show --property=LoadState --value "$unit" 2>/dev/null || true)"
if [[ "$load_state" != "loaded" ]]; then
printf 'unit=%s load_state=%s\n' "$unit" "${load_state:-not-found}"
exit 3
fi
enabled=no
active=no
failed=no
systemctl is-enabled --quiet "$unit" && enabled=yes
systemctl is-active --quiet "$unit" && active=yes
systemctl is-failed --quiet "$unit" && failed=yes
printf 'unit=%s enabled=%s active=%s failed=%s\n' \
"$unit" "$enabled" "$active" "$failed"
if [[ "$failed" == yes ]]; then
exit 2
elif [[ "$active" != yes ]]; then
exit 1
fi
BASH
printf 'exit_code=%s\n' "$?"预期输出(nginx.service 已启用且运行正常):
unit=nginx.service enabled=yes active=yes failed=no
exit_code=0脚本返回 0 表示已加载且正在运行,1 表示未运行但未失败,2 表示已失败,3 表示单元未加载或名称不存在。
输出字段说明
LoadState=loaded表示单元定义已被 systemd 载入;not-found常见于单元名错误或文件不存在。UnitFileState=enabled只说明已配置启动链接,不代表当前进程正在运行。ActiveState是粗粒度状态,SubState提供更具体的running、exited、dead等子状态。Result记录最近一次启动或停止结果;排障时应与日志一起读取,不能只凭success判断当前仍在运行。
风险与边界
- 直接在
set -e脚本中调用这些命令,预期的非零状态可能提前终止脚本。安全做法是把命令放入if条件或显式保存退出码。 is-failed返回0代表“确实失败”,语义与常见健康检查相反。脚本中应写成“命令成功则进入失败分支”,不要使用直觉式取反。- 一次性
oneshot服务可能执行成功后显示inactive,这不等于故障。应结合Type、RemainAfterExit、Result和业务产物判断。 - 用户级单元需要添加
--user,容器或 chroot 中若 systemd 不是 PID 1,系统级查询可能无法连接服务管理器。
排障清单
单元不存在时先用 systemctl list-unit-files 核对完整名称;active=no 且 failed=no 时检查 ActiveState、SubState 和单元类型;failed=yes 时再查看 systemctl status --no-pager <UNIT> 与 journalctl -u <UNIT> -b --no-pager -n 100,定位最近一次失败原因。
查看服务原始定义、覆盖配置及最终加载来源。
查看服务单元文件
用于确认服务的主单元文件、*.d 覆盖文件以及 systemd 当前记录的加载来源。查看文件内容首选 systemctl cat,确认加载路径使用 systemctl show;两者结合可区分“磁盘上写了什么”和“管理器实际加载了什么”。
命令定位
systemctl cat UNIT 按 systemd 的搜索顺序输出主单元文件和已发现的 drop-in 文件,每段前会标出真实路径。它只是按来源依次展示,并不会把重复指令、清空指令和列表追加规则计算成一份“最终合并文件”。
FragmentPath 是主单元文件的加载路径,DropInPaths 是覆盖文件列表,SourcePath 常用于生成单元,指出其原始来源,例如 SysV 脚本。需要检查最终生效值时,再使用 systemctl show 查询对应属性。
高频用法
下面使用 systemd 主机通常都存在的 systemd-journald.service。替换 UNIT 即可检查目标服务。
UNIT=systemd-journald.service
# 先看主文件与 drop-in 的原始内容,再核对管理器记录的来源路径
systemctl cat --no-pager --full "$UNIT"
printf '\n== loaded sources ==\n'
systemctl show "$UNIT" --no-pager --all \
-p LoadState -p FragmentPath -p SourcePath -p DropInPaths预期输出(节选;内容和路径随发行版、版本及本机覆盖配置变化):
# <PATH>/systemd-journald.service
[Unit]
Description=Journal Service
Documentation=man:systemd-journald.service(8)
[Service]
ExecStart=/usr/lib/systemd/systemd-journald
Type=notify
== loaded sources ==
LoadState=loaded
FragmentPath=<PATH>/systemd-journald.service
SourcePath=
DropInPaths=读取时先看每个 # <PATH> 标记:第一段通常是主文件,后续 *.service.d/*.conf 是覆盖文件。LoadState=loaded 表示单元已成功加载;空的 DropInPaths= 表示当前没有已加载的 drop-in。<PATH> 为动态值,常见于 /usr/lib/systemd/system、/lib/systemd/system、/etc/systemd/system 或 /run/systemd/system。
常用参数
--no-pager 防止进入分页器,适合复制、远程执行和脚本采集;--full 禁止截断长行;--all 让 systemctl show 同时显示空属性,便于确认“没有配置”而不是“输出被省略”。用户级服务在同一命令中加入 --user,例如 systemctl --user cat my-agent.service。
风险与边界
修改单元文件后未执行 systemctl daemon-reload 时,systemctl cat 看到的是磁盘内容,而 systemctl show 仍可能反映旧的已加载状态,导致误判配置已经生效。安全做法是先保存变更,再运行 sudo systemctl daemon-reload,随后重新查询;该操作重新加载单元定义,但不会自动重启服务。
不要直接修改 /usr/lib/systemd/system 或 /lib/systemd/system 下的供应商文件,软件升级可能覆盖改动。需要长期覆盖时使用 sudo systemctl edit UNIT 创建 /etc/systemd/system/UNIT.d/override.conf,并在变更后执行 daemon-reload 和必要的服务重启。
排障清单
遇到 Unit ... could not be found,先用 systemctl list-unit-files --type=service | grep -F '<NAME>' 核对完整单元名,并区分模板 name@.service 与实例 name@value.service。若 FragmentPath 位于 /run/systemd/generator*,该单元可能由生成器动态创建,应结合 SourcePath 查原始配置。
若命令报 System has not been booted with systemd as init system,先执行 ps -p 1 -o comm=;PID 1 不是 systemd 时,应改用容器或该系统实际采用的服务管理方式。
兼容性
系统服务默认查询系统管理器;用户服务必须由对应用户使用 systemctl --user 查询。不同发行版的单元目录和文件内容会变化,因此判断来源应以 FragmentPath、SourcePath 和 DropInPaths 的本机输出为准。
查询启动命令、运行用户、依赖关系、限制和退出结果等结构化属性。
查看服务属性
用于以结构化方式查询启动命令、运行身份、依赖与排序关系、资源限制、主进程状态和最近一次退出结果。相比解析 systemctl status 的人类可读文本,systemctl show 更适合精确核对和脚本采集。
基本语法
基本形式是 systemctl show UNIT -p PROPERTY。重复 -p 可以只取需要的字段;加入 --all 可保留空值;加入 --value 可只输出值。属性名称区分大小写,未知属性通常会被忽略或给出提示,因此脚本上线前应在目标 systemd 版本上验证。
高频用法
下面一次查询常用排障字段,避免输出数百个无关属性。
UNIT=systemd-journald.service
systemctl show "$UNIT" --no-pager --all \
-p LoadState -p ActiveState -p SubState \
-p FragmentPath -p ExecStart -p User -p Group \
-p Requires -p After -p Restart \
-p LimitNOFILE -p MainPID \
-p Result -p ExecMainCode -p ExecMainStatus预期输出(动态值以占位符表示):
LoadState=loaded
ActiveState=active
SubState=running
FragmentPath=<PATH>/systemd-journald.service
ExecStart={ path=/usr/lib/systemd/systemd-journald ; argv[]=/usr/lib/systemd/systemd-journald ; ignore_errors=no ; start_time=[<TIME>] ; stop_time=[n/a] ; pid=<PID> ; code=(null) ; status=0/0 }
User=
Group=
Requires=systemd-journald.socket
After=system.slice systemd-journald.socket
Restart=no
LimitNOFILE=<LIMIT>
MainPID=<PID>
Result=success
ExecMainCode=0
ExecMainStatus=0<PATH>、<TIME>、<PID> 和 <LIMIT> 会随主机变化。系统服务的 User= 为空通常表示使用默认身份,即 root;不要把空值理解为“没有用户”。运行中的服务尚未退出时,ExecMainCode 和 ExecMainStatus 可能仍为 0,最终结果应在服务停止或失败后再次查询。
输出字段说明
ExecStart 是 systemd 解析后的启动命令结构,包含可执行文件、参数、进程号和退出信息。Requires 表示强依赖关系,依赖启动失败或被显式停止时可能影响当前单元;After 只表达启动或停止顺序,不会单独拉起另一个单元,而且输出顺序不是实际启动时间线。
Restart 是自动重启策略;LimitNOFILE 是进程可用文件描述符上限。Result 给出服务级结果,如 success、exit-code、signal 或 timeout;ExecMainCode 表示主进程退出原因类别,ExecMainStatus 是对应的退出码或信号状态。排查失败时应同时读取三者,不能只看 ActiveState=failed。
脚本取值
脚本只需要单个值时使用 --value,避免手工切割等号右侧的复杂内容。
UNIT=systemd-journald.service
main_pid=$(systemctl show "$UNIT" -p MainPID --value)
printf 'MainPID=%s\n' "$main_pid"预期输出:
MainPID=<PID><PID> 为当前主进程号;未运行或没有主进程时通常为 0。批量采集多个属性时不要同时使用 --value 后再依赖字段名,因为输出只保留值并按请求顺序排列。
风险与边界
systemctl show 读取的是 systemd 管理器当前加载和计算后的属性,不等同于磁盘文件文本。刚修改单元文件但未执行 systemctl daemon-reload 时,查询结果可能仍是旧值;安全流程是保存配置、运行 sudo systemctl daemon-reload、重新查询,确认后再决定是否重启服务。
不要用 grep、cut -d= -f2 解析 ExecStart 等复杂属性,值中可能包含空格、分号或等号。优先按明确属性名查询;只取单值时使用 --value。资源限制还可能受父级 slice、内核上限或运行时覆盖影响,必要时结合 systemctl show UNIT -p Slice 与对应 slice 属性继续核对。
排障清单
属性为空时先加 --all,再检查该字段是否适用于当前单元类型。查询用户服务时使用 systemctl --user show UNIT;由 root 查询并不等同于目标用户的用户管理器状态。模板服务应查询具体实例,例如 worker@1.service,否则实例化后的环境和命令可能看不到。
如果主机的旧版 systemd 不支持 --value,可退回 systemctl show UNIT -p MainPID 并删除固定前缀,但仍应保留等号后的全部内容。容器中 PID 1 不是 systemd 时,这些属性不可用,应改查容器运行时或进程管理器。
为自定义程序编写可由 systemd 管理的基础 service 单元。
创建服务单元
用于把自定义常驻程序交给 systemd 启停、开机拉起、失败重启和日志收集。基础做法是把可执行文件放到稳定路径,在 /etc/systemd/system/ 创建 .service,校验后执行 daemon-reload,再启用并验证运行状态。
使用前提
示例使用 demo-worker.service,会写入 /usr/local/libexec/demo-worker 和 /etc/systemd/system/demo-worker.service,需要 root 权限。程序不保存持久数据,因此采用 DynamicUser=yes;真实程序需要写目录时,应显式准备目录权限,或改用 StateDirectory=、RuntimeDirectory=。
基础单元
Type=simple 适合前台运行且不自行 fork 的程序;ExecStart 必须使用绝对路径。Restart=on-failure 只在异常退出、信号终止或超时时重启,人工执行 systemctl stop 不会触发重启。WantedBy=multi-user.target 仅决定 enable 时创建的开机启动链接。
创建并启用
以下命令创建一个最小前台进程、写入单元文件、校验语法并立即启用。注释只标出执行顺序和关键安全设置。
sudo install -d -m 0755 /usr/local/libexec
sudo tee /usr/local/libexec/demo-worker >/dev/null <<'EOF'
#!/bin/sh
while true; do
echo "demo-worker heartbeat"
sleep 60
done
EOF
sudo chmod 0755 /usr/local/libexec/demo-worker
sudo tee /etc/systemd/system/demo-worker.service >/dev/null <<'EOF'
[Unit]
Description=Demo worker
[Service]
Type=simple
ExecStart=/usr/local/libexec/demo-worker
DynamicUser=yes
Restart=on-failure
RestartSec=3s
NoNewPrivileges=yes
PrivateTmp=yes
[Install]
WantedBy=multi-user.target
EOF
# 先校验,再让 PID 1 重新读取单元并启动服务
sudo systemd-analyze verify /etc/systemd/system/demo-worker.service
sudo systemctl daemon-reload
sudo systemctl enable --now demo-worker.service >/dev/null 2>&1
printf 'enabled=%s\n' "$(systemctl is-enabled demo-worker.service)"
printf 'active=%s\n' "$(systemctl is-active demo-worker.service)"
printf 'MainPID=%s\n' "$(systemctl show demo-worker.service -p MainPID --value)"预期输出:
enabled=enabled
active=active
MainPID=<PID><PID> 是本次启动生成的主进程号,实际值每次可能不同。systemd-analyze verify 成功时通常不输出内容;出现错误必须先修正,不能把无效单元直接加载到生产环境。
验证与读取
systemctl status demo-worker.service 用于查看 Loaded、Active、主进程和最近日志;journalctl -u demo-worker.service -b --no-pager 查看本次启动以来的完整日志。systemctl cat demo-worker.service 可确认 PID 1 当前读取的主文件与 drop-in 来源,避免排查时看错文件。
风险与排障
- 程序后台化:若程序自行 fork,但仍配置
Type=simple,systemd 可能跟踪错误进程,导致状态和重启行为不可靠。安全替代是让程序以前台模式运行;无法修改时再根据程序行为使用Type=forking和可靠的PIDFile=。 - 默认以 root 运行:省略
User=或DynamicUser=会扩大漏洞影响范围。优先使用专用低权限账号,并只开放必需目录。 - 快速失败循环:错误路径、权限或参数会触发连续重启并命中启动限流。先读
systemctl status和journalctl -u,修复后执行systemctl reset-failed再启动。 - 修改后未重载:编辑单元但漏掉
systemctl daemon-reload时,systemd 仍使用旧配置。先重载,再restart;仅重载不会重启进程。
兼容性
DynamicUser= 需要 systemd 232 及以上。旧版本可预先创建系统账号,并用 User=demo-worker、Group=demo-worker 代替。发行版提供的单元通常位于 /usr/lib/systemd/system/ 或 /lib/systemd/system/;自定义单元应放在 /etc/systemd/system/,不要写入包管理器维护的目录。
通过 drop-in 覆盖服务参数,避免直接修改发行版提供的单元文件。
使用覆盖配置
用于在不改动发行版或软件包提供的主单元文件时调整环境变量、重启策略、资源限制或启动参数。drop-in 位于 /etc/systemd/system/<unit>.d/*.conf,升级软件包后仍可保留,也便于单独审计和回滚。
创建覆盖
交互式修改优先使用 sudo systemctl edit demo-worker.service,它会创建 drop-in 并在保存后重载配置。自动化场景可直接写入目录;以下示例假定 demo-worker.service 已存在且能正常启动,只覆盖运行环境和重启间隔。
sudo install -d -m 0755 /etc/systemd/system/demo-worker.service.d
sudo tee /etc/systemd/system/demo-worker.service.d/10-runtime.conf >/dev/null <<'EOF'
[Service]
Environment="APP_ENV=production"
Restart=on-failure
RestartSec=10s
EOF
# 手工写文件后必须重载;restart 才会让进程使用新环境
sudo systemd-analyze verify demo-worker.service
sudo systemctl daemon-reload
sudo systemctl restart demo-worker.service
printf 'dropin=%s\n' "$(systemctl show demo-worker.service -p DropInPaths --value)"
printf 'environment=%s\n' "$(systemctl show demo-worker.service -p Environment --value)"
printf 'restart=%s\n' "$(systemctl show demo-worker.service -p Restart --value)"
printf 'restart_delay=%s\n' "$(systemctl show demo-worker.service -p RestartUSec --value)"
printf 'active=%s\n' "$(systemctl is-active demo-worker.service)"预期输出:
dropin=/etc/systemd/system/demo-worker.service.d/10-runtime.conf
environment=APP_ENV=production
restart=on-failure
restart_delay=10s
active=activeDropInPaths 用于确认实际加载的覆盖文件;Environment、Restart 和 RestartUSec 是合并后的有效值。路径、属性格式在少数旧版本中可能略有差异,但 active=active 才表示重启后服务仍正常。
覆盖启动命令
ExecStart= 属于可重复指令。要替换主单元已有命令,必须先用空赋值清空旧列表,再写新命令。下面是片段示例,依赖真实存在的程序和配置文件,保存后仍需执行 daemon-reload 与 restart。
[Service]
ExecStart=
ExecStart=/opt/myapp/bin/server --config /etc/myapp/prod.yaml生效行为:最终只保留新的 ExecStart。若漏掉空的 ExecStart=,除 Type=oneshot 等特殊情况外,单元通常会因存在多个启动命令而校验失败。可用 systemd-analyze verify <UNIT> 检查,并用 systemctl show <UNIT> -p ExecStart 查看合并结果。
优先级与命名
同一单元可有多个 drop-in,文件名按字典序合并,建议使用 10-runtime.conf、20-limits.conf 这类前缀表达顺序。/etc/systemd/system 的管理员配置优先于 /run/systemd/system 和发行版目录;同一指令后出现的标量值通常覆盖前值,可重复列表则可能追加,是否需要先清空取决于指令语义。
风险与回滚
- 直接改主单元:修改
/usr/lib/systemd/system/*.service可能在软件升级时被覆盖,也难以区分厂商默认值与本地变更。安全替代是普通systemctl edit创建 drop-in。 - 误用
systemctl edit --full:它会复制完整主单元,后续厂商新增的安全项和依赖不会自动进入本地副本。只有确需完全接管时才使用,并纳入配置审计。 - 只重载不重启:
daemon-reload只更新 PID 1 的配置,不会改变已运行进程的环境和命令。窗口允许时执行restart;不允许中断时先评估服务是否支持reload。 - 覆盖资源限制过大:放宽
LimitNOFILE=、MemoryMax=等可能放大资源耗尽影响。先记录原值,逐步调整并监控。
回滚时删除对应 .conf,执行 systemctl daemon-reload,再重启服务。不要直接删除整个 .d 目录,除非已确认其中没有其他团队维护的覆盖文件。
排障速查
先用 systemctl cat <UNIT> 核对主文件和全部 drop-in,再用 systemctl show <UNIT> -p DropInPaths -p ExecStart -p Environment 查看有效属性。出现“修改无效”时,重点检查文件是否以 .conf 结尾、节名是否正确、是否执行过 daemon-reload,以及是否有排序更靠后的 drop-in 再次覆盖当前值。
在新增或修改单元文件后通知 systemd 重新扫描配置。
重新加载单元文件
新增、修改、删除单元文件或 drop-in 后,用 systemctl daemon-reload 让 systemd PID 1 重新扫描配置并重建依赖关系。该命令只刷新管理器中的单元定义,不会自动重启正在运行的服务。
命令定位
适用于修改 /etc/systemd/system/*.service、*.socket、*.timer,调整 *.d/*.conf 覆盖文件,或新增、删除单元符号链接之后。若只是修改应用自身的配置文件,通常不需要执行本命令,应使用该服务支持的 reload 或 restart。
基本语法
sudo systemctl daemon-reload预期输出
# 成功时通常无输出,退出码为 0没有输出表示 systemd 已完成重新扫描;它不代表目标服务一定能够启动,也不代表新定义已经作用到现有进程。
高频用法
修改单元后,先重新加载,再按变更性质决定是否重启。下面以 myapp.service 为例,实际使用时替换为目标单元名。
UNIT=myapp.service
sudo systemctl daemon-reload
sudo systemctl restart "$UNIT"
systemctl is-active "$UNIT"预期输出
active若只想确认管理器是否仍认为单元文件存在未加载变更,可查看 NeedDaemonReload,并同时确认实际加载路径。
UNIT=myapp.service
systemctl show "$UNIT" --property=NeedDaemonReload --property=FragmentPath --property=DropInPaths预期输出
NeedDaemonReload=no
FragmentPath=/etc/systemd/system/myapp.service
DropInPaths=/etc/systemd/system/myapp.service.d/override.confNeedDaemonReload=no 表示当前磁盘版本已被管理器重新读取;文件路径和 drop-in 列表会随实际部署变化。
风险与边界
当单元内容存在语法错误、依赖缺失或命令路径错误时,daemon-reload 仍可能完成,但目标服务会在后续启动或重启时失败。安全做法是先运行 systemd-analyze verify,再重新加载,并仅重启受影响的单元。
不要用 systemctl daemon-reexec 代替常规重新加载。daemon-reexec 会让 systemd 管理器重新执行自身,适合 systemd 软件包升级等少数场景;普通配置变更使用它会无谓扩大操作影响面。
排障清单
- 出现
Warning: The unit file ... changed on disk:执行sudo systemctl daemon-reload,再重新查询状态。 - 修改后仍使用旧配置:用
systemctl cat <UNIT>和systemctl show <UNIT> -p FragmentPath -p DropInPaths确认是否编辑了真正生效的文件。 - 重新加载后服务未变化:单元定义通常只影响下一次启动;根据服务能力执行
systemctl reload <UNIT>,或在维护窗口执行systemctl restart <UNIT>。 - 重启失败:立即查看
systemctl status <UNIT> --no-pager与journalctl -u <UNIT> -b --no-pager -n 100,不要连续盲目重试。
在加载或发布前检查单元文件语法、指令和依赖配置错误。
校验单元文件
在发布、重新加载或重启服务前,用 systemd-analyze verify 检查单元文件的语法、未知指令、依赖引用和部分命令路径问题。校验通过只表示静态定义可被解析,不能替代实际启动验证。
基本语法
systemd-analyze verify /absolute/path/to/myapp.service预期输出
# 校验通过时通常无输出,退出码为 0优先使用绝对路径,避免因为当前目录或单元搜索路径不同而校验到错误文件。发现问题时,命令会输出文件、行号和诊断原因。
主示例
下面创建一个最小的一次性服务并校验,不会安装、加载或启动该单元。
cat > /tmp/demo-verify.service <<'EOF'
[Unit]
Description=systemd verify demo
[Service]
Type=oneshot
ExecStart=/usr/bin/true
EOF
systemd-analyze verify /tmp/demo-verify.service
printf 'exit=%s\n' "$?"预期输出
exit=0没有额外诊断且退出码为 0,表示该文件通过当前 systemd 版本的静态校验。临时文件可在检查后删除。
识别错误
可以用一个故意包含未知指令和不存在命令的文件观察诊断格式。
cat > /tmp/demo-bad.service <<'EOF'
[Unit]
Description=broken verify demo
[Service]
Type=oneshot
UnknownKey=yes
ExecStart=/path/that/does/not/exist
EOF
systemd-analyze verify /tmp/demo-bad.service
printf 'exit=%s\n' "$?"预期输出
<PATH>:<LINE>: Unknown key 'UnknownKey' in section [Service], ignoring.
demo-bad.service: Command /path/that/does/not/exist is not executable: No such file or directory
exit=1实际措辞、行号和前缀可能因 systemd 版本不同而变化;读取时重点看文件名、行号、指令名和最后的非零退出码。
高频用法
- 校验正式文件:
systemd-analyze verify /etc/systemd/system/myapp.service。 - 同时校验相互依赖的单元:在
verify后依次给出多个绝对路径,减少测试环境中依赖未被发现的误报。 - 校验用户级单元:使用
systemd-analyze --user verify ~/.config/systemd/user/myapp.service,并确保依赖也位于用户单元搜索路径。
风险与边界
校验临时目录中的单元时,如果它依赖尚未安装到系统搜索路径的配套单元,可能出现依赖缺失诊断。安全做法是同时传入相关单元文件,或在与目标主机一致的根文件系统中校验。
即使退出码为 0,服务仍可能因权限、环境变量文件、挂载、网络、凭据或运行时资源失败。发布流程应继续执行 daemon-reload,在维护窗口启动或重启目标单元,并用 systemctl status、systemctl is-active 和 journalctl -u 验证。
排障清单
- 报
Unknown key:核对指令拼写、所在节名和目标 systemd 版本是否支持。 - 报可执行文件不存在:确认
ExecStart=使用绝对路径,目标文件已部署且具备执行权限。 - 报依赖找不到:检查
Requires=、Wants=、After=中的单元名,或把配套单元一并传给verify。 - 校验通过但启动失败:执行
sudo systemctl daemon-reload后再启动,并读取journalctl -u <UNIT> -b --no-pager -n 100的首个错误。
指定服务进程的用户、用户组及所需目录权限。
配置服务运行用户
当服务不应以 root 运行,或需要把运行时、状态和日志目录交给固定账号管理时,在 [Service] 中设置 User=、Group=,并优先让 systemd 创建所需目录。这样可以同时收紧进程权限和目录权限,避免启动脚本里散落 mkdir、chown。
配置位置
不要直接修改软件包提供的 unit 文件。使用 drop-in 覆盖配置,升级软件包时不会被覆盖。先用 systemctl cat <服务名> 确认原始 unit、已有 drop-in 和实际的 [Service] 配置来源。
推荐配置
下面以已存在的 myapp.service 为例。先建立不可登录的系统账号,再写入 drop-in;RuntimeDirectory=、StateDirectory= 和 LogsDirectory= 会分别管理 /run/myapp、/var/lib/myapp、/var/log/myapp。
set -euo pipefail
SERVICE=myapp.service
ACCOUNT=myapp
NOLOGIN=$(command -v nologin || printf '/usr/sbin/nologin')
# 仅在账号或组不存在时创建,避免覆盖现有 UID/GID。
getent group "$ACCOUNT" >/dev/null || sudo groupadd --system "$ACCOUNT"
getent passwd "$ACCOUNT" >/dev/null || \
sudo useradd --system --gid "$ACCOUNT" --home-dir /var/lib/myapp \
--no-create-home --shell "$NOLOGIN" "$ACCOUNT"
sudo install -d -m 0755 "/etc/systemd/system/${SERVICE}.d"
sudo tee "/etc/systemd/system/${SERVICE}.d/20-runtime-user.conf" >/dev/null <<'EOF'
[Service]
User=myapp
Group=myapp
RuntimeDirectory=myapp
RuntimeDirectoryMode=0750
StateDirectory=myapp
StateDirectoryMode=0750
LogsDirectory=myapp
LogsDirectoryMode=0750
UMask=0027
EOF
# verify 成功通常无输出;随后重载配置并重启进程。
sudo systemd-analyze verify "$SERVICE"
sudo systemctl daemon-reload
sudo systemctl restart "$SERVICE"预期结果:
<无输出;命令退出码为 0,服务已按新账号重新启动>验证结果
读取 unit 的最终属性,并检查 systemd 管理目录的属主和权限。MainPID 是动态值;目录应由 myapp:myapp 持有,模式应为 0750。
SERVICE=myapp.service
sudo systemctl show "$SERVICE" \
-p User -p Group -p UMask \
-p RuntimeDirectory -p StateDirectory -p LogsDirectory -p MainPID
sudo stat -c '%A %U:%G %n' \
/run/myapp /var/lib/myapp /var/log/myapp预期输出:
User=myapp
Group=myapp
UMask=0027
RuntimeDirectory=myapp
StateDirectory=myapp
LogsDirectory=myapp
MainPID=<PID>
drwxr-x--- myapp:myapp /run/myapp
drwxr-x--- myapp:myapp /var/lib/myapp
drwxr-x--- myapp:myapp /var/log/myapp常用补充
服务还需访问共享设备、套接字或文件组时,可增加 SupplementaryGroups=<组名>,但目标组必须预先存在。已有业务目录不受上述目录指令管理,应使用精确的 install -d -o myapp -g myapp -m 0750 <目录> 或 ACL 授权,不要对大目录递归 chown。
无固定身份要求且服务基本无状态时,可评估 DynamicUser=yes。它会分配临时身份,并应配合 systemd 管理的目录使用;不要同时再指定固定 User=,也不要让业务依赖稳定 UID。
风险与排障
切换运行用户后,配置文件、证书、Unix Socket、设备节点或已有数据目录不可读写时,服务会以 Permission denied 失败。先查看 journalctl -u myapp.service -b 定位具体路径,再只修正该路径的属组、模式或 ACL,安全替代方案不是恢复为 root 或执行 chmod -R 777。
若程序需要监听低于 1024 的端口,不要仅为此使用 root。优先改用高端口并由反向代理转发;确需直连时,再最小化配置 CAP_NET_BIND_SERVICE。修改 drop-in 后必须执行 daemon-reload,并重启服务;仅 reload 通常不会替换进程身份。
较老的 systemd 可能不支持全部目录指令。用 systemd --version 和本机 man systemd.exec 核对;不支持时改由 tmpfiles.d 或部署脚本预创建目录,并保持同等的属主和权限。
为服务设置固定环境变量或加载独立环境文件。
配置服务环境变量
当服务需要固定运行参数,或不同环境需要独立维护一组变量时,在 [Service] 中使用 Environment= 或 EnvironmentFile=。少量稳定值可直接写入 drop-in;变量较多、需要独立发布时使用环境文件,修改后重启服务才能进入新进程。
选择方式
Environment="KEY=value" 适合少量值,包含空格时应给完整赋值加引号。EnvironmentFile=/path/file 从文件逐行读取 KEY=value;路径前加 - 表示文件缺失时忽略。systemd 不会自动加载 /etc/default/* 或 /etc/sysconfig/*,除非 unit 明确引用。
推荐配置
下面为 myapp.service 设置固定日志级别,并从独立文件加载运行模式和端口。环境文件由 root 管理,服务账号不应拥有写权限,防止进程自行篡改下次启动参数。
set -euo pipefail
SERVICE=myapp.service
sudo install -d -m 0755 /etc/myapp
sudo install -d -m 0755 "/etc/systemd/system/${SERVICE}.d"
sudo install -m 0600 -o root -g root /dev/null /etc/myapp/myapp.env
sudo tee /etc/myapp/myapp.env >/dev/null <<'EOF'
APP_MODE=production
HTTP_PORT=8080
EOF
sudo tee "/etc/systemd/system/${SERVICE}.d/30-environment.conf" >/dev/null <<'EOF'
[Service]
Environment="LOG_LEVEL=info"
EnvironmentFile=/etc/myapp/myapp.env
EOF
# 配置语法通过后,重载 unit 并重启进程以获取新环境。
sudo systemd-analyze verify "$SERVICE"
sudo systemctl daemon-reload
sudo systemctl restart "$SERVICE"预期结果:
<无输出;命令退出码为 0,服务已使用新环境重新启动>验证实际进程
不要只检查文件内容,应读取正在运行进程的环境,确认变量确实进入新进程。MainPID 必须大于 0;Type=oneshot 等没有常驻主进程的服务,应改用应用日志或服务自带的诊断命令验证。
set -euo pipefail
SERVICE=myapp.service
pid=$(systemctl show "$SERVICE" -p MainPID --value)
test "$pid" -gt 0
sudo cat "/proc/$pid/environ" \
| tr '\0' '\n' \
| grep -E '^(APP_MODE|HTTP_PORT|LOG_LEVEL)=' \
| sort预期输出:
APP_MODE=production
HTTP_PORT=8080
LOG_LEVEL=info语法边界
环境文件不是 Shell 脚本:不要写 export KEY=value、命令替换 $(...) 或依赖 ${OTHER_VAR} 展开。值中包含空格、# 或分号时,应按 systemd.exec 支持的引用规则加引号,并在变更后运行 systemd-analyze verify。
多个 drop-in 或环境文件重复设置同名变量时,最终有效值受加载顺序和覆盖关系影响。用 systemctl cat myapp.service 检查所有片段,避免只查看自己新建的文件。需要删除旧变量时,使用 UnsetEnvironment=KEY,不要把空字符串误当作“未设置”。
风险与排障
把密码、令牌或私钥写入 Environment=、环境文件或命令行,可能被有权限读取 unit、D-Bus、进程环境或诊断信息的主体看到。安全替代方案是使用 systemd credentials(如 LoadCredential=)、专用密钥文件或外部密钥服务,并只向服务授予最小读取权限。
必需的 EnvironmentFile= 不存在、格式错误或不可读时,服务可能启动失败;只有确实允许缺失的可选文件才使用前导 -。修改 unit 或 drop-in 后漏执行 daemon-reload,systemd 仍使用旧定义;只 reload 应用但不重启进程,也通常不会更新现有环境。
若变量已进入进程但应用行为未变化,检查应用是否读取了不同的变量名、启动参数是否覆盖环境值,以及包装脚本是否主动清理环境。排障时先比较 /proc/<PID>/environ 与应用日志,不要反复扩大文件权限。
根据退出类型设置自动重启条件、等待时间和重试边界。
配置自动重启策略
用于让长期运行服务在异常退出后自动恢复,并通过等待时间与启动频率限制避免重启风暴。生产环境通常从 Restart=on-failure 开始,再按业务退出码补充“禁止重启”或“强制重启”边界。
基本配置
把策略写入 drop-in,避免直接修改发行版提供的原始单元。下面假设服务名为 my-api.service;执行前先用 systemctl status my-api.service 确认单元名。
sudo mkdir -p /etc/systemd/system/my-api.service.d
sudo tee /etc/systemd/system/my-api.service.d/restart.conf >/dev/null <<'EOF'
[Unit]
# 60 秒内最多允许 5 次启动;超过后进入 failed,阻止无限拉起
StartLimitIntervalSec=60s
StartLimitBurst=5
[Service]
# 仅在非零退出码、异常信号、超时或看门狗失败时重启
Restart=on-failure
RestartSec=5s
# 约定 64/78 为参数或配置错误,继续重启通常没有意义
RestartPreventExitStatus=64 78
EOF
sudo systemctl daemon-reload
systemctl show my-api.service \
-p Restart \
-p RestartUSec \
-p StartLimitIntervalUSec \
-p StartLimitBurst \
-p RestartPreventExitStatus预期输出:
Restart=on-failure
RestartUSec=5s
StartLimitIntervalUSec=1min
StartLimitBurst=5
RestartPreventExitStatus=64 78字段顺序可能不同;看到这些值说明 manager 已读取新策略。daemon-reload 不等于重启进程,只有确需重新执行启动流程时才在维护窗口运行 sudo systemctl restart my-api.service。
策略选择
Restart=on-failure 适合常驻服务:正常退出不拉起,异常退出自动恢复。Restart=always 连退出码 0 也会拉起,适合进程本应永久驻留且“主动退出也算故障”的场景,但 systemd 主动执行 stop 时不会因此再次启动。
Restart=on-abnormal 只覆盖异常信号、超时、看门狗等非正常终止;应用以非零退出码报告错误时不会重启。Restart=no 是默认值,适合一次性任务或由外部编排器负责恢复的服务。
需要按退出原因微调时,可使用 RestartPreventExitStatus= 阻止特定失败码重启,或使用 RestartForceExitStatus= 强制某些退出码或信号触发重启。退出码约定必须与应用实际行为一致,不能照抄示例数字。
重试边界与状态读取
RestartSec= 控制两次启动之间的等待时间;过短会放大 CPU、磁盘、网络和日志压力。StartLimitIntervalSec= 与 StartLimitBurst= 统计启动次数,达到阈值后停止尝试并把单元置为 failed。
排障时读取以下属性:
systemctl show my-api.service \
-p ActiveState \
-p SubState \
-p Result \
-p NRestarts预期输出:
ActiveState=<STATE>
SubState=<SUBSTATE>
Result=<RESULT>
NRestarts=<COUNT>SubState=auto-restart 表示正在等待下一次拉起;Result=exit-code 或 signal 指向最近一次失败类型;NRestarts 是本次 manager 生命周期内已执行的自动重启次数,实际值会变化。
风险与边界
当 RestartSec 很短且 StartLimitBurst 很大时,持续失败会形成重启风暴,后果是日志爆量、依赖被反复冲击和节点资源耗尽。安全做法是设置秒级退避与有限突发次数,并先修复根因再恢复服务。
当应用因永久性配置错误退出,却仍返回普通失败码时,on-failure 会重复尝试。应让应用返回可识别的退出码,并通过 RestartPreventExitStatus= 停止无效重试;不要用无限重启掩盖配置错误。
Type=oneshot 不适合 Restart=always 或 on-success。一次性作业需要周期执行时使用 timer;只需失败后重试时再评估 on-failure,并确保任务本身幂等。
排障清单
先查看 systemctl status my-api.service 与 journalctl -u my-api.service -b,确认是退出码、信号、超时还是启动频率限制。出现 start-limit-hit 后,先修复程序、权限、端口或配置问题,再执行 sudo systemctl reset-failed my-api.service 清除限制状态。
若策略看似未生效,使用 systemctl cat my-api.service 确认 drop-in 已合并,并检查是否有后加载的文件覆盖同名指令。最后用 systemd-analyze verify my-api.service 检查单元语法;不同 systemd 版本的诊断文字可能不同。
使用顺序和依赖指令控制服务启动前提及停止传播关系。
配置启动顺序与依赖
用于控制“哪些单元会被一起拉起、谁先进入启动阶段、停止或重启是否传播”。最常见的正确组合是用 Wants= 或 Requires= 建立依赖,再用 After= 明确顺序;只写其中一类通常不能表达完整意图。
先区分依赖与顺序
Wants= 会拉起目标单元,但目标失败通常不阻止当前单元继续启动;Requires= 是更强依赖,目标启动失败时当前单元也会失败。After= 与 Before= 只建立先后关系,不会自动拉起任何单元。
Requisite= 不会启动目标,只在目标当前未激活时让本单元立即失败。PartOf= 传播目标单元的停止与重启操作,但不负责启动。BindsTo= 适合生命周期强绑定:目标意外消失或变为 inactive 时,本单元也应停止。

基本配置
下面通过 drop-in 让 API 弱依赖网络就绪目标,并强依赖 PostgreSQL;两个依赖都排在 API 之前。不同发行版的数据库单元名可能不是 postgresql.service,应先用 systemctl list-unit-files | grep -i postgres 核对。
sudo mkdir -p /etc/systemd/system/my-api.service.d
sudo tee /etc/systemd/system/my-api.service.d/dependencies.conf >/dev/null <<'EOF'
[Unit]
# 拉起网络就绪目标,但目标失败时仍允许服务继续尝试启动
Wants=network-online.target
After=network-online.target
# 数据库必须被拉起,并先完成其 systemd 启动阶段
Requires=postgresql.service
After=postgresql.service
EOF
sudo systemctl daemon-reload
systemctl show my-api.service \
-p Wants \
-p Requires \
-p After预期输出:
Wants=network-online.target <OTHER_UNITS>
Requires=postgresql.service <OTHER_UNITS>
After=network-online.target postgresql.service <OTHER_UNITS><OTHER_UNITS> 表示原单元和默认依赖带来的其他项目,顺序也可能不同。关键是对应字段中能找到目标单元;若不存在,优先检查单元名、drop-in 路径和是否执行了 daemon-reload。
停止与重启传播
需要“停止整个应用栈时同时停止 API”时,可在 API 的 [Unit] 中加入 PartOf=app-stack.target。但 PartOf= 不会让目标启动时自动启动 API,还需由 app-stack.target 的 Wants= 或 API 的 [Install] 中 WantedBy=app-stack.target 建立拉起关系。
需要“数据库一旦意外失活,API 也立即停止”时,使用 BindsTo=postgresql.service 并保留 After=postgresql.service。这比单独 Requires= 更严格,触发条件包括依赖单元被跳过、卸载或意外转为 inactive;后果是业务服务同步停止,使用前必须确认这是期望的故障隔离策略。
验证关系与启动链
systemctl list-dependencies my-api.service --plain 查看当前单元会拉起的依赖;systemctl list-dependencies postgresql.service --reverse --plain 查看反向依赖。systemd-analyze critical-chain my-api.service 用于定位启动链中耗时最长的单元,但它展示的是实际启动时间,不等同于完整依赖图。
若服务“数据库已 active 但仍不可用”,说明依赖只保证 systemd 激活状态,不保证端口、迁移或业务健康检查完成。优先让依赖服务使用 Type=notify 正确上报 ready;无法改造时,再用受控的 ExecStartPre= 健康检查并设置超时,避免无限等待。
风险与边界
只配置 After=postgresql.service 时,PostgreSQL 不会因此被拉起,API 仍可能在依赖未启动的机器上失败。安全替代是同时添加 Wants= 或 Requires=,强弱取决于依赖失败后 API 是否还能提供有效服务。
只配置 Requires= 而不配置 After= 时,两个单元可能并行启动;依赖存在不代表先后顺序。对必须先完成初始化的服务,应显式组合 Requires= 与 After=。
network-online.target 只有在对应的 wait-online 服务启用并正确配置时才代表网络达到预期状态,否则可能很快结束或长期等待。生产环境应限定等待超时,并以应用真正需要的地址、路由或端口作为最终可用性判断。
互相设置 After=、Before= 或形成跨多个单元的闭环会产生 ordering cycle,systemd 可能丢弃部分作业或导致启动失败。出现循环提示时,使用 systemd-analyze verify my-api.service 和启动日志定位闭环,不要通过继续叠加依赖掩盖设计问题。
排障清单
先用 systemctl cat my-api.service 确认最终合并结果,再用 systemctl show -p Wants -p Requires -p After -p Before -p PartOf -p BindsTo my-api.service 查看 manager 实际认知。依赖单元未找到时检查完整名称与实例参数;启动顺序异常时检查是否把“拉起关系”和“排序关系”混为一谈。
停止传播不符合预期时,确认关系写在哪一侧:PartOf=app-stack.target 写在 API 上,表示 target 的停止或重启传播给 API;它不是对称关系。修改后执行 daemon-reload,再在维护窗口验证启动、停止和失败场景。