snapshot of https://github.com/twentyhq/twenty.git (main, 2026-09-17; blobs > 131072B omitted)

packages/twenty-docs/l/ru/developers/self-host/capabilities/docker-compose.mdx

@@ -0,0 +1,262 @@
+---
+title: Docker Compose
+icon: docker
+---
+
+<Warning>
+Контейнеры Docker предназначены для продакшен-хостинга или саморазмещения. Для участия в разработке см. [Локальная настройка](/l/ru/developers/contribute/capabilities/local-setup).
+</Warning>
+
+## Обзор
+
+Это руководство предоставляет пошаговые инструкции по установке и настройке приложения Twenty с помощью Docker Compose. Цель заключается в том, чтобы сделать процесс простым и избежать распространенных ошибок, которые могут привести к сбоям в настройке.
+
+**Важно:** изменяйте только те настройки, которые явно упоминаются в этом руководстве. Изменение других конфигураций может привести к проблемам.
+
+См. [Настройка переменных окружения](/l/ru/developers/self-host/capabilities/setup) для расширенной конфигурации. Все переменные окружения должны быть задекларированы в файле `docker-compose.yml` на уровне сервера и/или воркера, в зависимости от переменной.
+
+## Системные требования
+
+* ОЗУ: Убедитесь, что в вашей среде не менее 2 ГБ ОЗУ. Недостаток памяти может вызвать сбой процессов.
+* Docker и Docker Compose: убедитесь, что оба установлены и обновлены.
+
+## Вариант 1: Скрипт с одной строкой
+
+Установите последнюю стабильную версию Twenty одной командой:
+
+```bash
+bash <(curl -sL https://raw.githubusercontent.com/twentyhq/twenty/main/packages/twenty-docker/scripts/install.sh)
+```
+
+Для установки конкретной версии или ветки:
+
+```bash
+VERSION=vx.y.z BRANCH=branch-name bash <(curl -sL https://raw.githubusercontent.com/twentyhq/twenty/main/packages/twenty-docker/scripts/install.sh)
+```
+
+* Замените x.y.z на желаемый номер версии.
+* Замените branch-name на имя ветки, которую вы хотите установить.
+
+## Вариант 2: Ручные шаги
+
+Выполните следующие шаги для ручной настройки.
+
+### Шаг 1: Настройте файл среды
+
+1. **Создайте файл .env**
+
+   Скопируйте пример файла окружения в новый .env файл в вашем рабочем каталоге:
+
+   ```bash
+   curl -o .env https://raw.githubusercontent.com/twentyhq/twenty/refs/heads/main/packages/twenty-docker/.env.example
+   ```
+
+2. **Сгенерируйте ключ шифрования**
+
+   Выполните следующую команду для генерации уникальной случайной строки:
+
+   ```bash
+   openssl rand -base64 32
+   ```
+
+   **Внимание:** держите это значение в секрете / не делитесь им. Потеря `ENCRYPTION_KEY` означает потерю доступа ко всем секретам, хранящимся в базе данных (OAuth-токены, переменные приложения, TOTP-секреты и т. д.).
+
+3. **Обновите файл `.env`**
+
+   Замените значение плейсхолдера в вашем файле .env на сгенерированный токен:
+
+   ```ini
+   ENCRYPTION_KEY=random_string
+   ```
+
+   См. [руководство по ротации ключей](/l/ru/developers/self-host/capabilities/key-rotation) для получения инструкций по их ротации без простоя.
+
+4. **Установите пароль для Postgres**
+
+   Обновите значение `PG_DATABASE_PASSWORD` в файле .env, используя надежный пароль без специальных символов.
+
+   ```ini
+   PG_DATABASE_PASSWORD=my_strong_password
+   ```
+
+### Шаг 2: Получите файл Docker Compose
+
+Скачайте файл `docker-compose.yml` в ваш рабочий каталог:
+
+```bash
+curl -o docker-compose.yml https://raw.githubusercontent.com/twentyhq/twenty/refs/heads/main/packages/twenty-docker/docker-compose.yml
+```
+
+### Шаг 3: Запустите приложение
+
+Запустите Docker-контейнеры:
+
+```bash
+docker compose up -d
+```
+
+### Шаг 4: Доступ к приложению
+
+Если вы размещаете twentyCRM на своем компьютере, откройте ваш браузер и перейдите на [http://localhost:3000](http://localhost:3000).
+
+Если вы размещаете это на сервере, убедитесь, что сервер запущен и что все в порядке с
+
+```bash
+curl http://localhost:3000
+```
+
+## Конфигурация
+
+### Открыть доступ к Twenty из внешней сети
+
+По умолчанию Twenty работает на `localhost` на порту `3000`. Пользовательский интерфейс определяет API из источника самого браузера, поэтому он загружается с любого имени хоста, который обращается к контейнеру, — но всё равно укажите `SERVER_URL` как ваш публичный URL: сервер использует его для сгенерированных ссылок (email‑сообщений, OAuth‑обратных вызовов) и для определения HTTPS для защищённых cookie.
+
+#### Понимание `SERVER_URL`
+
+* **Протокол:** используйте `http` или `https` в зависимости от вашей настройки.
+  * Используйте `http`, если SSL не настроен.
+  * Используйте `https`, если SSL настроен.
+* **Домен/IP:** это имя домена или IP-адрес, где ваше приложение доступно.
+* **Порт:** указывайте номер порта, если вы не используете порты по умолчанию (`80` для `http`, `443` для `https`).
+
+### Требования к SSL
+
+SSL (HTTPS) требуется для правильной работы некоторых функций браузера. Хотя эти функции могут работать во время разработки на локальном компьютере (поскольку браузеры обрабатывают localhost иначе), правильная настройка SSL необходима при размещении Twenty на регулярном домене.
+
+Например, API буфера обмена может потребовать защищенный контекст - некоторые функции, такие как кнопки копирования в приложении, могут не работать без включения HTTPS.
+
+Мы настоятельно рекомендуем настроить Twenty за обратным прокси-сервером с прекращением SSL для оптимальной безопасности и функциональности.
+
+#### Настройка `SERVER_URL`
+
+1. **Определите ваш URL-адрес доступа**
+   * **Без обратного прокси (Прямой доступ):**
+
+     Если вы получаете доступ к приложению напрямую без использования обратного прокси:
+
+     ```ini
+     SERVER_URL=http://your-domain-or-ip:3000
+     ```
+
+   * **С обратным прокси (Стандартные порты):**
+
+     Если вы используете обратный прокси, такой как Nginx или Traefik, и у вас настроен SSL:
+
+     ```ini
+     SERVER_URL=https://your-domain-or-ip
+     ```
+
+   * **С обратным прокси (Не стандартные порты):**
+
+     Если вы используете нестандартные порты:
+
+     ```ini
+     SERVER_URL=https://your-domain-or-ip:custom-port
+     ```
+
+2. **Обновите файл `.env`**
+
+   Откройте ваш файл `.env` и обновите `SERVER_URL`:
+
+   ```ini
+   SERVER_URL=http(s)://your-domain-or-ip:your-port
+   ```
+
+   **Примеры:**
+
+   * Прямой доступ без SSL:
+     ```ini
+     SERVER_URL=http://123.45.67.89:3000
+     ```
+   * Доступ через домен с SSL:
+     ```ini
+     SERVER_URL=https://mytwentyapp.com
+     ```
+
+3. **Перезапустите приложение**
+
+   Для применения изменений перезапустите контейнеры Docker:
+
+   ```bash
+   docker compose down
+   docker compose up -d
+   ```
+
+#### Рассмотрения
+
+* **Конфигурация обратного прокси:**
+
+  Убедитесь, что ваш обратный прокси передаёт запросы на правильный внутренний порт (`3000` по умолчанию). Настройте завершение SSL и все необходимые заголовки.
+
+* **Настройки брандмауэра:**
+
+  Откройте необходимые порты в вашем брандмауэре для обеспечения внешнего доступа.
+
+* **Последовательность:**
+
+  Значение `SERVER_URL` должно соответствовать тому, как пользователи обращаются к вашему приложению в своих браузерах.
+
+#### Сохранение данных
+
+* **Тома данных:**
+
+  Конфигурация Docker Compose использует тома для сохранения данных базы данных и хранилища сервера.
+
+* **Среды без состояния:**
+
+  Если развёртывание осуществляется в бесстатном окружении (например, некоторых облачных сервисах), настройте внешнее хранилище для сохранения данных.
+
+## Резервное копирование и восстановление
+
+Регулярные резервные копии защищают данные вашей CRM от потери.
+
+### Создание резервной копии базы данных
+
+```bash
+docker exec twenty-postgres pg_dump -U postgres twenty > backup_$(date +%Y%m%d).sql
+```
+
+### Автоматизируйте ежедневное резервное копирование
+
+Добавьте в свой crontab (`crontab -e`):
+
+```bash
+0 2 * * * docker exec twenty-postgres pg_dump -U postgres twenty > /backups/twenty_$(date +\%Y\%m\%d).sql
+```
+
+### Восстановление из резервной копии
+
+1. Остановите приложение:
+
+```bash
+docker compose stop server worker
+```
+
+2. Восстановите базу данных:
+
+```bash
+docker exec -i twenty-postgres psql -U postgres twenty < backup_20240115.sql
+```
+
+3. Перезапустите службы:
+
+```bash
+docker compose up -d
+```
+
+### Лучшие практики резервного копирования
+
+* **Регулярно проверяйте восстановление** — убедитесь, что резервные копии действительно работают
+* **Храните резервные копии вне площадки** — используйте облачное хранилище (S3, GCS и т. д.)
+* **Шифруйте конфиденциальные данные** — защищайте резервные копии с помощью шифрования
+* **Храните несколько копий** — сохраняйте ежедневные, еженедельные и ежемесячные резервные копии
+
+## Устранение неполадок
+
+Если у вас возникли проблемы, проверьте [Устранение неполадок](/l/ru/developers/self-host/capabilities/troubleshooting) для получения решений.
+
+## Управляемый хостинг
+
+<Tip>
+  Не хотите запускать и поддерживать Twenty самостоятельно? [Найдите сертифицированного партнёра по хостингу Twenty](https://twenty.com/partners/list?categories=HOSTING\&ref=docs-docker-compose), который развернёт, разместит и полностью возьмёт на себя управление вашим экземпляром. *(Или свяжитесь с нашей командой: [contact@twenty.com](mailto:contact@twenty.com).)*
+</Tip>

packages/twenty-docs/l/ru/developers/self-host/capabilities/key-rotation.mdx

@@ -0,0 +1,60 @@
+---
+title: Ротация ключей
+icon: rotate
+---
+
+У Twenty есть два независимых семейства ключей:
+
+* **Ключи подписи JWT** — асимметричные пары ключей ES256 (с тегами `kid`), хранятся в `core."signingKey"` и используются для подписи и проверки access/refresh-токенов.
+* **Ключ шифрования данных на диске** — `ENCRYPTION_KEY`, используется для шифрования OAuth-токенов, переменных приложения, закрытых ключей подписи, конфиденциальных значений конфигурации и TOTP-секретов внутри оболочки `enc:v2:`.
+
+`APP_SECRET` — устаревший секрет, сохранённый для обратной совместимости: когда `ENCRYPTION_KEY` не установлен, он используется как резерв для шифрования данных на диске/сеансовых cookie и по-прежнему проверяет ранее выданные HS256 access-токены. Он будет объявлен устаревшим.
+
+## Ключи подписи JWT
+
+Каждый ключ содержит `publicKey` (хранится бессрочно, чтобы можно было проверять ранее выданные токены), зашифрованный `privateKey` (используется только пока ключ является текущим), флаг `isCurrent` (в каждый момент времени ровно одна строка) и необязательное поле `revokedAt`.
+
+### Выполнить ротацию текущего ключа
+
+Установите `SIGNING_KEY_ROTATION_DAYS`, чтобы включить эту опцию: ежедневный cron затем будет выпускать новый текущий ключ, как только существующий ключ станет старше этого порогового значения. Предыдущие ключи *не* отзываются, поэтому токены, подписанные ими, продолжают успешно проходить проверку. Оставьте переменную не заданной, чтобы отключить автоматическую ротацию.
+
+<Note>Автоматическая ротация доступна, начиная с версии v2.6+.</Note>
+
+### Отозвать ключ (только при утечке / в экстренных случаях)
+
+**Settings → Admin Panel → Signing keys → Revoke** в нетекущей строке. Стирает зашифрованный закрытый материал, устанавливает `revokedAt` и отклоняет все существующие токены, подписанные с этим `kid`.
+
+## Выполнить ротацию `ENCRYPTION_KEY`
+
+<Note>Команда `secret-encryption:rotate`, описанная ниже, поставляется начиная с v2.6+.</Note>
+
+Каждое зашифрованное значение оборачивается как `enc:v2:\<keyId>:\<payload>`, где `\<keyId>` — это 8-символьный шестнадцатеричный префикс, полученный из исходного ключа. Ротация выполняется онлайн и может быть возобновлена.
+
+1. **Сгенерировать новый ключ**: `openssl rand -base64 32`.
+
+2. **Настройте оба ключа параллельно** в `.env`, затем перезапустите:
+   ```ini
+   ENCRYPTION_KEY=NEW_VALUE
+   FALLBACK_ENCRYPTION_KEY=OLD_VALUE
+   ```
+   Новые записи используют новый ключ, существующие строки по-прежнему расшифровываются через резервный ключ.
+
+3. **Повторно зашифровать существующие строки**:
+
+   ```bash
+   docker exec -it {server_container} yarn command:prod secret-encryption:rotate
+   ```
+
+   Команда обходит шесть разделов (`connected-account-tokens`, `application-variable`, `application-registration-variable`, `signing-key-private-keys`, `sensitive-config-storage`, `totp-secrets`). SQL-фильтр пропускает строки, которые уже находятся на новом `\<keyId>`, поэтому команда идемпотентна: прерывайте и запускайте повторно по мере необходимости. Завершает работу с ненулевым кодом, если какая-либо строка завершилась с ошибкой — запустите повторно, чтобы повторить попытку.
+
+   | Флаг                                     | Описание                                                           |
+   | ---------------------------------------- | ------------------------------------------------------------------ |
+   | `-s, --site \<site>`    | Ограничить одним сайтом.                                           |
+   | `-b, --batch-size \<n>` | Строк в партии (по умолчанию `200`, максимум `5000`).              |
+   | `-d, --dry-run`                          | Расшифровать + повторно зашифровать в памяти, пропустить `UPDATE`. |
+
+4. **Удалите резервный ключ** после того, как `--dry-run` покажет ноль оставшихся строк: удалите `FALLBACK_ENCRYPTION_KEY` и перезапустите.
+
+## Устаревшая поддержка `APP_SECRET`
+
+Более старые инстансы, в которых никогда не был установлен `ENCRYPTION_KEY`, используют `APP_SECRET` как ключ шифрования данных на диске (и как секрет для сеансовых cookie, производный от него). Этот путь сохранен для обратной совместимости, но **устарел** — установите отдельный `ENCRYPTION_KEY` и выполните описанную выше процедуру ротации, чтобы с него мигрировать. Сам `APP_SECRET` продолжает использоваться для проверки устаревших HS256 access-токенов.

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

@@ -0,0 +1,413 @@
+---
+title: Настройка
+icon: gear
+---
+
+# Управление конфигурацией
+
+<Warning>
+**Устанавливаете впервые?** Следуйте [руководству по установке Docker Compose](/l/ru/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`) серверные и рабочие контейнеры читают из одной базы данных. Изменения в панели администратора влияют на оба контейнера автоматически, исключая необходимость дублирования переменных среды между контейнерами (за исключением инфраструктурных переменных).
+</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/ru/developers/self-host/capabilities/key-rotation).
+
+## 2. Конфигурация только для среды
+
+```bash
+IS_CONFIG_VARIABLES_IN_DB_ENABLED=false
+```
+
+**Вся конфигурация управляется через файлы `.env`:**
+
+1. Установите `IS_CONFIG_VARIABLES_IN_DB_ENABLED=false` в своем `.env` файле
+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
+```
+
+Включите режим нескольких рабочих пространств для развертываний, похожих на SaaS, где нескольким независимым командам нужны собственные рабочие пространства на одном экземпляре Twenty.
+
+**Ключевые отличия от режима одного рабочего пространства:**
+
+* На одном экземпляре можно создать несколько рабочих пространств
+* Каждое рабочее пространство получает собственный поддомен (например, `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 Cloud
+
+1. Перейдите в [Google Cloud Console](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 Client ID
+3. Добавьте эти URI перенаправления:
+   * `https://{your-domain}/auth/google/redirect` (для SSO)
+   * `https://{your-domain}/auth/google-apis/get-access-token` (для интеграций)
+
+### Настройка в Twenty
+
+1. Перейдите в **Настройки → Панель администратора → Переменные конфигурации**
+2. Найдите раздел **Google Auth**.
+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 Auth**.
+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 здесь: [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` и настройте переменные `STORAGE_S3_*` через админ-панель или `.env`. См. [справочник config-variables.ts](https://github.com/twentyhq/twenty/blob/main/packages/twenty-server/src/engine/core-modules/twenty-config/config-variables.ts) для полного списка переменных S3.
+
+При использовании S3 с функциями, зависящими от CORS (например, загрузки файлов в браузере), убедитесь, что в конфигурации CORS вашего бакета разрешен origin фронтенда Twenty.
+
+## Логические функции и интерпретатор кода
+
+Twenty поддерживает логические функции для рабочих процессов и интерпретатор кода для анализа данных ИИ. Оба запускают предоставленный пользователем код и требуют явной настройки в целях безопасности.
+
+### Настройки безопасности по умолчанию
+
+**В продакшене (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` | Отключить выполнение кода ИИ                          | Н/Д                               |
+| Локальный | `CODE_INTERPRETER_TYPE=LOCAL`    | Только для разработки                                 | Низкий (без изоляции)             |
+| E2B       | `CODE_INTERPRETER_TYPE=E_2_B`    | Рабочая среда с изолированным исполнением в песочнице | Высокий (изолированная песочница) |
+
+<Note>
+При использовании `LOGIC_FUNCTION_TYPE=DISABLED` или `CODE_INTERPRETER_TYPE=DISABLED` любая попытка выполнения вернёт ошибку. Это полезно, если вы хотите запускать Twenty без этих возможностей.
+</Note>
+
+## API и фронтенд на отдельных хостах
+
+Актуально только в том случае, если вы не позволяете бэкенду обслуживать фронтенд. Для развертываний с одинаковым origin
+здесь ничего не требуется.
+
+Укажите каждый браузерный origin, который обращается к API, через запятую. `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`) на бэкенд для каждого имени хоста рабочего пространства, чтобы каждое рабочее пространство оставалось в рамках одного источника (same-origin) — именно так работает Twenty Cloud.

packages/twenty-docs/l/ru/developers/self-host/capabilities/troubleshooting.mdx

@@ -0,0 +1,255 @@
+---
+title: Устранение неполадок
+icon: wrench
+---
+
+## Устранение неполадок
+
+Если вы столкнулись с какой-либо проблемой при настройке окружения для разработки, обновлении вашего экземпляра или самостоятельном хостинге,
+вот некоторые решения общих проблем.
+
+### Самостоятельный хостинг
+
+#### Первая установка завершается с ошибкой `password authentication failed for user "postgres"`
+
+🚨 **ВАЖНО: Это решение ТОЛЬКО для новых установок** 🚨
+Если у вас уже есть экземпляр Twenty с производственными данными, **НЕ** следуйте этим шагам, так как они безвозвратно удалят вашу базу данных!
+
+Во время первой установки Twenty вы можете изменить пароль по умолчанию для базы данных.
+Пароль, который вы установили во время первой установки, навсегда сохраняется в объеме базы данных. Если вы позже попытаетесь изменить этот пароль в вашей конфигурации без удаления старого объема, возникнут ошибки аутентификации, так как база данных по-прежнему использует исходный пароль.
+
+⚠️ ПРЕДУПРЕЖДЕНИЕ: Следующие шаги ПОЛНОСТЬЮ УДАЛЯТ все данные базы данных! ⚠️
+Продолжайте, только если это новая установка без важной информации.
+
+Для обновления `PG_DATABASE_PASSWORD` необходимо:
+
+```sh
+# Update the PG_DATABASE_PASSWORD in .env
+docker compose down --volumes
+docker compose up -d
+```
+
+#### CR разрывы строк обнаружены [Windows]
+
+Это происходит из-за строчных символов Windows в сочетании с вашей Git конфигурацией. Попробуйте выполнить:
+
+```
+git config --global core.autocrlf false
+```
+
+Затем удалите репозиторий и клонируйте его заново.
+
+#### Отсутствует схема метаданных
+
+Во время установки Twenty, вам нужно настроить базу данных postgres с правильными схемами, расширениями и пользователями.
+Если вы успешно выполнили эту настройку, в вашей базе данных должны быть схемы `default` и `metadata`.
+Если нет, убедитесь, что на вашем компьютере запущено не более одного экземпляра PostgreSQL.
+
+#### Невозможно найти модуль 'twenty-emails' или его соответствующие определения типа.
+
+Перед запуском инициализации базы данных вы должны создать пакет `двадцать emails` (`npx nx run twenty-emails:build`).
+
+#### Отсутствует пакет twenty-x
+
+Убедитесь, что вы запустили yarn в корневой директории, а затем выполните команду `npx nx server:dev twenty-server`. Если это по-прежнему не работает, попробуйте собрать отсутствующий пакет вручную.
+
+#### Lint on Save не работает
+
+Это должно работать из коробки с установленным расширением Oxc (`oxc.oxc-vscode`). Если это не работает, попробуйте добавить это в настройки кода VS (область Dev контейнера dev):
+
+```
+"editor.codeActionsOnSave": {
+
+  "source.fixAll.oxc": "explicit"
+
+}
+```
+
+#### Во время выполнения `npx nx start` или `npx nx start twenty-front`, произошла ошибка памяти
+
+Запускайте только те сервисы, которые вам нужны, вместо `npx nx start`. Например, если вы работаете на сервере, запускайте только `npx nx worker twenty-server`
+
+**Если это не работает:**
+Если вы пытались запустить только `npx nx run twenty-server:start` в WSL и это завершается приведённой ниже ошибкой памяти:
+
+`FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory`
+
+Обсуждайтесь с командой ниже в терминале, или добавьте её в свой профиль `.bashrc`, чтобы он применялся автоматически:
+
+`export NODE_OPTIONS="--max-old-space-size=8192"`
+
+Флаг --max-old-space-size=8192 устанавливает верхний предел 8 ГБ для heap Node.js; использование этого значения зависит от потребностей приложения.
+Источник: https://stackoverflow.com/questions/56982005/where-do-i-set-node-options-max-old-space-size-2048
+
+**Если это не сработает:**
+Узнайте, какие процессы занимают большую часть оперативной памяти вашей машины. В Twenty, мы заметили, что некоторые расширения VS Code занимают много оперативной памяти, поэтому мы временно отключили их.
+
+**Если это не сработает:**
+Перезапуск вашей машины помогает очистить привязные процессы.
+
+#### При запуске `npx nx start` в логах появляются странные [0] и [1]
+
+Это ожидаемо, так как команда `npx nx start` запускает несколько команд под капотом
+
+#### Электронные письма не отправляются
+
+В большинстве случаев это происходит из-за того, что `воркер` не работает в фоновом режиме. Попробуйте запустить
+
+```
+npx nx worker twenty-server
+```
+
+#### Не удается подключить мой аккаунт Microsoft 365 к Twenty
+
+В большинстве случаев это происходит из-за того, что ваш администратор не включил лицензию Microsoft 365 для вашего аккаунта. Проверьте [https://admin.microsoft.com/](https://admin.microsoft.com/Adminportal/Home).
+
+Если вы получили код ошибки `AADSTS50020`, это, вероятно, означает, что вы используете личную учетную запись Microsoft. Это пока не поддерживается. Подробнее [здесь](https://learn.microsoft.com/fr-fr/troubleshoot/entra/entra-id/app-integration/error-code-aadsts50020-user-account-identity-provider-does-not-exist).
+
+#### При запуске `yarn`, предупреждения появятся в консоли
+
+Предупреждения информируют о добавлении дополнительных зависимостей, которые не указаны явно в `package.json`, поэтому, пока не появляются критичные ошибки, всё должно работать как ожидается.
+
+#### Когда пользователь обращается к странице входа в систему, в логах появляется ошибка о неавторизованном пользователе, пытающемся получить доступ к проекту
+
+Ожидается, что пользователь не авторизован при выходе из системы, так как их личность не была проверена.
+
+#### Как проверить, работает ли ваш воркер?
+
+* Перейдите на [webhook-test.com](https://webhook-test.com/) и скопируйте **Ваш уникальный URL вебхука**.
+
+<div style={{textAlign: 'center'}}>
+  <img src="/images/docs/developers/self-hosting/webhook-test.jpg" alt="Тест вебхука" />
+</div>
+
+* Откройте приложение Twenty, перейдите в `/settings` и включите переключатель **Advanced** внизу слева на экране.
+* Создайте новый вебхук.
+* Вставьте **Ваш уникальный URL вебхука** в поле **Endpoint Url** в Twenty. Установите **Фильтры** на `Компании` и `Создано`.
+
+<div style={{textAlign: 'center'}}>
+  <img src="/images/docs/developers/self-hosting/webhook-settings.jpg" alt="Настройки вебхука" />
+</div>
+
+* Перейдите в `/objects/companies` и создайте новую запись компании.
+* Вернитесь на [webhook-test.com](https://webhook-test.com/) и проверьте, был ли получен новый **POST запрос**.
+
+<div style={{textAlign: 'center'}}>
+  <img src="/images/docs/developers/self-hosting/webhook-test-result.jpg" alt="Результат теста вебхука" />
+</div>
+
+* Если **POST запрос** получен, ваш воркер успешно работает. В противном случае, вам нужно устранить неполадки вашего воркера.
+
+#### Front-end не удается запустить и возвращает ошибку TS5042: Опция 'project' не может быть смешанной с исходными файлами в командной строке
+
+Прокомментируйте плагин чекера в `packages/twenty-ui/vite-config.ts`, как показано в приведенном ниже примере:
+
+```
+plugins: [
+      react({ jsxImportSource: 'react' }),
+      tsconfigPaths(),
+      svgr(),
+      dts(dtsConfig),
+      // checker(checkersConfig),
+      wyw({
+        include: [
+          '**/OverflowingTextWithTooltip.tsx',
+          '**/Chip.tsx',
+          '**/Tag.tsx',
+          '**/Avatar.tsx',
+          '**/AvatarChip.tsx',
+        ],
+        babelOptions: {
+          presets: ['@babel/preset-typescript', '@babel/preset-react'],
+        },
+      }),
+    ],
+```
+
+#### Административная панель недоступна
+
+Запустите `UPDATE core."user" SET "canAccessFullAdminPanel" = ПОЛУЧИТЬ ЧЕЕ email = 'you@yourdomain.com';` в контейнере базы данных, чтобы получить доступ к панели администратора.
+
+#### При запуске рабочего процесса выполнение завершается ошибкой: "Выполнение логической функции отключено. Установите LOGIC_FUNCTION_TYPE в значение LOCAL или LAMBDA, чтобы их включить.
+
+В производственной среде логические функции по умолчанию отключены. Установите переменную окружения `LOGIC_FUNCTION_TYPE` в `LOCAL` или `LAMBDA`, чтобы их включить. Это можно настроить через переменные окружения или через переменные базы данных в панели администратора. См. [руководство по настройке логических функций](/l/ru/developers/self-host/capabilities/setup#logic-functions-available-drivers) для получения подробной информации.
+
+#### Когда я набираю сообщение в AI чате, оно не отвечает немедленно и я должен обновить страницу, чтобы увидеть ответ
+
+Это означает, что ваш обратный прокси отсутствует конфигурация ответов на потоковый API. Ниже приведен пример конфигурации Nginx:
+
+```
+location ~* ^/api/.*stream|\/graphql\/stream {
+proxy_pass http://twenty_backend;
+proxy_http_version 1.1;
+proxy_set_header Connection "";
+proxy_set_header Host $host;
+proxy_set_header X-Real-IP $remote_addr;
+proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+proxy_set_header X-Forwarded-Proto $scheme;
+proxy_buffering off;
+proxy_request_buffering off;
+proxy_cache off;
+gzip off;
+#chunked_transfer_encoding off;
+add_header X-Accel-Buffering no always;
+}
+```
+
+### Докер написать 1 клик
+
+#### Не удается войти в систему
+
+Если не удается войти в систему после настройки:
+
+1. Выполните следующие команды:
+   ```bash
+   docker exec -it twenty-server-1 yarn
+   docker exec -it twenty-server-1 npx nx database:reset  --configuration=no-seed
+   ```
+2. Перезапустите контейнеры Docker:
+   ```bash
+   docker compose down
+   docker compose up -d
+   ```
+
+Обратите внимание, что команда `database:reset` полностью очистит вашу базу данных и пересоздаст ее с нуля.
+
+#### Проблемы подключения за обратным прокси
+
+Если вы запускаете Twenty за обратным прокси и испытываете проблемы с подключением:
+
+1. **Проверьте SERVER_URL:**
+
+   Убедитесь, что `SERVER_URL` в вашем файле `.env` соответствует вашему внешнему URL-адресу, включая `https`, если SSL включён.
+
+2. **Проверьте настройки обратного прокси:**
+
+   * Убедитесь, что ваш обратный прокси правильно перенаправляет запросы на сервер Twenty.
+   * Убедитесь, что заголовки, как `X-Forwarded-For` и `X-Forwarded-Proto`, корректно установлены.
+
+3. **Перезапустите службы:**
+
+   После внесения изменений перезапустите как обратный прокси, так и контейнеры Twenty.
+
+#### Ошибка при загрузке изображения - доступ запрещён
+
+Проблема решается сменой владельца папки данных на хосте с root на другого пользователя и группу.
+
+#### Ошибка «Файл не найден» при тестировании функции Logic в рабочем процессе
+
+Выполните команду `yarn command:prod application:rebuild-default-deps` в контейнере twenty-server, чтобы устранить проблему с отсутствующими зависимостями.
+
+## Получение помощи
+
+Если вы столкнулись с проблемами, не охваченными в этом руководстве:
+
+* Проверьте логи:
+
+  Просмотрите логи контейнера на наличие сообщений об ошибках:
+
+  ```bash
+  docker compose logs
+  ```
+
+* Поддержка сообщества:
+
+  Обратитесь к [сообществу Twenty](https://github.com/twentyhq/twenty/issues) или [каналам поддержки](https://discord.gg/cx5n4Jzs57) за помощью.

packages/twenty-docs/l/ru/developers/self-host/capabilities/upgrade-guide.mdx

@@ -0,0 +1,106 @@
+---
+title: Руководство по обновлению
+icon: arrow-up-right-dots
+---
+
+## Общие рекомендации
+
+**Всегда создавайте резервную копию базы данных перед началом процесса обновления**, выполнив:
+
+```bash
+docker exec -it {db_container_name_or_id} pg_dumpall -U {postgres_user} > databases_backup.sql
+```
+
+Восстановление из резервной копии:
+
+```bash
+cat databases_backup.sql | docker exec -i {db_container_name_or_id} psql -U {postgres_user}
+```
+
+Если вы используете Docker Compose, выполните следующие шаги:
+
+1. Остановите Twenty: `docker compose down`
+2. Измените значение `TAG` в файле `.env` рядом с вашим `docker-compose.yml`
+3. Запустите Twenty: `docker compose up -d`
+
+Сервер автоматически выполняет все необходимые миграции обновления при запуске. Ручных команд не требуется.
+
+## Обновление до v2.34+ — требуется PostgreSQL 15
+
+Для Twenty v2.34 требуется PostgreSQL 15 или более поздней версии. В официальной конфигурации Docker Compose используется PostgreSQL 16. Если ваш экземпляр подключается к внешне управляемой базе данных, обновите её перед запуском сервера v2.34.
+
+## Межверсионные обновления (v1.23+)
+
+Начиная с **v1.23**, Twenty поддерживает межверсионные обновления. Вы можете перейти напрямую с любой поддерживаемой версии на последний релиз, не проходя каждую промежуточную версию.
+
+Например, полностью поддерживается обновление с v1.23 сразу до v2.0.
+
+## Переход на v2.5+ — конверт шифрования данных в состоянии покоя
+
+Начиная с **v2.5**, Twenty хранит секреты в состоянии покоя (токены OAuth, переменные приложения, закрытые ключи подписи, конфиденциальные значения конфигурации, TOTP‑секреты) внутри версионируемого конверта `enc:v2:`, зашифрованного с помощью `ENCRYPTION_KEY` (или `APP_SECRET`, если `ENCRYPTION_KEY` не задан).
+
+Первый запуск на v2.5 выполняет медленные команды обновления, которые **дополняют** существующие строки, помещая их в новый конверт. Они идемпотентны — при прерывании и перезапуске сервера выполнение продолжается с того места, где остановилось, — но на больших базах данных это может занять продолжительное время. Вы можете отслеживать прогресс с помощью `upgrade:status`.
+
+Вам следует задать отдельный `ENCRYPTION_KEY` **перед** обновлением до v2.5, чтобы процедура дополнения с самого начала записывала строки под этим ключом. Смена ключей после завершения дополнения требует [ротации](/l/ru/developers/self-host/capabilities/key-rotation).
+
+## Ротация секретов и ключей подписи
+
+Для повседневных операционных задач, таких как ротация `ENCRYPTION_KEY`, ротация ключа подписи JWT или отзыв скомпрометированного ключа подписи, см. специализированное руководство [Key rotation guide](/l/ru/developers/self-host/capabilities/key-rotation).
+
+## Проверка статуса обновления
+
+Команда `upgrade:status` позволяет просмотреть текущее состояние вашего экземпляра и миграций рабочих пространств. Это полезно для отладки проблем с обновлением или при обращении в поддержку.
+
+Запустите её из контейнера сервера:
+
+```bash
+docker exec -it {server_container_name_or_id} yarn command:prod upgrade:status
+```
+
+Пример результата:
+
+```sh
+APP_VERSION: v1.23.0
+
+Instance
+    Inferred version: 1.23.0
+    Latest command:   1.23.0_DropWorkspaceVersionColumnFastInstanceCommand_1785000000000
+    Status:           Up to date
+    Executed by:      v1.23.0
+    At:               2026-04-16T11:43:58.823Z
+
+Workspace
+  Apple (20202020-1c25-4d02-bf25-6aeccf7ea419)
+      Inferred version: 1.23.0
+      Latest command:   1.23.0_UpdateGlobalObjectContextCommandMenuItemsCommand_1780000005000
+      Status:           Up to date
+      Executed by:      v1.23.0
+      At:               2026-04-16T11:44:09.361Z
+
+Summary
+    Instance: Up to date
+    Workspaces: 1 up to date, 0 behind, 0 failed (1 total)
+```
+
+### Настройки
+
+| Флаг                      | Описание                                                                            |
+| ------------------------- | ----------------------------------------------------------------------------------- |
+| `-w, --workspace-id <id>` | Фильтрует по конкретному рабочему пространству. Можно передавать несколько раз.     |
+| `-f, --failed-only`       | Скрывает актуальные рабочие пространства, показывает только отстающие и с ошибками. |
+
+## Устранение неполадок
+
+Если обновление завершается ошибкой в некоторых рабочих пространствах, сервер не перейдёт дальше проблемного шага. Перезапуск сервера (`docker compose up -d`) повторит обновление с того места, где оно остановилось.
+
+Чтобы быстро выявить проблемы, выполните:
+
+```bash
+docker exec -it {server_container_name_or_id} yarn command:prod upgrade:status --failed-only
+```
+
+Будут показаны только рабочие пространства, которые отстают или завершились с ошибкой, вместе с сообщением об ошибке для каждого сбоя.
+
+## До v1.23
+
+Если ваш экземпляр старее v1.23, необходимо поэтапно обновляться через каждую основную помеченную версию (с v1.6 до v1.7, затем с v1.7 до v1.8 и так далее) до v1.23. После этого можно перейти сразу на последнюю версию.

packages/twenty-docs/l/ru/developers/self-host/self-host.mdx

@@ -0,0 +1,26 @@
+---
+title: Самостоятельный хостинг
+description: Развертывайте и управляйте Twenty в собственной инфраструктуре.
+---
+
+<Frame>
+  <img src="/images/user-guide/what-is-twenty/20.png" alt="ИИ" />
+</Frame>
+
+## Обзор
+
+Twenty можно развернуть в собственной инфраструктуре, что дает вам полный контроль над данными и процессом развертывания.
+
+## Почему самостоятельный хостинг?
+
+* **Владение данными**: Храните все данные CRM на собственных серверах
+* **Соответствие требованиям**: Соблюдайте регуляторные требования к локализации данных
+* **Настройка**: Полный доступ для изменения и расширения платформы
+
+## Начало работы
+
+<CardGroup cols={2}>
+  <Card title="Docker Compose" icon="docker" href="/l/ru/developers/self-host/capabilities/docker-compose">
+    Быстрая настройка с Docker
+  </Card>
+</CardGroup>