Перейти до вмісту
Oleaflyv0.4.12

Запуск сервера

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

Усі налаштування Oleafly Server, зберігання файлів на диску або в бакеті S3, скомпільовані PDF, робота за проксі, обмеження для класів в одній мережі та для кожного облікового запису, журнали, резервні копії, відновлення та оновлення.

Ця сторінка описує щоденну роботу з Oleafly Server. Щоб його встановити, почніть зі сторінки Запуск сервера співпраці.

Сервер читає свої налаштування зі змінних середовища. Змінна, що задана, але порожня, вважається незаданою. Якщо налаштування бракує або воно неправильне, сервер не запускається, а його журнал називає його.

ЗміннаЩо робитьТипове значення
OLEAFLY_PUBLIC_URLHTTPS-адреса, яку люди вводять в 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_URLHTTPS-адреса квадратного зображення, показаного поруч із назвою.Немає
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Вважати кожну адресу електронної пошти від цього провайдера підтвердженою. Спершу прочитайте Підтверджені адреси електронної пошти.false
OLEAFLY_SMTP_URL, OLEAFLY_MAIL_FROMЕлектронна пошта. Прочитайте Електронна пошта.Вимкнено
OLEAFLY_OPEN_SIGNUPДавати кожному, хто входить через один із ваших провайдерів, обліковий запис учасника. Прочитайте Відкрита реєстрація.false
OLEAFLY_WEBУвімикає доступ через браузер. Прочитайте Доступ через браузер.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Найбільший обсяг, який можуть зберігати проєкти, що належать одному обліковому запису, у мегабайтах. Прочитайте Обмеження для облікового запису.Без обмеження, або 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.

Типово сервер зберігає все в 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:

    Вікно термінала
    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 на сервер разом із файлом SyncTeX, якщо він є. Для кожного проєкту застосунок надсилає щонайбільше один PDF на хвилину. Сервер зберігає по одному PDF і одному файлу SyncTeX на проєкт, із назвою головного файла, а також тим, хто й коли його скомпілював. Доступ через браузер показує цей PDF людям у проєкті.

Кожне вивантаження замінює попереднє, а старий файл видаляється, щойно його ніщо не використовує. Скомпільовані файли зберігаються разом з іншими файлами, на диску або в бакеті, і видаляються разом зі своїм проєктом. Скомпільований файл може мати розмір до OLEAFLY_MAX_FILE_MB. Він зараховується до сховища облікового запису власника, але не до вивантажень на годину.

Кожен учасник проєкту може читати його скомпільовані файли. Замінювати їх можуть лише власники та редактори.

За зворотним проксі

Розділ «За зворотним проксі»

Сервер розмовляє звичайним 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 — часто це університетська чи корпоративна мережа з фільтрувальним проксі. Редагування в реальному часі там усе одно працює, тільки повільніше. Коли дві спроби 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

Розділ «Що змінює OLEAFLY_BEHIND_PROXY»

Сервер занотовує адресу клієнта у двох місцях: у журналі безпеки і в обмеженнях на те, як часто одна адреса може починати вхід або відкривати живе з’єднання.

Без цього налаштування сервер користується адресою того, хто до нього під’єднався. За проксі це завжди проксі, тож усі ділять одне обмеження, а журнал безпеки показує лише адресу проксі.

З 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 пропускає з’єднання WebSocket і X-Forwarded-For без додаткових налаштувань і сам дістає сертифікат. Повний Caddyfile є в розділі Поставте HTTPS попереду.

Спершу дістаньте сертифікат для домену, наприклад через certbot. Потім збережіть це як /etc/nginx/conf.d/oleafly.conf і виконайте sudo nginx -t && sudo systemctl reload 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 2.4.47 або новіший, який є в Debian 12 та Ubuntu 22.04 і новіших. Увімкніть модулі:

Вікно термінала
sudo a2enmod proxy proxy_http ssl

Збережіть це як /etc/apache2/sites-available/oleafly.conf, потім виконайте sudo a2ensite oleafly && sudo systemctl reload apache2:

<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 рахуються за одну адресу. Ці обмеження працюють на кожну людину окремо лише тоді, коли сервер бачить справжню адресу кожного, тож налаштуйте свій проксі як слід.

Сервер пінгує кожне живе з’єднання що 30 секунд. Він закриває з’єднання, яке 90 секунд не відповідає на ці пінги, і те, що перестає читати те, що сервер надсилає.

Обмеження проєктів стосуються всіх: OLEAFLY_MAX_PROJECT_MB на цілий проєкт (типово 200 МБ), OLEAFLY_MAX_FILE_MB на один файл (50 МБ) і OLEAFLY_MAX_MEMBERS_PER_PROJECT на людей в одному проєкті (20). Поточні обмеження показує Огляд у консолі адміністратора.

Обмеження для облікового запису

Розділ «Обмеження для облікового запису»

Для кожного облікового запису діють три обмеження. Вони вимкнені, доки ви їх не задасте, якщо тільки не ввімкнено відкриту реєстрацію. Вона вмикає їх із такими типовими значеннями:

ОбмеженняНалаштуванняЗ відкритою реєстрацією
Сховище для проєктів, якими володіє обліковий записOLEAFLY_ACCOUNT_STORAGE_MB100 МБ
Спільні проєкти, якими володіє обліковий записOLEAFLY_MAX_PROJECTS_PER_ACCOUNT50
Вивантаження, які обліковий запис робить за годинуOLEAFLY_UPLOADS_PER_HOUR300

Значення, яке ви задали, завжди переважає типове. Кожне має бути цілим числом, не меншим за 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, типово): база даних, файли й знімки — усе в теці даних. Робіть резервну копію всієї теки.
  • Файли в бакеті: тека даних тримає базу даних, а бакет — файли й знімки. Копія бази даних разом із бакетом — це повна резервна копія. Увімкніть версіонування бакета, щоб випадково видалений об’єкт можна було повернути.
Де сервер зберігає дані й що резервуватиКоли файли на диску, як за замовчуванням, папка даних містить базу даних і папку blobs із файлами й знімками, тож ви резервуєте всю папку. Коли файли в бакеті, папка даних містить базу даних, а бакет S3 містить файли й знімки, тож ви резервуєте базу даних і бакет.Файли на диску (за замовчуванням)Файли в бакетіoleafly-serverПапка данихБаза даних: облікові записи, налаштування, журналиblobs: файли й знімкиРезервуйте всю папкуoleafly-serverПапка данихБаза данихБакет S3Файли йзнімкиРезервуйте базу даних і бакетДе сервер зберігає дані й що резервуватиКоли файли на диску, як за замовчуванням, папка даних містить базу даних і папку blobs із файлами й знімками, тож ви резервуєте всю папку. Коли файли в бакеті, папка даних містить базу даних, а бакет S3 містить файли й знімки, тож ви резервуєте базу даних і бакет.Файли на диску (за замовчуванням)Файли в бакетіoleafly-serverПапка данихБаза даних і blobs(файли, знімки)Резервуйте всю папкуoleafly-serverПапка данихБаза данихБакет S3Файли йзнімкиРезервуйте базу данихі бакет
Що потрібно для повної резервної копії, залежить від того, де зберігаються файли.

Робіть резервні копії регулярно і тримайте їх приватними, адже вони містять усі проєкти. Ваших налаштувань, як-от .env, у теці даних немає, тож тримайте ще й їхню копію.

З Docker сервер на кілька секунд зупиняється, поки ви копіюєте том. Oleafly перепід’єднується сам. Виконайте ці команди в теці сервера — /opt/oleafly-server, якщо ви користувалися установником.

Вікно термінала
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:

Вікно термінала
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.

Вікно термінала
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, який нікого не впускає, і немає відкритого порта, тож нею ніхто не може скористатися. Вилучіть її, коли закінчите:

Вікно термінала
sudo docker rm -f oleafly-restore-drill
sudo docker volume rm oleafly-restore-drill

Щоб відновити насправді з Docker Compose, зупиніть сервер, замініть вміст тому архівом і знову запустіть його:

Вікно термінала
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:

Вікно термінала
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»

Архів містить лише те, що було на момент його створення. Litestream (відкривається в новій вкладці) копіює кожну зміну в базі даних сервера до бакета, сумісного з S3, приблизно за секунду після того, як вона стається. Compose-файл містить його як необов’язкову службу.

Litestream копіює лише базу даних. Якщо файли в бакеті, бакет уже тримає файли й знімки, тож копія Litestream разом із бакетом може повернути втрачений диск. Якщо файли на диску, далі робіть архіви тому, бо Litestream не копіює теку blobs.

  1. Створіть бакет або теку в ньому, якою користується лише Litestream цього сервера. Не діліть його з OLEAFLY_BLOB_STORE. Дайте Litestream ключ, який може перелічувати бакет і читати, записувати й видаляти об’єкти в ньому.

  2. Додайте дані до .env:

    Вікно термінала
    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. Запустіть його:

    Вікно термінала
    sudo docker compose up -d
  4. Перевірте, що базу даних скопійовано. Це надрукує рядок із snapshot complete:

    Вікно термінала
    sudo docker compose logs litestream | grep 'snapshot complete'

Litestream робить повну копію раз на день і тримає тиждень копій та зміни між ними. Розклад задано в litestream.yml.

Тренування з відновлення з Litestream

Розділ «Тренування з відновлення з Litestream»

Це тренування відновлює базу даних з бакета в тимчасовий том, запускає на ньому другу копію сервера і перевіряє, що обидві — той самий сервер. Сервер, що працює, не чіпається.

Вікно термінала
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 у двох останніх відповідях мусить збігатися. Вилучіть копію, коли закінчите:

Вікно термінала
sudo docker rm -f oleafly-litestream-drill
sudo docker volume rm oleafly-litestream-drill

Відновлення бази даних з Litestream

Розділ «Відновлення бази даних з Litestream»

Коли файл бази даних пошкоджений або зник, а решта теки даних у порядку, зупиніть сервер і Litestream, вилучіть те, що лишилося від бази даних, відновіть її і запустіть знову:

Вікно термінала
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. Кожен проєкт повертається зі своїми файлами й знімками.

Після втрати диска, коли файли були на диску, відновіть свій найновіший архів і на цьому зупиніться. Не кладіть новішу базу даних з Litestream поверх старішого архіву. База вказувала б на файли й знімки, яких в архіві немає, і такі проєкти не відкривалися б.

Спершу зробіть резервну копію. Сервер оновлює свою базу даних при першому запуску нового релізу, тож повернення до старішого релізу означає відновлення копії, зробленої перед оновленням.

  • Встановлення однією командою: виконайте curl -fsSL https://oleafly.com/server/install.sh | sudo sh -s -- update. Воно зберігає .env, дістає файли й образ нового релізу та перезапускає сервер.
  • Docker Compose власноруч: звантажте файли нового релізу в теку сервера, як описано в Docker Compose власноруч, потім виконайте sudo docker compose up -d.
  • Coolify: виберіть Redeploy. З опублікованим образом це підтягує найновіший реліз під тегом образу.
  • Render: відкрийте службу і запустіть ручне розгортання, яке знову підтягує образ.
  • Railway: розгорніть службу знову з її меню. Railway також може сам оновлювати образ із реєстру GitHub.
  • systemd: установіть новий реліз, як описано в Завантаження сервера, потім виконайте sudo systemctl restart oleafly-server.

Oleafly перевіряє версію сервера при кожному з’єднанні. Якщо застосунок і сервер не можуть працювати разом, Oleafly каже, якому з них потрібне оновлення.

Перегляд зображення

Не вдалося завантажити відповіді ШІ

Спробуйте ще раз або скористайтеся пошуком у документації.