SSD Nodes Learn Hosting plans →
가이드 Matt Connor작성자 Matt Connor

AFFiNE 직접 호스팅: Docker Compose 구축 가이드

Docker Compose를 사용하여 AFFiNE을 VPS에 직접 설치하는 방법을 설명합니다. 4개의 컨테이너 구성, 데이터 저장 경로, 2GB RAM 환경에서의 성능 제약 및 안정적인 백업 전략을 포함한 실무 가이드를 확인하여 Notion 대안을 직접 운영해 보시기 바랍니다.

AFFiNE을 직접 호스팅할 때 얻는 것

AFFiNE을 직접 호스팅하면 사용자가 제어하는 서버에서 Notion 스타일의 작업 공간을 운영할 수 있습니다. 이 환경은 애플리케이션, 일회성 마이그레이션 작업, Postgres, Redis라는 4개의 컨테이너로 구성됩니다. 실시간 협업 기능이 포함되어 있으며, 직접 호스팅하는 작업 공간은 기본적으로 최대 10개의 시트를 지원합니다. 설치는 하나의 compose 파일과 하나의 JSON 설정 파일로 이루어집니다. 이미지 태그, 디스크 레이아웃, 메모리 제한, 그리고 앞단에 배치할 프록시 설정에 대해 고려해야 합니다.

AFFiNE은 문서 편집기와 무한 캔버스를 동일한 작업 공간 내에 유지하므로, 하나의 페이지를 문서로 읽거나 화이트보드처럼 펼쳐서 볼 수 있습니다. 무엇을 실행할지 아직 결정하지 못했다면 먼저 직접 호스팅 가능한 Notion 대안 비교를 읽어보시기 바랍니다. 이 가이드는 이미 선택이 완료되었다고 가정하며, 비교보다는 AFFiNE을 올바르게 실행하는 방법에 중점을 둡니다.

여기에 기재된 모든 내용은 2026년 8월 8일 기준 AFFiNE 직접 호스팅 문서 및 공개된 릴리스 파일을 바탕으로 검증되었습니다. 해당 날짜의 최신 안정 버전은 2026년 7월 23일에 릴리스된 0.27.3입니다. 이후 날짜가 명시된 내용은 2026년 10월 12일에 1차 출처를 통해 재검증되었으며, 당시 최신 안정 버전은 2026년 8월 18일에 릴리스된 0.27.4였습니다.

네 개의 컨테이너가 수행하는 역할

affine은 서버와 웹 클라이언트를 하나의 이미지로 통합한 것입니다. 이 컨테이너는 3010 포트에서 대기합니다.

affine_migration은 node ./scripts/self-host-predeploy.js을 실행하고 데이터베이스 마이그레이션을 적용한 뒤 종료되는 일회성 작업입니다. 애플리케이션은 해당 작업에 condition: service_completed_successfully를 선언하므로, 마이그레이션이 0이 아닌 상태 코드로 종료되면 affine은 아예 시작되지 않습니다. 웹 인터페이스가 나타나지 않는다면 가장 먼저 해당 작업의 로그를 확인해야 합니다.

postgres은 문서, 사용자, 작업 공간 및 권한 정보를 보관합니다. 제공되는 이미지는 pgvector/pgvector:pg16이며, 이는 pgvector 확장 기능이 컴파일된 일반적인 Postgres 16입니다. pgvector는 Postgres에 vector 열 유형을 추가합니다. 이는 텍스트를 의미 기반으로 검색할 수 있도록 임베딩을 저장하는 데 사용되는 숫자 형식입니다.

redis는 필수 의존 요소입니다. 서버와 마이그레이션 작업 모두 이 컨테이너의 상태 확인이 완료될 때까지 대기한 후 시작됩니다. 제공된 compose 파일에서 Redis에 볼륨을 할당하지 않았다는 점에 주목하십시오. Redis 내부의 데이터는 docker compose down가 발생하면 모두 사라집니다. 이는 Redis가 사용자의 콘텐츠를 저장하지 않으며 백업이 필요 없음을 명확히 보여줍니다.

왜 기본 postgres가 아닌 pgvector 이미지를 사용하는가

이 요구 사항은 선호도가 아닌 AFFiNE의 스키마에서 비롯된 것입니다. v0.27.4 버전에서 schema.prisma는 여전히 extensions = [pgvector(map: "vector")]를 선언하지만, 임베딩 컬럼은 포함하지 않습니다. v0.27.3에서 vector(1024) 타입의 embedding 컬럼을 가졌던 4개의 모델은 v0.27.4에서 제외되었습니다. 제공된 pgvector/pgvector:pg16 이미지를 유지하십시오. 해당 확장은 여전히 선언되어 있으며, 기본 postgres:16 이미지에는 포함되어 있지 않기 때문입니다.

공식 v0.27.4 템플릿은 pgvector 이미지를 사용합니다. v0.21.0 템플릿은 여전히 postgres:16을 사용했습니다. 이전 설치 버전에서 이미지 라인만 수정하는 것으로는 업그레이드가 완료되지 않습니다. 따라서 이미지를 pull하기 전에 AFFiNE self-host docs의 업그레이드 페이지를 먼저 읽어보시기 바랍니다.

태그와 관련하여 한 가지 더 주의할 점이 있습니다. pg16는 Postgres 16을 의미하며, Postgres 메이저 버전은 임의로 올릴 수 있는 숫자가 아닙니다. 기존 데이터 디렉터리 위에서 pg17으로 변경하면 Postgres는 시작을 거부하며, docker compose logs postgres에 The data directory was initialized by PostgreSQL version 16, which is not compatible with this version 17와 같은 메시지가 기록됩니다. 메이저 버전 업그레이드는 PostgreSQL 17 릴리스 노트에 명시된 세 가지 방법 중 하나를 따라야 합니다. 새로운 데이터 디렉터리에 덤프 및 복원(dump and restore)을 수행하거나, pg_upgrade을 사용하거나, 논리적 복제(logical replication)를 수행해야 합니다. 단일 Compose 설치 환경에서는 pg_upgrade이 구버전과 신버전의 서버 바이너리를 동시에 요구하므로, 일반적으로 덤프 및 복원 방식이 가장 간단합니다.

자체 호스팅 AFFiNE은 CPU와 RAM을 얼마나 필요로 하는가

AFFiNE의 요구 사항 페이지에서는 최소 4개의 CPU 코어와 2 GB의 RAM을 권장하며, 문서가 10,000 단어를 넘어가면 메모리를 4 GB로 늘릴 것을 명시합니다. 같은 페이지에서 메모리가 사용되는 곳은 동기화 시스템과 문서 병합 과정이라고 설명합니다. 기억해야 할 중요한 수치는 10,000개의 수정 사항이 포함된 문서를 병합할 때 최대 1 GB의 메모리가 필요할 수 있다는 점입니다.

이제 2 GB 플랜에서 두 명의 사용자가 글을 쓰는 상황을 가정해 보겠습니다. 평균적인 사용량은 문제가 없습니다. Postgres와 Node 프로세스는 제한 범위 내에서 여유 있게 동작합니다. 문제는 최대 사용량입니다. 단일 대규모 병합 작업이 서버 메모리 사용량을 약 1 GB까지 치솟게 할 수 있으며, 스왑(swap)이 없는 2 GB 서버에서는 이 최대치와 Postgres 및 기타 상주 프로세스의 메모리 점유가 합쳐져 메모리가 고갈될 수 있습니다. 이때 커널의 OOM(out-of-memory) killer가 메모리를 확보하기 위해 프로세스를 강제 종료합니다. Docker 문서에 따르면 어떤 프로세스든 대상이 될 수 있지만, 가장 큰 프로세스인 AFFiNE 서버가 종료될 가능성이 높습니다.

AFFiNE 서버가 종료되면 동료 사용자는 오류 메시지를 보지 못합니다. restart: unless-stopped이 몇 초 만에 컨테이너를 다시 시작하기 때문에 페이지가 새로고침되는 현상만 경험하게 됩니다. 추측하지 말고 다음 명령어로 확인하십시오.

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

첫 번째 명령에서 true가 출력되거나, 두 번째 명령에서 node을 지목하는 Killed process 줄이 보인다면 버그가 아니라 메모리 부족 현상입니다. 양쪽 모두에서 해결책을 적용하십시오. 먼저 스왑을 추가하여 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

이제 free -h 명령을 실행하면 총 2.0Gi의 스왑이 보고되어야 합니다. 스왑은 AFFiNE을 빠르게 만드는 것이 아니며, 그런 용도도 아닙니다. 스왑은 일시적인 메모리 급증을 받아내는 공간이므로, 컨테이너가 죽는 대신 잠시 느려지는 현상으로 끝날 가능성을 높여줍니다. 이는 보증이 아닌 버퍼입니다. 해결책의 다른 한 축은 병합 시점에 Postgres가 애플리케이션에 필요한 공간까지 캐시로 점유하지 못하게 막는 것이며, 이는 Compose 서비스의 메모리 제한을 통해 수행합니다. 두 조치 이후에도 종료 현상이 계속된다면, AFFiNE 요구 사항 페이지에서 명시한 대로 더 큰 문서를 다루기 위해 4 GB의 서버 사양이 필요합니다.

스토리지 용량은 예측하기 훨씬 쉽습니다. 다음은 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가 필요합니다. 약 1,000 단어 분량의 문서 1,000개는 0.1 GB의 Postgres 데이터를 추가하며, 이는 거의 무시할 수 있는 수준입니다. 1,000개의 업로드 파일은 10 GB를 추가하며, 이것이 전체 데이터의 핵심입니다. 이 수치는 실제 운영 중인 인스턴스에서 측정한 값이 아니라 계획을 위한 참고 수치이므로, 절대적인 약속이 아닌 경향성으로 이해해야 합니다. 중요한 것은 데이터베이스는 작게 유지되고, 디스크 사용량은 업로드 파일이 결정한다는 점입니다.

직접 compose 파일을 작성하고 태그를 고정하십시오

문서화된 설치 방법은 curl -L -o docker-compose.yml https://github.com/toeverything/AFFiNE/releases/latest/download/docker-compose.yml을 사용하여 미리 만들어진 파일을 다운로드합니다. 이 방법도 작동하지만, 의존하기 전에 알아두어야 할 세부 사항이 있습니다. 2026년 8월 8일 기준으로 릴리스 0.27.3에 첨부된 파일은 여전히 ${UPLOAD_LOCATION}, ${CONFIG_LOCATION}, ${DB_DATA_LOCATION}를 사용하여 .env 파일에서 경로를 읽어왔습니다. 반면 문서 참조 페이지는 스토리지를 ./data 아래에, PostgreSQL 데이터를 ./data 아래에, 설정을 ./config 아래에 두는 새로운 레이아웃을 보여주었으며 .env는 전혀 필요하지 않았습니다. 릴리스 0.27.4에서 첨부 파일이 해당 레이아웃으로 변경되었으며, 2026년 10월 12일 기준으로 두 설정은 일치합니다. 이전 파일로 설치했다면 경로는 여전히 .env에서 가져오며, AFFiNE 업그레이드 페이지는 해당 설정을 유지하지 않고 compose 파일을 교체하면 빈 데이터 디렉터리로 Postgres가 시작될 수 있다고 경고합니다. 파일을 직접 작성하면 이러한 문제를 완전히 피할 수 있으며, 어차피 이미지를 고정하고 데이터베이스 비밀번호를 설정하려면 파일을 수정해야 합니다.

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}을 대신 입력해주므로, 지원 스레드에 붙여넣을 파일에 비밀번호가 노출되지 않습니다. 이 습관은 운영하는 모든 스택에서 유지할 가치가 있으며, 그 이유는 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

업스트림에서 제공하는 파일과 네 가지 차이점이 있으며, 각각 이유가 있습니다.

  • 127.0.0.1:3010:3010은 루프백 주소로만 포트를 게시합니다. 28.0.0 이전의 Docker 릴리스는 동일한 L2 세그먼트의 호스트가 로컬호스트로 게시된 포트에 접근할 수 있게 하며, 구성된 직접 라우팅은 루프백 게시에도 불구하고 컨테이너 포트를 노출할 수 있습니다. Docker 28.0.0 이상을 사용하고 설정 중에는 직접 라우팅을 비활성화하십시오. 업스트림의 '3010:3010'은 모든 인터페이스에 바인딩되며, 대부분의 VPS 이미지에서는 공용 인터페이스가 포함됩니다.
  • POSTGRES_HOST_AUTH_METHOD: trust는 제거되었고 대신 비밀번호가 설정되었습니다. 신뢰 인증(Trust authentication)은 해당 데이터베이스에 대한 모든 연결을 비밀번호 없이 affine 사용자로 허용합니다. 이는 사설 Compose 네트워크로 제한되지만, 해당 네트워크에 컨테이너를 하나 더 추가하거나 디버깅 중에 5432 포트를 게시하는 날에는 문제가 될 수 있습니다.
  • redis:8-alpine는 단순한 redis를 대체하며, 이는 latest으로 해석됩니다. 2026년 8월 기준으로 이는 Redis 8이므로, 태그를 고정하면 테스트한 메이저 버전을 유지할 수 있고 관련 없는 docker compose pull 중에 미래의 Redis 9가 설치되는 것을 방지합니다.
  • pgvector/pgvector:pg16은 위에서 언급한 이유로 업스트림 설정 그대로 유지됩니다.

POSTGRES_PASSWORD는 Postgres가 처음으로 데이터 디렉터리를 생성할 때만 읽힙니다. 이미 존재하는 인스턴스에서는 docker compose exec postgres psql -U affine -c "ALTER USER affine WITH PASSWORD 'yourpassword'"으로 비밀번호를 설정한 다음 DATABASE_URL을 일치하도록 업데이트하십시오.

설정은 config/config.json에 위치합니다

AFFiNE은 /root/.affine/config에 마운트한 디렉터리 내의 config/config.json에서 설정을 읽어옵니다. 이 파일은 자동으로 생성되지 않으므로 첫 실행 전에 직접 작성해야 합니다. ~/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은 사용자가 직접 키를 입력하는 옵션으로, 워크스페이스 소유자가 자신의 모델 제공자 키를 워크스페이스 설정에 입력할 수 있게 합니다. AFFiNE을 직접 호스팅하는 경우 AI 구독은 포함되어 있지 않습니다. 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 short hash가 붙는 태그는 그렇지 않습니다. stable 상태로 두면, 6개월 뒤에 실행하는 docker compose pull은(는) 다른 이미지를 가져와 사용자가 의도하지 않은 시점에 데이터베이스 마이그레이션을 수행하게 됩니다. 테스트를 마친 정확한 이미지를 고정하십시오.

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

이 명령은 ghcr.io/toeverything/affine@sha256: 뒤에 긴 해시가 붙은 형태의 문자열을 출력합니다. 전체 문자열을 복사하여 affine과(와) affine_migration 모두의 image: 줄에 붙여넣으십시오. 이 두 파일은 동일한 이미지가 두 가지 역할을 수행하므로 항상 일치해야 합니다. 일치하지 않으면 한쪽 스키마로 데이터베이스를 마이그레이션하는 동안 다른 쪽 스키마로 서비스를 제공하는 상황이 발생합니다. 업그레이드는 예기치 않은 상황이 아닌 의도적인 편집이 되어야 합니다. 다이제스트를 변경하고, 백업을 수행한 뒤, 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를 엽니다. 등록 및 로그인을 마친 후 터널을 종료하십시오. 이제 인스턴스를 공개 도메인에 연결해도 안전합니다. 다른 셀프 호스팅 애플리케이션에서도 동일한 경쟁 상태가 발생하며, 첫 로그인 시 호스트 이름에 종속된 패스키가 생성되는 경우에는 더 위험합니다. 이것이 바로 openGym 셀프 호스팅을 할 때 첫 계정을 만들기 전에 TLS와 최종 도메인 설정을 완료해야 하는 이유입니다.

AFFiNE의 데이터 저장 위치

세 개의 경로에 모든 데이터가 저장되며, 이들은 모두 사용자가 생성한 디렉터리 내부에 위치합니다.

  • ./data/postgres는 Postgres 데이터 디렉터리입니다. 문서, 사용자, 워크스페이스, 권한 및 관리자 패널에서 저장된 모든 서버 설정이 포함됩니다.
  • ./data/storage은 컨테이너 내부의 /root/.affine/storage 경로에 마운트되며, 업로드된 모든 파일을 보관합니다.
  • ./config은 /root/.affine/config에 마운트되며, config.json 및 마이그레이션 작업으로 생성된 private.key을 보관합니다.

Upstream은 네임드 볼륨 대신 바인드 마운트를 사용하며, 이는 의도적인 선택입니다. Docker가 데이터를 어디에 저장했는지 확인할 필요 없이 일반적인 명령어로 해당 경로를 tar로 묶어 복사할 수 있기 때문입니다. 대신 호스트 시스템에서의 파일 소유권 관리는 사용자의 몫이 되며, 이에 대한 자세한 내용은 바인드 마운트와 네임드 볼륨에서 다룹니다.

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 출력에서 크기를 확인하십시오. 수백 바이트 정도의 파일은 덤프가 실패했음에도 셸이 파일을 생성한 경우이며, 이는 6개월 뒤에야 발견하게 되는 흔한 실패 사례입니다. -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만 복사하면 해당 파일이 누락됩니다. 관리자 패널에서 저장한 설정은 데이터베이스에 저장되므로 위에서 수행한 덤프에 이미 포함되어 있습니다. 2026년 10월 12일 기준으로 AFFiNE의 백업 페이지에 따르면 수정된 서버 설정은 관리자 패널에서 별도로 내보낼 수도 있습니다. 세 가지 파일을 모두 서버 외부로 복사하십시오. 보호 대상과 동일한 디스크에 저장된 백업은 진정한 백업이 아닙니다. 데이터베이스 덤프와 업로드 디렉터리의 tar 파일을 분리하여 관리하는 방식은 상태를 유지하는 모든 컨테이너에 적용해야 하는 패턴입니다. 이 방식은 대화 기록과 첨부 파일을 안전하게 보관하는 방법이며, 지원 데스크로 Chatwoot을 직접 호스팅할 때도 동일하게 적용됩니다.

복구 및 게시된 단계의 함정

복구 단계가 필요해지기 전에 공식 복구 절차를 미리 읽어두고, 내용을 꼼꼼히 확인하십시오. 2026년 8월에 게시된 문서에서는 affine.backup이라는 파일을 컨테이너로 복사한 뒤 ./pg.backup에서 복구를 수행하도록 안내했는데, 이는 서로 다른 이름입니다. 또한 당시 문서에서는 ./postgres 디렉터리를 삭제하라고 했으나, 현재의 compose 파일은 데이터를 ./data/postgres에 보관합니다. 2026년 10월 12일 기준으로 해당 페이지는 전체적으로 affine.backup를 사용하며, 복구가 검증될 때까지 기존 Postgres 디렉터리를 유지하라고 안내하고 있습니다. 즉, 상위 문서의 함정은 수정되었으나, 그 이전에 저장된 단계별 가이드에는 여전히 오류가 포함되어 있을 수 있습니다. 어떤 경우든 문서의 코드 조각에 적힌 경로를 그대로 따르지 말고, 본인이 실제로 사용한 경로를 따라야 합니다. 이 가이드의 레이아웃을 기준으로 한 순서는 다음과 같습니다.

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

rm이 아닌 mv를 사용한다는 점에 유의하십시오. 사본을 보관하지 않은 상태에서 데이터베이스를 덮어쓰며 복구하는 것은 잘못된 명령어 하나로 모든 데이터를 영구히 손실하게 만드는 원인이 됩니다. 기존 디렉터리를 다른 곳으로 옮겨두는 데는 비용이 들지 않습니다. 업로드 파일도 tar xzf backup/storage-2026-08-08.tgz -C data을 사용하여 함께 복구하십시오. 그렇지 않으면 모든 문서에서 첨부 파일이 깨진 상태로 표시됩니다. 복구 후에는 로그인하여 이미지가 포함된 문서를 열어보십시오. 이것이 테스트입니다. 브라우저에서 열어보지 않은 복구본은 백업이 아니라 단순한 파일일 뿐입니다.

AFFiNE을 기존 프록시 뒤에 배치하기

AFFiNE은 WebSocket을 사용하며, 이는 선택 사항이 아닙니다. 문서에 명시된 바와 같이 WebSocket은 AFFiNE 동기화 및 협업 시스템의 기반이므로, 해당 연결을 업그레이드하지 않는 프록시를 사용하면 편집 내용이 동기화되지 않는 작업 공간이 생성됩니다. 페이지 로드와 로그인은 정상적으로 작동하지만, 한 브라우저에서 수행한 편집 내용이 다른 브라우저에 도달하지 않습니다. 브라우저의 개발자 도구에서 Network 탭을 열고 WS로 필터링하십시오. 연결이 반복적으로 열리고 닫힌다면 프록시가 업그레이드 요청을 전달하지 못하는 것입니다.

이미 다른 컨테이너를 위해 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 미들웨어를 설정하여 AFFiNE에 대한 브라우저 접근을 제어할 수 있습니다. 다만 데스크톱 앱은 브라우저 세션을 공유하지 않아 동기화에 실패할 수 있으므로, 테스트가 완료될 때까지는 이 설정을 비활성화해 두십시오. 하나의 인스턴스 뒤에서 여러 앱을 운영하는 방법은 여러 앱 앞단의 단일 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 업그레이드를 자동으로 처리합니다.

자체 호스팅 빌드에서 제외된 기능

팀을 이주시키기 전에 이 점을 스스로 솔직하게 검토해야 합니다.

실시간 협업 기능은 포함되어 있으며, 모든 규모 산정 조언이 이 기능을 기준으로 합니다. AFFiNE의 자체 문서에서도 메모리 사용량의 원인을 동기화 시스템과 문서 병합으로 돌리고 있기 때문입니다. 오프라인 편집은 많은 사용자가 로컬 우선 도구를 원하는 이유이며, 데스크톱 애플리케이션은 자체 호스팅 서버를 워크스페이스 목록에 추가하고 로그인할 수 있게 합니다. 팀이 의존하는 정확한 오프라인 동작을 확정하기 전에 반드시 테스트하십시오. 네트워크를 끈 상태에서 데스크톱 앱으로 편집하고, 다시 연결한 뒤 두 번째 기기에서 결과를 확인하십시오. 기능 목록은 증거가 될 수 없으며, 이 목록 또한 마찬가지입니다.

서버 측 전문 검색(full-text search)은 제공되는 compose 파일에서 꺼져 있으며, 서버와 마이그레이션 작업에 AFFINE_INDEXER_ENABLED=false이 설정되어 있습니다. 이 기능을 켜려면 Manticore Search 컨테이너를 추가해야 하는데, 이는 다섯 번째 서비스가 되어 메모리 사용량을 늘립니다. 2 GB 서버 환경에서는 이 변경이 한계치를 넘게 만드는 요인이 됩니다. 클라이언트 내부의 검색 기능은 현재 열려 있는 워크스페이스에서 여전히 작동합니다.

사용자를 초대하기 전에 알아두어야 할 두 가지 제한 사항이 있습니다. 자체 호스팅 워크스페이스는 최대 10개의 좌석(seat)만 허용되며, 이를 초과하려면 AFFiNE의 Team 라이선스가 필요합니다. 자체 호스팅 인스턴스를 위한 무제한 블롭(blob) 저장소와 무제한 블롭 크기는 문서상으로는 의도된 기능이나 2026년 10월 확인 시점까지 완전히 구현되지 않았습니다. 가정이나 소규모 팀에는 문제가 되지 않지만, 40명 규모의 인원을 이주시키려는 계획이라면 두 가지 모두 중요한 고려 사항입니다.

업그레이드

업그레이드 전 릴리스 노트를 먼저 읽어야 합니다. 특히 0.26에서 0.27로 넘어가는 것과 같은 마이너 버전 업데이트 시에는 호환성이 깨지는 변경 사항이 포함될 수 있습니다. 작업을 시작하기 전에 데이터베이스와 스토리지 디렉터리를 반드시 백업하십시오. 다음 시작 시 마이그레이션 작업이 스키마를 변경하며, 이는 되돌릴 수 없기 때문입니다. 그 후 고정된 다이제스트(pinned digest)를 변경하고 docker compose pull를 실행한 뒤 docker compose up -d을 수행하십시오. docker compose logs -f affine_migration이 정상적으로 종료될 때까지 상태를 모니터링하십시오. 작업이 완료되면 docker image prune를 사용하여 이전 레이어를 정리할 수 있습니다. 아주 오래된 버전을 사용하는 경우를 위한 참고 사항으로, 0.23.0 버전부터 이미지 이름이 affine-graphql에서 affine로 변경되었습니다. 따라서 그보다 이전의 compose 파일을 사용하는 경우, 이미지를 pull 하기 전에 해당 파일의 image 항목을 수정해야 합니다. 또한 0.27.4 버전부터 공식 compose 템플릿의 Postgres, 업로드 및 설정 경로가 변경되었으며 기본 데이터베이스 연결 방식도 바뀌었습니다. 따라서 기존에 정상 작동 중인 설치 환경에 새 파일을 덮어쓰지 말고, 기존 파일과 새 파일을 비교하여 수정하십시오.

FAQ

AFFiNE 컨테이너가 시작되지 않는 이유는 무엇입니까?

affine 서비스는 affine_migration 작업에 condition: service_completed_successfully를 선언합니다. 따라서 마이그레이션이 0이 아닌 상태로 종료되면 서버는 시작되지 않으며 웹 인터페이스도 전혀 나타나지 않습니다. docker compose logs affine_migration을 실행하여 어느 단계에서 중단되었는지 확인하십시오. 직접 수정한 compose 파일이 여전히 pgvector/pgvector:pg16를 사용하는지 확인하십시오. v0.27.4 버전에서는 v0.27.3에 있던 4개의 임베딩 모델을 더 이상 정의하지 않지만, AFFiNE 스키마는 여전히 pgvector 확장을 선언하므로 기본 Postgres 이미지로는 작동하지 않습니다.

자체 호스팅 AFFiNE에는 어느 정도의 RAM이 필요합니까?

AFFiNE 요구 사항 페이지에서는 최소 4개의 CPU 코어와 2 GB의 RAM을 권장하며, 문서가 10,000 단어를 넘어가면 4 GB로 늘릴 것을 명시합니다. 또한 10,000개의 수정 사항이 포함된 문서를 병합할 때 최대 1 GB의 메모리가 소모될 수 있다고 언급합니다. 2 GB 서버에서는 유휴 상태의 부하가 아니라 이러한 순간적인 피크가 문제를 일으킵니다. 커널의 OOM(Out-of-Memory) 킬러가 가장 큰 프로세스인 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.json 및 생성된 private.key을 위한 ./config입니다. 실행 중인 Postgres 파일을 직접 복사하는 것은 안전하지 않으므로, docker compose exec -T postgres pg_dump --format c --username affine affine > affine.dump을 사용하여 데이터베이스를 백업하십시오. 이 덤프 파일에는 AFFiNE이 데이터베이스에 저장하는 관리자 패널 설정도 포함됩니다. 업로드 파일은 ./data/storage를 tar로 압축하고, 전체 config 디렉터리, Compose 파일 및 .env를 보관하십시오. 이 파일들은 데이터베이스에 포함되지 않기 때문입니다.

자체 호스팅 AFFiNE에서 실시간 협업이 작동합니까?

네, 별도의 활성화 설정은 필요 없습니다. 단, 동기화가 WebSocket 연결을 통해 이루어지므로 리버스 프록시 설정이 필수입니다. nginx의 경우 proxy_http_version 1.1와 함께 Upgrade 및 Connection: upgrade 헤더가 필요하며, Traefik과 Caddy는 별도의 설정 없이도 해당 연결을 통과시킵니다. 프록시가 연결을 업그레이드하지 못하면 워크스페이스 로드와 로그인은 정상적으로 수행되지만, 한 브라우저에서 수행한 편집 내용이 다른 브라우저에 나타나지 않는 증상이 발생합니다.

기본 Postgres 이미지를 사용하여 AFFiNE을 실행할 수 있습니까?

pgvector 확장이 포함된 Postgres 16인 pgvector/pgvector:pg16을 사용하십시오. AFFiNE v0.27.4는 여전히 schema.prisma에서 extensions = [pgvector(map: "vector")]를 선언하지만, v0.27.3에 있던 vector(1024) 임베딩 컬럼을 가진 4개의 모델은 더 이상 정의하지 않습니다. 기본 Postgres 이미지에는 선언된 확장이 포함되어 있지 않습니다. 외부 Postgres 서버를 사용하는 경우, 마이그레이션을 실행하기 전에 해당 서버에 pgvector를 설치하고 대상 데이터베이스에 확장을 생성하십시오.

이 글이 도움이 되었나요?