xcchat 是一个基于 Django 和 Django Channels 构建的轻量级在线客服系统。它支持实时聊天、人工/机器人客服切换、访客信息追踪和多站点接入

xcchat - 开源在线客服系统

作者：北小菜
邮箱：bilibili_bxc@126.com
QQ：1402990689
微信：bilibili_bxc
哔哩哔哩主页：https://space.bilibili.com/487906612
gitee地址：https://gitee.com/Vanishi/xcchat
github地址：https://github.com/beixiaocai/xcchat

xcchat 是一个基于 Django 和 Django Channels 构建的轻量级在线客服系统。它支持实时聊天、人工/机器人客服切换、访客信息追踪和多站点接入。

🌟 项目特点

B2C架构：面向企业对客户的客服场景
实时双向通信：基于 WebSocket 实现毫秒级消息传递
双模式客服：人工客服与机器人客服自由切换
访客行为分析：自动收集访客设备信息、地理位置等数据
FAQ 管理：内置 FAQ 管理系统，支持在前端展示常见问题。
高度可定制：前后端分离设计，易于二次开发和定制

🏗️ 系统架构

xcchat 采用现代化的分层架构设计：

表现层：前端 Widget 组件和管理后台界面
应用层：Django 应用模块（chat、sysadmin、widget 等）
服务层：WebSocket 服务、AI 服务、文件处理服务
数据层：MySQL 主数据库
通信层：基于 Django Channels 的 WebSocket 通信

🚀 功能特性

站点管理：支持创建和管理多个站点（Site），每个站点拥有独立的客服和数据。
实时通讯：基于 WebSocket (Django Channels) 实现低延迟的实时消息传输。
混合客服模式：
- 人工客服：支持多客服协作。
- 机器人客服：支持配置机器人 API 接口和 API Key，实现自动回复。
访客追踪：自动记录访客的 IP、浏览器、操作系统、设备类型及地理位置信息。
FAQ 知识库：可配置常见问题解答，帮助访客自助解决问题。
便捷接入：提供轻量级 JavaScript Widget，只需一段代码即可嵌入任何网页。
统一后台管理：
- 管理员后台 (sysadmin)：统一管理站点、客服、FAQ、查看会话记录和系统日志。

🛠️ 技术栈

后端框架：Python 3.8+, Django 5.0.4, Django Channels 4.3.2
数据库：MySQL 8+ (主数据库)
实时通信：WebSocket (基于 Django Channels 和 Daphne)
前端框架：Bootstrap 5, Vanilla JavaScript
AI 相关：支持集成大语言模型、向量检索等AI能力
其他组件：Django REST Framework, django-cors-headers

🗄️ 数据库设计

项目目前采用单一数据库设计：

主数据库（MySQL）：存储用户、站点、会话、消息等核心业务数据

知识库相关的数据结构和存储方案将在后续版本中重新设计，以适配新的简洁知识库功能。

📋 环境要求

Python 3.8+
MySQL 8+（推荐 InnoDB 引擎，UTF8MB4 字符集）
（可选）Redis（用于生产环境的 Channel Layer）

⚡ 快速开始

1. 克隆项目

git clone <repository_url> cd xcchat

2. 创建并激活虚拟环境

windows 创建虚拟环境

//创建虚拟环境 python -m venv venv //切换到虚拟环境 venv\Scripts\activate //更新pip python -m pip install --upgrade pip -i https://pypi.tuna.tsinghua.edu.cn/simple //安装requirements python -m pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

linux 创建虚拟环境

//创建虚拟环境 python -m venv venv //切换到虚拟环境 source venv/bin/activate //更新pip python -m pip install --upgrade pip -i https://pypi.tuna.tsinghua.edu.cn/simple //安装requirements python -m pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

3. 数据库配置

项目使用 MySQL 作为主数据库，向量数据也存储在同一数据库中（使用二进制字段存储向量，不再依赖 pgvector 扩展）。

在framework/settings.py中配置数据库连接：

ENGINE:django.db.backends.mysql
HOST: 数据库主机
PORT: 端口（默认 3306）
NAME: 数据库名
USER: 用户名
PASSWORD: 密码

4. 迁移数据库

python manage.py migrate

5. 创建超级管理员（可选）

项目已内置默认管理员账号：

用户名:admin
密码:admin888

6. 启动服务

开发环境下可以使用 Django 自带的runserver(支持 ASGI)：

python manage.py runserver 0.0.0.0:8063

或者使用daphne启动：

daphne -b 0.0.0.0 -p 8063 framework.asgi:application

📖 使用指南

1. 登录管理员后台

访问http://localhost:8063/login/使用默认管理员账号登录：

用户名:admin
密码:admin888

首次登录后建议立即修改密码以保障系统安全。

2. 站点与客服管理

进入后台后，在站点管理页面添加一个新的站点（密钥）。
填写站点名称，保存后将生成 API Key。
在客服管理中为站点分配客服人员或配置机器人。

3. 获取接入代码

在站点列表页面查看站点的 API Key。将以下代码添加到你网站 HTML 的<body>标签结束前：

<script src="http://你的域名:端口/static/widget/js/xcchat.js" data-api-key="你的API_KEY"> </script>

4. 模拟聊天

打开嵌入了代码的网页，作为访客发送消息。
在管理员后台的对话管理页面，可以实时收到消息并回复。

知识库相关功能正在重构中，当前版本暂未提供知识库管理与对话能力。

📂 项目结构

xcchat/ ├── chat/ # 核心聊天业务 (Models, Consumers) ├── core/ # 核心用户模型和日志 ├── sysadmin/ # 系统管理员后台视图 ├── website/ # 官网/着陆页 ├── widget/ # 前端组件 (JS Widget) ├── framework/ # 项目配置 (Settings, ASGI/WSGI) ├── static/ # 静态文件 ├── templates/ # 全局模板 ├── manage.py # Django 管理脚本 └── requirements.txt # 项目依赖

注：该系统采用B2C架构，为企业提供客户服务支持，而非多租户SaaS平台。

❓ 常见问题

报错 "MySQLdb or PyMySQL is required"
- 项目使用PyMySQL作为 MySQL 驱动，确保按requirements.txt安装即可。
报错 “Cannot use ImageField because Pillow is not installed”
- 请安装Pillow（已在requirements.txt列出），并重新运行迁移。
Channels 生产环境部署
- 建议使用 Redis 作为 Channel Layer，并通过daphne或uvicorn部署 ASGI 服务，前置反向代理（如 Nginx）。