一、项目速览

入门 · 1 分钟版

Twenty 是一个用 TypeScript 写的开源 CRM，定位是「Salesforce 的开源替代品」，并且从一开始就为 AI 集成做了设计。目前 GitHub 上有 52,000+ Star，由 Twenty 公司维护，官网是 twenty.com。

它是什么：一个现代、可自托管的客户关系管理系统，包含联系人管理、销售管道、自动化工作流等核心 CRM 功能。

它解决什么问题：传统 CRM（Salesforce、HubSpot 等）要么太贵（按席位收费），要么太封闭（数据锁死、定制困难）。Twenty 让你拥有完整的数据库控制权，能用代码定义业务对象，还能轻松接入 AI 助手。

谁最该用：技术团队——特别是那些觉得 Salesforce 太重、HubSpot 太贵、想用代码控制 CRM 逻辑的开发者。如果你只是需要个简单的联系人管理工具，Twenty 可能有点杀鸡用牛刀。

作者视角：Twenty 的「杀手锏」不是功能数量（目前不如 Salesforce 丰富），而是它的「代码优先」理念。你可以在代码里定义字段、视图、权限，然后跟 Git 版本一起管理——这对 DevOps 团队来说简直是刚需。

![]{描述：Twenty 的 GitHub 仓库封面图，展示了其现代化 UI 设计风格}(https://opengraph.githubassets.com/master/twentyhq/twenty)

二、核心功能与架构

进阶 · 推荐细读

Twenty 的架构是典型的前后端分离 + 微服务模式，但用 monorepo 统一管理。核心栈是：

• 前端：React + TypeScript，用 GraphQL 跟后端通信
• 后端：NestJS（Node.js 框架）+ PostgreSQL
• AI 层：预留了 AI 接口，未来会集成更多 LLM 能力

核心功能分为三层：

第一层：基础 CRM 能力
- 联系人/公司管理，支持自定义字段（文本、数字、日期、关联等）
- 销售管道（Pipeline）看板，拖拽移动阶段
- 活动记录（邮件、笔记、通话）自动关联到对应联系人
- 搜索与过滤，支持 GraphQL 查询

第二层：代码定义业务对象
- 用 TypeScript 定义对象（Object）和字段（Field），类似 ORM 但更直观
- 视图（View）可以按团队/个人定制，存为配置代码
- 权限模型：基于角色的访问控制（RBAC），细粒度到字段级别

第三层：AI 与扩展
- 内置 AI 助手接口，可以接入 OpenAI 等模型做智能推荐
- Webhook 和 API 优先，几乎所有操作都能通过 GraphQL 完成
- 插件系统（开发中），未来可以写自定义逻辑

一句话判断：Twenty 不是「开箱即用的 CRM」，而是「可编程的 CRM 框架」。如果你需要快速上线 CRM 且接受自托管，它比 Salesforce 灵活 10 倍，比自建省 100 倍时间。

架构亮点：Twenty 采用了「对象-字段-视图」三层抽象。对象相当于数据库表，字段是列，视图是查询+展示的组合。这种设计让非技术人员也能通过 UI 配置（虽然目前 UI 配置能力还在完善），而开发者则可以直接写代码。

![]{描述：Twenty 的架构示意图，展示前后端分离和 GraphQL 通信模式}(https://opengraph.githubassets.com/master/twentyhq/twenty)

三、动手实践

入门

环境准备

你需要：
- Node.js 18+（推荐 20 LTS）
- Docker（用于 PostgreSQL 和 Redis）
- Git

# 克隆仓库
git clone https://github.com/twentyhq/twenty.git
cd twenty

# 安装依赖（monorepo 用 yarn workspaces）
yarn install

# 启动基础设施（PostgreSQL + Redis）
docker compose up -d

最小可运行示例

Twenty 提供了 CLI 工具 create-twenty-app，但为了看到完整效果，建议直接跑整个项目：

# 初始化数据库（会提示输入管理员账号密码）
yarn prisma:migrate

# 启动开发服务器（前端 + 后端一起）
yarn dev

打开 http://localhost:3001，你会看到登录页面。用刚才设置的管理员账号登录，就能看到默认的 CRM 界面。

改一行代码看效果：在 packages/twenty-server/src/core/object-metadata/object-metadata.service.ts 中，找到 findMany 方法，在返回前加一行日志：

// 找到这行
return objects;

// 改成
console.log('Current user objects:', objects.length);
return objects;

重启服务后，每次加载联系人列表，终端都会打印对象数量。这验证了你能修改后端逻辑。

常见踩坑

1. Docker 端口冲突：如果 5432（PostgreSQL）或 6379（Redis）被占用，修改 docker-compose.yml 里的端口映射，同时更新 .env 文件里的 DATABASE_URL。

2. Node.js 版本问题：Twenty 依赖 ES modules 和某些最新 API，建议用 nvm 切换到 Node 20。如果遇到 ERR_REQUIRE_ESM 错误，检查是否用了 CommonJS 的 require。

3. 数据库迁移失败：如果 yarn prisma:migrate 报错，先确认 Docker 容器正常运行（docker ps），然后手动连接数据库验证：

docker exec -it twenty-postgres psql -U twenty -d twenty

如果能连上，说明数据库没问题，可能是迁移文件冲突。尝试 yarn prisma:reset 清空重建。

作者视角：我踩过最大的坑是 .env 文件缺失。Twenty 默认没有 .env.example，你得自己从 packages/twenty-server/.env 复制一份。很多新手会漏掉这一步，导致后端连不上数据库。

四、进阶玩法

深入 · 老手可选

自定义业务对象

Twenty 的核心能力是「用代码定义 CRM」。比如你想加一个「项目」对象，关联到联系人：

// packages/twenty-server/src/core/object-metadata/seed/seed-objects.ts
export const SEED_OBJECTS = [
  // ... 已有对象
  {
    nameSingular: 'project',
    namePlural: 'projects',
    labelSingular: 'Project',
    labelPlural: 'Projects',
    description: 'A business project',
    icon: 'IconBriefcase',
    fields: [
      {
        name: 'name',
        type: 'TEXT',
        label: 'Project Name',
        isRequired: true,
      },
      {
        name: 'deadline',
        type: 'DATE',
        label: 'Deadline',
      },
      {
        name: 'clientId',
        type: 'RELATION',
        label: 'Client',
        relation: {
          // 关联到已有的 person 对象
          targetObjectNameSingular: 'person',
          type: 'MANY_TO_ONE',
        },
      },
    ],
  },
];

运行 yarn prisma:migrate 后，Twenty 会自动创建对应的数据库表和 GraphQL 接口。前端也会自动生成表单和列表视图。

AI 集成示例

Twenty 预留了 AI 接口，你可以让 AI 助手根据对话内容自动创建联系人：

# GraphQL Mutation
mutation CreateContactFromAI($name: String!, $email: String!) {
  createPerson(data: {
    name: $name
    email: $email
    // AI 可以自动填写的字段
    company: "Auto-detected"
    position: "Auto-detected"
  }) {
    id
    name
    email
  }
}

然后在你的 AI 代理（比如 OpenAI Function Calling）里调用这个 mutation。Twenty 的 GraphQL playground 在 http://localhost:3001/graphql，你可以直接测试。

五、判断与建议

进阶 · 推荐细读

应该选 Twenty 的场景

• 你是技术团队，需要高度可定制的 CRM，且愿意投入开发时间
• 你想把 CRM 数据跟现有系统打通（ERP、营销工具等），Twenty 的 GraphQL API 比 Salesforce REST API 好用得多
• 你重视数据主权，不想把客户数据存在 SaaS 厂商的服务器上
• 你正在做 AI 相关的产品，需要一个「AI 友好」的数据底座

不该选 Twenty 的场景

• 你需要开箱即用的 CRM，团队里没有开发者或不想碰代码 → 建议用 HubSpot 免费版
• 你只需要简单的联系人管理，不需要销售管道、自动化工作流 → 用 Google Contacts 或 Notion 就够了
• 你的业务非常传统，需要 Salesforce 那套「销售预测」「配额管理」等企业级功能 → Twenty 目前还不成熟
• 你对自托管有顾虑，不想维护 PostgreSQL 和 Node.js 服务 → 用 Twenty Cloud 付费版

一句话判断：Twenty 是「开发者的 CRM」，不是「销售员的 CRM」。如果你的团队能写 TypeScript，它比任何商业 CRM 都灵活；如果连个会写 SQL 的人都没有，趁早放弃。

最终建议：先花 30 分钟跑通本地环境，然后用它的 GraphQL API 尝试导入 100 条联系人数据。如果这个过程让你觉得「比想象中简单」，那 Twenty 就是你的菜。如果觉得「怎么还要写代码」，那就说明你其实不需要它。

项目信息

参考链接

• GitHub 仓库
• 项目主页