跳至主要內容

后端应用部署

王金城大约 10 分钟

目前后端应用部署不需要使用 tomcat，只需要将 jar 包放在服务器上直接运行即可。basic-paper-gateway 是所有程序的入口，所以必须部署它之后才能访问。我们推荐使用 安装包部署。

注意

  1. 确保已经安装好 数据库、redis 等基础设置。
  2. 确保已经安装的 nacos，创建了命名空间，并导入的默认配置文件。
  3. 确保已经安装了 nginx，并正确配置了反向代理。
  4. 确保已经安装了 jdk，并配置了环境变量（如果使用安装包部署可以不配置环境变量，可以使用捆绑 JDK 的方式，但不推荐）

安装包部署

安装包部署是将所有应用打包成一个 *.tar.gz 包，在服务器上解压成目录后可以使用内置脚本完成启动和停止，相对简单方便，推荐使用。我们以 basic-paper-cloud-server-1.0.0.tar.gz 为例来介绍如何安装。

部署步骤

解压安装包-> 修改配置文件 -> 启动应用

目录结构

警告

  1. 请勿改动 basic-paper-cloud-server 的目录结构，否则会导致程序无法启动！
  2. modules 目录下的 jar 包无法脱离 basic-paper-cloud-server 目录运行，请勿移动！
basic-paper-cloud-server           # 应用主目录
├─ bin                      # 脚本目录。内部存在启动、停止脚本
│  ├─ env.sh                # 环境变量脚本，无需执行。
│  ├─ shutdown-all.sh       # 停止全部服务脚本
│  ├─ shutdown-*.sh         # 停止独立应用脚本
│  ├─ startup-all.sh        # 启动全部应用脚本，会自动跳过已启动的程序。
│  └─ startup-*.sh          # 启动独立应用脚本
├─ conf                     # 配置文件目录
│  ├─ bootstrap.properties  # 通用引导配置文件，可以配置 nacos、日志输出等，影响全部模块。
│  └─ *.conf                # 其他模块专属配置文件，可以配置端口号、JAVA_OPTS 等，仅对应默认生效。
├─ jdk                      # 捆绑的 jdk 目录（默认是空文件夹，有需要可以自行替换）
├─ lib                      # 应用依赖目录
├─ logs                     # 默认的应用日志输出目录，如果不配置日志输出，日志会输出到这里。
└─ modules                  # 应用模块目录
   └─ *.jar                 # 其他模块 jar

解压安装包

将 basic-paper-cloud-server-1.0.0.tar.gz 解压到 /usr/local/simperfect 目录下。解压后会在 /usr/local/simperfect 目录下出现一个 basic-paper-cloud-server 目录。

tar -zxvf basic-paper-cloud-server-1.0.0.tar.gz -C /usr/local/simperfect

JDK 的安装

JDK 支持 配置系统环境变量 和 应用内捆绑 两种形式，推荐使用环境变量形式。

配置系统环境变量（推荐）

详见 JDK 安装

应用内捆绑（需要多版本 jdk 共存时的备用方案）

安装包内部 jdk 目录是空的，需要去官网下载最新的 JDK 21 并解压到该目录。 下面是以 21.0.3 为例的操作步骤

# 解压后会出现一个名为 jdk-21.0.3 的目录
tar -zxvf jdk-21.0.3_linux-x64_bin.tar.gz -C /usr/local/simperfect/basic-paper-cloud-server

# 进入对应目录
cd /usr/local/simperfect/basic-paper-cloud-server

# 将全部文件移动到 jdk 目录下
mv jdk-21.0.3/* ./jdk

# 删除 jdk-21.0.3 目录
rm -r jdk-21.0.3

修改配置文件

一般情况下只需要需改 conf/bootstrap.properties 文件即可。

警告

spring.cloud.nacos.namespace 应填写命名空间 ID，不是命名空间名称。不是名称！不是名称！不是名称！ 如果不知道什么是命名空间 ID，那么请先移步至 新建命名空间 查看如何新建命名空间。

这个配置文件是所有模块都会读取的。下面是默认内容：

# nacos 访问地址（必填）。配置多个，用逗号分隔开。如：127.0.0.1:8848,127.0.0.2:8848
spring.cloud.nacos.server-addr=
# 命名空间（必填），用于注册中心、配置中心的数据隔离（在同一个注册中心负责多个环境时极其重要），只读取此命名空间下的配置文件。
spring.cloud.nacos.namespace=
# nacos 账号密码（必填），注意：请务必将 nacos 服务器开启账号密码功能，并修改默认密码，严禁使用默认密码。
spring.cloud.nacos.username=
spring.cloud.nacos.password=
# 日志文件输出路径，请配置物理磁盘，防止日志写入延迟导致程序卡顿。一般情况不需要修改，默认会输出到项目根目录的 logs 中。
#logging.file.path=logs
# 日志文件备份路径，可以配置网盘路径，用于备份使用。尽量修改到拥有更大的存储盘中，默认会输出到项目根目录的 logs/bak 中。
#logging.file.bak-path=logs/bak
# 日志留存数量，由于按照日期存储的日志，所以这里可以理解为日志留存时间
logging.logback.rollingpolicy.max-history=180

参数说明

  1. spring.cloud.nacos.server-addr 和 spring.cloud.nacos.namespace 参数必填，请确保这两个参数配置正确。
  2. logging.file.path 为日志输出路径，一般情况下采取默认值即可，如果应用安装目录的磁盘真的很小可以考虑需改目录，但必须保证是物理盘，防止日志写入延迟导致程序卡顿。
  3. logging.file.bak-path 为日志备份路径，可以根据情况修改，但必须保证磁盘空间充足，防止磁盘写满导致各种问题。
参数
必填默认值说明
spring.cloud.nacos.server-addr✔️-nacos 访问地址，多个地址用逗号分隔。 如：127.0.0.1:8848,127.0.0.2:8848
spring.cloud.nacos.namespace✔️-命名空间，用于注册中心、配置中心的数据隔离（在同一个注册中心负责多个环境时极其重要），只读取此命名空间下的配置文件。
spring.cloud.nacos.username✔️-nacos 用户名，注意：请务必将 nacos 服务器开启账号密码功能，并修改默认密码，严禁使用默认密码。
spring.cloud.nacos.password✔️-nacos 密码，注意：请务必将 nacos 服务器开启账号密码功能，并修改默认密码，严禁使用默认密码。
logging.file.path❌logs日志文件输出路径，请配置物理磁盘，防止日志写入延迟导致程序卡顿。一般情况不需要修改，默认会输出到项目根目录的 logs 中。
logging.file.bak-path❌logs/bak日志文件备份路径，可以配置网盘路径，用于备份使用。尽量修改到网盘中，默认会输出到项目根目录的 logs/bak 中。
logging.logback.rollingpolicy.max-history✔️180日志留存数量，由于按照日期存储的日志，所以这里可以理解为日志留存时间

如果想要了解更多内容，可以跳转到 配置文件说明 中查看详情。

启动程序

所有的启动脚本都会判断当前程序是否已运行，如果运行则会跳过执行，在终端中会有日志输出。

批量启动

安装包 bin 目录内，内置了多个脚本，可以通过 ./startup-all.sh 脚本启动全部程序。

注意

为了防止批量启动导致服务器负载过高，脚本内部会进行暂停处理。 在终端上会出现一个进度条代表需要等待的时间，进度条完成后会继续执行下一个脚本，并不是程序已经启动完成， 如果想查看程序是否启动成功请再开一个终端查看日志，或者在 nacos 中查看服务是否已经注册。

启动一个程序

安装包 bin 目录内，内置了多个脚本，可以通过 ./startup-*.sh 脚本启动一个程序。

停止程序

  1. 安装包 bin 目录内，内置了多个脚本，可以通过 ./shutdown-*.sh 脚本停止一个程序。
  2. 安装包 bin 目录内，执行 ./shutdown-all.sh 脚本可以停止全部程序。

使用 Nginx 代理后端服务

我们统一的出口都是 nginx，所以要将 API 访问地址也通过 nginx 代理。由于是分布式架构，所以我们只需代理 basic-paper-gateway 即可。

API 接口地址代理

注意

  1. proxy_pass 的端口号一定是 basic-paper-gateway 的端口号，程序默认端口号查看 服务概要信息
  2. /basic-paper-cloud/api/ 开头结尾必须有 /
  3. proxy_pass http://localhost:8000/ 结尾必须有 /

所有对外的接口多需要经过 gateway 转发，所以需要配置代理，配置如下：

如果使用默认值则可以直接抄

# 服务地址代理，注意：这里比较特殊，结尾必须有 /
location /basic-paper-cloud/api/ {
    # 这里的端口号一定是 basic-paper-gateway 的端口号，注意：这里比较特殊，结尾必须有 /
    proxy_pass http://localhost:8000/;
    include proxy.conf; # 引入扩展配置文件
}

文件映射地址代理

注意

  1. proxy_pass 的端口号一定是 basic-paper-gateway 的端口号
  2. /files 结尾不要有 /
  3. proxy_pass http://localhost:8000/basic-paper-file/files 结尾不要有 /

所有对外的接口多需要经过 gateway 转发，所以需要配置代理，就算文件访问也不例外。配置如下：

如果使用默认值则可以直接抄

# 文件映射地址
location /files {
    # 这里的端口号一定是 basic-paper-gateway 的端口号
    proxy_pass http://localhost:8000/basic-paper-file/files;
    include proxy.conf; # 引入扩展配置文件
    # 注意这里不用配置缓存时间，因为 server 有自己的规则进行缓存
}

FAQ

SSO 读取默认字体包报错

当出现错误：Caused by: java.lang.RuntimeException:读取默认字体包报错 时可能是因为没有安装 fontconfig 导致的。

yum
yum install -y fontconfig

独立 jar 部署（了解）

当每个应用独立为一个 jar 时才使用此方案部署，不推荐使用，了解即可。

配置文件修改

使用压缩软件打开 jar 包，将 bootstrap.yml 配置文件拷贝出来进行修改其中的配置。详见：应用中的配置文件

检查 Nginx 配置

确保 Nginx 已经配置 /basic-paper-cloud/api/ 和 /files 的映射。详见：Nginx 配置

上传文件

将需要启动的 jar 包复制到 /usr/local/simperfect 目录下，然后使用如下命令进行启动。

启动应用

已配置环境变量

使用如下命令进行启动

nohup java -Xms1024m -Xmx1024m -Xmn384m -jar /usr/local/simperfect/basic-paper-sso-1.0.0.jar > /dev/null 2>&1 &

其中IVR、Phone模块与CTIServer通讯，需要使用具体的实例名称，占用特定的UDP端口，在启动时需要加入--ivr.ins=xxx的参数，例如启动ivr1实例：

nohup java -Xms1024m -Xmx1024m -Xmn384m -jar /usr/local/simperfect/crystal-call-ivr-1.0.0.jar --ivr.ins=ivr1 > /dev/null 2>&1 &

如果未添加实例参数或者未匹配到对应的实例，系统将以默认参数启动相关模块。

未配置环境变量

使用如下命令进行启动，其中 /usr/local/java/jdk-21.0.3/bin/java 需要替换成你自己的 java 路径

nohup /usr/local/java/jdk-21.0.3/bin/java -Xms1024m -Xmx1024m -Xmn384m -jar /usr/local/simperfect/basic-paper-sso-1.0.0.jar > /dev/null 2>&1 &

命令参数介绍

-Xms1024m -Xmx1024m -Xmn384m

-Xms 堆内存的初始大小，默认为物理内存的1/64

-Xmx 堆内存的最大大小，默认为物理内存的1/4

-Xmn 堆内新生代的大小，通过这个值也可以得到老生代的大小：-Xmx减去-Xmn

-Xms 与 -Xmx 设置为相同大小，-Xmn 设置为 -Xmx的0.375倍

2>&1 &

  1. 2>&1 就是将标准错误输出重定向到标准输出。符号 >& 是一个整体，不可分开，分开后就不是上述含义了。
  2. 最后一个&，表示在后台运行。

0：标准输入（一般是键盘）
1：标准输出（一般是显示屏，是用户终端控制台）
2：标准错误（错误信息输出）

> /dev/null

我们多数使用不输出日志，因为程序内部有日志系统，这段代码的意思就是不输出日志。

Linux下还有一个特殊的文件/dev/null，它就像一个无底洞，所有重定向到它的信息都会消失得无影无踪。这一点非常有用，当我们不需要回显程序的所有信息时，就可以将输出重定向到/dev/null。

多实例配置信息

IVR多实例配置信息

在 ivr-common.yaml 中，支持多个IVR实例的配置

simperfect:
  ivr:
    instances:
      #IVR实例名称，模块启动时附带--ivr.ins=ivr1参数
      - ins: ivr1
        #本机IP
        local-ip: 127.0.0.1
        #本机端口
        local-port: 13001
        #呼叫对象容量
        capacity: 30
      #IVR实例名称，模块启动时附带--ivr.ins=ivr2参数
      - ins: ivr2
        #本机IP
        local-ip: 127.0.0.1
        #本机端口
        local-port: 13002
        #呼叫对象容量
        capacity: 30
      #IVR实例名称，模块启动时附带--ivr.ins=ivr3参数
      - ins: ivr3
        #本机IP
        local-ip: 127.0.0.1
        #本机端口
        local-port: 13003
        #呼叫对象容量
        capacity: 30

如果未添加实例参数或者未匹配到对应的实例，系统将以如下默认参数启动相关模块

simperfect:
  ivr:
    instances:
      - ins: ivr
        #本机IP
        local-ip: 127.0.0.1
        #本机端口
        local-port: 13001
        #呼叫对象容量
        capacity: 30

修改 crystal-call-ivr.conf 配置，添加实例参数。直接写 --ivr.ins=ivr1 即可，不用添加任何转义字符和引号。

# 启动端口号
server.port=8023
# JAVA_OPTS 参数，一般用于设置内存大小
java.opts=-Xms1024m -Xmx1024m -Xmn384m
# 实例参数，模块启动时附带--ivr.ins=ivr1参数
app.opts=--ivr.ins=ivr1

Phone实例配置信息

在crystal-call-phone.yaml中，支持配置多个Phone实例

simperfect:
  phone:
    instances:
      #实例名称,模块启动时附带--phone.ins=ccPhone1参数
      - ins: ccPhone1
        #本地IP
        local-ip: 127.0.0.1
        #本地端口，坐席实例登录的端口
        local-port: 13011
        #监控模块占用端口
        monitor-port: 13012
      #实例名称,模块启动时附带--phone.ins=ccPhone2参数
      - ins: ccPhone2
        #本地IP
        local-ip: 127.0.0.1
        #本地端口，坐席实例登录的端口
        local-port: 13013
        #监控模块占用端口
        monitor-port: 13014
      #实例名称,模块启动时附带--phone.ins=ccPhone3参数
      - ins: ccPhone3
        #本地IP
        local-ip: 127.0.0.1
        #本地端口，坐席实例登录的端口
        local-port: 13015
        #监控模块占用端口
        monitor-port: 13016

如果未添加实例参数或者未匹配到对应的实例，系统将以如下默认参数启动相关模块

simperfect:
  phone:
    instances:
      #实例名称,模块启动时附带--phone.ins=ccPhone1参数
      - ins: ccPhone
        #本地IP
        local-ip: 127.0.0.1
        #本地端口，坐席实例登录的端口
        local-port: 13011
        #监控模块占用端口
        monitor-port: 13012