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

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 启动的主进程作为监控目标。验证方式很简单:
- 执行
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 本身无关。


















