首页/资讯中心/详情

悟空AICRM Docker部署实战：从环境配置到生产调优全指南

悟空AICRM Docker部署实战：从环境配置到生产调优全指南
📅 发布时间：2026/7/25 6:36:16

悟空 AICRM 这套系统，如果你是想找一个能快速跑起来、功能相对完整的开源 CRM 来学习或者做内部管理，用 Docker 部署是目前最省事的选择。它把数据库、缓存、搜索、配置中心这些依赖都打包好了，你不用再一个个去配环境，尤其适合对 Java 项目部署不熟，或者想快速验证功能的人。

但“一键安装”不等于“闭眼安装”。我实测下来，从拉代码到能登录系统，中间有几个地方最容易卡住：Docker 环境本身、网络配置、以及启动后的服务等待时间。很多人照着教程跑，最后访问不了，问题往往出在这几步。这篇文章我会按实际落地的顺序，从环境检查、镜像拉取、配置调整，到最终访问和基础验证，完整走一遍，把每个环节的“为什么”和“踩坑点”都讲清楚。

1. 部署前先搞清楚：你到底需要什么环境？

在动手下载任何东西之前，先确认你的目标环境。悟空 AICRM 的 Docker 部署方案，虽然宣传支持 Linux、Windows、Mac，但实际体验和资源消耗差异很大。

1.1 硬件与操作系统要求

官方建议配置是 4 核 16G，这是一个比较宽松的生产环境建议。如果你只是本地学习、功能演示，或者用户量很小的内部测试，资源可以适当降低。但有几个底线：

  • 内存：这是硬门槛。整套 Docker Compose 会启动多个容器（MySQL、Redis、Elasticsearch、Nacos 等），即使空跑，内存占用也会轻松超过 4GB。所以，个人电脑或虚拟机至少保证 8GB 可用内存，否则启动过程中就可能因为内存不足导致容器异常退出，现象就是某个服务一直重启。
  • 磁盘空间：预留 10GB 以上的空闲空间。Docker 镜像、数据卷、日志都会占用空间，Elasticsearch 和 MySQL 的数据目录增长较快。
  • 操作系统：
    • Linux (推荐)：这是最稳定、问题最少的环境。CentOS 7/8、Ubuntu 18.04/20.04/22.04 都行。重点检查内核版本（uname -r）是否支持 Docker。
    • Windows：务必使用Windows 10 专业版/企业版/教育版或Windows 11，并开启 Hyper-V 或 WSL 2 后端。家庭版需要额外步骤启用 Hyper-V，且可能不稳定。Docker Desktop 在 Windows 上对资源（尤其是内存）的管理不如 Linux 原生，更容易出问题。
    • macOS：Intel 芯片和 Apple Silicon (M1/M2) 芯片都支持，但后者需要确认镜像是否有 arm64 版本。Docker Desktop for Mac 资源占用也比较高。

我个人的建议是，如果条件允许，优先使用 Linux 服务器或虚拟机进行部署，无论是稳定性还是后续维护，都更省心。

1.2 软件依赖：Docker 与 Docker Compose

这是核心依赖，版本不能太老。

  • Docker Engine：版本建议在20.10.0及以上。太老的版本可能不支持 Compose V2 的语法或一些网络特性。
  • Docker Compose：悟空 AICRM 的docker-compose.yml通常是 V3 格式。请务必使用 Docker Compose V2（即docker compose命令），而不是旧的 Python 编写的docker-composeV1。V2 性能更好，与 Docker Engine 集成更紧密。

如何检查？

# 检查 Docker 版本 docker --version # 检查 Docker Compose (V2) 版本 docker compose version

如果输出类似Docker Compose version v2.20.0，那就是对的。如果提示命令不存在，或者版本是 1.x，就需要安装或升级。

2. 从零开始：拉取代码与安装 Docker 环境

我们假设在一个干净的 Linux 服务器（以 Ubuntu 22.04 为例）上操作。Windows 和 macOS 的 Docker 安装请参考 Docker 官网，步骤更图形化。

2.1 获取项目源码

官方仓库在 GitHub。直接使用git克隆是最佳方式，能确保文件结构完整。

# 1. 安装 git (如果未安装) sudo apt update && sudo apt install -y git # 2. 克隆项目到当前目录 (网络不好可能需要多试几次或配置代理) git clone https://github.com/WuKongOpenSource/WukongCRM-11.0-JAVA.git # 3. 进入项目目录的 docker 子目录，所有操作都在这里进行 cd WukongCRM-11.0-JAVA/docker

进入docker目录后，你会看到前面提到的目录结构。start.sh、docker-compose.yml是核心文件。

2.2 安装与配置 Docker 环境

项目提供了一个docker-install.sh脚本，但我不建议直接运行。我更习惯分步操作，这样出错了也知道是哪一步的问题。

第一步：卸载旧版本（如有）

sudo apt-get remove docker docker-engine docker.io containerd runc

第二步：安装依赖和证书

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 gpg --dearmor -o /etc/apt/keyrings/docker.gpg

第四步：设置稳定版仓库

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

第五步：安装 Docker Engine 和 Compose Plugin

sudo apt-get update sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

第六步：启动 Docker 并设置开机自启

sudo systemctl start docker sudo systemctl enable docker

第七步：将当前用户加入 docker 组（避免每次用 sudo）

sudo usermod -aG docker $USER # 执行后需要退出当前终端，重新登录，或者执行 `newgrp docker` 使组生效 newgrp docker

现在，你应该可以不用sudo直接运行docker ps和docker compose version了。

注意：如果你是在云服务器上操作，并且安全要求高，可以跳过“将用户加入 docker 组”这一步，但后续所有docker和docker compose命令前都需要加sudo。

3. 启动前的关键配置调整

直接运行start.sh可能会成功，但更稳妥的做法是先理解配置，处理掉可能的问题。

3.1 理解网络配置（解决无法访问的核心）

这是最容易出问题的地方。看docker-compose.yml，你会发现所有服务都连接到一个自定义网络wkcrm_network，并设置了固定的子网172.20.0.0/16。

为什么需要自定义网络？为了让容器之间能通过服务名（如mysql，redis）互相访问，而不是 IP 地址。Docker 的默认桥接网络不支持容器名解析。

潜在问题： 如果你的服务器上已经有其他 Docker 项目也使用了172.20.0.0/16这个子网，或者这个子网和你宿主机的网络冲突了，就会导致网络创建失败或容器无法互通。

解决方案：

  1. 检查现有网络：docker network ls查看已有网络，docker network inspect <网络名>查看其子网。
  2. 修改子网（如有冲突）：编辑docker-compose.yml，找到networks部分，修改subnet为一个不冲突的网段，例如172.21.0.0/16。
    networks: wkcrm_network: driver: bridge ipam: config: - subnet: 172.21.0.0/16 # 修改这里
    同时，需要修改start.sh脚本中创建网络的命令（如果脚本里有的话），或者直接删除start.sh中创建网络的行，因为docker compose up会自动创建docker-compose.yml中定义的网络。

3.2 修改 Nginx 配置（绑定域名或 IP）

默认配置是允许通过服务器 IP 访问。如果你需要用域名访问，或者服务器有多个 IP 需要指定，必须修改 Nginx 配置。

文件路径：./conf/nginx/conf.d/wkcrm.conf

找到server_name部分：

server { listen 80; # 将 localhost 改为你的服务器IP或域名 server_name localhost; ... }

例如，你的服务器公网 IP 是123.123.123.123，就改为server_name 123.123.123.123;。如果是域名crm.yourcompany.com，就改为server_name crm.yourcompany.com;。

重要：如果你在本地电脑（localhost）上部署测试，保持localhost即可。如果在虚拟机里，可能需要改为虚拟机的 IP（如192.168.x.x）。

3.3 检查端口冲突

Docker Compose 会映射一些端口到宿主机。检查这些端口是否已被占用：

  • 80：Nginx (HTTP)
  • 3306：MySQL
  • 6379：Redis
  • 8848：Nacos
  • 9200：Elasticsearch

在 Linux 上可以用sudo netstat -tlnp | grep <端口号>查看。如果冲突，你有两个选择：

  1. 停止占用端口的服务。
  2. 修改docker-compose.yml中服务的ports映射，例如将“80:80”改为“8080:80”，这样外部就通过 8080 端口访问 Nginx。

3.4 （可选）替换第三方组件

如果你已经有一套现成的 MySQL、Redis 等，不想用 Docker 启动的，可以：

  1. 在docker-compose.yml中，注释掉（在行首加#）对应的服务定义（如mysql，redis等）。
  2. 修改悟空 CRM 应用本身的配置文件（在workspace目录或通过环境变量），将连接地址指向你自己的服务。

但对于初次部署和测试，强烈建议使用 Docker Compose 自带的服务，避免因外部服务配置问题导致排查困难。

4. 启动所有服务并验证

配置检查无误后，就可以启动了。

4.1 启动容器

在docker目录下，执行：

# 使用 Docker Compose V2 命令启动所有服务，-d 表示后台运行 docker compose up -d

或者，如果你坚持使用项目提供的脚本：

# 给脚本执行权限（首次运行需要） chmod +x start.sh # 执行脚本 ./start.sh

start.sh脚本内部通常也是调用docker compose up -d，并可能包含一些前置检查。

执行命令后，Docker 会开始拉取镜像（如果本地没有）、创建网络、启动容器。这个过程取决于你的网速和机器性能，可能需要几分钟。你可以用以下命令观察进度和状态：

# 查看所有容器状态 docker compose ps # 或者 docker ps # 实时查看所有容器的日志（组合输出） docker compose logs -f # 查看特定容器的日志，例如看应用启动是否报错 docker compose logs -f wkcrm

4.2 等待服务完全就绪

这是最关键也最需要耐心的一步。容器状态显示Up并不代表里面的应用服务已经启动完成。尤其是 Java 应用wkcrm和配置中心nacos，需要时间初始化。

正确的验证顺序：

  1. 等日志稳定：观察docker compose logs -f wkcrm的输出，直到看到类似“Started Application in XX seconds”或者没有新的错误日志持续输出 30 秒以上。
  2. 检查健康端点：悟空 CRM 或 Spring Boot 应用通常有健康检查接口。尝试访问http://你的服务器IP或域名/actuator/health(或类似路径)，看是否返回{"status":"UP"}。
  3. 检查依赖服务：确保 MySQL、Redis、Nacos 都运行正常。可以进入容器内部测试：
    # 测试 MySQL 连接 (从宿主机) docker exec -it docker-mysql-1 mysql -uroot -p123456 # 密码在 docker-compose.yml 或配置文件中 # 连接成功后执行 `show databases;` 查看是否有 crm 相关数据库
  4. 检查 Nacos：访问http://你的服务器IP或域名:8848/nacos，默认账号密码是nacos/nacos。登录后查看“服务管理”->“服务列表”，应该有wkcrm相关的服务注册上来。

4.3 首次访问与系统配置

当所有服务就绪后，在浏览器访问你配置的地址（如http://localhost或http://你的服务器IP）。

你应该会看到悟空 CRM 的初始化或登录页面。

首次使用通常需要：

  1. 初始化数据库：系统可能会提示你进行数据库初始化，点击执行即可。脚本通常已由容器在启动时自动执行（data目录下的 SQL 文件）。
  2. 创建管理员账号：按照页面提示，设置超级管理员账号、密码、公司名称等信息。
  3. 登录系统：使用创建的管理员账号登录，进入 CRM 主界面。

登录成功后，简单测试几个核心功能：创建一个客户、一条销售线索、一个合同。确保数据的增删改查流程是通的，这能验证前后端和数据库的基本联通性。

5. 部署后管理、排错与优化

系统跑起来只是第一步，要稳定使用，还得知道怎么管理。

5.1 常用 Docker Compose 管理命令

都在项目docker目录下执行：

# 停止所有服务，但保留容器和数据 docker compose stop # 启动已停止的服务 docker compose start # 重启所有服务 docker compose restart # 停止并删除所有容器、网络（数据卷通常会保留，具体看 volumes 定义） docker compose down # 停止并删除所有容器、网络、数据卷（危险！会清空数据库！） docker compose down -v # 查看实时日志 docker compose logs -f [服务名，如 wkcrm] # 进入某个容器的 shell 环境 docker compose exec [服务名] bash # 例如进入 MySQL 容器 docker compose exec mysql bash

5.2 常见问题与排查思路

问题1：访问http://IP显示 “502 Bad Gateway” 或 “连接被拒绝”

  • 排查：这通常是 Nginx 或后端应用没起来。
    • docker compose ps看nginx和wkcrm容器状态是否为Up。
    • docker compose logs nginx看 Nginx 错误日志，常见是connect() failed (111: Connection refused)，说明 Nginx 无法连接到后端wkcrm应用。
    • docker compose logs -f wkcrm重点看 Java 应用启动日志，是否有数据库连接失败、Redis 连接失败、端口被占用、内存不足（OOM）等错误。
    • 检查wkcrm容器内的应用是否真的在监听端口（如 8080），可以docker compose exec wkcrm netstat -tlnp。

问题2：服务启动一段时间后自动停止或重启

  • 排查：大概率是内存或 CPU 资源不足。
    • docker stats查看所有容器的实时资源占用。重点看wkcrm（Java应用）和elasticsearch，它们比较吃内存。
    • 查看宿主机整体内存free -h，确认是否有足够 Swap 空间。
    • 如果是学习环境，可以尝试调低 JVM 参数（在wkcrm服务的environment或Dockerfile中调整-Xmx）和 Elasticsearch 的ES_JAVA_OPTS。但这可能影响性能。

问题3：无法注册或登录，提示数据库错误

  • 排查：
    • 检查mysql容器是否正常运行：docker compose logs mysql。
    • 进入 MySQL 容器，检查数据库和表是否创建成功：docker compose exec mysql mysql -uroot -p123456 -e “show databases; use wkcrm_db; show tables;”（数据库名和密码以实际配置为准）。
    • 检查wkcrm应用的配置文件（如application.yml）中数据库连接信息（主机名、端口、用户名、密码、数据库名）是否正确。在 Docker Compose 网络中，主机名就是服务名mysql。

问题4：上传文件失败或附件无法查看

  • 排查：检查文件存储路径的权限。Docker 容器内应用用户（如nobody，root）需要对宿主机映射的目录（在docker-compose.yml的volumes中定义）有读写权限。可以在宿主机上对相关目录执行chmod -R 777 /path/to/volume（生产环境慎用 777，应设置更精确的权限）。

5.3 数据备份与迁移

所有持久化数据（数据库、上传文件）都通过 Docker 卷（volumes）或宿主机目录绑定（bind mounts）保存在宿主机上。查看docker-compose.yml中的volumes部分，找到本地路径。

  • MySQL 数据：通常在./data/mysql目录下。备份时可以直接打包这个目录，或者使用docker compose exec mysql mysqldump命令导出 SQL。
  • 上传文件：通常在./workspace或./data下的某个子目录。定期备份整个目录。
  • Elasticsearch 数据：在./data/elasticsearch目录下。

迁移到新服务器：

  1. 在新服务器上安装好 Docker 和 Docker Compose。
  2. 将整个项目目录（包括docker子目录及其所有内容）拷贝到新服务器。
  3. 确保新服务器的目录路径与docker-compose.yml中定义的卷路径一致，或者修改docker-compose.yml中的路径。
  4. 在新服务器docker目录下执行docker compose up -d。
  5. 检查应用日志，确认启动成功。

5.4 性能与安全调优建议（生产环境）

如果你打算用于小团队生产环境，除了基础部署，还需要考虑：

  • 资源限制：在docker-compose.yml中为每个服务（尤其是wkcrm，mysql，elasticsearch）设置deploy.resources.limits，限制其最大 CPU 和内存使用，防止单个服务拖垮宿主机。
  • 使用 HTTPS：修改 Nginx 配置，配置 SSL 证书，将 HTTP 重定向到 HTTPS。
  • 修改默认密码：务必修改 MySQL、Redis、Nacos 等服务的默认密码。密码在docker-compose.yml或./conf下的配置文件中。
  • 防火墙设置：在云服务器安全组或宿主机防火墙中，只开放必要的端口（如 80/443, 22）。
  • 日志管理：配置日志轮转（logrotate），防止日志文件撑满磁盘。可以修改./conf下各服务的日志配置。
  • 定期更新：关注项目 GitHub 仓库的 Releases，定期更新镜像和代码，修复安全漏洞。

通过以上步骤，你应该能顺利在 Docker 环境中部署并运行悟空 AICRM。整个过程的核心思路是：先确保基础环境（Docker）没问题，再理解网络和端口配置，然后耐心等待服务完全启动，最后通过功能测试和日志来验证。遇到问题，按照“看容器状态 -> 查服务日志 -> 验内部连接 -> 核对外配置”的顺序排查，大部分都能解决。