--- title: 设置 icon: 齿轮 --- # 配置管理 **第一次安装？** 请按照 [Docker Compose 安装指南](/l/zh/developers/self-host/capabilities/docker-compose) 获得 Twenty 运行，然后返回此处进行配置。 Twenty 提供**两种配置模式**以适应不同的部署需求： **管理员面板访问：** 只有具有管理员权限的用户(`canAccessFullAdminPanel: true`) 可以访问配置界面。 ## 1. 管理员面板配置（默认） ```bash 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 限流 * **还有更多……** ![管理员面板配置变量](/images/user-guide/setup/admin-panel-config-variables.png) 每个变量都在您的管理面板的**设置 → 管理员面板 → 配置变量**中记录了说明。 某些基础设施设置如数据库连接 (`PG_DATABASE_URL`)、服务器 URL (`SERVER_URL`) 和密钥（`ENCRYPTION_KEY`、`FALLBACK_ENCRYPTION_KEY`）只能通过 `.env` 文件配置。 [完整技术参考→](https://github.com/twentyhq/twenty/blob/main/packages/twenty-server/src/engine/core-modules/twenty-config/config-variables.ts) ## 加密密钥 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`，请参阅[密钥轮换指南](/l/zh/developers/self-host/capabilities/key-rotation)。 ## 2. 仅限环境配置 ```bash IS_CONFIG_VARIABLES_IN_DB_ENABLED=false ``` **所有配置通过 `.env` 文件管理：** 1. 在 `.env` 文件中设置 `IS_CONFIG_VARIABLES_IN_DB_ENABLED=false` 2. 将所有配置变量添加到 `.env` 文件中 3. 重启容器以使更改生效 4. 管理员面板将显示当前值，但无法修改它们 ## 多工作区模式 默认情况下，Twenty 以**单工作区模式**运行——对于大多数需要为组织部署一个 CRM 实例的自托管部署而言，这是理想之选。 ### 单工作区模式（默认） ```bash IS_MULTIWORKSPACE_ENABLED=false # default ``` * 每个 Twenty 实例一个工作区 * 首位用户会自动成为具有完整权限的管理员（`canImpersonate` 和 `canAccessFullAdminPanel`） * 创建第一个工作区后，新注册将被禁用 * 简单的 URL 结构：`https://your-domain.com` ### 启用多工作区模式 ```bash 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 的情况下自动进行子域路由。 ### 限制工作区创建 在多工作区模式下，你可能希望限制谁可以创建新工作区： ```bash IS_WORKSPACE_CREATION_LIMITED_TO_SERVER_ADMINS=true ``` 启用后，只有具有 `canAccessFullAdminPanel` 权限的用户才能创建其他工作区。 用户仍可在首次注册时创建他们的第一个工作区。 ## Gmail & Google Calendar 集成 ### 创建 Google 云项目 1. 转到 [Google 云控制台](https://console.cloud.google.com/) 2. 创建新项目或选择现有项目 3. 启用这些 API： * [Gmail API](https://console.cloud.google.com/apis/library/gmail.googleapis.com) * [Google Calendar API](https://console.cloud.google.com/apis/library/calendar-json.googleapis.com) * [People API](https://console.cloud.google.com/apis/library/people.googleapis.com) ### 配置 OAuth 1. 转到 [凭据](https://console.cloud.google.com/apis/credentials) 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://github.com/twentyhq/twenty/blob/main/packages/twenty-server/src/engine/core-modules/auth/utils/get-google-apis-oauth-scopes.ts#L4-L10) * `https://www.googleapis.com/auth/calendar.events` * `https://www.googleapis.com/auth/gmail.readonly` * `https://www.googleapis.com/auth/profile.emails.read` ### 如果你的应用程序处于测试模式 如果你的应用程序处于测试模式，你需要将测试用户添加到你的项目中。 在 [OAuth 同意屏幕](https://console.cloud.google.com/apis/credentials/consent) 下，将你的测试用户添加到 "测试用户" 部分。 ## Microsoft 365 集成 用户必须拥有 [Microsoft 365 许可证](https://admin.microsoft.com/Adminportal/Home) 才能使用日历和消息传递 API。 没有许可证，他们将无法在 Twenty 上同步他们的帐户。 ### 在 Microsoft Azure 中创建项目 你需要在 [Microsoft Azure](https://portal.azure.com/#view/Microsoft_AAD_IAM/AppGalleryBladeV2) 中创建项目并获取凭据。 ### 启用 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` 文件中。 ### 配置范围 [查看相关源码](https://github.com/twentyhq/twenty/blob/main/packages/twenty-server/src/engine/core-modules/auth/utils/get-microsoft-apis-oauth-scopes.ts#L2-L9) * 'openid' * '电子邮件' * '个人资料' * 'offline_access' * 'Mail.ReadWrite' * 'Mail.Send' * 'Calendars.Read' ### 如果你的应用程序处于测试模式 如果你的应用程序处于测试模式，你需要将测试用户添加到你的项目中。 将你的测试用户添加到“用户和组”部分。 ## 日历和消息传递的后台作业 在配置完 Gmail、Google Calendar 或 Microsoft 365 集成后，你需要启动同步数据的后台作业。 在你的工作容器中注册以下重复作业： ```bash # 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 设置： 你需要提供一个 [应用密码](https://support.google.com/accounts/answer/185833)。 * EMAIL_DRIVER=smtp * EMAIL_SMTP_HOST=smtp.gmail.com * EMAIL_SMTP_PORT=465 * EMAIL_SMTP_USER=gmail_email_address * EMAIL_SMTP_PASSWORD='gmail_app_password' 请记住，如果您启用了双重身份验证，您需要提供一个 [应用密码](https://support.microsoft.com/en-us/account-billing/manage-app-passwords-for-two-step-verification-d6dc8c6d-4bf7-4851-ad95-6d07799387e9)。 * EMAIL_DRIVER=smtp * EMAIL_SMTP_HOST=smtp.office365.com * EMAIL_SMTP_PORT=587 * EMAIL_SMTP_USER=office365_email_address * EMAIL_SMTP_PASSWORD='office365_password' **smtp4dev** 是一个用于开发和测试的假 SMTP 电子邮件服务器。 * 运行 smtp4dev 镜像： `docker run --rm -it -p 8090:80 -p 2525:25 rnwood/smtp4dev` * 在此处访问 smtp4dev UI：[http://localhost:8090](http://localhost:8090) * 设置以下变量： * EMAIL_DRIVER=smtp * EMAIL_SMTP_HOST=localhost * EMAIL_SMTP_PORT=2525 **仅限环境模式：** 如果你设置 `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 参考](https://github.com/twentyhq/twenty/blob/main/packages/twenty-server/src/engine/core-modules/twenty-config/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` | 开发和可信环境 | 低（无沙箱） | | Lambda | `LOGIC_FUNCTION_TYPE=LAMBDA` | 生产环境（处理不受信任代码） | 高（硬件级隔离） | ### 逻辑函数 - 推荐配置 **用于开发：** ```bash LOGIC_FUNCTION_TYPE=LOCAL # default when NODE_ENV=development ``` **用于生产（AWS）：** ```bash 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 ``` **要禁用逻辑函数：** ```bash LOGIC_FUNCTION_TYPE=DISABLED # default when NODE_ENV=production ``` ### 代码解释器 - 可用驱动程序 | 驱动 | 环境变量 | 用例 | 安全级别 | | --- | -------------------------------- | ----------- | ------- | | 禁用 | `CODE_INTERPRETER_TYPE=DISABLED` | 禁用 AI 代码执行 | 不适用 | | 本地 | `CODE_INTERPRETER_TYPE=LOCAL` | 仅限开发环境 | 低（无沙箱） | | E2B | `CODE_INTERPRETER_TYPE=E_2_B` | 生产环境（沙盒化执行） | 高（隔离沙盒） | 当使用 `LOGIC_FUNCTION_TYPE=DISABLED` 或 `CODE_INTERPRETER_TYPE=DISABLED` 时，任何执行尝试都会返回错误。 如果你想在不启用这些功能的情况下运行 Twenty，这将很有用。