linux Troubleshooting
systemd 服务启动失败排查流程
systemctl 启动服务后 status 显示 failed、exit-code 或 status=203/EXEC 时，用 journalctl -u <service> -n 200 读取完整错误，检查 ExecStart 是否绝对路径、WorkingDirectory 是否存在且服务用户有权限，改 unit 后必须 daemon-reload。
先看 journalctl 的真实错误，而不是只看 systemctl status 的摘要。多数问题是 ExecStart 路径、WorkingDirectory、用户权限或环境变量。
Scenario
这篇文章解决什么问题
适用于 systemctl start 后服务 status 显示 failed (exit-code) 或 status=203/EXEC 的场景。排查核心是看 journalctl 的真实错误，而不是只看 status 摘要。
Symptoms
典型现象
- systemctl status <service> 显示 Active: failed (Result: exit-code)。
- status=203/EXEC 表示 ExecStart 命令找不到或不可执行。
- status=1 表示应用启动后异常退出，需要看 journalctl 具体报错。
- 手动执行 ExecStart 命令能跑，但 systemd 启动就失败。
Before Debugging
排查前先确认
- 先确定故障资源：CPU、内存、磁盘、网络、权限、文件句柄还是 systemd 生命周期。
- 区分当前状态和故障发生时状态，事故恢复后 free/top 可能已经看不出根因。
- 任何清理或 kill 操作前先记录 PID、命令行、日志和影响范围。
Root Causes
常见根因分层
资源耗尽或限制过低
磁盘、内存、CPU、load、文件句柄和进程数限制都会让服务表现为启动失败、连接失败或随机超时。
- 先看系统级指标，再看进程级指标
- 确认 systemd/cgroup 限制
- 保留 dmesg/journalctl 历史证据
运行环境和交互 shell 不一致
systemd 服务没有你的 shell 环境变量、工作目录和 PATH；手动能跑不代表服务单元能跑。
- ExecStart 使用绝对路径
- 设置 WorkingDirectory 和 EnvironmentFile
- 修改 unit 后 daemon-reload
文件、权限和句柄生命周期异常
权限不对、文件已删除但仍被进程持有、日志无限增长、fd 泄漏都会造成表象复杂的问题。
- 用 lsof +L1 查 deleted 文件
- 检查目录权限和属主
- 看 /proc/<pid>/limits
Diagnosis Path
分步诊断流程
1. 固定现场，避免追着变化状态跑
先记录故障时间、影响入口、完整错误和最近一次变更。systemd 服务启动失败排查流程 这类问题经常在重启、重试或缓存刷新后短暂消失，没有现场信息会很难复盘。
- 截图或保存完整错误文本
- 记录请求域名/IP/端口/namespace/服务名
- 标出最近发布、配置、证书、镜像或依赖变更
systemctl status <service> --no-pager
journalctl -u <service> -n 200 --no-pager2. 在故障发生的同一位置复现
很多误判来自测试位置不同：本机通不代表服务器通，容器内通不代表宿主机通，集群外通也不代表 Pod 内通。复现命令要尽量贴近真实流量路径。
- 从报错服务所在机器执行测试
- 必要时加 Host、SNI、namespace 或代理参数
- 把成功路径和失败路径的输出并排比较
journalctl -u <service> -n 200 --no-pager
systemd-analyze verify /etc/systemd/system/<service>.service
sudo systemctl daemon-reload3. 读取服务端证据，而不是只看客户端提示
客户端报错通常是结果摘要。真正能区分根因的是服务端日志、内核日志、事件、进程状态或数据库状态。
- 读取 journalctl 完整错误。
- 确认 ExecStart 使用绝对路径。
- 确认 WorkingDirectory 存在且服务用户有权限。
systemd-analyze verify /etc/systemd/system/<service>.service
sudo systemctl daemon-reload4. 做最小修复并立即回归验证
每次只改一个变量，修复后用同一条复现命令回测，并观察日志是否停止增长。这样可以避免多个临时改动互相掩盖。
- 确认 WorkingDirectory 存在且服务用户有权限。
- 修改 unit 后执行 daemon-reload。
- 必要时加 Environment 或 EnvironmentFile。
systemd-analyze verify /etc/systemd/system/<service>.service
sudo systemctl daemon-reloadCommands
排查命令与使用意图
命令 1
用于确认服务当前运行状态、退出码和最近日志。重点看 Active 行和 Main PID。
systemctl status <service> --no-pager命令 2
用于读取 systemd 或内核在故障时间附近记录的真实错误，比 status 摘要更完整。重点看时间、退出码、权限、路径和依赖失败。
journalctl -u <service> -n 200 --no-pager命令 3
用于补充“systemd 服务启动失败排查流程”的排查证据链。systemd-analyze 的输出需要结合上下文其他命令交叉验证，不要单独依赖某一条结果下结论。
systemd-analyze verify /etc/systemd/system/<service>.service命令 4
用于补充“systemd 服务启动失败排查流程”的排查证据链。sudo 的输出需要结合上下文其他命令交叉验证，不要单独依赖某一条结果下结论。
sudo systemctl daemon-reloadRisk Notes
容易踩坑的地方
- ExecStart 必须使用绝对路径（如 /usr/bin/node），systemd 不走 PATH 查找，写 node 会报 203/EXEC。
- systemd 环境变量、工作目录和用户权限与交互 shell 完全不同，手动能跑但 systemd 不能跑是典型问题。
- 修改 unit 文件后必须 systemctl daemon-reload，否则 systemd 用旧配置。
Verification
修复后怎么确认
- 原始故障现象已经消失，且使用同一入口重新测试 systemd 服务启动失败 能稳定成功。
- 服务端日志不再出现同类错误，监控中的错误率、重启次数、连接数或延迟回到正常区间。
- 如果做过临时绕过，已经记录恢复计划，例如还原宽松策略、补监控、补限制或提交正式配置。
Prevention
后续预防
- 用 systemd-analyze verify /etc/systemd/system/<service>.service 在启动前检查 unit 文件语法。
- 在 unit 文件中显式设置 WorkingDirectory、User、Environment，不依赖 shell 环境。
- 为关键服务配置 Restart=on-failure 和 StartLimitBurst，避免崩溃后不自动恢复。
常见问题
为什么命令手动能跑，systemd 不能跑？
systemd 环境变量、工作目录和用户权限与交互 shell 不同。
Long-tail SEO
你可能正在搜索这些报错
下面这些错误原文、场景词和中英文搜索词，都是排查同类问题时常见的入口。
- systemd service failed with result exit-code
- systemd status code=exited status=203/EXEC
- systemd ExecStart 路径错误
- systemd WorkingDirectory 权限
- journalctl 查看服务启动失败
- systemctl daemon-reload 后仍失败
- systemd 环境变量不生效
- Main process exited code=exited status=1/FAILURE
Need More Help
这个问题还没完全解决？
把你的报错、环境和已经尝试过的步骤发给我，后续会优先补充到排障手册。