Docker部署悟空AICRM：从环境准备到问题排查全流程指南-尧图网络科技

1. 先搞清楚“悟空 AICRM”是什么，以及为什么用 Docker 部署

如果你在找“悟空 AICRM”的部署方法，大概率是看到了某个基于大模型的客户关系管理或智能对话系统。这类项目通常整合了类似 GPT 的对话能力、知识库以及 CRM 的客户管理功能，目标是打造一个能自动回复、分析客户意图的智能助手。

直接下载源码、配环境、装依赖的传统方式，对于这类整合了前端、后端、数据库、向量库、大模型服务的项目来说，非常容易踩坑。不同组件的版本冲突、系统环境差异、配置文件路径问题，足以让新手折腾好几天。

所以，用Docker来部署是当前最稳妥的选择。Docker 把应用和它所有的依赖打包成一个“集装箱”，你只需要确保 Docker 本身能跑起来，然后一条命令就能拉起整个服务栈，包括数据库、Redis、后端 API、前端界面等。这解决了“在我机器上能跑，在你那就报错”的核心痛点。

这篇文章会带你走通从零开始，在 Linux 服务器或本地开发机上，用 Docker 完整部署“悟空 AICRM”的全过程。我会把重点放在环境检查、镜像拉取、配置修改、服务启动和初步验证这几个关键环节，并补充那些文档里可能没写，但实际部署一定会遇到的细节和排查点。

2. 部署前的核心准备：环境与资源盘点

在运行任何docker-compose up命令之前，先花十分钟做好准备工作，能避免 80% 的后续问题。部署“悟空 AICRM”这类服务，你需要关注的不仅仅是 Docker 本身。

2.1 硬件与操作系统要求

首先看你的机器条件。这不是一个轻量级应用，它通常包含多个容器。

CPU 与内存：这是基础。建议至少 2 核 CPU 和 4GB 以上的可用内存。如果计划启用向量检索、嵌入模型等高级功能，内存需求会更高，8GB 是更稳妥的起点。你可以用free -h命令查看可用内存。
磁盘空间：Docker 镜像、数据库数据、日志文件都会占用空间。预留至少 20GB 的可用磁盘空间是必要的。使用df -h命令检查挂载点（通常是/或/var/lib/docker）的剩余空间。
操作系统：Linux 是首选，特别是 Ubuntu 20.04/22.04 或 CentOS 7/8 等主流发行版，社区支持最好。本文的演示和命令也以 Linux 环境为主。
- 关于 Windows/macOS：虽然 Docker Desktop 支持这两者，但用于生产部署或长期学习，Linux 服务器环境更稳定，资源开销更小。如果你是 Windows 用户，强烈建议使用 WSL 2 (Windows Subsystem for Linux) 来获得接近原生 Linux 的体验，而不是直接使用 Docker Desktop for Windows 的 Hyper-V 模式，后者在文件挂载、网络等方面有时会有兼容性问题。

2.2 软件依赖检查

核心依赖就一个：Docker和Docker Compose。

安装 Docker Engine：

不要使用系统自带的陈旧版本。去 Docker 官方文档，根据你的 Linux 发行版，使用仓库安装。以 Ubuntu 为例，命令序列通常是：

sudo apt-get update sudo apt-get install ca-certificates curl sudo install -m 0755 -d /etc/apt/keyrings sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc sudo chmod a+r /etc/apt/keyrings/docker.asc echo \ "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \ $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \ sudo tee /etc/apt/sources.list.d/docker.list > /dev/null sudo apt-get update sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

安装后，运行sudo docker run hello-world测试是否安装成功。看到欢迎信息即表示 Docker 引擎正常。

安装 Docker Compose：
- 如果你安装的是docker-compose-plugin（如上一步），那么docker compose（注意中间没有横线）命令已经可用。这是新版本的方式。
- 如果你需要独立的docker-compose（带横线），可以通过 pip 安装或下载二进制文件。但建议优先使用插件版，与 Docker CLI 集成更好。
- 验证：运行docker compose version或docker-compose --version，能看到版本号即可。
权限配置（非常重要）：
- 默认情况下，运行 Docker 命令需要sudo。为了方便，可以将当前用户加入docker用户组。
```
sudo usermod -aG docker $USER
```
- 执行此命令后，你必须完全退出当前终端会话（关闭所有窗口或断开 SSH），然后重新登录，权限变更才会生效。重新登录后，运行docker ps不再需要sudo，即表示配置成功。

2.3 获取部署文件

“悟空 AICRM”的 Docker 部署通常需要一个docker-compose.yml文件和一个存放环境变量的.env文件。你需要从项目的官方仓库（如 GitHub、Gitee）获取这些文件。

寻找源码：在搜索引擎或代码托管平台搜索 “悟空 AICRM docker-compose” 或类似关键词，找到项目主页。
关键文件：
- docker-compose.yml：定义了所有服务（如 MySQL、Redis、后端 App、前端 Nginx）的构建或镜像、依赖关系、网络、卷挂载。
- .env或example.env：存放配置项，如数据库密码、Redis 地址、API 密钥、服务端口等。这是你需要重点修改的文件。
- README.md：务必阅读，里面可能有特定的版本要求、先决条件或已知问题。

假设你已经将包含这些文件的目录下载或克隆到本地，例如路径是~/wukong-aicrm。接下来的操作都在这个目录下进行。

3. 核心部署流程：从配置到启动

拿到部署文件后，不要急着启动。先理解结构，再修改配置，最后按顺序启动服务。

3.1 解析 Docker Compose 结构

用编辑器打开docker-compose.yml，你会看到类似下面的结构（具体服务名可能不同）：

version: '3.8' services: mysql: image: mysql:8.0 environment: MYSQL_ROOT_PASSWORD: ${DB_PASSWORD} volumes: - ./data/mysql:/var/lib/mysql healthcheck: {...} redis: image: redis:7-alpine volumes: - ./data/redis:/data backend: build: ./backend # 或者 image: some-registry/wukong-backend:latest depends_on: - mysql - redis environment: - DATABASE_URL=mysql://root:${DB_PASSWORD}@mysql:3306/wukong_db ports: - "3000:3000" frontend: image: nginx:alpine volumes: - ./frontend/dist:/usr/share/nginx/html - ./nginx.conf:/etc/nginx/conf.d/default.conf depends_on: - backend ports: - "80:80"

你需要关注的点：

services：列出了所有容器。
imagevsbuild：image表示直接拉取现成的镜像；build表示需要根据当前目录下的 Dockerfile 构建镜像。对于“悟空 AICRM”，后端服务可能是build的，这意味着首次启动会慢一些，因为它要编译代码。
depends_on：定义了启动顺序。backend会等mysql和redis就绪后才启动。
environment：容器的环境变量，很多值（如${DB_PASSWORD}）会从.env文件读取。
volumes：将主机上的目录（如./data/mysql）挂载到容器内，这样数据可以持久化，即使容器删除，数据还在。
ports：端口映射。主机端口:容器端口。这里frontend把容器的 80 端口映射到主机的 80 端口，意味着你通过浏览器访问服务器的 IP 或域名就能打开前端。

3.2 配置环境变量 (.env 文件)

找到.env或复制example.env为.env。这是配置的核心。你需要修改的关键项通常包括：

# 数据库配置 DB_PASSWORD=YourStrongPassword123! # 改成高强度密码 DB_ROOT_PASSWORD=YourStrongRootPassword123! DB_DATABASE=wukong_db # Redis 配置（通常默认即可，除非你外部已有 Redis） REDIS_PASSWORD= # 后端服务配置 API_HOST=backend # Docker Compose 网络内服务名 API_PORT=3000 SECRET_KEY=generate_a_very_long_and_random_string_here # 用于加密，必须修改！ # 大模型 API 配置（例如，如果你使用 OpenAI 或国内大模型） OPENAI_API_KEY=sk-... # 如果你用 OpenAI # 或者国内模型的 API_KEY 和 BASE_URL API_KEY=your_api_key_here BASE_URL=https://api.openai.com/v1 # 根据模型提供商修改 # 前端访问地址（用于后端 API 调用） FRONTEND_URL=http://你的服务器IP或域名

修改要点：

所有密码（DB_PASSWORD,SECRET_KEY）必须修改，不要使用默认值或示例值。
大模型配置：这是 AICRM 的“智能”来源。你需要有一个可用的 LLM API 密钥（如 OpenAI、智谱、DeepSeek 等），并正确填写API_KEY和BASE_URL。如果暂时没有，可以先注释掉或留空，但对话功能可能无法使用。
FRONTEND_URL：如果是本地测试，可以设为http://localhost；如果是服务器部署，必须设为服务器的公网 IP 或域名（如http://123.123.123.123或http://aicrm.yourdomain.com）。

3.3 启动服务与观察日志

配置完成后，进入项目目录，启动服务：

cd ~/wukong-aicrm docker compose up -d

-d参数表示“后台运行”（detached mode）。
首次运行如果包含build，会下载基础镜像并构建项目镜像，耗时较长，请耐心等待。

启动后，立刻查看日志，这是排查问题的第一现场：

# 查看所有服务的综合日志 docker compose logs # 持续跟踪日志（类似 tail -f） docker compose logs -f # 只看某个服务的日志，例如后端 docker compose logs -f backend

在日志中，你需要关注以下成功信号：

mysql容器：出现mysqld: ready for connections。
redis容器：出现Ready to accept connections。
backend容器：这是关键。等待直到出现类似Application startup complete、Server started on port 3000、Connected to database的消息。如果后端依赖数据库，它可能会进行初始数据迁移（Migrating），看到Applying migration...是正常的。
frontend容器：Nginx 启动通常很快。

如果日志中有ERROR或持续重启，就需要根据错误信息排查。常见问题我们放在下一节。

3.4 验证服务是否正常运行

日志没有报错后，通过几种方式验证：

检查容器状态：
```
docker compose ps
```
所有服务的State栏应该显示为Up（或Up (healthy)）。
访问前端页面：
- 本地部署：打开浏览器，访问http://localhost。
- 服务器部署：访问http://你的服务器IP。
- 如果看到登录页、注册页或系统首页，说明前端和反向代理（Nginx）基本正常。
检查后端 API：
- 后端服务通常提供 API 文档（如 Swagger UI）或健康检查端点。尝试访问：
```
curl http://localhost:3000/health # 或 /api/health, /docs
```
- 如果返回{"status": "ok"}或类似的 JSON 响应，说明后端服务正常。
进入系统：
- 根据项目文档，使用默认管理员账号（如admin/admin123）或注册新账号登录。
- 登录后，尝试创建一个对话或知识库，测试核心功能是否连通。

4. 部署后必查：常见问题与深度排查指南

即使按照教程一步步来，也可能遇到问题。这里提供一个从外到内、从简单到复杂的排查顺序。

4.1 容器启动失败或不断重启

运行docker compose ps看到状态是Restarting或Exited。

第一步：看日志。docker compose logs [服务名]。错误信息最直接。
第二步：检查端口冲突。docker compose.yml中映射的端口（如80:80,3000:3000）可能被主机上其他程序占用。
```
# 查看端口占用 sudo netstat -tulpn | grep :80 sudo netstat -tulpn | grep :3000
```
- 如果被占用，要么停止占用程序，要么在docker-compose.yml中修改主机端口，例如将"80:80"改为"8080:80"，然后通过http://localhost:8080访问。
第三步：检查.env配置。特别是密码、API Key、URL 等是否填写正确，是否有特殊字符需要转义。一个快速验证方法是进入容器内部检查环境变量：
```
docker compose exec backend env | grep KEY
```
第四步：检查数据卷权限。如果日志提示Permission denied关于/var/lib/mysql等目录，可能是挂载的本地目录（./data/mysql）权限不对。确保 Docker 进程（通常是root或docker组）有读写权限。可以尝试：
```
sudo chown -R 999:999 ./data/mysql # MySQL 容器内通常以 999 用户运行 # 或者更粗暴但有效的方式 sudo chmod -R 777 ./data # 注意，这有安全风险，仅用于快速测试
```
第五步：资源不足。如果机器内存不足，MySQL 或后端应用可能因 OOM（Out Of Memory）被系统杀死。查看系统日志dmesg | grep -i kill或使用docker stats观察容器资源占用。

4.2 前端能打开，但登录/操作报错（如 502 Bad Gateway）

这通常意味着前端（Nginx）无法连接到后端服务。

第一步：确认后端服务是否真的在运行。docker compose ps看backend状态是否为Up。docker compose logs backend看是否有应用启动成功的日志。
第二步：检查 Nginx 配置。docker-compose.yml中frontend服务挂载了./nginx.conf。检查这个文件里的proxy_pass指令，是否指向了正确的后端服务名和端口。在 Docker Compose 网络中，应该使用服务名（如http://backend:3000），而不是localhost。
第三步：测试后端连通性。从 Nginx 容器内部测试是否能访问后端。
```
docker compose exec frontend curl -v http://backend:3000/health
```
- 如果失败，检查 Docker 网络：docker network ls和docker network inspect [网络名]，确保frontend和backend容器在同一个用户定义的网络中（默认由 Compose 创建）。
第四步：检查环境变量FRONTEND_URL。这个变量可能被后端用于构建 CORS（跨域）头或生成链接。如果设置错误，可能导致 API 请求被浏览器阻止。确保它与浏览器访问的地址一致。

4.3 大模型对话功能无效或报错

这是 AICRM 的核心，也是最容易出问题的地方。

第一步：检查 API 配置。确认.env文件中的API_KEY和BASE_URL绝对正确。对于国内用户，如果使用 OpenAI 官方接口，需要确认网络连通性。如果使用国内镜像或厂商，BASE_URL必须对应修改。
第二步：查看后端日志。发起一次对话请求，然后立刻查看后端日志：
```
docker compose logs --tail=100 backend
```
寻找关于调用 LLM API 的日志。常见的错误有：
- Invalid API Key：密钥错误或过期。
- Connection timeout或Network error：网络不通，无法访问BASE_URL。
- Rate limit exceeded：调用频率超限。
- Model not found：请求的模型名称不对。
第三步：手动测试 API 连通性。你可以在服务器上用一个简单的curl命令测试你的 API 密钥是否有效（注意保护密钥）：
```
curl https://api.openai.com/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" \ -d '{ "model": "gpt-3.5-turbo", "messages": [{"role": "user", "content": "Hello!"}], "max_tokens": 5 }'
```
- 如果这个命令都失败，那就是网络或密钥问题，与 AICRM 本身无关。
第四步：检查项目配置。有些项目可能在后端代码或另外的配置文件中指定模型名称。检查项目文档，看是否需要修改model参数。

4.4 数据库连接问题

后端日志出现Can't connect to MySQL server或Access denied for user。

第一步：检查数据库容器状态和日志。docker compose logs mysql。
第二步：验证连接参数。确保.env中的DB_PASSWORD与docker-compose.yml中mysql服务的MYSQL_ROOT_PASSWORD环境变量一致。同时检查DATABASE_URL或类似配置中的主机名（应为mysql）、端口（3306）、数据库名（wukong_db）是否正确。
第三步：手动连接测试。进入 MySQL 容器内部，尝试用配置的密码连接：
```
docker compose exec mysql mysql -uroot -p # 输入 .env 中配置的 DB_PASSWORD
```
- 如果连接失败，说明密码错误或 MySQL 未正常启动。
- 连接成功后，检查数据库是否已创建：SHOW DATABASES;，看是否有wukong_db。

4.5 性能与优化建议

当服务跑起来后，你可能会关心它的表现。

资源监控：使用docker stats可以实时查看各容器的 CPU、内存、网络 I/O 使用情况。重点关注backend和mysql容器。
数据库优化：如果数据量增大后感觉变慢，可以考虑为 MySQL 容器增加配置，例如通过挂载自定义my.cnf文件来调整缓冲区大小。

镜像清理：多次构建和更新后，会产生很多悬空镜像，占用磁盘空间。定期清理：

docker system prune -f # 清理未使用的镜像、容器、网络 docker volume prune -f # 清理未使用的数据卷（谨慎！确保数据已备份）

备份数据：你的数据（数据库、上传的文件）保存在./data目录（根据你的卷挂载配置）。定期备份这个目录。最简单的备份方式就是压缩复制：
```
tar -czf aicrm-backup-$(date +%Y%m%d).tar.gz ./data
```
升级版本：如果需要升级“悟空 AICRM”版本，通常的步骤是：
1. 备份数据和当前配置（.env,docker-compose.yml）。
2. 拉取最新的代码或镜像。
3. 比较新旧docker-compose.yml，看服务定义有无重大变化。
4. 停止服务：docker compose down。
5. 重新拉取/构建镜像：docker compose pull或docker compose build。
6. 启动服务：docker compose up -d。
7. 观察日志，检查数据迁移是否正常。