---
url: /v6.2/deployment-upgrade-faq.md
---
# 部署升级与备份恢复

很多安装部署问题，其实不是“安装命令不会用”，而是**部署后工作、迁移切换、备份范围、代理配置**这些边界没有提前想清楚。这页把高频运维 FAQ 集中整理出来。

## 迁移服务器时，最容易漏掉什么？

最容易漏掉的是：**新环境虽然装好了，但还没验证网络、防火墙、重点报表和回滚路径，就急着切流。**

更稳妥的迁移顺序通常是：

1. 先在新服务器部署并完成访问验证
2. 老服务器停服后导出 metadb 和 MinIO 数据
3. 导入到新服务器
4. 重点验证服务状态和关键报表
5. 最后再切换域名或流量

其中最容易被忽略的是第 4 步。很多迁移事故不是“导不进来”，而是“导完没充分验证就切换了”。

## 迁移时，哪些数据必须备份，哪些通常不用迁？

优先级最高的是：

* **metadb**
* **MinIO 对象存储**

而内置数仓 / engine 数据，很多场景下**不建议优先做完整迁移**，而是在新环境恢复后重新触发同步任务更新。

如果你把所有数据都当成“必须原样搬走”，不仅迁移时间更长，也会增加回滚复杂度。

## 升级前最重要的两个动作是什么？

1. **先停旧版本服务**
2. **确认备份和回滚路径可用**

标准升级流程本身已经比较明确，但真正常出问题的是：

* 没有先停干净旧服务
* 升级前没确认 backup 是否可用
* 升级后发现异常时，不知道回滚包和回滚步骤在哪

所以升级前不要只盯安装包，更要确认“失败后怎么退回来”。

## Docker 或 K8s 部署升级时，镜像 OS 变了要处理内置 PostgreSQL 吗？

需要。如果升级前后使用的 Docker 或 K8s 镜像底层 OS 发生变化，例如从 CentOS 7 切换到 AlmaLinux 8，底层 glibc / locale 规则可能随之变化。PostgreSQL 的字符串排序和唯一索引依赖这些规则，继续复用升级前的数据目录时，已有索引可能需要重建。

该操作只适用于使用 HENGSHI 内置 PostgreSQL 的环境。使用外部 PostgreSQL 时，请由数据库管理员按外部数据库的变更规范处理。

建议在升级完成、业务正式恢复前执行：

1. 完成 metadb、文件存储等必要备份，并安排维护窗口。
2. 升级镜像后，让内置 PostgreSQL 处于可连接状态，业务服务保持停止或暂不对外开放。
3. 连接 metadb 所在数据库，执行：

```sql
REINDEX DATABASE hengshi;
```

4. 如果环境使用了内置文件上传 / 文件存储数据库，再连接对应数据库，执行：

```sql
REINDEX DATABASE hengshi_sense_internal_storage;
```

5. 重建完成后再启动或放开 HENGSHI 业务服务，并验证关键报表、登录、文件上传和下载。

如果升级后已经出现唯一约束字段重复、保存时报名称重复等异常，先停止业务写入并联系技术支持清理重复数据。存在重复数据时直接执行 `REINDEX` 可能失败，不能替代数据清理。

## 为什么服务在服务器上能访问，从外部机器却访问不了？

这通常不是 HENGSHI 服务没起来，而是**端口没开放 / 防火墙没放行 / 代理没配好**。

最常见的判断顺序：

1. 先在服务器本机 `curl http://127.0.0.1:8080`
2. 再从外部机器 `curl http://IP:8080`
3. 如果本机通、外部不通，就优先查防火墙和安全组

不要一上来就怀疑应用进程挂了。

## HENGSHI 的端口应该怎么对外暴露？

不建议把内部服务端口直接裸露给外网。

更推荐的方式是：

* 内部服务按默认方式运行
* 通过 Nginx 等反向代理对外提供统一入口
* 对外暴露 HTTPS

而且部署后建议在代理层启用：

* **HTTP/2**
* **gzip**

这不仅是安全问题，也会直接影响最终访问体验。

## 代理后为什么会报“页面缓存失效，请刷新浏览器”？

一个高频原因是：**代理组件改写了 cookie 名称或格式**，导致系统无法正常解析 cookie，也拿不到 `x-csrf-token`。

也就是说，这类问题通常不是“前端缓存真坏了”，而是代理链路把登录态相关 cookie 改坏了。

如果你看到代理后 cookie 从原本的 `csrf=...`、`sid=...` 变成了其他特殊前缀形式，就应该先查代理规则，而不是先让用户不停刷新。

## 备份恢复最常见的误区是什么？

最常见的误区是：**只记得备份，不记得演练恢复。**

建议至少明确三件事：

1. 备份文件放在哪里
2. 恢复时要停哪些服务、挪走哪些旧目录
3. 恢复完成后如何验证业务是否真的可用

如果没有恢复演练，很多“看起来备份成功了”的数据在真正故障时并不能快速接回。

## 升级或迁移后，什么时候才算真正完成？

不是“服务启动了”就算完成，而是至少要同时满足：

1. 服务状态正常
2. 关键报表能打开
3. 外部访问链路正常
4. 必要时具备明确回滚路径

如果只是看到进程 `IS ACTIVE` 就宣布完成，很多问题会在切换后才暴露。

进一步阅读：

* [单机环境版本升级](install-upgrade.md)
* [数据备份与恢复](backup-restore.md)
* [部署后工作及注意事项](post-deployment.md)