GEOFlow Updater完全指南：签名更新、完整备份与恢复点回滚告别升级事故-育师

GEOFlow Updater完全指南：签名更新、完整备份与恢复点回滚告别升级事故

【免费下载链接】GEOFlowOpen-source GEO content engineering and multi-site distribution platform with AI quality inspection, illustrated admin help, hosted sites, browser-assisted publishing, and signed updates.项目地址: https://gitcode.com/gh_mirrors/geof/GEOFlow

GEOFlow Updater 是 GEOFlow 运行在宿主机上的独立更新工具，一次提供签名更新、完整备份、恢复点回滚三大能力：升级包经过 TUF + Ed25519 签名校验，每次更新前自动生成完整恢复点，出问题时一键回到升级前的版本与数据。对于负责运维 GEOFlow 站点的管理员来说，这套机制把"升级事故"从不可控的风险变成了可预检、可备份、可回滚的标准流程。🛡️

GEOFlow Updater 是什么

GEOFlow Updater 不是一个后台按钮，而是安装在 Linux 宿主机上的 systemd 服务（geoflow-updater）。它负责四类工作：

能力	说明
签名安装	首次安装站点时拉取签名镜像，自动生成密钥与凭据
签名升级	按 TUF 签名计划预检，蓝绿双槽位切流升级
完整备份	停写后备份数据库、业务存储、Redis 与环境配置
恢复点回滚	应用回切或回到任意完整恢复点

网站后台的"系统更新"页面（默认/geo_admin/system-updates）只是它的管理入口，真正的执行边界在宿主机上——这也是它比"后台一键拉包"方案更安全的原因。核心实现位于 app/Services/SystemUpdater/ 目录，升级流程的发布门禁记录在 docs/deployment/SYSTEM_UPDATER_PHASE_C.md。

签名更新：如何确认升级包是"官方出品"

升级事故的第一个来源是"来路不明的代码"。GEOFlow Updater 用三层机制拦截这个问题：

TUF 签名清单：每次发布都附带签名清单（root/targets 双角色、阈值签名），应用端会逐字段严格校验。校验器 TufBootstrapVerifier.php 会拒绝字段不符、签名数不足、已过期或资产 URL 不在官方发布前缀内的任何清单，并强制校验每个资产的 sha256 摘要与大小。
迁移文件指纹：升级计划文件 deployment/upgrade-plan.json 为每一条数据库迁移固定了sha256摘要，迁移执行前会先比对文件内容，确保执行的正是计划声明的那份迁移。
操作级授权：后台的更新、备份、回滚操作分别需要独立的 6 位动态授权码 + 管理员密码二次确认。授权码条目只能消费一次，连续五次输错会触发 15 分钟锁定。作用域定义见 RemoteUpdaterService.php 中的SCOPES常量。

协议版本约束记录在 deployment/recovery-contract.json，防止新旧版本 updater 之间的不兼容操作。

获取升级计划：先预检，再动手

无论用后台还是服务器命令，正确姿势都是"预检 → 核对 → 确认执行"。在宿主机执行：

sudo geoflow-updater doctor --instance primary --json sudo geoflow-updater update --instance primary --dry-run --json

预检返回几个关键字段：

字段	含义
`target_version`	即将安装的版本
`strategy`	`online`（在线蓝绿升级）或`maintenance`（需维护窗口）
`layout_change`	是否首次转换为蓝绿布局
`pending_migrations`	尚未执行的数据库迁移数
`plan_sha256`	执行时必须原样提交的预检摘要

拿到plan_sha256后再执行更新；计划变了就重新预检，不要强行提交。后台操作路径是：打开"系统更新"→ 点击"获取升级计划" → 核对策略 → 点"检查并安全更新"并填写密码和update授权码 → 等待状态变为"已完成" → 运行环境验收。详细步骤见 docs/blue-green-deployment-usage.md 第 7、8 节。

💡 提示：预检可能拉取镜像、启动临时检查容器，最长可运行 25 分钟，请耐心等待，它不会执行迁移或切流。

完整备份：先准备好"后悔药"

完整备份会暂停服务和写入，需要安排在维护窗口内执行：

sudo geoflow-updater backup --instance primary --json sudo geoflow-updater recovery-points --instance primary

一个恢复点包含：PostgreSQL 全库、完整业务存储、停写后的 Redis 数据、环境配置与受管部署文件。系统默认保留 5 个恢复点，并自动保护"最近一次更新前的检查点"——这正是每次升级的默认回滚目标。

恢复点回滚：升级出问题的两条退路

当升级后业务异常时，根据数据状态选择一条路径：

应用回切（保留当前数据）：适用于已成功完成的在线蓝绿升级。执行sudo geoflow-updater switch-back --instance primary --json，切回上一应用版本，继续共用当前数据库与业务文件，升级后的新写入不丢失。
数据恢复（回到完整恢复点）：需要同时恢复数据、配置和版本时使用。先用recovery-points核对恢复点 ID，再执行rollback --recovery-point <ID>。注意：恢复点之后的新增数据会被覆盖，务必先确认时间点和业务影响。

后台对应入口为"应用回切"（update授权码）与"恢复数据与版本"（rollback授权码，只允许最近一次更新前检查点）。源码脚本 scripts/geoflow-deploy.sh 提供等价的rollback --application/rollback --data命令。

日常升级五步清单

✅ 暂停新增任务，排空队列，确认无运行中的更新操作
✅ 预检dry-run，核对strategy与plan_sha256
✅ 安排维护窗口（maintenance策略必需），完成完整备份
✅ 提交执行，观察阶段进度直到succeeded
✅ 验收：登录、文章读写、队列任务、实时消息、doctor与verify全绿

升级失败时的标准处理：状态为rolled_back说明已自动恢复旧版本，先确认可用再排查；状态为recovery_required时保留现场，检查失败阶段日志并走数据恢复。不要删除部署日志、锁文件或数据卷。常见问题对照表见 docs/blue-green-deployment-usage.md 第 11 节，3.0.0 → 3.1.0 的具体路径见 docs/deployment/GEOFLOW_V3_1_UPGRADE.md。