Chatwoot Docker 生产环境完整部署教程

以下内容由豆包生成，仅做存档记录

# Chatwoot Docker 生产环境完整部署教程（官方文档逐步骤落地）
## 一、前置要求
### 1. 系统环境
推荐 Ubuntu/Debian Linux 服务器，开放 **80/443** 端口（后续Nginx+SSL）。
### 2. 软件最低版本要求
```bash
# Docker ≥ 20.10.10
docker --version
# Docker Compose ≥ v2.14.1
docker compose version

旧版 docker-compose（带横杠 docker-compose）：命令把 docker compose 替换成 docker-compose，容器名 - 改为 _。

二、步骤1：安装 Docker & Compose（Ubuntu）

# 更新系统
apt-get update && apt-get upgrade -y
# 一键安装docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
# 安装compose插件
apt install docker-compose-plugin -y
# 验证安装
docker compose version

三、步骤2：下载官方配置文件

mkdir chatwoot && cd chatwoot
# 下载环境变量模板 .env
wget -O .env https://raw.githubusercontent.com/chatwoot/chatwoot/develop/.env.example
# 下载生产版docker-compose编排文件
wget -O docker-compose.yaml https://raw.githubusercontent.com/chatwoot/chatwoot/develop/docker-compose.production.yaml

四、步骤3：修改核心配置（最关键）

4.1 编辑 .env 文件

nano .env

必须修改的参数（其他按需保留默认）：

数据库密码

POSTGRES_PASSWORD=自定义强密码
REDIS_PASSWORD=和上面一致的密码（compose里postgres、redis共用）

站点访问地址（域名/公网IP）

FRONTEND_URL=https://chat.你的域名.com
HELPCENTER_URL=https://chat.你的域名.com

系统加密密钥（必生成，否则登录报错）
终端执行生成随机密钥：

openssl rand -base64 32

复制输出填入：

SECRET_KEY_BASE=上面生成的字符串

邮件SMTP（找回密码、通知必填）

SMTP_ADDRESS=smtp.qq.com # 对应邮箱服务商
SMTP_PORT=587
SMTP_USERNAME=你的邮箱@qq.com
SMTP_PASSWORD=邮箱授权码
SMTP_AUTHENTICATION=login
SMTP_ENABLE_STARTTLS_AUTO=true

可选：本地存储/对象存储，默认本地无需改动。

4.2 同步修改 docker-compose.yaml

打开文件，找到 postgres、redis 服务，确认 POSTGRES_PASSWORD、REDIS_PASSWORD 和 .env 中密码完全一致。

如果你有外部托管Postgres/Redis，可删除compose内postgres、redis服务，在.env填写外部数据库连接地址 DATABASE_URL、REDIS_URL。

五、步骤4：初始化数据库（首次部署必执行）

docker compose run --rm rails bundle exec rails db:chatwoot_prepare

作用：自动创建数据库、执行全部迁移、初始化基础数据。

不要直接用 rails db:migrate，官方指定 db:chatwoot_prepare。

六、步骤5：后台启动全部服务

docker compose up -d

启动4个容器：rails（主程序）、sidekiq（任务队列）、postgres、redis。

验证服务是否正常

# 查看容器运行状态
docker compose ps
# 测试接口是否返回200
curl -I localhost:3000/api

返回 HTTP/1.1 200 OK 代表程序正常。

七、步骤6：公网访问配置（Nginx反向代理+SSL域名）

容器默认仅绑定 127.0.0.1:3000，禁止直接暴露3000端口公网，必须Nginx反向代理。

7.1 安装Nginx & SSL工具

apt install nginx certbot python3-certbot-nginx -y
# 创建SSL验证目录
mkdir -p /var/www/ssl-proof/chatwoot/.well-known

7.2 创建站点配置文件

nano /etc/nginx/sites-available/chat.conf

粘贴配置，替换 chat.你的域名.com：

server {
    server_name chat.你的域名.com;
    set $upstream 127.0.0.1:3000;
    underscores_in_headers on; # Chatwoot API必需，不能删

    location /.well-known {
        alias /var/www/ssl-proof/chatwoot/.well-known;
    }

    location / {
        proxy_pass_header Authorization;
        proxy_pass http://$upstream;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_http_version 1.1;
        proxy_buffering off;
        client_max_body_size 0;
        proxy_read_timeout 36000s;
        proxy_redirect off;
    }
    listen 80;
}

7.3 启用站点、校验Nginx配置

# 软链接到启用目录
ln -s /etc/nginx/sites-available/chat.conf /etc/nginx/sites-enabled/
# 校验配置语法
nginx -t
# 重载Nginx
systemctl reload nginx

7.4 申请Let’s Encrypt免费SSL证书

certbot --webroot -w /var/www/ssl-proof/chatwoot/ -d chat.你的域名.com -i nginx

按提示输入邮箱、同意协议，自动配置HTTPS跳转。

八、访问系统初始化

浏览器打开 https://chat.你的域名.com，按页面提示创建超级管理员账号，完成部署。

九、常用运维命令

1. 查看运行日志（排错用）

# 查看主程序日志
docker compose logs -f rails
# 查看任务队列日志
docker compose logs -f sidekiq

2. 进入Rails控制台（创建用户、调试）

docker exec -it $(basename $(pwd))-rails-1 sh -c 'RAILS_ENV=production bundle exec rails c'

3. 版本升级流程

# 拉取最新镜像
docker compose pull
# 重启服务
docker compose up -d
# 执行数据库迁移（必做）
docker compose run --rm rails bundle exec rails db:chatwoot_prepare

4. 停止/重启服务

# 停止
docker compose down
# 重启
docker compose restart

十、社区版CE部署说明

如果需要开源免费社区版，修改 docker-compose.yaml 内镜像标签：

最新版：chatwoot/chatwoot:latest-ce
指定版本：chatwoot/chatwoot:v2.3.2-ce

十一、常见踩坑提示

500报错/登录失败：未正确设置 SECRET_KEY_BASE 或未执行 db:chatwoot_prepare；
接口400/WebSocket断开：Nginx 缺少 underscores_in_headers on;；
数据库连接失败：.env 与 compose 内postgres密码不一致；
邮件收不到通知：检查SMTP授权码、端口、TLS开关；
公网无法访问：服务器防火墙放行80/443，域名解析指向服务器公网IP。