Обзор
Twenty предлагает два режима конфигурации, чтобы соответствовать разным потребностям развертывания: Доступ к панели администратора: Только пользователи с правами администратора (canAccessFullAdminPanel: true) могут получить доступ к интерфейсу конфигурации.
1. Конфигурация панели администратора (по умолчанию)
- Получите доступ к вашему экземпляру Twenty (обычно
http://localhost:3000) - Перейдите в Настройки / Панель администратора / Переменные конфигурации
- Настройте интеграции, почту, хранилище и многое другое
- Изменения вступают в силу немедленно (в течение 15 секунд для многоконтейнерных развертываний)
- Аутентификация - Google/Microsoft OAuth, настройки паролей
- Электронная почта - настройки SMTP, шаблоны, верификация
- Хранилище - конфигурация S3, пути локального хранения
- Интеграции - Gmail, Google Calendar, сервисы Microsoft
- Рабочий процесс и Ограничения скорости - лимиты выполнения, ограничение API
- И многое другое…

Ключи шифрования
Twenty использует два ключа шифрования, задаваемых только через переменные окружения:
Для обеспечения обратной совместимости, если
ENCRYPTION_KEY не задан, Twenty использует APP_SECRET для шифрования данных в состоянии покоя — что соответствует устаревшему поведению для более старых развертываний. Для новых установок всегда следует задавать отдельный ENCRYPTION_KEY.
Генерируйте значения с помощью openssl rand -base64 32 и храните их в безопасном месте (менеджер секретов, защищённая конфигурация и т. п.). Потеря ENCRYPTION_KEY означает потерю доступа ко всем секретам, хранящимся в базе данных.
Чтобы выполнить ротацию ENCRYPTION_KEY без простоя, см. руководство по ротации ключей.
2. Конфигурация только для среды
.env:
- Установите
IS_CONFIG_VARIABLES_IN_DB_ENABLED=falseв своем.envфайле - Добавьте все переменные конфигурации в ваш файл
.env - Перезапустите контейнеры, чтобы изменения вступили в силу
- Панель администратора будет показывать текущие значения, но не сможет их изменить
Режим нескольких рабочих пространств
По умолчанию Twenty работает в режиме одного рабочего пространства — оптимально для большинства развертываний с самостоятельным размещением, где вашей организации нужен один экземпляр CRM.Режим одного рабочего пространства (по умолчанию)
- Одно рабочее пространство на один экземпляр Twenty
- Первый пользователь автоматически становится администратором с полными привилегиями (
canImpersonateиcanAccessFullAdminPanel) - Новые регистрации отключаются после создания первого рабочего пространства
- Простая структура URL:
https://your-domain.com
Включение режима нескольких рабочих пространств
- На одном экземпляре можно создать несколько рабочих пространств
- Каждое рабочее пространство получает собственный поддомен (например,
sales.your-domain.com,marketing.your-domain.com) - Пользователи регистрируются и входят на
{DEFAULT_SUBDOMAIN}.your-domain.com(например,app.your-domain.com) - Нет автоматических привилегий администратора — первый пользователь в каждом рабочем пространстве является обычным пользователем
- Параметры, специфичные для рабочего пространства, такие как поддомен и пользовательский домен, становятся доступны в настройках рабочего пространства
Настройка DNS для режима нескольких рабочих пространств
При использовании режима нескольких рабочих пространств настройте DNS с помощью подстановочной записи, чтобы разрешить динамическое создание поддоменов:Ограничение создания рабочих пространств
В режиме нескольких рабочих пространств вы можете ограничить круг пользователей, которые могут создавать новые рабочие пространства:canAccessFullAdminPanel могут создавать дополнительные рабочие пространства. Пользователи все равно могут создать свое первое рабочее пространство во время первоначальной регистрации.
Интеграция Gmail и Google Calendar
Создайте проект в Google Cloud
- Перейдите в Google Cloud Console
- Создайте новый проект или выберите существующий
- Включите следующие API:
Настройте OAuth
- Перейдите к Учётные данные
- Создайте OAuth 2.0 Client ID
- Добавьте эти URI перенаправления:
https://{your-domain}/auth/google/redirect(для SSO)https://{your-domain}/auth/google-apis/get-access-token(для интеграций)
Настройка в Twenty
- Перейдите в Настройки → Панель администратора → Переменные конфигурации
- Найдите раздел Google Auth
- Установите эти переменные:
MESSAGING_PROVIDER_GMAIL_ENABLED=trueCALENDAR_PROVIDER_GOOGLE_ENABLED=trueAUTH_GOOGLE_CLIENT_ID={client-id}AUTH_GOOGLE_CLIENT_SECRET={client-secret}AUTH_GOOGLE_CALLBACK_URL=https://{your-domain}/auth/google/redirectAUTH_GOOGLE_APIS_CALLBACK_URL=https://{your-domain}/auth/google-apis/get-access-token
https://www.googleapis.com/auth/calendar.eventshttps://www.googleapis.com/auth/gmail.readonlyhttps://www.googleapis.com/auth/profile.emails.read
Если ваше приложение находится в тестовом режиме
Если ваше приложение находится в тестовом режиме, вам потребуется добавить тестовых пользователей в ваш проект. На экране согласия OAuth добавьте тестовых пользователей в раздел “Тестовые пользователи”.Интеграция Microsoft 365
Создайте проект в Microsoft Azure
Вам потребуется создать проект в Microsoft Azure и получить учетные данные.Включите API
На консоли Microsoft Azure включите следующие API в “Разрешениях”:- Microsoft Graph: Mail.ReadWrite
- Microsoft Graph: Mail.Send
- Microsoft Graph: Calendars.ReadWrite
- Microsoft Graph: User.Read
- Microsoft Graph: openid
- Microsoft Graph: email
- Microsoft Graph: profile
- Microsoft Graph: offline_access
Все эти разрешения обязательны, даже если вы хотите синхронизировать только электронные письма и события календаря. Twenty всегда запрашивает “Mail.ReadWrite”, “Mail.Send” и “Calendars.ReadWrite”, когда пользователь подключает свою учетную запись, поэтому разрешений только для чтения, таких как “Mail.Read” или “Calendars.Read”, недостаточно.
Если ваш клиент не позволяет обычным пользователям давать согласие на эти разрешения, при подключении учетной записи они увидят ошибку AADSTS90094. Администратор может исправить это, нажав “Grant admin consent for ” на странице “API permissions” регистрации приложения.
Авторизованные URI перенаправления
Вам нужно добавить следующие URI перенаправления в ваш проект:https://{your-domain}/auth/microsoft/redirectесли вы хотите использовать Microsoft SSOhttps://{your-domain}/auth/microsoft-apis/get-access-token
Настройка в Twenty
- Перейдите в Настройки → Панель администратора → Переменные конфигурации
- Найдите раздел Microsoft Auth
- Установите эти переменные:
MESSAGING_PROVIDER_MICROSOFT_ENABLED=trueCALENDAR_PROVIDER_MICROSOFT_ENABLED=trueAUTH_MICROSOFT_ENABLED=trueAUTH_MICROSOFT_CLIENT_ID={client-id}AUTH_MICROSOFT_CLIENT_SECRET={client-secret}AUTH_MICROSOFT_CALLBACK_URL=https://{your-domain}/auth/microsoft/redirectAUTH_MICROSOFT_APIS_CALLBACK_URL=https://{your-domain}/auth/microsoft-apis/get-access-token
Настройка областей доступа
соответствующий исходный код](https://github.com/twentyhq/twenty/blob/main/packages/twenty-server/src/engine/core-modules/auth/utils/get-microsoft-apis-oauth-scopes.ts#L2-L11)- ‘openid’
- ‘электронная почта’
- ‘профиль’
- ‘offline_access’
- ‘Mail.ReadWrite’
- ‘Mail.Send’
- ‘Calendars.ReadWrite’
- ‘User.Read’
Если ваше приложение находится в тестовом режиме
Если ваше приложение находится в тестовом режиме, вам потребуется добавить тестовых пользователей в ваш проект. Добавьте тестовых пользователей в раздел “Пользователи и группы”.Фоновые задания для Календаря и Сообщений
После настройки интеграций Gmail, Google Calendar или Microsoft 365, вам необходимо запустить фоновые задания, синхронизирующие данные. Зарегистрируйте следующие повторяющиеся задания в вашем контейнере рабочего:Исходящие подключения к внутренним хостам
По умолчанию Twenty отклоняет исходящие подключения к частным/внутренним IP-адресам (защита от SSRF). Это относится к HTTP-действиям рабочих процессов, вебхукам, поставщикам удостоверений SSO и подключениям IMAP/SMTP/CalDAV. Если ваш поставщик удостоверений, почтовый или календарный сервер работает в частной сети, укажите его имя хоста или IP-адрес:http://keycloak:8080/realms/twenty, укажите keycloak. Все остальные частные адреса остаются заблокированными, и даже разрешенный хост никогда не сможет получить доступ к диапазону адресов метаданных облака. Установите для переменной значение *, чтобы полностью отключить защиту; это допустимо только в доверенных изолированных сетях.
OUTBOUND_HTTP_SAFE_MODE_ENABLED устарела. Пока ей присвоено значение false, защита остается полностью отключенной, а OUTBOUND_HTTP_ALLOWED_INTERNAL_HOSTS игнорируется, поэтому удалите ее при переходе на список.
Этот список не охватывает вложения файлов для ИИ: изображения и PDF поступают в модель в виде ссылок, сформированных из SERVER_URL и получаемых либо поставщиком ИИ, либо AI SDK в воркере, который отклоняет приватные адреса. Для работы вложений SERVER_URL должен быть общедоступным; при localhost или приватном SERVER_URL чаты и агенты ИИ работают только с текстом.
Конфигурация электронной почты
- Перейдите в Настройки → Панель администратора → Переменные конфигурации
- Найдите раздел Электронной почты
- Настройте параметры вашего SMTP:
- Gmail
- Office365
- smtp4dev
Вам потребуется предоставить Пароль Приложения.
- 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’
S3 Хранилище
УстановитеSTORAGE_TYPE=S_3 и настройте переменные STORAGE_S3_* через админ-панель или .env.
Минимальный
.env для AWS S3 с пользователем IAM:
Файл Docker Compose передает из
.env STORAGE_TYPE, STORAGE_S3_REGION, STORAGE_S3_NAME, STORAGE_S3_ENDPOINT и две переменные учетных данных. Задайте переменные предварительно подписанных URL-адресов в панели администратора или добавьте их в блок environment сервисов server и worker.Учётные данные
КогдаSTORAGE_S3_ACCESS_KEY_ID не задан, сервер получает учетные данные через цепочку AWS SDK по умолчанию: переменные среды AWS_ACCESS_KEY_ID и AWS_SECRET_ACCESS_KEY, общий файл учетных данных, роль задачи ECS, роль учетной записи сервиса EKS (IRSA) или профиль экземпляра EC2.
CredentialsProviderError: Could not load credentials from any providers, тогда как в пользовательском интерфейсе отображается только общая ошибка.
Разрешения бакета
Сначала загружаемый файл записывается во временный путь, проверяется, затем копируется в окончательный путь, а временный объект удаляется. Поэтому политике требуется больше, чемs3:PutObject:
s3:ListBucket используется для удаления папок, например при удалении рабочего пространства. Без него S3 отвечает на запросы отсутствующих объектов ошибкой отказа в доступе вместо сообщения об отсутствии объекта, поэтому сервер не может отличить отсутствующий файл от проблемы с разрешениями.
Конечная точка и адресация
Twenty всегда использует адресацию в стиле пути, поэтому запросы направляются наhttps://endpoint/bucket/key. Для нативного AWS S3 не задавайте STORAGE_S3_ENDPOINT: SDK формирует https://s3.{region}.amazonaws.com из STORAGE_S3_REGION, поэтому ошибка в названии региона проявляется как ошибка DNS, а не ошибка S3. Задавайте конечную точку только для S3-совместимых сервисов или когда сервер обращается к S3 через конечную точку интерфейса VPC.
CORS (совместное использование ресурсов между источниками)
КогдаSTORAGE_S3_PRESIGNED_URL_ENABLED имеет значение true, браузеры взаимодействуют с бакетом напрямую. Скачивания выполняются запросами GET, а загрузки — запросами PUT с заголовком Content-Type, из-за чего браузер сначала отправляет предварительный запрос. Поэтому политика CORS бакета должна разрешать ваш источник Twenty, оба метода и этот заголовок:
Устранение неполадок
Ошибки загрузки отображаются в пользовательском интерфейсе как общая ошибка. Базовая ошибка S3 содержится в журналах сервера (docker compose logs server) и в ответе GraphQL, видимом на вкладке сети браузера.
Логические функции и интерпретатор кода
Twenty поддерживает логические функции для рабочих процессов и интерпретатор кода для анализа данных ИИ. Оба запускают предоставленный пользователем код и требуют явной настройки в целях безопасности.Настройки безопасности по умолчанию
В продакшене (NODE_ENV=production): логические функции и интерпретатор кода по умолчанию — Отключено. Если вам нужны эти функции, вы должны явно включить их с помощьюLOGIC_FUNCTION_TYPE и CODE_INTERPRETER_TYPE.
В разработке (NODE_ENV=development): оба по умолчанию — LOCAL для удобства при локальном запуске.
Логические функции — доступные драйверы
Логические функции — рекомендуемая конфигурация
Для разработки:Интерпретатор кода — доступные драйверы
При использовании
LOGIC_FUNCTION_TYPE=DISABLED или CODE_INTERPRETER_TYPE=DISABLED любая попытка выполнения вернёт ошибку. Это полезно, если вы хотите запускать Twenty без этих возможностей.API и фронтенд на отдельных хостах
Актуально только в том случае, если вы не позволяете бэкенду обслуживать фронтенд. Для развертываний с одинаковым origin здесь ничего не требуется. Укажите каждый браузерный origin, который обращается к API, через запятую.SERVER_URL
и FRONTEND_URL уже считаются доверенными. Сервер записывает предупреждение в журнал, когда браузер
обращается к нему с неуказанного источника.
AUTH_COOKIE_SAME_SITE=none, что требует HTTPS.
При включённой поддержке нескольких рабочих пространств не перечисляйте здесь все поддомены рабочих пространств.
Вместо этого маршрутизируйте пути API (/graphql, /metadata, /rest, /auth/, /client-config, /file) на бэкенд для каждого имени хоста рабочего пространства, чтобы каждое рабочее пространство оставалось в рамках одного источника (same-origin) — именно так работает Twenty Cloud.