Linux 服务启动失败怎么查：systemctl 与 journalctl 排障指南

服务启动失败时，反复重启机器或把目录权限改成 777，往往会掩盖真正原因。用 systemd 管理的服务，可以按“状态 → 日志 → 配置 → 可用性”的顺序排查。下面以 my-api.service 为例，单元名、用户名和路径请替换成你环境中的实际值。

1. 先看 systemd 观察到的状态

先查看服务状态和最近日志：

systemctl status my-api.service --no-pager

重点看 Active 状态、主进程退出码和最后几行错误。active (running) 表示 systemd 认为进程仍在运行，并不代表 API 已经能正常处理请求。

2. 按服务和启动周期筛选日志

# 查看当前开机周期内该服务的日志
journalctl -u my-api.service -b --no-pager

# 只看最近 10 分钟
journalctl -u my-api.service --since "10 minutes ago" --no-pager

# 持续跟踪新日志，按 Ctrl+C 退出
journalctl -fu my-api.service

遇到 No such file or directory，先核对 ExecStart 和 WorkingDirectory 的路径；看到 Permission denied，检查服务运行用户、目录访问权限和可执行文件权限；如果报端口已占用，再确认是否已有进程监听目标端口。不要一上来就扩大权限。

3. 检查实际生效的 unit 配置

systemctl cat my-api.service
systemctl show my-api.service -p FragmentPath -p User -p WorkingDirectory -p ExecStart
systemd-analyze verify /etc/systemd/system/my-api.service

systemctl cat 可以查看单元文件及其覆盖配置；systemctl show 适合核对关键生效属性；systemd-analyze verify 可以检查指定 unit 文件中的配置问题。若服务依赖环境变量，不要假设交互式终端里的变量也会自动传给 systemd；可以用受限权限的环境文件显式配置，并避免把密钥写进公开文章或宽权限文件。

一个精简的 Python API 单元示例：

[Unit]
Description=My Python API
After=network.target

[Service]
Type=simple
User=deploy
WorkingDirectory=/srv/my-api
ExecStart=/srv/my-api/.venv/bin/uvicorn app:app --host 127.0.0.1 --port 8000
Restart=on-failure
RestartSec=3

[Install]
WantedBy=multi-user.target

请确认 deploy 用户确实存在，并且能读取项目文件、访问工作目录。若应用启动时需要连接数据库或其他网络服务，应用本身应做好重试；单靠 After=network.target 不能证明依赖服务已经就绪。

4. 修改后重新加载并验证

修改 unit 文件后，先让 systemd 重新读取配置，再重启服务：

sudo systemctl daemon-reload
sudo systemctl restart my-api.service
systemctl status my-api.service --no-pager

daemon-reload 用于重新读取 unit 文件；restart 会重启进程。reload 通常是让应用重载自身配置，只有服务明确支持时才使用，两者不能互相替代。

最后从应用接口确认服务已可用：

curl -fsS http://127.0.0.1:8000/health

如果没有 /health 路由，就替换为项目实际提供的健康检查地址。对于只能本机访问的绑定地址，还要结合反向代理和防火墙单独检查外部访问链路。

一套可复用的排查顺序

1. systemctl status：确认状态、退出码和最近错误。
2. journalctl -u：按服务、启动周期和时间范围找日志。
3. systemctl cat/show：核对 unit 文件和生效属性。
4. 修复单一原因后执行 daemon-reload 与 restart，再检查日志。
5. 用 HTTP 健康接口验证服务可用，而不是只看进程存在。

更多选项可查阅 systemd 官方手册中的 systemctl、journalctl 与 systemd.service 章节。