一个现代化的智能客服系统:AI + 人工一体+可私有化部署

English | 中文

AI-CS 智能客服系统

开源的 AI 客服系统：AI + 人工一体、可私有化部署、可配置、可观测。
适合把「官网右下角客服小窗」与「客服工作台」一起落地的团队。

界面预览

官网首页（核心能力模块）

客服小窗

人工客服模式

AI 客服模式

在线演示

官网首页（产品介绍 + SEO）：demo.cscorp.top
访客聊天页：demo.cscorp.top/chat（也可从首页右下角按钮进入）
客服登录：demo.cscorp.top/agent/login

你能用它做什么

访客侧（嵌入小窗）
- 右下角聊天小窗，可嵌入任意网站（iframe 方式）
- 支持 AI 模式 / 人工模式切换、消息提示音、文件上传
- 可选「本回合联网搜索」开关（是否对访客展示可在后台控制）
- 访客邮箱采集：首次在消息框按键时展开邮箱行（可选填）；填完或发首条消息后自动收起，便于离线触达
- 会话安全：每个访客会话持有随机 access_token，读/发消息与 WebSocket 须携带令牌，防止仅凭会话 ID 越权访问
客服侧（工作台）
- 会话列表 分页加载、实时消息（WebSocket）、未读角标提示；大批量 open 会话下更流畅
- 自动关闭长期未活跃的 open 访客会话（设置 → 会话维护 或 .env 可配天数）
- 访客 IP 与大致地理位置（离线 ip2region，客服工作台访客详情展示）
- 支持「实时共享草稿输入」（双方未发送内容可实时可见）
- 多模型管理（文本/绘画等）与对话配置；OpenAI 兼容 Chat Completions 接口，填对 URL + 模型名 + Key 即可接入多数中转/官方服务
- 提示词配置（Prompt 管理）
- 知识库管理 + RAG（向量检索，可按需启用；向量库不可用时可不影响启动）
- PDF / DOCX 导入、文档分段（Chunk） 与逐段向量化
- FAQ 优先：命中 FAQ 直接返回答案；聊天输入 / 快捷搜索 FAQ
- 知识库测试窗口（内部会话），回复可标记 sources_used（知识库 / 大模型 / 联网）
- 离线邮件通知：访客离线且已留邮箱时，客服发人工消息后延迟 SMTP 推送（设置页可配，访客上线自动取消、同会话合并）
- 日志中心：结构化日志落库，支持按级别/分类/事件/trace_id/关键字筛选排障
- 数据报表：按日/区间查看访客打开小窗、会话与消息、AI 回复与失败率、知识库命中率、转人工等指标
官网与 SEO（面向获客）
- 蓝白主题官网首页，分段渐变与滚动进场动效
- metadata / Open Graph / JSON-LD / sitemap.xml / robots.txt，便于搜索引擎收录与社交分享
可选联网搜索（Web Search）
- 支持 Serper：MCP 接入（SERPER_MCP_URL）或直连 API（SERPER_API_KEY）
- 也支持「厂商内置 web search」（由模型自己决定是否搜）的 function calling 流程（按模型能力与供应商而定）

项目结构

AI-CS/
├── backend/                    # Go 后端：API、WebSocket、AI、RAG
│   ├── controller/             # HTTP 控制器
│   ├── service/                # 业务逻辑（会话、消息、知识库、AI…）
│   ├── repository/             # 数据访问
│   ├── models/                 # 数据模型
│   ├── infra/                  # DB、Milvus、ip2region、存储
│   ├── websocket/              # 实时消息与 Redis 广播
│   ├── router/                 # 路由注册
│   ├── data/                   # ip2region xdb（可选，见 data/README.md）
│   └── main.go
├── frontend/                   # Next.js：官网、访客小窗、客服工作台
│   ├── app/                    # 页面路由（/、/chat、/agent/*）
│   ├── components/             # UI 组件
│   ├── features/               # 按领域划分的 API / hooks
│   └── public/widget.js        # 可嵌入站点的脚本小窗
├── doc/                        # 项目文档与 CHANGELOG
├── scripts/                    # 辅助脚本（如下载 ip2region xdb）
├── assets/readme/              # README 截图资源
├── docker-compose.yml          # 本地构建部署
├── docker-compose.prod.yml     # 预构建镜像部署
├── docker-compose.milvus.yml     # Milvus 相关（按需）
└── .env.example                # 环境变量模板（复制为 .env）

快速开始（只维护根目录 `/.env`）

统一配置真源：只维护项目根目录 /.env。Docker 与本地启动都读这一份。
初始化：复制 /.env.example 为 /.env 并填写必填项。

方式 A：预构建镜像部署（推荐，最省事）

1）准备配置

git clone https://github.com/2930134478/AI-CS.git
cd AI-CS
cp .env.example .env

至少要改（必填）：

数据库：MYSQL_ROOT_PASSWORD、DB_PASSWORD
管理员：ADMIN_PASSWORD
安全密钥：ENCRYPTION_KEY（64 位 hex）

生成 ENCRYPTION_KEY：

# Linux/Mac
openssl rand -hex 32

# Windows PowerShell
-join ((48..57) + (97..102) | Get-Random -Count 64 | ForEach-Object {[char]$_})

2）启动

docker-compose -f docker-compose.prod.yml up -d

3）访问

官网首页：localhost:3000
访客聊天：localhost:3000/chat
客服登录：localhost:3000/agent/login
- 用户名：admin（或 .env 中 ADMIN_USERNAME）
- 密码：.env 中 ADMIN_PASSWORD

生产部署提示：前端生产镜像走同域 /api/*，需外层 Nginx/Caddy 将 /api 反向代理到后端，并转发 X-User-Id、X-Conversation-Token 等自定义请求头。本地 npm run dev 时由 Next.js rewrites 自动代理。

演示站管理员安全策略

ADMIN_PASSWORD 仅在首次创建管理员时生效；数据库里已有管理员后，重启服务不会覆盖其密码。
出于演示环境安全，前端默认不允许：
- 修改 admin 账号密码
- 删除任意 admin 账号
删除 agent 用户时，系统会自动把其名下 AI 配置转移给当前管理员，避免配置丢失或无人维护。
若需维护管理员账号，请直接通过数据库操作（例如重置密码、删除异常管理员）。

端口修改（重要说明）

默认端口：前端 3000，后端对外 18080
修改：在 .env 里改 FRONTEND_PORT / BACKEND_PORT

说明：预构建镜像在某些静态资源/图片路径场景可能与端口强绑定（历史兼容原因）。如果你需要彻底自定义端口并确保所有资源路径一致，建议用下面的「方式 B 本地构建」。

方式 B：Docker 本地构建部署（可自定义）

git clone https://github.com/2930134478/AI-CS.git
cd AI-CS
cp .env.example .env
docker-compose up -d --build

方式 C：传统部署（本地开发/手动安装）

环境要求：

Go 1.24+
Node.js 20.9.0+

MySQL 8.0+

git clone https://github.com/2930134478/AI-CS.git
cd AI-CS
cp .env.example .env

# 1) 后端
cd backend
go mod tidy
go run main.go

# 2) 前端（新开终端）
cd ../frontend
npm install
npm run dev

配置字典（根目录 `/.env`）

下面表格以 /.env.example 为准，帮助你快速判断「必填/可选/什么时候需要填」。

变量	用途	是否必填	默认值（示例）	示例
`APP_PROFILE`	部署画像（`docker/local`）	否	`docker`	`local`
`SERVER_HOST`	后端监听地址	是	`0.0.0.0`	`127.0.0.1`
`SERVER_PORT`	后端容器内端口	是	`8080`	`8080`
`GIN_MODE`	后端模式	建议	`release`	`debug`
`SYSTEM_LOG_MIN_LEVEL`	结构化日志最低落库级别（`system_logs`）	否	`info`	`warn` 可减少成功类写入；`none` 关闭落库；客服端「日志中心」可改并持久化，覆盖本项直至恢复
`DB_HOST`	后端数据库地址	是	`mysql`	`localhost`
`DB_PORT`	后端数据库端口	是	`3306`	`3306`
`DB_USER`	数据库用户名	是	`ai_cs_user`	`root`
`DB_PASSWORD`	数据库密码	是	无	`StrongPwd`
`DB_NAME`	数据库名	是	`ai_cs`	`ai_cs`
`MYSQL_ROOT_PASSWORD`	MySQL root 密码（compose）	是（Docker）	无	`RootPwd`
`MYSQL_PORT`	MySQL 对外端口（compose）	否	`3306`	`13306`
`ADMIN_USERNAME`	默认管理员用户名	否	`admin`	`admin`
`ADMIN_PASSWORD`	默认管理员密码	是	无	`AdminPwd`
`ENCRYPTION_KEY`	后端加密密钥（64位 hex）	是	无	`openssl rand -hex 32`
`REDIS_URL`	Redis 连接串（启用跨实例 WS 广播）	可选（多实例推荐）	空	`redis://:pwd@redis:6379/0`
`REDIS_ADDR`	Redis 地址（与 `REDIS_URL` 二选一）	可选	空	`redis:6379`
`REDIS_PASSWORD`	Redis 密码（使用 `REDIS_ADDR` 时）	可选	空	`StrongRedisPwd`
`REDIS_DB`	Redis DB（使用 `REDIS_ADDR` 时）	可选	`0`	`0`
`REDIS_WS_CHANNEL`	分布式 WS 事件频道名	可选	`ai_cs:ws_events`	`ai_cs:ws_events`
`BACKEND_PORT`	后端映射到宿主机端口	否	`18080`	`28080`
`FRONTEND_PORT`	前端映射到宿主机端口	否	`3000`	`13000`
`MILVUS_HOST`	向量库地址	可选（启用 RAG）	`milvus-standalone`	`localhost`
`MILVUS_PORT`	向量库端口	可选（启用 RAG）	`19530`	`19530`
`MILVUS_USERNAME`	Milvus 用户名	可选	空	`user`
`MILVUS_PASSWORD`	Milvus 密码	可选	空	`pass`
`MILVUS_DISABLED`	禁用向量库（不连接）	否	`false`	`true`
`VECTOR_STORE_DISABLED`	同上（兼容开关）	否	`false`	`true`
`MILVUS_REQUIRED`	强依赖向量库（失败即退出）	否	`false`	`true`
`RAG_MIN_SCORE`	RAG 向量检索最低相似度（0~1）	否	`0.22`	分段场景可试 `0.2`~`0.35`
`AUTO_CLOSE_CONVERSATION_DAYS`	自动关闭 N 天未活跃 open 会话（0=关闭）	否	`7`	也可在设置 → 会话维护配置
`OFFLINE_EMAIL_ENABLED`	访客离线邮件推送总开关	否	`false`	`true`
`OFFLINE_EMAIL_DELAY_SECONDS`	离线邮件延迟秒数	否	`60`	`30`
`SMTP_HOST` / `SMTP_PORT`	离线邮件 SMTP 地址与端口	可选	空 / `465`	优先在设置页配置
`SMTP_USER` / `SMTP_PASSWORD`	SMTP 账号与密码	可选	空	云厂商 SMTP
`SMTP_FROM_EMAIL` / `SMTP_FROM_NAME`	发件人邮箱与显示名	可选	空	`noreply@example.com`
`SERPER_MCP_URL`	联网搜索 MCP 地址	可选（启用联网）	空	`http://host:3000/sse`
`SERPER_API_KEY`	联网搜索 API Key	可选（启用联网）	空	`xxxxx`
`NEXT_PUBLIC_SITE_URL`	站点对外绝对地址（用于 SEO）	否	空（默认 demo 域名）	`https://www.example.com`
`NEXT_PUBLIC_API_BASE_URL`	前端公开 API 地址	建议	`http://localhost:18080`	`https://api.example.com`
`NEXT_PUBLIC_BACKEND_HOST`	前端 dev 代理目标 host	否	`localhost`	`127.0.0.1`
`NEXT_PUBLIC_BACKEND_PORT`	前端 dev 代理目标 port	否	`8080`	`18080`
`NEXT_PUBLIC_MATOMO_CONTAINER_URL`	Matomo 脚本地址	可选	空	`https://.../container.js`
`BACKEND_IMAGE`	预构建后端镜像（prod compose）	是（prod）	`537yaha/ai-cs-backend:latest`	`your/backend:tag`
`FRONTEND_IMAGE`	预构建前端镜像（prod compose）	是（prod）	`537yaha/ai-cs-frontend:latest`	`your/frontend:tag`

启用/关闭知识库（RAG）的推荐做法

两套独立配置（不要混用）

用途	配置位置	接口
AI 对话（大模型回复）	设置 → AI 配置	OpenAI 兼容 Chat Completions（如 `…/v1/chat/completions`）
向量化 / RAG 检索	设置 → 知识库向量模型	OpenAI 兼容 Embeddings（如 `…/v1/embeddings`）

开关 Milvus

你暂时不想用知识库：把 .env 里 MILVUS_DISABLED=true（或 VECTOR_STORE_DISABLED=true）
- 应用仍可启动，AI 对话与人工客服不受影响
你必须依赖知识库（生产强约束）：把 .env 里 MILVUS_REQUIRED=true
- 此时如果 Milvus 不可用，会落库一条错误日志后退出，避免「半残服务上线」

分段（Chunk）与检索调优

长文档建议先分段再向量化；Milvus 集合含 chunk_db_id 字段，schema 变更后可能需要 重新向量化。
分段后相似度分数通常低于整篇文档；若出现「搜不到」，可调低 .env 中的 RAG_MIN_SCORE（默认 0.22）。
FAQ 条目会 优先于 向量检索直接返回答案。

多实例实时消息一致性（Redis）

单实例可不配置 Redis，系统维持当前行为。
多实例/多副本部署建议配置 REDIS_URL（或 REDIS_ADDR + REDIS_PASSWORD + REDIS_DB），用于 WebSocket 事件跨实例同步。
可通过 REDIS_WS_CHANNEL 自定义事件频道（默认 ai_cs:ws_events）。

集成访客小窗到你的网站（iframe）

把下面代码放到你网站的 </body> 前，核心是把 src 指向你自己的部署域名的 /chat。
说明：/chat 在 iframe 内会自动进入嵌入模式（也可显式加 ?embed=1），只显示聊天界面，不会出现第二个浮动按钮；宿主站点保留外层「打开/关闭」按钮即可，点一次即可对话。

<div id="ai-cs-widget" style="position: fixed; bottom: 20px; right: 20px; z-index: 9999;">
  <button
    id="ai-cs-toggle-btn"
    style="width:56px;height:56px;border-radius:50%;background:#3b82f6;color:#fff;border:none;cursor:pointer;box-shadow:0 4px 12px rgba(0,0,0,.15);"
    onclick="toggleChat()"
  >
    Chat
  </button>

  <iframe
    id="ai-cs-chat-iframe"
    src="https://你的域名/chat"
    style="display:none;position:fixed;bottom:80px;right:20px;width:400px;height:600px;max-width:calc(100vw - 40px);max-height:calc(100vh - 100px);border:none;border-radius:12px;box-shadow:0 20px 25px -5px rgba(0,0,0,.1);"
  ></iframe>
</div>

<script>
  function toggleChat() {
    const iframe = document.getElementById("ai-cs-chat-iframe");
    iframe.style.display = iframe.style.display !== "none" ? "none" : "block";
  }
</script>

也可使用 frontend/public/widget.js（AICSWidget.init({ ... })），详见脚本内注释。

常见问题与排障（先看这里）

提示音听不到：浏览器通常需要「用户一次交互」才能解锁音频；请先点一下页面任意按钮/再打开喇叭开关测试
向量库连不上导致启动失败：检查 .env 的 MILVUS_REQUIRED 是否误开；不需要知识库时建议 MILVUS_DISABLED=true
知识库 / RAG 搜不到内容：确认 Milvus 已启动、文档已 分段并向量化；分段场景可尝试调低 RAG_MIN_SCORE（默认 0.22）
Docker 创建文档报「请提供 X-User-Id」：需使用含最新修复的前端镜像；并确认 Nginx 转发了 X-User-Id 请求头
API 401/403（访客）：访客接口须带 X-Conversation-Token；客服接口须先登录并带 X-User-Id
搜不到站点/分享卡片不正确：设置 NEXT_PUBLIC_SITE_URL=https://你的域名，用于 canonical / OG / sitemap 生成
弹窗「初始化失败」/ 后端连不上 MySQL：先 curl http://<host>:<BACKEND_PORT>/health，再 docker logs ai-cs-backend --tail 50；Docker 部署时 DB_HOST 应为 mysql 而非 localhost
离线邮件没收到：仅 人工客服消息 触发（AI 自动回复不触发）；访客须已留邮箱且 WebSocket 离线；SMTP 可在 设置 → 离线邮件通知 配置并发送测试信

Star History

<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=2930134478/AI-CS&type=Date&theme=dark" />
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=2930134478/AI-CS&type=Date" />
<img alt="Star History Chart" src="https://api.star-history.com/svg?repos=2930134478/AI-CS&type=Date" />

交流与反馈

Bug / 功能建议：GitHub Issues（请附部署方式、后端日志；勿贴 API Key、数据库密码）
QQ 交流群：1106804464，官网 / Demo 页脚「联系我们」会同步展示

Friendly Links

在线演示 · AI-CS Demo
ip2region · 离线 IP 地理位置库（本项目访客地域解析）
欢迎通过 Issue 推荐友链，维护者审核后加入本节

贡献

欢迎提交 Issue 和 Pull Request。报 Bug 请附上部署方式、后端日志与 .env 关键项（密码打码）。

README.md 20 KB

Permalink Riwayat Mentahan

一个现代化的智能客服系统:AI + 人工一体+可私有化部署

AI-CS 智能客服系统

目录

界面预览

在线演示

你能用它做什么

项目结构

快速开始（只维护根目录 `/.env`）

方式 A：预构建镜像部署（推荐，最省事）

1）准备配置

2）启动

3）访问

演示站管理员安全策略

端口修改（重要说明）

方式 B：Docker 本地构建部署（可自定义）

方式 C：传统部署（本地开发/手动安装）

配置字典（根目录 `/.env`）

启用/关闭知识库（RAG）的推荐做法

两套独立配置（不要混用）

开关 Milvus

分段（Chunk）与检索调优

多实例实时消息一致性（Redis）

集成访客小窗到你的网站（iframe）

相关文档

常见问题与排障（先看这里）

Star History

交流与反馈

Friendly Links

贡献

许可证

README.md 20 KB Permalink Riwayat Mentahan

一个现代化的智能客服系统:AI + 人工一体+可私有化部署

AI-CS 智能客服系统

目录

界面预览

在线演示

你能用它做什么

项目结构

快速开始（只维护根目录 /.env）

方式 A：预构建镜像部署（推荐，最省事）

1）准备配置

2）启动

3）访问

演示站管理员安全策略

端口修改（重要说明）

方式 B：Docker 本地构建部署（可自定义）

方式 C：传统部署（本地开发/手动安装）

配置字典（根目录 /.env）

启用/关闭知识库（RAG）的推荐做法

两套独立配置（不要混用）

开关 Milvus

分段（Chunk）与检索调优

多实例实时消息一致性（Redis）

集成访客小窗到你的网站（iframe）

相关文档

常见问题与排障（先看这里）

Star History

交流与反馈

Friendly Links

贡献

许可证

README.md 20 KB

Permalink Riwayat Mentahan

快速开始（只维护根目录 `/.env`）

配置字典（根目录 `/.env`）