升级、备份与恢复
升级包含应用版本、数据库结构、基础数据和运行配置的变化。先记录当前状态，再在隔离环境演练；当前 CLI 没有通用 backup、restore 或自动 rollback 命令。
备份清单
| 内容 | 默认位置或来源 | 恢复时的作用 |
|---|---|---|
| PostgreSQL | hohu-pgdata 卷或外部数据库 | 业务数据、账号、授权与迁移版本 |
| 公开与私有文件 | 部署目录 uploads、private_uploads | 图片、导入导出文件和业务附件 |
| 部署配置 | .hohu/deploy/.env 与自定义 override | 连接、密钥、版本与服务拓扑 |
| 应用与镜像版本 | IMAGE_TAG、镜像 ID/摘要、源码提交 | 与恢复后的数据库匹配 |
| 证书与自动化配置 | 实际证书及受控运维配置 | 恢复入口与后续维护 |
| Redis / 监控数据 | 对应持久卷或外部服务 | 按恢复目标处理会话、短期状态和历史监控 |
保管 SECRET_KEY 等原密钥；加密保存的 Provider 或邮件凭据不能靠新生成的密钥解密。数据库快照与文件备份应处于可对应的业务时间点，备份保存到独立位置并验证可读。
数据库可使用 PostgreSQL 的逻辑备份或数据库服务商快照。pg_dump 不包含数据库角色等集群全局对象，需要单独规划；不要把运行中的数据目录简单复制当作一致备份。具体方式见 PostgreSQL 备份说明。
升级步骤
- 记录 CLI、镜像或源码版本，以及数据库当前 Alembic revision；查阅更新说明。
- 在隔离环境恢复备份，演练目标版本迁移和功能验证。
- 安排维护窗口，停止入口写入及相关后台任务，完成最后一份一致备份。
- 选择下表中的更新路径；检查迁移与种子同步退出结果。
- 验证登录、普通账号权限、租户、设置、文件、任务和 AI，再恢复业务流量。
| 部署方式 | 更新步骤 |
|---|---|
| 已发布镜像 | 修改部署配置中的目标镜像/标签，运行 hohu deploy pull |
| 独立组件源码仓库 | 分别更新配套源码，运行 hohu build、hohu deploy |
| 可拉取的项目根 Git 仓库 | 满足前提后可用 hohu deploy upgrade |
pull 会迁移并启动应用，不是只下载镜像。upgrade 只在项目根执行一次 git pull，随后构建、停止与重新部署；不会逐个更新独立组件仓库，也不是无停机升级。完整前提见 CLI 部署。
不要用 --no-migrate 跳过版本必需的结构或种子更新。独立 migrate 的外部依赖限制见迁移参考。
支持的数据库起点
当前迁移支持空库和 v0.1.4 发布边界 bf244f9a8b76。更早版本先沿对应旧发布链升级到该边界，再切换当前版本。曾运行压缩前实验迁移的开发库不属于自动升级范围。
迁移失败时保留错误和当前 revision；不能用 stamp head 把版本号伪装为已升级。准确 head 以匹配版本的 Alembic 输出为准，维护说明见后端仓库 docs/DATABASE-MIGRATIONS.md。
恢复步骤
- 保持维护状态，保存失败日志，判断是否已经写入新版本数据。
- 在隔离目标恢复配套数据库、文件、原密钥和应用版本；避免直接覆盖唯一的原始备份。
- 按恢复目标处理 Redis 的旧会话和待确认任务，不将过期的执行上下文视为仍有效。
- 验证账号、权限、数据数量、文件引用及任务，确认后切换流量并恢复写入。
切回旧镜像不会自动恢复数据库。downgrade 可能删除表或字段，不能代替经过演练的数据恢复。记录恢复点与可能的数据差异，避免将旧文件配上新数据库继续运行。