部署升级与备份恢复
很多安装部署问题，其实不是“安装命令不会用”，而是部署后工作、迁移切换、备份范围、代理配置这些边界没有提前想清楚。这页把高频运维 FAQ 集中整理出来。
迁移服务器时，最容易漏掉什么？
最容易漏掉的是：新环境虽然装好了，但还没验证网络、防火墙、重点报表和回滚路径，就急着切流。
更稳妥的迁移顺序通常是：
- 先在新服务器部署并完成访问验证
- 老服务器停服后导出 metadb 和 MinIO 数据
- 导入到新服务器
- 重点验证服务状态和关键报表
- 最后再切换域名或流量
其中最容易被忽略的是第 4 步。很多迁移事故不是“导不进来”，而是“导完没充分验证就切换了”。
迁移时，哪些数据必须备份，哪些通常不用迁？
优先级最高的是：
- metadb
- MinIO 对象存储
而内置数仓 / engine 数据，很多场景下不建议优先做完整迁移，而是在新环境恢复后重新触发同步任务更新。
如果你把所有数据都当成“必须原样搬走”，不仅迁移时间更长，也会增加回滚复杂度。
升级前最重要的两个动作是什么？
- 先停旧版本服务
- 确认备份和回滚路径可用
标准升级流程本身已经比较明确，但真正常出问题的是：
- 没有先停干净旧服务
- 升级前没确认 backup 是否可用
- 升级后发现异常时，不知道回滚包和回滚步骤在哪
所以升级前不要只盯安装包，更要确认“失败后怎么退回来”。
Docker 或 K8s 部署升级时，镜像 OS 变了要处理内置 PostgreSQL 吗？
需要。如果升级前后使用的 Docker 或 K8s 镜像底层 OS 发生变化，例如从 CentOS 7 切换到 AlmaLinux 8，底层 glibc / locale 规则可能随之变化。PostgreSQL 的字符串排序和唯一索引依赖这些规则，继续复用升级前的数据目录时，已有索引可能需要重建。
该操作只适用于使用 HENGSHI 内置 PostgreSQL 的环境。使用外部 PostgreSQL 时，请由数据库管理员按外部数据库的变更规范处理。
建议在升级完成、业务正式恢复前执行：
- 完成 metadb、文件存储等必要备份，并安排维护窗口。
- 升级镜像后，让内置 PostgreSQL 处于可连接状态，业务服务保持停止或暂不对外开放。
- 连接 metadb 所在数据库，执行：
REINDEX DATABASE hengshi;- 如果环境使用了内置文件上传 / 文件存储数据库，再连接对应数据库，执行：
REINDEX DATABASE hengshi_sense_internal_storage;- 重建完成后再启动或放开 HENGSHI 业务服务，并验证关键报表、登录、文件上传和下载。
如果升级后已经出现唯一约束字段重复、保存时报名称重复等异常，先停止业务写入并联系技术支持清理重复数据。存在重复数据时直接执行 REINDEX 可能失败，不能替代数据清理。
为什么服务在服务器上能访问，从外部机器却访问不了？
这通常不是 HENGSHI 服务没起来，而是端口没开放 / 防火墙没放行 / 代理没配好。
最常见的判断顺序：
- 先在服务器本机
curl http://127.0.0.1:8080 - 再从外部机器
curl http://IP:8080 - 如果本机通、外部不通，就优先查防火墙和安全组
不要一上来就怀疑应用进程挂了。
HENGSHI 的端口应该怎么对外暴露？
不建议把内部服务端口直接裸露给外网。
更推荐的方式是：
- 内部服务按默认方式运行
- 通过 Nginx 等反向代理对外提供统一入口
- 对外暴露 HTTPS
而且部署后建议在代理层启用：
- HTTP/2
- gzip
这不仅是安全问题，也会直接影响最终访问体验。
代理后为什么会报“页面缓存失效，请刷新浏览器”？
一个高频原因是：代理组件改写了 cookie 名称或格式，导致系统无法正常解析 cookie，也拿不到 x-csrf-token。
也就是说，这类问题通常不是“前端缓存真坏了”，而是代理链路把登录态相关 cookie 改坏了。
如果你看到代理后 cookie 从原本的 csrf=...、sid=... 变成了其他特殊前缀形式，就应该先查代理规则，而不是先让用户不停刷新。
备份恢复最常见的误区是什么？
最常见的误区是：只记得备份，不记得演练恢复。
建议至少明确三件事：
- 备份文件放在哪里
- 恢复时要停哪些服务、挪走哪些旧目录
- 恢复完成后如何验证业务是否真的可用
如果没有恢复演练，很多“看起来备份成功了”的数据在真正故障时并不能快速接回。
升级或迁移后，什么时候才算真正完成？
不是“服务启动了”就算完成，而是至少要同时满足：
- 服务状态正常
- 关键报表能打开
- 外部访问链路正常
- 必要时具备明确回滚路径
如果只是看到进程 IS ACTIVE 就宣布完成，很多问题会在切换后才暴露。
进一步阅读：