# xcchat **Repository Path**: ecoteam/xcchat ## Basic Information - **Project Name**: xcchat - **Description**: xcchat 是一个基于 Django 和 Django Channels 构建的轻量级在线客服系统。它支持实时聊天、人工/机器人客服切换、访客信息追踪和多站点接入。 - **Primary Language**: Python - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 1 - **Created**: 2025-12-17 - **Last Updated**: 2025-12-17 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README ## 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 采用现代化的分层架构设计： 1. **表现层**：前端 Widget 组件和管理后台界面 2. **应用层**：Django 应用模块（chat、sysadmin、widget 等） 3. **服务层**：WebSocket 服务、AI 服务、文件处理服务 4. **数据层**：MySQL 主数据库 5. **通信层**：基于 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 ## 🗄️ 数据库设计 项目目前采用单一数据库设计： 1. **主数据库（MySQL）**：存储用户、站点、会话、消息等核心业务数据 > 知识库相关的数据结构和存储方案将在后续版本中重新设计，以适配新的简洁知识库功能。 ## 📋 环境要求 - Python 3.8+ - MySQL 8+（推荐 InnoDB 引擎，UTF8MB4 字符集） - （可选）Redis（用于生产环境的 Channel Layer） ## ⚡ 快速开始 ### 1. 克隆项目 ```bash git clone 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. 迁移数据库 ```bash python manage.py migrate ``` ### 5. 创建超级管理员（可选） 项目已内置默认管理员账号： - **用户名**: `admin` - **密码**: `admin888` ### 6. 启动服务 开发环境下可以使用 Django 自带的 `runserver` (支持 ASGI)： ```bash python manage.py runserver 0.0.0.0:8063 ``` 或者使用 `daphne` 启动： ```bash 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 的 `` 标签结束前： ```html ``` ### 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）。 ## 📦 关键依赖 - Django==5.0.4 - djangorestframework==3.15.1 - django-cors-headers==4.3.1 - channels==4.3.2 - daphne==4.2.1 - PyMySQL==1.1.1 - Pillow==12.0.0 ## 📄 License MIT License