fastapi 项目不挂断运行
2026/3/23大约 4 分钟
问题背景
在 Linux 服务器部署 FastAPI 项目时，直接通过命令行启动会存在两个核心问题：
- 关闭 SSH 连接后，项目进程自动终止，无法后台不挂断运行；
- 服务器重启后，项目不会自动启动，需要手动重新运行，无法满足生产环境稳定性要求。
systemd 是 Linux 系统自带的服务管理工具，无需额外安装，可完美实现：FastAPI 项目后台持久运行、服务器重启自动启动、进程异常崩溃自动重启，是生产环境轻量稳定的部署方案。
前置条件
- 服务器系统：Ubuntu 16.04+/CentOS 7+（默认自带 systemd）；
- FastAPI 项目已上传至服务器，且手动启动命令可正常运行；
- 推荐使用 Python 虚拟环境隔离项目依赖；
- 已记录项目核心路径（项目目录、虚拟环境中 uvicorn/gunicorn 绝对路径）。
关键信息
进入项目目录
# 替换为你的项目实际路径
cd /home/dev/code/rag-xxmall激活虚拟环境
source venv/bin/activate测试启动命令
# 生产环境推荐：uvicorn 多进程启动
uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4测试成功后按 Ctrl+C 停止进程。
记录核心路径
执行以下命令获取绝对路径：
# 项目根目录
pwd
# 虚拟环境 uvicorn 绝对路径
which uvicorn操作步骤
创建 systemd 服务文件
服务文件必须存放于 /etc/systemd/system/ 目录，执行命令创建：
sudo vim /etc/systemd/system/rag-xxmall.service写入服务配置
将以下内容粘贴至文件中，修改为自己的实际路径：
[Unit]
Description=RAG-XXMALL Service
After=network.target network-online.target
Wants=network-online.target
[Service]
# 运行用户/用户组（服务器实际用户名）
User=dev
Group=dev
# 项目根目录（pwd 命令获取的路径）
WorkingDirectory=/home/dev/code/rag-xxmall
# 启动命令（which uvicorn 获取的绝对路径）
ExecStart=/home/dev/code/rag-xxmall/venv/bin/uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4
# 自动重启配置
Restart=always
RestartSec=5
# 日志文件路径
StandardOutput=append:/var/log/rag-xxmall.log
StandardError=append:/var/log/rag-xxmall.error.log
[Install]
WantedBy=multi-user.target保存退出：按 Esc → 输入 :wq → 回车。
提示
配置中 Restart=always 可保证项目崩溃、服务器重启后自动重启，是生产环境必备配置。
创建并授权日志文件
# 创建日志文件
sudo touch /var/log/rag-xxmall.log /var/log/rag-xxmall.error.log
# 授权给运行用户（避免权限报错）
sudo chown dev:dev /var/log/rag-xxmall.log /var/log/rag-xxmall.error.log
sudo chmod 644 /var/log/rag-xxmall.log /var/log/rag-xxmall.error.log提示
日志文件必须授权给服务运行用户，否则会因无权限写入日志导致服务启动失败。
加载配置并启动服务
# 重新加载 systemd 配置（必做）
sudo systemctl daemon-reload
# 后台启动服务
sudo systemctl start rag-xxmall.service
# 设置开机自启
sudo systemctl enable rag-xxmall.service
# 查看服务状态
sudo systemctl status rag-xxmall.service验证部署结果
- 后台运行验证：关闭 SSH 重新连接，执行状态查看命令，服务仍为
active (running)； - 开机自启验证：执行
sudo reboot重启服务器，重启后服务自动运行； - 访问验证：浏览器访问
http://服务器IP:8000/docs，可正常打开接口文档。
日常管理命令（高频使用）
# 1. 查看服务运行状态
sudo systemctl status rag-xxmall.service
# 2. 重启服务（修改代码后必执行）
sudo systemctl restart rag-xxmall.service
# 3. 停止服务
sudo systemctl stop rag-xxmall.service
# 4. 关闭开机自启
sudo systemctl disable rag-xxmall.service
# 5. 实时查看标准日志
tail -f /var/log/rag-xxmall.log
# 6. 实时查看错误日志
tail -f /var/log/rag-xxmall.error.log
# 7. 查看 systemd 完整启动日志
journalctl -u rag-xxmall.service -f重要
修改项目代码后，必须重启服务才能生效，直接修改代码不会自动更新。
常见问题与注意事项
服务启动失败排查
# 查看详细报错日志
journalctl -u rag-xxmall.service -e常见原因：
- 路径错误：
WorkingDirectory或ExecStart路径填写错误； - 权限问题：日志文件/项目目录无读写权限；
- 端口占用：8000 端口被其他进程占用。
端口占用解决
# 查看端口占用进程
sudo lsof -i :8000
# 杀死占用进程
sudo kill -9 进程ID配置修改后操作
修改服务文件后，必须重新加载配置再重启服务：
sudo systemctl daemon-reload
sudo systemctl restart rag-xxmall.service注意
生产环境不建议使用 root 用户运行服务，使用普通用户可降低安全风险。
进程说明
服务启动后会显示多个子进程，这是 uvicorn --workers 多进程模式的正常现象，无需处理。
总结
通过 systemd 实现了 FastAPI 项目的：
- 后台不挂断运行，关闭 SSH 不受影响；
- 服务器重启自动启动；
- 进程异常自动重启；
- 日志持久化，方便问题排查；
- 轻量无依赖，Linux 系统直接使用。
完全满足生产环境稳定运行需求，是小型项目部署的最优方案。