悟空 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 原生更容易出问题。macOSIntel 芯片和 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 Pluginsudo 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 组避免每次用 sudosudo 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。为什么需要自定义网络为了让容器之间能通过服务名如mysqlredis互相访问而不是 IP 地址。Docker 的默认桥接网络不支持容器名解析。潜在问题 如果你的服务器上已经有其他 Docker 项目也使用了172.20.0.0/16这个子网或者这个子网和你宿主机的网络冲突了就会导致网络创建失败或容器无法互通。解决方案检查现有网络docker network ls查看已有网络docker network inspect 网络名查看其子网。修改子网如有冲突编辑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 会映射一些端口到宿主机。检查这些端口是否已被占用80Nginx (HTTP)3306MySQL6379Redis8848Nacos9200Elasticsearch在 Linux 上可以用sudo netstat -tlnp | grep 端口号查看。如果冲突你有两个选择停止占用端口的服务。修改docker-compose.yml中服务的ports映射例如将“80:80”改为“8080:80”这样外部就通过 8080 端口访问 Nginx。3.4 可选替换第三方组件如果你已经有一套现成的 MySQL、Redis 等不想用 Docker 启动的可以在docker-compose.yml中注释掉在行首加#对应的服务定义如mysqlredis等。修改悟空 CRM 应用本身的配置文件在workspace目录或通过环境变量将连接地址指向你自己的服务。但对于初次部署和测试强烈建议使用 Docker Compose 自带的服务避免因外部服务配置问题导致排查困难。4. 启动所有服务并验证配置检查无误后就可以启动了。4.1 启动容器在docker目录下执行# 使用 Docker Compose V2 命令启动所有服务-d 表示后台运行 docker compose up -d或者如果你坚持使用项目提供的脚本# 给脚本执行权限首次运行需要 chmod x start.sh # 执行脚本 ./start.shstart.sh脚本内部通常也是调用docker compose up -d并可能包含一些前置检查。执行命令后Docker 会开始拉取镜像如果本地没有、创建网络、启动容器。这个过程取决于你的网速和机器性能可能需要几分钟。你可以用以下命令观察进度和状态# 查看所有容器状态 docker compose ps # 或者 docker ps # 实时查看所有容器的日志组合输出 docker compose logs -f # 查看特定容器的日志例如看应用启动是否报错 docker compose logs -f wkcrm4.2 等待服务完全就绪这是最关键也最需要耐心的一步。容器状态显示Up并不代表里面的应用服务已经启动完成。尤其是 Java 应用wkcrm和配置中心nacos需要时间初始化。正确的验证顺序等日志稳定观察docker compose logs -f wkcrm的输出直到看到类似“Started Application in XX seconds”或者没有新的错误日志持续输出 30 秒以上。检查健康端点悟空 CRM 或 Spring Boot 应用通常有健康检查接口。尝试访问http://你的服务器IP或域名/actuator/health(或类似路径)看是否返回{status:UP}。检查依赖服务确保 MySQL、Redis、Nacos 都运行正常。可以进入容器内部测试# 测试 MySQL 连接 (从宿主机) docker exec -it docker-mysql-1 mysql -uroot -p123456 # 密码在 docker-compose.yml 或配置文件中 # 连接成功后执行 show databases; 查看是否有 crm 相关数据库检查 Nacos访问http://你的服务器IP或域名:8848/nacos默认账号密码是nacos/nacos。登录后查看“服务管理”-“服务列表”应该有wkcrm相关的服务注册上来。4.3 首次访问与系统配置当所有服务就绪后在浏览器访问你配置的地址如http://localhost或http://你的服务器IP。你应该会看到悟空 CRM 的初始化或登录页面。首次使用通常需要初始化数据库系统可能会提示你进行数据库初始化点击执行即可。脚本通常已由容器在启动时自动执行data目录下的 SQL 文件。创建管理员账号按照页面提示设置超级管理员账号、密码、公司名称等信息。登录系统使用创建的管理员账号登录进入 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 bash5.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查看所有容器的实时资源占用。重点看wkcrmJava应用和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 容器内应用用户如nobodyroot需要对宿主机映射的目录在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目录下。迁移到新服务器在新服务器上安装好 Docker 和 Docker Compose。将整个项目目录包括docker子目录及其所有内容拷贝到新服务器。确保新服务器的目录路径与docker-compose.yml中定义的卷路径一致或者修改docker-compose.yml中的路径。在新服务器docker目录下执行docker compose up -d。检查应用日志确认启动成功。5.4 性能与安全调优建议生产环境如果你打算用于小团队生产环境除了基础部署还需要考虑资源限制在docker-compose.yml中为每个服务尤其是wkcrmmysqlelasticsearch设置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没问题再理解网络和端口配置然后耐心等待服务完全启动最后通过功能测试和日志来验证。遇到问题按照“看容器状态 - 查服务日志 - 验内部连接 - 核对外配置”的顺序排查大部分都能解决。