AI 客服安装与使用教程

Before Start

先看懂：AI 客服不是普通 PHP 页面

这个项目是一个独立的 Node.js 服务。它可以和你的官网、商城、PHP 网站、WordPress 网站放在同一台服务器，也可以单独放一台服务器。

<script>
  window.SITE_AI_WIDGET = {
    apiBase: "https://你的AI客服域名"
  };
</script>
<script src="https://你的AI客服域名/widget.js" defer></script>

Prepare

安装前准备

node -v
npm -v

如果 node -v 显示版本低于 20，建议先升级 Node.js。版本太低可能启动失败。

Windows

Windows 服务器部署

1. 安装 Node.js 20 LTS，安装完成后打开 PowerShell，执行 node -v 确认版本。
2. 把项目放到固定目录，例如 D:\site-ai-assistant，不要放在桌面或临时目录。
3. 在项目目录打开 PowerShell，执行 npm install 安装依赖。
4. 执行 npm start 启动服务，然后浏览器打开 http://服务器IP:3000 测试。
5. 正式使用建议用 NSSM、WinSW 或 PM2 把 Node 服务做成后台常驻服务。
6. 如果有 IIS、Nginx for Windows 或其他反向代理，把 kf.example.com 代理到 http://127.0.0.1:3000。

cd D:\site-ai-assistant
npm install
npm start

Linux

Linux 无面板部署

1. 登录服务器，安装 Node.js 20 或更高版本。
2. 把项目上传到 /www/wwwroot/aikefu 或 /opt/aikefu。
3. 进入项目目录执行 npm install。
4. 先用 npm start 测试，确认 http://服务器IP:3000/api/health 返回正常。
5. 安装 PM2，让服务后台常驻，并设置开机自启。
6. 用 Nginx 把域名反向代理到 127.0.0.1:3000，并配置 HTTPS。

cd /www/wwwroot/aikefu
npm install
npm install -g pm2
pm2 start src/server.js --name aikefu
pm2 save
pm2 startup

server {
  listen 80;
  server_name kf.example.com;

  location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
  }
}

Baota

宝塔面板部署

1. 在宝塔「软件商店」安装 Node.js 版本管理器、Nginx，并安装 Node.js 20 或更高版本。
2. 在「网站」里添加站点，域名填写你的客服域名，例如 kf.example.com。这个站点只是给客服服务绑定域名，不是 PHP 项目。
3. 上传项目到站点目录，例如 /www/wwwroot/aikefu。
4. 进入「Node 项目」或「Node.js 项目」，添加项目。
5. 项目目录填写 /www/wwwroot/aikefu，启动文件选择 src/server.js，启动命令可用 npm start 或 node src/server.js。
6. Node 版本选择 20+，包管理器选择 npm，先安装依赖，再启动项目。
7. 项目端口填写 3000。如果 3000 被占用，可以在环境变量里设置 PORT=3001，再把反向代理目标改成对应端口。
8. 站点设置里添加反向代理，目标 URL 填 http://127.0.0.1:3000，发送域名填 127.0.0.1 或服务器内网地址。
9. 申请 SSL 证书，让 https://kf.example.com 能正常访问。

宝塔里不要把这个当普通 PHP 源码运行。正确方式是 Node 项目负责运行服务，网站域名通过反向代理访问 Node 端口。

Xiaopi

小皮面板 / phpStudy 部署

1. 小皮主要管理 Apache、Nginx、PHP、MySQL，这个项目需要额外安装 Node.js 20+。
2. 把项目放到固定目录，例如 D:\phpstudy_pro\WWW\aikefu。
3. 打开 PowerShell 进入项目目录，执行 npm install 和 npm start。
4. 小皮里添加一个网站，例如 kf.example.com，然后在 Nginx 配置里添加反向代理到 http://127.0.0.1:3000。
5. 如果不会改 Nginx 配置，可以先临时用 http://服务器IP:3000 测试，确认服务正常后再做域名代理。
6. 正式运行建议用 NSSM 或 PM2 让 Node 服务常驻，避免关闭 PowerShell 后服务停止。

cd D:\phpstudy_pro\WWW\aikefu
npm install
npm start

Other Panels

1Panel、AMH、WDCP、云虚拟主机等其他环境

Intranet

公司内部服务器 / 局域网部署

1. 如果只给公司内网网站使用，可以把服务部署在内网服务器，不必暴露公网。
2. 内网电脑需要能访问 AI 客服服务地址，例如 http://192.168.1.20:3000 或 http://kf.intra.company。
3. 如果使用内部域名，需要让公司 DNS 或 hosts 能解析到服务器内网 IP。
4. 如果需要调用外部 AI 接口，服务器必须能访问外网；如果不能出外网，就只能使用本地规则兜底或接入内网大模型接口。
5. 内网也建议设置后台密码、域名白名单和定期备份。

内网嵌入代码里的 apiBase 要写内网用户能访问到的地址。公网域名访问不到内网 IP，内网地址也不能被外部访客访问。

Admin

后台必须配置的内容

Content

录入产品资料和知识库

1. 进入「产品资料」，录入产品名称、型号、分类、关键词、说明。关键词里写客户常用叫法、简称、别名和型号。
2. 图片链接和资料链接是可选项。命中产品时前台可以展示产品卡片和“查看资料”入口。
3. 进入「知识库」，录入售后说明、资料下载、服务流程、常见问题、报价规则等。
4. 资料多时，先导出后台提供的 .xlsx 表格，用 Excel/WPS 编辑后再导入。
5. 如果保留已有 id 再导入，会更新原记录；如果 id 留空，会新增记录。

Embed

把客服嵌入到业务网站

1. 确认 AI 客服服务域名能访问，例如 https://kf.example.com。
2. 把下面代码里的 apiBase 和 src 改成你的 AI 客服服务域名。
3. 把代码放到业务网站页面的 </body> 前面，或者放到网站后台的“底部代码 / 统计代码 / 自定义 JS”位置。
4. 如果业务网站是 HTTPS，AI 客服也必须用 HTTPS，否则浏览器可能拦截。
5. 刷新业务网站，右下角出现客服按钮即表示嵌入成功。

<script>
  window.SITE_AI_WIDGET = {
    apiBase: "https://kf.example.com"
  };
</script>
<script src="https://kf.example.com/widget.js" defer></script>

Checklist

上线前检查清单

Troubleshooting

常见问题排查