SSD Nodes Learn Hosting plans →
Посібники Matt ConnorВід Matt Connor

Як розгорнути AFFiNE на VPS через Docker Compose

Запустіть AFFiNE на одному VPS через Docker Compose: 4 контейнери, закріплені теги образів, розташування даних, резервні копії та реальні можливості 2 GB RAM.

Що ви отримуєте під час self-hosting AFFiNE

Self-hosting AFFiNE дає вам робочий простір у стилі Notion на сервері під вашим контролем. Він працює як чотири контейнери: застосунок, одноразове завдання міграції, Postgres і Redis. Спільна робота в реальному часі доступна одразу, з обмеженням до 10 місць, які self-hosted робочий простір отримує за замовчуванням. Для інсталяції потрібні один compose-файл і один JSON-файл конфігурації. Продумати потрібно теги образів, структуру дисків, обмеження пам’яті та проксі перед застосунком.

AFFiNE поєднує редактор документів і нескінченне полотно в одному робочому просторі. Тому одну сторінку можна читати як документ або розгорнути як дошку. Якщо ви ще вирішуєте, що запускати, спочатку прочитайте порівняння self-hosted альтернатив Notion. Цей посібник передбачає, що вибір уже зроблено, і описує правильний запуск AFFiNE, а не повторне порівняння.

Усю наведену тут інформацію перевірено за документацією AFFiNE для self-hosting і опублікованими файлами релізів станом на 8 August 2026. Найновішим стабільним релізом на цю дату був 0.27.3, опублікований 23 July 2026. Твердження нижче, що містять пізнішу дату, повторно перевірено за першоджерелами 12 October 2026. На той момент найновішим стабільним релізом був 0.27.4, опублікований 18 August 2026.

Що насправді роблять чотири контейнери

affine — це сервер і вебклієнт в одному образі. Він прослуховує порт 3010.

affine_migration — це одноразове завдання, яке запускає node ./scripts/self-host-predeploy.js, застосовує міграції бази даних і завершує роботу. Застосунок оголошує condition: service_completed_successfully для цього завдання, тому міграція, що завершується з ненульовим кодом стану, означає, що affine взагалі не запускається. Якщо вебінтерфейс не відкривається, журнал цього завдання слід перевірити насамперед.

postgres зберігає ваші документи, користувачів, робочі простори та дозволи. Образ, що постачається, — pgvector/pgvector:pg16, тобто звичайний Postgres 16 із скомпільованим розширенням pgvector. pgvector додає до Postgres тип стовпця vector — числове представлення, яке використовується для зберігання embedding, щоб шукати текст за змістом.

redis — це жорстка залежність: сервер і завдання міграції очікують на перевірку його стану перед запуском. Зверніть увагу, чого файл compose, що постачається, не надає Redis: це volume. Після docker compose down усередині нього нічого не зберігається, тому очевидно, що він не містить ваших даних і не потребує резервного копіювання.

Чому образом Postgres є pgvector, а не стандартний postgres

Ця вимога походить зі схеми AFFiNE, а не з уподобань. У v0.27.4 schema.prisma все ще оголошує extensions = [pgvector(map: "vector")], але не містить стовпців для embedding. Чотири моделі зі стовпцями embedding типу vector(1024), які були у v0.27.3, відсутні у v0.27.4. Використовуйте наданий образ pgvector/pgvector:pg16: розширення все ще оголошене, а стандартний postgres:16 його не містить.

В офіційному шаблоні v0.27.4 використовується образ pgvector; у шаблоні v0.21.0 ще використовувався postgres:16. У старій інсталяції зміна рядка з образом не є повним оновленням, тому перш ніж виконувати pull, прочитайте сторінку про оновлення в документації AFFiNE для self-host.

Є ще один важливий момент щодо цього тегу. pg16 означає Postgres 16, а major-версію Postgres не можна просто збільшити. Якщо змінити її на pg17 у вже наявному каталозі даних, Postgres відмовиться запускатися. У журналі docker compose logs postgres з’явиться повідомлення на кшталт The data directory was initialized by PostgreSQL version 16, which is not compatible with this version 17. Перехід на іншу major-версію потребує одного з трьох способів, зазначених у нотатках до випуску PostgreSQL 17: створення dump і відновлення в новий каталог даних, pg_upgrade або логічної реплікації. Для однієї інсталяції Compose зазвичай найпростіше створити dump і відновити його, оскільки pg_upgrade потребує одночасної наявності бінарних файлів старого та нового сервера.

Скільки CPU і RAM потрібно для self-hosted AFFiNE

На сторінці вимог AFFiNE зазначено, що потрібно щонайменше 4 CPU cores і 2 GB RAM. Для документів обсягом понад 10,000 слів рекомендований обсяг пам’яті збільшується до 4 GB. На цій самій сторінці пояснюється, на що витрачається пам’ять: система синхронізації та об’єднання документів. Є один показник, який варто запам’ятати: об’єднання документа з 10,000 змінами може тимчасово використовувати до 1 GB пам’яті.

Тепер порівняймо це з планом на 2 GB, яким користуються двоє людей. У середньому ресурсів достатньо. Postgres і процес Node працюють у межах ліміту, і ще залишається запас. Проблема виникає під час пікового навантаження. Одне велике об’єднання може збільшити використання пам’яті сервером приблизно до 1 GB. На сервері з 2 GB і без swap цей пік разом із Postgres та іншими процесами може вичерпати доступну пам’ять. Тоді kernel запускає засіб OOM (out-of-memory), який завершує процес, щоб звільнити пам’ять. Сервер AFFiNE як найбільший процес, імовірно, буде завершено. Водночас у документації Docker прямо зазначено, що вибрано може бути будь-який процес, зокрема сам Docker.

Якщо завершується сервер AFFiNE, колега не бачить повідомлення про помилку. Сторінка просто перезавантажується, оскільки restart: unless-stopped повертає контейнер до роботи за кілька секунд. Не здогадуйтеся — перевірте це:

docker inspect affine_server --format '{{.State.OOMKilled}} {{.RestartCount}}'
sudo dmesg -T | grep -i -E 'out of memory|killed process'

true з першої команди або рядок Killed process з назвою node з другої означає, що пам’ять вичерпалася, а не що ви знайшли помилку в програмі. Виправляйте проблему з обох боків. Спочатку додайте swap, щоб під час пікового навантаження пам’ять мала тимчасовий резерв до запуску OOM:

sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
free -h

Тепер free -h має показувати загальний обсяг swap 2.0Gi. Swap не зробить AFFiNE швидшим, і він для цього не призначений. Він дає короткому піку навантаження місце для розподілу. Тому пік із набагато більшою імовірністю спричинить коротке уповільнення, а не зупинку контейнера. Це буфер, а не гарантія. Друга частина виправлення — не дозволити Postgres розширювати кеш у простір, потрібний застосунку під час об’єднання. Для цього призначені обмеження пам’яті для сервісу Compose. Якщо після виконання обох кроків процеси все одно завершуються, серверу потрібні 4 GB, які вказані на сторінці вимог AFFiNE для більших документів.

Обсяг сховища передбачити набагато простіше. Ось показники, які AFFiNE наводить на цій самій сторінці:

ГрафікPublished AFFiNE storage figures, August 2026
Дані, на яких побудовано графік
[
  {
    "label": "Server install",
    "gb": 1.5
  },
  {
    "label": "Postgres per 1,000 docs",
    "gb": 0.1
  },
  {
    "label": "Blob store per 1,000 uploads",
    "gb": 10
  }
]

Встановлення сервера займає 1.5 GB. Тисяча документів приблизно по тисячі слів додає 0.1 GB даних Postgres, тобто майже нічого. Тисяча завантажених файлів додає 10 GB, і саме вони визначають загальний обсяг. Це опубліковані орієнтовні показники, а не вимірювання запущеного екземпляра, тому сприймайте їх як загальну залежність, а не як гарантію. Важлива саме ця залежність: база даних залишається невеликою, а обсяг диска визначається завантаженими файлами.

Напишіть compose-файл самостійно та зафіксуйте теги

Документована процедура встановлення завантажує готовий файл за допомогою curl -L -o docker-compose.yml https://github.com/toeverything/AFFiNE/releases/latest/download/docker-compose.yml. Це працює. Але перед використанням варто знати одну деталь: станом на 8 August 2026 файл, прикріплений до release 0.27.3, усе ще зчитував шляхи з файлу .env за допомогою ${UPLOAD_LOCATION}, ${CONFIG_LOCATION} і ${DB_DATA_LOCATION}, тоді як reference page у документації показувала новішу структуру. У ній дані storage і PostgreSQL розміщені в ./data, конфігурація зберігається в ./config, і файл .env не потрібен. У release 0.27.4 прикріплений файл перевели на цю структуру, і станом на 12 October 2026 обидва варіанти узгоджуються. Якщо ви встановлювали систему зі старого файлу, ваші шляхи й далі беруться з .env. На сторінці оновлення AFFiNE попереджається, що заміна compose-файлу без перенесення цих параметрів може запустити Postgres із порожнім каталогом даних. Якщо написати файл самостійно, це питання не виникає. Крім того, його все одно потрібно змінити, щоб зафіксувати images і встановити пароль бази даних.

mkdir -p ~/affine/config ~/affine/data
cd ~/affine
printf 'DB_PASSWORD=%s\n' "$(openssl rand -hex 24)" > .env
chmod 600 .env

Compose самостійно зчитує .env з каталогу проєкту та підставляє ${DB_PASSWORD}. Тому пароль не з’являється у файлі, який ви могли б вставити в support thread. Цю практику варто застосовувати для кожного stack, який ви запускаєте. Обґрунтування наведено в зберіганні секретів поза compose-файлом.

Тепер створіть ~/affine/docker-compose.yml:

name: affine
services:
  affine:
    image: ghcr.io/toeverything/affine:stable
    container_name: affine_server
    ports:
      - '127.0.0.1:3010:3010'
    depends_on:
      redis:
        condition: service_healthy
      postgres:
        condition: service_healthy
      affine_migration:
        condition: service_completed_successfully
    volumes:
      - ./data/storage:/root/.affine/storage
      - ./config:/root/.affine/config
    environment:
      - REDIS_SERVER_HOST=redis
      - DATABASE_URL=postgresql://affine:${DB_PASSWORD}@postgres:5432/affine
      - AFFINE_INDEXER_ENABLED=false
    restart: unless-stopped

  affine_migration:
    image: ghcr.io/toeverything/affine:stable
    container_name: affine_migration_job
    command: ['sh', '-c', 'node ./scripts/self-host-predeploy.js']
    volumes:
      - ./data/storage:/root/.affine/storage
      - ./config:/root/.affine/config
    environment:
      - REDIS_SERVER_HOST=redis
      - DATABASE_URL=postgresql://affine:${DB_PASSWORD}@postgres:5432/affine
      - AFFINE_INDEXER_ENABLED=false
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy

  redis:
    image: redis:8-alpine
    container_name: affine_redis
    healthcheck:
      test: ['CMD', 'redis-cli', '--raw', 'incr', 'ping']
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped

  postgres:
    image: pgvector/pgvector:pg16
    container_name: affine_postgres
    volumes:
      - ./data/postgres:/var/lib/postgresql/data
    environment:
      POSTGRES_USER: affine
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_DB: affine
      POSTGRES_INITDB_ARGS: '--data-checksums'
    healthcheck:
      test: ['CMD', 'pg_isready', '-U', 'affine', '-d', 'affine']
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped

Є чотири відмінності від файлу, який upstream постачає. Кожна з них має конкретну причину.

  • 127.0.0.1:3010:3010 публікує порт лише на loopback-адресі. Версії Docker до 28.0.0 дають змогу хостам у тому самому L2-сегменті звертатися до портів, опублікованих на localhost. Налаштована пряма маршрутизація також може відкрити порт контейнера, навіть якщо його опубліковано на loopback. Використовуйте Docker 28.0.0 або новішої версії та під час встановлення залишайте пряму маршрутизацію вимкненою. В upstream '3010:3010' прив’язується до всіх інтерфейсів. У більшості VPS images це також охоплює публічний інтерфейс.
  • POSTGRES_HOST_AUTH_METHOD: trust видалено, а натомість встановлено пароль. Trust authentication приймає будь-яке підключення до цієї бази даних від користувача affine без пароля. Це обмежено приватною Compose network. Проблема виникне, якщо ви під’єднаєте до цієї network ще один контейнер або опублікуєте 5432 під час діагностики.
  • redis:8-alpine замінює непідтверджений redis, який розгортається в latest. Станом на August 2026 це Redis 8. Тому такий pin зберігає major version, яку ви протестували, і не дає Redis 9 з’явитися під час стороннього docker compose pull.
  • pgvector/pgvector:pg16 залишається без змін, як його встановлює upstream, з причини, наведеної вище.

POSTGRES_PASSWORD зчитується лише під час першого створення каталогу даних Postgres. Якщо instance уже існує, встановіть пароль за допомогою docker compose exec postgres psql -U affine -c "ALTER USER affine WITH PASSWORD 'yourpassword'", а потім змініть DATABASE_URL відповідно.

Налаштування зберігаються в config/config.json

AFFiNE читає налаштування з config/config.json. Це каталог, змонтований у /root/.affine/config. Цей файл не створюється автоматично, тому створіть його до першого запуску. Відкрийте ~/affine/config/config.json у редакторі та додайте такий вміст, замінивши приклад власним доменом:

{
  "$schema": "https://github.com/toeverything/affine/releases/latest/download/config.schema.json",
  "server": {
    "name": "Team workspace",
    "externalUrl": "https://affine.example.com"
  },
  "copilot": {
    "enabled": false,
    "byok": {
      "enabled": false
    }
  }
}

server.externalUrl має містити адресу, яку користувачі фактично відкривають у браузері. AFFiNE формує посилання для спільного доступу та запрошення до робочих просторів на основі цього значення. Якщо залишити http://localhost:3010, надіслане запрошення вказуватиме на комп’ютер самого отримувача та не працюватиме. Укажіть публічну HTTPS-адресу до першого запуску. Так файл конфігурації та панель адміністратора завжди міститимуть однакову адресу. Налаштування, які ви згодом змінюєте в панелі адміністратора, зберігаються в базі даних, а не записуються назад у цей файл.

copilot керує функціями AI. copilot.byok.enabled — це перемикач bring-your-own-key. Він дає змогу власнику робочого простору вставити власний ключ провайдера моделей у налаштуваннях робочого простору. Self-hosting AFFiNE не включає підписку на AI. Якщо ці функції не потрібні, залиште обидва false.

Запустіть стек:

docker compose up -d
docker compose ps --all

docker compose ps --all має показувати affine_postgres і affine_redis як healthy, affine_server — як running, а affine_migration_job — зі станом exited (0). Параметр --all важливий: без нього docker compose ps показує лише запущені контейнери, тому завдання міграції, яке успішно завершилося, взагалі не відображається. Якщо завдання міграції завершилося з будь-яким іншим кодом, саме це потрібно дослідити. Його журнал містить назву кроку, на якому виконання зупинилося:

docker compose logs affine_migration

Зафіксуйте образ, перш ніж забути

stable — це змінний тег. Процес випуску AFFiNE прив’язує кілька тегів до кожної стабільної збірки. Тут важливі два: stable, який переназначається під час кожного випуску, і stable-, після якого вказано короткий git-хеш, який не змінюється. Якщо залишити stable, то docker compose pull через шість місяців завантажить інший образ і виконає його міграції для вашої бази даних у момент, який ви не обирали. Зафіксуйте точний образ, який ви протестували:

docker compose pull
docker image inspect ghcr.io/toeverything/affine:stable --format '{{index .RepoDigests 0}}'

Команда виведе рядок на кшталт ghcr.io/toeverything/affine@sha256:, після якого буде довгий хеш. Вставте весь цей рядок у рядок image: обох файлів: affine і affine_migration. Ці значення завжди мають збігатися, оскільки йдеться про той самий образ, який виконує дві ролі. Якщо вони відрізняються, база даних мігрує до однієї схеми, а обслуговуватися буде іншою. Після цього оновлення стає свідомою зміною, а не несподіванкою: змініть digest, створіть резервну копію, docker compose pull, docker compose up -d.

Створіть обліковий запис адміністратора раніше за всіх

Відкрийте /admin у щойно розгорнутому екземплярі. AFFiNE перенаправить вас на сторінку створення облікового запису, оскільки на сервері ще немає адміністратора. У цьому процесі немає коду запрошення або токена налаштування. Перший користувач, який завершить реєстрацію, стане адміністратором вашого сервера, тому порт має залишатися закритим, доки ви не зареєструєтеся.

Саме тому наведений вище compose-файл прив’язує сервіс до 127.0.0.1. Отримайте доступ до нього через SSH-тунель зі свого комп’ютера:

ssh -L 3010:127.0.0.1:3010 you@your-server-ip

Залиште цей процес запущеним і відкрийте http://127.0.0.1:3010/admin у локальному браузері. Зареєструйтеся та увійдіть у систему, після чого закрийте тунель. Лише після цього екземпляр можна безпечно опублікувати за публічним доменним ім’ям. Така сама проблема виникає в інших self-hosted застосунках. Вона ще серйозніша, якщо під час першого входу створюється passkey, прив’язаний до hostname. Саме тому TLS і остаточне доменне ім’я потрібно налаштувати до створення першого облікового запису, коли ви розгортаєте self-hosted openGym.

Де AFFiNE зберігає ваші дані

Усі дані зберігаються у трьох шляхах, розташованих у створеному вами каталозі.

  • ./data/postgres — це каталог даних Postgres: документи, користувачі, робочі простори, дозволи та параметри сервера, збережені в панелі адміністрування.
  • ./data/storage змонтовано в контейнері за шляхом /root/.affine/storage. Тут зберігаються всі завантажені файли.
  • ./config змонтовано за шляхом /root/.affine/config. Тут зберігаються config.json і private.key, створені завданням міграції.

У цьому випадку upstream використовує bind mounts замість іменованих томів. Це зроблено навмисно: ці шляхи можна архівувати за допомогою tar і копіювати звичайними командами, не з’ясовуючи, де саме Docker їх розмістив. Недоліком є те, що за власників файлів на хості тепер відповідаєте ви. Цей компроміс описано в розділі bind mounts та іменовані томи.

Як створити резервну копію AFFiNE

Потрібно створити резервні копії двох компонентів, і робляться вони по-різному. База даних працює як активний сервер, тому копіювання її файлів під час роботи створить пошкоджену копію. Натомість створіть дамп:

mkdir -p ~/affine/backup
cd ~/affine
docker compose exec -T postgres pg_dump --format c --username affine affine \
  > backup/affine-$(date +%F).dump
ls -lh backup/

Дамп створюється всередині контейнера через його локальний сокет, тому пароль не запитується. Перевірте розмір у виводі ls. Файл розміром кілька сотень байтів означає, що створення дампа завершилося помилкою, але shell все одно створив файл. Таку помилку часто виявляють лише через шість місяців. Параметр -T також важливий: без нього Compose може виділити термінал і пошкодити бінарний потік.

Завантажені файли є звичайними файлами, тому запакуйте їх за допомогою tar:

tar czf backup/storage-$(date +%F).tgz -C data storage
tar czf backup/config-$(date +%F).tgz config docker-compose.yml .env

Збережіть у резервній копії весь каталог config, файл Compose і .env, оскільки дамп їх не містить. Завдання міграції також створює config/private.key, тому копіювання лише config.json не збереже цей файл. Налаштування, збережені в панелі адміністрування, містяться в базі даних, тому наведений вище дамп уже містить їх. Станом на 12 October 2026 сторінка резервного копіювання AFFiNE також дає змогу експортувати змінені налаштування сервера з панелі адміністрування. Скопіюйте всі три файли на інший сервер або інший носій. Резервна копія на тому самому диску, що й дані, які вона захищає, не є резервною копією. Такий поділ на дамп бази даних і tar-архів каталогу завантажень слід застосовувати для кожного іншого stateful-контейнера. За таким самим принципом зберігаються історія розмов і вкладення, коли ви самостійно розгортаєте Chatwoot як службу підтримки.

Відновлення та одна помилка в опублікованих інструкціях

Прочитайте офіційні інструкції з відновлення заздалегідь і уважно їх перевірте. У версії, опублікованій у серпні 2026 року, файл із назвою affine.backup копіювали в контейнер, а потім виконували відновлення з ./pg.backup. Це різні імена. Також видаляли каталог ./postgres, хоча поточний compose-файл зберігає дані в ./data/postgres. Станом на 12 жовтня 2026 року на сторінці всюди використовується affine.backup і зазначено, що старий каталог Postgres потрібно зберігати до перевірки відновлення. Отже, цю помилку виправлено в upstream-версії, але копія інструкцій, збережена раніше, усе ще її містить. У будь-якому разі використовуйте фактичні шляхи, які ви налаштували, а не шляхи з будь-якого фрагмента інструкцій. Для структури каталогів у цьому посібнику послідовність така:

cd ~/affine
docker compose down
sudo mv data/postgres data/postgres.old
docker compose up -d postgres
docker compose cp backup/affine-2026-08-08.dump postgres:/tmp/affine.dump
docker compose exec postgres pg_restore --format c --username affine \
  --dbname affine --verbose /tmp/affine.dump
docker compose up -d

Зверніть увагу на mv, а не на rm. Відновлення поверх бази даних, резервної копії якої у вас немає, може перетворити одну помилкову команду на повну втрату даних. Переміщення старого каталогу в інше місце нічого не коштує. Також відновіть uploads за допомогою tar xzf backup/storage-2026-08-08.tgz -C data, інакше кожен документ відображатиметься без вкладених файлів. Потім увійдіть у систему та відкрийте документ, який містить зображення. Це і є перевірка. Відновлення, яке ви не відкрили в браузері, — це файл, а не резервна копія.

Розміщення AFFiNE за наявним reverse proxy

AFFiNE використовує WebSocket, і це обов’язково. У документації прямо зазначено: WebSocket є основою системи синхронізації та спільної роботи AFFiNE. Тому proxy, який не оновлює такі з’єднання, створює workspace, де редагування непомітно перестає синхронізуватися. Сторінка завантажується, вхід працює, але зміни, внесені в одному браузері, не з’являються в іншому. В інструментах розробника браузера відкрийте вкладку Network і застосуйте фільтр WS. З’єднання, яке постійно відкривається та закривається, означає, що proxy не передає запит на оновлення з’єднання.

Якщо ви вже використовуєте Traefik для інших контейнерів, AFFiNE додається до нього як звичайний сервіс. Видаліть блок ports: із сервісу affine, а потім додайте:

    networks:
      - default
      - proxy
    labels:
      - 'traefik.enable=true'
      - 'traefik.docker.network=proxy'
      - 'traefik.http.routers.affine.rule=Host(`affine.example.com`)'
      - 'traefik.http.routers.affine.entrypoints=websecure'
      - 'traefik.http.routers.affine.tls.certresolver=letsencrypt'
      - 'traefik.http.services.affine.loadbalancer.server.port=3010'

У нижній частині файлу, поруч із services:, додайте:

networks:
  proxy:
    external: true

Назва certificate resolver має збігатися з назвою, визначеною у конфігурації Traefik, а loadbalancer.server.port — це порт контейнера 3010, а не порт хоста. Traefik проксуює WebSocket-з’єднання без додаткової конфігурації, тому більше нічого додавати не потрібно. Якщо решта вашого стека вже працює за Authentik для єдиного входу, forward auth middleware на цьому router обмежить доступ браузера до AFFiNE. Проте не вмикайте його, доки не протестуєте desktop app: він не має browser session і просто не зможе синхронізуватися. Запуск кількох застосунків за одним екземпляром описано в розділі один Traefik перед кількома застосунками.

У nginx оновлення з’єднання потрібно явно дозволити:

location / {
    proxy_pass http://127.0.0.1:3010;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    client_max_body_size 100m;
}

client_max_body_size у nginx за замовчуванням має значення 1 MB. Без цього рядка кожне завантаження, більше за невелике фото, завершується статусом 413, а в журналах AFFiNE нічого не з’являється, оскільки запит не дійшов до застосунку. Для Caddy потрібен один рядок — reverse_proxy http://127.0.0.1:3010. Він самостійно обробляє сертифікати та оновлення WebSocket-з’єднань.

Що не входить до self-hosted збірки

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

Спільна робота в реальному часі підтримується. Саме на цій можливості ґрунтуються всі рекомендації щодо розміру сервера, оскільки власна документація AFFiNE пов’язує використання пам’яті із системою синхронізації та злиттям документів. Офлайн-редагування є однією з причин, чому багато користувачів обирають local-first інструмент. Настільний застосунок може додати ваш self-hosted сервер до списку робочих просторів і виконати вхід через нього. Перевірте точну офлайн-поведінку, від якої залежить ваша команда, перш ніж ухвалювати рішення: вимкніть мережу, відредагуйте документ у настільному застосунку, підключіться знову, а потім перевірте результат на другому пристрої. Списки функцій не є доказом, і це стосується також цього списку.

Повнотекстовий пошук на сервері вимкнено у файлі compose, що постачається разом із продуктом, де AFFINE_INDEXER_ENABLED=false встановлено на сервері та в завданні міграції. Щоб увімкнути пошук, потрібно додати контейнер Manticore Search. Це буде п’ятий сервіс і збільшить використання пам’яті. На сервері з 2 GB RAM саме ця зміна може перевищити доступний ресурс. Пошук усередині клієнта продовжує працювати у відкритому робочому просторі.

Перед запрошенням користувачів варто знати про два обмеження. Для self-hosted робочого простору можна надати не більше 10 місць. Для більшої кількості потрібна Team ліцензія від AFFiNE. В документації зазначено, що необмежене blob-сховище та необмежений розмір blob для self-hosted інстансів заплановані, але станом на October 2026 ще не повністю реалізовані. Для домашнього використання або невеликої команди це не має значення. Обидва обмеження важливі, якщо ви планували перевести сорок людей.

Оновлення

Спочатку прочитайте release notes, особливо перед переходом на мінорну версію, наприклад з 0.26 на 0.27, оскільки в ній можуть з’явитися несумісні зміни. Перед будь-якими змінами створіть резервні копії бази даних і каталогу storage, оскільки під час наступного запуску migration job змінить схему, а скасувати ці зміни неможливо. Потім змініть зафіксований digest, виконайте docker compose pull, а після нього docker compose up -d, і monitor-те docker compose logs -f affine_migration, доки команда не завершиться без помилок. Після цього docker image prune видалить старі layers. Для користувачів дуже старих інсталяцій важлива така історична примітка: починаючи з версії 0.23.0, назву image змінено з affine-graphql на affine. Тому в compose-файлі старішої версії потрібно переписати рядки з image, перш ніж pull зможе знайти потрібний image. Починаючи з версії 0.27.4, офіційний compose template змінив шляхи до Postgres, upload і configuration, а також default database connection. Тому порівняйте новий файл зі своїм, а не замінюйте ним робочу інсталяцію.

FAQ

Чому контейнер AFFiNE ніколи не запускається?

Сервіс affine оголошує condition: service_completed_successfully для завдання affine_migration. Тому, якщо міграція завершується з будь-яким статусом, відмінним від 0, сервер не запускається, а вебінтерфейс взагалі не з’являється. Виконайте docker compose logs affine_migration, щоб визначити, на якому кроці стався збій. Перевірте, чи уручну відредагований Compose-файл і далі використовує pgvector/pgvector:pg16. Стандартний Postgres не містить розширення pgvector, яке досі оголошене в схемі AFFiNE, хоча у версії v0.27.4 вже не визначені чотири моделі embedding, присутні у v0.27.3.

Скільки RAM потрібно для self-hosted AFFiNE?

На сторінці вимог AFFiNE зазначено щонайменше 4 ядра CPU і 2 GB RAM. Якщо документи містять понад 10,000 слів, потреба в RAM зростає до 4 GB. Також зазначено, що об’єднання документа з 10,000 змінами може тимчасово потребувати до 1 GB. На сервері з 2 GB саме цей пік, а не навантаження в режимі простою, спричиняє проблему: kernel out-of-memory killer завершує один із процесів, найімовірніше сервер AFFiNE як найбільший процес, а restart: unless-stopped запускає його знову. Тому користувачі бачать перезавантаження сторінки, а не повідомлення про помилку. Підтвердьте це за допомогою docker inspect affine_server --format '{{.State.OOMKilled}}' і sudo dmesg -T | grep -i 'out of memory'. Потім додайте файл підкачки розміром 2 GB як буфер для короткочасних піків навантаження. Якщо завершення процесу тривають, збільште обсяг RAM до 4 GB.

Де AFFiNE зберігає мої дані і що потрібно резервувати?

Усі дані зберігаються у трьох шляхах у каталозі Compose: ./data/postgres — база даних, ./data/storage — завантажені файли, а ./config — config.json і згенерований private.key. Створюйте резервну копію бази даних за допомогою docker compose exec -T postgres pg_dump --format c --username affine affine > affine.dump, а не копіюванням файлів, оскільки запущений Postgres не можна безпечно копіювати таким способом. Цей дамп також містить налаштування, збережені в адміністративній панелі, оскільки AFFiNE зберігає їх у базі даних. Створіть архів ./data/storage для завантажених файлів і збережіть весь каталог config, Compose-файл і .env, оскільки ці файли не є частиною бази даних.

Чи працює спільна робота в реальному часі у self-hosted AFFiNE?

Так, додатково вмикати цю функцію не потрібно. Єдина вимога стосується reverse proxy, оскільки синхронізація працює через WebSocket-з’єднання. У nginx це означає proxy_http_version 1.1, а також заголовки Upgrade і Connection: upgrade. Traefik і Caddy передають такі з’єднання без додаткової конфігурації. Якщо proxy не переводить з’єднання в режим WebSocket, робочий простір завантажується і вхід виконується нормально, але зміни, внесені в одному браузері, не з’являються в іншому.

Чи можна запускати AFFiNE зі стандартним образом Postgres?

Використовуйте pgvector/pgvector:pg16. Це Postgres 16 із скомпільованим розширенням pgvector. AFFiNE v0.27.4 досі оголошує extensions = [pgvector(map: "vector")] у schema.prisma, але вже не визначає чотири моделі зі стовпцями embedding vector(1024), присутні у v0.27.3. Стандартний Postgres не містить оголошеного розширення. Якщо AFFiNE підключається до зовнішнього сервера Postgres, установіть на ньому pgvector і створіть розширення в цільовій базі даних до запуску міграції.

Чи була ця стаття корисною?