跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://docs.twenty.com/llms.txt

Use this file to discover all available pages before exploring further.

​
配置管理

第一次安装？ 请按照 Docker Compose 安装指南 获得 Twenty 运行，然后返回此处进行配置。
Twenty 提供两种配置模式以适应不同的部署需求： 管理员面板访问： 只有具有管理员权限的用户(canAccessFullAdminPanel: true) 可以访问配置界面。

​
1. 管理员面板配置（默认）

IS_CONFIG_VARIABLES_IN_DB_ENABLED=true  # default
大多数配置在安装后通过 UI 进行：
  1. 访问你的 Twenty 实例（通常为 http://localhost:3000)
  2. 转到 设置 / 管理员面板 / 配置变量
  3. 配置集成、电子邮件、存储等
  4. 更改会立即生效（多容器部署在 15 秒内）
多容器部署： 当使用数据库配置（IS_CONFIG_VARIABLES_IN_DB_ENABLED=true）时，server 和 worker 容器都会从同一个数据库读取。 管理员面板更改会自动影响两者，无需在容器之间重复环境变量（基础设施变量除外）。
通过管理员面板可以配置的内容：
  • 身份验证 - Google/Microsoft OAuth、密码设置
  • 电子邮件 - SMTP 设置、模板、验证
  • 存储 - S3 配置、本地存储路径
  • 集成 - Gmail, Google Calendar, Microsoft 服务
  • 工作流和速率限制 - 执行限制、API 限流
  • 还有更多……
管理员面板配置变量
每个变量都在您的管理面板的设置 → 管理员面板 → 配置变量中记录了说明。 某些基础设施设置如数据库连接 (PG_DATABASE_URL)、服务器 URL (SERVER_URL) 和密钥（ENCRYPTION_KEY、FALLBACK_ENCRYPTION_KEY）只能通过 .env 文件配置。完整技术参考→

​
加密密钥

Twenty 使用两个仅通过环境变量配置的加密密钥：
变量目的必填
ENCRYPTION_KEY用于对静态存储的机密信息（OAuth 令牌、应用程序变量、签名密钥的私钥、TOTP 密钥、敏感配置值）进行加密的主密钥。新安装必须设置（旧安装可能依赖于 APP_SECRET —— 见下文）
FALLBACK_ENCRYPTION_KEY仅用于验证的密钥。 在轮换期间，将其设置为先前的 ENCRYPTION_KEY，以便现有行仍可解密。仅在轮换期间
为保持向后兼容性，如果未设置 ENCRYPTION_KEY，Twenty 将回退为使用 APP_SECRET 进行静态数据加密——与旧部署的旧版行为一致。 新的安装应始终设置专用的 ENCRYPTION_KEY。 使用 openssl rand -base64 32 生成值，并将其安全存储（如密钥管理器、加密配置等）。 丢失 ENCRYPTION_KEY 意味着将失去对数据库中存储的所有机密的访问权限。 要在不停机的情况下轮换 ENCRYPTION_KEY，请参阅密钥轮换指南。

​
2. 仅限环境配置

IS_CONFIG_VARIABLES_IN_DB_ENABLED=false
所有配置通过 .env 文件管理：
  1. 在 .env 文件中设置 IS_CONFIG_VARIABLES_IN_DB_ENABLED=false
  2. 将所有配置变量添加到 .env 文件中
  3. 重启容器以使更改生效
  4. 管理员面板将显示当前值，但无法修改它们

​
多工作区模式

默认情况下，Twenty 以单工作区模式运行——对于大多数需要为组织部署一个 CRM 实例的自托管部署而言，这是理想之选。

​
单工作区模式（默认）

IS_MULTIWORKSPACE_ENABLED=false  # default
  • 每个 Twenty 实例一个工作区
  • 首位用户会自动成为具有完整权限的管理员（canImpersonate 和 canAccessFullAdminPanel）
  • 创建第一个工作区后，新注册将被禁用
  • 简单的 URL 结构：https://your-domain.com

​
启用多工作区模式

IS_MULTIWORKSPACE_ENABLED=true
DEFAULT_SUBDOMAIN=app  # default value
对于在同一 Twenty 实例上需要多个独立团队拥有各自工作区的类 SaaS 部署，启用多工作区模式。 与单工作区模式的关键区别：
  • 同一实例上可以创建多个工作区
  • 每个工作区都有其自己的子域（例如，sales.your-domain.com、marketing.your-domain.com）
  • 用户在 {DEFAULT_SUBDOMAIN}.your-domain.com 进行注册和登录（例如，app.your-domain.com）
  • 不自动授予管理员权限——每个工作区的首位用户是普通用户
  • 子域、自定义域名等与工作区相关的设置将在工作区设置中可用。
仅限环境的设置：IS_MULTIWORKSPACE_ENABLED 只能通过 .env 文件进行配置，并且需要重启。 无法通过管理面板进行更改。

​
多工作区模式的 DNS 配置

使用多工作区模式时，请在 DNS 中配置通配符记录，以允许动态创建子域： 
*.your-domain.com -> your-server-ip
这使新工作区能够在无需手动配置 DNS 的情况下自动进行子域路由。

​
限制工作区创建

在多工作区模式下，你可能希望限制谁可以创建新工作区： 
IS_WORKSPACE_CREATION_LIMITED_TO_SERVER_ADMINS=true
启用后，只有具有 canAccessFullAdminPanel 权限的用户才能创建其他工作区。 用户仍可在首次注册时创建他们的第一个工作区。

​
Gmail & Google Calendar 集成

​
创建 Google 云项目

  1. 转到 Google 云控制台
  2. 创建新项目或选择现有项目
  3. 启用这些 API：

​
配置 OAuth

  1. 转到 凭据
  2. 创建 OAuth 2.0 客户端 ID
  3. 添加这些重定向 URI：
    • https://{your-domain}/auth/google/redirect (用于 SSO)
    • https://{your-domain}/auth/google-apis/get-access-token (用于集成)

​
在 Twenty 中配置

  1. 转到 设置 → 管理员面板 → 配置变量
  2. 找到 Google 身份验证 部分
  3. 设置这些变量：
    • MESSAGING_PROVIDER_GMAIL_ENABLED=true
    • CALENDAR_PROVIDER_GOOGLE_ENABLED=true
    • AUTH_GOOGLE_CLIENT_ID={client-id}
    • AUTH_GOOGLE_CLIENT_SECRET={client-secret}
    • AUTH_GOOGLE_CALLBACK_URL=https://{your-domain}/auth/google/redirect
    • AUTH_GOOGLE_APIS_CALLBACK_URL=https://{your-domain}/auth/google-apis/get-access-token
仅限环境模式： 如果你设置 IS_CONFIG_VARIABLES_IN_DB_ENABLED=false，请将这些变量添加到 .env 文件中。
所需范围（自动配置）： 查看相关源码
  • https://www.googleapis.com/auth/calendar.events
  • https://www.googleapis.com/auth/gmail.readonly
  • https://www.googleapis.com/auth/profile.emails.read

​
如果你的应用程序处于测试模式

如果你的应用程序处于测试模式，你需要将测试用户添加到你的项目中。 在 OAuth 同意屏幕 下，将你的测试用户添加到 “测试用户” 部分。

​
Microsoft 365 集成

用户必须拥有 Microsoft 365 许可证 才能使用日历和消息传递 API。 没有许可证，他们将无法在 Twenty 上同步他们的帐户。

​
在 Microsoft Azure 中创建项目

你需要在 Microsoft Azure 中创建项目并获取凭据。

​
启用 API

在 Microsoft Azure 控制台中的“权限”中启用以下 API：
  • Microsoft Graph: Mail.ReadWrite
  • Microsoft Graph: Mail.Send
  • Microsoft Graph: Calendars.Read
  • Microsoft Graph: User.Read
  • Microsoft Graph: openid
  • Microsoft Graph: email
  • Microsoft Graph: profile
  • Microsoft Graph: offline_access
注意：“Mail.ReadWrite”和“Mail.Send”仅在你想使用我们的工作流程操作发送电子邮件时是强制性的。 如果你只想接收邮件，你可以使用“Mail.Read”。

​
授权重定向 URI

你需要将以下重定向 URI 添加到你的项目中：
  • https://{your-domain}/auth/microsoft/redirect 如果你想使用 Microsoft SSO
  • https://{your-domain}/auth/microsoft-apis/get-access-token

​
在 Twenty 中配置

  1. 转到 设置 → 管理员面板 → 配置变量
  2. 找到 Microsoft 身份验证 部分
  3. 设置这些变量：
    • MESSAGING_PROVIDER_MICROSOFT_ENABLED=true
    • CALENDAR_PROVIDER_MICROSOFT_ENABLED=true
    • AUTH_MICROSOFT_ENABLED=true
    • AUTH_MICROSOFT_CLIENT_ID={client-id}
    • AUTH_MICROSOFT_CLIENT_SECRET={client-secret}
    • AUTH_MICROSOFT_CALLBACK_URL=https://{your-domain}/auth/microsoft/redirect
    • AUTH_MICROSOFT_APIS_CALLBACK_URL=https://{your-domain}/auth/microsoft-apis/get-access-token
仅限环境模式： 如果你设置 IS_CONFIG_VARIABLES_IN_DB_ENABLED=false，请将这些变量添加到 .env 文件中。

​
配置范围

查看相关源码
  • ‘openid’
  • ‘电子邮件’
  • ‘个人资料’
  • ‘offline_access’
  • ‘Mail.ReadWrite’
  • ‘Mail.Send’
  • ‘Calendars.Read’

​
如果你的应用程序处于测试模式

如果你的应用程序处于测试模式，你需要将测试用户添加到你的项目中。 将你的测试用户添加到“用户和组”部分。

​
日历和消息传递的后台作业

在配置完 Gmail、Google Calendar 或 Microsoft 365 集成后，你需要启动同步数据的后台作业。 在你的工作容器中注册以下重复作业： 
# from your worker container
yarn command:prod cron:messaging:messages-import
yarn command:prod cron:messaging:message-list-fetch
yarn command:prod cron:calendar:calendar-event-list-fetch
yarn command:prod cron:calendar:calendar-events-import
yarn command:prod cron:messaging:ongoing-stale
yarn command:prod cron:calendar:ongoing-stale
yarn command:prod cron:workflow:automated-cron-trigger

​
电子邮件配置

  1. 转到 设置 → 管理员面板 → 配置变量
  2. 找到 电子邮件 部分
  3. 配置你的 SMTP 设置：
仅限环境模式： 如果你设置 IS_CONFIG_VARIABLES_IN_DB_ENABLED=false，请将这些变量添加到 .env 文件中。

​
S3 存储

默认情况下，Twenty 将上传的文件存储在本地文件系统上。 对于生产环境部署，请使用 S3 或兼容 S3 的服务（MinIO、DigitalOcean Spaces 等）。 以确保文件在容器重启后仍然存在，并可在多个服务器实例间扩展。
设置 STORAGE_TYPE=S_3，并通过管理面板或 .env 配置 STORAGE_S3_* 变量。 有关 S3 变量的完整列表，请参见config-variables.ts 参考。 在将 S3 与依赖 CORS 的功能（例如浏览器内文件下载）一起使用时，请确保你的存储桶在其 CORS 配置中允许你的 Twenty 前端来源。

​
逻辑函数与代码解释器

Twenty 支持用于工作流的逻辑函数，以及用于 AI 数据分析的代码解释器。 二者都会运行用户提供的代码，并要求进行显式配置以确保安全。

​
安全默认设置

在生产环境（NODE_ENV=production）： 逻辑函数和代码解释器的默认设置为禁用。 如需这些功能，必须通过 LOGIC_FUNCTION_TYPE 和 CODE_INTERPRETER_TYPE 显式启用它们。 在开发环境（NODE_ENV=development）： 为方便在本地运行，二者默认均为LOCAL。
安全提示： 本地驱动（LOGIC_FUNCTION_TYPE=LOCAL 或 CODE_INTERPRETER_TYPE=LOCAL）会在没有沙箱的情况下，在主机上的 Node.js 进程中直接运行代码。 它应仅在开发环境中用于可信代码。 对于在生产环境中处理不受信任代码的部署，请使用 LOGIC_FUNCTION_TYPE=LAMBDA 或 CODE_INTERPRETER_TYPE=E2B（使用沙盒），或将它们保持禁用。

​
逻辑函数 - 可用驱动程序

驱动环境变量用例安全级别
禁用LOGIC_FUNCTION_TYPE=DISABLED完全禁用逻辑函数不适用
本地LOGIC_FUNCTION_TYPE=LOCAL开发和可信环境低（无沙箱）
LambdaLOGIC_FUNCTION_TYPE=LAMBDA生产环境（处理不受信任代码）高（硬件级隔离）

​
逻辑函数 - 推荐配置

用于开发： 
LOGIC_FUNCTION_TYPE=LOCAL  # default when NODE_ENV=development
用于生产（AWS）： 
LOGIC_FUNCTION_TYPE=LAMBDA
LOGIC_FUNCTION_LAMBDA_REGION=us-east-1
LOGIC_FUNCTION_LAMBDA_ROLE=arn:aws:iam::123456789:role/your-lambda-role
LOGIC_FUNCTION_LAMBDA_ACCESS_KEY_ID=your-access-key
LOGIC_FUNCTION_LAMBDA_SECRET_ACCESS_KEY=your-secret-key
要禁用逻辑函数： 
LOGIC_FUNCTION_TYPE=DISABLED  # default when NODE_ENV=production

​
代码解释器 - 可用驱动程序

驱动环境变量用例安全级别
禁用CODE_INTERPRETER_TYPE=DISABLED禁用 AI 代码执行不适用
本地CODE_INTERPRETER_TYPE=LOCAL仅限开发环境低（无沙箱）
E2BCODE_INTERPRETER_TYPE=E_2_B生产环境（沙盒化执行）高（隔离沙盒）
当使用 LOGIC_FUNCTION_TYPE=DISABLED 或 CODE_INTERPRETER_TYPE=DISABLED 时，任何执行尝试都会返回错误。 如果你想在不启用这些功能的情况下运行 Twenty，这将很有用。