跳到正文
零到全栈 · 卷 7 · 上线与运维

systemd 让进程常驻

本合集目录
本章目录

单册说明:本文件是卷 7 的第 3 章,可独立阅读。前置:第 2 章(服务器环境准备)。本章把"手工敲命令启动的 uvicorn"变成一个真正的系统服务:开机自启、崩溃自动拉起、日志统一收走。

项 内容
所属卷 卷 7 · 上线与运维(第 3 / 8 章)
前置章节 7.2 服务器环境准备
本章产出 /etc/systemd/system/dudao.service + 一次"杀掉进程看它自己回来"的演练
对应代码 dudao.service(完整 unit 文件见 7.3.3)
配图 无(后续统一制图)
读完的判定 systemctl kill -s SIGKILL dudao 之后三秒,curl 127.0.0.1:8000/healthz 又能返回 200

7.3.1 一句话结论:进程要活下来,得有人替你盯着它

先看三个真实场景,它们会以不同面目出现,但根子是同一个。

场景一:你 SSH 上去,uvicorn main:app 跑起来,浏览器能访问。合上笔记本去吃饭,回来再打开——curl 超时。因为 SSH 断开时,终端给前台进程发了 SIGHUP,进程跟着退出。

场景二:你学聪明了,用 nohup uvicorn main:app &。撑过了关终端,但云主机做了一次维护重启,服务再也没起来。因为 nohup 只挡信号,不管开机。

场景三:进程因为一个未捕获的异常退出了。你在睡觉。第二天早上用户说"网站打不开",你上去手动敲了一遍启动命令,就好了——但你没解决任何问题,只是把它重启了。

三种场景的共同答案都是 systemd:

$ sudo systemctl start dudao
Job for dudao.service failed because the control process exited with error code.
See "systemctl status dudao.service" and "journalctl -xeu dudao.service" for details.

看到这个别慌。它只说"进程退出了",具体原因在 status 和 journalctl 里。学会读这两处,是本章真正的收获。

7.3.2 原理与方法

① nohup … & 为什么不够

把后台运行的需求拆成五条,nohup 只解决第一条:

需求 nohup cmd & 说明
关终端后继续跑 解决 nohup 忽略 SIGHUP,输出重定向到 nohup.out
机器重启后自动起 不解决 没有任何东西记得它
崩溃后自动拉起 不解决 进程死了就是死了
日志统一管理 半解决 全写进 nohup.out,没有轮转、没有级别、没有时间戳格式
以指定用户运行 不解决 你 sudo 跑就是 root
优雅停止 不解决 只能 kill,还得自己找 PID

再加上一个隐形问题:nohup.out 会无限增长。三个月后某天,磁盘满了,SQLite 写入失败,全站 500,而你还以为是代码 bug。

结论:能用 systemd 的地方不要用 &。 它不是"更规范",它是把五件你迟早要手工做的事一次做完。

② systemd 是什么

它是 Linux 的 1 号进程(PID 1),开机后第一个起来,负责启动其它一切。它管的东西叫 unit,用文件描述。和本项目相关的只有一种:

unit 类型 文件后缀 干什么 本书用到
service .service 一个常驻进程 是(本章)
timer .timer 定时触发,替代 cron 是(7.8 备份)
socket .socket 按连接激活服务 否
target .target 一组 unit 的集合 间接(multi-user.target = 多用户模式)

unit 文件放在哪,决定了它的"归属":

路径 谁的 优先级 本书用哪个
/etc/systemd/system/ 管理员 高 是
/run/systemd/system/ 运行时临时 中 否
/lib/systemd/system/ 软件包自带 低 只读,不要改

自己写的服务一律放 /etc/systemd/system/。改软件包自带的 unit 时用 systemctl edit xxx 生成覆盖片段,不要直接改 /lib 下的文件——升级会覆盖掉你的修改。

③ unit 文件三段,逐行读

[Unit]      这个服务是什么、跟谁有先后关系
[Service]   怎么启动它、挂了怎么办
[Install]   什么时候让它开机自启

下面是「读到」的完整 unit。先看结构,逐行解释在表里:

[Unit]
Description=DuDao API (FastAPI via uvicorn)
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=dudao
Group=dudao
WorkingDirectory=/srv/dudao/backend
EnvironmentFile=/srv/dudao/backend/.env
Environment=PYTHONUNBUFFERED=1
ExecStart=/srv/dudao/backend/.venv/bin/uvicorn main:app \
    --host 127.0.0.1 --port 8000 \
    --proxy-headers --forwarded-allow-ips=127.0.0.1
Restart=always
RestartSec=3
TimeoutStopSec=20
KillSignal=SIGTERM
StandardOutput=journal
StandardError=journal
SyslogIdentifier=dudao

[Install]
WantedBy=multi-user.target
行 作用 写错的后果
Description 给人看的名字 只在 status 里显示得难看
After=network-online.target 等网络就绪再启动 启动时 DNS 未就绪,连不上外部服务
Wants=network-online.target 主动把网络拉起来 与 After 配套,缺了可能等到超时
Type=simple 认为 ExecStart 一执行就算启动成功 见下一节,坑最深的一行
User / Group 以谁的身份跑 缺了就默认 root,等于白做 7.2 的隔离
WorkingDirectory 进程的工作目录 Python 的相对 import 会失败
EnvironmentFile 从文件读环境变量 见坑 3,systemd 的解析规则和 shell 不同
Environment= 直接写单个变量 值里有空格要小心
ExecStart 启动命令 必须是绝对路径,见坑 1
Restart=always 任何退出都重启 写成 no 就变成"崩了没人管"
RestartSec=3 重启前等 3 秒 太短会在崩溃循环里刷爆日志
TimeoutStopSec=20 停止时最多等 20 秒 太短会强杀正在处理的请求
KillSignal=SIGTERM 先发 TERM 让它自己收尾 改成 KILL 等于每次重启都硬断电
StandardOutput=journal 标准输出交给 journald 改成文件就失去 journalctl 的统一查询
WantedBy=multi-user.target 开机进多用户模式时启动 少了这段 enable 会报错

一个换行细节:ExecStart 太长时用行尾 \ 续行,\ 后面不能有空格。多一个空格,systemd 会把参数解析成一堆空字符串,报错信息还看不出所以然。

④ Type=simple 的陷阱:启动了不等于活了

Type=simple 的语义是"fork() 之后立刻认为启动成功"。它不检查进程是否真的在监听端口,更不检查应用是否健康。

所以会出现这种状态:

Active: active (running) since Mon 2026-11-17 03:40:12 CST; 4s ago

而 curl 127.0.0.1:8000 报 Connection refused——因为 uvicorn 还在导入模块,或者刚因为端口被占而退出,systemd 还没来得及发现。

三种 Type 的差别:

Type 什么时候算"启动成功" 适合
simple(默认) 进程一创建就算 前台不退出的服务(uvicorn 单进程)
exec execve() 成功后才算 比 simple 稍微准一点,仍不检查端口
notify 应用主动 sd_notify(READY=1) 需要精确就绪信号的服务,uvicorn 默认不发

notify 最准,但需要应用配合,uvicorn 不原生支持。所以本书用 simple,并靠外部健康检查(7.8 的 /healthz)来确认它真的活了。"systemd 说 running"和"服务可用"是两件事,这个区分在排障时非常关键。

⑤ Restart 与"崩溃循环"

Restart 有几个取值,差别在于"什么情况下重启":

取值 正常退出(exit 0) 异常退出(exit≠0) 被信号杀死 适合
no 不重启 不重启 不重启 一次性任务
on-failure 不重启 重启 重启 允许正常结束的服务
always 重启 重启 重启 常驻服务(本书用这个)

always 的副作用是:你 systemctl stop 时它不会反复拉起(stop 是显式指令,systemd 分得清),但如果应用自己 exit(0),它会立刻再起一次。所以"启动脚本跑完就退出"的写法不适合 always。

RestartSec=3 之外,还要知道有一道熔断:

StartLimitIntervalSec=10
StartLimitBurst=5

默认语义是"10 秒内超过 5 次启动就放弃,进入 failed 状态"。这条设计的用意是防止一个配置错误的程序把 CPU 和日志刷爆。撞上时 status 里会写:

dudao.service: Start request repeated too quickly.
dudao.service: Failed with result 'start-limit-hit'.

修好根因后要手工复位:

sudo systemctl reset-failed dudao
sudo systemctl start dudao

⑥ 优雅停止:为什么要等那 20 秒

systemctl restart 的真实过程是:

  1. 给主进程发 SIGTERM;
  2. 等它自己退出,最多等 TimeoutStopSec;
  3. 还没退,发 SIGKILL 强杀;
  4. 重新执行 ExecStart。

uvicorn 收到 SIGTERM 后会做三件事:停止接受新连接、等正在处理的请求跑完、关闭连接池。这就是"优雅"的含义——用户正在提交的那条摘录不会被腰斩。

配置 默认 建议 理由
KillSignal SIGTERM 保持 只有 TERM 能让应用收尾
TimeoutStopSec 90 秒 20 秒 太长会让部署卡住;20 秒够大部分请求
KillMode control-group 保持 连子进程一起收,避免残留

一个必须接受的现实:重启期间一定会有几秒 502。 单机单进程没有无缝重启的能力。要减少影响,只能靠"重启前先从 Nginx 摘流量"或者多实例,那是卷 8 的话题。现在只需知道:部署时那几秒报错是预期的,不是你配错了。

⑦ 日志去哪了

StandardOutput=journal 的意思是:进程写到 stdout/stderr 的每一行,都被 journald 收走,带上时间戳、unit 名、PID。

命令 干什么 什么时候用
journalctl -u dudao -n 50 --no-pager 最近 50 行 日常查看
journalctl -u dudao -f 实时跟随 复现问题时
journalctl -u dudao --since "10 min ago" 按时间过滤 知道大概什么时候出的问题
journalctl -u dudao -p err -b 本次开机以来的错误级 快速定位
journalctl -u dudao -o cat 只留消息体,去掉前缀 想复制日志给别人时
journalctl --disk-usage 日志占了多少磁盘 磁盘告警时
journalctl -u dudao --no-pager | grep -c " 500 " 数 500 的条数 粗略统计

默认情况下 Ubuntu 的 journal 可能只存在内存(/run/log/journal),重启就没了。要留历史:

sudo mkdir -p /var/log/journal
sudo systemctl restart systemd-journald
journalctl --disk-usage

有 /var/log/journal 目录后,journal 才会落盘。代价是占磁盘,所以还要配 SystemMaxUse= 限制总量(7.7 一起做)。

不要自己写日志文件。 应用往 stdout 写,落地和轮转交给 journald——这就是 7.1 说的第 XI 条。

⑧ EnvironmentFile 的解析规则

很多人以为 systemd 读 .env 和 shell 的 source 一样。不一样,差三处:

写法 shell(source .env) systemd EnvironmentFile
KEY="abc" 值是 abc 值是 "abc",引号是值的一部分
KEY=$OTHER/x 展开成变量值 原样 $OTHER/x,不展开
KEY=abc # 注释 值是 abc 值是 abc # 注释
# 整行注释 忽略 忽略(这条一致)
export KEY=abc 支持 不支持 export 前缀

所以 .env 的写法必须克制:一行一个 KEY=VALUE,不加引号,不写行尾注释,不做变量引用。 7.1 定的那三条规则,原因就在这里。

还有一条权限规则:EnvironmentFile 由 systemd(root)读取,所以文件属主是谁不太重要,但不能是所有人都可读——里面有 SECRET_KEY。600 是对的。

7.3.3 动手:写 unit、启动、杀掉、看它回来

第一步:写文件

sudo tee /etc/systemd/system/dudao.service >/dev/null <<'EOF'
[Unit]
Description=DuDao API (FastAPI via uvicorn)
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=dudao
Group=dudao
WorkingDirectory=/srv/dudao/backend
EnvironmentFile=/srv/dudao/backend/.env
Environment=PYTHONUNBUFFERED=1
ExecStart=/srv/dudao/backend/.venv/bin/uvicorn main:app --host 127.0.0.1 --port 8000 --proxy-headers --forwarded-allow-ips=127.0.0.1
Restart=always
RestartSec=3
TimeoutStopSec=20
KillSignal=SIGTERM
StandardOutput=journal
StandardError=journal
SyslogIdentifier=dudao

[Install]
WantedBy=multi-user.target
EOF

用 tee 而不是 nano,是为了让这段配置能原样复制、可版本化。文件里不要写中文注释——systemd 能读 UTF-8,但排障时 cat 出来的乱码会干扰判断。

PYTHONUNBUFFERED=1 是必须的:Python 默认会缓冲 stdout,日志可能卡在缓冲区里几十分钟才进 journal。加了它,每一行立即落盘。

--proxy-headers --forwarded-allow-ips=127.0.0.1 是给 7.4 铺路:告诉 uvicorn"只信任来自 127.0.0.1 的 X-Forwarded-* 头"。这样应用能拿到真实客户端 IP 和真实的 https 协议。

第二步:校验语法

sudo systemd-analyze verify /etc/systemd/system/dudao.service

没有任何输出就是通过。它只能查语法和明显的路径问题,查不出"变量值不对"这类内容错误。

第三步:加载、启用、启动

sudo systemctl daemon-reload
sudo systemctl enable --now dudao

daemon-reload 让 systemd 重新读所有 unit 文件。每次改 unit 都必须执行,这条没有例外。

enable --now 是两步合一:enable 建立开机自启的软链,start 立刻启动。等价于:

sudo systemctl enable dudao
sudo systemctl start dudao

第四步:看状态

systemctl status dudao --no-pager

预期形如:

● dudao.service - DuDao API (FastAPI via uvicorn)
     Loaded: loaded (/etc/systemd/system/dudao.service; enabled; preset: enabled)
     Active: active (running) since Mon 2026-11-17 03:40:12 CST; 8s ago
   Main PID: 21533 (uvicorn)
      Tasks: 3 (limit: 2261)
     Memory: 58.2M
        CPU: 412ms
     CGroup: /system.slice/dudao.service
             ├─21533 /srv/dudao/backend/.venv/bin/python /srv/dudao/backend/.venv/bin/uvicorn main:app
             └─21548 /srv/dudao/backend/.venv/bin/python -c "from multiprocessing.resource_tracker import main;main(4)"

四个字段要会读:

字段 看什么
Loaded 加载的是哪个文件、enabled 还是 disabled
Active active (running) 才对;failed 或 activating (auto-restart) 都是有问题
Main PID 主进程号,后面 kill 要用
CGroup 这个服务带起来的所有进程,能看出有没有多开

再确认它真的在服务:

curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8000/healthz

200 才算成。active (running) 只说明进程在,不说明它在干活——这一条在 7.3.2 第 ④ 节讲过,现在亲手验证一次。

第五步:故意杀掉,看它自己回来

这是本章最重要的一次演练。先记下重启次数:

systemctl show dudao -p NRestarts -p MainPID -p ActiveEnterTimestamp

然后强杀主进程(-9 是 SIGKILL,应用没有任何机会收尾,模拟最恶劣的崩溃):

sudo systemctl kill -s SIGKILL dudao

立刻连续查询:

for i in 1 2 3 4 5 6; do
  printf '%s  ' "$(date +%H:%M:%S)"
  systemctl show dudao -p ActiveState -p SubState -p NRestarts --value | tr '\n' ' '
  echo
  sleep 1
done

预期形如:

03:45:02  activating auto-restart 2
03:45:03  activating auto-restart 2
03:45:04  activating auto-restart 2
03:45:05  active running 2
03:45:06  active running 2
03:45:07  active running 2

三秒后恢复,NRestarts 从 1 变成 2。再做一次 HTTP 验证:

curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8000/healthz

200。这三秒的 502 是预期的,如果你此时从公网访问,看到的就是 Nginx 的 502 Bad Gateway——下一章会解释这个状态码是谁发的。

日志里能看到完整的"死亡—重启"记录:

sudo journalctl -u dudao -n 20 --no-pager
Nov 17 03:45:01 ip-10-0-0-12 systemd[1]: dudao.service: Main process exited, code=killed, status=9/KILL
Nov 17 03:45:01 ip-10-0-0-12 systemd[1]: dudao.service: Failed with result 'signal'.
Nov 17 03:45:01 ip-10-0-0-12 systemd[1]: dudao.service: Scheduled restart job, restart counter is at 2.
Nov 17 03:45:04 ip-10-0-0-12 systemd[1]: Started DuDao API (FastAPI via uvicorn).
Nov 17 03:45:04 ip-10-0-0-12 uvicorn[21602]: INFO:     Started server process [21602]
Nov 17 03:45:04 ip-10-0-0-12 uvicorn[21602]: INFO:     Application startup complete.

注意 restart counter is at 2 这一行——它就是"崩溃循环熔断"的计数器。如果这个数字很快涨到 5,说明应用在启动阶段就崩,先去看它上面那几行 traceback。

第六步:验证开机自启

不用真的重启机器(会断你的 SSH)。看软链就够了:

systemctl is-enabled dudao
ls -l /etc/systemd/system/multi-user.target.wants/dudao.service

预期:

enabled
lrwxrwxrwx 1 root root 38 Nov 17 03:39 /etc/systemd/system/multi-user.target.wants/dudao.service -> /etc/systemd/system/dudao.service

enable 的本质就是这个软链:开机时 systemd 启动 multi-user.target,顺着 wants 目录把所有链接的服务拉起来。没有这个链接,unit 写得再对也不会自启。

真要验证一次的话,选个没人用的时间 sudo reboot,重连后 systemctl status dudao 看 Active 那行的启动时间是不是开机时间。

第七步:把常用操作记住

操作 命令
启动 / 停止 / 重启 sudo systemctl start|stop|restart dudao
只看是否在跑 systemctl is-active dudao
看是否自启 systemctl is-enabled dudao
改完 unit 后 sudo systemctl daemon-reload
看生效的 unit 内容 systemctl cat dudao
看 systemd 缓存里的启动命令 systemctl show dudao -p ExecStart
复位熔断 sudo systemctl reset-failed dudao

后两条的区别很重要,坑 2 会用到:cat 读的是磁盘上的文件,show 读的是 systemd 内存里的解析结果。

7.3.4 三个坑

坑 1:status=203/EXEC

症状:

dudao.service: Main process exited, code=exited, status=203/EXEC
dudao.service: Failed with result 'exit-code'.

成因:ExecStart 指向的程序不存在或不可执行。最常见的三种写法:

写法 为什么错
ExecStart=uvicorn main:app systemd 不读你的 shell PATH,找不到 uvicorn
ExecStart=/usr/local/bin/uvicorn ... 包装在 venv 里,/usr/local/bin 没有
ExecStart=/srv/dudao/backend/.venv/bin/uvicorn 但 venv 是 root 建的 权限不够,dudao 执行不了

修法:用绝对路径,并确认这个文件真的可执行:

ls -l /srv/dudao/backend/.venv/bin/uvicorn
sudo -u dudao /srv/dudao/backend/.venv/bin/uvicorn --version

第一条要看到 -rwxr-xr-x 且属主是 dudao;第二条要能打印版本号。两条都过,ExecStart 就没问题。

203/EXEC 还有一个变体:脚本第一行的 shebang 指向的解释器不存在(比如 #!/usr/bin/env python3.11 但系统只有 3.12),表现一样,报错一样,只能靠手工执行来区分。

坑 2:改了 unit 没 daemon-reload

症状:你把 ExecStart 里的端口从 8000 改成 8001,sudo systemctl restart dudao,结果 ss -lntp 显示还在监听 8000。systemctl cat dudao 明明显示的是 8001。

成因:systemd 在 daemon-reload 时把 unit 解析进内存,之后一直用缓存。restart 只是重启进程,不会重读文件。systemctl cat 直接读磁盘,所以它显示新内容——这就是最容易骗人的地方。

修法:

sudo systemctl daemon-reload
sudo systemctl restart dudao
systemctl show dudao -p ExecStart

show 输出的是内存里的值,和 cat 不一致就说明还没 reload。养成习惯:改 unit 的固定动作是 daemon-reload → restart → show 确认,三步一条链。

顺带一个反例:daemon-reload 对应用代码没有任何作用。改了 main.py 只需 restart,不需要 reload。

坑 3:EnvironmentFile 里的引号让密钥带上了引号

症状:服务能起来,config.py 的长度检查也过了,但所有用户登录后刷新页面就掉登录态;或者接口报签名校验失败。日志里没有明显错误。

成因:.env 写成了:

SECRET_KEY="a1b2c3d4..."

shell 里这样写没问题,systemd 会把引号当成值的一部分。于是应用拿到的密钥是 "a1b2c3d4..."——含引号,长度还多了 2。7.1 写的"至少 32 个字符"这条检查因此照样通过,看着一切正常。

真正的伤害发生在你改配置的那一刻:本机用 shell 加载 .env(引号被去掉),服务器用 systemd 加载(引号保留),两边算出的签名不一样;或者你某次把引号删掉,密钥值跟着变了,所有旧 Cookie 立刻失效。

另一种更隐蔽的变形是编辑器留下的行尾注释:

SECRET_KEY=a1b2c3d4  # 生产密钥
ALLOW_ORIGIN=https://dudao.example.com/

第一行值里带上了 # 生产密钥,签名密钥变了,重启后所有旧 Cookie 全部失效;第二行结尾的斜杠让 CORS 静默不匹配。两个问题都不报错。

修法:先看进程真正拿到了什么:

sudo tr '\0' '\n' < /proc/$(systemctl show -p MainPID --value dudao)/environ | grep -E 'SECRET_KEY|ALLOW_ORIGIN'

这条命令读的是内核里的环境变量表,systemd 怎么解析的,这里就怎么显示。看到引号或注释就说明是文件格式问题。

然后按 7.1 的三条规则改文件:不加引号、不写行尾注释、不做变量引用。改完 restart,不要 reload。

再补一条容易忽略的:如果 .env 权限是 600 但属主是 root,systemd(root)能读,应用也能拿到值——所以这条不会报错,但你的部署脚本以 dudao 身份读同一个文件时会失败。属主统一成 dudao:dudao 最省心。

坑 关键现象 一句话修法
203/EXEC 进程一起就退 ExecStart 用 venv 里的绝对路径,先手工执行验证
改了不生效 cat 是新的,show 是旧的 daemon-reload 后 restart
密钥带引号 登录态异常、CORS 静默失效 读 /proc/PID/environ 看真值,改掉引号和行尾注释

本章验收

  • systemctl is-active dudao 输出 active,is-enabled 输出 enabled
  • systemctl status dudao 的 CGroup 里主进程属主是 dudao(看 ps -o user=)
  • systemctl kill -s SIGKILL dudao 后三秒内 /healthz 恢复 200,NRestarts 增加 1
  • journalctl -u dudao -n 20 能看到"退出—重启—启动完成"的完整链条
  • 能说出 systemctl cat 和 systemctl show -p ExecStart 的区别
  • 能背出改 unit 之后的三步:daemon-reload → restart → show

自测

Q1:systemctl status 显示 active (running),但浏览器访问是 502。可能的原因是什么?

看答案 至少三种:应用还在启动中(Type=simple 不等待就绪,导入模块可能要几秒);应用监听的端口和 Nginx 配的不一致;应用监听在 0.0.0.0 之外的某个地址而 Nginx 连不上。判断方法是先在服务器上 curl 127.0.0.1:8000/healthz——能通说明是 Nginx 侧的问题,不通说明应用没真的在服务。

Q2:为什么 Restart=always 还需要 RestartSec?

看答案 没有间隔的重启会形成紧密循环:应用因为配置错误秒退,systemd 立刻再拉,一秒钟几十次,日志瞬间刷满磁盘,CPU 也被占满,反而让你没法登录排查。RestartSec=3 给了一个缓冲窗口,再配合 StartLimitBurst 的熔断,才能让"崩溃"变成一个可观察的状态而不是一场雪崩。

Q3:把密钥写在 Environment= 里和写在 EnvironmentFile= 里,各有什么代价?

看答案 写在 Environment= 里,密钥直接出现在 unit 文件中,而 unit 文件通常是 644,任何本地用户都能读;而且它会出现在 systemctl show 的输出和某些备份里。写在 EnvironmentFile 里,unit 文件可以安全地提交到版本库,密钥单独 600 保护。代价是 EnvironmentFile 的解析规则更严格(不加引号、不展开变量),写错时静默出错。生产环境应该用后者。

下一步

进程不会再死了,但它只在 127.0.0.1:8000 上说话,公网进不来。下一章用 Nginx 接住 80 端口,把静态文件直接发出去、把 /api 转给后端。

→ 卷7-04-Nginx反向代理.md