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

# 웹훅 기반 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 통합을 위한 웹훅 핸들러 예제
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 워커 추가
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