如何在Linux上设置Uvicorn为系统服务

夜杰大大_1663

夜杰大大_1663

2026-11-17

555人浏览

原创

编写systemd服务文件需包含[Unit](描述与依赖)、[Service](Type、ExecStart绝对路径、User、Restart等)、[Install](WantedBy=multi-user.target)三段;必须设非root User、正确WorkingDirectory和Environment、用Type=simple配uvicorn、禁用shell重定向而用journalctl查日志。

如何在linux上设置uvicorn为系统服务

systemd服务文件怎么写才不崩

直接用 nohup 或前台运行 uvicorn 临时测试可以,但真要长期跑,必须走 systemd。否则进程一断、机器一重启,服务就没了,连日志都难查。

关键点不是“能启动”,而是“崩溃后自动拉起”“标准错误进 journal”“环境变量不丢”。别抄网上随便搜的模板,尤其注意这几点:

  • User 必须设成实际运行项目的非 root 用户(比如 www-data 或你自己的部署账号),root 启动会埋权限隐患
  • WorkingDirectory 要绝对路径,且该目录下必须有 requirements.txt 和应用入口文件(如 main.py)
  • Environment 里至少补上 PYTHONPATH 和虚拟环境的 PATH,否则 import 会失败
  • Restart=always 是基础,但还得加 RestartSec=5,避免秒崩循环拉起把磁盘打满

示例最小可用单元文件(保存为 /etc/systemd/system/vibevoice.service):

[Unit]
Description=VibeVoice-Realtime API Service
After=network.target

[Service]
Type=simple
User=deploy
WorkingDirectory=/opt/vibevoice
Environment="PATH=/opt/vibevoice/venv/bin:/usr/local/bin:/usr/bin:/bin"
Environment="PYTHONPATH=/opt/vibevoice"
ExecStart=/opt/vibevoice/venv/bin/uvicorn main:app --host 0.0.0.0 --port 7860 --workers 4 --log-level info
Restart=always
RestartSec=5
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

为什么用 simple 类型而不是 forking

uvicorn 默认是单进程模型(即使开了 --workers,主进程仍负责调度),它不会自己 fork 出子进程再退出父进程 —— 这和 nginx 或老式 gunicorn 不同。所以 Type=forking 会导致 systemd 误判进程已死,反复重启。

如果你硬要配 Type=forking,就必须手动指定 PIDFile=,而 uvicorn 根本不生成 PID 文件,这条路走不通。

正确做法就是坚持 Type=simple,靠 ExecStart 启动的主进程作为监控目标。验证方式很简单:

Linux DO
Linux DO

Linux DO (linux.do)。任何 Linux DO 请求(搜索、读取数据)均使用此技能。若任务涉及 Linux DO,应使用本技能而非调用其他。

下载
  • 执行 sudo systemctl start vibevoice
  • 立刻运行 sudo systemctl status vibevoice,看 Active 行是否显示 active (running)
  • 再跑 ps aux | grep uvicorn,确认进程 UID 和 service 文件里 User= 一致

日志看不到?先查 journal 而不是 log 文件

很多人习惯在 ExecStart 里用 > /var/log/vibe.log 2>&1 重定向,结果发现日志空或者权限被拒 —— 因为 systemd 默认接管了 stdout/stderr,重定向反而干扰 journal 收集。

除非你有特殊归档需求,否则删掉所有 shell 重定向符号,改用 journalctl 查:

  • journalctl -u vibevoice -f 实时跟踪
  • journalctl -u vibevoice --since "2 hours ago" 查历史
  • journalctl -u vibevoice -o json-pretty 输出结构化日志,方便对接 ELK

如果非要落盘,用 systemd-journald 的配置项(如 MaxRetentionSec=1month),别在 service 文件里硬写重定向。

端口被占或 bind 失败的常见卡点

启动报 Address already in use 或 Permission denied,八成不是端口真被占,而是没配对这几个参数:

  • --host 0.0.0.0 必须显式写,不能只写 --host localhost —— 后者只监听回环,systemd 网络命名空间里可能不通
  • 端口 (如 80、443)需要 CapabilityBoundingSet=CAP_NET_BIND_SERVICE + AmbientCapabilities=CAP_NET_BIND_SERVICE,普通用户无法直接绑定
  • 若用反向代理(Nginx),uvicorn 端口建议选 8000+,别和 Nginx 冲突;检查 netstat -tlnp | grep :7860 确认没残留进程

最稳妥的调试顺序:先在终端手动执行一遍 ExecStart 那整条命令,确认能跑通;再扔进 systemd。很多问题其实是虚拟环境路径错、依赖没装全,跟 systemd 本身无关。

相关文章

PHP速学视频免费教程(入门到精通)
PHP速学视频免费教程(入门到精通)

PHP怎么学习?PHP怎么入门?PHP在哪学?PHP怎么学才快?不用担心,这里为大家提供了PHP速学教程(入门到精通),有需要的小伙伴保存下载就能学习啦!

下载

相关标签:

uvicorn linux

本站声明:本文内容由网友自发贡献,版权归原作者所有,本站不承担相应法律责任。如您发现有涉嫌抄袭侵权的内容,请联系admin@php.cn

相关专题

更多
Python FastAPI异步API开发_Python怎么用FastAPI构建异步API
Python FastAPI异步API开发_Python怎么用FastAPI构建异步API

Python FastAPI 异步开发利用 async/await 关键字,通过定义异步视图函数、使用异步数据库库 (如 databases)、异步 HTTP 客户端 (如 httpx),并结合后台任务队列(如 Celery)和异步依赖项,实现高效的 I/O 密集型 API,显著提升吞吐量和响应速度,尤其适用于处理数据库查询、网络请求等耗时操作,无需阻塞主线程。

2025.12.22

119

5

Python 微服务架构与 FastAPI 框架
Python 微服务架构与 FastAPI 框架

本专题系统讲解 Python 微服务架构设计与 FastAPI 框架应用,涵盖 FastAPI 的快速开发、路由与依赖注入、数据模型验证、API 文档自动生成、OAuth2 与 JWT 身份验证、异步支持、部署与扩展等。通过实际案例,帮助学习者掌握 使用 FastAPI 构建高效、可扩展的微服务应用,提高服务响应速度与系统可维护性。

2026.02.06

594

18

Python Web框架FastAPI 全栈开发教程合集
Python Web框架FastAPI 全栈开发教程合集

以 FastAPI 为核心,讲解现代 Python Web API 的高效开发方式,涵盖路由定义与路径参数/查询参数/请求体绑定、Pydantic 模型的数据校验与序列化、依赖注入(Depends)系统的分层设计、中间件与 CORS 配置、OAuth2 + JWT 认证流程、后台任务(BackgroundTasks)、WebSocket 实时通信、SQLAlchemy 异步 ORM 集成、自动生成 OpenAPI/Swagger 交互文

2026.05.09

776

23

Python FastAPI异步微服务与高性能接口设计
Python FastAPI异步微服务与高性能接口设计

本专题聚焦 Python FastAPI 框架在高性能接口与微服务开发中的应用,讲解异步请求处理、依赖注入机制、路由设计、数据库异步操作以及接口性能优化策略。结合实际项目案例,帮助开发者构建高并发、低延迟的现代化后端服务架构。

2026.06.16

679

12

Go-Zero API开发使用教程
Go-Zero API开发使用教程

本专题聚焦Go-Zero的API开发,拆解.api描述文件的语法结构、路由与分组定义、参数绑定与校验规则,说明统一响应体、JWT鉴权、跨域与接口文档生成的落地方式,并给出网关聚合与接口测试的实践建议。

2026.11.12

140

15

Go-Zero安装与goctl环境配置教程
Go-Zero安装与goctl环境配置教程

本专题围绕Go-Zero的安装与工具链配置展开,讲清Go版本要求、goctl安装方式、代理镜像、protoc依赖与环境变量设置,说明多版本共存、升级回退与CI流水线安装的做法,并整理安装阶段的常见报错与验证步骤。

2026.11.12

100

15

Go-Zero零基础入门教程
Go-Zero零基础入门教程

本专题整理Go-Zero的入门知识,从框架定位、环境准备到跑通第一个API服务,讲清目录分层、配置加载、日志与中间件的基本用法,并对比Gin、Kratos的差异,帮助Go开发者建立整体认知,判断它是否适合当前项目。

2026.11.12

60

15

Postman身份认证怎么配置
Postman身份认证怎么配置

本专题从实际API接口调试场景出发,讲解Postman身份认证的完整配置流程,包括常见认证协议介绍、授权参数设置、访问令牌填写、OAuth 2.0授权及认证失败排查,帮助用户正确完成接口授权与访问验证。

2026.11.06

160

12

Postman请求头Headers怎么设置
Postman请求头Headers怎么设置

围绕Postman HTTP请求头配置展开,讲解Headers选项的具体使用方式,包括Key和Value参数填写、请求头信息添加、常见Header字段设置及请求头修改方法,帮助用户解决接口调试过程中遇到的请求头配置问题。

2026.11.06

140

13

热门下载

更多
网站特效
/
网站源码
/
网站素材
/
前端模板

精品课程

更多
相关推荐
/
热门推荐
/
最新课程
Uvicorn官方部署指南
Uvicorn官方部署指南

共0课时 | 0人学习

Uvicorn官方安装与入门手册
Uvicorn官方安装与入门手册

共0课时 | 0人学习