这次我们来看一个企业级开源项目Wukong AICRM。它是一个基于AI的客户关系管理系统核心目标是通过智能化工具提升销售、市场和客服团队的效率。对于技术团队而言它的价值在于提供了开箱即用的Docker化部署方案让企业能够快速搭建一套私有、可控的AI CRM平台无需从零开始处理复杂的微服务依赖。本文将带你完成从零到一的Wukong AICRM Docker部署全流程。重点不是概念而是实操你的机器需要什么配置Docker镜像怎么拉取环境变量如何配置服务启动后如何访问和验证我们会一步步拆解并提供完整的命令和配置示例。无论你是想评估这套系统还是计划在生产环境部署这篇文章都能提供直接的参考。1. 核心能力速览在开始动手之前先快速了解Wukong AICRM的核心特性和部署要求判断它是否适合你的场景。能力项说明项目类型开源AI客户关系管理系统CRM核心功能销售自动化、客户智能分析、营销活动管理、客服工单、AI助手如线索评分、对话摘要部署方式Docker容器化为主要推荐方式整合了前后端及依赖服务硬件门槛中等。建议至少4核CPU、8GB内存、50GB磁盘空间。AI功能若涉及本地模型推理对GPU有额外要求。显存占用取决于启用的AI模块。如果仅使用基础CRM功能或调用云端AI API则无需GPU。如需本地运行大模型则需按模型规格准备显存。启动方式通过docker-compose一键启动所有服务数据库、缓存、后端、前端等。是否支持API是。提供完整的RESTful API供第三方系统集成。是否支持批量任务是。系统内置任务队列支持批量导入客户、执行营销活动等。数据存储通常使用PostgreSQL作为主数据库Redis作为缓存和消息队列。适合场景中小企业搭建私有CRM、开发团队进行二次开发、需要AI能力集成的业务场景。2. 适用场景与使用边界Wukong AICRM适合哪些团队又能解决什么问题了解这些能帮助你做出更好的技术选型。适合谁用中小企业技术负责人希望快速部署一套功能全面、带AI能力的CRM避免SaaS产品的数据安全和定制化限制。开发者/架构师需要研究或借鉴一个现代化的、微服务架构的CRM系统实现。销售/市场运营团队有明确的流程管理、客户分析和自动化需求且公司支持私有化部署。能解决什么问题客户数据集中管理统一存储客户联系人、沟通记录、交易历史。销售流程可视化从线索到回款的全流程跟踪与管理。AI赋能效率利用AI进行线索优先级排序、自动生成沟通摘要、智能回复建议等。营销自动化创建并执行邮件、短信等营销活动自动跟踪效果。服务与支持管理客户服务请求和工单。使用边界与注意事项非开箱即用型SaaS需要一定的服务器运维和Docker知识。AI功能依赖配置系统内的AI能力可能需要对接OpenAI API或部署本地模型需要额外配置和成本。性能与规模单机Docker部署适合中小规模团队和测试环境。大规模生产环境需要考虑分布式部署、数据库分库分表、负载均衡等高级架构。合规与数据安全作为私有化部署数据安全责任在部署方。需确保服务器安全、数据库加密、访问控制等措施到位。处理客户个人信息必须遵守相关法律法规。3. 环境准备与前置条件部署前请确保你的服务器或本地开发环境满足以下条件。3.1 操作系统推荐Linux发行版如 Ubuntu 20.04/22.04 LTS, CentOS 7/8。生产环境首选。也可用Windows 10/11 Pro/Enterprise/Education需安装WSL 2或Docker Desktop for Windows。macOS需安装Docker Desktop。不推荐Windows家庭版可能无法启用Hyper-V导致Docker Desktop安装困难。3.2 Docker与Docker Compose这是最核心的依赖。Wukong AICRM通常使用docker-compose.yml来编排多个容器。Docker Engine版本 20.10.0 或更高。Docker Compose版本 v2.0.0 或更高。目前推荐使用Docker Desktop内置的Compose V2或独立安装的docker-compose-plugin。3.3 硬件资源CPU至少2核建议4核或以上。内存至少4GB建议8GB或以上。如果启用内存密集型AI服务需要更多。磁盘至少20GB可用空间用于存放Docker镜像、数据库数据、日志文件等。建议预留50GB。网络服务器需要能访问互联网以下载Docker镜像。如果部署在内网需提前配置内部镜像仓库。3.4 端口占用检查默认的docker-compose.yml可能会映射以下端口到宿主机请确保它们未被占用80或8080前端Web界面。8000或3000后端API服务。5432PostgreSQL数据库通常不直接暴露但需确认容器内部端口。6379Redis服务通常不直接暴露。 使用以下命令检查端口占用# Linux/macOS sudo netstat -tulpn | grep :80 # 或使用 lsof sudo lsof -i:80 # Windows (在PowerShell中) Get-NetTCPConnection -LocalPort 804. 安装部署与启动方式我们将以最常见的Linux服务器Ubuntu为例演示完整的安装流程。其他系统可参考Docker官方安装文档。4.1 步骤一安装Docker与Docker Compose首先在Ubuntu系统上安装Docker。# 1. 更新apt包索引并安装依赖 sudo apt-get update sudo apt-get install -y ca-certificates curl gnupg lsb-release # 2. 添加Docker官方GPG密钥 sudo mkdir -p /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg # 3. 设置Docker稳定版仓库 echo \ deb [arch$(dpkg --print-architecture) signed-by/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \ $(lsb_release -cs) stable | sudo tee /etc/apt/sources.list.d/docker.list /dev/null # 4. 安装Docker Engine, containerd 和 Docker Compose Plugin sudo apt-get update sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin # 5. 验证安装 sudo docker --version sudo docker compose version # 注意是 docker compose不是 docker-compose4.2 步骤二获取Wukong AICRM部署文件通常开源项目会提供一个包含docker-compose.yml和环境配置文件的代码仓库。你需要克隆或下载它。# 假设项目仓库地址为 https://github.com/xxx/wukong-aicrm-docker # 请替换为实际仓库地址 git clone https://github.com/xxx/wukong-aicrm-docker.git cd wukong-aicrm-docker # 查看目录结构通常包含以下关键文件 ls -la # docker-compose.yml # Docker服务编排文件 # .env.example # 环境变量配置示例 # README.md # 说明文档4.3 步骤三配置环境变量大多数配置通过环境变量文件.env管理。复制示例文件并修改关键配置。# 复制环境变量示例文件 cp .env.example .env # 编辑 .env 文件配置数据库密码、密钥、域名等 nano .env # 或使用 vim, cat 等编辑器一个典型的.env文件需要修改的内容如下具体变量名请以项目实际文件为准# 数据库配置 POSTGRES_DBwukong_crm POSTGRES_USERwukong_user POSTGRES_PASSWORDYourStrongPassword123! # 务必修改为强密码 POSTGRES_HOSTpostgres POSTGRES_PORT5432 # Redis配置 REDIS_HOSTredis REDIS_PORT6379 REDIS_PASSWORDYourRedisPassword # 可选但建议设置 # 后端应用配置 SECRET_KEYYourVeryLongAndSecureSecretKeyForDjango # 务必修改用于加密会话等 DEBUGFalse # 生产环境务必设为 False ALLOWED_HOSTSyour-server-ip,localhost,127.0.0.1 # 设置你的服务器IP或域名 # 前端访问地址 FRONTEND_URLhttp://your-server-ip:80 # 或你的域名 # AI服务配置如果需要 OPENAI_API_KEYsk-xxx # 如果使用OpenAI在此填入API Key # 或者本地模型配置 LOCAL_LLM_HOSTllm-service LOCAL_LLM_PORT50004.4 步骤四启动所有服务使用docker compose命令启动定义在docker-compose.yml中的所有服务。# 在包含 docker-compose.yml 的目录下执行 # -d 参数表示在后台运行 sudo docker compose up -d这个命令会执行以下操作根据docker-compose.yml拉取所需的镜像PostgreSQL, Redis, 后端应用前端应用等。创建独立的Docker网络使容器间可以通信。按依赖顺序启动容器先启动数据库和Redis再启动应用。将容器内的服务端口映射到宿主机。4.5 步骤五查看服务状态与日志启动后检查容器是否全部正常运行。# 查看所有容器状态 sudo docker compose ps # 预期输出类似 # NAME COMMAND SERVICE STATUS PORTS # wukong-postgres docker-entrypoint.s… postgres running 5432/tcp # wukong-redis docker-entrypoint.s… redis running 6379/tcp # wukong-backend python manage.py ru… backend running 0.0.0.0:8000-8000/tcp # wukong-frontend nginx -g daemon of… frontend running 0.0.0.0:80-80/tcp # 如果某个容器状态不是 running查看其日志 sudo docker compose logs [service-name] # 例如sudo docker compose logs backend sudo docker compose logs --follow [service-name] # 持续跟踪日志5. 功能测试与效果验证服务启动成功后我们需要验证系统是否正常工作。按照从外到内、从基础到高级的顺序进行测试。5.1 测试一前端Web界面访问这是最直接的验证方式。打开浏览器访问你配置的地址。如果FRONTEND_URL配置为http://your-server-ip:80则直接在浏览器地址栏输入服务器IP。如果部署在本地开发机可以访问http://localhost。预期结果加载出Wukong AICRM的登录或注册页面。成功标准页面正常显示无502 Bad Gateway、404 Not Found或连接超时错误。失败排查检查容器状态sudo docker compose ps确保frontend和backend服务都是running。检查端口映射sudo docker compose port frontend 80确认映射是否正确。查看前端容器日志sudo docker compose logs frontend。查看后端容器日志sudo docker compose logs backend常见错误包括数据库连接失败、环境变量未正确加载等。5.2 测试二后端API健康检查通过调用后端API的健康检查端点确认后端服务及数据库连接正常。# 使用 curl 测试后端API假设后端映射到宿主机的8000端口 curl http://localhost:8000/api/health/ # 或者 curl http://your-server-ip:8000/api/health/预期结果返回一个JSON响应如{status: ok, database: connected}。成功标准HTTP状态码为200且返回信息显示服务健康、数据库连接正常。失败排查查看后端日志sudo docker compose logs backend重点关注启动时是否有数据库连接错误、依赖缺失等。检查数据库容器sudo docker compose exec postgres psql -U wukong_user -d wukong_crm -c \l验证数据库是否可连接。5.3 测试三核心业务流程验证登录系统通常首次访问需要注册一个管理员账号进行以下操作客户管理创建一个测试客户填写名称、电话、邮箱等信息。销售线索新建一条销售线索并将其分配给一个模拟的销售员。活动记录为该客户添加一条沟通记录。AI功能如果已配置尝试使用线索智能评分、生成沟通摘要等功能。预期结果各项操作能成功完成数据能正确保存并在列表中显示。成功标准界面交互流畅无报错数据持久化。失败排查操作失败时查看浏览器开发者工具F12中的“网络(Network)”标签看API请求是否返回错误如4xx, 5xx。根据错误信息结合后端日志定位问题。6. 接口API与批量任务Wukong AICRM作为现代系统提供API供外部集成并内置了处理批量任务的机制。6.1 API接口调用示例假设系统提供了创建客户的API端点。以下是一个使用Pythonrequests库调用该API的示例。import requests import json # 配置API基础地址和认证信息以Bearer Token为例 BASE_URL http://your-server-ip:8000/api API_TOKEN your_generated_api_token_here # 需要在系统内生成 headers { Authorization: fBearer {API_TOKEN}, Content-Type: application/json } # 1. 创建客户 create_customer_url f{BASE_URL}/customers/ customer_data { name: 测试科技有限公司, phone: 13800138000, email: contacttest.com, source: 官网, industry: 科技 } response requests.post(create_customer_url, headersheaders, jsoncustomer_data, timeout30) if response.status_code 201: print(客户创建成功) new_customer response.json() customer_id new_customer.get(id) print(f客户ID: {customer_id}) else: print(f请求失败状态码{response.status_code}) print(response.text) # 2. 批量查询客户示例 list_customers_url f{BASE_URL}/customers/?page1page_size20 response requests.get(list_customers_url, headersheaders, timeout30) if response.status_code 200: customers response.json().get(results, []) print(f获取到 {len(customers)} 条客户记录)关键点认证首先需要在Wukong AICRM后台创建API令牌Token。端点路径具体API路径请查阅项目的API文档通常是Swagger UI访问http://your-server-ip:8000/api/docs/或类似地址。错误处理务必检查HTTP状态码并对错误响应进行适当处理。6.2 批量任务处理系统内部的批量操作如批量导入客户、发送营销邮件通常通过消息队列如Redis和后台工作进程Celery实现。如何触发在Web界面可能有一个“批量导入”按钮上传CSV文件后后端会创建一个异步任务。如何监控# 查看后台工作进程的日志 sudo docker compose logs worker # 如果服务名是 worker 或 celery任务队列管理高级用户可以通过Celery Flower等工具监控任务队列状态如果项目配置了该组件。7. 资源占用与性能观察部署后需要关注系统的资源消耗以便进行容量规划和故障排查。7.1 查看容器资源占用使用Docker自带的统计命令。# 查看所有运行中容器的实时资源占用CPU、内存、网络I/O、磁盘I/O sudo docker stats # 查看指定容器的资源使用详情 sudo docker compose top [service-name]7.2 关键指标观察数据库PostgreSQL内存占用会随着数据量增长。观察连接数是否过高。Redis内存占用取决于缓存的数据量。在批量任务多时内存使用可能上升。后端应用CPU和内存占用在用户访问和AI任务执行时会显著增加。如果启用本地AI模型GPU显存是关键指标。前端Nginx通常资源消耗很低。7.3 性能优化方向数据库索引对于数据量大的表客户、交易记录确保关键查询字段已建立索引。缓存策略合理利用Redis缓存频繁访问但更新不频繁的数据如配置项、用户权限。AI服务降级如果本地AI模型负载过高可以考虑限流、排队或切换到调用云端API。静态资源确保前端静态文件JS、CSS、图片被Nginx高效缓存。容器资源限制在生产环境中应为每个docker-compose服务配置资源限制防止单个容器耗尽主机资源。# 在 docker-compose.yml 中示例 services: backend: # ... 其他配置 deploy: resources: limits: cpus: 2 memory: 4G reservations: cpus: 0.5 memory: 1G8. 常见问题与排查方法部署和运行过程中可能会遇到一些问题下表列出了常见问题及解决方法。问题现象可能原因排查方式解决方案docker compose up -d失败1.docker-compose.yml语法错误。2. 镜像拉取失败网络问题。3. 端口被占用。1. 运行sudo docker compose config检查语法。2. 查看命令输出错误信息。3. 使用netstat或lsof检查端口。1. 修正yml文件。2. 配置国内镜像加速器或手动拉取镜像。3. 修改docker-compose.yml中的端口映射。前端页面能打开但登录/操作后报错5xx后端服务异常或数据库连接失败。1.sudo docker compose logs backend查看后端日志。2.sudo docker compose exec postgres psql -U user -d dbname测试数据库连接。1. 根据日志修复后端错误如依赖缺失、配置错误。2. 检查.env文件中的数据库连接参数是否正确。容器启动后立即退出1. 启动命令执行失败。2. 环境变量缺失或错误。3. 健康检查失败。1.sudo docker compose logs [service-name]查看退出前的日志。2.sudo docker inspect [container-id]查看容器详细配置。1. 修正启动命令或入口点脚本。2. 确保.env文件已正确配置并被加载。3. 检查服务依赖如后端依赖数据库先启动。上传文件或执行操作非常慢1. 服务器资源CPU/内存不足。2. 磁盘I/O瓶颈。3. 网络问题如果使用远程存储或AI服务。1. 使用top,htop,docker stats监控资源。2. 使用iostat,iotop监控磁盘。3. 检查网络延迟和带宽。1. 升级服务器配置或优化应用。2. 使用SSD硬盘。3. 将服务部署在同一内网或使用CDN/对象存储。AI功能无法使用1. AI服务配置错误API Key无效或本地模型未启动。2. 网络无法访问外部AI API。1. 检查.env中OPENAI_API_KEY等配置。2. 查看后端日志中AI模块的报错信息。3. 测试从容器内是否能访问AI服务地址。1. 填写正确的API Key或启动本地模型服务。2. 配置网络代理或防火墙规则。忘记管理员密码无法登录系统。-1. 通过Docker进入后端容器使用Django管理命令重置密码sudo docker compose exec backend python manage.py changepassword [username]9. 最佳实践与使用建议为了更稳定、安全地运行Wukong AICRM请遵循以下建议。首次部署先测试在投入生产前先在测试环境完整跑通所有核心流程。使用小规模数据进行压力测试。配置管理永远不要将包含密码、密钥的.env文件提交到代码仓库。使用.env.example作为模板将实际的.env文件添加到.gitignore中。生产环境可以考虑使用Docker Secrets或专门的配置管理工具如Vault。数据持久化确保PostgreSQL和Redis的数据目录通过volumes映射到了宿主机持久化存储。定期备份数据库。# docker-compose.yml 片段示例 services: postgres: image: postgres:15 volumes: - ./data/postgres:/var/lib/postgresql/data # 数据持久化 # ...日志收集配置Docker容器的日志驱动将日志集中收集到ELKElasticsearch, Logstash, Kibana或Loki等日志平台便于排查问题。安全加固修改所有默认密码和密钥。将DEBUG设置为False。正确配置ALLOWED_HOSTS不要使用通配符*。考虑在Nginx前端配置HTTPSSSL/TLS证书。使用防火墙限制对管理端口如SSH Docker守护进程端口的访问。监控与告警对服务器CPU、内存、磁盘、网络以及容器状态设置监控和告警。可以使用Prometheus Grafana cAdvisor方案。版本升级升级前务必备份数据库和重要配置文件。仔细阅读新版本的Release Notes和升级指南。在测试环境验证无误后再升级生产环境。10. 总结与下一步Wukong AICRM通过Docker Compose提供了一站式的部署体验极大地降低了企业部署私有化、智能化CRM系统的门槛。它的价值在于将AI能力与传统的客户管理流程相结合并提供了灵活的API和可扩展的架构。部署完成后你可以立即开始基础配置在系统设置中配置公司信息、用户角色、权限、销售流程阶段等。数据导入使用系统的批量导入功能将现有的客户数据迁移进来。AI功能探索根据文档配置并测试各类AI助手功能找到提升团队效率的具体场景。系统集成基于提供的RESTful API将CRM与公司现有的OA、ERP或财务系统打通。最容易遇到的坑主要集中在初始环境配置Docker、端口、环境变量填写错误以及数据库连接问题上。按照本文的步骤和排查方法大部分问题都能快速定位。对于有开发能力的团队下一步可以深入研究其源代码进行定制化开发或者将其作为微服务架构的参考案例。整个项目基于Docker的部署方式也为你后续进行水平扩展、CI/CD集成打下了良好的基础。建议将本文中的命令和配置保存下来作为运维手册的一部分。