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

部署心智:配置与代码分离

本合集目录
本章目录

单册说明:本文件是卷 7 的第 1 章,可独立阅读。前置:卷 5 第 8 章(联调收口里的 .env)。本章不装任何软件,只解决一件事:为什么同一份代码在你的电脑上能跑、到服务器上就崩,以及怎么让它在两个地方都跑对。

项 内容
所属卷 卷 7 · 上线与运维(第 1 / 8 章)
前置章节 5.8 联调收口;6.8 数据不丢、越权不进
本章产出 一份 .env.example + 一个启动即校验的 config.py + 一条"密钥已泄漏"的处置顺序
对应代码 backend/config.py、backend/.env.example、.gitignore
配图 无(后续统一制图)
读完的判定 删掉一个环境变量再启动,你能看懂报错并说出是哪一行代码拦住的

7.1.1 一句话结论:代码描述"怎么做",配置描述"在哪做",两者混在一起就必然出事

先把最常见的部署事故摆出来。你在本机 uvicorn main:app 一切正常,传到服务器,第一次 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.

按提示去看日志,真正的错误在最后几行:

Traceback (most recent call last):
  File "/srv/dudao/backend/main.py", line 3, in <module>
    from config import SECRET_KEY
  File "/srv/dudao/backend/config.py", line 14, in <module>
    SECRET_KEY = _require("SECRET_KEY")
config.ConfigError: 缺少必需的环境变量 SECRET_KEY,请检查 /srv/dudao/backend/.env

代码一个字都没改,本机能跑,服务器不能跑。因为它们不是同一个运行环境:数据库路径不同、允许的前端来源不同、密钥不同。这些差异不该写进代码,只能从外面喂进去。

这一章要建立的就是这个心智:部署不是"把代码复制过去",而是"把同一份代码放进另一套配置里"。

7.1.2 原理与方法

① 同一份代码,两个世界

把「读到」从本机搬到服务器,实际发生变化的只有配置,代码逻辑一行都不用动:

配置项 开发环境(你的电脑) 生产环境(服务器) 写错的后果
SECRET_KEY dev-only-not-a-secret 64 位随机串 会话可被伪造;或者每次重启所有人都被登出
DB_PATH C:/code/dudao/backend/data/dudao.db /srv/dudao/data/dudao.db 库建在代码目录里,回滚时连同新数据一起被覆盖
ALLOW_ORIGIN http://localhost:3000 https://dudao.example.com 浏览器报 CORS 错,接口"明明通了却拿不到数据"
LOG_LEVEL debug info 生产打 debug 日志,一天写满磁盘
PORT 8000 8000(只监听 127.0.0.1) 监听 0.0.0.0 绕过 Nginx,等于把应用裸奔在公网

看清这张表的规律:左列是"我这台机器",右列是"那台机器"。凡是随机器变化的东西,都不属于代码。

反过来,什么该留在代码里?路由、SQL、校验规则、业务判断——这些在开发和生产的语义完全一致,跟着代码走才是对的。

② 配置的三个层级

不是所有配置都同等敏感。分三层,处理方式不同:

层级 例子 放哪 能不能进 Git
常量 分页大小 20、密码最短 8 位 代码里直接写 能,它就该进
环境相关 端口、路径、日志级别、允许来源 .env(本机)/ systemd(生产) 只提交键名,不提交值
密钥 SECRET_KEY、第三方 API Key、数据库口令 同上层,但权限收到 600 绝对不能,任何形式都不行

三层混在一起的典型症状:把分页大小也做成环境变量,配置文件里堆了四十行,最后没人知道哪个真的在用。只有"换台机器要变"的东西才值得外置。

③ .env 与 .env.example 的分工

两个文件长得很像,作用完全相反:

文件 内容 提交 Git 谁读它
.env 真实值,含密钥 不提交 应用启动时
.env.example 只有键名和占位符 提交 人(新同事、三个月后的你)

.env.example 不是形式主义。它是这个项目"需要哪些配置"的唯一清单。换一台机器部署时,cp .env.example .env,然后逐个填空,漏了哪个会立刻被启动校验拦住——这正是下一节要建的机制。

一个必须注意的细节:.gitignore 里常见的写法是 .env*,它会把 .env.example 一起忽略掉。要补一行例外,且顺序不能反:

.env*
!.env.example

验证不要靠眼睛,让 Git 回答:

git check-ignore -v .env          # 有输出 = 被忽略,正确
git check-ignore -v .env.example  # 无输出 = 会被提交,正确
git ls-files | grep env           # 只应该看到 .env.example

④ 12-Factor 里真正有用的三条

那套方法论有十二条,对个人项目来说大部分用不上。真正每天都会救你的只有三条:

条目 原话的意思 在「读到」里对应什么
III. 配置存于环境 配置不放代码里,放环境变量 就是这一章在干的事
V. 构建、发布、运行严格分离 构建一次,产物加配置就是一次发布 前端 npm run build 出的 web/ 目录,加上当次的 .env,才算一个可回滚的版本(7.8 展开)
XI. 日志当作事件流 应用只管往标准输出写,收集是别人的事 后端不自己写日志文件,交给 systemd/journald(7.3、7.7 展开)

这三条的共同点:都在把"环境相关的东西"从代码里赶出去。 第二条还额外解释了一个常见困惑——为什么不能在生产服务器上直接改代码然后重启?因为那样"构建"和"运行"混在了一起,你没法说清线上跑的到底是哪个版本。

⑤ 密钥为什么不能进仓库,以及已经进了怎么办

Git 的历史是只追加的。你 git rm 一个文件,只是在新提交里删掉它,旧提交里那份永远还在。任何人 clone 下来,git log -p 就能翻出来。

所以补救顺序是固定的三步,顺序不能换:

步骤 动作 为什么必须是这一步
1 吊销:去签发方把这个密钥作废 文件可能已经被镜像、被爬虫、被以前的协作者 clone 走了。只有吊销能让它立刻失效
2 换钥:生成新密钥并部署 服务要能继续跑,得先有新钥匙
3 清历史:改写提交、强推 这一步只影响"以后别人 clone 到的东西",救不了已经泄漏的那份

很多人把顺序做反了:先花两小时清历史,密钥却还活着。清历史是卫生工作,吊销才是止血。

清历史的具体做法(git filter-repo 或 git filter-branch)会改写所有提交的哈希,协作中的仓库必须提前通知所有人重新 clone。个人项目里,更省事的替代方案是:确认没有别的敏感内容后,重建一个干净的仓库。

⑥ 配置缺失要在启动时报错,而不是运行时 500

这是本章最容易被忽略、收益最大的一条。

对比两种写法:

# 写法 A:给默认值
SECRET_KEY = os.getenv("SECRET_KEY", "dev-secret")

# 写法 B:没有就报错
SECRET_KEY = _require("SECRET_KEY")

写法 A 看起来"更健壮",实际是把一个部署错误藏了起来。真实事故是这样的:服务器上忘了配 SECRET_KEY,应用用 dev-secret 正常启动,一切看起来都好。三天后你发现有人能构造出别人的会话 Cookie——因为签名密钥是公开的默认值。

写法 B 在启动的第一秒就崩,systemctl status 里明明白白写着缺哪个变量。启动时崩一次,好过运行时错一百次。

失败要"早、响、准":

要求 含义 反例
早 在进程启动阶段,不在第一个请求进来时 用户注册时才 KeyError
响 进程退出、日志里有明确文字 打个 warning 继续跑
准 报错里写清变量名和该去哪个文件改 只说 ValidationError

7.1.3 动手:把三个配置抽出来,并让它在启动时自检

第一步:写 .env.example

新建 backend/.env.example:

# 会话签名密钥。生成方式:python -c "import secrets; print(secrets.token_urlsafe(48))"
# 至少 32 个字符。开发和生产的值必须不同。
SECRET_KEY=请替换为随机串

# SQLite 数据库文件的绝对路径。生产环境必须指向 /srv/dudao/data 下。
DB_PATH=/srv/dudao/data/dudao.db

# 允许跨源访问的前端地址,只写协议+域名+端口,结尾不要斜杠。
ALLOW_ORIGIN=https://dudao.example.com

# 日志级别:debug / info / warning / error
LOG_LEVEL=info

本机实验时,把它复制成 .env 后要改两处:DB_PATH 换成你自己项目里的绝对路径(如 C:/code/dudao/backend/data/dudao.db),ALLOW_ORIGIN 换成 http://localhost:3000。模板里填的是生产值。

三个写作规则,都是踩过才写的:

规则 违反后的现象
值不要加引号 systemd 读 EnvironmentFile 时不做去引号处理,"abc" 会连引号一起变成值
不要在值里写 $OTHER 同一个原因:systemd 不做变量展开
注释单独一行 行尾注释会被当成值的一部分

第二步:写 config.py

新建 backend/config.py。只用标准库,不引入新依赖:

import os
from pathlib import Path


class ConfigError(RuntimeError):
    """配置缺失或不合法。启动阶段抛出,让进程立刻退出。"""


def _require(name: str) -> str:
    value = os.environ.get(name, "").strip()
    if not value:
        raise ConfigError(
            f"缺少必需的环境变量 {name}。"
            f"请检查 backend/.env(生产环境为 /srv/dudao/backend/.env)"
        )
    return value


SECRET_KEY = _require("SECRET_KEY")
DB_PATH = Path(_require("DB_PATH"))
ALLOW_ORIGIN = _require("ALLOW_ORIGIN")
LOG_LEVEL = os.environ.get("LOG_LEVEL", "info").lower()

if SECRET_KEY.startswith("请替换"):
    raise ConfigError("SECRET_KEY 还是 .env.example 里的占位符,没有真正配置。")

if len(SECRET_KEY) < 32:
    raise ConfigError(
        f"SECRET_KEY 只有 {len(SECRET_KEY)} 个字符,至少需要 32 个。"
        "生成方式:python -c \"import secrets; print(secrets.token_urlsafe(48))\""
    )

if not DB_PATH.is_absolute():
    raise ConfigError(f"DB_PATH 必须是绝对路径,当前是 {DB_PATH}")

if ALLOW_ORIGIN.endswith("/"):
    raise ConfigError(f"ALLOW_ORIGIN 结尾不要带斜杠,当前是 {ALLOW_ORIGIN}")

if LOG_LEVEL not in {"debug", "info", "warning", "error"}:
    raise ConfigError(f"LOG_LEVEL 只能是 debug/info/warning/error,当前是 {LOG_LEVEL}")

逐条解释为什么值这些检查:

检查 拦住的真实问题
空值 忘了配,或者 .env 里写成了 SECRET_KEY=
长度 ≥ 32 有人图省事写 SECRET_KEY=123456,等于没签
不是占位符 直接 cp .env.example .env 就启动,忘了改
绝对路径 用相对路径时,数据库位置取决于"从哪个目录启动",systemd 和手动启动会落到两个不同的库
来源不以 / 结尾 https://dudao.example.com/ 和浏览器发来的 https://dudao.example.com 不相等,CORS 会静默失败
日志级别白名单 拼错成 INFOO 时,日志系统会静默退回默认级别

第三步:在 main.py 里第一行就导入它

from config import SECRET_KEY, DB_PATH, ALLOW_ORIGIN, LOG_LEVEL

from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

config.py 里的检查写在模块顶层,被 import 的那一刻就执行。所以只要 main.py 第一行导入它,任何缺失都会在 uvicorn 启动阶段抛出,而不是等到第一个请求。

顺序也有讲究:from config import ... 必须在 from fastapi import ... 之前。不是为了好看,是为了让"配置错误"排在"依赖没装"前面报出来——否则你会先去查为什么 FastAPI 装不上,其实只是 .env 没写。

第四步:本机跑一遍,故意让它失败

先制造错误。把 .env 里的 SECRET_KEY 删掉(或写成空),然后:

cd backend
uvicorn main:app --reload --env-file .env

预期输出(截取尾部):

ERROR:    Error loading ASGI app. Could not import module "main".

完整原因要看它上面几行:

  File "/srv/dudao/backend/config.py", line 14, in <module>
    SECRET_KEY = _require("SECRET_KEY")
config.ConfigError: 缺少必需的环境变量 SECRET_KEY。请检查 backend/.env(生产环境为 /srv/dudao/backend/.env)

注意这里有个容易误判的地方:uvicorn 只会说"加载不了 main",真正的原因是 import 时抛了异常。看到 Could not import module 别急着查文件名,往上翻。

补上密钥再跑一次:

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

把输出粘进 .env,重新启动,看到 Uvicorn running on http://127.0.0.1:8000 就对了。

第五步:验证生产侧不再依赖 .env 的加载器

本机是 uvicorn 的 --env-file 帮忙读的文件,生产环境没有这个参数——7.3 会用 systemd 的 EnvironmentFile= 注入。这意味着:

环境 谁把变量放进进程 应用代码要不要改
开发 uvicorn --env-file .env(依赖 python-dotenv) 不要
生产 systemd EnvironmentFile=/srv/dudao/backend/.env 不要

两条路径的终点是同一个东西:进程的环境变量表。应用只认 os.environ,不关心它是谁填的。 这就是"配置从外面喂进来"的实际含义。

所以生产环境不需要装 python-dotenv。少一个依赖,少一处出错的可能。

第六步:把权限收掉

.env 里有密钥,权限必须是 600,属主是运行应用的那个用户。以下在服务器上执行:

sudo chown dudao:dudao /srv/dudao/backend/.env
sudo chmod 600 /srv/dudao/backend/.env
ls -l /srv/dudao/backend/.env

预期:

-rw------- 1 dudao dudao 412 Nov 17 03:10 /srv/dudao/backend/.env

如果这里写成 644,服务器上任何一个普通账号都能读到你的签名密钥——而它同时也是你所有用户会话的伪造工具。这一行权限,比后面很多安全措施都重要。

7.1.4 三个坑

坑 1:.env 已经被提交过,加 .gitignore 也没用

症状:git status 干净,git ls-files | grep env 却能看到 .env;或者你在代码托管平台上直接翻到了它。

成因:.gitignore 只对"尚未被跟踪"的文件生效。文件一旦进过索引,之后每一次提交都会继续带着它,直到你显式把它移出索引。

修法:按固定顺序做,一步都不能跳。

# 1. 先去签发方吊销旧密钥(假设已泄漏)
# 2. 生成新密钥,更新服务器与本机的 .env

# 3. 把文件移出索引,但保留本地文件
git rm --cached .env

# 4. 确认忽略规则生效
git check-ignore -v .env

# 5. 提交
git commit -m "chore: 移除误提交的 .env,改由环境变量注入"

做完这三步,历史里仍然有旧值。如果这个仓库是公开的、或曾经公开过,必须当作已泄漏处理,也就是吊销。清历史是可选的卫生工作,吊销不是。

坑 2:给 SECRET_KEY 留了默认值

症状:服务能启动,但每次重启所有用户都被登出;或者更糟——线上和测试环境用同一个密钥,两个站点的会话能互相冒用。

成因:os.getenv("SECRET_KEY", "dev-secret") 这类写法。它让"没配置"变成了一个合法状态,把部署错误藏成了运行时的怪现象。

修法:去掉默认值,改成 _require()。区分"必须有"和"可以缺"两类配置:

类型 写法 例子
必须有 _require("SECRET_KEY") 密钥、数据库路径
可以缺 os.getenv("LOG_LEVEL", "info") 日志级别、分页大小

还有一条:开发和生产的 SECRET_KEY 必须不同。 相同的话,本机签发的 Cookie 在线上同样有效,本地调试时就可能污染真实用户。

坑 3:改了 .env,服务还是旧值

症状:服务器上 cat .env 明明是新值,接口行为却是旧的;systemctl reload dudao 之后依然如此。

成因:环境变量是在进程启动的那一刻从文件读进内存的。reload 只是让进程重新加载代码(有些服务连这个都不做),不会重新读 EnvironmentFile。而且本章的 config.py 在 import 时就把值取成了模块级常量,进程不重启,它永远是旧的。

修法:

sudo systemctl restart dudao
sudo systemctl show dudao -p Environment       # 看 systemd 眼里的值(不含 EnvironmentFile 的内容)
sudo tr '\0' '\n' < /proc/$(systemctl show -p MainPID --value dudao)/environ | grep SECRET_KEY

最后一条是终极手段:直接读进程的环境变量表,看到什么就是应用拿到什么。注意它会打印出密钥本身,只在排障时用,别把输出贴到公开的地方。

如果重启后还是旧值,问题多半在文件本身:systemd 的 EnvironmentFile 不处理引号、不展开变量、不支持行尾注释。用 systemd-analyze 或先在 shell 里 set -a; . ./.env; set +a 试一下,能复现就知道是格式问题。

坑 关键现象 一句话修法
.env 进过仓库 git ls-files 里有它 吊销 → 换钥 → git rm --cached → 清历史
密钥有默认值 重启后全员掉线 / 会话互通 去掉默认值,启动即校验
改配置不生效 cat 是新值,行为是旧的 systemctl restart,再不行查 EnvironmentFile 格式

本章验收

  • backend/.env.example 存在且已提交,.env 不在 git ls-files 的输出里
  • git check-ignore -v .env 有输出,git check-ignore -v .env.example 无输出
  • 删掉 SECRET_KEY 后启动,能在日志里看到明确的 ConfigError,且进程退出
  • SECRET_KEY 长度检查、绝对路径检查、来源结尾斜杠检查都能各触发一次
  • 能说出"密钥已泄漏"的三步顺序,并解释为什么吊销必须排第一
  • .env 权限是 600,属主是将来运行应用的非 root 用户

自测

Q1:为什么 DB_PATH 必须是绝对路径?用 ./data/dudao.db 会出什么事?

看答案 相对路径是相对"进程的当前工作目录"解析的。手动启动时工作目录可能是 /srv/dudao/backend,systemd 启动时由 WorkingDirectory 决定,两种情况下可能落到两个不同的目录,于是出现"数据莫名消失"——其实是两个库。更麻烦的是回滚:库文件跟着代码目录走,切回旧版本时会把新写入的数据一起丢掉。写成绝对路径并指向 /srv/dudao/data,数据库就和代码版本解耦了。

Q2:.env 已经推到公开仓库半小时了,你先清 Git 历史还是先换密钥?

看答案 先吊销并换密钥。公开仓库半小时足够被自动化爬虫扫到,历史是否清理干净已经不影响"密钥已泄漏"这个事实。清历史只影响以后 clone 的人能看到什么,救不了已经被拿走的那份。正确顺序是吊销 → 换钥 → 清历史,把止血放在卫生前面。

Q3:启动时报 ERROR: Error loading ASGI app. Could not import module "main",可能的原因有哪些?

看答案 至少四种:文件名或路径不对(不在当前目录、模块名拼错);main.py 里 import 了不存在的包;main.py 在 import 阶段主动抛了异常(本章的配置校验就是这种);虚拟环境没激活,依赖根本装不到。判断方法是往上看 traceback 的第一段——如果最底层是 ConfigError,那就是配置问题,不是文件名问题。

下一步

配置已经能外置、能在启动时自检了。但服务器上还没有一个能装它的地方:用什么用户跑、代码放哪、Python 从哪来。下一章把这台机器从"刚租来"准备到"能跑 uvicorn main:app"。

→ 卷7-02-服务器环境准备.md