使用文档 - 月牙AI客服

环境要求

Node.js

18.0 及以上

MySQL

5.7 及以上

阿里云账号

百炼 + 机器翻译

安装步骤

1

第一步：安装依赖

双击运行安装全部依赖.bat，等待所有依赖安装完成。

安装全部依赖.bat

2

第二步：启动项目

双击运行启动项目.bat，启动开发服务器。

启动项目.bat
# http://127.0.0.1:3000

3

第三步：完成安装向导

浏览器访问 http://127.0.0.1:3000，系统会自动引导你完成数据库配置和管理员账号创建。

安装向导会自动执行 SQL 建表、创建管理员、写入配置文件，全程可视化，无需手动操作数据库。

数据库结构

系统共7张数据表，安装向导会自动创建，以下是各表的用途说明：

Table	Description
`users`	管理员和客服账号，支持 admin / agent 两种角色
`clients`	站点配置，每个接入网站对应一条记录，存储阿里云 Agent ID 等信息
`chat_sessions`	访客会话，记录访客IP、设备、来源页面、当前服务模式等
`chat_messages`	聊天消息，记录所有消息内容及发送者类型（访客/客服/AI）
`knowledge_base`	知识库问答对，支持分类、关键词和优先级
`knowledge_files`	上传到阿里云知识库的文件记录及同步状态
`system_config`	系统全局配置，包括阿里云 API 密钥、翻译密钥等

阿里云配置

系统需要两个阿里云服务：百炼大模型平台（AI回复）和机器翻译（消息翻译）。登录管理后台进入「系统设置」，填写以下配置项：

ali_api_key 百炼 API Key

在阿里云百炼控制台创建，用于调用知识问答 Agent。

ali_workspace_id 业务空间 ID

百炼控制台右上角可查看，格式类似 ws-xxxxxxxx。

ali_translate_key_id 翻译 AccessKey ID

在阿里云 RAM 控制台创建，开通机器翻译服务后获取。

ali_translate_key 翻译 AccessKey Secret

与 AccessKey ID 配套，创建时保存，之后无法再次查看。

关于 Agent ID：每个接入站点需要在阿里云百炼中单独创建知识库和 Agent，创建完成后在管理后台的「站点管理」里填写对应的 Agent ID 和知识库 ID。

网站接入

安装完成后，把聊天窗口嵌入到你的网站，访客无需跳转即可发起对话。

第一步：创建站点

登录管理后台，进入「站点管理」，创建一个新站点并填写网站域名。系统会生成唯一的客户识别码（client code）。

第二步：嵌入代码

将以下代码片段粘贴到网站 HTML 的标签之前，替换 YOUR_LOCALE 为语言代码（如 zh-CN），YOUR_CLIENT_CODE 为站点识别码：

<script>
  (function() {
    var btn = document.createElement('a');
    btn.href = 'https://your-domain.com/YOUR_LOCALE/chat?client=YOUR_CLIENT_CODE';
    btn.target = '_blank';
    btn.rel = 'noopener noreferrer';
    btn.title = '联系客服';
    btn.style.cssText = 'position:fixed;bottom:24px;right:24px;width:56px;height:56px;border-radius:50%;background:#2563eb;display:flex;align-items:center;justify-content:center;box-shadow:0 4px 16px rgba(37,99,235,.45);z-index:9999;transition:transform .15s';
    btn.innerHTML = '<svg width="28" height="28" viewBox="0 0 24 24" fill="none" stroke="#fff" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z"/></svg>';
    btn.onmouseover = function(){ btn.style.transform = 'scale(1.1)'; };
    btn.onmouseout  = function(){ btn.style.transform = 'scale(1)'; };
    document.body.appendChild(btn);
  })();
</script>

第三步：配置知识库

在阿里云百炼创建知识库，上传业务文档，创建问答 Agent。然后回到管理后台「站点管理」填写 Agent ID，AI 即可自动回复访客问题。