Chatwoot开源客服系统Docker部署全攻略：从零搭建到邮件配置

Chatwoot开源客服系统Docker部署实战从零搭建到邮件服务集成在当今数字化客户服务领域开源解决方案正成为企业降本增效的重要选择。Chatwoot作为一款现代化的开源客服平台以其多渠道集成、自动化工作流和实时分析功能脱颖而出。本文将带您完成一次完整的Docker化部署之旅涵盖从基础环境搭建到邮件服务集成的全流程特别针对国内开发者常见的配置痛点提供解决方案。1. 环境准备与Docker配置部署Chatwoot前需要确保宿主机已安装Docker Engine≥20.10.7和Docker Compose≥1.29.2。推荐使用Linux发行版作为宿主系统以下操作以Ubuntu 22.04 LTS为例# 验证Docker环境 docker --version docker-compose --version # 创建项目目录结构 mkdir -p chatwoot/{postgres,redis,app/{log,tmp,storage}}关键的目录权限设置往往被忽视这可能导致容器运行时出现写入失败sudo chown -R 1000:1000 chatwoot/app sudo chmod -R 755 chatwoot/app接下来创建核心配置文件docker-compose.yml这里我们采用多服务分离的架构设计version: 3.8 services: postgres: image: postgres:14-alpine container_name: chatwoot-db volumes: - ./postgres:/var/lib/postgresql/data environment: POSTGRES_PASSWORD: ${DB_PASSWORD} POSTGRES_USER: chatwoot POSTGRES_DB: chatwoot_production healthcheck: test: [CMD-SHELL, pg_isready -U chatwoot] interval: 5s timeout: 5s retries: 5 redis: image: redis:6.2-alpine container_name: chatwoot-cache command: [redis-server, --requirepass ${REDIS_PASSWORD}] volumes: - ./redis:/data healthcheck: test: [CMD, redis-cli, ping] app: image: chatwoot/chatwoot:latest depends_on: postgres: condition: service_healthy redis: condition: service_healthy ports: - 3000:3000 volumes: - ./app/storage:/app/storage - ./app/tmp:/app/tmp - ./app/log:/app/log env_file: - .env restart: unless-stopped2. 关键环境变量配置创建.env文件存放敏感配置这是国内开发者最容易出错的环节。以下是经过验证的安全配置模板# 安全密钥使用openssl生成 SECRET_KEY_BASE$(openssl rand -hex 64) # 网络配置需替换实际域名 FRONTEND_URLhttps://support.yourdomain.com FORCE_SSLtrue # 数据库连接 POSTGRES_HOSTpostgres POSTGRES_USERNAMEchatwoot POSTGRES_PASSWORD${DB_PASSWORD} RAILS_ENVproduction # Redis配置 REDIS_URLredis://:${REDIS_PASSWORD}redis:6379/1 REDIS_PASSWORD$(openssl rand -base64 32) # 账户策略 ENABLE_ACCOUNT_SIGNUPfalse DEFAULT_LOCALEzh-CN特别提醒几个关键点SECRET_KEY_BASE每次部署必须重新生成Redis密码需包含大小写字母、数字和特殊字符生产环境务必禁用ENABLE_ACCOUNT_SIGNUP3. 系统初始化与启动配置完成后按顺序执行以下命令完成初始化# 拉取镜像并构建服务 docker-compose pull # 数据库迁移关键步骤 docker-compose run --rm app bundle exec rails db:chatwoot_prepare # 启动所有服务 docker-compose up -d # 查看实时日志 docker-compose logs -f app常见问题排查技巧数据库连接失败docker exec -it chatwoot-db psql -U chatwoot \l # 查看数据库列表Redis认证问题docker exec -it chatwoot-cache redis-cli -a ${REDIS_PASSWORD} INFO server # 验证服务状态资产预编译失败docker-compose run --rm app bundle exec rails assets:precompile4. 邮件服务深度配置国内企业常用QQ邮箱或企业邮箱作为通知渠道其SMTP配置有特殊要求。以下是以QQ邮箱为例的完整配置# QQ邮箱SMTP配置 MAILER_SENDER_EMAIL客服系统 12345678qq.com SMTP_ADDRESSsmtp.qq.com SMTP_PORT465 SMTP_USERNAME12345678qq.com SMTP_PASSWORDxxxxxxxxxxxxxx # 需使用授权码而非邮箱密码 SMTP_AUTHENTICATIONlogin SMTP_ENABLE_STARTTLS_AUTOtrue SMTP_SSLtrue SMTP_OPENSSL_VERIFY_MODEnone配置完成后可通过控制台测试邮件发送docker-compose exec app bundle exec rails console # 在Rails控制台中执行 ActionMailer::Base.mail( from: ENV[MAILER_SENDER_EMAIL], to: testexample.com, subject: SMTP测试, body: 这是一封测试邮件 ).deliver_now国内邮箱特殊配置指南邮箱服务商SMTP地址端口加密方式认证方式QQ邮箱smtp.qq.com465SSL授权码163邮箱smtp.163.com465SSL授权码阿里企业邮smtp.mxhichina.com465SSL密码Gmailsmtp.gmail.com587STARTTLSOAuth2重要提示国内邮箱服务商普遍要求开启SMTP服务后才能使用QQ邮箱需通过网页版邮箱设置-账户-开启POP3/SMTP服务获取授权码。5. 系统优化与维护为保证生产环境稳定运行建议进行以下优化性能调优参数# 数据库连接池 RAILS_MAX_THREADS10 POSTGRES_STATEMENT_TIMEOUT15s # Sidekiq并发 SIDEKIQ_CONCURRENCY5 # 内存限制 RUBY_GC_HEAP_OLDOBJECT_LIMIT_FACTOR1.3定期维护命令# 清理过期会话 docker-compose exec app bundle exec rails runner Session.where(updated_at ?, 1.week.ago).delete_all # 备份数据库 docker exec chatwoot-db pg_dump -U chatwoot chatwoot_production backup_$(date %Y%m%d).sql # 更新系统 docker-compose pull docker-compose down docker-compose up -d监控指标收集通过/monitoring/sidekiq查看后台任务队列使用docker stats观察容器资源占用配置日志轮转防止磁盘写满实际部署中发现合理配置Puma worker数量能显著提升并发处理能力。可通过修改.env添加WEB_CONCURRENCY2 # 建议设置为CPU核心数的1-1.5倍 MAX_THREADS5 # 每个worker的线程数至此您已经完成了一个高可用Chatwoot客服系统的全栈部署。系统上线后建议定期检查日志文件app/log/production.log及时处理异常警告。对于需要横向扩展的场景可以考虑将Redis和PostgreSQL迁移到独立服务器并通过增加App服务实例实现负载均衡。