Systemd 部署 Uvicorn‑FastAPI 生产服务

简介

uvicorn 新版本已经移除 daemon（守护进程）参数，不支持自带后台运行。生产环境推荐使用 Linux systemd 管理 FastAPI 服务，具备开机自启、程序异常自动重启、统一日志管理、服务状态管控能力。项目使用 Python 虚拟环境，无需手动执行source activate激活环境，直接调用虚拟环境内的 uvicorn 可执行文件。

注意：systemd 配置中所有路径必须使用绝对路径，禁止相对路径。

1、编写 systemd 服务配置文件

编辑 service 单元文件：

vim /etc/systemd/system/backend.service

 

 

模板内容，替换为你服务器上真实的绝对路径：

[Unit]
Description=FastAPI Backend Service
After=network.target

[Service]
User=root
# 项目根目录绝对路径
WorkingDirectory=/opt/backend
# 直接调用虚拟环境内的uvicorn，不要source激活虚拟环境
ExecStart=/opt/backend/venv/bin/uvicorn app.main:app --host 0.0.0.0 --port 8000
# 进程异常自动重启
Restart=always
# 崩溃后等待3秒重启
RestartSec=3

[Install]
# 系统开机时启动该服务
WantedBy=multi-user.target

 

参数说明：

• WorkingDirectory：项目所在目录，app.main需要在此目录下可以找到。
• ExecStart：使用虚拟环境 bin 目录下的 uvicorn 二进制程序。
• Restart=always：无论程序 crash、被 kill，都会自动重新拉起服务。
• RestartSec=3：服务停止后延迟 3 秒再重启。

2、systemd 常用管理命令

修改完 service 文件后，必须重载 systemd 配置：

# 重载配置
systemctl daemon-reload

# 启动服务
systemctl start backend

# 设置开机自启
systemctl enable backend

# 查看服务运行状态
systemctl status backend

# 实时跟踪服务日志
journalctl -u backend -f

# 修改代码后重启服务
systemctl restart backend

# 停止服务
systemctl stop backend

 

3、排错技巧

1. 服务启动失败，优先执行 systemctl status backend 看报错信息；
2. 排查端口占用：

 

ss -tulnp | grep 8000

 

3. 不要在 service 里写source ../venv/bin/activate，systemd 不支持 shell source 操作；直接调用 venv/bin 下可执行文件。

对比说明

对比 nohup 临时方案：nohup 适合测试，进程崩溃不会自动恢复、服务器重启服务丢失。systemd 适合正式上线，保证服务稳定性。

生产额外建议：uvicorn 建议搭配 gunicorn 多工作进程使用，不建议单 uvicorn 直接对外暴露公网，前面搭配 Nginx 反向代理。