如果你正在寻找一个能真正帮你提升销售效率、让客户跟进自动化的 AI 工具但又被复杂的本地部署和 API 集成搞得头大那么 Wukong AICRM 的 Docker 一键安装方案可能就是你现在最需要的“解药”。市面上很多 AI 工具要么是 SaaS 服务数据安全让你心存疑虑要么是开源项目部署过程堪比“从零造轮子”劝退无数非专业运维的销售团队或中小开发者。Wukong AICRM 瞄准的正是这个痛点它提供了一个功能相对完整的 AI 驱动客户关系管理原型而 Docker 化部署则将复杂的 Python 环境、模型依赖、数据库初始化等步骤封装成了几条简单的命令。这篇文章不会只告诉你“运行docker-compose up就行”。我们将深入拆解 Wukong AICRM 通过 Docker 部署的完整流程从 Docker 环境准备、镜像拉取与配置、到服务启动验证和初步使用。更重要的是我会结合常见的实战踩坑经验告诉你哪些配置项决定了能否成功运行初次登录后应该先检查什么以及当容器启动失败时如何像老手一样快速定位问题根源。无论你是想快速体验 AI CRM 的能力还是为后续二次开发搭建基础环境这份详尽的指南都能让你绕过我当初摸索时遇到的那些“坑”。1. Wukong AICRM 是什么为什么 Docker 部署是首选在深入安装步骤之前我们有必要先厘清 Wukong AICRM 的核心定位。它并非一个成熟的企业级 CRM 产品如 Salesforce、HubSpot而是一个开源、AI 驱动的客户关系管理演示或原型系统。它的价值在于集成了大语言模型LLM能力能够自动化完成诸如客户意向分析、智能回复建议、销售话术生成等任务为开发者或技术型销售团队提供一个可研究、可修改的 AI 应用样板。那么为什么官方文档和社区都强烈推荐使用 Docker 部署呢原因有三点环境一致性难题迎刃而解Wukong AICRM 通常依赖特定的 Python 版本、第三方库如 LangChain、向量数据库客户端、以及可能需要的 AI 模型服务。手动在物理机或虚拟机上配置极易出现“在我机器上能跑”的环境冲突。Docker 容器提供了隔离的、标准化的运行环境确保应用在任何支持 Docker 的系统中行为一致。复杂度封装一键启动一个完整的 AI 应用栈可能包含 Web 前端、后端 API 服务、数据库、缓存、向量数据库等多个组件。Docker Compose 工具允许你用一个docker-compose.yml文件定义所有服务及其依赖关系通过一条命令启动整个生态极大地降低了部署门槛。利于隔离和清理Docker 容器是临时的。当你只是想体验或测试时完事后可以轻松地停止并删除所有容器甚至删除镜像而不会在宿主机上留下各种配置文件、数据库文件或依赖包保持系统清洁。对于绝大多数用户目标就是最快、最稳地看到系统跑起来。因此遵循“Docker 一键安装”的路径是最务实的选择。除非你计划进行深度的源码级二次开发否则不建议初期就涉足手动源码安装。2. 安装前的核心准备理解架构与检查清单在运行任何命令之前花几分钟理解你将启动什么以及你的机器需要满足什么条件能避免很多盲目操作导致的失败。2.1 Wukong AICRM Docker 部署的典型架构根据开源项目的通用模式一个基于 Docker Compose 的 Wukong AICRM 部署可能包含以下服务具体以项目最新docker-compose.yml为准app或web服务核心后端应用使用 Python可能是 FastAPI 或 Django编写提供 RESTful API。frontend服务基于 Vue.js 或 React 的前端界面用户通过浏览器与此交互。database服务通常是一个 PostgreSQL 或 MySQL 容器用于存储结构化数据用户、客户、跟进记录等。vector-db服务可选但常见如 Redis 或 Qdrant 等用于存储和检索客户对话、文档的向量嵌入以实现 AI 语义搜索。llm-api或proxy服务可能集成或需配置用于连接 OpenAI API、通义千问、DeepSeek 或其他大模型服务的网关或适配器。这些服务通过 Docker 网络互联前端访问后端 API后端访问数据库和向量数据库。你的任务就是用一份配置文件把它们全部协调起来。2.2 系统与环境检查清单请逐项确认你的环境这是成功的第一步。检查项要求如何检查/安装操作系统Linux (Ubuntu 20.04/CentOS 7), macOS, Windows 10/11 (WSL2)uname -a或系统信息Docker 引擎Docker Engine 20.10docker --versionDocker ComposeDocker Compose V2推荐docker compose version磁盘空间至少 5-10 GB 可用空间df -h(Linux/macOS)内存建议 8 GB 或以上4 GB 是最低门槛系统任务管理器网络能稳定访问 Docker Hub 和可能的外部 AI API如 OpenAIping hub.docker.com重点说明Windows/macOS 用户请直接安装Docker Desktop它包含了 Docker Engine、Docker Compose 和图形化管理工具。确保在设置中启用了 WSL2 后端Windows或 VirtioFS 加速macOS。Linux 用户可通过包管理器apt,yum安装 Docker 和 Docker Compose 插件。网络问题如果你在国内从 Docker Hub 拉取镜像可能较慢。建议配置国内镜像加速器。对于需要访问 OpenAI 等境外 API 的服务需确保网络环境允许。3. 实战第一步获取与配置 Wukong AICRM 的 Docker 部署文件通常开源项目会提供标准的 Docker 部署文件。我们需要找到并理解它们。3.1 克隆项目代码仓库最可靠的方式是从官方代码仓库如 GitHub、GitCode、Gitee获取最新代码。# 假设项目仓库在 GitCode 上 git clone https://gitcode.com/your-org/wukong-aicrm.git cd wukong-aicrm # 或者如果提供了直接下载链接 # wget https://example.com/wukong-aicrm-docker.zip unzip wukong-aicrm-docker.zip进入项目根目录后寻找以下关键文件docker-compose.yml核心编排文件定义了所有服务。Dockerfile用于构建自定义应用镜像的文件如果有一键脚本可能不需要手动构建。.env.example或config.example.yaml环境变量或配置文件模板。README.md最重要的文档包含最新的安装说明和配置要求。3.2 解析与修改 docker-compose.yml让我们以一个简化的、典型的docker-compose.yml为例进行解读version: 3.8 services: postgres: image: postgres:15-alpine container_name: wukong-postgres environment: POSTGRES_DB: wukongcrm POSTGRES_USER: wukong POSTGRES_PASSWORD: ${DB_PASSWORD:-your_strong_password_here} # 从环境变量读取 volumes: - postgres_data:/var/lib/postgresql/data ports: - 5432:5432 # 主机端口:容器端口可按需修改主机端口避免冲突 networks: - wukong-network healthcheck: test: [CMD-SHELL, pg_isready -U wukong] interval: 10s timeout: 5s retries: 5 redis: image: redis:7-alpine container_name: wukong-redis command: redis-server --appendonly yes volumes: - redis_data:/data ports: - 6379:6379 networks: - wukong-network app: build: ./backend # 指向后端代码目录Dockerfile 在此 container_name: wukong-app depends_on: postgres: condition: service_healthy # 等待数据库健康检查通过 redis: condition: service_started environment: - DATABASE_URLpostgresql://wukong:${DB_PASSWORD:-your_strong_password_here}postgres:5432/wukongcrm - REDIS_URLredis://redis:6379/0 - OPENAI_API_KEY${OPENAI_API_KEY} # 关键需要你提供 - LLM_BASE_URL${LLM_BASE_URL:-https://api.openai.com/v1} # 可配置其他兼容API volumes: - ./backend:/app # 开发时挂载源码热重载 - ./data:/app/data # 挂载数据卷 ports: - 8000:8000 networks: - wukong-network frontend: build: ./frontend # 指向前端代码目录 container_name: wukong-frontend depends_on: - app environment: - VITE_API_BASE_URLhttp://app:8000/api/v1 # 内部网络地址 ports: - 3000:3000 networks: - wukong-network networks: wukong-network: driver: bridge volumes: postgres_data: redis_data:关键修改点密码安全${DB_PASSWORD}和${OPENAI_API_KEY}是环境变量占位符。绝对不要将明文密码写在docker-compose.yml中。正确做法是创建一个.env文件。端口冲突如果宿主机 5432、6379、8000、3000 端口已被占用需要修改ports映射左侧的主机端口例如5433:5432。AI 模型配置OPENAI_API_KEY是必填项。如果你使用其他模型如通义千问、DeepSeek、本地部署的 Ollama则需要修改LLM_BASE_URL和对应的 API Key 环境变量名。3.3 配置环境变量文件 (.env)在docker-compose.yml同级目录下创建.env文件# .env 文件 # 数据库配置 DB_PASSWORDa_very_strong_and_secret_password_123! # AI 模型配置 (以 OpenAI 为例) OPENAI_API_KEYsk-your-actual-openai-api-key-here # 如果使用其他兼容API例如 DeepSeek # DEEPSEEK_API_KEYyour-deepseek-key # LLM_BASE_URLhttps://api.deepseek.com LLM_BASE_URLhttps://api.openai.com/v1 # 应用密钥用于JWT等可生成随机字符串 APP_SECRET_KEY$(openssl rand -hex 32) # 前端API地址供浏览器访问 PUBLIC_API_BASE_URLhttp://localhost:8000重要安全提示.env文件包含敏感信息务必将其添加到.gitignore中避免提交到代码仓库。APP_SECRET_KEY可以使用命令openssl rand -hex 32生成一个随机字符串。4. 核心流程启动服务与初始化配置完成后启动服务就相对简单了。4.1 启动所有服务使用 Docker Compose 命令在后台启动所有服务# 在包含 docker-compose.yml 和 .env 的目录下执行 docker compose up -d-d参数代表“detached”让容器在后台运行。命令执行后Docker 会拉取所需的公共镜像如postgres:15-alpine,redis:7-alpine。根据Dockerfile构建自定义镜像app,frontend。按依赖顺序启动容器并建立网络连接。4.2 查看服务状态与日志启动后立即检查服务是否正常运行# 查看所有容器状态 docker compose ps # 预期看到所有服务的 State 为 “Up” # 如果状态是 “Exit” 或 “Restarting”说明启动失败。 # 查看所有服务的实时日志组合视图 docker compose logs -f # 查看特定服务如 app的日志 docker compose logs -f app关键排查点启动失败时90%的问题可以通过日志发现。常见错误包括数据库连接失败检查.env中的DB_PASSWORD是否与docker-compose.yml中的配置一致检查 PostgreSQL 容器健康状态。AI API 连接失败检查OPENAI_API_KEY是否正确、是否有余额、网络是否通畅。如果使用代理可能需要在应用配置中设置。端口冲突检查日志中是否有address already in use错误。依赖缺失构建镜像时可能因为网络问题导致pip install失败。4.3 执行数据库迁移关键步骤很多 Web 应用尤其是 Django、Laravel、某些 FastAPI 项目在首次启动时需要执行数据库迁移Migration来创建数据表结构。这通常不会自动完成。你需要进入app容器内部执行迁移命令# 进入 app 容器的交互式 shell docker compose exec app sh # 或 bash取决于基础镜像 # docker compose exec app bash # 在容器内部执行迁移命令具体命令需参考项目 README # 假设是 Alembic (Python SQLAlchemy) alembic upgrade head # 或者如果是 Django python manage.py migrate # 执行完毕后退出容器 exit为什么这步很重要如果不执行迁移数据库是空的应用启动后访问 API 或前端可能会遇到500 Internal Server Error或relation “xxx” does not exist的错误。4.4 创建超级管理员用户可选但推荐同样许多系统需要创建一个初始管理员账户才能登录后台。docker compose exec app sh # 示例Django 创建超级用户 python manage.py createsuperuser # 然后根据提示输入用户名、邮箱和密码 exit5. 验证部署访问系统与功能测试当所有容器状态为Up日志没有持续报错后就可以验证部署成果了。访问前端界面打开浏览器访问http://localhost:3000根据你docker-compose.yml中frontend服务的端口映射。你应该能看到登录或注册界面。访问后端 API 文档通常基于 FastAPI 或 Django REST Framework 的后端会提供自动生成的 API 文档。访问http://localhost:8000/docs或http://localhost:8000/api/docs。如果能打开 Swagger UI 或 ReDoc 页面说明后端服务运行正常。测试基础功能使用上一步创建的超级用户账号登录前端。尝试创建一个“客户”或“线索”。尝试使用 AI 功能例如“生成跟进话术”或“分析客户需求”。注意首次使用 AI 功能可能会较慢因为需要调用外部 API。6. 常见问题与详细排查指南即使按照步骤操作也可能遇到问题。下表列出了常见问题及解决方法。问题现象可能原因排查步骤解决方案docker compose up失败提示build错误1. Dockerfile 语法错误。2. 构建时网络问题依赖下载失败。3. 基础镜像不存在。1. 查看docker compose logs中app或frontend构建阶段的错误输出。2. 尝试单独构建镜像docker build -t my-app ./backend。1. 检查项目 Dockerfile 是否完整。2. 更换 pip/apt 源为国内镜像或使用代理。3. 确认 Dockerfile 中FROM的镜像名和标签正确。容器启动后立即退出 (Exited (1))1. 应用启动脚本错误。2. 关键环境变量缺失或错误。3. 依赖服务如数据库未就绪。1.docker compose logs service-name查看退出前的最后日志。2.docker compose exec service-name sh尝试进入容器如果进得去。1. 检查docker-compose.yml中command或entrypoint。2. 确认.env文件已创建且变量名正确。3. 为app服务添加depends_on健康检查或使用restart: unless-stopped策略。前端能打开但登录/请求 API 报错Network Error或5021. 前端配置的 API 地址错误。2. 后端服务 (app) 未运行或崩溃。3. 后端服务端口未暴露或映射错误。1. 浏览器开发者工具 (F12) 查看 Network 标签页确认请求的 URL。2.docker compose ps确认app服务状态。3.curl http://localhost:8000/health测试后端是否响应。1. 检查前端环境变量VITE_API_BASE_URL或配置确保指向正确的后端地址容器内为http://app:8000生产环境需改。2. 修复后端启动问题。3. 检查docker-compose.yml中app服务的ports映射。执行数据库操作时日志报错relation “xxx” does not exist数据库迁移未执行。进入app容器检查数据库是否有表。docker compose exec app python -c “from app.database import engine; print(engine.table_names())”执行数据库迁移。参考上文第 4.3 节。AI 功能无响应或报错Invalid API Key1.OPENAI_API_KEY未设置或错误。2. 网络无法访问 OpenAI API。3. API Key 余额不足或过期。1. docker compose exec app envgrep OPENAI确认环境变量已传入。br2. 在宿主机或容器内curl https://api.openai.com/v1/models 测试连通性需带正确 Header。访问localhost:3000被拒绝1. 前端容器未运行。2. 端口映射错误或冲突。3. 防火墙/安全组阻止。1.docker compose ps查看frontend状态。2.docker port wukong-frontend查看实际映射端口。3. netstat -tulngrep :3000 查看端口监听情况。7. 生产环境部署与安全最佳实践上述流程适合本地开发和测试。如果计划用于小团队内网或生产环境必须考虑以下安全与稳定性增强措施使用独立的 Docker 网络在docker-compose.yml中可以定义自定义的桥接网络或使用外部网络避免与宿主机或其他应用网络冲突。数据持久化与备份确保数据库postgres_data和 Redisredis_data的卷volumes映射到了宿主机的可靠存储路径并定期备份。volumes: postgres_data: driver: local driver_opts: type: none o: bind device: /path/to/your/data/postgres # 指定宿主机路径强化安全配置修改默认端口将 PostgreSQL (5432)、Redis (6379)、后端 API (8000) 的管理端口在宿主机上映射为不常用的高端口减少被扫描攻击的风险。使用强密码.env文件中的数据库密码、应用密钥必须使用强随机密码生成器生成。限制容器权限在docker-compose.yml中为服务添加security_opt和cap_drop选项降低容器逃逸风险。services: app: # ... security_opt: - no-new-privileges:true cap_drop: - ALL cap_add: - NET_BIND_SERVICE # 仅授予绑定端口所需的最小权限配置 HTTPS生产环境前端必须通过 HTTPS 访问。可以使用 Nginx 或 Traefik 作为反向代理配置 SSL 证书。监控与日志收集使用docker compose logs只能查看近期日志。生产环境应配置日志驱动将容器日志发送到 ELKElasticsearch, Logstash, Kibana或 Loki 等集中日志系统。资源限制为每个容器设置 CPU 和内存限制防止单个服务异常耗尽主机资源。services: app: # ... deploy: resources: limits: cpus: 1.0 memory: 2G reservations: cpus: 0.5 memory: 1G8. 后续开发与维护指南成功部署后你可能会考虑以下步骤更新代码如果项目代码更新需要重新构建镜像。docker compose down # 停止并删除容器数据卷会保留 git pull origin main # 拉取最新代码 docker compose build --no-cache app frontend # 重新构建应用镜像 docker compose up -d # 重新启动查看数据可以直接连接 PostgreSQL 容器进行数据查询。docker compose exec postgres psql -U wukong -d wukongcrm清理环境如果想彻底重置注意这会删除所有数据库数据。docker compose down -v # -v 参数会删除所有匿名数据卷 docker system prune -a # 谨慎这会删除所有未使用的镜像、容器、网络通过以上从环境准备、配置解析、启动验证到故障排查和进阶实践的完整流程你应该已经能够独立完成 Wukong AICRM 的 Docker 化部署。这个过程的真正价值不仅在于启动了一个 AI CRM 演示系统更在于你掌握了一套标准化、可复用的 Docker Compose 应用部署方法论。下次遇到任何一个提供docker-compose.yml的开源项目你都可以从容地将其运行起来快速体验核心功能这正是现代开发运维效率提升的关键所在。
Wukong AICRM Docker一键部署：从环境配置到生产实践全指南
发布时间：2026/7/25 10:47:39
如果你正在寻找一个能真正帮你提升销售效率、让客户跟进自动化的 AI 工具但又被复杂的本地部署和 API 集成搞得头大那么 Wukong AICRM 的 Docker 一键安装方案可能就是你现在最需要的“解药”。市面上很多 AI 工具要么是 SaaS 服务数据安全让你心存疑虑要么是开源项目部署过程堪比“从零造轮子”劝退无数非专业运维的销售团队或中小开发者。Wukong AICRM 瞄准的正是这个痛点它提供了一个功能相对完整的 AI 驱动客户关系管理原型而 Docker 化部署则将复杂的 Python 环境、模型依赖、数据库初始化等步骤封装成了几条简单的命令。这篇文章不会只告诉你“运行docker-compose up就行”。我们将深入拆解 Wukong AICRM 通过 Docker 部署的完整流程从 Docker 环境准备、镜像拉取与配置、到服务启动验证和初步使用。更重要的是我会结合常见的实战踩坑经验告诉你哪些配置项决定了能否成功运行初次登录后应该先检查什么以及当容器启动失败时如何像老手一样快速定位问题根源。无论你是想快速体验 AI CRM 的能力还是为后续二次开发搭建基础环境这份详尽的指南都能让你绕过我当初摸索时遇到的那些“坑”。1. Wukong AICRM 是什么为什么 Docker 部署是首选在深入安装步骤之前我们有必要先厘清 Wukong AICRM 的核心定位。它并非一个成熟的企业级 CRM 产品如 Salesforce、HubSpot而是一个开源、AI 驱动的客户关系管理演示或原型系统。它的价值在于集成了大语言模型LLM能力能够自动化完成诸如客户意向分析、智能回复建议、销售话术生成等任务为开发者或技术型销售团队提供一个可研究、可修改的 AI 应用样板。那么为什么官方文档和社区都强烈推荐使用 Docker 部署呢原因有三点环境一致性难题迎刃而解Wukong AICRM 通常依赖特定的 Python 版本、第三方库如 LangChain、向量数据库客户端、以及可能需要的 AI 模型服务。手动在物理机或虚拟机上配置极易出现“在我机器上能跑”的环境冲突。Docker 容器提供了隔离的、标准化的运行环境确保应用在任何支持 Docker 的系统中行为一致。复杂度封装一键启动一个完整的 AI 应用栈可能包含 Web 前端、后端 API 服务、数据库、缓存、向量数据库等多个组件。Docker Compose 工具允许你用一个docker-compose.yml文件定义所有服务及其依赖关系通过一条命令启动整个生态极大地降低了部署门槛。利于隔离和清理Docker 容器是临时的。当你只是想体验或测试时完事后可以轻松地停止并删除所有容器甚至删除镜像而不会在宿主机上留下各种配置文件、数据库文件或依赖包保持系统清洁。对于绝大多数用户目标就是最快、最稳地看到系统跑起来。因此遵循“Docker 一键安装”的路径是最务实的选择。除非你计划进行深度的源码级二次开发否则不建议初期就涉足手动源码安装。2. 安装前的核心准备理解架构与检查清单在运行任何命令之前花几分钟理解你将启动什么以及你的机器需要满足什么条件能避免很多盲目操作导致的失败。2.1 Wukong AICRM Docker 部署的典型架构根据开源项目的通用模式一个基于 Docker Compose 的 Wukong AICRM 部署可能包含以下服务具体以项目最新docker-compose.yml为准app或web服务核心后端应用使用 Python可能是 FastAPI 或 Django编写提供 RESTful API。frontend服务基于 Vue.js 或 React 的前端界面用户通过浏览器与此交互。database服务通常是一个 PostgreSQL 或 MySQL 容器用于存储结构化数据用户、客户、跟进记录等。vector-db服务可选但常见如 Redis 或 Qdrant 等用于存储和检索客户对话、文档的向量嵌入以实现 AI 语义搜索。llm-api或proxy服务可能集成或需配置用于连接 OpenAI API、通义千问、DeepSeek 或其他大模型服务的网关或适配器。这些服务通过 Docker 网络互联前端访问后端 API后端访问数据库和向量数据库。你的任务就是用一份配置文件把它们全部协调起来。2.2 系统与环境检查清单请逐项确认你的环境这是成功的第一步。检查项要求如何检查/安装操作系统Linux (Ubuntu 20.04/CentOS 7), macOS, Windows 10/11 (WSL2)uname -a或系统信息Docker 引擎Docker Engine 20.10docker --versionDocker ComposeDocker Compose V2推荐docker compose version磁盘空间至少 5-10 GB 可用空间df -h(Linux/macOS)内存建议 8 GB 或以上4 GB 是最低门槛系统任务管理器网络能稳定访问 Docker Hub 和可能的外部 AI API如 OpenAIping hub.docker.com重点说明Windows/macOS 用户请直接安装Docker Desktop它包含了 Docker Engine、Docker Compose 和图形化管理工具。确保在设置中启用了 WSL2 后端Windows或 VirtioFS 加速macOS。Linux 用户可通过包管理器apt,yum安装 Docker 和 Docker Compose 插件。网络问题如果你在国内从 Docker Hub 拉取镜像可能较慢。建议配置国内镜像加速器。对于需要访问 OpenAI 等境外 API 的服务需确保网络环境允许。3. 实战第一步获取与配置 Wukong AICRM 的 Docker 部署文件通常开源项目会提供标准的 Docker 部署文件。我们需要找到并理解它们。3.1 克隆项目代码仓库最可靠的方式是从官方代码仓库如 GitHub、GitCode、Gitee获取最新代码。# 假设项目仓库在 GitCode 上 git clone https://gitcode.com/your-org/wukong-aicrm.git cd wukong-aicrm # 或者如果提供了直接下载链接 # wget https://example.com/wukong-aicrm-docker.zip unzip wukong-aicrm-docker.zip进入项目根目录后寻找以下关键文件docker-compose.yml核心编排文件定义了所有服务。Dockerfile用于构建自定义应用镜像的文件如果有一键脚本可能不需要手动构建。.env.example或config.example.yaml环境变量或配置文件模板。README.md最重要的文档包含最新的安装说明和配置要求。3.2 解析与修改 docker-compose.yml让我们以一个简化的、典型的docker-compose.yml为例进行解读version: 3.8 services: postgres: image: postgres:15-alpine container_name: wukong-postgres environment: POSTGRES_DB: wukongcrm POSTGRES_USER: wukong POSTGRES_PASSWORD: ${DB_PASSWORD:-your_strong_password_here} # 从环境变量读取 volumes: - postgres_data:/var/lib/postgresql/data ports: - 5432:5432 # 主机端口:容器端口可按需修改主机端口避免冲突 networks: - wukong-network healthcheck: test: [CMD-SHELL, pg_isready -U wukong] interval: 10s timeout: 5s retries: 5 redis: image: redis:7-alpine container_name: wukong-redis command: redis-server --appendonly yes volumes: - redis_data:/data ports: - 6379:6379 networks: - wukong-network app: build: ./backend # 指向后端代码目录Dockerfile 在此 container_name: wukong-app depends_on: postgres: condition: service_healthy # 等待数据库健康检查通过 redis: condition: service_started environment: - DATABASE_URLpostgresql://wukong:${DB_PASSWORD:-your_strong_password_here}postgres:5432/wukongcrm - REDIS_URLredis://redis:6379/0 - OPENAI_API_KEY${OPENAI_API_KEY} # 关键需要你提供 - LLM_BASE_URL${LLM_BASE_URL:-https://api.openai.com/v1} # 可配置其他兼容API volumes: - ./backend:/app # 开发时挂载源码热重载 - ./data:/app/data # 挂载数据卷 ports: - 8000:8000 networks: - wukong-network frontend: build: ./frontend # 指向前端代码目录 container_name: wukong-frontend depends_on: - app environment: - VITE_API_BASE_URLhttp://app:8000/api/v1 # 内部网络地址 ports: - 3000:3000 networks: - wukong-network networks: wukong-network: driver: bridge volumes: postgres_data: redis_data:关键修改点密码安全${DB_PASSWORD}和${OPENAI_API_KEY}是环境变量占位符。绝对不要将明文密码写在docker-compose.yml中。正确做法是创建一个.env文件。端口冲突如果宿主机 5432、6379、8000、3000 端口已被占用需要修改ports映射左侧的主机端口例如5433:5432。AI 模型配置OPENAI_API_KEY是必填项。如果你使用其他模型如通义千问、DeepSeek、本地部署的 Ollama则需要修改LLM_BASE_URL和对应的 API Key 环境变量名。3.3 配置环境变量文件 (.env)在docker-compose.yml同级目录下创建.env文件# .env 文件 # 数据库配置 DB_PASSWORDa_very_strong_and_secret_password_123! # AI 模型配置 (以 OpenAI 为例) OPENAI_API_KEYsk-your-actual-openai-api-key-here # 如果使用其他兼容API例如 DeepSeek # DEEPSEEK_API_KEYyour-deepseek-key # LLM_BASE_URLhttps://api.deepseek.com LLM_BASE_URLhttps://api.openai.com/v1 # 应用密钥用于JWT等可生成随机字符串 APP_SECRET_KEY$(openssl rand -hex 32) # 前端API地址供浏览器访问 PUBLIC_API_BASE_URLhttp://localhost:8000重要安全提示.env文件包含敏感信息务必将其添加到.gitignore中避免提交到代码仓库。APP_SECRET_KEY可以使用命令openssl rand -hex 32生成一个随机字符串。4. 核心流程启动服务与初始化配置完成后启动服务就相对简单了。4.1 启动所有服务使用 Docker Compose 命令在后台启动所有服务# 在包含 docker-compose.yml 和 .env 的目录下执行 docker compose up -d-d参数代表“detached”让容器在后台运行。命令执行后Docker 会拉取所需的公共镜像如postgres:15-alpine,redis:7-alpine。根据Dockerfile构建自定义镜像app,frontend。按依赖顺序启动容器并建立网络连接。4.2 查看服务状态与日志启动后立即检查服务是否正常运行# 查看所有容器状态 docker compose ps # 预期看到所有服务的 State 为 “Up” # 如果状态是 “Exit” 或 “Restarting”说明启动失败。 # 查看所有服务的实时日志组合视图 docker compose logs -f # 查看特定服务如 app的日志 docker compose logs -f app关键排查点启动失败时90%的问题可以通过日志发现。常见错误包括数据库连接失败检查.env中的DB_PASSWORD是否与docker-compose.yml中的配置一致检查 PostgreSQL 容器健康状态。AI API 连接失败检查OPENAI_API_KEY是否正确、是否有余额、网络是否通畅。如果使用代理可能需要在应用配置中设置。端口冲突检查日志中是否有address already in use错误。依赖缺失构建镜像时可能因为网络问题导致pip install失败。4.3 执行数据库迁移关键步骤很多 Web 应用尤其是 Django、Laravel、某些 FastAPI 项目在首次启动时需要执行数据库迁移Migration来创建数据表结构。这通常不会自动完成。你需要进入app容器内部执行迁移命令# 进入 app 容器的交互式 shell docker compose exec app sh # 或 bash取决于基础镜像 # docker compose exec app bash # 在容器内部执行迁移命令具体命令需参考项目 README # 假设是 Alembic (Python SQLAlchemy) alembic upgrade head # 或者如果是 Django python manage.py migrate # 执行完毕后退出容器 exit为什么这步很重要如果不执行迁移数据库是空的应用启动后访问 API 或前端可能会遇到500 Internal Server Error或relation “xxx” does not exist的错误。4.4 创建超级管理员用户可选但推荐同样许多系统需要创建一个初始管理员账户才能登录后台。docker compose exec app sh # 示例Django 创建超级用户 python manage.py createsuperuser # 然后根据提示输入用户名、邮箱和密码 exit5. 验证部署访问系统与功能测试当所有容器状态为Up日志没有持续报错后就可以验证部署成果了。访问前端界面打开浏览器访问http://localhost:3000根据你docker-compose.yml中frontend服务的端口映射。你应该能看到登录或注册界面。访问后端 API 文档通常基于 FastAPI 或 Django REST Framework 的后端会提供自动生成的 API 文档。访问http://localhost:8000/docs或http://localhost:8000/api/docs。如果能打开 Swagger UI 或 ReDoc 页面说明后端服务运行正常。测试基础功能使用上一步创建的超级用户账号登录前端。尝试创建一个“客户”或“线索”。尝试使用 AI 功能例如“生成跟进话术”或“分析客户需求”。注意首次使用 AI 功能可能会较慢因为需要调用外部 API。6. 常见问题与详细排查指南即使按照步骤操作也可能遇到问题。下表列出了常见问题及解决方法。问题现象可能原因排查步骤解决方案docker compose up失败提示build错误1. Dockerfile 语法错误。2. 构建时网络问题依赖下载失败。3. 基础镜像不存在。1. 查看docker compose logs中app或frontend构建阶段的错误输出。2. 尝试单独构建镜像docker build -t my-app ./backend。1. 检查项目 Dockerfile 是否完整。2. 更换 pip/apt 源为国内镜像或使用代理。3. 确认 Dockerfile 中FROM的镜像名和标签正确。容器启动后立即退出 (Exited (1))1. 应用启动脚本错误。2. 关键环境变量缺失或错误。3. 依赖服务如数据库未就绪。1.docker compose logs service-name查看退出前的最后日志。2.docker compose exec service-name sh尝试进入容器如果进得去。1. 检查docker-compose.yml中command或entrypoint。2. 确认.env文件已创建且变量名正确。3. 为app服务添加depends_on健康检查或使用restart: unless-stopped策略。前端能打开但登录/请求 API 报错Network Error或5021. 前端配置的 API 地址错误。2. 后端服务 (app) 未运行或崩溃。3. 后端服务端口未暴露或映射错误。1. 浏览器开发者工具 (F12) 查看 Network 标签页确认请求的 URL。2.docker compose ps确认app服务状态。3.curl http://localhost:8000/health测试后端是否响应。1. 检查前端环境变量VITE_API_BASE_URL或配置确保指向正确的后端地址容器内为http://app:8000生产环境需改。2. 修复后端启动问题。3. 检查docker-compose.yml中app服务的ports映射。执行数据库操作时日志报错relation “xxx” does not exist数据库迁移未执行。进入app容器检查数据库是否有表。docker compose exec app python -c “from app.database import engine; print(engine.table_names())”执行数据库迁移。参考上文第 4.3 节。AI 功能无响应或报错Invalid API Key1.OPENAI_API_KEY未设置或错误。2. 网络无法访问 OpenAI API。3. API Key 余额不足或过期。1. docker compose exec app envgrep OPENAI确认环境变量已传入。br2. 在宿主机或容器内curl https://api.openai.com/v1/models 测试连通性需带正确 Header。访问localhost:3000被拒绝1. 前端容器未运行。2. 端口映射错误或冲突。3. 防火墙/安全组阻止。1.docker compose ps查看frontend状态。2.docker port wukong-frontend查看实际映射端口。3. netstat -tulngrep :3000 查看端口监听情况。7. 生产环境部署与安全最佳实践上述流程适合本地开发和测试。如果计划用于小团队内网或生产环境必须考虑以下安全与稳定性增强措施使用独立的 Docker 网络在docker-compose.yml中可以定义自定义的桥接网络或使用外部网络避免与宿主机或其他应用网络冲突。数据持久化与备份确保数据库postgres_data和 Redisredis_data的卷volumes映射到了宿主机的可靠存储路径并定期备份。volumes: postgres_data: driver: local driver_opts: type: none o: bind device: /path/to/your/data/postgres # 指定宿主机路径强化安全配置修改默认端口将 PostgreSQL (5432)、Redis (6379)、后端 API (8000) 的管理端口在宿主机上映射为不常用的高端口减少被扫描攻击的风险。使用强密码.env文件中的数据库密码、应用密钥必须使用强随机密码生成器生成。限制容器权限在docker-compose.yml中为服务添加security_opt和cap_drop选项降低容器逃逸风险。services: app: # ... security_opt: - no-new-privileges:true cap_drop: - ALL cap_add: - NET_BIND_SERVICE # 仅授予绑定端口所需的最小权限配置 HTTPS生产环境前端必须通过 HTTPS 访问。可以使用 Nginx 或 Traefik 作为反向代理配置 SSL 证书。监控与日志收集使用docker compose logs只能查看近期日志。生产环境应配置日志驱动将容器日志发送到 ELKElasticsearch, Logstash, Kibana或 Loki 等集中日志系统。资源限制为每个容器设置 CPU 和内存限制防止单个服务异常耗尽主机资源。services: app: # ... deploy: resources: limits: cpus: 1.0 memory: 2G reservations: cpus: 0.5 memory: 1G8. 后续开发与维护指南成功部署后你可能会考虑以下步骤更新代码如果项目代码更新需要重新构建镜像。docker compose down # 停止并删除容器数据卷会保留 git pull origin main # 拉取最新代码 docker compose build --no-cache app frontend # 重新构建应用镜像 docker compose up -d # 重新启动查看数据可以直接连接 PostgreSQL 容器进行数据查询。docker compose exec postgres psql -U wukong -d wukongcrm清理环境如果想彻底重置注意这会删除所有数据库数据。docker compose down -v # -v 参数会删除所有匿名数据卷 docker system prune -a # 谨慎这会删除所有未使用的镜像、容器、网络通过以上从环境准备、配置解析、启动验证到故障排查和进阶实践的完整流程你应该已经能够独立完成 Wukong AICRM 的 Docker 化部署。这个过程的真正价值不仅在于启动了一个 AI CRM 演示系统更在于你掌握了一套标准化、可复用的 Docker Compose 应用部署方法论。下次遇到任何一个提供docker-compose.yml的开源项目你都可以从容地将其运行起来快速体验核心功能这正是现代开发运维效率提升的关键所在。
