Chatwoot：开源全渠道客服系统，后端 Ruby‑on‑Rails7，前端 Vue3+Vite，存储 PostgreSQL+Redis+Sidekiq 任务队列。路线分为 使用者 → 运维部署 → API 集成 → 二次开发 → 贡献源码 5 个阶段，按需选择路径。

🎯 阶段 1：产品使用者（0‑7 天，业务人员 / 测试）

目标：懂业务概念，会配置、日常操作，不碰代码。

1. 核心概念理解
   • 账号、团队、坐席、收件箱 (inbox)、渠道、会话、联系人、标签、自定义属性、宏、自动化规则、SLA、工作时间
   • 消息归一化：多渠道消息统一会话；联系人合并；会话分配逻辑（团队分配 / 坐席分配）
2. 上手体验
   • 使用官方云实例 app.chatwoot.com 注册体验全部功能
   • 网站聊天部件嵌入、消息收发、内部备注、快捷回复、批量操作、过滤器
   • 自动化规则、路由规则、报表、帮助中心知识库
3. 多渠道对接实操
   • Web 聊天、邮件、Telegram；理解 Webhook 回调机制
   • 理解 WhatsApp、Meta 渠道对接原理（token、webhook 回调）
4. 输出：可以独立搭建一套业务可用的客服工作台。

参考文档：Chatwoot User Guide（官方用户手册）

🚀 阶段 2：自托管运维部署（7‑14 天，运维 / 实施工程师）

目标：本地测试部署、生产部署、调优、升级排错，不修改源代码。

2.1 环境与硬件要求

• 测试：2 核 4G；生产建议 4 核 8G SSD；PostgreSQL≥12，Redis≥6
• 核心组件：Rails web 服务、Sidekiq (后台任务)、ActionCable (websocket 实时消息)、对象存储、SMTP 邮件服务

2.2 部署方式学习（优先 Docker Compose）

1. 本地测试部署：docker compose up‑d，熟悉 .env 核心环境变量
   • FRONTEND_URL、SECRET_KEY_BASE、数据库连接、Redis、SMTP、存储配置
2. 生产环境部署
   • 域名 + Nginx/Caddy 反向代理、SSL 证书
   • 对象存储（S3 兼容），不能本地磁盘用于生产
   • 邮件服务配置，系统通知、用户邮件
3. 运维必学操作
   • 日志查看、容器故障排查；备份 PostgreSQL 数据库
   • 版本升级流程（拉镜像、执行 migrate 迁移）
   • cwctl 命令行工具使用
   • 常见坑：websocket 不通、webhook 回调失败、附件存储、邮件发送失败
4. 进阶部署：K8s 部署、高可用、水平扩展（多 Sidekiq worker）

重点：不要直接用localhost上线公网；公网必须 HTTPS；webhook 依赖公网可访问回调地址。

参考文档：官方 Self‑Hosted 部署文档

🔌 阶段 3：API & Webhook 集成开发（14‑28 天，后端开发）

目标：不修改源码，通过 API/Webhook 对接外部系统、对接 AI 大模型、业务系统打通。

1. 吃透三类 API（官方 API 文档）
   • Application API：账号内操作，会话、联系人、消息、标签、坐席管理（业务集成最常用）
   • Platform API：超级管理员，多租户实例管理（自建 SaaS 场景）
   • Client API：自定义聊天部件，替代官方 JS widget
2. Webhook 深度掌握
   • 会话创建、消息发送、状态变更事件；签名校验防篡改
   • 经典场景：接入 AI 机器人：Chatwoot 事件 webhook 推送 → AI 服务 → 调用 Chatwoot API 回写消息到会话
3. 实战项目练习
   1. 调用 API 创建联系人、发送消息、读取会话列表
   2. 实现 webhook 接收消息，对接大模型自动回复
   3. 把 Chatwoot 与 CRM/ERP 打通，同步客户资料
4. JS Widget 二次定制：自定义聊天窗口样式、预填充客户属性、事件回调。

这个阶段绝大多数企业二次开发需求就可以完成，不需要修改 Rails/Vue 源码。

🛠️ 阶段 4：源码二次开发（28‑60 天，全栈开发）

技术栈：后端 Ruby on Rails7；前端 Vue3+Pinia+TailwindCSS；DB PostgreSQL；Sidekiq；Vite

前置基础

1. Ruby on Rails 基础、MVC、ActiveRecord、Sidekiq 任务队列
2. Vue3 <script setup>、Pinia 状态管理、TailwindCSS
3. PostgreSQL 基础，理解迁移 migrate

本地开发环境搭建

git clone https://github.com/chatwoot/chatwoot
make burn     #安装ruby/js依赖
make db       #数据库初始化
make run      #overmind启动整套开发环境（rails+vite+sidekiq）

源码目录关键结构

• app/：Rails 后端；app/javascript/dashboard Vue 后台管理前端
• app/javascript/widget 聊天小部件前端
• enterprise/ 企业版闭源叠加层
• db/migrate 数据库迁移脚本
• lib 业务逻辑；config/routes.rb API 路由定义

二次开发练习任务（循序渐进）

1. 后端：新增自定义 API 接口，新增联系人自定义字段
2. 前端：修改后台页面组件，新增列表页面
3. 新增渠道适配器（消息接入）
4. Sidekiq 后台任务开发；理解消息处理链路
5. 自定义报表、导出功能
6. 本地打包镜像，测试自定义版本部署

⚠️注意：修改源码后，官方升级会产生冲突，要做好版本管理，尽量把业务逻辑放到 webhook/api 层，少改核心代码。

✨ 阶段 5：参与开源贡献（可选）

1. 阅读贡献指南，了解 git‑flow，develop 开发分支
2. 跑单元测试 rspec、前端 eslint；Cypress 端到端测试
3. 修复 issue、提交 PR，熟悉代码规范（RuboCop、ESLint、全部使用 Tailwind）

📋 学习资源清单

1. 官方用户手册：https://www.chatwoot.com/hc/user-guide
2. 开发者文档：https://developers.chatwoot.com/
3. GitHub 仓库：https://github.com/chatwoot/chatwoot
4. API 参考：https://developers.chatwoot.com/api-reference
5. Community 社区：https://www.chatwoot.com/community

🧭 不同角色学习路径精简

1. 业务实施人员：阶段 1 → 阶段 2（部署运维），不用碰 API 和源码
2. 后端集成工程师：阶段 1 → 阶段 2 → 阶段 3（API/Webhook+AI 对接）
3. 二次开发工程师：全部阶段 1‑4，掌握 Rails+Vue3 源码
4. 运维人员：阶段 1 → 阶段 2，重点高可用、备份升级、故障排查

⚠️ 常见踩坑提醒

1. 自托管实例公网必须 HTTPS，webhook、websocket 全部依赖 HTTPS
2. 生产环境不要使用本地磁盘存储附件，必须 S3 兼容对象存储
3. 版本升级务必执行数据库迁移 db:migrate
4. 尽量优先使用 Webhook+API 实现业务，尽量不修改源代码，降低后续升级成本
5. Sidekiq worker 资源不足会出现消息延迟、自动化规则不执行，生产要监控 Sidekiq 队列堆积。