SSD Nodes Learn Hosting plans →
Mga Gabay Matt ConnorNi Matt Connor

Paano mag-self-host ng AFFiNE gamit ang Docker Compose

I-run ang AFFiNE sa isang VPS gamit ang Docker Compose: alamin ang 4 na container, pinned image tags, data location, backups, at limitasyon ng 2 GB RAM.

Ano ang makukuha mo sa pag-self-host ng AFFiNE

Sa pag-self-host ng AFFiNE, magkakaroon ka ng workspace na gaya ng Notion sa server na ikaw ang kumokontrol. Tumatakbo ito bilang apat na container: ang application, isang one-shot migration job, Postgres, at Redis. Kasama ang real-time collaboration, hanggang sa 10 seat na default na inilaan para sa self-hosted workspace. Ang installation ay binubuo ng isang compose file at isang JSON config file. Ang kailangang pag-isipan ay ang image tags, disk layout, memory ceiling, at ang proxy na ilalagay sa harap nito.

Pinagsasama ng AFFiNE ang document editor at infinite canvas sa iisang workspace. Kaya maaaring basahin ang isang page bilang dokumento o ilatag ito bilang whiteboard. Kung pinagpapasyahan mo pa kung ano ang patatakbuhin, basahin muna ang paghahambing ng mga self-hosted na alternatibo sa Notion. Ipinapalagay ng gabay na ito na napili na ang software, at nakatuon ito sa wastong pagpapatakbo ng AFFiNE sa halip na muling paghambingin ang mga opsyon.

Sinuri ang lahat ng nilalaman dito batay sa self-host documentation ng AFFiNE at sa mga inilabas na release file noong 8 August 2026. Ang pinakabagong stable release sa petsang iyon ay 0.27.3, na inilabas noong 23 July 2026. Ang mga pahayag sa ibaba na may mas huling petsa ay muling sinuri batay sa kanilang primary sources noong 12 October 2026, nang ang pinakabagong stable release ay 0.27.4, na inilabas noong 18 August 2026.

Ano talaga ang ginagawa ng apat na container

affine ang server at web client sa iisang image. Nakikinig ito sa port 3010.

affine_migration ay isang one-shot job na nagpapatakbo ng node ./scripts/self-host-predeploy.js, nag-a-apply ng database migrations, at nag-e-exit. Idinedeklara ng application ang condition: service_completed_successfully bilang dependency ng job na iyon, kaya kapag nag-exit ang migration nang may non-zero status, hindi talaga nagsisimula ang affine. Kapag hindi lumalabas ang web interface, ang log ng job na iyon ang unang dapat basahin.

postgres ang naglalaman ng iyong mga dokumento, user, workspace, at permission. Ang shipped image ay pgvector/pgvector:pg16, na karaniwang Postgres 16 na may naka-compile na pgvector extension. Nagdaragdag ang pgvector ng vector column type sa Postgres. Ito ang numeric form na ginagamit para mag-store ng embeddings upang ma-search ang text batay sa kahulugan.

redis ang hard dependency: naghihintay ang server at migration job sa health check nito bago sila magsimula. Pansinin kung ano ang hindi ibinibigay ng shipped compose file sa Redis, na isang volume. Walang laman nito ang nananatili matapos ang docker compose down, kaya malinaw na wala itong iyong content at hindi ito nangangailangan ng backup.

Bakit pgvector ang Postgres image at hindi stock postgres

Nagmumula sa schema ng AFFiNE ang requirement na ito, hindi sa personal na preference. Sa v0.27.4, dine-declare pa rin ng schema.prisma ang extensions = [pgvector(map: "vector")], pero wala itong embedding columns. Wala na sa v0.27.4 ang apat na model na may mga column na embedding na naka-type bilang vector(1024) sa v0.27.3. Gamitin ang ibinigay na pgvector/pgvector:pg16 image: dine-declare pa rin ang extension, at hindi ito kasama sa stock postgres:16.

Ginagamit ng opisyal na v0.27.4 template ang pgvector image; ginagamit pa rin ng v0.21.0 template ang postgres:16. Kung mas luma ang install, hindi sapat na baguhin lang ang image line para sa upgrade. Basahin muna ang upgrade page sa mga self-host docs ng AFFiNE bago mag-pull ng anuman.

May isa pang mahalagang punto tungkol sa tag na iyon. Nangangahulugan ang pg16 na Postgres 16, at hindi basta numerong maaaring i-bump ang major version ng Postgres. Kapag pinalitan mo ito ng pg17 habang ginagamit ang kasalukuyang data directory, tatanggi ang Postgres na magsimula. May lalabas na linyang gaya ng The data directory was initialized by PostgreSQL version 16, which is not compatible with this version 17 sa docker compose logs postgres. Kailangan ng paglipat sa bagong major version ang isa sa tatlong paraang binanggit sa PostgreSQL 17 release notes: dump at restore sa bagong data directory, pg_upgrade, o logical replication. Sa iisang Compose install, karaniwang pinakasimple ang dump at restore dahil kailangang magkatabi ang lumang server binaries at bagong server binaries para sa pg_upgrade.

Gaano karaming CPU at RAM ang kailangan ng self-hosted AFFiNE

Ayon sa requirements page ng AFFiNE, kailangan nito ng hindi bababa sa 4 CPU core at 2 GB RAM. Itinataas nito ang kinakailangang memory sa 4 GB kapag lumampas sa 10,000 salita ang mga dokumento mo. Nakasaad din sa parehong page kung saan napupunta ang memory: sa sync system at document merging. May isang figure itong dapat tandaan: ang pag-merge ng dokumentong may 10,000 modification ay maaaring umabot sa 1 GB ang peak memory use.

Ihambing ito sa isang 2 GB plan na ginagamit ng dalawang taong sumusulat. Maayos ang average usage. Nananatili sa ilalim ng limit ang Postgres at ang Node process, na may natitirang memory. Ang peak ang problema. Maaaring itulak ng isang malaking merge ang memory use ng server sa humigit-kumulang 1 GB. Sa 2 GB server na walang swap, maaaring maubos ang memory kapag isinama ang peak na ito sa Postgres at iba pang resident process. Pagkatapos, papatayin ng kernel's out-of-memory (OOM) killer ang isang process upang magbakante ng memory. Dahil pinakamalaki ang AFFiNE server process, malamang na ito ang mapili, bagama't malinaw sa documentation ng Docker na maaaring anumang process ang piliin, pati ang Docker mismo.

Kapag ang AFFiNE server ang pinatay, walang error na makikita ang kasamahan mo. Magre-reload lang ang page dahil awtomatikong ibinabalik ng restart: unless-stopped ang container sa loob ng ilang segundo. Huwag itong hulaan. Kumpirmahin ito:

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

Ang true mula sa unang command, o isang linyang Killed process na naglalaman ng node mula sa ikalawang command, ay nangangahulugang naubusan ka ng memory at hindi na nakakita ng bug. Ayusin ito mula sa dalawang panig. Magdagdag muna ng swap para may buffer na mapaglalagyan ng spike bago kumilos ang OOM killer:

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

Dapat i-report ngayon ng free -h ang kabuuang swap na 2.0Gi. Hindi pinapabilis ng swap ang AFFiNE, at hindi iyon ang layunin nito. Nagbibigay ito ng pansamantalang mapupuntahan ng biglaang memory spike, kaya mas malamang na magdulot ito ng isang mabagal na segundo kaysa sa pag-dead ng container. Buffer ito, hindi garantiya. Ang kabilang panig ng solusyon ay pigilan ang Postgres na palakihin ang cache nito hanggang sa espasyong kailangan ng application sa oras ng merge. Iyan ang gamit ng memory limits sa isang Compose service. Kung nagpapatuloy ang mga pagpatay matapos gawin ang dalawang hakbang, kailangan ng server ang 4 GB na hinihingi ng requirements page ng AFFiNE para sa mas malalaking dokumento.

Mas madaling hulaan ang storage. Ito ang mga figure na inilalathala ng AFFiNE sa parehong page:

TsartPublished AFFiNE storage figures, August 2026
Ang datos sa likod ng tsart na ito
[
  {
    "label": "Server install",
    "gb": 1.5
  },
  {
    "label": "Postgres per 1,000 docs",
    "gb": 0.1
  },
  {
    "label": "Blob store per 1,000 uploads",
    "gb": 10
  }
]

Kumokonsumo ng 1.5 GB ang server install. Ang 1,000 dokumentong may humigit-kumulang 1,000 salita bawat isa ay nagdaragdag ng 0.1 GB ng Postgres data, na halos wala. Ang 1,000 uploaded file ay nagdaragdag ng 10 GB, at iyon ang pangunahing usapin. Mga published planning figure ang mga ito, hindi mga sukat mula sa aktuwal na tumatakbong instance. Ituring ang mga ito bilang gabay sa pattern ng paggamit, hindi bilang garantiya. Ang mahalaga ay ang pattern: mananatiling maliit ang database mo, habang ang mga upload ang magpapasya kung gaano kalaking disk ang kailangan mo.

Isulat mismo ang compose file, at i-pin ang mga tag

Idinada-download ng dokumentadong installation ang isang handa nang file gamit ang curl -L -o docker-compose.yml https://github.com/toeverything/AFFiNE/releases/latest/download/docker-compose.yml. Gumagana ito. May isang detalyeng dapat malaman bago ka umasa rito: noong 8 August 2026, binabasa pa rin ng file na naka-attach sa release 0.27.3 ang mga path nito mula sa isang .env file, gamit ang ${UPLOAD_LOCATION}, ${CONFIG_LOCATION}, at ${DB_DATA_LOCATION}, samantalang ang reference page ng documentation ay nagpapakita ng mas bagong layout na naglalagay ng storage at PostgreSQL data sa ilalim ng ./data, nagpapanatili ng configuration sa ilalim ng ./config, at hindi na nangangailangan ng .env. Inilipat ng release 0.27.4 ang naka-attach na file sa layout na iyon, at noong 12 October 2026 ay magkapareho na ang dalawa. Kung nag-install ka gamit ang mas lumang file, mula pa rin sa .env ang mga path mo. Nagbababala ang upgrade page ng AFFiNE na kapag pinalitan ang compose file nang hindi isinama ang mga setting na iyon, maaaring magsimula ang Postgres gamit ang isang walang laman na data directory. Kung ikaw mismo ang susulat ng file, maiiwasan mo ang isyung iyon. Kailangan mo rin itong i-edit para i-pin ang mga image at magtakda ng database password.

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

Awtomatikong binabasa ng Compose ang .env mula sa project directory at pinapalitan nito ang ${DB_PASSWORD} para sa iyo. Dahil dito, hindi lumalabas ang password sa file na maaari mong i-paste sa isang support thread. Panatilihin ang ganitong gawain sa bawat stack na pinapatakbo mo. Ipinaliwanag ang dahilan sa pag-iwas na mailagay ang mga secret sa compose file.

Isulat ngayon ang ~/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

May apat na pagkakaiba ito kumpara sa file na inilalabas ng upstream, at may dahilan ang bawat isa.

  • Ang 127.0.0.1:3010:3010 ay nagpa-publish ng port sa loopback address lamang. Sa Docker bago ang 28.0.0, maaaring maabot ng mga host sa parehong L2 segment ang mga port na naka-publish sa localhost. Maaari ring ilantad ng naka-configure na direct routing ang container port kahit loopback publishing ang ginagamit. Gumamit ng Docker 28.0.0 o mas bago, at panatilihing naka-disable ang direct routing habang nagse-set up. Ang upstream na '3010:3010' ay nagbi-bind sa lahat ng interface. Sa karamihan ng VPS image, kabilang dito ang public interface.
  • Inalis ang POSTGRES_HOST_AUTH_METHOD: trust at nagtakda ng password sa halip. Tumatanggap ang trust authentication ng anumang connection sa database na iyon bilang user na affine nang walang password. Limitado ito sa private Compose network, na ayos hanggang sa mag-attach ka ng isa pang container sa network na iyon o mag-publish ng 5432 habang nagde-debug.
  • Pinapalitan ng redis:8-alpine ang isang walang pin na redis, na nagre-resolve sa latest. Noong August 2026, Redis 8 iyon. Pinananatili ng pin ang major version na sinubukan mo at pinipigilan nitong dumating ang Redis 9 habang may ibang docker compose pull na isinasagawa.
  • Nananatiling eksaktong katulad ng upstream ang pgvector/pgvector:pg16, para sa dahilang ipinaliwanag sa itaas.

Binabasa lamang ang POSTGRES_PASSWORD kapag unang nililikha ng Postgres ang data directory nito. Kung mayroon nang instance, itakda ang password gamit ang docker compose exec postgres psql -U affine -c "ALTER USER affine WITH PASSWORD 'yourpassword'", pagkatapos ay i-update ang DATABASE_URL upang tumugma rito.

Nasa config/config.json ang configuration

Binabasa ng AFFiNE ang mga setting nito mula sa config/config.json, na siyang directory na ni-mount mo sa /root/.affine/config. Walang awtomatikong gumagawa ng file na iyon, kaya isulat ito bago ang unang pag-start. Buksan ang ~/affine/config/config.json sa isang editor at ilagay ang content na ito. Palitan ang example ng sarili mong domain:

{
  "$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
    }
  }
}

Ang server.externalUrl ay dapat na address na aktuwal na binubuksan ng mga user sa browser. Ginagamit ng AFFiNE ang value na ito sa paggawa ng share links at workspace invitations. Kung mananatili itong http://localhost:3010, ang invitation na ipapadala mo ay magtuturo sa sariling machine ng tatanggap at mabibigo roon. Itakda ito sa public HTTPS address bago ang unang pag-start upang hindi magkaiba ang file at ang admin panel tungkol dito. Ang mga setting na babaguhin mo kalaunan sa admin panel ay sine-save sa database at hindi isinusulat pabalik sa file na ito.

Kinokontrol ng copilot ang mga AI feature. Ang copilot.byok.enabled ay ang bring-your-own-key switch. Pinapayagan nito ang workspace owner na ilagay ang sarili nilang model provider key sa workspace settings. Walang kasamang AI subscription ang self-hosted na AFFiNE. Iwanang naka-disable ang dalawang false kung ayaw mong gamitin ito.

I-start ang stack:

docker compose up -d
docker compose ps --all

Dapat ilista ng docker compose ps --all ang affine_postgres at affine_redis bilang healthy, ang affine_server bilang running, at ang affine_migration_job na may state na exited (0). Mahalaga ang --all. Kung wala ito, mga tumatakbong container lamang ang ipinapakita ng docker compose ps, kaya hindi lalabas ang migration job na malinis nang natapos. Anumang ibang exit code sa migration job ang dapat siyasatin. Tinutukoy ng log nito ang step kung saan ito huminto:

docker compose logs affine_migration

I-pin ang image bago mo makalimutan

Ang stable ay isang gumagalaw na tag. Tinutukoy ng release workflow ng AFFiNE ang bawat stable build gamit ang ilang tag, at dalawa rito ang mahalaga: ang stable, na itinuturo sa bagong release sa bawat release, at ang stable- na sinusundan ng git short hash, na hindi nagbabago. Kapag iniwan sa stable, ang docker compose pull pagkalipas ng anim na buwan ay kukuha ng ibang image at magpapatakbo ng migrations laban sa database mo sa panahong hindi mo pinili. I-pin ang eksaktong image na sinubukan mo:

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

Magpi-print ito ng linyang tulad ng ghcr.io/toeverything/affine@sha256: na sinusundan ng mahabang hash. I-paste ang buong string sa linyang image: ng parehong affine at affine_migration. Dapat palaging magkapareho ang dalawang iyon dahil iisang image ang ginagamit nila sa magkaibang role, at nangangahulugan ang mismatch na imu-migrate ang database sa isang schema habang ibang schema naman ang ginagamit sa pag-serve nito. Sa ganitong paraan, sinasadya ang upgrade sa pamamagitan ng pag-edit sa halip na maging sorpresa: palitan ang digest, mag-back up, docker compose pull, docker compose up -d.

Gawin ang admin account bago ito magawa ng iba

Buksan ang /admin sa bagong instance. Ire-redirect ka ng AFFiNE sa page ng paggawa ng account dahil wala pang administrator ang server. Walang invitation code o setup token sa flow na ito. Ang unang makatapos ng registration ang magiging administrator ng server mo, kaya dapat sarado ang port hanggang makapag-register ka.

Kaya nagbi-bind ang compose file sa 127.0.0.1. I-access ito sa pamamagitan ng SSH tunnel mula sa sarili mong machine:

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

Iwanang tumatakbo ang tunnel at buksan ang http://127.0.0.1:3010/admin sa local browser mo. Mag-register at mag-log in, pagkatapos ay isara ang tunnel. Saka pa lamang ligtas na ilagay ang instance sa public name. Ganito rin ang race condition sa ibang self-hosted app. Mas malala ito sa mga app kung saan ang unang pag-login ay gumagawa ng passkey na naka-bind sa hostname. Kaya kailangang maayos na ang TLS at final domain bago gawin ang unang account kapag nagse-self-host ng openGym.

Kung saan iniimbak ng AFFiNE ang iyong data

Tatlong path ang naglalaman ng lahat ng data, at nasa loob ang mga ito ng directory na ginawa mo.

  • Ang ./data/postgres ay Postgres data directory. Nilalaman nito ang mga document, user, workspace, permission, at anumang server setting na na-save mula sa admin panel.
  • Naka-mount ang ./data/storage sa /root/.affine/storage sa loob ng container. Nilalaman nito ang lahat ng in-upload na file.
  • Naka-mount ang ./config sa /root/.affine/config. Nilalaman nito ang config.json at ang private.key na ginawa ng migration job.

Gumagamit ang upstream ng bind mount dito sa halip na named volume, at sinadya ang pagpiling ito. Maaari mong i-tar at kopyahin ang mga path na ito gamit ang karaniwang command, nang hindi kailangang alamin sa Docker kung saan nito inilagay ang mga ito. Ang kapalit nito ay ikaw ang kailangang mamahala sa file ownership sa host. Ito ang trade-off na tinatalakay sa bind mount at named volume.

Paano mag-back up ng AFFiNE

Dalawang bagay ang kailangang i-back up, at magkaiba ang paraan ng pag-back up sa mga ito. Live server ang database, kaya magiging corrupt ang kopya kung kokopyahin ang mga file nito habang tumatakbo ito. Sa halip, gumawa ng dump:

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/

Tumatakbo ang dump sa loob ng container gamit ang lokal nitong socket, kaya hindi ito humihingi ng password. Suriin ang size sa output ng ls na iyon. Kung ilang daang byte lamang ang file, nabigo ang dump kahit ginawa pa rin ng shell ang file. Karaniwang natutuklasan ang ganitong problema makalipas ang anim na buwan. Mahalaga rin ang -T: kung wala ito, maaaring maglaan ang Compose ng terminal at masira ang binary stream.

Mga file lamang ang uploaded files, kaya i-tar ang mga ito:

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

Isama sa backup ang buong directory na config, ang Compose file, at ang .env, dahil hindi kasama ang mga ito sa dump. Gumagawa rin ang migration job ng config/private.key, kaya maiiwan ang file na iyon kung config.json lamang ang kokopyahin. Naka-store sa database ang mga setting na sine-save sa admin panel, kaya kasama na ang mga ito sa dump sa itaas. Simula 12 October 2026, ipinapakita rin sa backup page ng AFFiNE na maaaring i-export mula sa admin panel ang mga binagong server settings. Kopyahin ang tatlong file palabas ng server. Hindi backup ang kopyang nasa kaparehong disk ng pinoprotektahan nitong data. Ang paghihiwalay na ito ng database dump at tar ng uploads directory ang pattern na dapat ulitin sa bawat iba pang stateful container na pinapatakbo mo. Ito rin ang paraan upang mapanatiling ligtas ang conversation history at attachments kapag nag-self-host ng Chatwoot bilang support desk.

Pagpapanumbalik, at isang bitag sa mga inilathalang hakbang

Basahin ang opisyal na mga hakbang sa restore bago mo kailanganin ang mga ito, at basahin nang mabuti. Sa pagkakalathala noong August 2026, kinokopya ng mga ito ang file na affine.backup papunta sa container at pagkatapos ay nagre-restore mula sa ./pg.backup. Magkaibang pangalan ang mga ito. Tinatanggal din ng mga hakbang ang directory na ./postgres, samantalang pinapanatili ng kasalukuyang compose file ang data nito sa ./data/postgres. Simula 12 October 2026, ginagamit na ng page ang affine.backup sa buong dokumento at sinasabi nitong panatilihin ang lumang Postgres directory hanggang ma-verify ang restore. Naayos na upstream ang bitag, pero taglay pa rin ito ng kopya ng mga hakbang na na-save bago ang petsang iyon. Sa alinmang kaso, sundin ang mga path na aktuwal mong ginamit, hindi ang mga nasa snippet. Narito ang sequence para sa layout sa guide na ito:

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

Pansinin ang mv sa halip na rm. Kapag nag-restore ka sa database na wala kang kopya, maaaring mauwi ang isang maling command sa tuluyang pagkawala ng data. Wala namang gastos ang paglipat muna sa lumang directory sa ibang lokasyon. I-restore din ang uploads gamit ang tar xzf backup/storage-2026-08-08.tgz -C data, kung hindi, may broken attachments ang bawat dokumentong ire-render. Pagkatapos, mag-log in at magbukas ng dokumentong may image. Iyon ang test. Ang restore na hindi mo pa nabubuksan sa browser ay file lamang, hindi backup.

Paglalagay ng AFFiNE sa likod ng proxy na ginagamit mo na

Gumagamit ang AFFiNE ng WebSocket, at hindi ito optional. Malinaw itong sinasabi sa documentation: WebSocket ang batayan ng AFFiNE sync at collaboration system. Kaya kapag hindi nag-u-upgrade ng mga connection ang proxy, magkakaroon ka ng workspace kung saan tahimik na tumitigil ang pag-sync ng mga edit. Naglo-load ang page at gumagana ang login, pero hindi nakakarating sa kabilang browser ang edit na ginawa sa isang browser. Sa developer tools ng browser, buksan ang Network tab at i-filter ito sa WS. Kapag paulit-ulit na nagbubukas at nagsasara ang connection, hindi ipinapasa ng proxy ang upgrade.

Kung gumagamit ka na ng Traefik para sa ibang container, idagdag ang AFFiNE bilang normal na service. Tanggalin ang ports: block mula sa affine service, pagkatapos ay idagdag ang:

    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'

Sa ibaba ng file, kasabay ng services:, idagdag ang:

networks:
  proxy:
    external: true

Dapat tumugma ang pangalan ng certificate resolver sa nakatakda sa iyong Traefik configuration. Ang loadbalancer.server.port ay ang container port 3010, hindi host port. Awtomatikong ipinapasa ng Traefik ang mga WebSocket connection at wala nang karagdagang configuration na kailangan. Kung ang iba mong app ay nasa likod na ng Authentik para sa single sign-on, maaaring gumamit ng forward auth middleware sa router na ito upang kontrolin ang browser access sa AFFiNE. Iwan muna itong naka-disable hanggang masubukan mo ang desktop app, dahil wala itong browser session at basta na lang mabibigo ang sync. Ang pagpapatakbo ng maraming app sa iisang instance nito ay nakasaad sa isang Traefik sa harap ng maraming app.

Sa nginx, kailangan mong tahasang hilingin ang upgrade:

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;
}

Ang default na value ng client_max_body_size sa nginx ay 1 MB. Kung wala ang linyang iyon, mabibigo ang bawat upload na mas malaki sa maliit na larawan at magbabalik ito ng 413 status. Walang lalabas sa AFFiNE logs dahil hindi nakarating doon ang request. Isang linya lang ang kailangan sa Caddy, reverse_proxy http://127.0.0.1:3010, at awtomatiko nitong hina-handle ang certificates at WebSocket upgrades.

Mga hindi kasama sa self-hosted build

Maging tapat sa sarili tungkol dito bago mo ilipat ang isang team.

May real-time collaboration, at ito ang feature na pinagtutuunan ng lahat ng sizing advice, dahil ayon sa sariling documentation ng AFFiNE, nakadepende ang memory use sa sync system at sa document merging. Ang offline editing ang dahilan kung bakit gusto ng maraming tao ng local-first tool, at maaaring idagdag ng desktop application ang iyong self-hosted server sa workspace list nito at mag-login dito. Subukan muna ang eksaktong offline behaviour na kailangan ng team mo bago ka magpasya: mag-edit sa desktop app habang naka-off ang network, kumonekta muli, pagkatapos ay tingnan ang resulta sa ikalawang device. Hindi sapat na ebidensiya ang feature lists, at kabilang dito ang listahang ito.

Naka-off ang server-side full-text search sa shipped compose file, kung saan naka-set ang AFFINE_INDEXER_ENABLED=false sa server at sa migration job. Para i-on ito, kailangan mong magdagdag ng Manticore Search container, na magiging ikalimang service at mangangailangan ng mas maraming memory. Sa 2 GB na machine, ito ang pagbabagong magtutulak sa iyo lampas sa limitasyon. Gumagana pa rin ang search sa loob ng client para sa workspace na kasalukuyan mong binuksan.

May dalawang limitasyong dapat malaman bago ka mag-imbita ng mga tao. Ang isang self-hosted workspace ay maaaring magkaroon ng hanggang 10 seat lamang, at kailangan ng Team license mula sa AFFiNE kapag lalampas dito. Inilalarawan sa documentation na nakalaan para sa self-hosted instance ang unlimited blob storage at unlimited blob size, ngunit hindi pa ganap na implemented ang mga ito, batay sa pagsusuri noong October 2026. Hindi mahalaga ang alinman sa mga ito para sa isang household o maliit na team. Parehong mahalaga ang mga ito kung plano mong ilipat ang apatnapung tao.

Mga Upgrade

Basahin muna ang release notes, lalo na para sa minor version bump gaya ng 0.26 patungong 0.27, kung saan maaaring magkaroon ng breaking changes. Mag-back up ng database at storage directory bago gumawa ng anumang pagbabago, dahil binabago ng migration job ang schema sa susunod na start at walang undo. Pagkatapos, palitan ang pinned digest, patakbuhin ang docker compose pull na sinusundan ng docker compose up -d, at i-monitor ang docker compose logs -f affine_migration hanggang sa malinis itong matapos. Pagkatapos nito, nililinis ng docker image prune ang mga lumang layer. Isang historical note para sa mga gumagamit ng napakalumang install: mula sa version 0.23.0, nagbago ang image name mula affine-graphql tungo sa affine, kaya kailangang baguhin ang image lines sa compose file na mas luma rito bago may makita ang pull. Mula naman sa version 0.27.4, inilipat ng opisyal na compose template ang Postgres, upload, at configuration paths at binago ang default database connection, kaya ihambing ang bagong file sa kasalukuyan mong file sa halip na direktang ipalit ito sa gumaganang install.

FAQ

Bakit hindi kailanman nagsisimula ang AFFiNE container?

Idinedeklara ng affine service ang condition: service_completed_successfully sa affine_migration job. Kaya kung matatapos ang migration na may status na iba sa 0, hindi kailanman magsisimula ang server at walang lalabas na web interface. Patakbuhin ang docker compose logs affine_migration upang makita kung aling step ang huminto. Tiyaking ginagamit pa rin ng mano-manong in-edit na compose file ang pgvector/pgvector:pg16: walang kasamang pgvector extension ang stock Postgres, kahit idinedeklara pa rin ito ng schema ng AFFiNE, bagama't hindi na tinutukoy ng v0.27.4 ang apat na embedding model na nasa v0.27.3.

Gaano karaming RAM ang kailangan ng self-hosted AFFiNE?

Nangangailangan ang AFFiNE ng hindi bababa sa 4 CPU core at 2 GB RAM, ayon sa requirements page nito. Umaabot ito sa 4 GB kapag lumampas sa 10,000 salita ang mga dokumento. Nakatala rin doon na maaaring umabot sa 1 GB ang memorya kapag nag-merge ng dokumentong may 10,000 modification. Sa 2 GB server, ang peak na ito ang nagdudulot ng problema, hindi ang idle load: pumipili ang kernel out-of-memory killer ng prosesong ihihinto, at malamang na ang AFFiNE server dahil ito ang pinakamalaki. Pagkatapos, muli itong sinisimulan ng restart: unless-stopped, kaya page reload ang nakikita ng mga user sa halip na error. Kumpirmahin ito gamit ang docker inspect affine_server --format '{{.State.OOMKilled}}' at sudo dmesg -T | grep -i 'out of memory'. Pagkatapos, magdagdag ng 2 GB swap file bilang buffer laban sa maiikling memory spike. Lumipat sa 4 GB RAM kung nagpapatuloy ang mga paghinto.

Saan iniimbak ng AFFiNE ang data ko, at ano ang dapat kong i-back up?

Tatlong path sa ilalim ng compose directory ang naglalaman ng lahat: ./data/postgres para sa database, ./data/storage para sa mga uploaded file, at ./config para sa config.json at nabuong private.key. I-back up ang database gamit ang docker compose exec -T postgres pg_dump --format c --username affine affine > affine.dump sa halip na kopyahin ang mga file, dahil hindi ligtas kopyahin ang isang tumatakbong Postgres. Kasama rin sa dump ang anumang setting na na-save sa admin panel, dahil iniimbak ng AFFiNE ang mga ito sa database. I-tar ang ./data/storage para sa mga upload at panatilihin ang buong config directory, Compose file, at .env, dahil hindi bahagi ng database ang mga file na iyon.

Gumagana ba ang real-time collaboration sa self-hosted AFFiNE?

Oo, at walang kailangang i-enable para rito. Ang tanging requirement ay ang reverse proxy mo, dahil tumatakbo ang sync sa mga WebSocket connection. Sa nginx, nangangahulugan ito ng proxy_http_version 1.1 kasama ang Upgrade at Connection: upgrade headers. Ipinapasa naman ng Traefik at Caddy ang mga connection na ito nang walang karagdagang configuration. Ang palatandaan ng proxy na hindi nag-u-upgrade sa mga ito ay isang workspace na normal na naglo-load at nagla-login, pero hindi lumilitaw sa ibang browser ang mga edit na ginawa sa isang browser.

Maaari ko bang patakbuhin ang AFFiNE gamit ang stock Postgres image?

Gamitin ang pgvector/pgvector:pg16, na Postgres 16 na may naka-compile na pgvector extension. Idinedeklara pa rin ng AFFiNE v0.27.4 ang extensions = [pgvector(map: "vector")] sa schema.prisma, pero hindi na nito tinutukoy ang apat na model na may vector(1024) embedding column na nasa v0.27.3. Walang kasamang idineklarang extension ang stock Postgres. Kung ituturo mo sa external Postgres server ang AFFiNE, i-install ang pgvector dito at gawin ang extension sa target database bago patakbuhin ang migration.

Nakatulong ba ang artikulong ito?