Ubuntu 20.04系统重启后gunicorn.service启动失败排障求助

gunicorn返回的退出码3为官方定义的启动失败/配置未实现，结合你给出的systemd日志，服务启动34秒后才退出，常见诱因是启动时依赖的资源未就绪、配置文件错误、权限不足三类。

• 第一步：查看完整运行日志定位具体报错
  执行以下命令查看gunicorn服务的全量运行日志，直接定位具体错误点：

  journalctl -u gunicorn.service -f --no-pager
  

  常见日志报错对应问题：找不到gunicorn.py/main.py文件、Python依赖缺失、gunicorn配置语法错误、端口绑定失败、数据库/缓存等依赖服务连接失败。
• 第二步：手动验证服务启动有效性
  切换到服务指定的nols用户，手动执行启动命令验证是否可以正常运行：

  sudo -u nols /home/nols/fastapi/env/bin/gunicorn --config /home/nols/fastapi/gunicorn.py main:app
  

  如果手动执行也报错，问题和systemd配置无关，直接对应报错修复即可；如果手动执行正常，则问题出在systemd启动时序或环境变量配置上。
• 第三步：修复启动时序问题
  你当前的systemd配置仅配置了After=network.target，该目标仅代表系统网络管理服务启动，不代表网卡已经分配到可用IP，如果你在gunicorn配置中绑定了固定公网IP、或者启动需要访问远程资源，网络未就绪就会导致启动失败。修改gunicorn.service的[Unit]段为以下内容：

  [Unit]
  Description=Gunicorn Web Server as Unit Service Systemd - slimzulu.hopto.me
  After=network.target network-online.target
  Wants=network-online.target
  

  修改后执行sudo systemctl daemon-reload重载配置。
• 第四步：排查权限与特殊端口问题
  如果gunicorn配置中绑定了1024以下的端口，普通用户nols默认没有端口绑定权限，有两种解决方案：一是将绑定端口改为1024以上的高位端口，配合Nginx反向代理对外提供服务；二是给gunicorn执行文件加端口绑定权限：

  sudo setcap 'cap_net_bind_service=+ep' /home/nols/fastapi/env/bin/gunicorn
  

  同时确认nols用户对/home/nols/fastapi目录下所有文件有读写执行权限。
• 第五步：添加依赖服务等待配置
  如果你的FastAPI服务依赖MySQL、Redis等其他本地服务，需要在[Unit]段的After配置中添加对应服务，比如After=network.target network-online.target mysql.service redis.service；也可以添加启动延迟兜底，在[Service]段添加ExecStartPre=/bin/sleep 5，让服务晚5秒启动等待依赖就绪。

内容的提问来源于stack exchange，提问作者Nols Smit