VPS 搭建 Chatwoot（2026）：Docker、PostgreSQL、Redis、Caddy HTTPS、邮件与备份完整教程

Chatwoot 是一套全渠道客户支持平台，可以把网站聊天、邮件以及经过官方渠道接入的社交消息汇总到一个客服工作台。它更接近 Intercom、Zendesk 一类客服系统，而不是内部团队聊天工具。

适合自建的场景包括：

• 客户会话和联系人数据需要保留在自己的基础设施；
• 有多个客服，需要分配会话、添加标签、内部备注和快捷回复；
• 希望把网站聊天、邮件、Webhook 或 API 接进统一收件箱；
• 能安排人员维护 Linux、Docker、邮件投递、备份和安全更新；
• SaaS 按坐席计费已经明显高于 VPS 与运维成本。

如果只是给个人网站加一个简单留言框，或者团队没有人负责监控和恢复演练，托管客服 SaaS 往往更省事。Community Edition 虽然免费，但 VPS、域名、邮件服务、对象存储、异地备份和运维时间都不是零成本。

Chatwoot Community Edition 并不等于所有商业功能都免费。官方当前方案中，Captain AI、语音、去品牌、高级角色权限、SSO/SAML 和 SLA 等能力不全部包含在 Community Edition。选型时应按实际需要核对 Chatwoot 自托管方案，不要把付费能力写进免费版采购清单。

如果你的目标是团队内部频道、私聊和 ChatOps，而不是对外客服工单，应该看 Mattermost 自建教程。

Chatwoot 官方当前要求至少 4 GB 内存；其容量参考中，4 核与 4 GB 内存可支持约 10,000 次会话/天，8 核与 8 GB 内存可支持约 20,000 次会话/天，但实际负载还取决于客服并发、消息渠道、附件、Webhook 和后台任务。Sidekiq 在繁忙实例上可能单独占用 1 GB 以上内存。

官方还建议至少配置 1 GB swap，避免升级时瞬时内存不足。swap 是安全缓冲，不是用廉价磁盘替代内存：如果系统长期交换，应扩容 RAM 或拆分服务。

sudo fallocate -l 1G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
free -h

本文使用下面的数据路径：

访客网站 / 客服浏览器
          │ HTTPS 443
          ▼
     Caddy（宿主机）
          │ 127.0.0.1:3000
          ▼
  Chatwoot Rails 容器 ───── PostgreSQL
          │
          └──── Sidekiq ─── Redis

附件：本地 Docker volume，或 S3 兼容对象存储

公网只开放 22/tcp、80/tcp 和 443/tcp。官方生产 Compose 已把 Rails 的 3000、PostgreSQL 的 5432 和 Redis 的 6379 绑定到 127.0.0.1；不要为了调试把数据库或 Redis 改成 0.0.0.0。

准备一个子域名，例如 support.example.com，把 A 记录指向 VPS 公网 IPv4。若添加 AAAA 记录，必须保证 IPv6 也能访问服务器，否则证书签发和客户端连接可能间歇失败。

export CW_DOMAIN="support.example.com"
getent ahosts "$CW_DOMAIN"
curl -4 https://ifconfig.me

更新系统并配置 UFW：

sudo apt-get update
sudo apt-get upgrade -y
sudo apt-get install -y ca-certificates curl openssl ufw

sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
sudo ufw status verbose

云厂商如果还有安全组，也只开放相同端口。SSH 最好限制为管理 IP，并提前确认另一终端能登录，再关闭当前会话。

sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list >/dev/null

sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo systemctl enable --now docker
sudo docker version
sudo docker compose version

生产环境还应为容器配置日志轮转、资源预警和可观测性，具体可参考 Docker Compose 生产配置清单。

为避免 develop 分支以后变化，直接从 v4.17.1 标签下载对应文件：

sudo install -d -o "$USER" -g "$USER" -m 0750 /opt/chatwoot
cd /opt/chatwoot

curl -fL https://raw.githubusercontent.com/chatwoot/chatwoot/v4.17.1/.env.example -o .env
curl -fL https://raw.githubusercontent.com/chatwoot/chatwoot/v4.17.1/docker-compose.production.yaml -o docker-compose.production.yaml

sed -i 's|image: chatwoot/chatwoot:latest|image: chatwoot/chatwoot:v4.17.1-ce|' docker-compose.production.yaml
grep 'image: chatwoot/chatwoot' docker-compose.production.yaml

-ce 是不包含 Enterprise 代码的 Community Edition 镜像。固定版本的目的不是永远不升级，而是让每次升级都经过备份、发布说明检查和数据库迁移。

先生成三个互不相同的随机值，并立即保存到密码管理器：

openssl rand -hex 64
openssl rand -base64 36
openssl rand -base64 36

编辑 /opt/chatwoot/.env，至少确认这些项目。示例中的域名、密码和发件地址必须替换：

SECRET_KEY_BASE=replace-with-the-128-character-hex-secret
FRONTEND_URL=https://support.example.com
FORCE_SSL=true
ENABLE_ACCOUNT_SIGNUP=true
DEFAULT_LOCALE=zh_CN

REDIS_URL=redis://:replace-with-redis-password@redis:6379
REDIS_PASSWORD=replace-with-redis-password

POSTGRES_HOST=postgres
POSTGRES_DATABASE=chatwoot
POSTGRES_USERNAME=postgres
POSTGRES_PASSWORD=replace-with-postgres-password
RAILS_ENV=production
RAILS_LOG_TO_STDOUT=true
LOG_LEVEL=info

MAILER_SENDER_EMAIL=Support <[email protected]>
SMTP_DOMAIN=example.com
SMTP_ADDRESS=smtp.example.com
SMTP_PORT=587
[email protected]
SMTP_PASSWORD=replace-with-smtp-password
SMTP_AUTHENTICATION=login
SMTP_ENABLE_STARTTLS_AUTO=true
SMTP_OPENSSL_VERIFY_MODE=peer

ACTIVE_STORAGE_SERVICE=local

限制配置文件权限，并检查 Compose 展开结果：

cd /opt/chatwoot
chmod 600 .env
sudo docker compose -f docker-compose.production.yaml config >/tmp/chatwoot-compose.yaml
grep -A4 -E '127.0.0.1:3000|127.0.0.1:5432|127.0.0.1:6379' /tmp/chatwoot-compose.yaml

不要把 docker compose config 的完整输出贴到公开工单，它可能包含数据库、Redis 和 SMTP 密码。

第一次启动前运行 Chatwoot 官方数据库准备任务：

cd /opt/chatwoot
sudo docker compose -f docker-compose.production.yaml pull
sudo docker compose -f docker-compose.production.yaml run --rm rails bundle exec rails db:chatwoot_prepare
sudo docker compose -f docker-compose.production.yaml up -d
sudo docker compose -f docker-compose.production.yaml ps
sudo docker compose -f docker-compose.production.yaml logs --tail=100 rails sidekiq postgres redis

检查 Web 端口和依赖：

curl -I http://127.0.0.1:3000
ss -lntp | grep -E ':3000|:5432|:6379'
sudo docker compose -f docker-compose.production.yaml exec -T postgres pg_isready -U postgres -d chatwoot
sudo docker compose -f docker-compose.production.yaml exec -T redis sh -lc 'redis-cli -a "$REDIS_PASSWORD" ping'

预期 PostgreSQL 返回 accepting connections，Redis 返回 PONG，并且三个端口都只监听本机回环地址。

sudo apt-get install -y debian-keyring debian-archive-keyring apt-transport-https curl gnupg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list >/dev/null
sudo apt-get update
sudo apt-get install -y caddy

创建 /etc/caddy/Caddyfile：

support.example.com {
    encode zstd gzip
    reverse_proxy 127.0.0.1:3000

    log {
        output file /var/log/caddy/chatwoot-access.log {
            roll_size 100MiB
            roll_keep 7
        }
    }
}

Caddy 的 reverse_proxy 默认支持 WebSocket，不必手写 Upgrade 头。校验并重载：

sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
sudo systemctl status caddy --no-pager
curl -I https://support.example.com

若同一台服务器还代理其他应用，可先阅读 Caddy 反向代理与自动 HTTPS 指南。

先访问：

https://support.example.com/app/auth/signup

完成第一个管理员账户和组织创建后，立即把 .env 中的设置改为：

ENABLE_ACCOUNT_SIGNUP=false

然后重建应用容器，让环境变量生效：

cd /opt/chatwoot
sudo docker compose -f docker-compose.production.yaml up -d --force-recreate rails sidekiq

不要长期开启公开注册。后续客服账号应由管理员邀请，并开启 MFA；当前版本启用 MFA 前还要按照 .env.example 的说明配置 Active Record Encryption 三个密钥。

sudo docker compose -f docker-compose.production.yaml run --rm rails bundle exec rails db:encryption:init

把命令输出的 ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY、ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY 和 ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT 安全写入 .env，备份到密码管理器，再重建 Rails 与 Sidekiq 容器。丢失这些密钥可能影响已加密数据，不能每次部署重新生成。

登录后台后进入“设置 → 收件箱 → 添加收件箱”，选择 Website，填写站点名称和允许访问的域名。Chatwoot 会生成一段包含 websiteToken 的脚本，把它加入网站的全局布局或标签管理器。

上线前至少验证：

1. 无痕窗口能看到聊天气泡；
2. 发出第一条消息后，客服工作台实时出现会话；
3. 客服回复能推送回网页，而不是刷新后才出现；
4. 不在允许域名列表的测试站点无法滥用组件；
5. 附件类型和大小符合业务规则；
6. 关闭客服后台后，邮件通知仍能送达。

聊天气泡不出现时，先看浏览器开发者工具的 Console、Network 和 WebSocket 请求。常见原因是 FRONTEND_URL 写错、CSP 阻止脚本、CDN 缓存旧代码，或反向代理前还有错误的 HTTPS 跳转。

SMTP 不只是找回密码，还影响邀请、通知和会话邮件。配置后应从后台发送测试消息，并同时检查容器日志：

cd /opt/chatwoot
sudo docker compose -f docker-compose.production.yaml logs -f --tail=100 rails sidekiq

如果邮件进入垃圾箱，应检查发件域名的 SPF、DKIM 与 DMARC，而不是关闭 TLS 校验。MAILER_SENDER_EMAIL 的域名也应与 SMTP 服务允许的发件身份一致。

“客户给某个支持邮箱回信并继续同一会话”属于入站邮件，需要额外配置 Mailgun、Postmark、SendGrid、SES 或邮件转发服务，并设置 RAILS_INBOUND_EMAIL_SERVICE、入站密码和供应商 Webhook。不要把普通 SMTP 出站成功误认为入站邮件也已经完成。

Chatwoot 能把多个渠道汇总到统一收件箱，但渠道接入不等于绕过平台规则。WhatsApp、Instagram、Facebook 等通常需要对应的 Business 账号、开发者应用、Webhook、审核和平台侧费用。

生产使用时应：

• 只按 Chatwoot 与渠道平台的官方文档申请凭据；
• 使用单独的应用和最小权限 Token；
• 把回调域名固定为 HTTPS；
• 记录 Token 轮换和渠道审核负责人；
• 不购买来源不明的“免审核接口”或共享账号。

网站聊天和 API Inbox 更适合先做最小可行验证，再逐个增加外部渠道。

默认的 ACTIVE_STORAGE_SERVICE=local 会把附件写入 Docker 的 storage_data volume。它部署简单，但 VPS 磁盘损坏时附件会和主机一起丢失，所以必须异地备份。

附件增长较快时，可改用 S3 兼容对象存储：

ACTIVE_STORAGE_SERVICE=s3_compatible
STORAGE_BUCKET_NAME=chatwoot-attachments
STORAGE_ACCESS_KEY_ID=replace-with-access-key
STORAGE_SECRET_ACCESS_KEY=replace-with-secret-key
STORAGE_REGION=auto
STORAGE_ENDPOINT=https://your-s3-compatible-endpoint
STORAGE_FORCE_PATH_STYLE=true

不同服务对 path-style、CORS 和签名 URL 的要求不同，切换前应在测试实例验证上传、预览、下载和删除。对象存储本身也要启用版本控制、生命周期与备份；“放到 S3”不代表自动满足恢复目标。需要自己部署兼容服务时，可参考 MinIO 对象存储教程。

Chatwoot 官方列出的关键备份对象包括 PostgreSQL、附件存储、环境变量和代码定制。Redis 主要保存后台队列与缓存，不应被当作会话数据的唯一来源；重点是数据库和附件必须属于同一恢复点。

下面示例在短暂停止 Rails 与 Sidekiq 后创建一致性更高的本地备份：

cd /opt/chatwoot
STAMP=$(date +%F-%H%M%S)
BACKUP_DIR="/var/backups/chatwoot/$STAMP"
sudo install -d -m 0700 "$BACKUP_DIR"

sudo docker compose -f docker-compose.production.yaml stop rails sidekiq

sudo sh -c "docker compose -f /opt/chatwoot/docker-compose.production.yaml exec -T postgres pg_dump -U postgres -d chatwoot -Fc > '$BACKUP_DIR/chatwoot.dump'"

sudo docker compose -f docker-compose.production.yaml run --rm --no-deps \
  -v "$BACKUP_DIR:/backup" rails \
  tar -czf /backup/storage.tar.gz -C /app/storage .

sudo cp .env docker-compose.production.yaml "$BACKUP_DIR/"
sudo sha256sum "$BACKUP_DIR"/* | sudo tee "$BACKUP_DIR/SHA256SUMS"
sudo docker compose -f docker-compose.production.yaml start rails sidekiq

随后把整个目录加密并同步到另一地区或另一家服务商。只在同一块 VPS 磁盘保留副本不算灾难恢复。保留周期可按 RPO 设计，例如每日备份保留 7 天、每周保留 4 周、每月保留 6–12 个月。通用设计思路可参考 VPS 自动备份方案。

恢复前先确认目标 Chatwoot 镜像、.env 中的加密密钥、数据库名和附件存储方式与备份匹配。下面是新测试 VPS 上的基本顺序：

cd /opt/chatwoot
sudo docker compose -f docker-compose.production.yaml stop rails sidekiq

sudo docker compose -f docker-compose.production.yaml exec -T postgres dropdb -U postgres --if-exists chatwoot
sudo docker compose -f docker-compose.production.yaml exec -T postgres createdb -U postgres chatwoot
sudo sh -c "cat /var/backups/chatwoot/RESTORE_POINT/chatwoot.dump | docker compose -f /opt/chatwoot/docker-compose.production.yaml exec -T postgres pg_restore -U postgres -d chatwoot"

sudo docker compose -f docker-compose.production.yaml run --rm --no-deps \
  -v /var/backups/chatwoot/RESTORE_POINT:/backup:ro rails \
  tar -xzf /backup/storage.tar.gz -C /app/storage

sudo docker compose -f docker-compose.production.yaml run --rm rails bundle exec rails db:chatwoot_prepare
sudo docker compose -f docker-compose.production.yaml start rails sidekiq

演练完成后，验证管理员登录、历史会话、联系人、随机附件、网站组件、邮件通知和后台任务。没有定期恢复演练的备份，只能证明“生成过文件”，不能证明业务可恢复。

升级前阅读当前版本到目标版本之间的所有发布说明。跨多个大版本时，官方建议按中间版本逐步升级，不要一次跳到最新。

cd /opt/chatwoot

# 1. 先执行上一节的完整备份并记录当前镜像
grep 'image: chatwoot/chatwoot' docker-compose.production.yaml

# 2. 把 Compose 中的镜像改成已经核对过的新版本，例如 v4.17.2-ce
sudo docker compose -f docker-compose.production.yaml down
sudo docker compose -f docker-compose.production.yaml pull
sudo docker compose -f docker-compose.production.yaml up -d

# 3. 官方要求升级后运行数据库准备任务
sudo docker compose -f docker-compose.production.yaml run --rm rails bundle exec rails db:chatwoot_prepare

# 4. 回读状态与日志
sudo docker compose -f docker-compose.production.yaml ps
sudo docker compose -f docker-compose.production.yaml logs --tail=200 rails sidekiq
curl -I https://support.example.com

数据库迁移完成后，不要仅靠换回旧镜像回滚。旧版本可能无法读取新结构；可靠回滚应恢复升级前的数据库和附件快照，并在隔离环境先验证。

至少监控这些指标：

• VPS 内存、swap、CPU、磁盘容量和 inode；
• Rails 与 Sidekiq 容器重启次数；
• PostgreSQL 连接、容量和备份结果；
• Redis 可用性与内存；
• Sidekiq 队列积压和失败任务；
• HTTPS 证书、域名和外部探活；
• SMTP 退信率、Webhook 错误与附件增长速度。

快速巡检命令：

cd /opt/chatwoot
sudo docker compose -f docker-compose.production.yaml ps
sudo docker stats --no-stream
df -h
df -i
free -h
sudo docker compose -f docker-compose.production.yaml logs --since=30m rails sidekiq postgres redis

不要只设置“网站打不开”告警。Sidekiq 停止时登录页仍可能正常，但邮件、Webhook、导入和后台任务已经堆积。

• 域名 A/AAAA 记录与真实网络一致；
• 公网只开放 22、80、443，3000/5432/6379 仅本机监听；
• 镜像固定为已核对的 v4.17.1-ce，没有使用 latest；
• .env 权限为 600，所有默认密码已替换；
• 首个管理员创建后已关闭 ENABLE_ACCOUNT_SIGNUP；
• MFA 加密密钥已保存并纳入安全备份；
• 网站组件可实时双向收发消息；
• SMTP、邀请、通知和密码重置已测试；
• 外部渠道使用官方凭据，Token 有轮换计划；
• PostgreSQL、附件和配置已异地备份；
• 已在隔离环境完成一次恢复演练；
• Rails、Sidekiq、数据库、Redis、磁盘和 HTTPS 都有告警。

一套可长期使用的 Chatwoot 自建环境，至少要同时满足四件事：镜像版本可控、Rails/Sidekiq/PostgreSQL/Redis 依赖清晰、HTTPS 与邮件链路可验证、数据库与附件能够异地恢复。

对于刚开始的中小团队，4 vCPU、8 GB RAM、固定 Community Edition 镜像、Caddy 自动 HTTPS、本地附件加异地备份，是更稳妥的起点。等会话量、附件或渠道增加后，再把 PostgreSQL、Worker 和对象存储逐步拆分。不要把“容器已启动”当作上线完成；真正的完成标准是客服消息能收发、后台任务不积压，并且你已经亲手恢复过一次。