今天在 GitHub Trending 上看到一个有意思的项目：Chatwoot，一款开源的现代客户支持平台，定位是 Intercom、Zendesk、Salesforce Service Cloud 等商业 SaaS 的自主可控替代方案。
Chatwoot 是一个基于 Ruby on Rails + Vue.js 构建的现代客户支持平台，旨在帮助企业交付卓越的客户服务体验。项目采用 MIT 协议开源，支持自部署，让企业完全掌控客户数据。
核心定位：
核心特性：
Chatwoot 采用经典的 前后端分离 + 实时通信 架构：
┌─────────────────────────────────────────────────────┐
│ Client Layer │
│ Dashboard (Vue 3 + Pinia) │ Widget │ Portal │
└────────────────────┬────────────────────────────────┘
│ HTTPS / WebSocket
┌────────────────────┴────────────────────────────────┐
│ API & Real-time │
│ Rails API Server + ActionCable (WebSocket) │
└────────────────────┬────────────────────────────────┘
│
┌────────────────────┴────────────────────────────────┐
│ Service Layer │
│ Sidekiq (Async) │ Active Job │ Action Mailbox │
└────────────────────┬────────────────────────────────┘
│
┌────────────────────┴────────────────────────────────┐
│ Data Layer │
│ PostgreSQL │ Redis │ OpenSearch/Elasticsearch │
│ ActiveStorage (S3/Azure/GCS) │
└─────────────────────────────────────────────────────┘
| 层级 | 技术 | 选型理由 |
|---|---|---|
| 后端框架 | Ruby on Rails 7.1 | 开发效率高，生态成熟，Active Record ORM 强大 |
| 前端框架 | Vue 3 + Pinia | 响应式 UI，组合式 API，状态管理清晰 |
| 实时通信 | ActionCable (WebSocket) | Rails 原生支持，与鉴权体系无缝集成 |
| 数据库 | PostgreSQL | 支持 JSONB、全文搜索（pg_search）、向量扩展（pgvector） |
| 缓存/队列 | Redis + Sidekiq | 高性能异步任务处理，支持 Cron 定时任务 |
| 全文搜索 | OpenSearch / Elasticsearch | 支持文章全文检索，Searchkick 封装 |
| 文件存储 | ActiveStorage | 统一抽象，支持 S3 / Azure / GCS 多后端 |
| AI 能力 | RubyLLM + OpenAI / AI Agents | 接入大语言模型，驱动 Captain 智能客服 |
1. 多渠道消息统一抽象
Chatwoot 通过统一的 Conversation + Message 模型抽象所有渠道的消息，各渠道（Facebook Messenger、WhatsApp、邮件等）通过独立的 Channel Handler 进行适配：
# app/channels/application_channel.rb (概念结构)
class ApplicationChannel
def name; end
def send_message; end
def receive_message; end
end
各渠道实现继承自基类，实现消息的双向流转。
2. AI Captain 响应生成
Captain 基于 ruby_llm 和 ai-agents gem 实现，支持接入 OpenAI、Anthropic 等 LLM 提供商。系统会将对话历史、帮助中心文章作为上下文注入 Prompt，生成准确回复。
# 概念示例（基于 Gemfile 中的 ai-agents / ruby_llm）
agent = AI::Agent.new(
model: "gpt-4o",
context: conversation.history,
knowledge_base: help_center_articles
)
response = agent.generate_reply(user_message)
3. 向量语义搜索（pgvector）
帮助中心文章和用户消息通过 neighbor + pgvector 扩展实现余弦相似度检索，用于推荐相关文章和 Captain 知识库匹配：
# 文章向量化存储（概念）
class Article < ApplicationRecord
has_neighbors :embedding
end
# 语义检索
Article.nearest_neighbors(:embedding, query_vector, distance: "cosine")
以一封客户邮件触发客服回复的流程为例：
Action Mailbox 接收入站邮件 → 创建 Conversation + 首条 MessageActionCable 推送实时通知到客服 DashboardMailer 发送邮件 + 写入 Message 记录| 依赖 | 版本要求 |
|---|---|
| Ruby | 3.4.4 |
| Node.js | 24.x |
| pnpm | 10.x |
| PostgreSQL | 14+ |
| Redis | 6+ |
| (可选) OpenSearch | 1.x+ |
# 1. 克隆仓库
git clone https://github.com/chatwoot/chatwoot.git
cd chatwoot
# 2. 安装依赖
gem install bundler
bundle install
pnpm install
# 3. 准备数据库
RAILS_ENV=development bundle exec rails db:create
RAILS_ENV=development bundle exec rails db:migrate
RAILS_ENV=development bundle exec rails db:seed
# 4. 启动开发服务器（使用 overmind 或 foreman）
# 安装 overmind: brew install overmind
overmind start -f Procfile.dev
# 或直接用 foreman:
# foreman start -f Procfile.dev
服务启动后访问 http://localhost:3000 即可进入 Dashboard。
# 构建镜像
docker build -t chatwoot -f ./docker/Dockerfile .
# 或使用 Docker Compose（推荐）
# 参考官方 docker-compose.yml
<script>
(function(d,t) {
var BASE_URL = "https://app.chatwoot.com";
var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
g.src=BASE_URL+"/packs/js/sdk.js";
g.defer = true;
g.async = true;
s.parentNode.insertBefore(g,s);
g.onload=function(){
window.chatwootSDK.run({
websiteToken: 'YOUR_WEBSITE_TOKEN',
baseUrl: BASE_URL
})
}
})(document,"script");
</script>
Chatwoot 提供原生 Shopify 集成，客服可在对话侧边栏直接查看客户订单信息：
原因：Redis 内存不足或 Sidekiq 并发数配置过低。
解决：
# config/sidekiq.yml 调整并发
:concurrency: 25
同时检查 Redis maxmemory-policy 配置，建议使用 allkeys-lru。
原因：SES 入站邮件路由未正确配置或 RAILS_INBOUND_EMAIL_ 环境变量缺失。
解决：确保设置 RAILS_INBOUND_EMAIL_INBOUND_EMAIL_DOMAIN 和对应的 SES 规则集，并安装 aws-actionmailbox-ses gem（已包含在 Gemfile 中）。
原因：OpenSearch 默认 JVM 堆大小为 50% 系统内存。
解决：Docker 部署时设置 -e "OPENSEARCH_JAVA_OPTS=-Xms512m -Xmx512m" 限制堆内存。
原因：ActiveStorage 云服务凭证未配置。
解决：在 .env 中配置 S3_BUCKET_NAME、AWS_ACCESS_KEY_ID 等变量，或使用本地 Disk 存储（开发环境）：
# config/environments/development.rb
config.active_storage.service = :local
原因：Lint 检查未通过（ESLint / RuboCop）。
解决：
pnpm run eslint:fix # 自动修复 JS/Vue lint 问题
bundle exec rubocop -a # 自动修复 Ruby lint 问题
Chatwoot 是一款功能全面、架构清晰的开源客户支持平台。其 Rails API + Vue 前端 + Sidekiq 异步 + OpenSearch 搜索 的技术栈成熟稳定，适合中小团队自部署以替代昂贵的商业 SaaS。
适用场景：
项目活跃度：GitHub 上拥有大量 Contributors，Discord 社区活跃，持续迭代。Branching model 采用 git-flow，develop 为默认开发分支，发布版本打 v1.x.x 标签。
如果你正在评估客服系统方案，Chatwoot 绝对值得一试。 🚀
相关链接：
此内容由惯性聚合(RSS阅读器)自动聚合整理，仅供阅读参考。 原文来自 — 版权归原作者所有。