在业务系统选型与快速部署的实践中我们常常面临一个矛盾一方面希望系统功能强大、技术栈现代另一方面又受限于部署环境的复杂性尤其是当项目涉及前后端分离、数据库、中间件等多个组件时手动部署和联调会耗费大量时间。Wukong-AICRM 作为一个基于 Java Vue 的智能对话式客户关系管理系统其 Docker 一键安装方案完美地解决了这一痛点。本文将为你完整拆解 Wukong-AICRM 的 Docker 安装全流程从环境准备、镜像拉取、容器启动到访问验证每一步都附带详细的命令、配置说明和排错指南。无论你是想快速体验系统功能还是为团队搭建一个演示或测试环境都能在半小时内完成从零到一的部署。1. 项目背景与核心概念在深入安装步骤之前我们有必要了解 Wukong-AICRM 是什么以及为什么 Docker 是部署它的最佳实践。1.1 什么是 Wukong-AICRMWukong-AICRM 是一个开源的、智能对话式客户关系管理系统。它并非传统的表单录入式 CRM而是集成了智能对话能力旨在通过更自然的交互方式如聊天机器人来管理客户线索、跟进商机、记录沟通历史等。其技术栈采用了当前企业级开发的主流组合后端基于 Java 生态通常使用 Spring Boot 框架提供稳定的 RESTful API。前端基于 Vue.js 生态提供现代化、响应式的用户界面。数据库通常依赖 MySQL 或 PostgreSQL 等关系型数据库存储核心业务数据。其他组件可能还包括 Redis用于缓存或会话管理、消息队列等。这样一个多组件的系统如果采用传统方式部署需要分别安装配置 JDK、Node.js、数据库、Web 服务器等步骤繁琐且容易因环境差异导致问题。1.2 为什么推荐使用 Docker 部署Docker 是一个开源的应用容器引擎它允许开发者将应用及其依赖打包到一个轻量级、可移植的容器中。对于 Wukong-AICRM 这类项目Docker 部署的优势显而易见环境一致性容器包含了运行应用所需的一切代码、运行时、系统工具、库保证了“开发环境、测试环境、生产环境”的一致性彻底解决“在我机器上能跑”的问题。快速部署与启动通过预构建的 Docker 镜像你无需关心底层系统依赖一条命令即可启动整个应用栈极大提升了部署效率。资源隔离与高效容器之间以及容器与宿主机之间资源隔离更加安全同时容器共享主机操作系统内核比传统虚拟机更加轻量、启动更快。易于维护和扩展使用 Docker Compose 可以轻松定义和管理多容器应用后续的升级、回滚、扩展都变得非常简单。因此项目官方文档也推荐优先使用 Docker 一键安装这无疑是体验和部署 Wukong-AICRM 的最优路径。2. 环境准备与先决条件在开始安装之前请确保你的操作环境满足以下要求。我们将分别介绍在 Windows、macOS 和 Linux 系统上的准备工作。2.1 Docker 环境安装Docker 是运行 Wukong-AICRM 的基石。如果你的系统尚未安装 Docker请根据以下指引进行安装。对于 Windows 10/11 专业版、企业版或教育版支持 Hyper-V访问 Docker 官网的 Docker Desktop for Windows 下载页面。下载安装包并运行。安装过程中确保勾选“使用 WSL 2 而不是 Hyper-V”推荐性能更好的选项。安装完成后重启电脑。启动 Docker Desktop你会在系统托盘看到 Docker 图标。打开 PowerShell 或 WSL 终端运行docker --version和docker-compose --version来验证安装是否成功。对于 Windows 10/11 家庭版家庭版默认不支持 Hyper-V。你需要先安装 WSL 2 (Windows Subsystem for Linux 2)然后在 WSL 2 中安装 Docker或者使用 Docker Desktop 的 WSL 2 后端。建议参考微软和 Docker 官方文档进行配置。对于 macOS访问 Docker 官网的 Docker Desktop for Mac 下载页面。下载对应芯片Intel 或 Apple Silicon的安装包拖拽到“应用程序”文件夹即可。启动 Docker Desktop完成初始设置。打开终端运行docker --version验证。对于 Linux (以 Ubuntu 20.04/22.04 为例)通过官方仓库安装是最佳实践。# 1. 更新 apt 包索引并安装依赖 sudo apt-get update sudo apt-get install 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. 设置稳定版仓库 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 sudo apt-get update sudo apt-get install docker-ce docker-ce-cli containerd.io docker-compose-plugin # 5. 验证安装 sudo docker run hello-world注意Linux 下默认需要sudo权限运行 Docker 命令。可以将用户加入docker组来免 sudosudo usermod -aG docker $USER然后退出当前终端重新登录生效。2.2 Docker Compose 安装Wukong-AICRM 的多容器编排很可能依赖 Docker Compose。新版的 Docker Desktop 已内置docker compose插件命令为docker compose。对于 Linux 手动安装可以使用以下命令安装插件版本# 下载最新版本的 docker-compose-plugin sudo apt-get update sudo apt-get install docker-compose-plugin # 验证 docker compose version如果项目提供的是docker-compose.yml文件使用docker-compose旧版独立命令或docker compose新版插件命令均可本文统一使用docker compose。2.3 系统资源检查运行一个完整的应用栈需要一定的系统资源。建议确保你的机器至少满足CPU2 核或以上。内存4 GB 或以上Docker 容器会占用部分内存。磁盘空间至少 10 GB 可用空间用于存储镜像和容器数据。网络能够顺畅访问 Docker Hub 等镜像仓库。3. 获取 Wukong-AICRM 的 Docker 部署配置通常开源项目会将其 Docker 化部署的配置文件放在代码仓库的根目录。我们需要找到 Wukong-AICRM 的docker-compose.yml文件和相关配置。3.1 定位项目仓库根据提供的网络搜索内容项目托管在 GitCode 上。我们可以通过克隆仓库或直接下载部署文件的方式获取配置。# 方式一克隆整个仓库适合需要查看源码或后续二次开发 git clone https://gitcode.com/owner/Wukong-AICRM.git cd Wukong-AICRM # 方式二如果只需要部署文件可以查看仓库根目录下是否有 docker-compose.yml # 通常使用 curl 或 wget 直接下载该文件需要知道确切URL # 例如 # wget https://gitcode.com/owner/Wukong-AICRM/raw/main/docker-compose.yml注意由于提供的片段中仓库具体 URL 不完整在实际操作时你需要替换owner为正确的用户名或组织名或直接在 GitCode 网站找到该项目。3.2 理解 Docker Compose 文件结构一个典型的docker-compose.yml文件会定义多个服务容器。对于 Wukong-AICRM可能包含以下服务mysql或postgresql数据库服务。redis缓存服务。backendJava Spring Boot 后端应用。frontendVue.js 前端应用可能由 Nginx 提供服务。nginx可选作为反向代理统一端口。在项目根目录下找到docker-compose.yml文件后先浏览其内容了解各个服务的配置、依赖关系和映射的端口。4. 完整 Docker 部署实战假设我们已经获得了正确的docker-compose.yml文件。下面以一份假设的、但具有高度代表性的配置为例演示完整的部署流程。你的实际文件可能略有不同但核心步骤和思路是一致的。4.1 准备部署目录与配置文件首先创建一个干净的工作目录并将所有部署文件放入其中。mkdir wukong-aicrm-docker cd wukong-aicrm-docker将项目中的docker-compose.yml文件以及可能存在的.env环境变量文件、config/配置文件目录、init.sql数据库初始化脚本等文件都复制到这个目录下。一个简化的docker-compose.yml示例可能如下所示version: 3.8 services: mysql: image: mysql:8.0 container_name: wukong-mysql restart: always environment: MYSQL_ROOT_PASSWORD: root123456 MYSQL_DATABASE: wukong_crm MYSQL_USER: wukong MYSQL_PASSWORD: wukong123 ports: - 3307:3306 # 主机端口:容器端口避免与宿主机MySQL冲突 volumes: - ./data/mysql:/var/lib/mysql - ./init.sql:/docker-entrypoint-initdb.d/init.sql networks: - wukong-net redis: image: redis:7-alpine container_name: wukong-redis restart: always ports: - 6380:6379 volumes: - ./data/redis:/data command: redis-server --appendonly yes networks: - wukong-net backend: image: wukong-aicrm-backend:latest # 假设镜像已构建或存在于仓库 container_name: wukong-backend restart: always depends_on: - mysql - redis environment: - SPRING_DATASOURCE_URLjdbc:mysql://mysql:3306/wukong_crm?useUnicodetruecharacterEncodingutf8useSSLfalse - SPRING_DATASOURCE_USERNAMEwukong - SPRING_DATASOURCE_PASSWORDwukong123 - SPRING_REDIS_HOSTredis - SPRING_REDIS_PORT6379 ports: - 8080:8080 volumes: - ./logs/backend:/app/logs networks: - wukong-net frontend: image: nginx:alpine container_name: wukong-frontend restart: always depends_on: - backend ports: - 80:80 volumes: - ./dist:/usr/share/nginx/html # 挂载前端构建产物 - ./nginx.conf:/etc/nginx/nginx.conf:ro # 挂载自定义Nginx配置 networks: - wukong-net networks: wukong-net: driver: bridge关键点解释networks: 所有服务加入同一个自定义网络wukong-net这样容器间可以通过服务名如mysqlredis直接通信。depends_on: 定义了启动顺序backend依赖mysql和redis。volumes: 将主机目录挂载到容器内用于持久化数据数据库、日志和提供配置文件。ports: 将容器端口映射到主机端口以便从外部访问。4.2 配置与自定义在启动前根据你的环境调整配置修改密码务必修改MYSQL_ROOT_PASSWORD、MYSQL_PASSWORD等环境变量中的默认密码。检查端口确保主机端口如3307808080没有被其他程序占用。准备前端资源如果frontend服务挂载了./dist你需要将 Vue 项目构建后的产物放入该目录。准备数据库初始化脚本如果项目有init.sql确保其路径正确。4.3 启动所有服务在包含docker-compose.yml的目录下执行启动命令# 使用 docker compose 插件推荐 docker compose up -d # 或者使用旧版的 docker-compose 独立命令 # docker-compose up -dup: 创建并启动所有服务。-d: 在后台运行守护进程模式。命令执行后Docker 会执行以下操作检查本地是否存在所需的镜像如mysql:8.0redis:7-alpinenginx:alpine如果不存在则从 Docker Hub 拉取。为项目创建一个独立的网络 (wukong-net)。按照依赖顺序启动各个容器。将容器放入后台运行。4.4 查看启动状态与日志启动后使用以下命令确认服务状态# 查看所有容器的运行状态 docker compose ps # 查看所有容器的实时日志组合视图 docker compose logs -f # 查看特定容器的日志例如后端 docker compose logs -f backend如果看到后端服务日志中出现Started Application in X seconds或类似的成功启动信息同时没有持续报错通常意味着应用已成功启动。常见启动问题排查端口冲突如果启动失败首先检查日志错误。常见错误Bind for 0.0.0.0:XXXX failed: port is already allocated表示端口被占用需修改docker-compose.yml中的主机端口。数据库连接失败后端日志可能出现Communications link failure。检查backend服务中的数据库连接地址、用户名、密码是否正确并确认mysql容器是否已完全启动可能需要等待几十秒。镜像不存在如果backend使用的是自定义镜像如wukong-aicrm-backend:latest而这个镜像不存在于本地或公共仓库你需要先构建它。通常项目会提供Dockerfile使用docker build -t wukong-aicrm-backend .构建。4.5 访问系统并验证所有服务启动成功后即可通过浏览器访问前端页面根据配置通常映射到主机的80端口。打开浏览器访问http://localhost或http://你的服务器IP。后端API后端服务可能映射到8080端口可以访问http://localhost:8080查看是否有 API 文档如 Swagger UI或健康检查端点如/actuator/health。如果前端页面正常加载并且可以登录或看到系统界面说明 Docker 部署成功。5. 管理、维护与排错指南部署成功只是第一步日常的维护和问题排查同样重要。5.1 常用 Docker Compose 管理命令# 停止所有服务但保留容器和数据 docker compose stop # 停止并移除所有容器、网络数据卷默认不会删除 docker compose down # 停止并移除所有容器、网络、数据卷谨慎使用会丢失数据库数据 docker compose down -v # 重启所有服务 docker compose restart # 重启单个服务例如后端 docker compose restart backend # 查看服务资源使用情况 docker compose top # 进入某个容器的交互式终端例如进入MySQL容器 docker compose exec mysql bash # 或者 docker compose exec mysql sh5.2 数据持久化与备份在示例配置中我们通过volumes将容器内的数据目录挂载到了主机上如./data/mysql。这是数据持久化的关键。备份数据库你可以直接备份主机上的./data/mysql目录。更规范的做法是使用docker compose exec mysql mysqldump命令进行 SQL 转储。迁移与恢复要迁移整个应用只需复制整个项目目录包含docker-compose.yml和data/在新机器上运行docker compose up -d即可。5.3 常见问题与解决方案问题现象可能原因排查与解决思路docker compose up报错network ... not found网络被手动删除或未创建。运行docker network create wukong-net或直接docker compose up会重新创建。前端页面能打开但后端 API 调用 502/504前端容器内的 Nginx 配置未能正确代理到后端或后端服务未启动。1. 检查docker compose ps确认backend状态为Up。2. 进入frontend容器检查 Nginx 配置docker compose exec frontend cat /etc/nginx/nginx.conf。3. 查看后端日志docker compose logs backend。应用启动后数据库连接失败1. 数据库连接字符串配置错误主机名、端口、库名、密码。2. MySQL 容器初始化未完成。1. 核对backend服务环境变量与mysql服务定义是否一致。2. 查看 MySQL 容器日志docker compose logs mysql等待出现ready for connections。3. 尝试进入 MySQL 容器手动连接验证。修改了docker-compose.yml或代码后如何生效容器使用的是旧的镜像或配置。1.重建并重启服务docker compose up -d --build service_name(如果修改了Dockerfile)。2.重启服务docker compose restart service_name(如果只改了环境变量或配置)。3.完全重建docker compose down docker compose up -d(注意此操作会删除容器但保留数据卷)。主机磁盘空间不足Docker 镜像、容器日志、数据卷占用过多空间。1. 清理无用镜像docker image prune -a。2. 清理停止的容器和缓存docker system prune -f。3. 检查数据卷大小docker system df。5.4 性能与安全最佳实践生产环境配置本文示例为开发环境配置。生产环境务必使用强密码并通过secrets或外部环境变量文件管理而不是硬编码在docker-compose.yml中。修改默认端口避免使用808080等常见端口。考虑使用 Docker Swarm 或 Kubernetes 进行集群化部署而非单机 Docker Compose。为数据库等有状态服务配置独立的、更可靠的存储卷。日志管理将容器日志定向到外部日志系统如 ELK Stack避免日志占满磁盘。可以在docker-compose.yml中使用logging驱动配置。资源限制为每个服务设置 CPU 和内存限制防止单个容器耗尽主机资源。services: backend: # ... deploy: # 或者使用 resources 关键字取决于 compose 版本 resources: limits: cpus: 1.0 memory: 1G reservations: cpus: 0.5 memory: 512M镜像安全定期更新基础镜像如mysqlredis以获取安全补丁。对于自定义的backend镜像进行漏洞扫描。6. 总结与后续步骤通过以上步骤你应该已经成功在本地或服务器上使用 Docker 部署了 Wukong-AICRM 系统。Docker Compose 将复杂的多服务部署简化为一个配置文件加几条命令极大地提升了效率。部署完成后你可以探索系统功能登录系统熟悉其智能对话、客户管理、销售跟进等核心功能。进行二次开发如果你需要定制功能可以将后端和前端代码分别导入 IDE。修改代码后需要重新构建 Docker 镜像通常项目会提供构建脚本或 Dockerfile然后更新服务。集成外部系统研究其 API 文档尝试将 Wukong-AICRM 与你现有的系统如 OA、ERP进行集成。学习 Docker 进阶深入了解 Docker 网络、存储卷、Dockerfile 编写、Docker Registry 等概念为更复杂的生产部署做准备。如果在部署过程中遇到本文未覆盖的特定错误建议首先仔细阅读项目的官方README.md或docker-compose.yml文件中的注释。其次查看对应容器的详细日志是定位问题的根本方法。Docker 社区和项目的 Issue 页面也是寻找解决方案的好去处。
