SSD Nodes Learn Hosting plans →
راهنماها Matt Connorتوسط Matt Connor

آموزش نصب و میزبانی شخصی AFFiNE با Docker Compose

راهنمای کامل اجرای AFFiNE روی سرور شخصی با استفاده از 4 کانتینر. نحوه پیکربندی Postgres و Redis، مدیریت فایل‌های داده، تگ‌های ثابت image و بررسی عملکرد با 2 گیگابایت رم.

آنچه با میزبانی شخصی AFFiNE به دست می‌آورید

میزبانی شخصی AFFiNE به شما یک فضای کاری به سبک Notion روی سروری که تحت کنترل خودتان است می‌دهد که در قالب چهار کانتینر اجرا می‌شود: برنامه اصلی، یک job برای مهاجرت داده، Postgres و Redis. قابلیت همکاری بلادرنگ (real-time) گنجانده شده است و تا 10 کاربر به‌صورت پیش‌فرض در فضای کاری میزبانی‌شده شخصی پشتیبانی می‌شوند. نصب شامل یک فایل compose و یک فایل پیکربندی JSON است. آنچه نیاز به بررسی دقیق دارد، تگ‌های image، ساختار دیسک، سقف حافظه و پروکسی است که در مقابل آن قرار می‌دهید.

AFFiNE یک ویرایشگر سند و یک بوم بی‌نهایت را در یک فضای کاری واحد نگه می‌دارد، بنابراین یک صفحه می‌تواند هم به‌عنوان سند خوانده شود و هم به‌عنوان تخته‌سفید گسترش یابد. اگر هنوز در حال تصمیم‌گیری برای انتخاب نرم‌افزار هستید، ابتدا مقایسه جایگزین‌های Notion برای میزبانی شخصی را مطالعه کنید. این راهنما فرض را بر این می‌گذارد که انتخاب انجام شده است و به‌جای مقایسه مجدد، بر اجرای صحیح AFFiNE تمرکز دارد.

تمام مطالب اینجا با مستندات میزبانی شخصی AFFiNE و فایل‌های منتشرشده در تاریخ 8 August 2026 مطابقت داده شده است. جدیدترین نسخه پایدار در آن تاریخ 0.27.3 بود که در 23 July 2026 منتشر شد. ادعاهای زیر که تاریخ متأخرتری دارند، در تاریخ 12 October 2026 مجدداً با منابع اصلی بررسی شدند؛ زمانی که جدیدترین نسخه پایدار 0.27.4 بود که در 18 August 2026 منتشر شده بود.

عملکرد چهار کانتینر

affine شامل سرور و کلاینت وب در یک ایمیج واحد است. این سرویس روی پورت 3010 گوش می‌دهد.

affine_migration یک job یک‌بار‌اجرا (one-shot) است که node ./scripts/self-host-predeploy.js را اجرا کرده، مهاجرت‌های دیتابیس (migrations) را اعمال می‌کند و سپس خارج می‌شود. اپلیکیشن برای آن job، یک condition: service_completed_successfully تعریف کرده است؛ بنابراین اگر عملیات مهاجرت با وضعیتی غیر از صفر (non-zero) پایان یابد، affine هرگز شروع نخواهد شد. زمانی که رابط وب بالا نمی‌آید، لاگ این job اولین چیزی است که باید بررسی کنید.

postgres اسناد، کاربران، محیط‌های کاری و دسترسی‌های شما را نگهداری می‌کند. ایمیج ارائه‌شده pgvector/pgvector:pg16 است که در واقع همان Postgres 16 معمولی به همراه افزونه pgvector است که در آن کامپایل شده. pgvector یک نوع ستون vector به Postgres اضافه می‌کند؛ فرمت عددی که برای ذخیره embeddingها استفاده می‌شود تا بتوان متن را بر اساس مفهوم جستجو کرد.

redis یک وابستگی حیاتی (hard dependency) است: هم سرور و هم job مهاجرت، پیش از شروع کار منتظر بررسی سلامت (health check) آن می‌مانند. توجه کنید که فایل compose ارائه‌شده برای Redis هیچ volumeای تعریف نکرده است. هیچ داده‌ای در آن پس از یک docker compose down باقی نمی‌ماند و این به‌وضوح نشان می‌دهد که Redis هیچ محتوایی از شما را در خود نگه نمی‌دارد و نیازی به پشتیبان‌گیری ندارد.

چرا ایمیج Postgres از نوع pgvector است و نه نسخه استاندارد postgres

این الزام از طرح (schema) برنامه AFFiNE ناشی می‌شود و نه یک انتخاب سلیقه‌ای. در نسخه v0.27.4، مقدار schema.prisma همچنان extensions = [pgvector(map: "vector")] را اعلام می‌کند، اما فاقد ستون‌های embedding است. چهار مدلی که در نسخه v0.27.3 دارای ستون‌های embedding با نوع vector(1024) بودند، در نسخه v0.27.4 وجود ندارند. از همان ایمیج pgvector/pgvector:pg16 ارائه‌شده استفاده کنید: افزونه (extension) همچنان اعلام می‌شود و نسخه استاندارد postgres:16 آن را شامل نمی‌شود.

قالب رسمی v0.27.4 از ایمیج pgvector استفاده می‌کند؛ در حالی که قالب v0.21.0 همچنان از postgres:16 استفاده می‌کرد. در یک نصب قدیمی، صرفاً ویرایش خط مربوط به ایمیج برای ارتقا کافی نیست، بنابراین پیش از دریافت هر فایلی، صفحه ارتقا را در مستندات self-host برنامه AFFiNE مطالعه کنید.

یک نکته دیگر درباره آن تگ: pg16 به معنای Postgres 16 است و نسخه اصلی (major version) دیتابیس عددی نیست که بتوانید آن را به سادگی افزایش دهید. اگر آن را روی یک دایرکتوری داده موجود به pg17 تغییر دهید، Postgres از اجرا خودداری می‌کند و خطایی مشابه The data directory was initialized by PostgreSQL version 16, which is not compatible with this version 17 در docker compose logs postgres ثبت می‌شود. تغییر نسخه اصلی نیازمند یکی از سه روشی است که در یادداشت‌های انتشار PostgreSQL 17 ذکر شده است: گرفتن dump و بازیابی (restore) آن در یک دایرکتوری داده جدید، استفاده از pg_upgrade، یا replication منطقی. در یک نصب تک‌سرور با Compose، معمولاً روش dump و restore ساده‌ترین راه است، زیرا pg_upgrade نیازمند حضور همزمان باینری‌های سرور قدیمی و جدید در کنار یکدیگر است.

میزان CPU و RAM مورد نیاز برای AFFiNE به صورت self-hosted چقدر است

صفحه نیازمندی‌های AFFiNE حداقل 4 هسته CPU و 2 گیگابایت RAM را توصیه می‌کند و در صورتی که تعداد کلمات اسناد شما از 10,000 کلمه فراتر رود، این مقدار حافظه را به 4 گیگابایت افزایش می‌دهد. همان صفحه توضیح می‌دهد که این حافظه صرف چه مواردی می‌شود: سیستم همگام‌سازی (sync) و ادغام اسناد (document merging). یک عدد در این میان ارزش به‌خاطر سپردن دارد: ادغام سندی با 10,000 تغییر می‌تواند به اوج مصرف 1 گیگابایت حافظه برسد.

حال این موضوع را در کنار یک پلن 2 گیگابایتی با دو کاربر در حال نوشتن در نظر بگیرید. در حالت عادی مشکلی وجود ندارد. Postgres و پروسه Node زیر حد مجاز باقی می‌مانند و فضای خالی نیز وجود دارد. مشکل در زمان اوج مصرف (peak) رخ می‌دهد. یک ادغام بزرگ می‌تواند مصرف حافظه سرور را به حدود 1 گیگابایت برساند و در یک سرور 2 گیگابایتی بدون swap، این اوج مصرف به همراه Postgres و سایر پروسه‌های مقیم در حافظه، می‌تواند کل RAM را اشغال کند. در این حالت، مکانیزم out-of-memory (OOM) killer در هسته سیستم‌عامل، یک پروسه را برای آزاد کردن حافظه می‌کشد. سرور 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 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 فضای swap را گزارش کند. Swap باعث سریع‌تر شدن AFFiNE نمی‌شود و هدف آن نیز این نیست. Swap به پیک‌های لحظه‌ای فضایی برای قرارگیری می‌دهد، بنابراین احتمال اینکه یک پیک مصرف باعث یک ثانیه کندی شود بسیار بیشتر از آن است که منجر به مرگ کانتینر شود. این یک بافر است، نه یک تضمین. طرف دیگر راهکار این است که جلوی رشد کش Postgres در فضایی که برنامه در زمان ادغام به آن نیاز دارد را بگیرید؛ این همان کاری است که محدودیت‌های حافظه در یک سرویس Compose برای آن طراحی شده‌اند. اگر پس از انجام هر دو مورد، کشتن پروسه‌ها ادامه یافت، سرور به همان 4 گیگابایت RAM نیاز دارد که صفحه نیازمندی‌های 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 گیگابایت فضا اشغال می‌کند. هزار سند که هر کدام تقریباً هزار کلمه دارند، 0.1 گیگابایت به داده‌های Postgres اضافه می‌کنند که تقریباً ناچیز است. هزار فایل آپلود شده، 10 گیگابایت اضافه می‌کنند که کل داستان همین است. این‌ها ارقام برنامه‌ریزی‌شده هستند و نه اندازه‌گیری‌های دقیق از یک نمونه در حال اجرا، بنابراین آن‌ها را به عنوان یک الگوی کلی در نظر بگیرید، نه یک وعده قطعی. الگو همان چیزی است که اهمیت دارد: دیتابیس شما کوچک می‌ماند و فایل‌های آپلود شده تعیین‌کننده میزان مصرف دیسک شما هستند.

فایل compose را خودتان بنویسید و تگ‌ها را ثابت کنید

نصب مستندشده، یک فایل آماده را با curl -L -o docker-compose.yml https://github.com/toeverything/AFFiNE/releases/latest/download/docker-compose.yml دانلود می‌کند. این روش کار می‌کند. پیش از تکیه بر آن، دانستن یک نکته ارزشمند است: تا تاریخ 8 August 2026، فایل پیوست‌شده به نسخه 0.27.3 همچنان مسیرهای خود را از یک فایل .env و با استفاده از ${UPLOAD_LOCATION}، ${CONFIG_LOCATION} و ${DB_DATA_LOCATION} می‌خواند، در حالی که صفحه مرجع مستندات، چیدمان جدیدتری را نشان می‌داد که ذخیره‌سازی و داده‌های PostgreSQL را در ./data قرار می‌دهد، پیکربندی را در ./config نگه می‌دارد و اصلاً نیازی به .env ندارد. نسخه 0.27.4 فایل پیوست‌شده را به آن چیدمان منتقل کرد و تا تاریخ 12 October 2026، این دو با هم همخوانی دارند. اگر از فایل قدیمی‌تر نصب کرده‌اید، مسیرهای شما همچنان از .env می‌آیند و صفحه ارتقای AFFiNE هشدار می‌دهد که جایگزینی فایل compose بدون انتقال آن تنظیمات، می‌تواند Postgres را با یک دایرکتوری داده خالی راه‌اندازی کند. نوشتن فایل توسط خودتان، این مسئله را به‌طور کامل برطرف می‌کند و به‌هرحال برای ثابت کردن (pin) ایمیج‌ها و تعیین رمز عبور دیتابیس، باید آن را ویرایش کنید.

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} را برای شما جایگزین می‌کند، بنابراین رمز عبور هرگز در فایلی که ممکن است در یک انجمن پشتیبانی کپی کنید، ظاهر نمی‌شود. این عادت برای تمام پشته‌هایی (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

این فایل چهار تفاوت با فایلی که توسعه‌دهنده اصلی ارائه می‌دهد دارد و هر کدام دلیلی دارند.

  • 127.0.0.1:3010:3010 پورت را فقط روی آدرس loopback منتشر می‌کند. نسخه‌های Docker پیش از 28.0.0 به میزبان‌های موجود در همان سگمنت L2 اجازه می‌دهند به پورت‌های منتشرشده روی localhost دسترسی پیدا کنند و مسیریابی مستقیم پیکربندی‌شده می‌تواند پورت کانتینر را با وجود انتشار روی loopback، در معرض دید قرار دهد. از Docker 28.0.0 یا جدیدتر استفاده کنید و مسیریابی مستقیم را در طول راه‌اندازی غیرفعال نگه دارید. فایل '3010:3010' اصلی، تمام اینترفیس‌ها را bind می‌کند و در اکثر ایمیج‌های VPS، این شامل اینترفیس عمومی نیز می‌شود.
  • POSTGRES_HOST_AUTH_METHOD: trust حذف شده و به‌جای آن رمز عبور تعیین شده است. احراز هویت Trust، هر اتصالی به آن دیتابیس را به‌عنوان کاربر affine بدون رمز عبور می‌پذیرد. این محدود به شبکه خصوصی Compose است که تا زمانی که یک کانتینر دیگر به آن شبکه متصل نکنید یا پورت 5432 را هنگام دیباگ کردن منتشر نکنید، مشکلی ایجاد نمی‌کند.
  • redis:8-alpine جایگزین یک redis ساده شده است که به latest ترجمه می‌شود. تا August 2026، این نسخه Redis 8 است، بنابراین ثابت کردن (pin) آن باعث می‌شود نسخه اصلی که تست کرده‌اید حفظ شود و از ورود ناگهانی Redis 9 در طول یک docker compose pull نامرتبط جلوگیری شود.
  • 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 تنظیمات خود را از 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 لینک‌های اشتراک‌گذاری و دعوت‌نامه‌های فضای کاری (workspace) را بر اساس این مقدار می‌سازد؛ بنابراین اگر آن را روی http://localhost:3010 رها کنید، دعوت‌نامه‌ای که ارسال می‌کنید گیرنده را به ماشین خودش هدایت می‌کند و در آنجا با خطا مواجه می‌شود. پیش از اولین اجرا، آن را روی آدرس عمومی HTTPS تنظیم کنید تا فایل و پنل مدیریت هرگز در این مورد اختلاف نداشته باشند. تنظیماتی که بعداً در پنل مدیریت تغییر می‌دهید در دیتابیس ذخیره می‌شوند و در این فایل بازنویسی نخواهند شد.

گزینه copilot قابلیت‌های هوش مصنوعی را کنترل می‌کند. copilot.byok.enabled سوئیچی برای استفاده از کلید شخصی (bring-your-own-key) است که به مالک فضای کاری اجازه می‌دهد کلید ارائه‌دهنده مدل خود را در تنظیمات فضای کاری وارد کند. میزبانی شخصی (self-hosting) AFFiNE شامل اشتراک هوش مصنوعی نیست. اگر به آن نیازی ندارید، هر دو را روی 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 فقط کانتینرهای در حال اجرا را نشان می‌دهد و در نتیجه، یک job مهاجرت که با موفقیت به پایان رسیده است اصلاً نمایش داده نمی‌شود. هر کد خروجی دیگری در job مهاجرت، همان موردی است که باید بررسی شود و لاگ آن، مرحله‌ای که متوقف شده را مشخص می‌کند:

docker compose logs affine_migration

تصویر را پیش از فراموشی ثابت (Pin) کنید

stable یک تگ متغیر است. گردش کار انتشار AFFiNE چندین تگ را به هر بیلد پایدار اشاره می‌دهد که دو مورد از آن‌ها در اینجا اهمیت دارند: stable که در هر انتشار تغییر می‌کند، و stable- که به دنبال آن هش کوتاه git می‌آید و تغییر نمی‌کند. اگر روی stable باقی بمانید، یک docker compose pull در شش ماه آینده تصویر متفاوتی را دریافت کرده و migrationهای آن را در زمانی که شما انتخاب نکرده‌اید روی دیتابیس اجرا می‌کند. دقیقاً همان تصویری را که تست کرده‌اید ثابت کنید:

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

این دستور خطی مانند ghcr.io/toeverything/affine@sha256: و به دنبال آن یک هش طولانی چاپ می‌کند. کل رشته را در خط image: در هر دو فایل affine و affine_migration کپی کنید. این دو فایل همیشه باید با هم مطابقت داشته باشند، زیرا آن‌ها یک تصویر واحد هستند که دو نقش را ایفا می‌کنند؛ عدم تطابق به معنای migration دیتابیس به یک طرح (schema) و سرویس‌دهی با طرحی دیگر است. در این صورت، ارتقا یک ویرایش آگاهانه خواهد بود نه یک غافلگیری: digest را تغییر دهید، نسخه پشتیبان تهیه کنید، سپس docker compose pull و docker compose up -d را اجرا کنید.

پیش از هر کس دیگری، حساب کاربری مدیر را ایجاد کنید

هنگامی که برای نخستین بار /admin را روی یک نمونه تازه باز می‌کنید، AFFiNE شما را به صفحه ایجاد حساب کاربری هدایت می‌کند، زیرا سرور هنوز هیچ مدیر (administrator) ندارد. در این فرآیند، هیچ کد دعوت یا توکن راه‌اندازی وجود ندارد. اولین کسی که ثبت‌نام را تکمیل کند، مدیر سرور شما خواهد شد؛ بنابراین تا زمانی که ثبت‌نام نکرده‌اید، پورت باید بسته بماند.

به همین دلیل است که فایل compose در بالا به 127.0.0.1 متصل می‌شود. از طریق یک SSH tunnel از دستگاه خود به آن دسترسی پیدا کنید:

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

آن را در حال اجرا بگذارید و http://127.0.0.1:3010/admin را در مرورگر محلی خود باز کنید. ثبت‌نام کرده و وارد شوید، سپس tunnel را ببندید. تنها در این صورت است که قرار دادن نمونه روی یک نام دامنه عمومی ایمن خواهد بود. همین مسابقه (race condition) در سایر برنامه‌های self-hosted نیز وجود دارد و در مواردی که اولین ورود، یک passkey وابسته به نام میزبان (hostname) ایجاد می‌کند، وضعیت بدتر است؛ به همین دلیل است که هنگام self-host openGym، پیش از ایجاد اولین حساب کاربری، باید TLS و دامنه نهایی تنظیم شده باشند.

محل ذخیره‌سازی داده‌ها در AFFiNE

سه مسیر تمام داده‌ها را در خود جای می‌دهند و همگی در دایرکتوری که ایجاد کرده‌اید قرار دارند.

  • ./data/postgres دایرکتوری داده‌های Postgres است: اسناد، کاربران، ورک‌اسپیس‌ها، مجوزها و هر تنظیمات سروری که از پنل مدیریت ذخیره شده باشد.
  • ./data/storage در مسیر /root/.affine/storage داخل کانتینر mount می‌شود و تمام فایل‌های آپلود شده را نگه می‌دارد.
  • ./config در مسیر /root/.affine/config mount می‌شود و config.json و private.key تولید شده توسط job مهاجرت (migration) را در خود جای می‌دهد.

توسعه‌دهنده در اینجا به‌جای named volumes از bind mounts استفاده می‌کند و این انتخاب آگاهانه است: شما می‌توانید این مسیرها را با دستورات معمولی tar کرده و کپی کنید، بدون اینکه نیاز باشد از Docker بپرسید آن‌ها را کجا قرار داده است. هزینه این کار این است که مالکیت فایل‌ها روی میزبان (host) اکنون بر عهده شماست؛ این همان مبحثی است که در bind mounts and named volumes به آن پرداخته شده است.

نحوه پشتیبان‌گیری از AFFiNE

دو بخش نیاز به پشتیبان‌گیری دارند که روش پشتیبان‌گیری هر کدام متفاوت است. پایگاه داده یک سرور فعال است، بنابراین کپی کردن فایل‌های آن در حین اجرا منجر به ایجاد یک نسخه خراب می‌شود. در عوض از آن 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/

عملیات dump داخل کانتینر و از طریق سوکت محلی آن اجرا می‌شود، بنابراین نیازی به وارد کردن رمز عبور نیست. حجم فایل را در خروجی ls بررسی کنید. فایلی با حجم چند صد بایت به این معنی است که عملیات dump شکست خورده است، در حالی که 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 را در پشتیبان خود نگه دارید، زیرا dump شامل آن‌ها نمی‌شود. عملیات مهاجرت (migration) همچنین config/private.key را ایجاد می‌کند، بنابراین کپی کردن تنها config.json باعث می‌شود این فایل از قلم بیفتد. تنظیمات ذخیره‌شده در پنل مدیریت در پایگاه داده قرار دارند، بنابراین dump فوق آن‌ها را نیز شامل می‌شود؛ همچنین طبق اطلاعات صفحه پشتیبان‌گیری AFFiNE در تاریخ 12 October 2026، تنظیمات تغییریافته سرور را می‌توان از طریق پنل مدیریت نیز خروجی گرفت. هر سه فایل را از سرور خارج کنید. پشتیبانی که روی همان دیسکی باشد که از آن محافظت می‌کند، پشتیبان محسوب نمی‌شود. این الگوی تفکیک dump پایگاه داده و tar کردن دایرکتوری آپلودها، روشی است که باید برای هر کانتینر stateful دیگری که اجرا می‌کنید تکرار شود؛ این همان روشی است که تاریخچه گفتگوها و پیوست‌ها را هنگام میزبانی شخصی Chatwoot به عنوان میز پشتیبانی ایمن نگه می‌دارد.

بازیابی و یک تله در مراحل منتشرشده

پیش از آنکه به مراحل رسمی بازیابی نیاز پیدا کنید، آن‌ها را بخوانید و با دقت بررسی کنید. طبق آنچه در اوت 2026 منتشر شد، آن‌ها فایلی به نام affine.backup را در کانتینر کپی کرده و سپس از ./pg.backup بازیابی می‌کردند که دو نام متفاوت هستند؛ همچنین آن‌ها دایرکتوری ./postgres را حذف می‌کردند، در حالی که فایل compose فعلی داده‌های خود را در ./data/postgres نگه می‌دارد. از تاریخ 12 اکتبر 2026، این صفحه در تمام بخش‌ها از 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

به mv به جای rm توجه کنید. بازیابی روی دیتابیسی که از آن نسخه پشتیبان تهیه نکرده‌اید، روشی است که یک دستور اشتباه را به از دست رفتن کامل داده‌ها تبدیل می‌کند، و انتقال دایرکتوری قدیمی به یک مکان دیگر هزینه‌ای ندارد. فایل‌های آپلود شده را نیز با tar xzf backup/storage-2026-08-08.tgz -C data بازیابی کنید، در غیر این صورت تمام اسناد با پیوست‌های خراب نمایش داده می‌شوند. سپس وارد سیستم شوید و سندی را باز کنید که حاوی یک تصویر است. این همان تست نهایی است. بازیابی‌ای که در مرورگر باز نکرده‌اید، فقط یک فایل است، نه یک نسخه پشتیبان.

قرار دادن AFFiNE پشت پروکسی موجود

AFFiNE از WebSocket استفاده می‌کند و این موضوع اختیاری نیست. مستندات به‌صراحت بیان می‌کنند که WebSocket پایه و اساس سیستم همگام‌سازی و همکاری در AFFiNE است؛ بنابراین پروکسی که این اتصالات را ارتقا (upgrade) ندهد، باعث می‌شود فضای کاری شما همگام‌سازی را متوقف کند. صفحه بارگذاری می‌شود، ورود به سیستم کار می‌کند، اما ویرایشی که در یک مرورگر انجام شده به مرورگر دیگر نمی‌رسد. در ابزارهای توسعه‌دهنده مرورگر خود، زبانه 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 برای احراز هویت یکپارچه قرار دارند، یک middleware از نوع forward auth روی این روتر دسترسی مرورگر به AFFiNE را محدود می‌کند؛ اما تا زمانی که اپلیکیشن دسکتاپ را تست نکرده‌اید آن را فعال نکنید، زیرا اپلیکیشن دسکتاپ نشست مرورگر ندارد و همگام‌سازی آن با شکست مواجه می‌شود. اجرای چندین برنامه پشت یک نمونه از آن در یک Traefik واحد در مقابل چندین برنامه توضیح داده شده است.

در nginx باید ارتقا (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;
}

مقدار پیش‌فرض client_max_body_size در nginx برابر با 1 MB است، بنابراین بدون آن خط، هر آپلود بزرگ‌تر از یک عکس کوچک با وضعیت 413 شکست می‌خورد و هیچ چیزی در لاگ‌های AFFiNE ثبت نمی‌شود، زیرا درخواست هرگز به مقصد نرسیده است. Caddy تنها به یک خط یعنی reverse_proxy http://127.0.0.1:3010 نیاز دارد و گواهی‌ها و ارتقای WebSocket را به‌صورت خودکار مدیریت می‌کند.

آنچه در نسخه self-hosted نادیده گرفته شده است

پیش از انتقال یک تیم، در این مورد با خود صادق باشید.

قابلیت همکاری بلادرنگ (Real-time collaboration) در دسترس است و تمام توصیه‌های مربوط به تعیین ابعاد (sizing) بر اساس همین ویژگی ارائه شده‌اند، زیرا مستندات خود AFFiNE مصرف حافظه را به سیستم همگام‌سازی و ادغام اسناد نسبت می‌دهد. ویرایش آفلاین دلیلی است که بسیاری از افراد به دنبال ابزارهای local-first هستند و اپلیکیشن دسکتاپ می‌تواند سرور self-hosted شما را به لیست فضای کاری (workspace) اضافه کرده و به آن وارد شود. پیش از تصمیم‌گیری نهایی، رفتار دقیق آفلاین مورد نیاز تیم خود را تست کنید: در اپلیکیشن دسکتاپ و در حالی که شبکه قطع است ویرایش انجام دهید، دوباره متصل شوید و سپس نتیجه را در دستگاه دوم بررسی کنید. لیست ویژگی‌ها مدرک نیستند، و این شامل همین لیست هم می‌شود.

جستجوی تمام‌متن سمت سرور (Server-side full-text search) در فایل compose ارائه‌شده غیرفعال است، جایی که AFFINE_INDEXER_ENABLED=false روی سرور و در job مهاجرت تنظیم شده است. فعال‌سازی آن به معنای افزودن یک container برای Manticore Search است که پنجمین سرویس محسوب شده و حافظه بیشتری مصرف می‌کند. روی یک سرور 2 GB، این همان تغییری است که شما را با کمبود منابع مواجه می‌کند. جستجو در داخل کلاینت همچنان روی فضای کاری که باز کرده‌اید کار می‌کند.

پیش از دعوت از افراد، دانستن دو محدودیت ضروری است. به یک فضای کاری self-hosted حداکثر 10 کاربر (seat) اختصاص داده می‌شود و عبور از این تعداد نیازمند تهیه لایسنس Team از AFFiNE است. فضای ذخیره‌سازی نامحدود برای blobها و اندازه نامحدود برای blobها در نمونه‌های self-hosted، طبق مستندات، در برنامه قرار دارد اما تا اکتبر 2026 هنوز به‌طور کامل پیاده‌سازی نشده است. هیچ‌کدام از این موارد برای یک خانواده یا یک تیم کوچک اهمیتی ندارد. اما اگر قصد دارید چهل نفر را منتقل کنید، هر دو مورد اهمیت پیدا می‌کنند.

ارتقاها

ابتدا یادداشت‌های انتشار (release notes) را مطالعه کنید، به‌ویژه برای تغییرات جزئی نسخه مانند 0.26 به 0.27 که ممکن است شامل تغییرات ناسازگار (breaking changes) باشد. پیش از هر اقدامی، از پایگاه داده و دایرکتوری ذخیره‌سازی نسخه پشتیبان تهیه کنید؛ زیرا عملیات مهاجرت (migration) در شروع بعدی، طرح‌واره (schema) شما را تغییر می‌دهد و امکان بازگشت وجود ندارد. سپس digest ثابت‌شده را تغییر دهید، دستور docker compose pull و به دنبال آن docker compose up -d را اجرا کنید و docker compose logs -f affine_migration را تا زمان خروج موفقیت‌آمیز زیر نظر بگیرید. دستور docker image prune پس از آن لایه‌های قدیمی را پاکسازی می‌کند. یک نکته تاریخی برای کسانی که از نسخه‌های بسیار قدیمی استفاده می‌کنند: از نسخه 0.23.0 نام image از affine-graphql به affine تغییر یافته است؛ بنابراین فایل compose قدیمی‌تر از آن نسخه، پیش از آنکه pull بتواند چیزی پیدا کند، نیاز به بازنویسی خطوط image دارد. همچنین از نسخه 0.27.4، قالب رسمی compose مسیرهای Postgres، آپلود و پیکربندی را تغییر داده و اتصال پیش‌فرض پایگاه داده را اصلاح کرده است؛ بنابراین به‌جای جایگزینی فایل جدید روی یک نصب فعال، آن را با فایل فعلی خود مقایسه کنید.

FAQ

چرا کانتینر AFFiNE هرگز اجرا نمی‌شود؟

سرویس affine وابستگی condition: service_completed_successfully را روی job مربوط به affine_migration تعریف می‌کند؛ بنابراین اگر عملیات migration با هر وضعیتی غیر از 0 خاتمه یابد، سرور هرگز اجرا نمی‌شود و رابط کاربری وب اصلاً بالا نمی‌آید. دستور docker compose logs affine_migration را اجرا کنید تا ببینید کدام مرحله متوقف شده است. بررسی کنید که اگر فایل compose را دستی ویرایش کرده‌اید، همچنان از pgvector/pgvector:pg16 استفاده می‌کند: نسخهٔ استاندارد Postgres شامل افزونهٔ pgvector که در شمای AFFiNE تعریف شده نیست؛ حتی با اینکه نسخه v0.27.4 دیگر چهار مدل embedding موجود در v0.27.3 را تعریف نمی‌کند.

AFFiNE برای میزبانی شخصی به چه مقدار RAM نیاز دارد؟

صفحهٔ نیازمندی‌های AFFiNE حداقل 4 هسته CPU و 2 گیگابایت RAM درخواست می‌کند که با عبور تعداد کلمات اسناد از 10,000 کلمه، این مقدار به 4 گیگابایت افزایش می‌یابد. همچنین ذکر شده که ادغام سندی با 10,000 تغییر می‌تواند تا 1 گیگابایت RAM مصرف کند. در سروری با 2 گیگابایت RAM، این پیک مصرف است که باعث مشکل می‌شود، نه بار کاری عادی: مکانیزم out-of-memory killer هستهٔ سیستم‌عامل، یک پردازش را برای متوقف کردن انتخاب می‌کند که معمولاً سرور AFFiNE به دلیل حجم بالا است و restart: unless-stopped دوباره آن را اجرا می‌کند؛ بنابراین کاربران به‌جای خطا، شاهد بارگذاری مجدد صفحه هستند. این موضوع را با docker inspect affine_server --format '{{.State.OOMKilled}}' و sudo dmesg -T | grep -i 'out of memory' تأیید کنید، سپس یک فایل swap با حجم 2 گیگابایت به‌عنوان بافر برای پیک‌های کوتاه اضافه کنید و اگر توقف پردازش‌ها ادامه داشت، RAM را به 4 گیگابایت ارتقا دهید.

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 در حال اجرا ایمن نیست. آن dump شامل تمام تنظیمات ذخیره‌شده در پنل مدیریت نیز هست، زیرا AFFiNE آن‌ها را در پایگاه داده نگه می‌دارد. از ./data/storage برای فایل‌های آپلود شده آرشیو tar بگیرید و کل دایرکتوری config، فایل Compose و .env را حفظ کنید، زیرا این فایل‌ها بخشی از پایگاه داده نیستند.

آیا همکاری هم‌زمان (real-time collaboration) در نسخه خود-میزبانی AFFiNE کار می‌کند؟

بله، و برای آن نیازی به فعال‌سازی هیچ گزینه‌ای نیست. تنها پیش‌نیاز، reverse proxy شماست، زیرا همگام‌سازی از طریق اتصالات WebSocket انجام می‌شود. در nginx این به معنای proxy_http_version 1.1 به همراه هدرهای Upgrade و Connection: upgrade است، در حالی که Traefik و Caddy این اتصالات را بدون پیکربندی اضافی عبور می‌دهند. نشانهٔ پروکسی که این اتصالات را ارتقا (upgrade) نمی‌دهد این است که فضای کاری به‌طور عادی بارگذاری شده و وارد سیستم می‌شوید، اما ویرایش‌های انجام‌شده در یک مرورگر هرگز در مرورگر دیگر ظاهر نمی‌شوند.

آیا می‌توانم AFFiNE را با ایمیج استاندارد Postgres اجرا کنم؟

از pgvector/pgvector:pg16 استفاده کنید که همان Postgres 16 با افزونهٔ pgvector کامپایل‌شده است. نسخه v0.27.4 از AFFiNE همچنان extensions = [pgvector(map: "vector")] را در schema.prisma اعلام می‌کند، اما دیگر چهار مدل با ستون‌های embedding مربوط به vector(1024) که در v0.27.3 وجود داشتند را تعریف نمی‌کند. نسخه استاندارد Postgres شامل این افزونهٔ اعلام‌شده نیست. اگر AFFiNE را به یک سرور Postgres خارجی متصل می‌کنید، pgvector را روی آن نصب کنید و پیش از اجرای migration، افزونه را در پایگاه داده مقصد ایجاد کنید.

آیا این مقاله مفید بود؟