---
url: /v6.2/install-upgrade-notice.md
---
# 版本升级注意事项

本文介绍升级版本中的注意事项，请仔细阅读后执行后续升级操作。

## need migrate data, skip installation

当安装程序检测到当前已安装和升级包内的组件版本不一致时, 无法通过直接替换进行升级。

需要通过脚本来做数据迁移后才能进行升级操作。

* 使用衡石内置数据库(metadb)，参考 [数据库服务升级](metadb-upgrade.md)
* 使用衡石内置对象存储(minio)，参考 [对象存储服务升级](minio-upgrade.md)

## Version<=4.2版本升级到此版本

1. Metadb 版本不支持9.x 版本，升级前请确认使用的 Metadb 版本信息。

   1. 使用衡石内置数据库，参考 [数据库服务升级](metadb-upgrade.md)
   2. 使用外部数据库，自行升级数据库版本，建议升级版本为13.xx。

2. JDK 版本不在支持1.8版本，容器、K8s 部署方式忽略此问题，VM 单机、集群部署方式升级操作前 必要执行 init-os all
   1. 内网环境联系售后人员获取 JDK 静态资源

```shell
cd /opt/hengshi/lib
export hs_version="openjdk-11.0.17_8.1"
wget https://download.hengshi.com/hs-jdk/${hs_version}.tar.gz
tar -zxf ${hs_version}.tar.gz && rm ${hs_version}.tar.gz
ln -sf ${hs_version} jdk
```

2. 注意 如有要求使用特定 JDK 版本，请在 conf/hengshi-sense-env.sh 配置下列参数

```shell
export HS_JDK_HOME="JDK 安装目录"  # bin 目录上级目录位置
```

3. 提供内置的 Doris 引擎，如需存在使用 Doris 引擎作为内置默认引擎需求，请参考[Doris 引擎配置](engine-doris-config.md)

## 版本回滚到 Version<4.4版本

1. 4.4版本对 Greenplum 引擎进行逻辑层面的优化，不兼容 Version<4.4版本程序启动运行，执行版本回滚操作前，执行下列操作

```shell
cd /opt/hengshi
bin/clean_engine.sh -d true
```

执行结束后，继续进行版本[回滚操作](backup-restore.md#恢复-engine)

## 使用外部 PostgreSQL 数据库替代 Metadb 注意事项

请参考[替换衡石 metadb](rds-replace-of-postgres.md#准备工作),准备工作中 **使用超级管理员账号对用户进行授权操作** 步骤。

## 配置二级路径注意事项

本版本中不再支持使用**CONTEXT_PATH**参数实现二级路径访问。
如果需要二级路径访问请参考[二级访问路径配置](install-configure.md#二级访问路径配置)

## 清理 minio 注意事项

之前版本有些删除 app 的场景没有删除图片，导致 minio 产生了一些无用的图片。因此对 minio 无用的图片进行清理，完善删除逻辑，重新进行存储布局。

升级前请做好以下准备工作。

1. 做好 minio 备份（包括云上环境）及 metadb 备份。
2. 升级时需等待清理逻辑执行完成，可以通过观察日志了解清理的进度，可以通过`MinioImageClean`过滤出相关信息。经测试，清理11G 的无用照片大概需要4分钟左右。

> \[!TIP] 版本影响范围: 4.5.4及之前版本、4.6版本，4.6.1版本升级到当前版本时会执行 minio 清理操作，其他版本升级到当前版本时不会执行 minio 清理操作。

## LDAP 认证方式修改默认配置

LDAP 认证方式启用用户属性默认配置为 false，升级时不再同步用户属性。所以在升级前请确认是否需要同步用户属性，如果需要同步请将该配置设为 true。

> \[!TIP] 版本影响范围: 4.5.11及之前版本、5.0.0版本、5.0.1版本、5.0.2版本、5.0.3版本、5.0.4版本、5.1.0 版本升级到当前版本时需要检查该配置项。

## 会话 Cookie 修改默认名称注意事项

会话 Cookie 的默认名称为`_USER_SESSION_ID`，升级后需要重新登录。如客户系统有使用原 Cookie 名称 `sid` 的逻辑，需要修改为新的名称`_USER_SESSION_ID`，
或者设置参数 export SESSION_COOKIE_NAME=sid（原 cookie 名称）。

> \[!TIP] 版本影响范围: 4.5.15及之前版本、5.0.0~5.0.8、5.1.0~5.1.4 ，其他版本不受影响。

## 6.0+ 首次升级健康检查配置

6.0.0 的升级迁移过程耗时较长，不同的 metadb 数据量，cpu 性能，磁盘 io 性能相应的耗时不同，例如 metadb 40GB (7.5万仪表盘，43万图表)，Xeon W-2191B @ 2.30GHz，普通云盘SSD 升级大约需要 15 分钟左右。建议在首次 6.0+ 进行大版本升级前先关闭启动健康检查，**升级和成功启动后再恢复健康检查**。以下为几种部署方式的修改建议：

#### 2-1 关闭健康检查

::: details \[单机和集群部署]

停止monit监控服务

```shell
${HENGSHI_HOME}/bin/hengshi-sense-bin stop monit
# {HENGSHI_HOME} 为hengshi安装的目录变量，不能直接复制执行。
```

:::

::: details \[docker 部署]

将 docker-compose 文件中 hengshi 部分的 healthcheck 注释掉再启动 hengshi 服务

```shell
    healthcheck:
      test: /opt/hengshi/bin/hengshi-sense-bin health hengshi
      interval: 10s
      timeout: 30s
      retries: 90
```

:::

::: details \[k8s 部署]

将 hengshi-sense deployment 部署清单中的三项注释掉再启动 hengshi 服务

* startupProbe
* livenessProbe
* readinessProbe

```shell
kubectl -n [namespace] edit deployment hengshi-sense
```

```shell
          startupProbe:
            exec:
              command:
                - /bin/bash
                - /opt/hengshi/bin/hengshi-sense-bin
                - health
                - hengshi
                - single
            periodSeconds: 10
            successThreshold: 1
            failureThreshold: 90
          livenessProbe:
            exec:
              command:
                - /bin/bash
                - /opt/hengshi/bin/hengshi-sense-bin
                - health
                - hengshi
                - single
            periodSeconds: 10
            successThreshold: 1
            failureThreshold: 3
          readinessProbe:
            exec:
              command:
                - /bin/bash
                - /opt/hengshi/bin/hengshi-sense-bin
                - health
                - hengshi
                - single
            periodSeconds: 10
            successThreshold: 1
            failureThreshold: 3
```

:::

#### 2-2 成功后恢复健康检查

::: details \[单机和集群部署]\
恢复monit监控服务

```shell
${HENGSHI_HOME}/bin/hengshi-sense-bin start monit
# {HENGSHI_HOME} 为hengshi安装的目录变量，不能直接复制执行。
```

:::

::: details \[docker 部署] 与 \[k8s 部署]\
将关闭阶段注释掉的内容恢复，再重启 hengshi 服务
:::

> \[!TIP] 版本影响范围: 6.0.0 之前版本首次进行 6.0+ 的升级，比如 4.5.x -> 6.2.y、5.4.x -> 6.0.y\
> 已经在运行 6.0+ 版本的系统再次进行大版本升级不受影响，即 6.0.x -> 6.1.0 不受本事项影响，无需关闭健康检查进行首次升级

## 6.0+ nginx 配置修改

6.0.0 前端优化了静态文件的缓存逻辑，相应的需要在衡石的前置反向代理增加对入口静态文件的缓存配置，以 nginx 举例在衡石的 server 段落内增加：

```conf
location ~* \.(html|htm)$ {
    add_header Cache-Control "no-store, no-cache, must-revalidate";
    add_header Pragma "no-cache";
    add_header Expires "0";
}
```

[完整 nginx 配置参考](software-config-faq.html#如何通过80和443端口进行服务？), **其他代理或云上LBS需对应逻辑配置**

> \[!TIP] 版本影响范围: 6.0.0 之前版本升级 6.0.0+

## 6.2+ k8s 部署注意

> \[!WARNING] 从 6.1 升级到 6.2 或更高版本
> 6.2 起 k8s 配置包新增 `hengshi-rbac.yaml`，用于授予 `default` ServiceAccount
> `namespaces/get` 权限。升级时必须补充以下两步，否则 hengshi 容器将因权限不足而异常。

**1. 替换 namespace 占位符**

```shell
# 将 __HENGSHI_NAMESPACE__ 替换为实际 namespace 名称
sed -i 's/__HENGSHI_NAMESPACE__/<namespace>/' hengshi-rbac.yaml
```

**2. 应用 RBAC 配置**

```shell
kubectl -n <namespace> apply -f hengshi-rbac.yaml
```

> \[!TIP]
> `hengshi-rbac.yaml` 位于对应版本的 k8s 配置包内。完整部署流程参见
> [Kubernetes 部署指南](k8s.md#部署前准备)。