外观
从构建到兼容回滚:锁定依赖、运行身份与发布状态机
摘要
本地启动成功,部署后却导入旧包;切回旧程序又读不了新数据。本篇面向已有后端经验的 Python 学习者,串起构建身份、干净安装、启动关闭和数据库兼容回滚,并提供独立发布契约实验。
场景:代码回去了,服务却没有恢复
这是教学场景。日志服务第二版新增数据库字段,新程序运行失败后,维护者把源码目录切回第一版,觉得“回滚完成”。进程仍在使用旧环境中安装的第二版包,或者第一版已经无法理解被修改的数据。两种问题都不能靠重复重启解决:前者缺运行身份,后者缺兼容契约。真正的发布对象包含代码产物、依赖、配置、数据库状态和进程生命周期,Git 提交只是其中一个身份。
每次发布先对齐三份身份:准备启用的是哪份产物,实例实际运行的是哪份代码,当前数据仍被哪些版本理解。前两份不一致,重启可能继续导入错误包;第三份不兼容,切回旧代码也不能恢复。只有三者都通过检查,切换接入才有依据。
前置项目结构与打包区分源码与安装产物,本篇保持业务不变,先用manifest与版本集合追一次切换,再把同一判断迁移到真实wheel、运行实例和数据库。临时JSON只检验控制流程;Linux模板仍未在本轮实机执行,不扩大已有证据。
基础:可重复安装与可重复构建是两件事
Dependency lock(依赖锁)记录解析后的具体依赖版本和必要条件,避免两次安装解析出不同集合。只有顶层 fastapi==某版本 并不等于所有传递依赖都锁定。不同 Python 小版本、OS、CPU 架构和环境标记可能选到不同文件;需要记录目标平台,并核验可获得的产物。项目的 pyproject 定义意图,锁文件和制品清单定义这次交付,二者不能随意互相替代。
pip 可重复安装文档区分版本固定、哈希检查与预先收集分发文件等方法。--require-hashes 要求依赖链满足哈希检查规则,不是给一个顶层包补一行哈希就完成。它检查取得的文件是否符合记录,不验证包作者可信、不证明程序没有漏洞。哈希与来源信任必须分开:如果攻击者可以同时改文件和 manifest,单独的 SHA-256 无法提供真实性。
Reproducible build(可重复构建)更严格,要求在声明条件下从相同输入得到相同字节产物。时间戳、工具版本、路径和原生编译环境都可能改变字节。两次安装相同版本能正常启动,不证明 wheel 字节一致;本例对固定 JSON 的哈希检查也不证明完整 Python 包可重复构建。先给出可重复安装与身份追踪,再按项目需求提高构建确定性,不通过术语包装未做的验证。
构建身份至少包含源码提交、构建工具、Python 版本、目标平台、依赖锁摘要和产物摘要。运行身份至少包含实际解释器、已安装分发版本、模块来源、release_id 与配置版本。程序启动日志应输出非敏感身份字段;不能将密码、数据库 URL 密钥或完整环境变量也作为“诊断信息”打印。环境问题的具体命令见 解释器与虚拟环境,不是靠运维终端里的 python 指向猜服务进程。
原理:发布是有失败分支的状态机
图表将在阅读到此处时加载…
Liveness(存活探针)回答进程是否还能响应其最低生命检查;Readiness(就绪探针)回答是否适合接入业务流量。端口已监听不意味着依赖初始化、迁移和后台任务准备完成。另一方面,如果存活检查绑定一个短暂故障下游,可能造成重启放大。两种探针需要分别设计,不能简单给它们同一个“所有依赖都可用”逻辑,然后把反复重启称为自愈。 可进一步阅读systemd启动就绪与时间基础:托管进程的就绪、退出和环境有独立职责。
启动阶段应先校验配置与必要兼容条件,失败就明确退出;不要在模块导入时连接数据库或读取一次环境变量以后永久缓存未知状态。实例进入 draining(排空)阶段时,停止接收新任务,并在预算内处理或显式终结已接纳任务。超时后的强制终止仍可能留下已提交副作用,应保存操作身份并让重试有依据。后台任务治理解释为什么服务进程活着与任务已经安全结束不是同一件事。
原子切换一个文件指针只能保证读者看到旧指针或新指针,不能让安装、数据库迁移、路由和多实例同时具备事务原子性。甚至同目录 rename/replace 的持久性还受文件系统和断电语义影响,本例不做断电持久性承诺。真实发布系统必须记录已经完成的阶段,重入时判定继续还是补偿;失败后用当前真实状态恢复,而不是盲目从第一条命令再跑。
实战:验证哈希与数据库兼容后才切换
独立文件 34_release.py使用临时目录创建 v1、v2 两个演示产物。v1 声明可读数据库修订 1、2,v2 只声明修订 2。activate 先检查 SHA-256、兼容集合和演示 readiness,再用同目录临时指针替换 active。正确路径覆盖前进和兼容回滚,负例覆盖损坏产物及数据库修订 3 下的不安全回退。这里 app.json 是发布契约样品,不是真正的 wheel。
powershell
python docs/python/examples/34_release.pypython
"""Verify an artifact and atomically switch a temporary release pointer."""
import hashlib
import json
from pathlib import Path
import tempfile
def digest(data):
return hashlib.sha256(data).hexdigest()
def activate(root, name, database_revision):
release = root / name
manifest = json.loads((release / "manifest.json").read_text(encoding="utf-8"))
data = (release / "app.json").read_bytes()
if digest(data) != manifest["sha256"]:
raise ValueError("artifact hash mismatch")
if database_revision not in manifest["database_revisions"]:
raise ValueError("application/database incompatibility")
config = json.loads(data)
if not config.get("ready"):
raise ValueError("readiness check failed")
# Same-directory replace; pointer atomicity does not make a deployment transactional.
staged = root / "active.next.json"
staged.write_text(json.dumps({"release": name}), encoding="utf-8")
staged.replace(root / "active.json")
return config["version"]
def main():
with tempfile.TemporaryDirectory() as directory:
root = Path(directory)
for name, revisions in (("v1", [1, 2]), ("v2", [2])):
release = root / name
release.mkdir()
data = json.dumps({"version": name, "ready": True}, sort_keys=True).encode()
(release / "app.json").write_bytes(data)
(release / "manifest.json").write_text(json.dumps({
"sha256": digest(data), "database_revisions": revisions}), encoding="utf-8")
assert activate(root, "v1", 1) == "v1"
assert activate(root, "v2", 2) == "v2"
assert activate(root, "v1", 2) == "v1" # Expanded schema supports old application.
(root / "v2" / "app.json").write_text("tampered", encoding="utf-8")
try:
activate(root, "v2", 2)
except ValueError as error:
print("rejected damaged artifact:", error)
else:
raise AssertionError("tampered artifact activated")
try:
activate(root, "v1", 3) # Contracted incompatible schema.
except ValueError as error:
print("rejected unsafe rollback:", error)
else:
raise AssertionError("incompatible rollback activated")
assert json.loads((root / "active.json").read_text())["release"] == "v1"
print("forward, compatible rollback, failed activation preserve pointer: passed")
if __name__ == "__main__":
main()先预测两个失败分支会不会改active,再沿主例追指针:
| 输入与动作 | 检查结果 | active应指向 |
|---|---|---|
| v1与修订1、随后v2与修订2 | 清单、兼容与演示ready通过 | 先v1再v2 |
| v1与修订2 | 旧程序仍声明兼容 | v1 |
| 篡改v2的app.json后激活 | 哈希失败,尚未切换 | 保持v1 |
| 传入v1与修订3 | 兼容检查失败 | 仍保持v1 |
数据库修订在这里是契约参数,不是真实迁移。关键区别是失败发生在指针替换之前;主例断言最后active仍为v1,不用打印“rollback”冒充恢复。真实应用要把三份身份扩为产物来源、实际导入与当前数据,再从干净环境验证API和生命周期。临时目录实验不能证明Linux已经部署。
反例是 git checkout 后直接重启任何名为 python 的命令;正例是每个 release 有独立环境和明确入口路径,切换时保存 release_id,启动日志记录模块来源。另一个反例是文件损坏以后重算哈希并继续部署,这会消除证据而不是修复问题。产物摘要应由可信构建流程生成并传递,运行侧只验证预期摘要;需要签名和来源追溯时,不能拿可由攻击者一起修改的 JSON 当可信根。
干净安装检查包括:在新的虚拟环境安装已有产物;将工作目录移到源码树外;运行入口和资源加载;验证依赖与许可证清单;重复运行必要集成测试。源码目录恰好在 sys.path 中时,漏进 wheel 的模块可能被本地文件掩盖。参考 导入机制中入口和模块身份的区别,部署验证必须保留 cwd、sys.executable 与模块 __file__。
Linux 运行模板与核验边界
下面是 systemd 单元的局部模板,路径、用户、模块入口和超时值都是示例,不能直接部署。本文阅读了 systemd 在线手册中的 ExecStart、Type 与 TimeoutStopSec 说明,但本轮未在 Linux 或 systemd 实机验证。使用前须核对目标 systemd 版本、应用信号协议与文件权限,目标部署验收状态为待验证。
ini
[Unit]
Description=Log query teaching service
After=network.target
[Service]
Type=exec
User=logquery
WorkingDirectory=/opt/logquery/current
EnvironmentFile=/etc/logquery/config.env
ExecStart=/opt/logquery/current/venv/bin/python -m logquery
Restart=on-failure
TimeoutStopSec=30
[Install]
WantedBy=multi-user.targetType=exec 能改善执行入口不存在等问题的启动反馈,不表示业务 readiness 已验证。ExecStart 的默认解释规则不是随手写的 shell 脚本,重定向和管道不能直接照搬 shell 命令;若使用 shell,必须显式设计参数与注入边界。TimeoutStopSec 是管理器停止预算,应用应在更小的内部预算内停止接入、排空任务并关闭连接,否则可能被管理器终止。具体行为以目标手册为准,本文不会用 Windows 线程 join 结果证明 Linux 信号处理成功。
配置文件权限和环境注入方式要由运行平台管理,密钥轮换不能要求把敏感文件打进 wheel。普通业务配置可以版本化并校验类型,密钥只能记录引用与版本,不打印值。运行用户采用最小权限,日志、导出和临时目录的写权限与代码产物分开。容器部署同样需要明确入口 PID、停止信号、宽限期和持久卷权限,不能因为容器镜像有摘要就略过数据兼容和退出验收。
数据兼容:应用回滚不会自动撤销历史
Expand/contract(扩展后收缩)迁移先做兼容性增加,让旧新程序共同工作,再迁移读写和历史数据,确认旧版本不再需要以后才删除旧结构。举例而言,先新增可选字段而不是立即删除旧列;新程序写入旧程序无法理解的枚举值时,即使列结构兼容,数据语义仍可能不兼容。数据库修订集合只是教学模型,真实契约必须包括查询、写入与历史数据语义。
把manifest的“可读修订集合”迁移到真实数据库,判断要更细:结构兼容只是一层,旧程序是否理解新枚举和新字段含义还需存量数据验证。先增加可空字段、保留旧id查询,再启用新写入,与直接删除旧列是同一个发布问题的两条不同路径。连接池与迁移实验给出旧行保留和拒绝破坏性降级的具体起点。
迁移身份、成功标记与锁必须记录,不能各worker重复执行。备份恢复也会改变数据身份,备份后已成功写入可能丢失,需要说明RPO(可接受的数据损失窗口)。若第三份身份不兼容,就阻止自动回退,选择前向修复或经验证的恢复方案;不能只让第一份产物回到旧版本。
容易踩的坑与发布证据
失败恢复演练:从当前状态决定下一步
一次实用演练可以按阶段注入失败:产物已取得但哈希不符,安装完成但配置缺字段,进程已启动但业务 readiness 失败,接入已切换但关键查询报错,旧实例排空到一半时超出预算。每种失败的恢复对象不同。第一种应拒绝产物并保留证据;第二种不能改成静默默认让程序带未知配置启动;第三种不应放行流量;第四种先检查旧程序的数据兼容;第五种要判断哪些已接纳操作需要持久恢复。
恢复记录应写出当前 release、数据库修订、接入目标、存活实例和正在执行的操作身份。发布脚本重入时先读取这些事实,而不是认定上一次失败等于所有步骤都没有发生。例如迁移已经提交而后续启动失败,重跑不能再执行无保护的数据搬迁;应用已经处理写入以后切回旧版本,也不能删除新增记录来模拟原状态。补偿是新的业务动作,可能失败,需要自己的身份与审核记录。
环境重建可以设计一次来源外运行的坏变体:在构建时漏掉一个资源文件,本地源码测试通过,但干净安装以后资源加载失败。证据包括 wheel 文件清单、安装分发文件列表和实际资源查找入口,修复应让构建配置带上资源并重新取得产物摘要。不要把缺失文件手工复制到生产目录作为最终修复,因为下一次干净部署仍会失败,而且当前实例不再符合可信产物清单。
配置变更也要做兼容矩阵。旧程序读哪些字段、新程序新增哪些字段、回滚时能否继续接受、密钥轮换是否允许两个版本同时认证,应分别记录。环境文件作为密钥传递方式是否满足平台策略由实际运行权限决定,本文不把模板当成统一推荐。需要新旧密钥并存时明确过渡窗口和撤销条件;不能为了回滚方便无限保留旧凭据,也不能在旧实例尚未排空时提前撤销其必要访问。
验收人还应验证发布报告中的身份是否真的来自运行实例。一个常见误差是 CI 记录了产物版本,但服务启动日志没有 release_id,查询端点也不能关联进程;发生异常只能猜新版本是否生效。将非敏感身份加入启动和请求日志,并保存目标 PID 与启动时间,能区分残留旧进程、负载均衡流量未切完和新代码本身错误。多个实例必须逐个核对,不从一次成功响应推断整组实例一致。
最后,练习回滚不应删除证据。保留失败产物摘要、日志窗口、迁移状态和触发回退的指标,才能复盘是构建、配置、数据还是代码原因。只有恢复服务而没有解释阶段,会让下次发布再次遇到同样问题;反之,仅解释根因却没有恢复预算,也不满足运维交付。完整演练需要把止损时间、长期修复和防复发检查分别落到可执行任务上。
常见坑是“探针成功一次就关闭旧实例”。短探针可能没碰到写入、分页、权限或慢依赖。切换观察应包含错误率、关键业务结果、尾延迟和资源趋势,观察窗口按业务决定;不能将过载下的短暂成功当作稳定证据。旧实例也不能无限保留,否则连接、缓存和后台任务数量都可能翻倍。每个阶段要有退出条件与预算。
另一个坑是回滚脚本只改代码却忘记配置。配置已经删除旧程序依赖字段时,切回代码仍无法启动。发布记录应保存产物、依赖锁、非敏感配置身份、数据库迁移身份、探针结果与停止证据。与 OS 进程创建退出的关联是父子进程和退出协议,Python 后台任务不能以“主 PID 消失”宣称全部安全收尾。
能力任务与验收
用第28篇真实服务创建两份可安装产物,在新的环境、源码树外启动;故意制造漏资源和错环境,保存身份字段定位。再执行一次兼容迁移、发布和回滚,最后执行一个明确不兼容的变体并证明自动回退被阻止。Linux 部署必须补实际命令输出和停止证据;没有环境时将此关卡保留待验证,不能用本文临时 JSON 实验替代。
通过依据是干净安装、业务 readiness、运行身份、失败切换保留当前版本、停止后任务与连接闭合,以及回滚后的正确业务数据。参考解答只能展示一种发布协议;读者要写简短 ADR(Architecture Decision Record,架构决策记录),说明为什么选择环境隔离、迁移方式和恢复策略,并列出不能自动补偿的副作用。命令成功不等于交付成功,状态机每个失败分支都需要能恢复。
一句话总结:可靠回滚依赖可验证产物、真实运行身份和当前数据兼容,而不是把代码目录切回旧提交。
- 固定依赖、验证哈希和可重复构建是不同承诺,逐项保存证据。
- 启动、就绪、排空和终止各有契约,端口监听不能替代业务验证。
- 应用回退前检查数据与配置兼容,不把数据库历史当成可自动撤销。
来源:pip 可重复安装、systemd.service 在线手册。在线文档可能随版本更新,Linux 模板仍须目标环境实测。