服务器环境准备
本合集目录
本章目录
单册说明:本文件是卷 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 把它变成一个真正的系统服务:开机自启、崩了自动重启、日志可查。