Chatwoot 2026：开源客户支持平台与AI智能体集成 — 自建部署完整指南

# 克隆官方仓库
git clone https://github.com/chatwoot/chatwoot.git
cd chatwoot

# 切换到最新的稳定版本（截至2026年5月为v4.0.1）
git checkout v4.0.1

# 复制环境变量模板
cp .env.example .env

# 使用编辑器修改 .env 文件
nano .env

# --- 必填变量 ---
SECRET_KEY_BASE=$(openssl rand -hex 64)
FRONTEND_URL=https://support.yourdomain.com

# 数据库
POSTGRES_HOST=postgres
POSTGRES_USERNAME=postgres
POSTGRES_PASSWORD=your_secure_password_here

# Redis
REDIS_URL=redis://redis:6379

# SMTP（使用 Mailgun、SendGrid 或 AWS SES）
SMTP_ADDRESS=smtp.mailgun.org
SMTP_PORT=587
SMTP_USERNAME=postmaster@yourdomain.com
SMTP_PASSWORD=your_mailgun_key
SMTP_DOMAIN=yourdomain.com
MAILER_SENDER_EMAIL=noreply@yourdomain.com

# 启用AI功能（v4.0新增）
ENABLE_AI_FEATURES=true
OPENAI_API_KEY=sk-your-openai-key

# 使用生产环境Docker Compose文件
docker compose -f docker-compose.production.yaml up -d

# 验证所有服务运行正常
docker compose ps

# 预期输出：
# NAME                STATUS         PORTS
# chatwoot_app        Up 30 seconds  0.0.0.0:3000->3000/tcp
# chatwoot_worker     Up 30 seconds
# chatwoot_postgres   Up 30 seconds  5432/tcp
# chatwoot_redis      Up 30 seconds  6379/tcp

# 执行数据库迁移
docker compose exec rails bundle exec rails db:chatwoot_prepare

# 创建管理员账户
docker compose exec rails bundle exec rails db:seed

# /etc/nginx/sites-available/chatwoot
server {
    listen 80;
    server_name support.yourdomain.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name support.yourdomain.com;

    ssl_certificate /etc/letsencrypt/live/support.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/support.yourdomain.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # WebSocket支持实时消息
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

# 启用站点配置
sudo ln -s /etc/nginx/sites-available/chatwoot /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

# 通过 Let's Encrypt 获取SSL证书
sudo certbot --nginx -d support.yourdomain.com

# .env — AI配置
ENABLE_AI_FEATURES=true
OPENAI_API_KEY=sk-your-key
OPENAI_MODEL=gpt-4.1-mini  # 复杂查询可用 gpt-4.1
AI_AUTO_REPLY_THRESHOLD=0.85  # 自动回复的置信度阈值

# config/ai_assistants.yml — 定义助手行为
support_bot:
  name: "Support Assistant"
  model: gpt-4.1-mini
  system_prompt: |
    You are a helpful support assistant for Acme Inc.
    Follow these rules:
    1. Answer only questions in the knowledge base
    2. For billing issues, always offer to connect a human
    3. Keep responses under 150 words
  handoff_keywords: ["refund", "chargeback", "legal", "complaint"]
  max_response_tokens: 200

# 创建基于Webhook的AI集成
curl -X POST "https://support.yourdomain.com/api/v1/accounts/1/webhooks" \
  -H "Content-Type: application/json" \
  -H "Api-Access-Token: YOUR_API_TOKEN" \
  -d '{
    "url": "https://ai-bridge.yourdomain.com/chatwoot/webhook",
    "subscriptions": ["message.created", "conversation.created"],
    "headers": {"X-Custom-Auth": "your-secret-token"}
  }'

# ai_bridge.py — LangChain集成的Webhook处理器示例
from flask import Flask, request, jsonify
from langchain_openai import ChatOpenAI
from langchain.chains import RetrievalQA
from langchain_community.vectorstores import Chroma

app = Flask(__name__)
llm = ChatOpenAI(model="gpt-4.1-mini", temperature=0.3)

@app.route("/chatwoot/webhook", methods=["POST"])
def handle_chatwoot():
    data = request.json
    message = data.get("content", "")
    conversation_id = data["conversation"]["id"]

    # 查询知识库
    qa_chain = RetrievalQA.from_chain_type(
        llm=llm,
        chain_type="stuff",
        retriever=vectorstore.as_retriever()
    )
    response = qa_chain.invoke({"query": message})

    # 将回复发送回Chatwoot
    send_chatwoot_reply(conversation_id, response["result"])
    return jsonify({"status": "ok"})

# HubSpot CRM — 通过Chatwoot应用市场安装
# 路径：设置 > 应用 > HubSpot
# 或通过API配置：

curl -X POST "https://support.yourdomain.com/api/v1/accounts/1/integrations/hubspot" \
  -H "Content-Type: application/json" \
  -H "Api-Access-Token: YOUR_API_TOKEN" \
  -d '{
    "access_token": "your-hubspot-oauth-token",
    "sync_contacts": true,
    "sync_deals": true
  }'

# 通过Twilio添加WhatsApp Business渠道
curl -X POST "https://support.yourdomain.com/api/v1/accounts/1/inboxes" \
  -H "Content-Type: application/json" \
  -H "Api-Access-Token: YOUR_API_TOKEN" \
  -d '{
    "name": "WhatsApp Support",
    "channel": {
      "type": "whatsapp",
      "provider": "twilio",
      "provider_config": {
        "account_sid": "ACxxxxxxxxxxxxxxxx",
        "auth_token": "your_auth_token",
        "phone_number": "+1234567890"
      }
    }
  }'

# 添加Telegram Bot渠道
curl -X POST "https://support.yourdomain.com/api/v1/accounts/1/inboxes" \
  -H "Content-Type: application/json" \
  -H "Api-Access-Token: YOUR_API_TOKEN" \
  -d '{
    "name": "Telegram Support",
    "channel": {
      "type": "telegram",
      "provider_config": {
        "bot_token": "YOUR_BOT_TOKEN_FROM_BOTFATHER"
      }
    }
  }'

# 连接你的客服团队Slack工作区
# 在Chatwoot仪表盘中：设置 > 集成 > Slack
# 授权并选择用于支持提醒的频道

# 机器人将推送：
# - 新会话通知
# - 客服@提及提醒
# - 升级提醒

# docker-compose.scale.yaml — 增加更多Sidekiq worker
services:
  worker_default:
    image: chatwoot/chatwoot:v4.0.1
    command: bundle exec sidekiq -C config/sidekiq.yml
    deploy:
      replicas: 3  # 根据队列深度扩展
    environment:
      - REDIS_URL=redis://redis:6379/0

  worker_high_priority:
    image: chatwoot/chatwoot:v4.0.1
    command: bundle exec sidekiq -q high -q default -q low
    deploy:
      replicas: 2

# config/database.yml — 添加只读副本
production:
  primary:
    <<: *default
    host: <%= ENV['POSTGRES_HOST'] %>
  primary_replica:
    <<: *default
    host: <%= ENV['POSTGRES_REPLICA_HOST'] %>
    replica: true

# .env
POSTGRES_REPLICA_HOST=postgres-replica.yourdomain.com
DATABASE_REPLICA_ENABLED=true

#!/bin/bash
# /opt/scripts/chatwoot-backup.sh

BACKUP_DIR="/backup/chatwoot/$(date +%Y%m%d_%H%M%S)"
mkdir -p "$BACKUP_DIR"

# PostgreSQL 转储
docker compose exec -T postgres pg_dump \
  -U postgres chatwoot_production > "$BACKUP_DIR/database.sql"

# Redis RDB快照
docker compose exec redis redis-cli BGSAVE

# 上传到S3
aws s3 sync "$BACKUP_DIR" "s3://your-backup-bucket/chatwoot/"

# 仅保留最近14天
find /backup/chatwoot -maxdepth 1 -type d -mtime +14 -exec rm -rf {} \;

# Cron定时任务 — 每天凌晨2点执行
0 2 * * * /opt/scripts/chatwoot-backup.sh >> /var/log/chatwoot-backup.log 2>&1

# Chatwoot暴露 /metrics 端点
# 添加到你的 prometheus.yml

scrape_configs:
  - job_name: 'chatwoot'
    static_configs:
      - targets: ['support.yourdomain.com:3000']
    metrics_path: '/metrics'
    scrape_interval: 30s

# 在 .env 中启用API速率限制
RATE_LIMIT_ENABLED=true
RATE_LIMIT_REQUESTS=100
RATE_LIMIT_PERIOD=60  # 每IP每秒

# 通过Nginx添加安全头部
add_header X-Frame-Options "SAMEORIGIN" always;
add_header X-Content-Type-Options "nosniff" always;
add_header Referrer-Policy "strict-origin-when-cross-origin" always;
add_header Content-Security-Policy "default-src 'self'" always;

# 先备份
/opt/scripts/chatwoot-backup.sh

# 拉取新镜像并重启
docker compose pull
docker compose up -d
docker compose exec rails bundle exec rails db:migrate