Chatwoot：开源客服系统完全部署指南

Chatwoot：开源客服系统完全部署指南

背景

客户服务是业务增长的关键环节，越来越多的企业选择自建客服系统来掌控客户数据、降低运营成本。Chatwoot 作为一款开源的全渠道客服平台，提供了从基础对话到团队协作、从工单管理到数据分析的完整解决方案。与依赖第三方 SaaS 服务相比，自托管 Chatwoot 可以确保所有客户对话数据完全自主可控。本文分享 Chatwoot 的部署与使用经验，帮助技术团队快速搭建专业的客服系统。

一、项目概述与核心特性

Chatwoot 是一个开源的客户参与平台，GitHub Stars 数超过 25K，被全球数千家企业用于客户支持。其设计理念是将分散在各个渠道的客户对话统一到一个平台管理，提升客服团队效率。

多渠道统一收件箱：Chatwoot 支持接入网站在线聊天、电子邮件、Twitter、Facebook、WhatsApp、Telegram、SMS 等多种客户接触渠道。所有渠道的对话统一在 Chatwoot 中管理和回复，客服人员无需在多个系统间切换。

实时在线对话：网站访客可以发起实时聊天，客服人员通过 Chatwoot 界面即时响应。对话支持文字、图片、文件等多种消息类型，还支持快捷回复模板提高响应效率。

团队协作与分配：内置团队和 Agent 管理功能，支持对话在团队成员间灵活分配和转移。会话可以标记优先级、添加内部备注，方便复杂问题的协同处理。

工单与标签系统：对话可以转化为工单跟踪处理进度。支持为对话和工单添加自定义标签，方便分类统计和问题复盘。

数据统计与分析：提供对话量、响应时间、满意度评分等多维度报表，帮助管理层了解客服团队绩效和客户反馈趋势。

开放 API 与集成：提供 RESTful API 和 Webhooks，可以与 CRM、 Helpdesk 等现有系统集成。社区还贡献了大量第三方集成方案。

二、Docker Compose 部署教程

环境准备

Chatwoot 的 Docker 部署方案需要服务器满足以下要求：

• Docker Engine 24.0+
• Docker Compose v2.x
• 最低 4GB 内存（推荐 8GB+）
• 20GB+ 可用磁盘空间
• 支持 Linux AMD64

基础部署

创建 Chatwoot 专用目录：

mkdir -p ~/chatwoot/chatwoot
cd ~/chatwoot/chatwoot

创建环境变量配置文件 .env：

# 生成密钥
SECRET_KEY_BASE=$(openssl rand -hex 64)
RAILS_ENV=production

# PostgreSQL 配置
POSTGRES_HOST=postgres
POSTGRES_PORT=5432
POSTGRES_NAME=chatwoot
POSTGRES_USERNAME=postgres
POSTGRES_PASSWORD=chatwoot_password

# Redis 配置
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_PASSWORD=

# Chatwoot 基础配置
FRONTEND_URL=http://your-domain:3000
INSTALLATION_ENV=docker

创建 docker-compose.yaml：

version: "3.8"

services:
  chatwoot:
    image: chatwoot/chatwoot:latest
    container_name: chatwoot
    hostname: chatwoot-web
    ports:
      - "3000:3000"
    volumes:
      - ./chatwoot-data:/app/storage
    environment:
      - INSTALLATION_ENV=docker
      - RAILS_ENV=production
      - SECRET_KEY_BASE=${SECRET_KEY_BASE}
      - FRONTEND_URL=http://localhost:3000
      - POSTGRES_HOST=postgres
      - POSTGRES_PORT=5432
      - POSTGRES_NAME=chatwoot
      - POSTGRES_USERNAME=postgres
      - POSTGRES_PASSWORD=chatwoot_password
      - REDIS_HOST=redis
      - REDIS_PORT=6379
      - FRONTEND_URL=http://localhost:3000
    depends_on:
      - postgres
      - redis
    restart: unless-stopped
    networks:
      - chatwoot-network

  sidekiq:
    image: chatwoot/chatwoot:latest
    container_name: sidekiq
    hostname: sidekiq
    command: bundle exec sidekiq -C config/sidekiq.yml
    volumes:
      - ./chatwoot-data:/app/storage
    environment:
      - INSTALLATION_ENV=docker
      - RAILS_ENV=production
      - SECRET_KEY_BASE=${SECRET_KEY_BASE}
      - POSTGRES_HOST=postgres
      - POSTGRES_PORT=5432
      - POSTGRES_NAME=chatwoot
      - POSTGRES_USERNAME=postgres
      - POSTGRES_PASSWORD=chatwoot_password
      - REDIS_HOST=redis
      - REDIS_PORT=6379
    depends_on:
      - postgres
      - redis
    restart: unless-stopped
    networks:
      - chatwoot-network

  postgres:
    image: postgres:16-alpine
    container_name: postgres
    hostname: postgres
    environment:
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=chatwoot_password
      - POSTGRES_DB=chatwoot
    volumes:
      - ./postgres-data:/var/lib/postgresql/data
    restart: unless-stopped
    networks:
      - chatwoot-network

  redis:
    image: redis:7-alpine
    container_name: redis
    hostname: redis
    volumes:
      - ./redis-data:/data
    restart: unless-stopped
    networks:
      - chatwoot-network

networks:
  chatwoot-network:
    driver: bridge

启动 Chatwoot 服务：

docker compose up -d

Chatwoot 首次启动会执行数据库迁移，需要等待 2-3 分钟。使用浏览器访问 http://服务器IP:3000 即可看到安装向导。

邮箱配置

生产环境需要配置 SMTP 服务器以发送邮件通知。编辑 .env 文件添加以下配置：

# SMTP 配置示例（以 QQ 企业邮箱为例）
SMTP_ADDRESS=smtp.exmail.qq.com
SMTP_PORT=465
SMTP_USERNAME=your-email@company.com
SMTP_PASSWORD=your-smtp-password
SMTP_AUTHENTICATION=login
SMTP_ENABLE_STARTTLS_AUTO=true
SMTP_SSL=true

# 邮件发件人配置
MAER_SENDER_EMAIL_ADDRESS=your-email@company.com

重启服务使配置生效：

docker compose restart chatwoot sidekiq

三、快速入门与基础使用

初始化设置

首次访问 Chatwoot 时需要进行初始化配置：

1. 创建管理员账号：填写姓名、邮箱、管理员密码
2. 设置工作空间名称：这将成为团队的显示名称
3. 配置组织 Logo：可选步骤
4. 导入示例数据：可跳过

完成初始化后，使用管理员账号登录 Chatwoot 管理后台。

添加客服团队

在部署客服之前，需要先建立团队结构：

1. 进入「设置」→「团队」
2. 点击「新建团队」按钮
3. 填写团队名称（如「技术支持」「售前咨询」）
4. 设置团队成员，将对应客服人员添加到团队
5. 配置团队职能：是否接收新对话、接收哪些渠道的对话

配置网站在线聊天

网站即时通讯是最常用的客服渠道之一：

1. 进入「设置」→「频道」→「网站」
2. 点击「添加网站」按钮
3. 填写网站名称和域名
4. 配置聊天组件样式（颜色、位置、欢迎语）
5. 复制生成的安装代码

将以下代码添加到网站 HTML 的 </body> 之前：

<script>
  (function(d,t) {
    var BASE_URL="http://your-chatwoot-server:3000";
    var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
    g.src=BASE_URL+"/packs/js/sdk.js";
    g.async=1;
    s.parentNode.insertBefore(g,s);
    g.onload=function(){
      window.chatwootSDK.run({
        websiteToken: 'your-website-token',
        baseUrl: BASE_URL
      })
    }
  })(document,"script");
</script>

配置邮件渠道

邮件是客户服务的重要渠道，Chatwoot 支持 IMAP 收件和 SMTP 发件：

1. 进入「设置」→「频道」→「邮件」
2. 选择邮件服务商类型
3. 配置 IMAP 设置（收件）：
   • IMAP 地址：imap.gmail.com 或你的邮件服务器
   • IMAP 端口：993（SSL）
   • 用户名和密码
4. 配置 SMTP 设置（发件）：
   • SMTP 地址和端口
   • 认证凭据
5. 设置收件箱邮箱地址，如 support@yourcompany.com

配置完成后，发送到这个邮箱的邮件会自动创建对话并分配给客服处理。

日常对话处理

客服人员登录 Chatwoot 后可以在「对话」页面处理客户消息：

回复对话：点击对话列表中的对话，在右侧面板输入回复内容

快捷回复：输入 / 触发快捷回复列表，选择预设的回复模板

转接对话：点击「转接」按钮，选择目标客服或团队

添加备注：内部备注只有团队成员可见，不会发送给客户

标记状态：对话处理完成后标记为「已解决」，自动归档

四、高级功能与最佳实践

多渠道集成

Chatwoot 支持多种第三方渠道集成：

WhatsApp 集成：

1. 前往 Meta Business 管理后台创建 WhatsApp Business 账号
2. 在 Chatwoot 中添加 WhatsApp 频道
3. 配置 Webhook URL 和验证令牌
4. 将 WhatsApp 号码绑定到 Chatwoot

Facebook Messenger 集成：

1. 在 Meta Developers 创建 Facebook App
2. 配置 Messenger Webhook
3. 将 Facebook Page 绑定到 Chatwoot
4. 客户的 Messenger 消息会自动同步到 Chatwoot

Twitter/X 集成：

1. 在 Twitter Developer Portal 创建 App
2. 配置 API Key 和 Bearer Token
3. 绑定 Twitter 账号到 Chatwoot
4. 账号的 DM 和提及会自动创建对话

自动化规则

Chatwoot 支持通过自动化规则处理常见场景：

新对话分配规则：

1. 进入「设置」→「自动化规则」
2. 点击「新建规则」
3. 配置触发条件：「新对话创建」
4. 配置执行动作：「分配给」特定团队或成员
5. 设置条件匹配逻辑，如按消息内容关键词分配

超时提醒：

1. 创建规则「对话未回复超过 X 分钟」
2. 执行动作：发送内部通知或重新分配

快捷回复管理

快捷回复（ canned responses）是提高效率的利器：

1. 进入「设置」→「快捷回复」
2. 点击「新建文件夹」组织回复模板
3. 添加快捷回复，设置触发词
4. 客服在对话中输入 /触发词 快速插入回复

示例模板：

标题：感谢联系
触发词：thanks
内容：您好！感谢您联系我们。请问有什么可以帮助您的？

机器人配置

Chatwoot 内置简易的机器人功能，可以自动处理常见问题：

1. 进入「设置」→「机器人」
2. 点击「新建机器人」
3. 配置机器人名称和触发条件
4. 添加对话流程节点：
   • 问题节点：设置客户可能的输入
   • 回复节点：配置自动回复内容
   • 动作节点：转接人工、创建工单等
5. 将机器人绑定到特定渠道

数据分析与报表

Chatwoot 提供多维度的数据统计：

团队报表：

• 对话量趋势
• 平均响应时间
• 对话解决率
• 客服工作量排名

个人报表：

• 个人处理的对话数量
• 平均首次响应时间
• 客户满意度评分

报告导出：支持将报表数据导出为 CSV 格式，用于进一步分析或制作PPT。

五、常见问题与解决方案

Q1：网站聊天组件不显示？

排查步骤：

1. 确认 FRONTEND_URL 配置正确
2. 检查浏览器控制台是否有跨域错误
3. 确认防火墙开放了 3000 端口
4. 验证 websiteToken 是否正确

Q2：邮件收不到或发不出？

邮件问题排查：

1. 检查 SMTP/IMAP 配置是否正确
2. 确认邮箱开启了 IMAP/SMTP 服务
3. Gmail 等服务商需要开启「低安全性应用」或使用应用专用密码
4. 检查垃圾邮件文件夹

Q3：对话通知不推送？

确保 Sidekiq 容器正常运行：

docker compose ps sidekiq
docker logs sidekiq --tail=100

同时检查浏览器通知权限设置。

Q4：如何迁移 Chatwoot 数据？

完整备份需要备份以下数据：

# 备份数据库
docker compose exec postgres pg_dump -U postgres chatwoot > chatwoot_db.sql

# 备份文件存储
tar -czf chatwoot_storage.tar.gz ./chatwoot-data

恢复时依次导入数据库和文件。

Q5：支持中文界面吗？

Chatwoot 支持多语言。进入「设置」→「个人资料」→「语言」，选择「简体中文」即可切换界面语言。

六、总结

Chatwoot 作为开源客服系统的优秀代表，提供了从多渠道接入到团队协作、从自动化处理到数据分析的完整功能栈。通过 Docker Compose 部署，可以快速在自有服务器上搭建功能完备的客服平台，掌控所有客户对话数据。其 MySQL 兼容的数据库设计和清晰的前后端分离架构，也便于二次开发和定制集成。对于希望提升客户服务质量又希望保持数据自主的企业，Chatwoot 是值得考虑的解决方案。

---

© 版权归无边界科技所有，发表评论请注明出处。