Twenty项目Docker Compose部署指南

概述

Twenty是一个现代化的CRM系统，采用微服务架构设计。本文档将详细介绍如何使用Docker Compose部署Twenty项目，帮助开发者和系统管理员快速搭建完整的Twenty运行环境。

核心服务架构

Twenty的Docker Compose配置定义了四个核心服务组件：

1. server服务：主应用服务，处理HTTP请求
2. worker服务：后台任务处理服务
3. db服务：PostgreSQL数据库服务
4. redis服务：Redis缓存服务

详细配置解析

server服务配置

server服务是Twenty的核心应用服务，主要配置包括：

• 端口映射：将容器内的3000端口映射到主机的3000端口
• 数据卷：挂载server-local-data卷用于持久化存储
• 环境变量：
  • PG_DATABASE_URL：PostgreSQL数据库连接字符串
  • SERVER_URL：服务访问URL
  • REDIS_URL：Redis连接URL
  • STORAGE_*：存储相关配置（支持S3）
  • APP_SECRET：应用加密密钥

健康检查配置了HTTP端点检查，确保服务启动成功后才接受流量。

worker服务配置

worker服务负责处理后台任务，配置与server服务类似，但：

• 使用yarn worker:prod命令启动
• 禁用了数据库迁移和定时任务注册（由server服务处理）
• 依赖server和db服务的健康状态

db服务配置

PostgreSQL数据库服务配置：

• 使用PostgreSQL 16官方镜像
• 数据持久化到db-data卷
• 配置了用户认证信息
• 健康检查使用pg_isready命令验证数据库可用性

redis服务配置

Redis服务配置相对简单：

• 使用官方Redis镜像
• 配置了内存策略为"noeviction"（不淘汰数据）
• 默认端口6379

环境变量详解

Twenty项目通过环境变量实现灵活配置，主要分为以下几类：

数据库配置

• PG_DATABASE_USER：PostgreSQL用户名（默认postgres）
• PG_DATABASE_PASSWORD：PostgreSQL密码（默认postgres）
• PG_DATABASE_HOST：数据库主机（默认db）
• PG_DATABASE_PORT：数据库端口（默认5432）

应用配置

• APP_SECRET：应用加密密钥（必须修改）
• SERVER_URL：服务访问URL（必须配置）
• DISABLE_DB_MIGRATIONS：禁用数据库迁移
• DISABLE_CRON_JOBS_REGISTRATION：禁用定时任务注册

存储配置

• STORAGE_TYPE：存储类型
• STORAGE_S3_*：S3存储相关配置（区域、名称、端点）

第三方服务集成（注释状态）

配置文件中包含了多种第三方服务集成的配置选项，如：

• Google认证和日历服务
• Microsoft认证和日历服务
• 邮件服务配置

这些配置默认被注释，需要时取消注释并填写相应值即可启用。

部署建议

1. 安全配置：

   • 务必修改APP_SECRET环境变量
   • 生产环境不应使用默认的数据库凭证

2. 存储方案：

   • 开发环境可使用本地卷存储
   • 生产环境建议配置S3存储

3. 健康检查：

   • 默认健康检查配置适合大多数场景
   • 高负载环境可调整检查间隔和重试次数

4. 资源限制：

   • 生产环境应为各服务添加资源限制（CPU/内存）

常见问题解决

1. 服务启动顺序问题：

   • 使用depends_on和condition确保依赖服务就绪
   • 数据库健康检查可避免连接问题

2. 端口冲突：

   • 如3000端口被占用，可修改ports配置

3. 存储权限问题：

   • 确保Docker有权限写入配置的数据卷

总结

Twenty项目的Docker Compose配置提供了完整的开发和生产环境部署方案。通过合理配置环境变量，可以轻松适配不同部署场景。理解各服务组件的作用和相互关系，有助于排查部署过程中的问题，也为定制化部署提供了基础。