upstream-twenty/packages/twenty-docs/l/zh/developers/self-host/capabilities/setup.mdx

---
title: 设置
icon: gear
---

# 配置管理

<Warning>
**第一次安装？** 请按照 [Docker Compose 安装指南](/l/zh/developers/self-host/capabilities/docker-compose) 获得 Twenty 运行，然后返回此处进行配置。
</Warning>

Twenty 提供**两种配置模式**以适应不同的部署需求：

**管理员面板访问：** 只有具有管理员权限的用户(`canAccessFullAdminPanel: true`) 可以访问配置界面。

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

```bash
IS_CONFIG_VARIABLES_IN_DB_ENABLED=true  # default
```

**大多数配置在安装后通过 UI 进行：**

1. 访问你的 Twenty 实例（通常为 `http://localhost:3000`)
2. 转到 **设置 / 管理员面板 / 配置变量**
3. 配置集成、电子邮件、存储等
4. 更改会立即生效（多容器部署在 15 秒内）

<Warning>
**多容器部署：** 当使用数据库配置（`IS_CONFIG_VARIABLES_IN_DB_ENABLED=true`）时，server 和 worker 容器都会从同一个数据库读取。 管理员面板更改会自动影响两者，无需在容器之间重复环境变量（基础设施变量除外）。
</Warning>

**通过管理员面板可以配置的内容：**

* **身份验证** - Google/Microsoft OAuth、密码设置
* **电子邮件** - SMTP 设置、模板、验证
* **存储** - S3 配置、本地存储路径
* **集成** - Gmail, Google Calendar, Microsoft 服务
* **工作流和速率限制** - 执行限制、API 限流
* **还有更多……**

![管理员面板配置变量](/images/user-guide/setup/admin-panel-config-variables.png)

<Warning>
每个变量都在您的管理面板的**设置 → 管理员面板 → 配置变量**中记录了说明。
某些基础设施设置如数据库连接 (`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)
</Warning>

## 加密密钥

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`）
* 不自动授予管理员权限——每个工作区的首位用户是普通用户
* 子域、自定义域名等与工作区相关的设置将在工作区设置中可用。

<Warning>
**仅限环境的设置：**`IS_MULTIWORKSPACE_ENABLED` 只能通过 `.env` 文件进行配置，并且需要重启。 无法通过管理面板进行更改。
</Warning>

### 多工作区模式的 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`

<Warning>
**仅限环境模式：** 如果你设置 `IS_CONFIG_VARIABLES_IN_DB_ENABLED=false`，请将这些变量添加到 `.env` 文件中。
</Warning>

**所需范围**（自动配置）：
[查看相关源码](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 集成

<Warning>
用户必须拥有 [Microsoft 365 许可证](https://admin.microsoft.com/Adminportal/Home) 才能使用日历和消息传递 API。 没有许可证，他们将无法在 Twenty 上同步他们的帐户。
</Warning>

### 在 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

<Note>
“Mail.ReadWrite”和“Mail.Send”仅在你想使用我们的工作流程操作发送电子邮件时是必需的。 如果你只想接收邮件，你可以使用“Mail.Read”。
</Note>

<Note>
如果你想使用我们的工作流操作创建日历事件，则必须使用 "Calendars.ReadWrite"。 如果你只想同步日历事件，请使用 "Calendars.Read"。
</Note>

### 授权重定向 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`

<Warning>
**仅限环境模式：** 如果你设置 `IS_CONFIG_VARIABLES_IN_DB_ENABLED=false`，请将这些变量添加到 `.env` 文件中。
</Warning>

### 配置范围

[查看相关源码](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 设置：

<Tabs>

  <Tab title="Gmail">

  你需要提供一个 [应用密码](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'

  </Tab>

  <Tab title="Office365">

  请记住，如果您启用了双重身份验证，您需要提供一个 [应用密码](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'

  </Tab>

  <Tab title="smtp4dev">

  **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

  </Tab>

</Tabs>

<Warning>
**仅限环境模式：** 如果你设置 `IS_CONFIG_VARIABLES_IN_DB_ENABLED=false`，请将这些变量添加到 `.env` 文件中。
</Warning>

## S3 存储

<Warning>
默认情况下，Twenty 将上传的文件存储在本地文件系统上。 对于生产环境部署，请使用 S3 或兼容 S3 的服务（MinIO、DigitalOcean Spaces 等）。 以确保文件在容器重启后仍然存在，并可在多个服务器实例间扩展。
</Warning>

设置 `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**。

<Warning>
**安全提示：** 本地驱动（`LOGIC_FUNCTION_TYPE=LOCAL` 或 `CODE_INTERPRETER_TYPE=LOCAL`）会在没有沙箱的情况下，在主机上的 Node.js 进程中直接运行代码。 它应仅在开发环境中用于可信代码。 对于在生产环境中处理不受信任代码的部署，请使用 `LOGIC_FUNCTION_TYPE=LAMBDA` 或 `CODE_INTERPRETER_TYPE=E2B`（使用沙盒），或将它们保持禁用。
</Warning>

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

| 驱动     | 环境变量                           | 用例             | 安全级别     |
| ------ | ------------------------------ | -------------- | -------- |
| 禁用     | `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`    | 生产环境（沙盒化执行） | 高（隔离沙盒） |

<Note>
当使用 `LOGIC_FUNCTION_TYPE=DISABLED` 或 `CODE_INTERPRETER_TYPE=DISABLED` 时，任何执行尝试都会返回错误。 如果你想在不启用这些功能的情况下运行 Twenty，这将很有用。
</Note>

## API 和前端位于不同主机上

仅当你不让后端来提供前端资源时，此项才相关。 同源部署在这里无需任何设置。

声明每一个与 API 通信的浏览器来源（origin），使用逗号分隔。 `SERVER_URL`
和 `FRONTEND_URL` 已被信任。 当浏览器从未声明的来源调用它时，服务器会记录一条警告日志。

```bash
AUTH_COOKIE_ALLOWED_ORIGINS=https://app.example.com
```

<Warning>
前端会在每个请求中发送凭据，而浏览器会拒绝来自未声明源的携带凭据的响应，因此在你完成此设置之前，应用将无法加载。
</Warning>

如果这两个主机位于不同的可注册域（不仅仅是不同的子域），还需要设置 `AUTH_COOKIE_SAME_SITE=none`，并且这要求使用 HTTPS。

在启用多工作区功能时，不要在此列出每个工作区的子域名。
相反，请在每个工作区主机名上将 API 路径（`/graphql`、`/metadata`、`/rest`、`/auth/`、`/client-config`、`/file`）路由到后端，这样每个工作区都保持同源 —— 这正是 Twenty Cloud 的运行方式。