---
order: 4
navTitle: 集群
indexTitle: 集群环境安装
---
# 集群环境安装

SuccBI支持集群，部署集群环境主要有如下步骤：

\[\[toc]]

## 申请支持集群的产品许可{#require-license}

支持集群需要申请产品许可，申请方法：

1. 先部署好一个节点，连接好[默认数据库](../install/basic-install/workdir-and-defdb.md#defjdbc)，启动节点，系统会自动初始化数据库系统表。
2. 进入**系统设置**页面，选择**产品许可**，点击**更新注册码**按钮，按照页面指示申请注册码。
3. 其他的集群节点不需要再次申请注册码，注册码可以同时作用到集群其它节点上。

:::tip
不申请新的注册码也可以继续部署集群，系统会有一定概率显示提示申请注册码的页面，不影响集群部署和试用，建议生产环境尽快申请。
集群环境上更新注册码时在任意节点上更新都会作用到整个集群，建议在相对稳定不变的集群节点上更新注册码。
:::

## 开放集群通讯端口{#config-firewall}

放开服务器的防火墙的**TCP**协议的**7800**～**7805**端口。

集群节点默认使用**TCP**协议的**7800**端口进行通讯，端口被占用时（比如在一个服务器上启动多个节点）会自动使用7801、7802、7803……。

## 配置节点间的文件共享磁盘{#config-sharefolder}

集群节点需要一个共享的、读写的文件系统目录，以便存储一些集群间共享的文件，如用户上传的文件。位置位于工作目录的`clusters-share`，见[工作目录的结构](../install/basic-install/workdir-and-defdb.md#dir)。

> 如果项目没有共享存储以下信息的需求（比如用户不会上传文件、没有表单流程附件、也不需要用户头像），那么可以不用配置`clusters-share`目录，集群依然可以工作。

共享目录下主要有如下子目录：

1. **upload-files/** - 存放临时的上传文件的地方
2. **app-attachments/** - 报表填报应用中用户提交的附件，分项目存储，一个项目一个子目录
3. **meta-thumbnails/** - 元数据的缩略图
4. **co-screenshots/** - 评论和备注中用户上传的截图
5. **avatars** - 头像，文件名：userid+.png

配置方法：

1. 选择一个性能好的集群节点（也可以选择一个专用的存储服务器）作为共享文件存储服务器，确保磁盘和网络性能好。
2. 通过NFS(Network File System)将共享文件存储服务器的目录映射到每个节点服务器的工作目录的`clusters-share`目录上。
   1. 也可以使用其它分布式文件存储技术，比如AFS。
   2. 由于系统启动时会自动创建`clusters-share`目录，所以配置时需要停止服务器，删除系统原来创建的`clusters-share`目录。
   3. 做一个简单测试，在一个节点的`clusters-share`目录中创建一个文件，看看其它节点能否看到。

## 部署集群节点{#deploy-nodes}

在集群节点服务器上部署好SuccBI，都连接同一个默认数据库，见[配置默认数据库](../install/basic-install/workdir-and-defdb.md#defjdbc)

1. 确保多个节点部署在同一个服务器时，工作目录不要共用，Web端口不冲突。
2. 确保配置文件中**没有**设置~~-Dsucc.cluster.enable=false~~。
3. 多个部署直接连接同一个默认数据库且它们的网络互通时会自动识别为一个集群。
4. 注意节点部署的产品版本号要一致，如都是`v4.16.4 201910130814-11d56d0e-1174`，确实需要部署不一致的版本时也必须要确保主版本号和次版本号（即`v4.16`这部分）一致，补丁号和buildNumber可以不一致。
5. 服务器有多IP时，需要指定IP，见[多IP时如何指定IP](#多IP时如何指定IP)。

部署完成后启动所有节点，打开浏览器访问其中一个节点，进入**系统设置**>**集群**，检查下节点是否都被识别为集群节点。

## 负载平衡（Load Balancing）{#load-balancing}

负载平衡支持软负载平衡如（nginx或apache）或硬件负载（如F5），请根据不同负载平衡服务器的操作文档进行配置。基于nginx的负载平衡配置方法如下：

1. <http://nginx.org/en/docs/http/load_balancing.html>

## 会话粘滞（sticky sessions）{#sticky-sessions}

会话粘滞是确保一个用户在一次登录会话中始终访问集群中的同一个节点。SuccBI暂时不支持非会话粘滞的集群方式，请根据不同负载平衡服务器的操作文档进行配置。

会话粘滞的方式通常有根据IP或根据Cookie，当用户的使用代理服务器访问负载平衡服务器时可能很多用户的IP都是一样的，此时建议使用Cookie中的**JSESSIONID**配置会话粘滞。

## Docker下部署集群{#docker}

SuccBI同样支持在Docker下部署集群，具体步骤见[Docker部署SuccBI集群](../docker/docker-cluster.md)。

## 集群疑难问题排查{#faq}

### 启动时提示“加入集群(xxx)失败”{#faq-join-fail}

一个局域网内可能有多个集群，不同的集群间的通信不能互相干扰，所以加入集群是有一个认证机制的，满足下列情况才能加入集群：

1. 节点间网络互通，无法连接时，检查网络或防火墙设置。
2. 节点部署的产品主次版本号必须一致，如`v4.16.8 201910130814-11d56d0e-1174`中的`v4.16`必须一致，补丁号、日期和buildnumber等可以不一致，但推荐完全一致。
3. 所有节点必须连接同一个默认数据库，默认数据库配置中的`url`和用户名配置必须严格一致。

### 多IP时如何指定IP{#faq-multipulip}

如果服务器有多个IP，需要检查集群通讯使用的IP是否是内网局域网IP，进入**系统设置**>**集群**可查看IP，可以通过环境变量配置：

1. `-Dsucc.clusterBindAddress=192.168.7.128`，指定集群通讯使用的IP，注意是一定是IP地址，而**不是IP范围**如~~192.168.208.3/4~~。
2. `-Dsucc.clusterBindAddressPrefix=192.168`，指定集群通讯使用的包含指定**前缀**的IP。