# Сховище, резервні копії та обмеження

Усі налаштування 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` |

У Compose-файлі `.env` беріть значення в одинарні лапки, якщо воно містить `$` або `#`. Налаштування з таємницями можна також читати з файлів. Прочитайте [Таємниці поза .env](/docs/collaboration/server/#keep-secrets-out-of-env).

## Сховище

Типово сервер зберігає все в `OLEAFLY_DATA_DIR`: базу даних, файли, якими люди діляться, і знімки проєктів. Знімки — це збережені копії кожного проєкту, завдяки яким люди приєднуються і швидко дотягуються до актуального стану.

### Файли в бакеті

Натомість сервер може зберігати файли й знімки в Amazon S3 або в іншому сховищі з API, сумісним із S3, як-от 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 годин, тож збій не лишає по собі об'єктів.

### Знімки й пам'ять

Коли проєкт отримує спільний доступ, застосунок власника вивантажує його перший знімок і підписує його ключем цього пристрою. Відтоді сервер будує кожен знімок сам — з попереднього знімка та змін, які люди надіслали відтоді. Новий знімок будується, щойно в проєкту накопичиться 1,000 змін після останнього. Сервер завжди зберігає щонайменше останні 2,000 змін, тож пристрій, який ненадовго зник, дотягується з них і не звантажує весь проєкт знову.

Побудова знімка потребує приблизно вдесятеро більше за розмір попереднього знімка плюс зміни відтоді. Сервер розпочинає лише ту побудову, що вміщується в `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 назва тому починається з ID ресурсу. Знайдіть її командою `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 каже, якому з них потрібне оновлення.
