1.0 部署前的说明

「掌上无忧」客服系统是采用 Go 语言编写的，目前采用的版本是：go1.24.2。Go 语言的系统最大的好处是不用考虑编程语言环境，因为程序本身自带了 Go 编译器，只要运行一个文件就能全搞定，本篇教程用宝塔来部署运行本客服系统。

2.0 快速部署指引

本教程假想对象是新手，但是为了让老手可以很快部署完成，笔者在这里插入快速安装指引，以 Debian-12 和 宝塔 10-Stable（稳定版） 版本为例。

2.1 基础环境

- Nginx 1.26.3+
- MySQL 5.7
- Redis 7.4.6

2.2 下载脚本

直接在终端粘贴以下命令行后按回车下载 Go 二进制文件和配置文件
完成后，相当于下载解压放在：/www/wwwroot/chat（可以自行修改目录 chat 的名字）

bash <(curl -fsSL https://www.5umb.com/api/v1/script/QtCodeCreators/customer-service/v2.4.0/install.sh 2>/dev/null || wget -qO- https://www.5umb.com/api/v1/script/QtCodeCreators/customer-service/v2.4.0/install.sh 2>/dev/null || { echo "[错误] curl和wget都不可用，请手动下载安装脚本"; exit 1; })

2.3 手动配置

配置环节（重要！需要按照顺序阅读）

  • 手动创建 MySQL 用户名、数据库和密码等，创建好就行不用导入 sql 脚本。
  • 本客服系统没有 Web 安装向导的，需要先配置好数据库连接信息，启动时候自动初始化的。
  • 修改：/www/wwwroot/chat/configs/config.yaml 里面的 mysql 和 redis 连接信息。
  • 宝塔-网站-创建 Go 项目，选上比如 /www/wwwroot/chat/customer-service 作为运行程序。
  • 启动项目之后，会自动初始化默认的信息，就算启动失败也无所谓，不会重复创建的。

2.4 后台信息

脚本运行完毕后显示如下

超级管理员账号（用于系统管理和配置）：
访问地址：/super-admin
用户名：admin
密码：123456

客服账号（用于日常客服工作）：
访问地址：/admin
用户名：service
密码：123456

商户后台账号（用于商户测试）：
访问地址：/merchant
用户名：test
密码：123456

⚠️ 安全提醒：首次登录后请立即修改默认密码，确保系统安全！

以上是快速部署指引，下面开始新手逐步说明的部署过程教程。
出于连贯性的需求，部分内容可能会重复。

3.0 完整部署指引

预置信息及规划如下

  • 假如是使用一个二级域名来部署客服系统：kf.domain.com。
  • 解析域名的 A 记录到服务器 IP 地址了。
  • 操作系统选用 Debian-12 宝塔官方推荐的版本。
  • 购买并且加载了数据盘（这个可选）。
  • 宝塔选用版本：10-Stable 稳定版或者最新 11 版。
  • 提前注册好宝塔论坛 www.bt.cn 账号并绑定到新安装的宝塔面板。
  • 安装好面板之后，为了方便用 phpMyAdmin 管理 MySQL，建议安装：Nginx 默认推荐版本、MySQL 5.7、PHP 默认推荐版本 和 phpMyAdmin 默认推荐版本。
  • 安装完推荐的环境，再去应用商店安装 Redis 7 的最新版本。
  • 下载「掌上无忧」客服系统安装脚本。
  • 创建网站「Go 项目」并配置。
  • 完成授权和登录后台。

3.1 域名解析

域名需要登录注册域名所在站点，登录并添加顶级或者二级域名解析到要安装本客服系统的服务器 IP。涉及到阿里云、腾讯云或者其他云平台的差异，这里不做详细的解析展开，配合搜索引擎完成：比如 阿里云如何解析二级域名到服务器 IP之类的。

3.2 购买云服务器

推荐配置：

- 操作系统：Debian 12
- 内存：至少 2GB RAM（推荐 4GB 以上）
- 存储空间：至少 20GB 可用空间
- 网络：公网 IP 地址

购买过程就不详细展开，和域名一样要发挥下搜索引擎的作用。或者后面专门写宝塔的专栏的时候再举例展开。

3.3 安装宝塔面板

3.3.1 加载数据盘

如果有购买了数据盘，则先把数据盘加载到 /www，宝塔官方提供了一个格式化数据盘并加载到 /www 目录的脚本，但是需要注意，如果机器没有新买数据盘的话，不需要运行以下脚本，因为如果检测到有数据在 /www 会自动跳过。以下脚本只适合新机器，旧机器不需要安装宝塔的，或者宝塔安装到系统盘的都无需运行。

挂载数据盘到 /www 的脚本

wget -O auto_disk.sh http://download.bt.cn/tools/auto_disk.sh && sudo bash auto_disk.sh

3.3.2 开始安装宝塔

选以下其中一个脚本来安装宝塔都可以。

宝塔-10-Stable

宝塔-10-Stable 稳定版安装脚本：

url=https://download.bt.cn/install/installStable.sh;if [ -f /usr/bin/curl ];then curl -sSO $url;else wget -O installStable.sh $url;fi;bash installStable.sh ed250616lt

宝塔-11-Latest 最新版安装脚本：

if [ -f /usr/bin/curl ];then curl -sSO https://download.bt.cn/install/install_panel.sh;else wget -O install_panel.sh https://download.bt.cn/install/install_panel.sh;fi;bash install_panel.sh ed8484bec

以上不管是加载数据盘到 /www 还是安装宝塔面板的操作，都是粘贴以上命令行到宝塔面板左侧的「终端」，在第一个提示按下：y，然后按回车开始安装。

输入 y 后按回车，整个安装过程就开始了大概需时 2-5 分钟，耐心等待一下 。

看到类似以下的信息说明宝塔面板已经安装完成。

3.3.3 登录宝塔面板

先打开网页浏览器，把网址拷贝到地址栏后按回车打开。
现在宝塔默认都是打开 https，由于是自己生成的证书，所以会有风险提示。
点击继续，然后就会看到登录入口，接着请输入终端记录的账号和密码。

3.3.4 绑定宝塔论坛账号

打勾同意使用条款：

然后绑定宝塔论坛的账号到本面板：

有些人出租宝塔面板就是把他的账号绑定到你的宝塔面板，该绑定的账号不会有任何操作权限的，只是把账号的权益同步到该面板而已。

等待一下：

3.3.5 安装对应版本环境软件

初始化一下基础的环境软件，一般这个推荐的，按照我图的去掉打勾或者选择对应的版本，也可以根据你的实际选择。

以上是安装基础环境，点击一键安装之后，就开始跑配置了。

Linux 所有的安装几乎都是配置式，宝塔面板是一款集成了很多配置流程自动化的服务器面板，所以它也是一款很好的 Linux 运行环境的管理器。

速度还能接受，客服系统后面还要安装一个 Redis，去到：软件商店-全部-找到 Redis。选择 7 系列的最新版，然后点击安装，等待完成。

安装完成之后，点击旁边的设置，设置一下 Redis 的密码：

养成好习惯，不要使用空密码。
设置完成之后，拷贝一下这个密码放到文本里面，修改配置的时候要用到这个密码的。
接着，记得要重启一下 Redis 让密码生效：

3.4 开始安装

折腾完基础环境，总算开始进入正题了，在开始安装前，我们普及一下宝塔面板如何进入 ssh 终端，这个终端就是命令行模式，类似 windows 的 dos 命令行，但是 linux 的命令行远远比 dos 强大，几乎全世界的 linux 服务器仅用 ssh 终端就可以完成提供所有服务。

宝塔面板的出现远远降低了 ssh 的依赖，大部分操作都可以在 web 界面完成，大大降低了 linux 的使用门槛。但是有些时候，我们也要结合 ssh 终端来完成一些部署工作。不用听到命令行就头疼，我们尽量用复制粘贴完成。

进入 ssh 终端的路径如下：

有个小光标在闪就说明是成功登录了 ssh 终端，而且宝塔一般都是默认用 root 最高权限登录，这样操作什么的会方便点。

3.4.1 进入终端安装基本工具

系统需要安装 curl 或 wget 工具。如果都没有，请在终端运行以下命令行先安装：

apt-get update && apt-get install curl wget -y

这是第一段命令行，我们可以试试，先拷贝着，然后去到 ssh 终端入口的光标那里，然后点击鼠标右键，就会弹出一个菜单，点击粘贴，接着按回车。

apt-get update && apt-get install curl wget -y
Hit:1 http://repo.huaweicloud.com/debian bookworm InRelease
Hit:2 http://repo.huaweicloud.com/debian bookworm-updates InRelease
Hit:3 http://repo.huaweicloud.com/debian bookworm-backports InRelease
Reading package lists... Done
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
curl is already the newest version (7.88.1-10+deb12u14).
wget is already the newest version (1.21.3-1+deb12u1).
0 upgraded, 0 newly installed, 0 to remove and 67 not upgraded.

这个提示说明这台服务器已经安装了：curl 和 wget 的最新推荐的版本，无需重复安装。这两个是请求网址和下载的小工具，不少发行版的 linux 已经内置了，除非那种最小化安装的版本。好了，接着开始运行脚本。

3.4.2 进入终端运行脚本

同样进入 ssh 终端，把以下的脚本拷贝上，同样去到 ssh 终端的光标那里，点击鼠标右键后选择粘贴，换行无所谓，按回车。

bash <(curl -fsSL https://www.5umb.com/api/v1/script/QtCodeCreators/customer-service/v2.4.0/install.sh 2>/dev/null || wget -qO- https://www.5umb.com/api/v1/script/QtCodeCreators/customer-service/v2.4.0/install.sh 2>/dev/null || { echo "[错误] curl和wget都不可用，请手动下载安装脚本"; exit 1; })

我们把信息拷贝出来：

==========================================
  customer-service Linux 自动安装脚本
  Version: v2.4.0
==========================================

[信息] 正在检测系统架构...
[信息] 检测到的架构: amd64

[信息] 创建项目目录...
[信息] 下载地址: http://www.5umb.com/api/v1/download/QtCodeCreators/customer-service/v2.4.0/linux-amd64.zip
[信息] 开始下载...

--2025-10-23 19:26:45--  http://www.5umb.com/api/v1/download/QtCodeCreators/customer-service/v2.4.0/linux-amd64.zip
Resolving www.5umb.com (www.5umb.com)... 222.186.56.159
Connecting to www.5umb.com (www.5umb.com)|222.186.56.159|:80... connected.
HTTP request sent, awaiting response... 200 OK
Length: 10472832 (10.0M) [application/octet-stream]
Saving to: ‘linux-amd64.zip’

linux-amd64.zip                          100%[=========================================>]   9.99M  11.4MB/s    in 0.9s  

2025-10-23 19:26:46 (11.4 MB/s) - ‘linux-amd64.zip’ saved [10472832/10472832]

[成功] 下载完成: linux-amd64.zip
[信息] 正在解压文件...
[信息] 使用 unzip 解压...
Archive:  linux-amd64.zip
warning:  linux-amd64.zip appears to use backslashes as path separators
  inflating: configs/config.yaml   
  inflating: customer-service    
[成功] 解压完成!
[信息] 正在设置文件权限...
[成功] 已设置程序文件权限: customer-service (777)
[成功] 已设置配置文件权限: configs/config.yaml (644)
[信息] 正在清理临时文件...

==========================================
  customer-service v2.4.0 安装完成!
==========================================

[下一步] 请按照以下步骤完成部署:
1. 在宝塔面板中添加Go项目
   - 项目可执行程序: customer-service
   - 端口: 8180
   - 勾选[开机启动]

2. 配置数据库:
   - 在宝塔面板创建数据库: chat
   - 编辑 config.yaml 配置数据库连接

3. 启动服务
   - 在宝塔面板[Go项目]中启动项目

[系统访问]
- 客户端访问: http://你的服务器IP:8180
- 客服后台: http://你的服务器IP:8180/admin
- 超级管理员后台: http://你的服务器IP:8180/super-admin
- 商户管理后台: http://你的服务器IP:8180/merchant

[默认账号密码]

超级管理员账号（用于系统管理和配置）：
访问地址：/super-admin
用户名：admin
密码：123456

客服账号（用于日常客服工作）：
访问地址：/admin
用户名：service
密码：123456

商户后台账号（于商户测试）：
访问地址：/merchant
用户名：test
密码：123456

⚠️ 安全提醒：首次登录后请立即修改默认密码，确保系统安全！

这个脚本主要功能就是，下载：http://www.5umb.com/api/v1/download/QtCodeCreators/customer-service/v2.4.0/linux-amd64.zip 这个压缩包，然后解压到：/www/wwwroot/chat，我们可以在文件管理找到。

换一句话，你也可以直接下载那个压缩包，然后在宝塔面板解压剪切移动到你想要的位置。这个不在这里展开，我们沿着这个方式继续操作下去。

3.4.3 修改文件夹名字

宝塔面板创建站点，默认是推荐以域名为文件夹，我们这个客服系统也改成这种方式，方便多站点以后找到它容易些。因为假设域名是：kf.domain.com，那么我们去到文件管理。

如此一来，chat 文件夹就改成了：kf.domain.com
/www/wwwroot/chat -> /www/wwwroot/kf.domain.com
这里的操作不会对安装部署造成任何影响的，改错了再改一次就好。

改好之后，我们就沿用了宝塔面板的习惯了，站点的文件夹是以域名为命名。

好了，我们先不动这里，去手动创建数据库先。

3.4.5 手动创建数据库

「掌上无忧」客服系统没有 Web 网页的安装向导，它需要先配置好 MySQL 连接信息，然后启动的时候会初始化建表脚本的。进入新建数据库按钮：

我们按照以下信息创建数据库，你可以自己决定自己的名字，这里不限制：

- 用户名：kf_domain_com
- 数据库：kf_domain_com
- 密码：kyZ8C****LaEwN（做了脱敏处理，实际不是***）

你以你的为准，宝塔会自动生成 MySQL 密码的，我们拷贝下来放到文本中，和 Redis 的密码一样等着备用。添加完成数据库之后，列表这里会新增一条的，如果密码没有记录着也是可以回来这里找到：

这就完成了数据库的手动创建工作了。

3.4.6 修改项目的配置文件

回到文件管理，进入 /www/wwwroot/kf.domain.com/configs 这个路径，你的目录名字不一定是我的这个，以你的为准。

修改的提示看下图，这个步骤如果很少修改配置文件的同学来说比较恐惧，那就慢慢移动鼠标，把字符拷贝到双引号之间，不要把双引号删除了就行，拷贝之后，对着这张图对比下，一般都没有问题的。

修改完成之后，可以用键盘 Ctrl+S 快速保存，或者点击这里保存：

至此，整个部署最难的部分已经完成了。接着就可以创建 Go 项目并启动它了。

3.4.7 创建网站-添加 Go 项目

本项目是采用 Go 语言编写的，故我们创建 Go 项目来管理运行它。

这里我录制一个动图来选取：

完整的填写建议，我附字在图中：

对照检查下，我们点击「确定」。

忘了填写端口了，我们补充上去：8180，这个要和配置文件的端口一致，默认是这个 8180。

我们检查一下运行情况，以后排查错误也可以用这个：

提示这个一般已经初始化完成。
不过不够详细，我们找找程序的 debug 日志：

这里的日志就很详细了，以后也可以通过这个来排查错误。

3.4.8 申请 SSL 证书

按照截图步骤操作，我这个域名非真实解析域名，所以不能操作到最后一步申请成功。

这个如果你解析域名没什么问题的话，一般很快就能申请成功。

3.5 登录后台

找回 ssh 输出的默认登录信息并套上我的假设域名如下：

[默认账号密码]

超级管理员账号（用于系统管理和配置）：
访问地址：https://kf.domain.com/super-admin
用户名：admin
密码：123456

客服账号（用于日常客服工作）：
访问地址：https://kf.domain.com/admin
用户名：service
密码：123456

商户后台账号（于商户测试）：
访问地址：https://kf.domain.com/merchant
用户名：test
密码：123456

然后你就可以打开你的网址：https://kf.domain.com/super-admin，并输入：admin 和 123456 默认的信息登录。因为在授权网站 www.5umb.com 已经激活绑定的域名了，所以这里是已经自动激活的了。

有什么疑问，我们群里再做交流。