# Хранилище, резервные копии и ограничения

Все настройки Oleafly Server, хранение файлов на диске или в бакете S3, скомпилированные PDF, работа за обратным прокси, ограничения для учебных групп в одной сети и для каждой учётной записи, журналы, резервные копии, восстановление и обновления.

Эта страница посвящена повседневной работе с Oleafly Server. Чтобы установить его, начните с раздела [Запуск сервера совместной работы](/docs/collaboration/server/).

## Настройки

Сервер читает настройки из переменных окружения. Переменная, которая задана, но пуста, считается незаданной. Если настройка отсутствует или записана неверно, сервер не запускается, а его журнал сообщает, какая именно.

| Переменная | Что делает | По умолчанию |
| --- | --- | --- |
| `OLEAFLY_PUBLIC_URL` | HTTPS-адрес, который люди вводят в Oleafly. Он может включать путь, например `https://www.cs.example.edu/oleafly`. Обязательный. Файлы Compose и Coolify задают его за вас. | Нет |
| `OLEAFLY_BIND` | Адрес и порт, на которых сервер принимает подключения. | `0.0.0.0:8080` |
| `OLEAFLY_DATA_DIR` | Папка для базы данных и хранимых файлов. | `/data` |
| `OLEAFLY_SERVER_NAME` | Имя, которое люди видят в Oleafly, например `Smith Lab`. | `Oleafly Server` |
| `OLEAFLY_SERVER_ICON_URL` | HTTPS-адрес квадратного изображения, которое показывается рядом с именем. | Нет |
| `OLEAFLY_SETUP_CODE` | Ваш собственный одноразовый код настройки: минимум 12 букв или цифр, при желании с дефисами или пробелами. Без него сервер создаёт код сам. | Генерируется |
| `OLEAFLY_GITHUB_CLIENT_ID`, `OLEAFLY_GITHUB_CLIENT_SECRET` | Включает вход через GitHub. | Выключено |
| `OLEAFLY_GITHUB_URL` | Адрес GitHub Enterprise Server. | `https://github.com` |
| `OLEAFLY_GITHUB_API_URL` | Адрес API GitHub, если у вас необычный. | `https://api.github.com` или `/api/v3` внутри `OLEAFLY_GITHUB_URL` |
| `OLEAFLY_GITHUB_LABEL` | Текст на кнопке входа через GitHub. | `GitHub` |
| `OLEAFLY_OIDC_<NAME>_ISSUER`, `OLEAFLY_OIDC_<NAME>_CLIENT_ID`, `OLEAFLY_OIDC_<NAME>_CLIENT_SECRET` | Включает провайдер OpenID Connect с именем `<NAME>`. | Выключено |
| `OLEAFLY_OIDC_<NAME>_LABEL` | Текст на его кнопке входа, например `University login`. | `<NAME>` |
| `OLEAFLY_OIDC_<NAME>_TRUST_EMAIL` | Считает каждый адрес электронной почты от этого провайдера подтверждённым. Сначала прочитайте раздел [Подтверждённые адреса электронной почты](/docs/collaboration/server-access/#verified-email-addresses). | `false` |
| `OLEAFLY_SMTP_URL`, `OLEAFLY_MAIL_FROM` | Почта. Прочитайте раздел [Почта](/docs/collaboration/server-access/#email). | Выключено |
| `OLEAFLY_OPEN_SIGNUP` | Даёт каждому, кто входит через один из ваших провайдеров, учётную запись участника. Прочитайте раздел [Открытая регистрация](/docs/collaboration/server-access/#open-sign-up). | `false` |
| `OLEAFLY_WEB` | Включает доступ из браузера. Прочитайте раздел [Доступ из браузера](/docs/collaboration/server-access/#browser-access). | `false` |
| `OLEAFLY_BLOB_STORE` | Где хранятся файлы вроде изображений и PDF. Значение `fs` хранит их в `OLEAFLY_DATA_DIR`. Адрес вида `s3://lab-bucket` или `s3://lab-bucket/oleafly` хранит их в бакете. | `fs` |
| `OLEAFLY_S3_ENDPOINT` | Адрес S3-совместимого хранилища, отличного от Amazon S3, например MinIO или Cloudflare R2. Для Amazon S3 оставьте пустым. | Amazon S3 |
| `OLEAFLY_S3_REGION` | Регион бакета. | `us-east-1` |
| `OLEAFLY_S3_ACCESS_KEY_ID`, `OLEAFLY_S3_SECRET_ACCESS_KEY` | Ключ, который сервер использует для бакета. Обязателен с адресом `s3://`. | Нет |
| `OLEAFLY_MAX_PROJECT_MB` | Самый большой проект, который сервер принимает, в мегабайтах. | `200` |
| `OLEAFLY_MAX_FILE_MB` | Самый большой одиночный файл, в мегабайтах. | `50` |
| `OLEAFLY_MAX_MEMBERS_PER_PROJECT` | Максимум людей в одном проекте. | `20` |
| `OLEAFLY_ACCOUNT_STORAGE_MB` | Сколько максимум могут хранить проекты, которыми владеет одна учётная запись, в мегабайтах. Прочитайте раздел [Ограничения на учётную запись](#limits-per-account). | Без ограничения или `100` при открытой регистрации |
| `OLEAFLY_MAX_PROJECTS_PER_ACCOUNT` | Максимум общих проектов, которыми может владеть одна учётная запись. | Без ограничения или `50` при открытой регистрации |
| `OLEAFLY_UPLOADS_PER_HOUR` | Сколько выгрузок файлов и снимков одна учётная запись может выполнить за час. | Без ограничения или `300` при открытой регистрации |
| `OLEAFLY_SIGN_IN_BURST` | Сколько запросов входа один сетевой адрес может сделать во время всплеска. Вход занимает примерно шесть, поэтому значение по умолчанию рассчитано на 50 человек с одного адреса, входящих одновременно. | `300` |
| `OLEAFLY_SIGN_IN_PER_MINUTE` | Сколько запросов входа один сетевой адрес получает обратно каждую минуту после всплеска. | `120` |
| `OLEAFLY_EMAIL_LINKS_PER_IP` | Сколько писем для входа сервер отправляет людям с одного сетевого адреса за 15 минут. | `100` |
| `OLEAFLY_EMAIL_LINKS_PER_ADDRESS` | Сколько писем для входа может получить один адрес электронной почты за 15 минут. Не может быть больше `OLEAFLY_EMAIL_LINKS_PER_IP`. | `3` |
| `OLEAFLY_DEVICE_CODES_PER_IP` | Сколько кодов входа могут запросить люди с одного сетевого адреса за 10 минут. | `100` |
| `OLEAFLY_SNAPSHOT_MEMORY_MB` | Сколько памяти, в мегабайтах, сервер может использовать для сборки снимков проектов. | Половина лимита памяти контейнера или `1024` без лимита |
| `OLEAFLY_BEHIND_PROXY` | Берёт адрес каждого человека из заголовка `X-Forwarded-For`, который добавляет ваш прокси. Файлы Compose, Coolify и Render включают его. | `false` |
| `OLEAFLY_PROXY_HOPS` | Через сколько прокси проходит каждый запрос, прежде чем достигнет сервера. Требует `OLEAFLY_BEHIND_PROXY=true`. | `1` |
| `OLEAFLY_LOG_LEVEL` | Насколько подробный журнал ведёт сервер: `error`, `warn`, `info`, `debug` или `trace`. Библиотеки, которыми пользуется сервер, пишут в журнал только предупреждения, если не выбрать `debug` или `trace`. | `info` |
| `OLEAFLY_SECURITY_LOG_DAYS` | Сколько дней хранить записи журнала безопасности, записи журналов доступа к проектам, а также отвеченные или истёкшие приглашения гостей. | `365` |
| `OLEAFLY_ARCHIVE_DAYS` | Сколько дней хранить проект после того, как его владелец перестал им делиться. | `30` |
| `OLEAFLY_POLL_HOLD_SECONDS` | Как долго сервер держит открытым запрос долгого опроса, когда правки не ожидаются, от 1 до 40 секунд. Держите значение на несколько секунд ниже тайм-аута простоя любого прокси перед сервером. | `25` |

В файле `.env` для Compose заключайте значение в одинарные кавычки, если оно содержит `$` или `#`. Настройки с секретами можно также читать из файлов. Прочитайте раздел [Как держать секреты вне .env](/docs/collaboration/server/#keep-secrets-out-of-env).

## Хранилище

По умолчанию сервер хранит всё в `OLEAFLY_DATA_DIR`: базу данных, файлы, которыми люди делятся, и снимки проектов. Снимки — это сохранённые копии каждого проекта, позволяющие людям быстро присоединяться и навёрстывать пропущенное.

### Файлы в бакете

Сервер может вместо этого хранить файлы и снимки в Amazon S3 или в другом хранилище с S3-совместимым API, например MinIO или Cloudflare R2. База данных в любом случае остаётся в `OLEAFLY_DATA_DIR`, поэтому папка данных серверу всё равно нужна.

1. Создайте бакет и закройте к нему публичный доступ.
2. Создайте ключ, который может читать, записывать и удалять объекты в этом бакете и ничего больше. На Amazon S3 это `s3:GetObject`, `s3:PutObject` и `s3:DeleteObject` для `arn:aws:s3:::lab-bucket/*` или для `arn:aws:s3:::lab-bucket/oleafly/*`, если вы используете папку.
3. Задайте переменные, например в `.env`:

   ```sh
   OLEAFLY_BLOB_STORE=s3://lab-bucket/oleafly
   OLEAFLY_S3_REGION=eu-west-1
   OLEAFLY_S3_ACCESS_KEY_ID=your-access-key-id
   OLEAFLY_S3_SECRET_ACCESS_KEY=your-secret-access-key
   ```

Для хранилища, отличного от Amazon S3, также задайте в `OLEAFLY_S3_ENDPOINT` его адрес, например `https://minio.example.org:9000` или `https://<account-id>.r2.cloudflarestorage.com`, а в `OLEAFLY_S3_REGION` — регион, которого оно ожидает (`auto` для R2). Обычный `http://` тоже работает, но используйте его, только если хранилище находится в той же частной сети, что и сервер.

Часть после имени бакета — необязательная папка. Каждый файл назван по своему хешу SHA-256 и лежит в папке из первых двух символов этого хеша, поэтому файл с хешем, начинающимся на `3f9a`, хранится как `oleafly/3f/3f9a...`. У снимков есть собственная папка `snapshots` с папкой для каждого проекта. Когда сервер читает файл или снимок обратно, он сверяет байты с хешем и отклоняет несовпадающий. Без бакета та же структура лежит в папке `blobs` внутри `OLEAFLY_DATA_DIR`.

Если бакет отклоняет запрос, эта загрузка или выгрузка завершается неудачей, а журнал сервера показывает, что ответил бакет, например `403 Forbidden (AccessDenied)`. Ошибка сервера, тайм-аут или обрыв соединения — другое дело: сервер пробует до трёх раз с короткой случайной паузой между попытками. Если удалить объект не удаётся, сервер замечает это и пробует снова при каждом проходе обслуживания, каждые 6 часов, чтобы сбой не оставлял после себя объекты.

### Снимки и память

Когда проектом делятся, приложение владельца загружает его первый снимок и подписывает его ключом этого устройства. С этого момента сервер собирает каждый снимок сам — из предыдущего снимка и изменений, присланных людьми с тех пор. Новый снимок собирается, когда с прошлого накопится 1000 изменений проекта. Сервер всегда хранит как минимум последние 2000 изменений, поэтому устройство, отсутствовавшее недолго, навёрстывает упущенное по ним и не скачивает весь проект заново.

Для сборки снимка нужно примерно в десять раз больше, чем весит предыдущий снимок плюс изменения после него. Сервер запускает только сборку, помещающуюся в `OLEAFLY_SNAPSHOT_MEMORY_MB`, а сборки, идущие одновременно, делят этот объём между собой. Если сборка не помещается, сервер пропускает её, записывает в журнал, сколько памяти ей нужно, и хранит все изменения проекта. Устройства навёрстывают упущенное по этим изменениям по несколько мегабайт за раз. Поднимите настройку — и следующий снимок соберётся. Сервер не сохранит снимок крупнее `OLEAFLY_MAX_PROJECT_MB`.

### Скомпилированные PDF

Когда владелец или редактор успешно компилирует общий проект, его приложение отправляет PDF на сервер вместе с файлом SyncTeX, если он есть. Для каждого проекта оно отправляет не больше одного PDF в минуту. Сервер хранит для каждого проекта один PDF и один файл SyncTeX, с именем главного файла, а также сведениями о том, кто и когда его скомпилировал. [Доступ из браузера](/docs/collaboration/server-access/#browser-access) показывает этот PDF участникам проекта.

Каждая выгрузка заменяет предыдущую, а старый файл удаляется, как только он больше нигде не используется. Скомпилированные файлы хранятся вместе с остальными файлами, на диске или в бакете, и удаляются вместе со своим проектом. Скомпилированный файл может быть размером до `OLEAFLY_MAX_FILE_MB`. Он учитывается в [хранилище учётной записи](#limits-per-account) владельца, но не в числе выгрузок в час.

Читать скомпилированные файлы проекта может каждый его участник. Заменять их могут только владельцы и редакторы.

## За обратным прокси

Сервер говорит по обычному HTTP, поэтому HTTPS обрабатывает что-то перед ним: Caddy в настройке Compose, прокси Coolify или уже работающий у вас веб-сервер, например университетский. Что бы ни стояло впереди, оно должно:

- принимать запросы размером до `OLEAFLY_MAX_PROJECT_MB`
- добавлять адрес клиента в `X-Forwarded-For`

Оно также должно передавать запросы на повышение до WebSocket на `/ws` и держать такие соединения открытыми минимум час. Редактирование в реальном времени использует их, когда может. При включённом доступе из браузера оно должно передавать их и на `/web/ws`, потому что у браузерного приложения нет более медленного запасного пути.

Запустите сервер там, где до него может добраться только прокси. На той же машине задайте `OLEAFLY_BIND=127.0.0.1:8080`. Затем задайте `OLEAFLY_BEHIND_PROXY=true`.

### Когда соединения WebSocket заблокированы

Некоторые сети блокируют соединения WebSocket — часто это университетская или корпоративная сеть с фильтрующим прокси. Редактирование в реальном времени там всё равно работает, только медленнее. Когда две попытки WebSocket подряд заканчиваются неудачей, а сервер по-прежнему отвечает по HTTPS, Oleafly переходит на долгий опрос по HTTP. Он отправляет правки на `/api/v1/projects/<project>/frames` и ждёт правки других людей на `/api/v1/projects/<project>/poll`, держа каждый запрос открытым не дольше `OLEAFLY_POLL_HOLD_SECONDS` секунд. Каждая правка всё равно доходит. Oleafly повторяет попытку WebSocket каждую минуту и возвращается к нему, как только одна соединяется.

**Проверить подключение** в Oleafly и **Проверка подключения** в консоли администратора сообщают, когда это происходит: «Правки в реальном времени идут более медленным путём, потому что эта сеть блокирует обычный. Они всё равно доходят.»

Если вы управляете прокси перед сервером, всё равно передавайте запросы на повышение до WebSocket. Долгий опрос работает, но каждая партия правок стоит лишнего запроса и небольшого дополнительного ожидания.

Некоторые прокси закрывают запрос, который молчит меньше 30 секунд, — например, nginx с коротким `proxy_read_timeout`. Они отвечают на запросы долгого опроса ошибкой 502 или 504, и правки приходят с опозданием. Задайте `OLEAFLY_POLL_HOLD_SECONDS` на несколько секунд меньше этого тайм-аута, например `8` при тайм-ауте в 10 секунд.

### Что меняет OLEAFLY_BEHIND_PROXY

Сервер фиксирует адрес клиента в двух местах: в журнале безопасности и в [ограничениях](#limits-for-a-class-on-one-network) на то, как часто один адрес может начинать вход или открывать соединение реального времени.

Без этой настройки сервер использует адрес того, кто к нему подключился. За прокси это всегда сам прокси, поэтому все делят один лимит, а журнал безопасности показывает только адрес прокси.

С `OLEAFLY_BEHIND_PROXY=true` сервер читает заголовок `X-Forwarded-For` и использует последний адрес в нём — тот, который добавил ваш прокси. Если заголовок отсутствует или не содержит допустимого адреса, сервер возвращается к адресу подключения. Больше ничего не меняется. Сервер игнорирует `X-Forwarded-Proto`, `X-Forwarded-Host` и `Forwarded` и строит каждый выдаваемый адрес из `OLEAFLY_PUBLIC_URL`.

Включайте её, только когда каждый запрос приходит через ваш прокси. Если люди могут добраться до сервера и напрямую, кто угодно сможет прислать выдуманный `X-Forwarded-For`, подставить любой адрес в журнал безопасности и обойти лимит входа.

При двух прокси подряд, например Cloudflare перед прокси Coolify, задайте `OLEAFLY_PROXY_HOPS=2`. Тогда сервер берёт второй адрес с конца. Считайте только прокси, через которые проходит каждый запрос. Cloudflare Tunnel, ведущий прямо к серверу, считается за один.

Чтобы проверить это число, войдите со своего компьютера и откройте **Журнал безопасности** в консоли администратора. Новейшая запись должна показывать ваш публичный адрес — тот, о котором сообщает сайт вроде `ifconfig.me`. Если вместо этого показывается частный адрес или адрес Cloudflare, поднимите `OLEAFLY_PROXY_HOPS` на единицу.

### Caddy

Caddy пропускает соединения WebSocket и `X-Forwarded-For` без дополнительных настроек и сам получает сертификат. Полный `Caddyfile` есть в разделе [Поставьте HTTPS впереди](/docs/collaboration/server/#put-https-in-front).

### nginx

Сначала получите сертификат для домена, например с помощью certbot. Затем сохраните это как `/etc/nginx/conf.d/oleafly.conf` и выполните `sudo nginx -t && sudo systemctl reload nginx`:

```nginx
map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

server {
    listen 443 ssl;
    server_name collab.example.org;
    ssl_certificate /etc/letsencrypt/live/collab.example.org/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/collab.example.org/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_read_timeout 1h;
        proxy_send_timeout 1h;
        client_max_body_size 200m;
    }
}
```

`client_max_body_size` соответствует значению `OLEAFLY_MAX_PROJECT_MB` по умолчанию — 200. Если поднимаете одно, поднимите и другое.

### Apache

Вам нужен Apache 2.4.47 или новее; он есть в Debian 12, Ubuntu 22.04 и более поздних. Включите модули:

```sh
sudo a2enmod proxy proxy_http ssl
```

Сохраните это как `/etc/apache2/sites-available/oleafly.conf`, затем выполните `sudo a2ensite oleafly && sudo systemctl reload apache2`:

```apache
<VirtualHost *:443>
    ServerName collab.example.org
    SSLEngine on
    SSLCertificateFile /etc/letsencrypt/live/collab.example.org/fullchain.pem
    SSLCertificateKeyFile /etc/letsencrypt/live/collab.example.org/privkey.pem

    ProxyPreserveHost On
    ProxyPass / http://127.0.0.1:8080/ upgrade=websocket timeout=3600
    ProxyPassReverse / http://127.0.0.1:8080/
</VirtualHost>
```

`upgrade=websocket` пропускает соединения WebSocket, а `timeout=3600` держит их открытыми час. Apache сам добавляет адрес клиента в `X-Forwarded-For`.

### По вложенному пути

Если сервер живёт по вложенному пути, включите этот путь в `OLEAFLY_PUBLIC_URL`, например `https://www.cs.example.edu/oleafly`, и в адреса обратного вызова, которые вы регистрируете у провайдеров входа. Сервер отвечает и с этим путём, и без него, поэтому ваш прокси может передавать путь или убирать его. В nginx используйте `location /oleafly/ {` с теми же строками внутри и оставьте `proxy_pass http://127.0.0.1:8080;` без пути, чтобы nginx передавал путь дальше.

## Ограничения для учебной группы в одной сети

Целая учебная группа часто входит с одного сетевого адреса, например через NAT университета. Значения по умолчанию рассчитаны на это:

- **Входы**: один адрес получает всплеск из 300 запросов входа, затем по два в секунду. Вход занимает примерно шесть, поэтому 50 человек могут войти одновременно. Измените их с помощью `OLEAFLY_SIGN_IN_BURST` и `OLEAFLY_SIGN_IN_PER_MINUTE`.
- **Письма со ссылками**: 100 на один адрес за 15 минут и 3 на один адрес электронной почты. Измените их с помощью `OLEAFLY_EMAIL_LINKS_PER_IP` и `OLEAFLY_EMAIL_LINKS_PER_ADDRESS`.
- **Коды входа**: 100 кодов и 10 неверных кодов с одного адреса за 10 минут. Измените это с помощью `OLEAFLY_DEVICE_CODES_PER_IP`.
- **Соединения реального времени** имеют собственный, больший лимит, чтобы целая группа за одним адресом могла переподключиться сразу после перезапуска. Его тратят только соединения, которым не удалось доказать свою сессию: всплеск из 300, затем по десять в секунду. Соединение, доказавшее свою сессию, расходует лимит собственного устройства, которое может переподключиться 60 раз во всплеске, затем раз в секунду.

Все IPv6-адреса в одной сети `/64` считаются одним адресом. Эти ограничения действительно различают людей, только когда сервер видит реальный адрес каждого, поэтому [настройте прокси](#what-oleafly_behind_proxy-changes) правильно.

Сервер пингует каждое соединение реального времени каждые 30 секунд. Он закрывает соединение, которое 90 секунд не отвечает на эти пинги, и то, которое перестаёт читать отправляемое сервером.

Ограничения проектов действуют для всех: `OLEAFLY_MAX_PROJECT_MB` на весь проект (по умолчанию 200 МБ), `OLEAFLY_MAX_FILE_MB` на один файл (50 МБ) и `OLEAFLY_MAX_MEMBERS_PER_PROJECT` на людей в одном проекте (20). Текущие ограничения показывает **Обзор** в консоли администратора.

## Ограничения на учётную запись

Для каждой учётной записи действуют три ограничения. Они выключены, пока вы их не зададите. Исключение составляет [открытая регистрация](/docs/collaboration/server-access/#open-sign-up): она включает их со следующими значениями по умолчанию.

| Ограничение | Настройка | При открытой регистрации |
| --- | --- | --- |
| Хранилище для проектов, которыми владеет учётная запись | `OLEAFLY_ACCOUNT_STORAGE_MB` | 100 МБ |
| Общие проекты, которыми владеет учётная запись | `OLEAFLY_MAX_PROJECTS_PER_ACCOUNT` | 50 |
| Выгрузки учётной записи за час | `OLEAFLY_UPLOADS_PER_HOUR` | 300 |

Заданное вами значение всегда важнее значения по умолчанию. Каждое должно быть целым числом не меньше 1.

- **Хранилище** складывает файлы и историю изменений каждого проекта, которым владеет учётная запись, включая архивированные, а также их скомпилированные PDF. Снимки не учитываются. Файл, который кто-либо добавляет в проект, засчитывается владельцу проекта. Когда хранилище владельца заполнено, сервер отклоняет новые файлы и скомпилированные PDF для его проектов, и владелец не может поделиться ещё одним проектом. Файл остаётся на компьютере того, кто его добавил. Текст, который люди печатают, по-прежнему синхронизируется.
- **Общие проекты** считает проекты, которыми делится учётная запись, включая те, что ещё выгружаются. Архивированные проекты не учитываются, поэтому, если прекратить делиться проектом, место освободится.
- **Выгрузки** считает каждую выгрузку файла и снимка за последний час. Скомпилированные PDF не учитываются. Отклонённый файл Oleafly позже отправит снова сам.

**Обзор** в консоли администратора не показывает эти ограничения. При включённой открытой регистрации журнал сервера называет их при каждом запуске.

## Журналы

- **Журнал сервера** — это то, что показывают `docker compose logs oleafly-server`, **Logs** в Coolify или `journalctl -u oleafly-server`. `OLEAFLY_LOG_LEVEL` задаёт, сколько в него пишется.
- **Журнал безопасности** записывает входы и отклонённые входы, устройства, людей, роли, настройки, проекты и гостей — каждое событие с временем и IP-адресом. Администраторы и сопровождающие читают его в разделе **Журнал безопасности** консоли администратора. Записи старше `OLEAFLY_SECURITY_LOG_DAYS` дней удаляются.
- **Журналы доступа к проектам** записывают, кто открывал проект, присоединялся к нему или скачивал копию, с именем устройства и временем. Владелец проекта включает журнал, когда включено **Разрешить журналы доступа к проектам**, и читать его может только этот владелец. Срок хранения тот же.

## Резервные копии

Что нужно для полной резервной копии, зависит от того, где хранятся файлы:

- **Файлы на диске** (`OLEAFLY_BLOB_STORE=fs`, по умолчанию): база данных, файлы и снимки лежат в папке данных. Делайте резервную копию всей папки.
- **Файлы в бакете**: папка данных хранит базу данных, а бакет — файлы и снимки. Копия базы данных вместе с бакетом и есть полная резервная копия. Включите в бакете версионирование, чтобы ошибочно удалённый объект можно было вернуть.

Делайте резервные копии регулярно и держите их в закрытом доступе, поскольку они содержат каждый проект. Ваши настройки, например `.env`, в папку данных не входят, поэтому храните и их копию.

С Docker сервер останавливается на несколько секунд, пока вы копируете том. Oleafly переподключается сам. Выполните эти команды в папке сервера — `/opt/oleafly-server`, если вы использовали установщик.

```sh
cd /opt/oleafly-server
sudo docker compose stop oleafly-server
sudo docker run --rm -v oleafly-server_oleafly-data:/data:ro -v "$PWD":/backup debian:13.7-slim tar -C /data -czf /backup/oleafly-data-$(date +%F).tar.gz .
sudo docker compose start oleafly-server
```

С systemd:

```sh
sudo systemctl stop oleafly-server
sudo tar -C /var/lib/private/oleafly-server -czf /root/oleafly-data-$(date +%F).tar.gz .
sudo systemctl start oleafly-server
```

Скопируйте архив на другую машину.

В Coolify имя тома начинается с идентификатора ресурса. Найдите его с помощью `docker volume ls --filter name=oleafly-data`, подставьте вместо `oleafly-server_oleafly-data`, а сервер останавливайте и запускайте из панели Coolify, а не командой `docker compose`.

### Тренировочное восстановление

Резервная копия, которую вы ни разу не восстанавливали, — это только надежда. Эта тренировка запускает вторую копию сервера из резервной копии, не трогает работающую и проверяет, что обе — один и тот же сервер. Подставьте дату собственного архива вместо `2026-10-11`.

```sh
cd /opt/oleafly-server
sudo docker volume create oleafly-restore-drill
sudo docker run --rm -v oleafly-restore-drill:/data -v "$PWD":/backup:ro debian:13.7-slim tar -C /data -xzf /backup/oleafly-data-2026-10-11.tar.gz
sudo docker run -d --name oleafly-restore-drill -v oleafly-restore-drill:/data -e OLEAFLY_PUBLIC_URL=https://restore-drill.invalid -e OLEAFLY_GITHUB_CLIENT_ID=restore-drill -e OLEAFLY_GITHUB_CLIENT_SECRET=restore-drill "$(sudo docker compose images -q oleafly-server)"
sudo docker run --rm --network container:oleafly-restore-drill curlimages/curl:8.22.0 -fsS --retry 10 --retry-connrefused --retry-delay 1 http://127.0.0.1:8080/.well-known/oleafly-server
curl -fsS https://collab.example.org/.well-known/oleafly-server
```

`server_id` в двух ответах должен совпадать. У тренировочной копии вход через GitHub — заглушка, которая никого не впустит, и нет открытых портов, поэтому пользоваться ею никто не может. Удалите её, когда закончите:

```sh
sudo docker rm -f oleafly-restore-drill
sudo docker volume rm oleafly-restore-drill
```

### Восстановление

Чтобы выполнить настоящее восстановление с Docker Compose, остановите сервер, замените содержимое тома архивом и запустите его снова:

```sh
cd /opt/oleafly-server
sudo docker compose stop oleafly-server
sudo docker run --rm -v oleafly-server_oleafly-data:/data -v "$PWD":/backup:ro debian:13.7-slim sh -c 'find /data -mindepth 1 -delete && tar -C /data -xzf /backup/oleafly-data-2026-10-11.tar.gz'
sudo docker compose start oleafly-server
```

С systemd:

```sh
sudo systemctl stop oleafly-server
sudo find /var/lib/private/oleafly-server -mindepth 1 -delete
sudo tar -C /var/lib/private/oleafly-server -xzf /root/oleafly-data-2026-10-11.tar.gz
sudo systemctl start oleafly-server
```

На восстановленном сервере не хватает изменений, сделанных людьми после резервной копии. Каждое приложение замечает это при переподключении — оставалось ли оно открытым или было открыто позже — и снова отправляет свои недостающие изменения. Для этого никому ничего делать не нужно. Изменение, которое строится на чужом недостающем изменении, ждёт, пока тот человек откроет проект, потому что только его приложение может отправить его изменения. Попросите всех, кто редактировал примерно во время сбоя, один раз открыть проект.

### Непрерывные копии с Litestream

Архив хранит только то, что было на момент его создания. [Litestream](https://litestream.io) копирует каждое изменение в базе данных сервера в S3-совместимый бакет примерно через секунду после того, как оно произошло. Файл Compose включает его как необязательный сервис.

Litestream копирует только базу данных. Если файлы в бакете, бакет уже хранит файлы и снимки, поэтому копия Litestream вместе с бакетом может вернуть потерянный диск. Если файлы на диске, продолжайте делать архивы тома, потому что Litestream не копирует папку `blobs`.

1. Создайте бакет или папку в нём, которую использует только Litestream этого сервера. Не делите её с `OLEAFLY_BLOB_STORE`. Дайте Litestream ключ, который может просматривать содержимое бакета и читать, записывать и удалять объекты в нём.
2. Добавьте данные в `.env`:

   ```sh
   LITESTREAM_REPLICA_URL=s3://lab-backups/oleafly-server
   LITESTREAM_REGION=eu-west-1
   LITESTREAM_ACCESS_KEY_ID=your-access-key-id
   LITESTREAM_SECRET_ACCESS_KEY=your-secret-access-key
   COMPOSE_PROFILES=litestream
   ```

   Для хранилища, отличного от Amazon S3, также задайте в `LITESTREAM_ENDPOINT` его адрес, а в `LITESTREAM_REGION` — регион, которого оно ожидает (`auto` для R2). `COMPOSE_PROFILES` заставляет каждую команду `docker compose` включать Litestream.
3. Запустите его:

   ```sh
   sudo docker compose up -d
   ```

4. Проверьте, что база данных скопирована. Эта команда выводит строку с `snapshot complete`:

   ```sh
   sudo docker compose logs litestream | grep 'snapshot complete'
   ```

Litestream делает полную копию раз в день и хранит неделю копий и изменения между ними. Расписание задано в `litestream.yml`.

#### Тренировочное восстановление Litestream

Эта тренировка восстанавливает базу данных из бакета во временный том, запускает на нём вторую копию сервера и проверяет, что обе — один и тот же сервер. Работающий сервер не затрагивается.

```sh
cd /opt/oleafly-server
sudo docker run --rm -v oleafly-litestream-drill:/data "$(sudo docker compose images -q oleafly-server)" --version
sudo docker compose run --rm --no-deps -v oleafly-litestream-drill:/restore litestream restore -config /etc/litestream.yml -o /restore/oleafly-server.sqlite3 /data/oleafly-server.sqlite3
sudo docker run -d --name oleafly-litestream-drill -v oleafly-litestream-drill:/data -e OLEAFLY_PUBLIC_URL=https://restore-drill.invalid -e OLEAFLY_GITHUB_CLIENT_ID=restore-drill -e OLEAFLY_GITHUB_CLIENT_SECRET=restore-drill "$(sudo docker compose images -q oleafly-server)"
sudo docker run --rm --network container:oleafly-litestream-drill curlimages/curl:8.22.0 -fsS --retry 10 --retry-connrefused --retry-delay 1 http://127.0.0.1:8080/.well-known/oleafly-server
curl -fsS https://collab.example.org/.well-known/oleafly-server
```

Первая команда создаёт временный том с владельцем, который нужен серверу. `server_id` в двух последних ответах должен совпадать. Удалите копию, когда закончите:

```sh
sudo docker rm -f oleafly-litestream-drill
sudo docker volume rm oleafly-litestream-drill
```

#### Восстановление базы данных из Litestream

Когда файл базы данных повреждён или исчез, а остальная папка данных в порядке, остановите сервер и Litestream, удалите остатки базы данных, восстановите её и запустите снова:

```sh
cd /opt/oleafly-server
sudo docker compose stop oleafly-server litestream
sudo docker run --rm -v oleafly-server_oleafly-data:/data debian:13.7-slim rm -rf /data/oleafly-server.sqlite3 /data/oleafly-server.sqlite3-wal /data/oleafly-server.sqlite3-shm /data/.oleafly-server.sqlite3-litestream
sudo docker compose run --rm --no-deps litestream restore -config /etc/litestream.yml /data/oleafly-server.sqlite3
sudo docker compose up -d
```

После потери диска, когда файлы были в бакете, выполните команды выше на новом пустом томе и сохраните те же настройки бакета в `.env`. Каждый проект вернётся со своими файлами и снимками.

После потери диска, когда файлы были на диске, [восстановите](#restore) новейший архив и на этом остановитесь. Не накладывайте более новую базу данных из Litestream на более старый архив. База данных указывала бы на файлы и снимки, которых нет в архиве, и такие проекты не открывались бы.

## Обновление

Сначала сделайте резервную копию. Сервер обновляет свою базу данных при первом запуске нового релиза, поэтому возврат к более старому релизу означает восстановление копии, сделанной перед обновлением.

- **Установка одной командой**: выполните `curl -fsSL https://oleafly.com/server/install.sh | sudo sh -s -- update`. Она сохраняет `.env`, получает файлы и образ нового релиза и перезапускает сервер.
- **Docker Compose вручную**: скачайте файлы нового релиза в папку сервера, как в разделе [Docker Compose вручную](/docs/collaboration/server/#docker-compose-by-hand), затем выполните `sudo docker compose up -d`.
- **Coolify**: выберите **Redeploy**. С опубликованным образом это подтягивает новейший релиз под тегом образа.
- **Render**: откройте сервис и запустите развёртывание вручную — оно снова скачает образ.
- **Railway**: разверните сервис снова из его меню. Railway также может сам обновлять образ из реестра GitHub.
- **systemd**: установите новый релиз, как описано в разделе [Скачайте сервер](/docs/collaboration/server/#download-the-server), затем выполните `sudo systemctl restart oleafly-server`.

Oleafly проверяет версию сервера при каждом подключении. Если приложение и сервер не могут работать вместе, Oleafly сообщает, какое из них нужно обновить.
