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

服务器环境准备

本合集目录
本章目录

单册说明:本文件是卷 7 的第 2 章,可独立阅读。前置:卷 1 第 5 章(SSH 登录)、卷 5 第 3 章(venv)。本章把一台刚租来的 Ubuntu 从"能登录"准备到"能稳定跑起 uvicorn main:app",并且跑它的不是 root。

项 内容
所属卷 卷 7 · 上线与运维(第 2 / 8 章)
前置章节 1.5 租一台云服务器;5.3 Python 与虚拟环境
本章产出 一个 dudao 用户 · 五个目录 · 一个 venv · 一次以非 root 身份跑通的 uvicorn
对应代码 requirements.txt、/srv/dudao 目录树、main.py 的最小启动命令
配图 无(后续统一制图)
读完的判定 ps -o user= -p <pid> 显示的是 dudao 而不是 root,且 curl 127.0.0.1:8000 有响应

7.2.1 一句话结论:先把"谁、在哪、用什么跑"定死,再谈启动

新手在这一步最常撞的墙不是代码,是这句话:

$ python3 -m venv .venv
The virtual environment was not created successfully because ensurepip is not
available.  On Debian/Ubuntu systems, you need to install the python3-venv
package using the following command:

    apt install python3.12-venv

You may need to use sudo with that command.  After installing the python3-venv
package, recreate your virtual environment.

Ubuntu 把 Python 拆成了好几个包:解释器一个、标准库一个、venv 一个、头文件一个。默认只装了解释器,所以 python3 能用,venv 不能用。这不是你装错了,是发行版的策略。

另一头更隐蔽:你 sudo pip install -r requirements.txt 装成功了,uvicorn 也能跑,但数据库文件变成了 root 所有。三天后配好 systemd,服务以 dudao 身份启动,得到:

sqlite3.OperationalError: unable to open database file

代码没错、配置没错、权限看起来也没错——错在之前用 root 跑过一次。

这一章要做的,就是一次性把"谁、在哪、用什么"三件事定死,让后面六章不再反复返工。

7.2.2 原理与方法

① 目录规划:五个目录,各管一件事

先把结论摆出来。这是全书统一的部署形态,后面所有章节都引用这张表:

路径 放什么 属主 权限 为什么是这个权限
/srv/dudao 根,只当容器 root:root 755 顶层不让应用写,防止误建文件
/srv/dudao/backend 后端代码、.venv、.env dudao:dudao 755 应用要能读;.env 单独收 600
/srv/dudao/web 前端构建产物(静态文件) dudao:www-data 755 Nginx 以 www-data 读,必须有 x
/srv/dudao/data dudao.db、备份 dudao:dudao 700 库文件绝不能被 Nginx 或别的账号读到
/srv/dudao/releases 历史版本目录(7.8 用) dudao:dudao 755 要能快速切软链
/srv/dudao/shared 跨版本共用(日志、上传) dudao:dudao 750 只给同组读

三条设计理由,值得单独记住:

代码和产物分开。 backend 是 Python 源码,web 是 npm run build 吐出来的静态文件。两者发布节奏不同、回滚方式不同,混在一个目录里迟早互相覆盖。

数据和代码分开。 这条最值钱。7.8 会做"版本目录 + 软链"的发布方式,切版本时 current 指向另一个目录,data/ 原地不动。如果库文件在代码目录里,切一次版本就等于换了一个空库。

运行用户和 Web 服务器分开。 应用以 dudao 跑,Nginx 以 www-data 跑,两者只能通过文件权限和 127.0.0.1:8000 打交道。应用被攻破,攻击者也读不到 Nginx 的私钥。

② 为什么是 /srv,不是 /var/www 也不是 /opt

路径 文件系统层级标准里的语义 用在「读到」上的问题
/var/www 给 Web 服务器用的内容 语义贴切,但它是"站点根目录"的意思,把后端代码放进去会让 Nginx 有理由读到你不想公开的东西
/opt 第三方独立软件包 语义是"装好的软件",不是"会持续变更的项目"
/home/dudao 用户家目录 Ubuntu 默认给家目录 750,Nginx 进不去;而且家目录是给人用的,不适合放服务
/srv 这台机器对外提供的服务数据 语义正好:这是本站点的服务目录

选 /srv 的另一个好处是它和 /var/log、/etc 不重叠。备份时只要打包 /srv/dudao,不会不小心把系统日志和全机配置一起带走。

③ 用户:一个不能登录、不能 sudo 的服务账号

账号 用途 有 sudo 吗 能 SSH 登录吗
你的管理账号(如 ubuntu) 装软件、改配置、部署 有 能(密钥)
dudao 只运行应用 没有 不能

为什么服务账号不能有 sudo:应用是被公网流量打的那个东西。万一它有命令执行漏洞,攻击者拿到的权限就是应用进程的权限。如果这个进程能 sudo,一条 sudo rm -rf / 就结束了。

用 --shell /usr/sbin/nologin 的效果是:即使有人拿到了密钥,SSH 也登不进来。需要以它的身份操作时,用 sudo -u dudao bash 临时切过去——这条路只有拿到 sudo 的你走得了。

一条容易踩的规则:谁创建的文件,属主就是谁。 所以后面所有"以 dudao 身份写文件"的动作,都必须真的以它执行,不能"用 root 建好再 chown"——除非你每次都记得 chown,而人一定会忘。

④ Python:用系统的,别自己编译

Ubuntu LTS 自带的 Python 满足 3.11+ 的要求,不要去源码编译一个新版本。理由:

做法 后果
用 apt 装系统 Python 安全补丁跟着 apt upgrade 一起来,路径固定
源码编译到 /usr/local 系统升级后可能缺 libssl 版本,pip install 时报编译错误
用第三方一键脚本 来源不可控,且会改掉 python3 指向,后续所有教程对不上

需要隔离版本时,正确工具是 venv,不是"再装一个 Python"。

venv 解决的是另一个问题:不同项目依赖同一个包的不同版本。它给项目一个独立的 site-packages 目录,pip install 只影响这一个目录,不污染系统。

⑤ Node:两种方案,先想清楚再装

卷 4 讲过 Next 的两种上线方式。落到服务器上,就是这套对比:

方案 服务器要装什么 优点 缺点
A. 服务器上构建 Node + npm,跑 npm ci && npm run build 产物一定和服务器环境匹配;只需传源码 1–2 GB 内存的机器容易 OOM;每次发布要下载几百 MB 依赖;发布耗时几分钟
B. 本地构建,只传产物 只要 Nginx 服务器干净、发布快、回滚只要换目录 构建机的 Node 大版本要和约定一致;产物要完整同步(用 rsync --delete)

推荐 B。 你这台机器 2 GB 内存,跑 next build 时很可能会看到:

FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory

这不是配置问题,是物理内存不够。要硬在服务器上构建,得先加 2 GB swap 并设 NODE_OPTIONS=--max-old-space-size=1536,构建时间还会被 swap 拖慢几倍。

B 方案的前提是:本地构建产物必须是可移植的静态文件。 卷 4 第 8 章讲的静态导出正好满足。所以本书主线用 B。

⑥ 时区与时间同步:不是洁癖,是排障基础

服务器默认多半是 UTC。不定时区会出现这些怪事:

现象 真实原因
日志时间比手表差 8 小时 时区是 UTC
证书"还没到期"却报过期 系统时钟漂移,比真实时间慢了几小时
会话提前失效 / 延后失效 过期时间按错误时钟算
定时备份在凌晨 3 点跑,实际是上午 11 点 cron 按系统时区解释

设时区只要一条命令,同步交给 systemd-timesyncd(Ubuntu 默认就开着):

sudo timedatectl set-timezone Asia/Shanghai
sudo timedatectl set-ntp true
timedatectl

System clock synchronized: yes 和 NTP service: active 这两行是你要看的。云主机的时钟通常由宿主机同步,但容器或长期挂起的实例会漂,值得确认一次。

⑦ 权限数字:四个值覆盖 95% 的场景

数字 符号 谁能做什么 用在哪
755 rwxr-xr-x 属主全权,其他人读+进入 目录、web/ 里的文件、可执行脚本
644 rw-r--r-- 属主读写,其他人只读 普通源码、静态资源
700 rwx------ 只有属主能进 data/、~/.ssh
600 rw------- 只有属主读写 .env、私钥、备份文件

记住两条:目录的 x 是"能不能进去",没有它,里面文件是 644 也读不到;权限只对"属主/属组/其他人"三档生效,不在三档里的人一律按"其他人"算。

7.2.3 动手:从一台空机器到 uvicorn 跑起来

以下命令都在服务器上、用你的管理账号(有 sudo 的那个)执行。

第一步:确认系统与资源

cat /etc/os-release | head -n 3
python3 -V
free -h
df -h /

预期形如:

PRETTY_NAME="Ubuntu 24.04.1 LTS"
VERSION_ID="24.04"
Python 3.12.3
               total        used        free      shared  buff/cache   available
Mem:           1.9Gi       220Mi       1.4Gi       1.0Mi       310Mi       1.6Gi
/dev/vda1        40G  6.2G   32G  17% /

Python 3.12.3 满足 3.11+ 的要求,不需要额外装 Python。available 低于 300 MB 时先别装东西,去查是谁在吃内存。

第二步:建服务账号

sudo adduser --system --group --no-create-home \
  --home /srv/dudao --shell /usr/sbin/nologin dudao
id dudao

预期:

uid=998(dudao) gid=998(dudao) groups=998(dudao)

--system 表示系统账号(uid 在 100 以内或 999 以下),--no-create-home 是因为目录我们下面手工建、要精确控制属主,nologin 是禁止交互登录。

不要执行 sudo usermod -aG sudo dudao。这个账号永远不需要提权。

第三步:建目录树

sudo install -d -o root  -g root     -m 755 /srv/dudao
sudo install -d -o dudao -g dudao    -m 755 /srv/dudao/backend
sudo install -d -o dudao -g www-data -m 755 /srv/dudao/web
sudo install -d -o dudao -g dudao    -m 700 /srv/dudao/data
sudo install -d -o dudao -g dudao    -m 755 /srv/dudao/releases
sudo install -d -o dudao -g dudao    -m 750 /srv/dudao/shared

install -d 比 mkdir 多三件事:一次设好属主、属组、权限;父目录不存在时自动建;重复执行不报错。用它建目录比 mkdir 加三条 chown/chmod 更不容易漏。

检查一下:

ls -ld /srv/dudao /srv/dudao/*

预期:

drwxr-xr-x 6 root  root     4096 Nov 17 03:20 /srv/dudao
drwxr-xr-x 3 dudao dudao    4096 Nov 17 03:21 /srv/dudao/backend
drwx------ 2 dudao dudao    4096 Nov 17 03:21 /srv/dudao/data
drwxr-xr-x 2 dudao dudao    4096 Nov 17 03:21 /srv/dudao/releases
drwxr-x--- 2 dudao dudao    4096 Nov 17 03:21 /srv/dudao/shared
drwxr-xr-x 2 dudao www-data 4096 Nov 17 03:21 /srv/dudao/web

data 是 drwx------,这是对的:连 www-data 都进不去。数据库里存着所有用户的摘录和密码哈希,Nginx 没有任何理由读它。

第四步:装 Python 工具链

sudo apt update
sudo apt install -y python3-venv python3-pip sqlite3 rsync curl

四个包各管什么:

包 提供什么 缺了会怎样
python3-venv venv 模块与 ensurepip 建虚拟环境时报 ensurepip is not available
python3-pip 系统级 pip(venv 里的 pip 由 ensurepip 提供) 只想在系统里装个小工具时会缺
sqlite3 命令行客户端 7.8 做 .backup 时要用
rsync 增量同步 部署和备份都要用

第五步:把代码放上去

在本机项目根目录执行(dudao 是你 ~/.ssh/config 里的别名):

rsync -av --exclude '.venv' --exclude '__pycache__' --exclude '.env' \
  backend/ dudao:/tmp/dudao-backend/
ssh dudao 'sudo rsync -a --delete /tmp/dudao-backend/ /srv/dudao/backend/ && \
  sudo chown -R dudao:dudao /srv/dudao/backend'

两步走是因为 /srv/dudao/backend 的属主是 dudao,你的登录用户写不进去;/tmp 谁都能写,落地后再用 sudo 搬进去并统一属主。

--exclude '.env' 是刻意的:配置文件不走代码通道,下面在服务器上单独生成,这样"代码"和"密钥"两条路分开,谁泄露了都能定位。

再准备配置文件。不要把你本机的 .env 直接传上去——里面是开发值(Windows 路径、http://localhost:3000),传上去必然启动失败。正确做法是在服务器上从模板生成:

sudo cp /srv/dudao/backend/.env.example /srv/dudao/backend/.env
sudo nano /srv/dudao/backend/.env          # 填 SECRET_KEY 与生产路径
sudo chown dudao:dudao /srv/dudao/backend/.env
sudo chmod 600 /srv/dudao/backend/.env

生成密钥(在服务器上执行,不要在纸上编):

python3 -c "import secrets; print(secrets.token_urlsafe(48))"

填完确认三行分别是:SECRET_KEY= 一串随机字符、DB_PATH=/srv/dudao/data/dudao.db、ALLOW_ORIGIN=https://dudao.example.com。nano 里改完按 Ctrl+O 保存、回车确认、Ctrl+X 退出。

chown 必须在 chmod 之前:chmod 600 只对属主生效,如果属主是 root,dudao 连读都读不到,服务会在启动时报 Permission denied。

第六步:建 venv,装依赖

sudo -u dudao python3 -m venv /srv/dudao/backend/.venv
sudo -u dudao /srv/dudao/backend/.venv/bin/pip install --upgrade pip
sudo -u dudao /srv/dudao/backend/.venv/bin/pip install -r /srv/dudao/backend/requirements.txt

三步都必须带 sudo -u dudao。原因很实在:venv 目录里每个文件的属主,取决于"谁创建了它"。用 root 建,.venv 就是 root 的,之后 dudao 连升级包都做不到。

pip install 的正常结尾形如:

Successfully installed annotated-types-0.7.0 anyio-4.6.0 fastapi-0.115.0 ...

如果中间出现 Building wheel for ... 卡很久,多半是在编译某个没有预编译包的依赖,需要 build-essential。本书的依赖都有 wheel,正常不会走到这一步。

第七步:先手工跑一次

sudo -u dudao bash -c 'cd /srv/dudao/backend && set -a && . ./.env && set +a && \
  .venv/bin/uvicorn main:app --host 127.0.0.1 --port 8000'

这行有点长,拆开看:

片段 作用
sudo -u dudao bash -c '...' 以服务账号身份执行,模拟将来的运行环境
cd /srv/dudao/backend 工作目录,DB_PATH 虽是绝对路径,但 import 相对模块要靠它
set -a; . ./.env; set +a 把 .env 里的每一行导出成环境变量(set -a 让赋值自动 export)
.venv/bin/uvicorn 用绝对路径,不依赖 PATH

看到这些就对了:

INFO:     Started server process [20481]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

注意 127.0.0.1,不是 0.0.0.0。 应用只监听回环,公网访问一律走 Nginx。这样即使安全组配错,8000 端口也不会暴露。

另开一个终端验证:

curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8000/healthz
ss -lntp | grep 8000
ps -o user=,pid=,cmd= -p $(pgrep -f 'uvicorn main:app' | head -n 1)

预期:

200
LISTEN 0  2048  127.0.0.1:8000  0.0.0.0:*  users:(("uvicorn",pid=20481,fd=13))
dudao     20481 /srv/dudao/backend/.venv/bin/python /srv/dudao/backend/.venv/bin/uvicorn main:app

第三行的第一个字段是 dudao。这一行就是本章的核心验收——它证明"谁在跑"这件事已经定了。

按 Ctrl+C 停掉。现在应用能跑,但一关终端就没了,重启机器更不会自己起来。这是下一章的事。

7.2.4 三个坑

坑 1:ensurepip is not available

症状:

The virtual environment was not created successfully because ensurepip is not
available.  On Debian/Ubuntu systems, you need to install the python3-venv
package using the following command:
    apt install python3.12-venv

成因:Ubuntu 把 venv 和 ensurepip 拆进了独立包,最小化安装的镜像默认不带。报错里的 python3.12-venv 是版本化的包名,装 python3-venv 这个虚拟包更稳(它会跟着系统 Python 版本走)。

修法:

sudo apt install -y python3-venv
rm -rf /srv/dudao/backend/.venv     # 失败的残留必须删掉,否则重跑会报目录已存在
sudo -u dudao python3 -m venv /srv/dudao/backend/.venv

为什么要先删:venv 建到一半失败时,目录里已经有 bin/python 之类的半成品,再跑一次不会自动修好,只会让你以为"装了包还是不行"。

坑 2:error: externally-managed-environment

症状:直接 sudo pip install fastapi 时:

error: externally-managed-environment

× This environment is externally managed
╰─> To install Python packages system-wide, try apt install
    python3-xyz, where xyz is the package you are trying to
    install.

成因:较新的 Debian/Ubuntu 遵循 PEP 668,给系统 Python 打了"外部管理"标记,禁止 pip 往系统目录写包。这是为了保护 apt 管理的包不被 pip 覆盖——两者同时管一个目录,迟早把系统工具搞坏。

修法:不要加 --break-system-packages。正确做法是回到 venv:

sudo -u dudao /srv/dudao/backend/.venv/bin/pip install -r /srv/dudao/backend/requirements.txt

装完确认包进的是 venv 而不是系统:

sudo -u dudao /srv/dudao/backend/.venv/bin/pip show fastapi | grep Location

预期 Location: /srv/dudao/backend/.venv/lib/python3.12/site-packages。如果显示 /usr/lib/python3/dist-packages,说明你用错了 pip。

坑 3:用 root 跑过一次,数据库变成 root 的

症状:手工测试时图省事用了 sudo uvicorn main:app,一切正常。配好 systemd 以 dudao 启动后:

sqlite3.OperationalError: unable to open database file

或者写入时:

sqlite3.OperationalError: attempt to write a readonly database

成因:SQLite 打开数据库文件时,不仅需要读文件,还需要在同一目录下创建 -wal、-shm 临时文件。如果 dudao.db 属主是 root、或者 data/ 目录属主是 root,dudao 用户既改不了文件也建不了临时文件,于是报"打不开"——虽然文件明明存在。

修法:

sudo chown -R dudao:dudao /srv/dudao/data
sudo chmod 700 /srv/dudao/data
sudo -u dudao test -w /srv/dudao/data && echo "可写"

然后以 dudao 身份重新验证一次写入,不要只用 root 试:

sudo -u dudao sqlite3 /srv/dudao/data/dudao.db "PRAGMA integrity_check;"

预期输出 ok。如果输出 unable to open database file,说明问题还在权限上,继续往上查 namei -l /srv/dudao/data/dudao.db 的每一级。

预防办法只有一条:从第一次运行起就用 sudo -u dudao。 不要在"先跑通再说"的阶段用 root 图快,因为 SQLite 不会提醒你属主错了,它只会在换成 systemd 的那天突然报错。

坑 关键报错 一句话修法
venv 建不出来 ensurepip is not available apt install python3-venv,删掉残留再建
pip 被拒 externally-managed-environment 用 venv 里的 pip,别加 --break-system-packages
库打不开 unable to open database file chown -R dudao:dudao data,之后一律 sudo -u dudao

本章验收

  • id dudao 显示这是一个系统账号,且不在 sudo 组里
  • /srv/dudao 下五个目录的属主与权限和本章表格一致,data 是 700
  • python3 -V 显示 3.11 以上,.venv/bin/python -V 与之相同
  • pip show fastapi 的 Location 指向 /srv/dudao/backend/.venv/...
  • 手工启动后 ps -o user= 显示 dudao,ss -lntp 显示监听在 127.0.0.1:8000
  • sudo -u dudao sqlite3 /srv/dudao/data/dudao.db "PRAGMA integrity_check;" 输出 ok

自测

Q1:为什么应用要监听 127.0.0.1:8000 而不是 0.0.0.0:8000?

看答案 0.0.0.0 表示监听所有网卡,包括公网那张。这样 8000 端口就直接暴露在互联网上,任何人可以绕过 Nginx 直接打你的应用——没有 TLS、没有限流、没有静态文件缓冲,安全组一旦开错就完全裸奔。监听 127.0.0.1 时只有本机能连,Nginx 在同一台机器上,所以它能连、外面连不上。这正是我们要的分工。

Q2:为什么 venv 里的包不能靠 sudo pip install 装?

看答案 两个原因。一是 PEP 668 会直接拒绝往系统 Python 写包;二是即使绕过限制,装进去的是系统 site-packages,不在 venv 的搜索路径里,`uvicorn` 启动时会报 ModuleNotFoundError。正确做法是显式用 venv 里的 pip:/srv/dudao/backend/.venv/bin/pip install ...,这样包装进 venv,且属主是执行这条命令的用户。

Q3:目录权限 700 和文件权限 600 有什么区别?为什么 data/ 用 700 而不是 600?

看答案 600 作用在文件上才有意义(属主读写,其他人无权限);目录需要 x 才能进入,所以 700 是"属主可读写进入,其他人连进都进不去"。给 data/ 用 700 而不是 600,是因为 600 的目录缺少 x,连属主自己都进不去——SQLite 需要在这个目录里创建 -wal 和 -shm 文件,进不去就直接报 unable to open database file。

下一步

机器准备好了,应用能跑,但只在你的终端活着。下一章用 systemd 把它变成一个真正的系统服务:开机自启、崩了自动重启、日志可查。

→ 卷7-03-systemd让进程常驻.md