部署心智:配置与代码分离
本合集目录
本章目录
单册说明:本文件是卷 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"。