悟空本地部署安装教程真正的难点不在命令,而在选版本。官方仓库里同时躺着四个可部署的版本,最新的 v15 是容器化整包、一条命令起服务,2026 年新开的 AICRM 是 Java 源码加 AI 能力,另外两个 9.0 与 11.0 已经停更多年。版本选错,后面敲的命令全是白费。 悟空CRM本地部署该选哪个版本
官方代码组织 WuKongOpenSource 下挂着四个仓库,名字都带 WukongCRM,但状态差得很远。先看清最近的提交时间,再看技术栈,就不会拿五年前的教程去装今天的系统。
| | | | |
|---|
| 容器化整包,内含 MySQL、Redis、MinIO、Elasticsearch | | | |
| Java 21、Spring Boot 3、Spring AI、Vue 3 | | | |
| | | | |
| | | | |
判断依据要看两个字段,一个是「是否归档」,一个是「最近提交」。四个仓库都没有被归档,但 11.0-JAVA 的最后一次提交停在 2021 年,也就是说五年没动过。网上一大批「悟空CRM部署教程」讲的正是这一版,里面那套 JDK 8 加微服务的配法,套到 v15 上完全对不上。
一句话选型:只要用起来,选 v15;要 AI 能力或要改代码,选 AICRM;手上跑着 9.0 或 11.0 的老系统,才去找对应版本的旧文档。官方站是 wukongcrm.com,下载包与版本说明都在上面,仓库里的 README 也会同步指向它。
跑起来之前的机器与端口准备
v15 对机器几乎没有要求,官方 README 只写了两个先决条件:装好 Docker 与 Docker Compose。Linux 上可以直接用镜像脚本装,Mac 与 Windows 建议从 Docker 官网下载桌面版。
AICRM 走源码模式时门槛高一档,官方列的是 JDK 21 及以上、Node.js 18 及以上、Maven 3.8 及以上、PostgreSQL 17、Redis 6 及以上。这五项缺一项,编译或启动都会在中途报错。
| | |
|---|
| v15 的 nginx、AICRM 的 frontend | |
| | |
| v15 的 Elasticsearch 8.13.4 | |
| | |
| | |
| | |
| | |
80、3306、9000 都是常用端口,装之前先看一眼有没有被别的东西占着。尤其是 80,v15 的 nginx 在编排里写死成 80 比 80,宿主机上已经有 nginx 或者别的站点,容器就会起不来。
Docker一键部署的完整步骤
这是 v15 唯一推荐的方式,官方原话是「一键部署、几分钟内即可快速上线」。
- 装 Docker 与 Docker Compose。Linux 可以执行镜像站提供的一键脚本,Mac 与 Windows 从 Docker 官网下载安装包。
- 克隆仓库,地址是 https://github.com/WuKongOpenSource/Wukong_CRM_15.git,克隆完会得到一个 Wukong_CRM_15 目录。
- 进入 docker 子目录,部署用到的编排文件、初始化 SQL、nginx 配置、Elasticsearch 插件全在这里。
- 执行 docker compose up -d,让它自己在后台拉镜像、建容器。
- 等健康检查通过。MySQL 第一次启动时要导入一份约 1.8MB 的建表 SQL,编排里给的健康检查启动宽限期是 120 秒,这期间容器显示 unhealthy 属于正常现象。
- 浏览器打开 http://localhost,能看到登录页就说明主链路通了。
编排里一共起了七个服务:MySQL、Redis、MinIO、minio-init、Elasticsearch、wk_crm、nginx。wk_crm 是应用本体,它的健康检查打的是容器内 8445 端口的 ping 接口,所以宿主机上访问不到这个端口,包在 nginx 后面。第一次部署完不要急着改这个结构,先把页面打开再说。
两个容易被忽略的分支:一是 ARM 机器,官方另外给了一份 ARM 专用编排文件,要用它替代默认文件,否则会去拉 amd64 镜像然后跑不起来;二是国内网络,这份编排里的镜像地址已经全部指向国内加速源,这是官方为了让国内用户能顺利拉取而做的处理,如果换成官方原始镜像地址,拉取大概率超时。
源码部署怎么改配置跑起来
AICRM 的 README 把两条路分得很清楚:优先用 Docker 一键装,需要本地二次开发时再用源码。走源码这条路,前后端要分别起。
- 进 backend 目录,执行 mvn clean install 完成依赖拉取与编译,再执行 mvn spring-boot:run 启动后端。
- 后端默认跑在 8088 端口,接口文档在 http://localhost:8088/doc.html,能打开就说明后端活了。
- 另开一个终端进 frontend 目录,执行 npm install,再执行 npm run dev。
- 前端默认跑在 5173 端口,浏览器打开就能看到界面。
首次启动前必须先改配置文件,路径是 backend/src/main/resources/application.yml。里面五个区块都要动:数据库连到 PostgreSQL 的 wk_ai_crm 库,Redis 默认用 7 号库,AI 部分要填 api-key 与 base-url,MinIO 默认账号密码都是 minioadmin、桶名 ai-crm,知识库服务则是 base-url 加 api-key 加 knowledge-base-id。
AI 这一栏不填会直接报错,官方文档写得很直白:安装完成后要到后台的「系统设置」里配好 API 与 AI 的 Key,否则 AI 对话会报错。这里的模型不限厂商,任何提供 OpenAI 兼容接口的服务都能接,OpenAI、DeepSeek、通义千问、豆包、智谱,甚至本地跑的 Ollama 都行。 部署完先做哪几件事
系统能打开只是第一步。官方在 AICRM 的 README 里专门提示了一句:生产环境上线后,请及时修改初始化管理员密码,并关闭不需要的演示数据。这句提示背后是三个具体动作。
| | |
|---|
| | 编排里写死的默认口令,且 3306 会映射到宿主机 |
| | |
| | 账号密码相同,且 9000 与 9001 都对外映射 |
| | |
改默认值的正确位置是 docker 目录下的 .env 文件,里面列了 MySQL 密码、Redis 密码、MinIO 的账号与端口,把值填进去再重新 up 一次即可。别直接改编排文件,下次拉新版本会被覆盖。
第二件事是关演示数据。官方在 v15 的说明里写了这个版本「配备示例数据与配套文档」,目的是让新用户打开就能看懂界面。正式用之前要清掉,否则客户列表、合同列表里全是假数据,导入真数据时会混在一起。
第三件事是配 AI。AICRM 的 AI 能力不是装完就有,必须到后台「系统设置」的「API 与 AI」里填 Key,选好模型。这一步不做,界面能开、客户能录,但一用对话就报错。
部署常见的报错与处理
| | |
|---|
| | |
| | 确认可以清空后再删 volumes 目录重来,注意会丢数据 |
| | 看容器日志,多半是 MySQL 或 Elasticsearch 还没就绪 |
| | |
| | |
| | |
| | |
| 库没建,或 application.yml 里的密码不对 | |
排查顺序建议固定成三步:先 docker compose ps 看哪个容器不是 Up,再 docker compose logs 看那个容器的报错,最后才去改配置。跳过前两步直接改配置,十个里有八个是白改。
备份与升级要注意什么
所有业务数据都落在 docker 目录下的 volumes 里,包括 MySQL 的数据文件、Redis 的持久化、MinIO 的对象和 Elasticsearch 的索引。备份就是把这几块打包带走,最省事的做法是先停容器,再整目录压缩,最后单独导一份 SQL 作为兜底。
升级有一个关键机制要提前知道:MySQL 的初始化 SQL 放在 docker-entrypoint-initdb.d 目录里,容器只在数据目录为空时才会执行它。换句话说,你已经有数据的情况下重新 up,新版本带来的表结构变更不会自动生效。
所以升级的正确顺序是:先备份,再拉新代码或新镜像,然后手工比对并执行新版本 DB 目录里的 SQL,最后重启容器验证。跳过第三步,常见的结果是新版本代码去查一个还不存在的字段,页面直接报错。
选版本和上线前必须知道的限制
有几条限制官方写得很清楚,但第一次部署的人往往到最后才发现。
- 许可不是随便商用:AICRM 的仓库徽章写的是非商业使用,商业使用需要单独授权。企业内部自用与对外售卖是两件事,采购前先看清协议原文。
- 老版本别用在新项目上:11.0-JAVA 停在 2021 年、9.0-PHP 停在 2023 年,两者都没有归档但也不再更新。拿它们上新系统,等于一开始就背上技术债。
- 数据库与对象存储不要暴露公网:编排把 3306、9000、9200 都映射到了宿主机,方便调试,但正式环境要把这些映射去掉,只留 80 对外。
- 默认口令必须改:MySQL、Redis、MinIO 三处默认值都写在编排里,不改等于把门虚掩着。
- 数据确实在自己机器上:AICRM 官方 FAQ 明确说项目可完全私有化部署,客户、文档与 AI 交互数据都保存在自己的服务器里。这也是私有化部署最大的价值。
- 卡住了去哪问:官方给的是社区论坛与 GitHub Issues 两个渠道,提问时把容器日志和编排文件版本一起贴上,回复会快很多。
悟空本地部署安装教程常见问题
Q:一定要用 Docker 吗? A:v15 官方只给了 Docker 一条路,没有提供手动安装文档;AICRM 两条路都支持,源码模式适合要改代码的人。
Q:最低配置多少内存? A:官方 README 没给具体数字。从编排看,同时要跑 MySQL、Redis、MinIO、Elasticsearch 与应用本体,建议起步 4GB 以上,低于这个数 Elasticsearch 容易起不来。
Q:部署完访问哪个地址? A:v15 和 AICRM 的 Docker 模式都访问 80 端口,也就是浏览器直接打开 localhost;AICRM 源码模式前端在 5173、后端在 8088。
Q:默认管理员账号密码是多少? A:在仓库的初始化 SQL 里没有查找到内置管理员记录,账号来自安装流程或官方安装文档。首次登录后请立刻修改密码。
Q:能装在 Windows 上吗? A:可以,装 Docker Desktop 后按同样的命令走。注意 Windows 上端口占用更常见,80 端口经常被系统服务或其它 Web 服务占着。
Q:ARM 服务器能装吗? A:v15 官方额外提供了 ARM 专用编排文件,用它替代默认文件即可;AICRM 的镜像需要在 ARM 上重新构建。
Q:支持哪些 AI 模型? A:AICRM 支持任何提供 OpenAI 兼容接口的服务,OpenAI、DeepSeek、通义千问、豆包、智谱都能接,本地 Ollama 也可以。 Q:升级会丢数据吗? A:只要不动 volumes 目录就不会。但初始化 SQL 只在空库时执行,升级后要手工执行新版本的表结构变更脚本。
Q:商用需要授权吗? A:AICRM 的许可写明非商业使用,商业用途需要单独获得授权。采购或对外交付前请先确认协议原文。
版本选对、默认口令改掉之后,悟空本地部署安装教程里真正容易翻车的部分就过去了。剩下的都是运维日常,不在这篇的范围内。