promovaweb-devops-review-chatwoot-stack

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Review Chatwoot Stack

Chatwoot栈审查

Executa uma auditoria completa do arquivo

chatwoot.yaml

e reporta conformidade, problemas e sugestões.

对

chatwoot.yaml

文件执行完整审计，并报告合规性、存在的问题和优化建议。

Instruções de Execução

执行说明

Quando esta skill for invocada, siga exatamente este roteiro:

当本skill被调用时，请严格遵循以下流程执行：

Passo 1 — Ler o arquivo

步骤1 — 读取文件

Leia o arquivo

chatwoot.yaml

completo.

完整读取

chatwoot.yaml

文件内容。

Passo 2 — Executar todos os checks abaixo

步骤2 — 执行所有以下检查项

Execute cada bloco de verificação e registre os resultados (✅ OK / ⚠️ Atenção / ❌ Erro).

逐块执行所有校验规则，记录结果（✅ 正常 / ⚠️ 警告 / ❌ 错误）。

Passo 3 — Gravar o resultado

步骤3 — 保存结果

Grave o relatório completo em um arquivo chamado chatwoot.audit.md.

将完整审计报告保存为名为chatwoot.audit.md的文件。

Checks de Verificação

校验规则

1. Variáveis de Ambiente Obrigatórias

1. 必填环境变量

Verifique se todas as variáveis abaixo estão definidas nos anchors YAML (

x-chatwoot-*

Banco de dados (
x-chatwoot-db
)

```
POSTGRES_HOST
```
— deve ser definido (padrão:
```
postgres
```
)
```
POSTGRES_USERNAME
```
— deve ser definido (padrão:
```
postgres
```
)
```
POSTGRES_PASSWORD
```
— deve existir e não deve ser o placeholder
SENHA
, compare com a senha definida em
```
postgres.yaml
```
```
POSTGRES_DATABASE
```
— deve ser definido (padrão:
```
chatwoot
```
)

Redis (
x-chatwoot-redis
)

```
REDIS_URL
```
— deve começar com
```
redis://
```
e conter host e porta válidos (ex:
```
redis://redis:6379
```
)
```
REDIS_PASSWORD
```
— verificar se está definida (recomendado se Redis usa autenticação)

Object Storage (
x-chatwoot-storage
)

ACTIVE_STORAGE_SERVICE

— deve ser

s3_compatible

local

```
STORAGE_BUCKET_NAME
```
— deve ser definido se usar S3
```
STORAGE_ACCESS_KEY_ID
```
— deve ser preenchido se usar S3 (alertar se vazio)
```
STORAGE_SECRET_ACCESS_KEY
```
— deve ser preenchido se usar S3 (alertar se vazio)
```
STORAGE_REGION
```
— deve ser definido se usar S3
```
STORAGE_ENDPOINT
```
— deve ser uma URL válida se usar S3
```
STORAGE_FORCE_PATH_STYLE
```
— deve ser
```
"true"
```
se usar S3 compatível

Ambiente Geral (
x-chatwoot-env
)

```
INSTALLATION_NAME
```
— deve ser definido (padrão:
```
chatwoot
```
)
```
NODE_ENV
```
— deve ser
```
production
```
```
RAILS_ENV
```
— deve ser
```
production
```
```
INSTALLATION_ENV
```
— deve ser
```
docker
```
```
SECRET_KEY_BASE
```
— deve existir, ter pelo menos 32 caracteres e não ser o valor de exemplo
123458bb7ef6402f6a8bcf5d3be54321
```
FRONTEND_URL
```
— deve começar com
```
https://
```
e ser um domínio válido (não localhost, não
```
chat.agenciasynca.com.br
```
se for apenas placeholder)
```
DEFAULT_LOCALE
```
— deve ser definido (ex:
```
pt-BR
```
)
```
FORCE_SSL
```
— deve ser
```
"true"
```
```
ENABLE_ACCOUNT_SIGNUP
```
— verificar se é intencional estar habilitado (risco de segurança)
```
RAILS_LOG_TO_STDOUT
```
— deve ser
```
"true"
```
```
USE_INBOX_AVATAR_FOR_BOT
```
— deve ser
```
"true"
```
```
ENABLE_PUSH_RELAY_SERVER
```
— deve ser
```
"true"
```

检查以下所有变量是否都在YAML锚点（

x-chatwoot-*

）中定义：

数据库（
x-chatwoot-db
）

```
POSTGRES_HOST
```
— 必须定义（默认值：
```
postgres
```
）
```
POSTGRES_USERNAME
```
— 必须定义（默认值：
```
postgres
```
）
```
POSTGRES_PASSWORD
```
— 必须存在且不能是占位符
SENHA
，需与
```
postgres.yaml
```
中定义的密码比对一致
```
POSTGRES_DATABASE
```
— 必须定义（默认值：
```
chatwoot
```
）

Redis（
x-chatwoot-redis
）

```
REDIS_URL
```
— 必须以
```
redis://
```
开头，包含有效的主机和端口（例如：
```
redis://redis:6379
```
）
```
REDIS_PASSWORD
```
— 检查是否已定义（如果Redis启用了认证则为必填）

对象存储（
x-chatwoot-storage
）

ACTIVE_STORAGE_SERVICE

— 必须为

s3_compatible

或

local

```
STORAGE_BUCKET_NAME
```
— 使用S3时必须定义
```
STORAGE_ACCESS_KEY_ID
```
— 使用S3时必须填写（为空则告警）
```
STORAGE_SECRET_ACCESS_KEY
```
— 使用S3时必须填写（为空则告警）
```
STORAGE_REGION
```
— 使用S3时必须定义
```
STORAGE_ENDPOINT
```
— 使用S3时必须为有效的URL
```
STORAGE_FORCE_PATH_STYLE
```
— 使用兼容S3的存储时必须为
```
"true"
```

通用环境变量（
x-chatwoot-env
）

```
INSTALLATION_NAME
```
— 必须定义（默认值：
```
chatwoot
```
）
```
NODE_ENV
```
— 必须为
```
production
```
```
RAILS_ENV
```
— 必须为
```
production
```
```
INSTALLATION_ENV
```
— 必须为
```
docker
```
```
SECRET_KEY_BASE
```
— 必须存在，长度至少32位且不能是示例值
123458bb7ef6402f6a8bcf5d3be54321
```
FRONTEND_URL
```
— 必须以
```
https://
```
开头且为有效域名（不能是localhost，仅作为占位符的
```
chat.agenciasynca.com.br
```
也不符合要求）
```
DEFAULT_LOCALE
```
— 必须定义（例如：
```
pt-BR
```
）
```
FORCE_SSL
```
— 必须为
```
"true"
```
```
ENABLE_ACCOUNT_SIGNUP
```
— 检查是否为主动开启（存在安全风险）
```
RAILS_LOG_TO_STDOUT
```
— 必须为
```
"true"
```
```
USE_INBOX_AVATAR_FOR_BOT
```
— 必须为
```
"true"
```
```
ENABLE_PUSH_RELAY_SERVER
```
— 必须为
```
"true"
```

2. Serviços Obrigatórios

2. 必填服务

Verifique se todos estes serviços estão presentes:

Serviço	Obrigatório	Hostname Esperado
`chatwoot_admin`	Sim	`{{.Service.Name}}.{{.Task.Slot}}`
`chatwoot_sidekiq`	Sim	`{{.Service.Name}}.{{.Task.Slot}}`

检查是否存在以下所有服务：

服务	是否必填	预期主机名
`chatwoot_admin`	是	`{{.Service.Name}}.{{.Task.Slot}}`
`chatwoot_sidekiq`	是	`{{.Service.Name}}.{{.Task.Slot}}`

3. Comandos dos Containers

3. 容器命令

Verifique o comando (

command

) e

entrypoint

de cada serviço:

Serviço	Entrypoint Esperado	Comando Esperado
`chatwoot_admin`	`docker/entrypoints/rails.sh`	`bundle exec rails s -p 3000 -b 0.0.0.0`
`chatwoot_sidekiq`	—	deve incluir `db:prepare` , `db:chatwoot_prepare` e `sidekiq -C config/sidekiq.yml`

Alertar se o comando do

chatwoot_sidekiq

não incluir a preparação do banco de dados antes de iniciar o Sidekiq.

检查每个服务的

command

和

entrypoint

配置：

服务	预期Entrypoint	预期Command
`chatwoot_admin`	`docker/entrypoints/rails.sh`	`bundle exec rails s -p 3000 -b 0.0.0.0`
`chatwoot_sidekiq`	—	必须包含 `db:prepare` 、 `db:chatwoot_prepare` 和 `sidekiq -C config/sidekiq.yml`

如果

chatwoot_sidekiq

的命令中未在启动Sidekiq前包含数据库准备操作，需给出告警。

4. Replicas dos Serviços

4. 服务副本数

Verifique a quantidade de réplicas de cada serviço:

Serviço	Réplicas Mínimas	Observação
`chatwoot_admin`	1	Pode escalar, mas atenção à sessão
`chatwoot_sidekiq`	1	Pode escalar para mais workers

检查每个服务的副本数量：

服务	最小副本数	说明
`chatwoot_admin`	1	可扩容，但需注意会话一致性
`chatwoot_sidekiq`	1	可扩容为更多worker

5. Rotas Traefik

5. Traefik路由

Para o serviço

chatwoot_admin

, verifique:

Âncora de endereço (
x-chatwoot-app-url
):

A âncora
```
x-chatwoot-app-url
```
deve existir e conter um domínio válido (não placeholder como
```
chat.agenciasynca.com.br
```
)
O domínio na âncora deve ser idêntico ao domínio dentro de
```
Host(...)
```
na label
```
traefik.http.routers.chatwoot_admin.rule
```
Se não forem iguais, reportar como ❌ Erro: inconsistência entre
```
x-chatwoot-app-url
```
e a regra Traefik
O domínio na âncora deve coincidir também com o domínio em
```
FRONTEND_URL
```
(sem o
```
https://
```
)

Labels obrigatórias:

```
traefik.enable=true
```

traefik.swarm.network=network_swarm_public

traefik.http.routers.chatwoot_admin.rule

— deve conter

Host(...)

com domínio válido e coincidir com

x-chatwoot-app-url

FRONTEND_URL

traefik.http.routers.chatwoot_admin.entrypoints=websecure

traefik.http.routers.chatwoot_admin.tls.certresolver=letsencryptresolver

traefik.http.routers.chatwoot_admin.service=chatwoot_admin

traefik.http.services.chatwoot_admin.loadbalancer.server.port=3000

traefik.http.services.chatwoot_admin.loadbalancer.passhostheader=true

Middleware WebSocket:

traefik.http.middlewares.sslheader.headers.customrequestheaders.X-Forwarded-Proto=https

— obrigatório para WebSockets

traefik.http.routers.chatwoot_admin.middlewares=sslheader@swarm

— deve estar presente

针对

chatwoot_admin

服务，检查以下配置：

地址锚点（
x-chatwoot-app-url
）：

必须存在
```
x-chatwoot-app-url
```
锚点，且包含有效域名（不能是
```
chat.agenciasynca.com.br
```
这类占位符）
锚点中的域名必须完全一致于
```
traefik.http.routers.chatwoot_admin.rule
```
标签中
```
Host(...)
```
内的域名
如果不一致，标记为❌ 错误：
```
x-chatwoot-app-url
```
与Traefik规则不匹配
锚点中的域名也必须与
```
FRONTEND_URL
```
中的域名一致（去掉
```
https://
```
前缀后）

必填标签：

```
traefik.enable=true
```

traefik.swarm.network=network_swarm_public

traefik.http.routers.chatwoot_admin.rule

— 必须包含带有有效域名的

Host(...)

，且与

x-chatwoot-app-url

和

FRONTEND_URL

一致

traefik.http.routers.chatwoot_admin.entrypoints=websecure

traefik.http.routers.chatwoot_admin.tls.certresolver=letsencryptresolver

traefik.http.routers.chatwoot_admin.service=chatwoot_admin

traefik.http.services.chatwoot_admin.loadbalancer.server.port=3000

traefik.http.services.chatwoot_admin.loadbalancer.passhostheader=true

WebSocket中间件：

traefik.http.middlewares.sslheader.headers.customrequestheaders.X-Forwarded-Proto=https

— WebSocket必填配置

traefik.http.routers.chatwoot_admin.middlewares=sslheader@swarm

— 必须存在

6. Volumes

6. 存储卷

Verifique se os volumes estão corretamente configurados:

```
chatwoot_data
```
— deve ser declarado como
```
external: true
```
e montado em ambos os serviços em
```
/app/storage
```
Ambos os serviços (
```
chatwoot_admin
```
e
```
chatwoot_sidekiq
```
) devem compartilhar o mesmo volume para consistência de storage

检查存储卷是否配置正确：

```
chatwoot_data
```
— 必须声明为
```
external: true
```
，且挂载到两个服务的
```
/app/storage
```
路径
两个服务（
```
chatwoot_admin
```
和
```
chatwoot_sidekiq
```
）必须共享同一个存储卷，保证存储一致性

7. Recursos dos Containers

7. 容器资源

Para cada serviço, verifique os limites de recursos:

Serviço	CPU Mínimo	Memória Mínima	Memória Máxima
`chatwoot_admin`	"1"	1024M	2048M
`chatwoot_sidekiq`	"1"	1024M	2048M

Alertar se algum serviço não tiver

resources.limits

definido.

检查每个服务的资源限制：

服务	最低CPU配置	最低内存配置	最大内存配置
`chatwoot_admin`	"1"	1024M	2048M
`chatwoot_sidekiq`	"1"	1024M	2048M

如果任意服务未配置

resources.limits

需给出告警。

8. Configuração de Deploy

8. 部署配置

Para cada serviço, verifique:

```
mode: replicated
```
— ambos devem ser
```
replicated
```

placement.constraints

— deve incluir

node.role == manager

Verificar se há

update_config

com

order: start-first

failure_action: rollback

(recomendado)

检查每个服务的以下配置：

```
mode: replicated
```
— 两个服务都必须为
```
replicated
```
模式

placement.constraints

— 必须包含

node.role == manager

检查是否配置了

update_config

，包含

order: start-first

和

failure_action: rollback

（推荐配置）

9. Redes e Imagens

9. 网络与镜像

Redes:

Ambos os serviços devem estar na rede
```
network_swarm_public
```
A rede deve ser declarada como
```
external: true
```
na seção
```
networks:
```

Imagens:

Ambos os serviços devem usar
```
*chatwoot-image
```
(anchor)
Verificar se a imagem usa tag específica de versão em vez de
```
latest
```
(recomendado em produção)

网络：

两个服务都必须加入
```
network_swarm_public
```
网络
该网络必须在
```
networks:
```
区块中声明为
```
external: true
```

镜像：

两个服务都必须使用
```
*chatwoot-image
```
（锚点）
检查镜像是否使用了具体版本标签而非
```
latest
```
（生产环境推荐固定版本）

10. Segurança

10. 安全配置

```
POSTGRES_PASSWORD
```
não deve ser
```
SENHA
```
(placeholder)

SECRET_KEY_BASE

não deve ser o valor de exemplo

123458bb7ef6402f6a8bcf5d3be54321

(deve ser gerado com

openssl rand -hex 32

)

STORAGE_ACCESS_KEY_ID

STORAGE_SECRET_ACCESS_KEY

não devem estar vazios se usar S3

```
STORAGE_BUCKET_NAME
```
não deve ser
```
chatwoot
```
(placeholder)
```
ENABLE_ACCOUNT_SIGNUP: "false"
```
— recomendado para instalações privadas
```
FORCE_SSL: "true"
```
— deve estar presente
```
FRONTEND_URL
```
deve usar HTTPS e domínio real.

```
POSTGRES_PASSWORD
```
不能是占位符
```
SENHA
```

SECRET_KEY_BASE

不能是示例值

123458bb7ef6402f6a8bcf5d3be54321

（需使用

openssl rand -hex 32

生成）

使用S3时

STORAGE_ACCESS_KEY_ID

和

STORAGE_SECRET_ACCESS_KEY

不能为空

```
STORAGE_BUCKET_NAME
```
不能是占位符
```
chatwoot
```
私有部署推荐配置
```
ENABLE_ACCOUNT_SIGNUP: "false"
```
必须配置
```
FORCE_SSL: "true"
```
```
FRONTEND_URL
```
必须使用HTTPS和真实域名。

Formato do Relatório de Saída

输出报告格式

Ao final, produza um relatório estruturado:

undefined

执行完成后，生成结构化报告：

undefined

Relatório de Auditoria — chatwoot.yaml

审计报告 — chatwoot.yaml

Data: <data atual>

日期: <当前日期>

Resumo

摘要

Total de checks: X
✅ OK: X
⚠️ Atenções: X
❌ Erros: X

总检查项: X
✅ 正常: X
⚠️ 警告项: X
❌ 错误项: X

Resultados por Categoria

各分类检查结果

1. Variáveis de Ambiente

1. 环境变量

✅ POSTGRES_HOST: definido ❌ POSTGRES_PASSWORD: usando placeholder SENHA — troque antes do deploy ...

✅ POSTGRES_HOST: 已定义 ❌ POSTGRES_PASSWORD: 使用占位符SENHA — 部署前请修改 ...

2. Serviços

2. 服务

✅ chatwoot_admin: presente ✅ chatwoot_sidekiq: presente

✅ chatwoot_admin: 已存在 ✅ chatwoot_sidekiq: 已存在

3. Comandos

3. 命令配置

✅ chatwoot_admin: entrypoint e comando corretos ✅ chatwoot_sidekiq: inclui db:prepare e db:chatwoot_prepare ...

✅ chatwoot_admin: entrypoint和command配置正确 ✅ chatwoot_sidekiq: 包含db:prepare和db:chatwoot_prepare ...

4. Replicas

4. 副本数

✅ chatwoot_admin: 1 réplica ✅ chatwoot_sidekiq: 1 réplica ...

✅ chatwoot_admin: 1个副本 ✅ chatwoot_sidekiq: 1个副本 ...

5. Rotas Traefik

5. Traefik路由

✅ chatwoot_admin: rota Host correta, TLS ok ✅ chatwoot_admin: middleware WebSocket configurado ...

✅ chatwoot_admin: Host路由正确，TLS配置正常 ✅ chatwoot_admin: WebSocket中间件已配置 ...

6. Volumes

6. 存储卷

✅ chatwoot_data: declarado como external e compartilhado ...

✅ chatwoot_data: 已声明为外部卷且实现共享 ...

7. Recursos

7. 资源配置

✅ Todos os serviços com limits definidos ...

✅ 所有服务都已配置资源限制 ...

8. Deploy

8. 部署配置

⚠️ update_config não definido — recomendado configurar start-first e rollback ...

⚠️ 未定义update_config — 推荐配置start-first和回滚策略 ...

9. Redes e Imagens

9. 网络与镜像

⚠️ Imagem usando

latest

— considere fixar uma versão em produção ...

⚠️ 镜像使用

latest

标签 — 生产环境建议固定具体版本 ...

10. Segurança

10. 安全配置

❌ POSTGRES_PASSWORD: placeholder SENHA detectado ❌ SECRET_KEY_BASE: valor parece ser exemplo — gere um novo com openssl rand -hex 32 ...

❌ POSTGRES_PASSWORD: 检测到占位符SENHA ❌ SECRET_KEY_BASE: 疑似示例值 — 请使用openssl rand -hex 32生成新值 ...

Ações Recomendadas (por prioridade)

推荐操作（按优先级排序）

Crítico (fazer antes do deploy)

严重（部署前必须修复）

建议修复

Opcional

可选优化

undefined

undefined

promovaweb-devops-review-chatwoot-stack

Original

Translation

Review Chatwoot Stack

Chatwoot栈审查

Instruções de Execução

执行说明

Passo 1 — Ler o arquivo

步骤1 — 读取文件

Passo 2 — Executar todos os checks abaixo

步骤2 — 执行所有以下检查项

Passo 3 — Gravar o resultado

步骤3 — 保存结果

Checks de Verificação

校验规则

1. Variáveis de Ambiente Obrigatórias

1. 必填环境变量

2. Serviços Obrigatórios

2. 必填服务

3. Comandos dos Containers

3. 容器命令

4. Replicas dos Serviços

4. 服务副本数

5. Rotas Traefik

5. Traefik路由

6. Volumes

6. 存储卷

7. Recursos dos Containers

7. 容器资源

8. Configuração de Deploy

8. 部署配置

9. Redes e Imagens

9. 网络与镜像

10. Segurança

10. 安全配置

Formato do Relatório de Saída

输出报告格式

Relatório de Auditoria — chatwoot.yaml

审计报告 — chatwoot.yaml

Resumo

摘要

Resultados por Categoria

各分类检查结果

1. Variáveis de Ambiente

1. 环境变量

2. Serviços

2. 服务

3. Comandos

3. 命令配置

4. Replicas

4. 副本数

5. Rotas Traefik

5. Traefik路由

6. Volumes

6. 存储卷

7. Recursos

7. 资源配置

8. Deploy

8. 部署配置

9. Redes e Imagens

9. 网络与镜像

10. Segurança

10. 安全配置

Ações Recomendadas (por prioridade)

推荐操作（按优先级排序）

Crítico (fazer antes do deploy)

严重（部署前必须修复）

Recomendado

建议修复

Opcional

可选优化