AI Agent、架构决策记录与工程上下文治理：团队如何把隐性约束留在仓库里
2026/7/30 10:31:38
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 xcchat2. 创建并激活虚拟环境
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/simplelinux 创建虚拟环境
//创建虚拟环境 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/simple3. 数据库配置
项目使用 MySQL 作为主数据库，向量数据也存储在同一数据库中（使用二进制字段存储向量，不再依赖 pgvector 扩展）。
在framework/settings.py中配置数据库连接：
ENGINE:django.db.backends.mysqlHOST: 数据库主机PORT: 端口（默认 3306）NAME: 数据库名USER: 用户名PASSWORD: 密码
4. 迁移数据库
python manage.py migrate5. 创建超级管理员（可选）
项目已内置默认管理员账号：
- 用户名:
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）。
- 建议使用 Redis 作为 Channel Layer，并通过
📦 关键依赖
- 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