这次我们来看一个名为“悟空 AICRM”的项目它本质上是一个集成了AI能力的客户关系管理系统。对于需要将大模型智能对话、内容生成等能力融入销售、客服、市场等业务流程的团队来说本地部署一个这样的系统意味着数据安全可控和深度定制化。本文将带你完成从零开始的完整Docker化部署重点解决“能不能跑起来”和“怎么用起来”的问题。项目的核心价值在于它试图将AI Agent、知识库、工作流等前沿概念封装成一个开箱即用的业务系统。我们最关心的是它的部署门槛是否需要高性能GPU依赖是否复杂本文的实操将基于Docker容器技术这能极大简化环境配置的复杂度。无论你是想评估这套系统还是计划将其用于内部测试或小规模应用跟着步骤走一遍就能得到明确的答案。1. 核心能力速览在动手部署之前我们先快速了解“悟空 AICRM”的核心特性和部署要求这有助于判断它是否适合你的当前环境。能力项说明项目类型AI增强型客户关系管理系统CRM核心功能智能客户对话、销售流程自动化、知识库问答、数据分析看板、AI工作流引擎部署方式推荐Docker Compose一键拉起所有服务Web前端、后端API、数据库、向量数据库等硬件门槛中等。CPU推理模式下对GPU无硬性要求但涉及大模型推理时GPU会显著提升体验。内存建议8GB以上。显存占用非必须取决于模型。如果使用本地部署的轻量化大模型如Qwen2.5-7B-Instruct的4bit量化版约需6-8GB显存。系统也支持调用云端API如OpenAI、DeepSeek此时对本地显卡无要求。数据存储使用MySQL作为业务数据库Milvus/Weaviate等作为向量数据库用于知识库。需预留至少10GB磁盘空间。是否支持API是。系统提供完整的RESTful API可供其他业务系统集成调用。是否支持批量任务是。支持批量导入客户数据、批量执行AI外呼任务需配置语音接口、批量生成营销内容等。适合场景企业内网安全部署、AICRM方案技术验证、对数据隐私要求高的销售/客服团队、开发者进行二次开发。从表格可以看出该项目通过Docker实现了复杂依赖的封装部署的核心难点从“环境配置”转移到了“网络编排与资源分配”。只要宿主机资源足够部署过程是标准化且可重复的。2. 适用场景与使用边界在投入时间部署之前明确它能做什么、不能做什么至关重要。它非常适合以下场景数据敏感型企业的内部CRM所有数据客户信息、对话记录、知识库都留在自有服务器符合金融、医疗、法律等行业的合规要求。AI与业务结合的探索与验证团队希望在一个现成的系统中快速体验AI如何改造客户跟进、智能问答、报告生成等具体场景而无需从零开发。定制化AI工作流的开发基础系统提供了工作流引擎开发者可以基于此构建复杂的、符合自身业务逻辑的自动化流程例如“客户询价 - AI分析历史订单 - 自动生成报价单 - 发送邮件”。替代部分传统CRM的自动化功能利用AI自动总结通话记录、分类客户意向、生成下周跟进计划等提升销售人效。它的使用边界和注意事项并非“开箱即用”的SaaS部署后需要进行大量的初始化配置包括组织架构、角色权限、业务流程定义、AI模型接入等有一定学习成本。AI能力依赖模型或API系统的智能程度取决于背后接入的大模型。使用免费开源模型效果可能不及GPT-4等商用模型使用云端API则会产生费用并涉及网络访问。性能与规模相关当客户数据量达到百万级或并发用户数很高时需要对数据库、向量数据库和缓存进行性能调优默认的Docker Compose配置可能无法支撑。合规与授权如果使用该系统处理真实的客户个人信息必须确保符合《个人信息保护法》等相关法规。使用AI生成内容时需对生成结果进行人工审核避免产生错误或有害信息。3. 环境准备与前置条件部署“悟空 AICRM”需要一个干净的Linux服务器环境。以下是在开始安装Docker和部署应用之前必须完成的准备工作。3.1 操作系统要求推荐Ubuntu 22.04 LTS 或 CentOS 8/Rocky Linux 8。本文演示以Ubuntu 22.04为例。备选其他主流Linux发行版也可但部分命令和包管理工具需要调整。3.2 硬件资源检查请通过SSH连接到你的服务器并执行以下命令进行基础检查# 1. 检查系统版本 lsb_release -a # 2. 检查CPU和内存 free -h lscpu | grep -E “(Model name|CPU\(s\))” # 3. 检查磁盘空间确保根目录或目标数据盘有足够空间 df -h # 4. 检查GPU如果有并计划用于本地模型推理 lspci | grep -i nvidia nvidia-smi # 如果已安装驱动此命令可查看显卡详情最低配置建议2核CPU8GB内存50GB可用磁盘空间。推荐配置4核CPU16GB内存100GB SSD磁盘空间。如果计划在本地运行7B参数以上的大模型则需要一张至少8GB显存的NVIDIA显卡。3.3 网络与安全组配置确保服务器的以下端口未被占用且已在防火墙或云服务商安全组中放行80/443用于Web前端访问可通过Nginx反代。3306MySQL数据库端口强烈建议仅限内网访问或修改为其他端口。19530Milvus向量数据库端口默认。7860/8000后端API服务常用端口具体以项目docker-compose.yml为准。22SSH管理端口。你可以使用netstat -tunlp命令查看当前端口占用情况。4. 安装部署与启动方式一切就绪我们开始核心的部署流程。全程使用Docker和Docker Compose这是最简洁、依赖冲突最少的方式。4.1 安装Docker与Docker Compose如果你的系统尚未安装请执行以下命令# 更新系统包索引 sudo apt-get update # 安装必要的依赖包 sudo apt-get install -y ca-certificates curl gnupg lsb-release # 添加Docker官方GPG密钥 sudo mkdir -p /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gosu tee /etc/apt/keyrings/docker.asc /dev/null # 设置Docker稳定版仓库 echo \ “deb [arch$(dpkg --print-architecture) signed-by/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \ $(lsb_release -cs) stable” | sudo tee /etc/apt/sources.list.d/docker.list /dev/null # 安装Docker Engine sudo apt-get update sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin # 验证Docker安装 sudo docker run hello-world # 将当前用户加入docker组避免每次使用sudo操作后需退出SSH重新登录生效 sudo usermod -aG docker $USER4.2 获取“悟空 AICRM”部署文件通常开源项目会提供标准的docker-compose.yml和环境变量配置文件.env。你需要从项目的官方仓库如GitHub获取它们。# 创建一个专用的项目目录 mkdir -p ~/wukong-aicrm cd ~/wukong-aicrm # 假设项目仓库地址请替换为实际地址 # 方式一直接下载部署文件如果项目提供 wget -O docker-compose.yml https://raw.githubusercontent.com/xxx/wukong-aicrm/main/docker-compose.yml wget -O .env.example https://raw.githubusercontent.com/xxx/wukong-aicrm/main/.env.example # 方式二克隆整个仓库如果需要进行代码级定制 # git clone https://github.com/xxx/wukong-aicrm.git . # cd docker # 复制环境变量模板并配置 cp .env.example .env4.3 关键配置修改编辑.env文件这是整个系统的核心配置。你需要重点关注以下几项# 使用文本编辑器如nano或vim打开.env文件 nano .env数据库密码修改MYSQL_ROOT_PASSWORD、MYSQL_PASSWORD为强密码。服务端口检查WEB_PORT前端、API_PORT后端等确保不与系统已有端口冲突。AI模型配置如果使用云端API如OpenAI需要填写OPENAI_API_KEY、OPENAI_BASE_URL若使用代理。如果使用本地模型需要配置LOCAL_LLM_MODEL模型名称或路径和LOCAL_LLM_API_BASE指向本地Ollama、OpenAI-format API等服务的地址。文件存储路径确认VOLUME_PATH指向一个足够大的磁盘分区。域名/访问地址设置DOMAIN或APP_URL用于系统内部链接生成。4.4 启动所有服务配置完成后使用Docker Compose一键启动所有容器。# 在包含docker-compose.yml的目录下执行 # -d 参数表示后台运行 sudo docker compose up -d这个命令会依次拉取如果本地没有并启动MySQL、Redis、Milvus、后端API、前端Web等多个容器。首次执行耗时较长取决于网络速度。4.5 验证服务状态启动后使用以下命令检查容器是否全部正常运行# 查看所有容器状态 sudo docker compose ps # 查看某个容器的实时日志例如后端api服务 sudo docker compose logs -f api如果所有容器状态均为running且日志中没有持续报错则说明部署成功。4.6 访问系统在浏览器中访问你服务器IP和配置的前端端口例如http://your-server-ip:3000。你应该能看到系统的登录界面。首次访问通常需要初始化管理员账号请根据页面提示操作。5. 功能测试与效果验证部署成功只是第一步接下来我们需要验证核心功能是否正常工作。我们按照从基础到AI能力的顺序进行测试。5.1 基础功能测试用户与权限管理测试目的验证系统后台管理功能是否正常。操作步骤使用初始化创建的管理员账号登录系统。进入“系统管理”或“管理员后台”。尝试创建新用户、新角色并分配权限。使用新用户登录验证权限是否生效。预期结果能够顺利完成用户、角色、权限的增删改查操作权限控制生效。常见问题如果无法登录或后台页面报错检查后端API容器日志常见原因是数据库连接失败或初始化脚本未执行。5.2 核心业务测试客户与销售机会管理测试目的验证CRM的核心数据管理功能。操作步骤在“客户”模块手动创建一个新客户填写名称、电话、来源等信息。为该客户创建一个“销售机会”填写商机金额、预计成交时间等。在“跟进记录”中添加一条文本跟进记录。尝试导入一个包含客户信息的CSV文件如果系统支持。预期结果客户、商机、跟进记录能正常创建、查看、编辑和删除。数据列表和详情页加载流畅。判断成功数据能持久化保存并在页面正确显示。5.3 AI能力测试知识库问答测试目的验证系统“大脑”是否上线这是AI CRM的关键。前置条件确保AI模型已正确配置无论是云端API还是本地模型。操作步骤进入“知识库”模块。创建一个新的知识库例如“公司产品手册”。上传一份PDF或Word格式的产品文档或直接粘贴文本内容。系统应自动进行文本分割和向量化存储。在知识库的“问答”界面输入一个基于文档内容的问题例如“你们旗舰产品的主要优势是什么”预期结果系统在几秒内返回一个基于上传文档生成的答案答案应相关、准确。判断成功返回的答案并非通用回复而是明显引用了上传文档中的具体信息。失败排查检查向量数据库Milvus容器是否运行正常。查看后端日志确认文档解析和向量化过程是否报错。确认AI模型配置正确且API调用成功查看模型服务或API的调用日志。5.4 AI能力测试智能对话与工作流测试目的验证AI能否在业务场景中交互。操作步骤进入“AI工作流”或“智能助手”模块。尝试运行一个预置的“客户需求分析”工作流。可能需要你输入一段客户咨询的原始文本。观察AI是否能够按步骤执行提取关键信息、匹配产品知识、生成回复建议或总结报告。预期结果AI能够理解输入并按照预定义的逻辑链输出结构化的结果。性能观察记录从发起请求到获得完整响应的耗时。如果使用本地模型同时观察GPU显存占用nvidia-smi和CPU/内存使用率htop。6. 接口 API 与批量任务对于开发者或希望集成到其他系统的用户API接口和批量任务能力至关重要。6.1 API接口调用测试系统后端通常会提供Swagger或OpenAPI文档。访问http://your-server-ip:api-port/docs或http://your-server-ip:api-port/swagger即可查看。测试接口可用性以获取令牌为例curl -X POST “http://your-server-ip:8000/api/auth/login” \ -H “Content-Type: application/json” \ -d ‘{“username”: “admin”, “password”: “your_password”}’预期返回一个包含access_token的JSON对象。调用知识库问答APIimport requests api_base “http://your-server-ip:8000” token “your_access_token_here” headers { “Authorization”: f”Bearer {token}”, “Content-Type”: “application/json” } payload { “knowledge_base_id”: 1, # 你的知识库ID “question”: “你们产品的售后服务政策是怎样的”, “top_k”: 3 # 返回最相关的3个片段 } response requests.post(f”{api_base}/api/knowledge/query”, jsonpayload, headersheaders, timeout30) if response.status_code 200: result response.json() print(“答案”, result.get(‘answer’)) print(“参考来源”, result.get(‘sources’)) else: print(“请求失败”, response.status_code, response.text)6.2 批量任务处理批量功能通常通过后台任务队列如Celery实现。测试方式包括批量导入客户在Web界面找到“批量导入”功能上传一个格式正确的CSV文件观察后台任务执行进度和最终导入数量。批量AI外呼/短信如果集成配置好语音/短信渠道后创建一个包含多个客户电话的任务列表提交后观察任务状态变化。批量报告生成选择一批销售机会触发“批量生成客户分析报告”功能。关键观察点任务队列状态通过管理界面或命令如sudo docker compose exec worker celery -A app.celery status查看Celery Worker是否正常运行。资源占用执行批量任务时监控服务器的CPU、内存和IO使用情况避免资源耗尽影响主服务。错误处理查看任务日志确认是否有单条数据失败导致整个任务中断系统是否具备重试或跳过机制。7. 资源占用与性能观察一个稳定运行的系统需要对资源消耗心中有数。以下是关键的观察指标和方法。7.1 容器资源监控使用Docker自带的命令可以快速查看整体资源占用# 查看所有容器的实时资源使用CPU、内存、网络IO、磁盘IO sudo docker stats # 查看某个特定容器的详细信息包括启动命令、映射端口等 sudo docker inspect container_name_or_id7.2 关键服务资源分析后端API容器这是CPU和内存的消耗大户尤其是在处理AI推理请求时。使用docker stats观察其内存占用正常情况下应在1-4GB之间波动如果持续增长需警惕内存泄漏。向量数据库容器Milvus启动后会占用较多内存用于加载索引。查询时CPU使用率会上升。确保为它分配足够的内存通过docker-compose.yml中的mem_limit设置。MySQL容器常规操作下资源占用平稳。在批量数据导入或复杂报表查询时CPU和IO会升高。AI模型服务容器如果独立部署这是显存消耗的核心。如果本地运行7B模型使用nvidia-smi命令观察显存占用。一个4bit量化的7B模型推理通常需要5-8GB显存。如果使用CPU推理则会对系统内存和CPU造成巨大压力。7.3 性能优化初步思路API响应慢检查后端日志是否有慢查询。优化数据库索引或为频繁访问的数据增加Redis缓存。知识库问答慢向量检索耗时过长可以调整Milvus的索引类型如HNSW和搜索参数nprobe。也可以考虑将向量检索服务与AI推理服务分离部署。内存/显存不足对于API服务可以调整Gunicorn/Uvicorn的worker数量。对于AI模型使用量化程度更高的模型如GPTQ-4bit或升级硬件。在docker-compose.yml中为每个服务设置合理的资源限制deploy.resources.limits防止单个容器拖垮宿主机。磁盘空间不足定期清理日志文件*.log、临时文件以及不需要的旧版本Docker镜像docker image prune -a。8. 常见问题与排查方法部署和运行过程中难免遇到问题下表整理了常见问题的排查思路。问题现象可能原因排查方式解决方案docker compose up -d失败1. 网络问题无法拉取镜像。2.docker-compose.yml语法错误。3. 端口被占用。1. 运行docker compose config检查配置。2. 查看具体错误信息docker compose logs。3.netstat -tunlp | grep 端口号。1. 配置国内镜像加速器。2. 修正yml文件缩进或格式。3. 修改.env中的端口号或停止占用端口的进程。前端页面能打开但登录后白屏或接口报错1. 后端API服务未启动或崩溃。2. 前端配置的API地址错误。3. 跨域问题。1.docker compose ps查看api容器状态。2.docker compose logs api查看后端日志。3. 浏览器F12打开开发者工具查看Console和Network标签页报错。1. 重启api容器docker compose restart api。2. 检查前端环境变量VITE_API_BASE_URL是否正确指向后端。3. 在后端CORS配置中添加前端地址。知识库上传文档后问答无结果1. 向量数据库连接失败。2. 文档解析失败格式不支持或编码问题。3. AI模型未配置或调用失败。1. 检查milvus容器状态和日志。2. 查看后端日志中关于文档解析和向量化的部分。3. 测试AI模型接口是否通curl -X POST 模型API地址/v1/chat/completions ...。1. 确保milvus服务健康集合collection已创建。2. 尝试上传纯文本txt文件测试。3. 检查.env中AI模型相关配置并确认API密钥有效、网络可达。系统运行一段时间后变卡或崩溃1. 内存泄漏。2. 磁盘空间满。3. 数据库连接池耗尽。1.docker stats观察容器内存增长趋势。2.df -h检查磁盘使用率。3. 查看数据库日志和连接数。1. 定期重启有问题的容器或联系开发者排查代码。2. 清理日志、临时文件和Docker缓存。3. 优化数据库配置增加max_connections并在应用层使用连接池。批量任务卡在“处理中”状态1. Celery Worker进程挂掉。2. 消息队列Redis/RabbitMQ问题。3. 任务本身代码有异常。1.docker compose exec worker celery -A app.celery status。2. 检查redis容器日志。3. 查看Worker的日志docker compose logs worker。1. 重启worker容器docker compose restart worker。2. 确保redis配置正确且内存充足。3. 根据Worker日志中的异常堆栈修复代码或配置。本地模型推理速度极慢1. 使用CPU推理。2. 模型未量化显存不足导致使用系统内存交换。3. 推理参数如max_length设置过高。1.nvidia-smi确认GPU是否被使用。2. 观察系统内存交换情况free -h和si/so使用vmstat 1。1. 确认CUDA和显卡驱动已正确安装并在模型加载代码中指定了GPU。2. 换用量化版本模型如GGUF-Q4_K_M。3. 在API调用时降低生成token的最大数量。9. 最佳实践与使用建议基于上述部署和测试经验总结出以下几点建议可以帮助你更稳定、高效地使用“悟空 AICRM”。部署环境隔离始终在独立的服务器或虚拟机中部署生产环境避免与其他应用争抢资源。使用Docker Compose的profiles功能来区分开发、测试和生产配置。配置版本化管理将修改后的docker-compose.yml和.env文件纳入Git版本控制注意.env中的密码需用.env.example模板管理真实密码通过CI/CD或运维工具注入。这保证了环境的一致性便于回滚。数据持久化与备份在docker-compose.yml中务必为MySQL、Milvus等有状态服务配置卷Volumes映射将数据保存在宿主机目录。并建立定期的数据库备份机制例如通过cron定时执行mysqldump。AI模型策略在生产环境中优先考虑使用成熟的云端大模型API如GPT-4、DeepSeek等以获得最佳效果和稳定性。本地模型更适合对数据隐私有极端要求、且拥有强大GPU运维能力的场景。可以采用混合模式关键业务用云端API内部辅助分析用本地轻量模型。安全加固修改所有默认密码数据库、Redis、管理后台。通过Nginx反向代理对外暴露服务并配置SSL证书HTTPS。在Nginx或云防火墙层面限制API端口的访问IP仅允许前端服务器或内部网络调用。定期更新Docker镜像至安全版本。监控与告警至少部署基础的监控如使用cAdvisorPrometheusGrafana监控容器资源或使用云服务商的监控服务。设置CPU、内存、磁盘使用率的告警阈值。合规使用在系统中启用操作日志审计功能。使用AI生成客户沟通内容时务必加入人工审核环节。处理客户个人信息前确保已获得合法授权。10. 总结与下一步通过这篇教程我们完成了“悟空 AICRM”从环境准备、Docker部署、功能验证到问题排查的完整闭环。这个项目的最大优势在于它提供了一个一体化、可私有化部署的AICRM试验场。你能在几天内就在自己的服务器上搭建起一个具备智能对话、知识管理和工作流自动化能力的业务系统。对于初次接触的团队建议按以下路径推进第一步本周按照本文指南在测试环境成功部署并跑通所有基础功能。重点验证知识库问答和AI工作流这是区别于传统CRM的核心。第二步下个月尝试接入真实的业务数据脱敏后让销售或客服团队试用。收集关于界面、流程、AI效果的实际反馈。第三步长期基于反馈进行定制化开发或将其作为灵感来源自研更适合自身业务逻辑的系统。最容易踩的坑集中在初始配置环境变量、端口、模型API地址和资源不足显存、内存两方面。部署时请耐心对照日志一步步排查。这套系统的潜力在于它不仅仅是一个软件更是一个框架。当你熟悉了它的数据模型和API后可以很方便地将它的AI能力如知识库检索、文本生成抽离出来嵌入到你已有的OA、ERP或内部平台中实现渐进式的智能化改造。
悟空AICRM：基于Docker的AI客户关系管理系统私有化部署指南
发布时间：2026/7/27 8:06:48
这次我们来看一个名为“悟空 AICRM”的项目它本质上是一个集成了AI能力的客户关系管理系统。对于需要将大模型智能对话、内容生成等能力融入销售、客服、市场等业务流程的团队来说本地部署一个这样的系统意味着数据安全可控和深度定制化。本文将带你完成从零开始的完整Docker化部署重点解决“能不能跑起来”和“怎么用起来”的问题。项目的核心价值在于它试图将AI Agent、知识库、工作流等前沿概念封装成一个开箱即用的业务系统。我们最关心的是它的部署门槛是否需要高性能GPU依赖是否复杂本文的实操将基于Docker容器技术这能极大简化环境配置的复杂度。无论你是想评估这套系统还是计划将其用于内部测试或小规模应用跟着步骤走一遍就能得到明确的答案。1. 核心能力速览在动手部署之前我们先快速了解“悟空 AICRM”的核心特性和部署要求这有助于判断它是否适合你的当前环境。能力项说明项目类型AI增强型客户关系管理系统CRM核心功能智能客户对话、销售流程自动化、知识库问答、数据分析看板、AI工作流引擎部署方式推荐Docker Compose一键拉起所有服务Web前端、后端API、数据库、向量数据库等硬件门槛中等。CPU推理模式下对GPU无硬性要求但涉及大模型推理时GPU会显著提升体验。内存建议8GB以上。显存占用非必须取决于模型。如果使用本地部署的轻量化大模型如Qwen2.5-7B-Instruct的4bit量化版约需6-8GB显存。系统也支持调用云端API如OpenAI、DeepSeek此时对本地显卡无要求。数据存储使用MySQL作为业务数据库Milvus/Weaviate等作为向量数据库用于知识库。需预留至少10GB磁盘空间。是否支持API是。系统提供完整的RESTful API可供其他业务系统集成调用。是否支持批量任务是。支持批量导入客户数据、批量执行AI外呼任务需配置语音接口、批量生成营销内容等。适合场景企业内网安全部署、AICRM方案技术验证、对数据隐私要求高的销售/客服团队、开发者进行二次开发。从表格可以看出该项目通过Docker实现了复杂依赖的封装部署的核心难点从“环境配置”转移到了“网络编排与资源分配”。只要宿主机资源足够部署过程是标准化且可重复的。2. 适用场景与使用边界在投入时间部署之前明确它能做什么、不能做什么至关重要。它非常适合以下场景数据敏感型企业的内部CRM所有数据客户信息、对话记录、知识库都留在自有服务器符合金融、医疗、法律等行业的合规要求。AI与业务结合的探索与验证团队希望在一个现成的系统中快速体验AI如何改造客户跟进、智能问答、报告生成等具体场景而无需从零开发。定制化AI工作流的开发基础系统提供了工作流引擎开发者可以基于此构建复杂的、符合自身业务逻辑的自动化流程例如“客户询价 - AI分析历史订单 - 自动生成报价单 - 发送邮件”。替代部分传统CRM的自动化功能利用AI自动总结通话记录、分类客户意向、生成下周跟进计划等提升销售人效。它的使用边界和注意事项并非“开箱即用”的SaaS部署后需要进行大量的初始化配置包括组织架构、角色权限、业务流程定义、AI模型接入等有一定学习成本。AI能力依赖模型或API系统的智能程度取决于背后接入的大模型。使用免费开源模型效果可能不及GPT-4等商用模型使用云端API则会产生费用并涉及网络访问。性能与规模相关当客户数据量达到百万级或并发用户数很高时需要对数据库、向量数据库和缓存进行性能调优默认的Docker Compose配置可能无法支撑。合规与授权如果使用该系统处理真实的客户个人信息必须确保符合《个人信息保护法》等相关法规。使用AI生成内容时需对生成结果进行人工审核避免产生错误或有害信息。3. 环境准备与前置条件部署“悟空 AICRM”需要一个干净的Linux服务器环境。以下是在开始安装Docker和部署应用之前必须完成的准备工作。3.1 操作系统要求推荐Ubuntu 22.04 LTS 或 CentOS 8/Rocky Linux 8。本文演示以Ubuntu 22.04为例。备选其他主流Linux发行版也可但部分命令和包管理工具需要调整。3.2 硬件资源检查请通过SSH连接到你的服务器并执行以下命令进行基础检查# 1. 检查系统版本 lsb_release -a # 2. 检查CPU和内存 free -h lscpu | grep -E “(Model name|CPU\(s\))” # 3. 检查磁盘空间确保根目录或目标数据盘有足够空间 df -h # 4. 检查GPU如果有并计划用于本地模型推理 lspci | grep -i nvidia nvidia-smi # 如果已安装驱动此命令可查看显卡详情最低配置建议2核CPU8GB内存50GB可用磁盘空间。推荐配置4核CPU16GB内存100GB SSD磁盘空间。如果计划在本地运行7B参数以上的大模型则需要一张至少8GB显存的NVIDIA显卡。3.3 网络与安全组配置确保服务器的以下端口未被占用且已在防火墙或云服务商安全组中放行80/443用于Web前端访问可通过Nginx反代。3306MySQL数据库端口强烈建议仅限内网访问或修改为其他端口。19530Milvus向量数据库端口默认。7860/8000后端API服务常用端口具体以项目docker-compose.yml为准。22SSH管理端口。你可以使用netstat -tunlp命令查看当前端口占用情况。4. 安装部署与启动方式一切就绪我们开始核心的部署流程。全程使用Docker和Docker Compose这是最简洁、依赖冲突最少的方式。4.1 安装Docker与Docker Compose如果你的系统尚未安装请执行以下命令# 更新系统包索引 sudo apt-get update # 安装必要的依赖包 sudo apt-get install -y ca-certificates curl gnupg lsb-release # 添加Docker官方GPG密钥 sudo mkdir -p /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gosu tee /etc/apt/keyrings/docker.asc /dev/null # 设置Docker稳定版仓库 echo \ “deb [arch$(dpkg --print-architecture) signed-by/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \ $(lsb_release -cs) stable” | sudo tee /etc/apt/sources.list.d/docker.list /dev/null # 安装Docker Engine sudo apt-get update sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin # 验证Docker安装 sudo docker run hello-world # 将当前用户加入docker组避免每次使用sudo操作后需退出SSH重新登录生效 sudo usermod -aG docker $USER4.2 获取“悟空 AICRM”部署文件通常开源项目会提供标准的docker-compose.yml和环境变量配置文件.env。你需要从项目的官方仓库如GitHub获取它们。# 创建一个专用的项目目录 mkdir -p ~/wukong-aicrm cd ~/wukong-aicrm # 假设项目仓库地址请替换为实际地址 # 方式一直接下载部署文件如果项目提供 wget -O docker-compose.yml https://raw.githubusercontent.com/xxx/wukong-aicrm/main/docker-compose.yml wget -O .env.example https://raw.githubusercontent.com/xxx/wukong-aicrm/main/.env.example # 方式二克隆整个仓库如果需要进行代码级定制 # git clone https://github.com/xxx/wukong-aicrm.git . # cd docker # 复制环境变量模板并配置 cp .env.example .env4.3 关键配置修改编辑.env文件这是整个系统的核心配置。你需要重点关注以下几项# 使用文本编辑器如nano或vim打开.env文件 nano .env数据库密码修改MYSQL_ROOT_PASSWORD、MYSQL_PASSWORD为强密码。服务端口检查WEB_PORT前端、API_PORT后端等确保不与系统已有端口冲突。AI模型配置如果使用云端API如OpenAI需要填写OPENAI_API_KEY、OPENAI_BASE_URL若使用代理。如果使用本地模型需要配置LOCAL_LLM_MODEL模型名称或路径和LOCAL_LLM_API_BASE指向本地Ollama、OpenAI-format API等服务的地址。文件存储路径确认VOLUME_PATH指向一个足够大的磁盘分区。域名/访问地址设置DOMAIN或APP_URL用于系统内部链接生成。4.4 启动所有服务配置完成后使用Docker Compose一键启动所有容器。# 在包含docker-compose.yml的目录下执行 # -d 参数表示后台运行 sudo docker compose up -d这个命令会依次拉取如果本地没有并启动MySQL、Redis、Milvus、后端API、前端Web等多个容器。首次执行耗时较长取决于网络速度。4.5 验证服务状态启动后使用以下命令检查容器是否全部正常运行# 查看所有容器状态 sudo docker compose ps # 查看某个容器的实时日志例如后端api服务 sudo docker compose logs -f api如果所有容器状态均为running且日志中没有持续报错则说明部署成功。4.6 访问系统在浏览器中访问你服务器IP和配置的前端端口例如http://your-server-ip:3000。你应该能看到系统的登录界面。首次访问通常需要初始化管理员账号请根据页面提示操作。5. 功能测试与效果验证部署成功只是第一步接下来我们需要验证核心功能是否正常工作。我们按照从基础到AI能力的顺序进行测试。5.1 基础功能测试用户与权限管理测试目的验证系统后台管理功能是否正常。操作步骤使用初始化创建的管理员账号登录系统。进入“系统管理”或“管理员后台”。尝试创建新用户、新角色并分配权限。使用新用户登录验证权限是否生效。预期结果能够顺利完成用户、角色、权限的增删改查操作权限控制生效。常见问题如果无法登录或后台页面报错检查后端API容器日志常见原因是数据库连接失败或初始化脚本未执行。5.2 核心业务测试客户与销售机会管理测试目的验证CRM的核心数据管理功能。操作步骤在“客户”模块手动创建一个新客户填写名称、电话、来源等信息。为该客户创建一个“销售机会”填写商机金额、预计成交时间等。在“跟进记录”中添加一条文本跟进记录。尝试导入一个包含客户信息的CSV文件如果系统支持。预期结果客户、商机、跟进记录能正常创建、查看、编辑和删除。数据列表和详情页加载流畅。判断成功数据能持久化保存并在页面正确显示。5.3 AI能力测试知识库问答测试目的验证系统“大脑”是否上线这是AI CRM的关键。前置条件确保AI模型已正确配置无论是云端API还是本地模型。操作步骤进入“知识库”模块。创建一个新的知识库例如“公司产品手册”。上传一份PDF或Word格式的产品文档或直接粘贴文本内容。系统应自动进行文本分割和向量化存储。在知识库的“问答”界面输入一个基于文档内容的问题例如“你们旗舰产品的主要优势是什么”预期结果系统在几秒内返回一个基于上传文档生成的答案答案应相关、准确。判断成功返回的答案并非通用回复而是明显引用了上传文档中的具体信息。失败排查检查向量数据库Milvus容器是否运行正常。查看后端日志确认文档解析和向量化过程是否报错。确认AI模型配置正确且API调用成功查看模型服务或API的调用日志。5.4 AI能力测试智能对话与工作流测试目的验证AI能否在业务场景中交互。操作步骤进入“AI工作流”或“智能助手”模块。尝试运行一个预置的“客户需求分析”工作流。可能需要你输入一段客户咨询的原始文本。观察AI是否能够按步骤执行提取关键信息、匹配产品知识、生成回复建议或总结报告。预期结果AI能够理解输入并按照预定义的逻辑链输出结构化的结果。性能观察记录从发起请求到获得完整响应的耗时。如果使用本地模型同时观察GPU显存占用nvidia-smi和CPU/内存使用率htop。6. 接口 API 与批量任务对于开发者或希望集成到其他系统的用户API接口和批量任务能力至关重要。6.1 API接口调用测试系统后端通常会提供Swagger或OpenAPI文档。访问http://your-server-ip:api-port/docs或http://your-server-ip:api-port/swagger即可查看。测试接口可用性以获取令牌为例curl -X POST “http://your-server-ip:8000/api/auth/login” \ -H “Content-Type: application/json” \ -d ‘{“username”: “admin”, “password”: “your_password”}’预期返回一个包含access_token的JSON对象。调用知识库问答APIimport requests api_base “http://your-server-ip:8000” token “your_access_token_here” headers { “Authorization”: f”Bearer {token}”, “Content-Type”: “application/json” } payload { “knowledge_base_id”: 1, # 你的知识库ID “question”: “你们产品的售后服务政策是怎样的”, “top_k”: 3 # 返回最相关的3个片段 } response requests.post(f”{api_base}/api/knowledge/query”, jsonpayload, headersheaders, timeout30) if response.status_code 200: result response.json() print(“答案”, result.get(‘answer’)) print(“参考来源”, result.get(‘sources’)) else: print(“请求失败”, response.status_code, response.text)6.2 批量任务处理批量功能通常通过后台任务队列如Celery实现。测试方式包括批量导入客户在Web界面找到“批量导入”功能上传一个格式正确的CSV文件观察后台任务执行进度和最终导入数量。批量AI外呼/短信如果集成配置好语音/短信渠道后创建一个包含多个客户电话的任务列表提交后观察任务状态变化。批量报告生成选择一批销售机会触发“批量生成客户分析报告”功能。关键观察点任务队列状态通过管理界面或命令如sudo docker compose exec worker celery -A app.celery status查看Celery Worker是否正常运行。资源占用执行批量任务时监控服务器的CPU、内存和IO使用情况避免资源耗尽影响主服务。错误处理查看任务日志确认是否有单条数据失败导致整个任务中断系统是否具备重试或跳过机制。7. 资源占用与性能观察一个稳定运行的系统需要对资源消耗心中有数。以下是关键的观察指标和方法。7.1 容器资源监控使用Docker自带的命令可以快速查看整体资源占用# 查看所有容器的实时资源使用CPU、内存、网络IO、磁盘IO sudo docker stats # 查看某个特定容器的详细信息包括启动命令、映射端口等 sudo docker inspect container_name_or_id7.2 关键服务资源分析后端API容器这是CPU和内存的消耗大户尤其是在处理AI推理请求时。使用docker stats观察其内存占用正常情况下应在1-4GB之间波动如果持续增长需警惕内存泄漏。向量数据库容器Milvus启动后会占用较多内存用于加载索引。查询时CPU使用率会上升。确保为它分配足够的内存通过docker-compose.yml中的mem_limit设置。MySQL容器常规操作下资源占用平稳。在批量数据导入或复杂报表查询时CPU和IO会升高。AI模型服务容器如果独立部署这是显存消耗的核心。如果本地运行7B模型使用nvidia-smi命令观察显存占用。一个4bit量化的7B模型推理通常需要5-8GB显存。如果使用CPU推理则会对系统内存和CPU造成巨大压力。7.3 性能优化初步思路API响应慢检查后端日志是否有慢查询。优化数据库索引或为频繁访问的数据增加Redis缓存。知识库问答慢向量检索耗时过长可以调整Milvus的索引类型如HNSW和搜索参数nprobe。也可以考虑将向量检索服务与AI推理服务分离部署。内存/显存不足对于API服务可以调整Gunicorn/Uvicorn的worker数量。对于AI模型使用量化程度更高的模型如GPTQ-4bit或升级硬件。在docker-compose.yml中为每个服务设置合理的资源限制deploy.resources.limits防止单个容器拖垮宿主机。磁盘空间不足定期清理日志文件*.log、临时文件以及不需要的旧版本Docker镜像docker image prune -a。8. 常见问题与排查方法部署和运行过程中难免遇到问题下表整理了常见问题的排查思路。问题现象可能原因排查方式解决方案docker compose up -d失败1. 网络问题无法拉取镜像。2.docker-compose.yml语法错误。3. 端口被占用。1. 运行docker compose config检查配置。2. 查看具体错误信息docker compose logs。3.netstat -tunlp | grep 端口号。1. 配置国内镜像加速器。2. 修正yml文件缩进或格式。3. 修改.env中的端口号或停止占用端口的进程。前端页面能打开但登录后白屏或接口报错1. 后端API服务未启动或崩溃。2. 前端配置的API地址错误。3. 跨域问题。1.docker compose ps查看api容器状态。2.docker compose logs api查看后端日志。3. 浏览器F12打开开发者工具查看Console和Network标签页报错。1. 重启api容器docker compose restart api。2. 检查前端环境变量VITE_API_BASE_URL是否正确指向后端。3. 在后端CORS配置中添加前端地址。知识库上传文档后问答无结果1. 向量数据库连接失败。2. 文档解析失败格式不支持或编码问题。3. AI模型未配置或调用失败。1. 检查milvus容器状态和日志。2. 查看后端日志中关于文档解析和向量化的部分。3. 测试AI模型接口是否通curl -X POST 模型API地址/v1/chat/completions ...。1. 确保milvus服务健康集合collection已创建。2. 尝试上传纯文本txt文件测试。3. 检查.env中AI模型相关配置并确认API密钥有效、网络可达。系统运行一段时间后变卡或崩溃1. 内存泄漏。2. 磁盘空间满。3. 数据库连接池耗尽。1.docker stats观察容器内存增长趋势。2.df -h检查磁盘使用率。3. 查看数据库日志和连接数。1. 定期重启有问题的容器或联系开发者排查代码。2. 清理日志、临时文件和Docker缓存。3. 优化数据库配置增加max_connections并在应用层使用连接池。批量任务卡在“处理中”状态1. Celery Worker进程挂掉。2. 消息队列Redis/RabbitMQ问题。3. 任务本身代码有异常。1.docker compose exec worker celery -A app.celery status。2. 检查redis容器日志。3. 查看Worker的日志docker compose logs worker。1. 重启worker容器docker compose restart worker。2. 确保redis配置正确且内存充足。3. 根据Worker日志中的异常堆栈修复代码或配置。本地模型推理速度极慢1. 使用CPU推理。2. 模型未量化显存不足导致使用系统内存交换。3. 推理参数如max_length设置过高。1.nvidia-smi确认GPU是否被使用。2. 观察系统内存交换情况free -h和si/so使用vmstat 1。1. 确认CUDA和显卡驱动已正确安装并在模型加载代码中指定了GPU。2. 换用量化版本模型如GGUF-Q4_K_M。3. 在API调用时降低生成token的最大数量。9. 最佳实践与使用建议基于上述部署和测试经验总结出以下几点建议可以帮助你更稳定、高效地使用“悟空 AICRM”。部署环境隔离始终在独立的服务器或虚拟机中部署生产环境避免与其他应用争抢资源。使用Docker Compose的profiles功能来区分开发、测试和生产配置。配置版本化管理将修改后的docker-compose.yml和.env文件纳入Git版本控制注意.env中的密码需用.env.example模板管理真实密码通过CI/CD或运维工具注入。这保证了环境的一致性便于回滚。数据持久化与备份在docker-compose.yml中务必为MySQL、Milvus等有状态服务配置卷Volumes映射将数据保存在宿主机目录。并建立定期的数据库备份机制例如通过cron定时执行mysqldump。AI模型策略在生产环境中优先考虑使用成熟的云端大模型API如GPT-4、DeepSeek等以获得最佳效果和稳定性。本地模型更适合对数据隐私有极端要求、且拥有强大GPU运维能力的场景。可以采用混合模式关键业务用云端API内部辅助分析用本地轻量模型。安全加固修改所有默认密码数据库、Redis、管理后台。通过Nginx反向代理对外暴露服务并配置SSL证书HTTPS。在Nginx或云防火墙层面限制API端口的访问IP仅允许前端服务器或内部网络调用。定期更新Docker镜像至安全版本。监控与告警至少部署基础的监控如使用cAdvisorPrometheusGrafana监控容器资源或使用云服务商的监控服务。设置CPU、内存、磁盘使用率的告警阈值。合规使用在系统中启用操作日志审计功能。使用AI生成客户沟通内容时务必加入人工审核环节。处理客户个人信息前确保已获得合法授权。10. 总结与下一步通过这篇教程我们完成了“悟空 AICRM”从环境准备、Docker部署、功能验证到问题排查的完整闭环。这个项目的最大优势在于它提供了一个一体化、可私有化部署的AICRM试验场。你能在几天内就在自己的服务器上搭建起一个具备智能对话、知识管理和工作流自动化能力的业务系统。对于初次接触的团队建议按以下路径推进第一步本周按照本文指南在测试环境成功部署并跑通所有基础功能。重点验证知识库问答和AI工作流这是区别于传统CRM的核心。第二步下个月尝试接入真实的业务数据脱敏后让销售或客服团队试用。收集关于界面、流程、AI效果的实际反馈。第三步长期基于反馈进行定制化开发或将其作为灵感来源自研更适合自身业务逻辑的系统。最容易踩的坑集中在初始配置环境变量、端口、模型API地址和资源不足显存、内存两方面。部署时请耐心对照日志一步步排查。这套系统的潜力在于它不仅仅是一个软件更是一个框架。当你熟悉了它的数据模型和API后可以很方便地将它的AI能力如知识库检索、文本生成抽离出来嵌入到你已有的OA、ERP或内部平台中实现渐进式的智能化改造。
