讲师中心 微信公众号

工具推荐

视频效率加速
AniShort
AniShort

AI短剧协同制作平台

Seko
Seko

AI短剧一键生成成片

立刻MV
立刻MV

低成本歌曲 MV、视频生成

Laper
Laper

剧本策划到成片协作

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

夜杰大大_1663

夜杰大大_1663

发布时间:2026-11-17 05:41:49

|

555人浏览过

|

来源于php中文网

原创

编写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)需要 <code>CapabilityBoundingSet=CAP_NET_BIND_SERVICE + AmbientCapabilities=CAP_NET_BIND_SERVICE,普通用户无法直接绑定
  • 若用反向代理(Nginx),uvicorn 端口建议选 8000+,别和 Nginx 冲突;检查 netstat -tlnp | grep :7860 确认没残留进程

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

热门AI工具

更多
函子Zion

一款支持AI搭建、可视化编辑和多端发布的全栈无代码开发平台。

PixPix
PixPix Hot

PixPix是一款面向电商视觉生产的AI商品图生成工具。

豆包大模型

豆包大模型是一款由字节跳动推出的企业级大语言模型服务平台。

WorkBuddy

一款AI办公效率工具,主要用于腾讯云推出的AI原生桌面智能体工作台,适合需要提升相关任务效率的用户。

火山引擎

火山引擎是一款面向企业的云计算与AI服务平台。

DeepSeek

DeepSeek是一款面向对话、写作、编程和推理场景的AI大模型工具。

讯飞智文

一款面向学习和办公场景的AI文档创作工具,可辅助生成PPT与Word文档,提高资料整理和内容制作效率。

讯飞智作

讯飞智作是一款AI视频创作工具,AI文本配音工具,数字人课程、营销视频制作。

花生AI
花生AI Hot

一款AI视频创作工具,主要用于B站推出的AI视频创作工具,适合需要提升相关任务效率的用户。

相关专题

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

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

119

2025.12.22

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

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

594

2026.02.06

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

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

776

2026.05.09

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

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

679

2026.06.16

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

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

140

2026.11.12

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

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

100

2026.11.12

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

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

60

2026.11.12

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

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

160

2026.11.06

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

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

140

2026.11.06

热门下载

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

精品课程

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

共0课时 | 0人学习

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

共0课时 | 0人学习

关于我们 免责申明 举报中心 意见反馈 讲师合作 广告合作 最新更新
php中文网:公益在线php培训,帮助PHP学习者快速成长!
关注服务号
PHP中文网订阅号
每天精选资源文章推送

Copyright 2014-2026 https://www.php.cn/ All Rights Reserved | php.cn