系统操作手册

覆盖总后台、商户后台、客服工作台、访客会话窗口。HTTP 默认 :8000，实时通道 WebSocket 默认 :5017/ws。

1. 角色与入口

新建商户、客服的初始密码见总后台「系统设置 → 默认密码」，出厂为 123456，上线后请改掉。
建议顺序：总后台建商户与套餐 → 商户后台建客服与知识库 → 配置窗口并复制接入代码 → 客服上线 → 访客进线。

2. 总后台

概览 / 商户

• 首页：商户数、客服数、会话概况。
• 商户列表：新增或编辑账号、名称、状态、到期、套餐。可重置密码（变为系统默认密码）。
• 客服列表：全站客服，可按商户筛选。
• 套餐设置：客服数、分组数、价格，以及 AI 智能回复、语音通话、同事会话勾选。未勾选的功能商户无法自行打开。商户到期后无法接待。

会话

• 访客记录：按关键词、商户账号、日期筛选，可看聊天记录。
• 接待记录：谁接待了谁、起止时间。

系统

• 系统设置：网站名称/标题/描述/版权、默认密码、新建商户有效天数、首页开关、商户自助注册（手机或邮箱）、短信/邮件验证码、图形验证码类型、上传大小与后缀、涉诈关键词与正则（标记或拦截）。关闭首页后访问 / 显示暂未开放，三个后台不受影响。
• 后台账号：平台管理员。
• 登录日志：各角色登录成败。
• 审计日志：系统开关、会话窗口开关、踢下线、转接。按动作、时间、关键词筛选，点「查看」对上操作人、IP 与详情。
• 验证码记录：短信/邮件发送记录。

3. 商户后台

只管理本商户。页头显示套餐与到期时间。

客服与访客

• 客服列表：账号、姓名、同时接待人数、启用。同一客服电脑与手机可同时在线；同端重复登录会踢旧连接（审计记「踢下线」）。
• 客服分组：可设默认接待组。接入参数可指定分组或客服编码。
• 访客记录 / 访客资料：资料含姓名、电话、备注、标签，可按条件导出 Excel（最多 5000 条）。
• 留言、评价、黑名单：无客服时可留言；拉黑 IP 后无法进线。

知识库

• 常见问题：标题 + 答案，可排序、显示/隐藏。
• 机器人知识库：匹配词 + 回复。
• 快捷回复、商品库：工作台话术；商品可 Excel 导入后发给访客。

检索按商户隔离。保存后更新索引。AI 只在系统提示里带引用（如 faq:12），不出现在访客气泡。

聊天配置

• 会话分配：标题、主题色、欢迎语；无客服时机器人；手动转人工或自动接入；随机/空闲分配；回头客；超时关闭秒数。
• 聊天窗口：页脚、提示音；图片 / 视频 / 文件 / 语音通话 只控制访客端（工作台不受限）；商户域名（需解析到本机，Nginx 将站点转到 :8000、/ws 转到 :5017）；允许接入域名（测试请留空）。
• AI 回复：智能回复（访客侧，知识库未命中时）；工作台 AI 推荐（需 Key + 开关）；模型、地址、提示词。
• 消息翻译：工作台翻译访客消息，密钥在 uchat.baidu。
• 弹出按钮：文字、左右位置、胶囊/圆形、新窗口或页内浮层。

接入说明

1. 复制「推荐代码」整段（含 <script>），贴到网站 HTML 底部、</body> 前。
2. 用 http/https 打开，不要双击本地文件。
3. 对话链接 /chat/?m=商户编码 可放公众号、APP WebView、小程序 web-view。
4. 示例页：/chat/demo.html?m=商户编码。

4. 客服工作台

用客服账号登录 /work/。电脑与手机可同时在线，同一端会踢旧连接。

左侧

• 接待中：全部 / 在线 / 未读 / 未回。
• 同事会话：同商户内部沟通，访客不可见。
• 排队中：点选即接待。
• 历史会话：只读。

接待

• 回车发送；表情、图片、视频、文件、商品卡片。
• 消息可引用、翻译、撤回；发出的消息有已读勾。
• 转接：选在线同事。审计日志记操作人。
• 结束会话：会先挂断语音。
• 语音通话：仅人工接待中。接听、静音、挂断后聊天显示时长。需 HTTPS 或 localhost。
• AI 推荐：商户开启后生成可点选话术。

右上角可开关提示音、桌面通知（显示访客姓名）、主题、夜间模式、语言。右侧面板编辑访客资料或拉黑 IP。

5. 访客会话窗口

1. 打开方式：网站按钮、对话链接、二维码、公众号/APP/小程序 web-view。
2. 可能先看到欢迎语和 FAQ。点问题即出答案。
3. 手动转人工，或配置为自动接入时直接分给空闲客服。
4. 无客服且开了机器人：知识库 / AI 作答，仍可留言。
5. 转人工后不再推 FAQ，出现「某某加入会话」。
6. 图片、视频、文件、语音按钮是否显示，由商户「聊天窗口」开关决定。语音必须先转人工。
7. 挂断通话后出现「通话时长 mm:ss」。

黑名单 IP 无法进入。填了允许接入域名后，其它网站不会出现咨询按钮。

6. 推荐接入场景

7. 部署要点

• HTTP :8000，WebSocket :5017 路径 /ws。
• 绑定商户域名：该域名转到 :8000，/ws 转到 :5017。
• 多实例需 Redis，否则跨进程推送、在线状态、踢人不完整。
• 最低约 2 核 4G、MySQL 5.7/8.0。

二进制、Nginx、Docker Compose 的完整步骤见 系统部署手册（仓库 docs/部署手册.md）。

8. 排障