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 ar /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_URLmysql://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列出了所有容器。imagevsbuildimage表示直接拉取现成的镜像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_PASSWORDYourStrongPassword123! # 改成高强度密码 DB_ROOT_PASSWORDYourStrongRootPassword123! DB_DATABASEwukong_db # Redis 配置通常默认即可除非你外部已有 Redis REDIS_PASSWORD # 后端服务配置 API_HOSTbackend # Docker Compose 网络内服务名 API_PORT3000 SECRET_KEYgenerate_a_very_long_and_random_string_here # 用于加密必须修改 # 大模型 API 配置例如如果你使用 OpenAI 或国内大模型 OPENAI_API_KEYsk-... # 如果你用 OpenAI # 或者国内模型的 API_KEY 和 BASE_URL API_KEYyour_api_key_here BASE_URLhttps://api.openai.com/v1 # 根据模型提供商修改 # 前端访问地址用于后端 API 调用 FRONTEND_URLhttp://你的服务器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 或后端应用可能因 OOMOut 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 --tail100 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 数据库连接问题后端日志出现Cant 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”版本通常的步骤是备份数据和当前配置.env,docker-compose.yml。拉取最新的代码或镜像。比较新旧docker-compose.yml看服务定义有无重大变化。停止服务docker compose down。重新拉取/构建镜像docker compose pull或docker compose build。启动服务docker compose up -d。观察日志检查数据迁移是否正常。部署这类整合性项目最大的经验就是耐心看日志。90% 的问题都能在日志中找到线索。按照从底层Docker 环境、端口、权限到中层容器网络、配置变量再到上层应用逻辑、API 调用的顺序排查大部分部署难题都能解决。
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 ar /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_URLmysql://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列出了所有容器。imagevsbuildimage表示直接拉取现成的镜像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_PASSWORDYourStrongPassword123! # 改成高强度密码 DB_ROOT_PASSWORDYourStrongRootPassword123! DB_DATABASEwukong_db # Redis 配置通常默认即可除非你外部已有 Redis REDIS_PASSWORD # 后端服务配置 API_HOSTbackend # Docker Compose 网络内服务名 API_PORT3000 SECRET_KEYgenerate_a_very_long_and_random_string_here # 用于加密必须修改 # 大模型 API 配置例如如果你使用 OpenAI 或国内大模型 OPENAI_API_KEYsk-... # 如果你用 OpenAI # 或者国内模型的 API_KEY 和 BASE_URL API_KEYyour_api_key_here BASE_URLhttps://api.openai.com/v1 # 根据模型提供商修改 # 前端访问地址用于后端 API 调用 FRONTEND_URLhttp://你的服务器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 或后端应用可能因 OOMOut 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 --tail100 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 数据库连接问题后端日志出现Cant 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”版本通常的步骤是备份数据和当前配置.env,docker-compose.yml。拉取最新的代码或镜像。比较新旧docker-compose.yml看服务定义有无重大变化。停止服务docker compose down。重新拉取/构建镜像docker compose pull或docker compose build。启动服务docker compose up -d。观察日志检查数据迁移是否正常。部署这类整合性项目最大的经验就是耐心看日志。90% 的问题都能在日志中找到线索。按照从底层Docker 环境、端口、权限到中层容器网络、配置变量再到上层应用逻辑、API 调用的顺序排查大部分部署难题都能解决。
