Chatwoot v4.6.0 部署文档

# Chatwoot v4.6.0 部署文档

## 📋 目录
- [环境信息](#环境信息)
- [部署步骤](#部署步骤)
- [常见问题解决](#常见问题解决)
- [配置说明](#配置说明)
- [使用指南](#使用指南)
- [维护命令](#维护命令)

---

## 🖥️ 环境信息

### 服务器配置
- **操作系统**: Ubuntu 22.04 LTS
- **服务器IP**: 192.168.9.131
- **Chatwoot版本**: v4.6.0
- **Ruby版本**: 3.2.0
- **Node.js版本**: 20.x
- **数据库**: PostgreSQL 16.10
- **缓存**: Redis

### 端口使用
- **Web服务**: 3000
- **PostgreSQL**: 5432
- **Redis**: 6379

---

## 🚀 部署步骤

### 1. 系统准备

```bash
# 更新系统
sudo apt update && sudo apt upgrade -y

# 安装基础依赖
sudo apt install -y curl git build-essential libssl-dev
```

### 2. 安装 PostgreSQL 16

```bash
# 添加 PostgreSQL 仓库
sudo sh -c 'echo "deb http://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'
wget -qO- https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo tee /etc/apt/trusted.gpg.d/pgdg.asc

# 安装 PostgreSQL 16
sudo apt update
sudo apt install -y postgresql-16 postgresql-contrib-16

# 创建数据库和扩展
sudo -u postgres psql <<EOF
CREATE DATABASE chatwoot_production;
\c chatwoot_production;
CREATE EXTENSION pgvector;
CREATE EXTENSION pg_stat_statements;
CREATE EXTENSION pgcrypto;
CREATE EXTENSION pg_trgm;
EOF
```

### 3. 安装 Ruby 3.2

```bash
# 安装 rbenv
curl -fsSL https://github.com/rbenv/rbenv-installer/raw/HEAD/bin/rbenv-installer | bash

# 配置环境变量
echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(rbenv init -)"' >> ~/.bashrc
source ~/.bashrc

# 安装 Ruby 3.2.0
rbenv install 3.2.0
rbenv global 3.2.0

# 安装 Bundler
gem install bundler
```

### 4. 安装 Node.js 和 pnpm

```bash
# 安装 Node.js 20.x
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

# 安装 pnpm
npm install -g pnpm@9.15.0
```

### 5. 安装 Redis

```bash
sudo apt install -y redis-server
sudo systemctl enable redis-server
sudo systemctl start redis-server
```

### 6. 部署 Chatwoot

```bash
# 创建 chatwoot 用户
sudo useradd -m -s /bin/bash chatwoot

# 克隆代码
sudo su - chatwoot
cd /opt
sudo git clone https://github.com/chatwoot/chatwoot.git
sudo chown -R chatwoot:chatwoot /opt/chatwoot

# 切换到 chatwoot 用户
sudo su - chatwoot
cd /opt/chatwoot

# 安装依赖
bundle install
pnpm install

# 配置环境变量
cp .env.example .env
# 编辑 .env 文件，配置数据库连接等
```

### 7. 配置环境变量

编辑 `/opt/chatwoot/.env`：

```bash
# 数据库配置
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DATABASE=chatwoot_production
POSTGRES_USERNAME=postgres
POSTGRES_PASSWORD=your_password

# Redis 配置
REDIS_URL=redis://localhost:6379

# 应用配置
RAILS_ENV=production
SECRET_KEY_BASE=$(bundle exec rake secret)
FRONTEND_URL=http://192.168.9.131:3000

# 禁用 SSL（内网环境）
FORCE_SSL=false
```

### 8. 初始化数据库

```bash
cd /opt/chatwoot
RAILS_ENV=production bundle exec rails db:prepare
RAILS_ENV=production bundle exec rails db:seed
```

### 9. 预编译前端资源

```bash
cd /opt/chatwoot

# 设置 Node.js 内存限制
export NODE_OPTIONS="--max-old-space-size=8192"

# 预编译资源
RAILS_ENV=production bundle exec rails assets:precompile
```

### 10. 配置 Rack::Attack (重要)

编辑 `/opt/chatwoot/config/initializers/rack_attack.rb`，在文件开头（第3行）添加：

```ruby
# Priority safelist for widget
Rack::Attack.safelist('allow all widget') do |request|
  request.path.start_with?('/widget')
end
```

### 11. 启动服务

```bash
# 启动 Rails 服务器
cd /opt/chatwoot
RAILS_ENV=production nohup bundle exec rails server -b 0.0.0.0 -p 3000 > /var/log/chatwoot-web.log 2>&1 &

# 启动 Sidekiq
RAILS_ENV=production nohup bundle exec sidekiq -C config/sidekiq.yml > /var/log/chatwoot-sidekiq.log 2>&1 &
```

### 12. 创建超级管理员

创建文件 `/tmp/create-superadmin.rb`：

```ruby
# 查找或创建账户
account = Account.find_or_create_by!(name: 'Default Account')

# 创建超级管理员
user = User.create!(
  email: 'admin@chatwoot.com',
  name: 'Admin',
  password: 'Admin@123456',
  password_confirmation: 'Admin@123456',
  confirmed_at: Time.now
)

# 设置为 SuperAdmin
user.update!(type: 'SuperAdmin')

# 添加到账户
AccountUser.create!(
  account: account,
  user: user,
  role: :administrator
)

puts "超级管理员创建成功！"
puts "邮箱: admin@chatwoot.com"
puts "密码: Admin@123456"
```

执行脚本：

```bash
cd /opt/chatwoot
RAILS_ENV=production bundle exec rails runner /tmp/create-superadmin.rb
```

### 13. 启用账户功能

```bash
# 在 Rails console 中执行
cd /opt/chatwoot
RAILS_ENV=production bundle exec rails runner "Account.find(2).update!(feature_flags: 2**63 - 1)"
```

---

## 🔧 常见问题解决

### 问题 1: Vite SASS 导入错误

**症状**: 编译时出现 "Can't find stylesheet to import" 错误

**解决方案**: 在 `vite.config.ts` 中添加 CSS preprocessor 配置：

```typescript
export default defineConfig({
  // ... 其他配置
  css: {
    preprocessorOptions: {
      scss: {
        api: 'modern-compiler',
        loadPaths: [
          'node_modules',
          'node_modules/.pnpm',
          path.resolve(__dirname, 'node_modules')
        ]
      }
    }
  }
});
```

### 问题 2: Node.js 内存不足

**症状**: "JavaScript heap out of memory"

**解决方案**:

```bash
export NODE_OPTIONS="--max-old-space-size=8192"
RAILS_ENV=production bundle exec rails assets:precompile
```

### 问题 3: Widget 显示 "Retry later"

**症状**: 聊天小部件无法加载，浏览器显示 "Retry later"

**原因**: Rack::Attack 速率限制器阻止了 widget 请求

**解决方案**:

1. 编辑 `/opt/chatwoot/config/initializers/rack_attack.rb`
2. 在文件开头（第3行）添加白名单规则：

```ruby
# Priority safelist for widget
Rack::Attack.safelist('allow all widget') do |request|
  request.path.start_with?('/widget')
end
```

3. 重启 Rails 服务：

```bash
# 查找并停止旧进程
ps aux | grep "rails server" | grep -v grep
sudo kill -9 <PID>

# 删除 PID 文件
rm -f /opt/chatwoot/tmp/pids/server.pid

# 重新启动
cd /opt/chatwoot
RAILS_ENV=production nohup bundle exec rails server -b 0.0.0.0 -p 3000 > /var/log/chatwoot-web.log 2>&1 &
```

### 问题 4: 渠道按钮无法点击

**症状**: Inbox 创建页面的所有渠道按钮都是灰色，无法点击

**原因**: Enterprise 版本的 feature_flags 未启用

**解决方案**:

```bash
# 方法1: 通过 Rails console
cd /opt/chatwoot
RAILS_ENV=production bundle exec rails runner "Account.find(<account_id>).update!(feature_flags: 2**63 - 1)"

# 方法2: 直接修改数据库
sudo -u postgres psql -d chatwoot_production -c "UPDATE accounts SET feature_flags = 9223372036854775807 WHERE id = <account_id>;"
```

### 问题 5: 用户权限不足

**症状**: 登录后缺少管理员功能

**解决方案**: 确保用户类型为 SuperAdmin：

```bash
cd /opt/chatwoot
RAILS_ENV=production bundle exec rails runner "
user = User.find_by(email: 'admin@chatwoot.com')
user.update!(type: 'SuperAdmin', confirmed_at: Time.now)
"
```

---

## ⚙️ 配置说明

### 数据库配置

**位置**: `/opt/chatwoot/.env`

```bash
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DATABASE=chatwoot_production
POSTGRES_USERNAME=postgres
POSTGRES_PASSWORD=your_password
```

### Redis 配置

```bash
REDIS_URL=redis://localhost:6379
```

### 应用配置

```bash
# 环境
RAILS_ENV=production

# 密钥（必须生成）
SECRET_KEY_BASE=$(bundle exec rake secret)

# 前端地址
FRONTEND_URL=http://192.168.9.131:3000

# 禁用 SSL（内网环境）
FORCE_SSL=false
```

### Vite 配置

**位置**: `/opt/chatwoot/vite.config.ts`

关键配置：

```typescript
css: {
  preprocessorOptions: {
    scss: {
      api: 'modern-compiler',
      loadPaths: [
        'node_modules',
        'node_modules/.pnpm',
        path.resolve(__dirname, 'node_modules')
      ]
    }
  }
}
```

### Rack::Attack 配置

**位置**: `/opt/chatwoot/config/initializers/rack_attack.rb`

白名单配置（在文件开头添加）：

```ruby
# Priority safelist for widget
Rack::Attack.safelist('allow all widget') do |request|
  request.path.start_with?('/widget')
end
```

---

## 📖 使用指南

### 访问地址

- **后台管理**: http://192.168.9.131:3000
- **登录凭据**:
  - 邮箱: `admin@chatwoot.com`
  - 密码: `Admin@123456`

### 创建测试页面

创建 `/opt/chatwoot/public/test.html`：

```html
<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <title>Chatwoot 聊天测试</title>
</head>
<body>
  <h1>Chatwoot 测试页面</h1>

<script>
    (function(d,t) {
      var BASE_URL="http://192.168.9.131:3000";
      var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
      g.src=BASE_URL+"/packs/js/sdk.js";
      g.async = true;
      s.parentNode.insertBefore(g,s);
      g.onload=function(){
        window.chatwootSDK.run({
          websiteToken: 'YOUR_WEBSITE_TOKEN',
          baseUrl: BASE_URL
        })
      }
    })(document,"script");
  </script>
</body>
</html>
```

### 获取 Website Token

1. 登录后台
2. Settings → Inboxes → 选择你的 Inbox
3. Settings → Configuration → 复制 Website Token

### 集成到网站

将以下代码添加到网站的 `</body>` 标签前：

```html
<script>
  (function(d,t) {
    var BASE_URL="http://192.168.9.131:3000";
    var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
    g.src=BASE_URL+"/packs/js/sdk.js";
    g.async = true;
    s.parentNode.insertBefore(g,s);
    g.onload=function(){
      window.chatwootSDK.run({
        websiteToken: 'YOUR_WEBSITE_TOKEN',
        baseUrl: BASE_URL
      })
    }
  })(document,"script");
</script>
```

---

## 🛠️ 维护命令

### 查看日志

```bash
# Web 服务器日志
tail -f /var/log/chatwoot-web.log

# Sidekiq 日志
tail -f /var/log/chatwoot-sidekiq.log

# 生产日志
tail -f /opt/chatwoot/log/production.log
```

### 重启服务

```bash
# 停止所有进程
pkill -9 -f "rails server"
pkill -9 -f "sidekiq"

# 清理 PID 文件
rm -f /opt/chatwoot/tmp/pids/server.pid

# 启动 Web 服务
cd /opt/chatwoot
RAILS_ENV=production nohup bundle exec rails server -b 0.0.0.0 -p 3000 > /var/log/chatwoot-web.log 2>&1 &

# 启动 Sidekiq
RAILS_ENV=production nohup bundle exec sidekiq -C config/sidekiq.yml > /var/log/chatwoot-sidekiq.log 2>&1 &
```

### 数据库操作

```bash
# 进入 Rails console
cd /opt/chatwoot
RAILS_ENV=production bundle exec rails console

# 执行单行命令
RAILS_ENV=production bundle exec rails runner "puts User.count"

# 数据库备份
sudo -u postgres pg_dump chatwoot_production > chatwoot_backup_$(date +%Y%m%d).sql

# 数据库恢复
sudo -u postgres psql chatwoot_production < chatwoot_backup.sql
```

### 更新 Chatwoot

```bash
cd /opt/chatwoot

# 备份当前版本
git stash
git pull origin develop

# 更新依赖
bundle install
pnpm install

# 迁移数据库
RAILS_ENV=production bundle exec rails db:migrate

# 重新编译资源
export NODE_OPTIONS="--max-old-space-size=8192"
RAILS_ENV=production bundle exec rails assets:precompile

# 重启服务
pkill -9 -f "rails server"
pkill -9 -f "sidekiq"
rm -f tmp/pids/server.pid

RAILS_ENV=production nohup bundle exec rails server -b 0.0.0.0 -p 3000 > /var/log/chatwoot-web.log 2>&1 &
RAILS_ENV=production nohup bundle exec sidekiq -C config/sidekiq.yml > /var/log/chatwoot-sidekiq.log 2>&1 &
```

### 性能监控

```bash
# 检查进程状态
ps aux | grep -E "rails server|sidekiq" | grep -v grep

# 检查端口占用
netstat -tulnp | grep 3000

# 检查内存使用
free -h

# 检查磁盘使用
df -h
```

---

## 🔍 故障排查

### 服务无法启动

1. 检查日志文件：
```bash
tail -100 /var/log/chatwoot-web.log
tail -100 /opt/chatwoot/log/production.log
```

2. 检查端口占用：
```bash
sudo lsof -i :3000
```

3. 检查数据库连接：
```bash
sudo -u postgres psql -d chatwoot_production -c "SELECT version();"
```

### Widget 无法加载

1. 检查 Rack::Attack 日志：
```bash
grep "Rack::Attack" /var/log/chatwoot-web.log | tail -20
```

2. 测试 widget 端点：
```bash
curl -I http://192.168.9.131:3000/widget?website_token=YOUR_TOKEN
```

3. 检查浏览器控制台错误（F12）

### 性能问题

1. 启用 Redis 持久化
2. 调整 Sidekiq workers 数量
3. 配置 PostgreSQL 连接池
4. 使用 CDN 加速静态资源

---

## 📚 参考资源

- **官方文档**: https://www.chatwoot.com/docs
- **GitHub**: https://github.com/chatwoot/chatwoot
- **社区论坛**: https://community.chatwoot.com
- **API 文档**: https://www.chatwoot.com/developers/api

---

## 📝 附录

### A. 系统要求

- **最低配置**:
  - CPU: 2 核
  - 内存: 4GB RAM
  - 磁盘: 20GB

- **推荐配置**:
  - CPU: 4 核
  - 内存: 8GB RAM
  - 磁盘: 50GB SSD

### B. 端口清单

| 服务 | 端口 | 说明 |
|------|------|------|
| Web | 3000 | Chatwoot 主服务 |
| PostgreSQL | 5432 | 数据库 |
| Redis | 6379 | 缓存和队列 |

### C. 关键文件位置

| 文件/目录 | 路径 | 说明 |
|-----------|------|------|
| 应用目录 | `/opt/chatwoot` | Chatwoot 主目录 |
| 配置文件 | `/opt/chatwoot/.env` | 环境变量配置 |
| 日志目录 | `/opt/chatwoot/log` | 应用日志 |
| Web 日志 | `/var/log/chatwoot-web.log` | Rails 服务器日志 |
| Sidekiq 日志 | `/var/log/chatwoot-sidekiq.log` | 后台任务日志 |
| PID 文件 | `/opt/chatwoot/tmp/pids/` | 进程 ID 文件 |

---

**文档版本**: 1.0
**更新日期**: 2025-10-12
**适用版本**: Chatwoot v4.6.0