← 返回授权中心

客服云 · 完整搭建教程

从一台空服务器,到客服能登录 App 接单。共 8 步,全程约 20 分钟。首次部署建议照着「图文版」做,熟练后看「文字版」复制命令即可。

Go 单文件 · 无运行时依赖 Linux amd64 / arm64 SQLite 单库备份 授权校验 6 小时一次
本教程包含
  1. 准备服务器、域名与授权码
  2. 新建站点并开启 HTTPS
  3. 上传程序与目录结构
  4. 配置授权环境变量
  5. 注册为开机自启服务
  6. 配置反向代理
  7. 登录后台并创建客服账号
  8. 客服 App 填自己的域名登录
1

准备三样东西

  • 一台 Linux 云服务器:1 核 2G 起步,系统推荐 Ubuntu 22.04 / Debian 12 / CentOS 7+,装好宝塔面板。
  • 一个域名:例如 chat.kehu.com,解析 A 记录指向服务器公网 IP。
  • 一个授权码:由服务商在授权中心签发,格式形如 LC-7K2M-9QXA-…,并已把你的域名加进白名单。
① 云服务器 Ubuntu 22.04 · 1核2G 已安装宝塔面板 8.x 放行 80 / 443 端口 ② 域名解析 chat.kehu.com A → 你的公网 IP 解析生效通常 1–10 分钟 ③ 授权码 LC-7K2M-9QXA-P4RT-8WND 域名已加入白名单 一码一域名,不能混用
图 1:服务器、域名、授权码三者缺一不可。
2

在宝塔新建站点并开启 HTTPS

  1. 宝塔面板 → 网站 → 添加站点。
  2. 域名填 chat.kehu.com;PHP 版本选 纯静态;根目录保持默认。
  3. 建好后进站点设置 → SSL → 申请 Let's Encrypt 免费证书 → 开启「强制 HTTPS」。
宝塔面板 · 网站 · 添加站点 域名 chat.kehu.com 根目录 /www/wwwroot/chat.kehu.com PHP 版本 纯静态 ▾ 提 交 提示:这里只建站点、放 SSL;程序本身由 systemd 跑在 127.0.0.1:8095 上。
图 2:站点只承担「反向代理 + 证书」两个职责,不跑 PHP。
3

上传程序

把服务商给你的 livechat(Linux 二进制)上传到 /www/wwwroot/chat.kehu.com/,然后给它执行权限。

cd /www/wwwroot/chat.kehu.com
chmod +x livechat
mkdir -p data/uploads
./livechat --version
# 期望输出:livechat 1.26.0 (linux/amd64)
/www/wwwroot/chat.kehu.com ├── livechat ← 主程序,14MB 单文件 ├── data/ │ ├── app.db ← 全部业务数据 │ ├── .secret.key ← 消息加密密钥,必须一起备份 │ └── uploads/ ← 图片与文件 └── backup/ ← 升级前存放旧版本
图 3:整站只有一个二进制 + 一个 data 目录,迁移就是拷这两个。
4

配置授权(四行,缺一不可)

授权相关配置通过环境变量注入。下面四行在第 5 步的服务文件里填写:

LICENSE_SERVER=https://a.yxsd.top   # 授权中心地址,固定不变
LICENSE_KEY=LC-XXXX-XXXX-XXXX-XXXX # 你的授权码
LICENSE_DOMAIN=chat.kehu.com       # 必须是白名单里的域名
LICENSE_ENFORCE=1                  # 1=强制校验,校验不过不启动
⚠
LICENSE_DOMAIN 必须和浏览器地址栏里的域名完全一致。 用 chat.kehu.com 授权却通过 IP 或别的域名访问,会被判定为域名不匹配而拒绝启动。
客服系统启动 读取四个环境变量 请求授权中心校验 GET /api/license/verify 授权中心 ① 码是否存在 ② 域名是否匹配 ③ 是否到期 / 被停用 ④ Ed25519 签名后返回 验签通过 内置公钥验证签名 缓存授权(离线宽限) 正常对外提供服务
图 4:校验不通过时进程直接退出,日志会写明具体原因(域名不对 / 已到期 / 已停用)。
5

注册为开机自启服务

新建 /etc/systemd/system/livechat.service,内容如下(把域名、授权码换成自己的):

[Unit]
Description=LiveChat Server
After=network.target

[Service]
Type=simple
WorkingDirectory=/www/wwwroot/chat.kehu.com
Environment=ADDR=:8095
Environment=DB_PATH=data/app.db
Environment=UPLOAD_DIR=data/uploads
Environment=LICENSE_SERVER=https://a.yxsd.top
Environment=LICENSE_KEY=LC-XXXX-XXXX-XXXX-XXXX
Environment=LICENSE_DOMAIN=chat.kehu.com
Environment=LICENSE_ENFORCE=1
ExecStart=/www/wwwroot/chat.kehu.com/livechat
Restart=always
RestartSec=3
LimitNOFILE=65535

[Install]
WantedBy=multi-user.target
systemctl daemon-reload
systemctl enable --now livechat
sleep 2
systemctl is-active livechat      # 期望:active
curl -s http://127.0.0.1:8095/api/health  # 期望:{"ok":true,...}
root@server:~# systemctl is-active livechat active root@server:~# curl -s http://127.0.0.1:8095/api/health {"ok":true,"data":{"version":"1.26.0","license":{"ok":true,"customer":"某某科技"}}} 若为 inactive,看日志:journalctl -u livechat -n 40 --no-pager
图 5:健康检查里能看到授权状态,一眼确认是「校验通过」还是「被拒绝」。
6

配置反向代理,让域名能访问

宝塔 → 网站 → 点站点名 → 反向代理 → 添加:

  • 代理名称:livechat
  • 目标 URL:http://127.0.0.1:8095
  • 发送域名:$host

WebSocket 需要额外的 Upgrade 头,宝塔默认已带;如果客服端连不上实时消息,检查站点配置里是否有下面两行:

proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_read_timeout 3600s;
用户浏览器 https://chat.kehu.com 443 端口 证书由宝塔签发 HTTPS Nginx(宝塔) 反代 + SSL 终止 转发 WebSocket 127.0.0.1:8095 HTTP livechat 进程 只监听本机回环 不直接暴露公网 数据落 data/app.db
图 6:程序只监听 127.0.0.1,公网入口只有 Nginx,证书与端口都好管理。
7

登录后台,改密码、建客服

打开 https://chat.kehu.com/wh606612/(超管路径,不是 /admin/)。

  • 初始账号 admin,初始密码见服务商给你的交付说明;第一次登录后立刻改掉。
  • 进「商户中心」确认套餐,再到「客服与分组」建分组、建客服账号。
  • 客服账号建好后,可直接在 https://chat.kehu.com/agent/ 登录只回复会话。
云 客服云 管理后台登录 admin •••••••• 登 录 超级管理后台 /wh606612/ 你(服务商/店主) 商户后台 /merchant/ 店主:管人、管会话 客服工作台 /agent/ 客服:只回复会话
图 7:三个入口分别给三种角色,客服不需要看到管理菜单。
8

客服 App 填自己的域名登录

把安装包发给客户,客服手机上安装后,在登录页的「服务器地址」里填自己的域名:

https://chat.kehu.com

不需要 /api、不需要末尾斜杠。填完点「连接服务器」,成功后用客服账号登录即可收发消息。

云 客服云 https://chat.kehu.com 连接服务器 填自己的域名,不要带 /api 同一个 APK 所有客户通用 换域名只需改这一栏 App 不需要重新打包
图 8:一套 App 服务所有客户,域名由使用方自己填。
✓
到这一步就完成了。发给客户的交付内容就是三样:安装包、授权码 + 域名、这份教程的链接。 客户按教程 20 分钟能跑起来;后续升级只需要替换 livechat 二进制并重启服务。
↑

日常维护:备份与升级

备份(建议每天定时执行,宝塔「计划任务」里加一条 shell):

cd /www/wwwroot/chat.kehu.com
TS=$(date +%Y%m%d)
tar czf backup/data-$TS.tar.gz data/
ls -lh backup/ | tail -3

升级(拿到新版本二进制后):

cd /www/wwwroot/chat.kehu.com
cp -a livechat backup/livechat.$(date +%Y%m%dT%H%M%S)   # 先留退路
cp -f livechat.new livechat && chmod +x livechat
systemctl restart livechat
sleep 2 && systemctl is-active livechat
⚠
升级前务必确认 data/ 已备份。数据库结构会在启动时自动迁移,迁移不可回退。
客服云 · 授权中心 | 首页 | 授权后台