SSD Nodes Learn Hosting plans →
מדריכים Matt Connorמאת Matt Connor

אירוח עצמי של AFFiNE: מדריך התקנה עם Docker Compose

למדו איך להריץ AFFiNE על שרת VPS באמצעות Docker Compose. המדריך מפרט את ארבע המכולות הנדרשות, תגיות image קבועות, ניהול גיבויים והאם 2GB RAM מספיקים להרצה יציבה של המערכת.

מה מקבלים באירוח עצמי של AFFiNE

אירוח עצמי של AFFiNE מעניק לכם סביבת עבודה בסגנון Notion על שרת שבשליטתכם, הפועלת באמצעות ארבע מכולות: היישום, משימת העברת נתונים (migration) חד-פעמית, Postgres ו־Redis. שיתוף פעולה בזמן אמת כלול, עד ל-10 משתמשים שסביבת עבודה באירוח עצמי מקבלת כברירת מחדל. ההתקנה כוללת קובץ compose אחד וקובץ תצורה בפורמט JSON. הנושאים הדורשים מחשבה הם תגיות ה-image, מבנה הדיסק, מגבלת הזיכרון וה-proxy שתציבו בחזית.

AFFiNE משלב עורך מסמכים ולוח ציור אינסופי באותה סביבת עבודה, כך שניתן לקרוא דף כמסמך או לפרוס אותו כלוח מחיק. אם אתם עדיין מתלבטים מה להריץ, קראו תחילה את ה-השוואה בין חלופות Notion לאירוח עצמי. מדריך זה מניח שההחלטה התקבלה, והוא מתמקד בהרצה תקינה של AFFiNE ולא בהשוואה נוספת.

כל המידע כאן נבדק מול תיעוד האירוח העצמי של AFFiNE וקובצי ה-release שפורסמו ב-8 באוגוסט 2026. ה-release היציב העדכני ביותר בתאריך זה היה 0.27.3, שפורסם ב-23 ביולי 2026. טענות להלן הנושאות תאריך מאוחר יותר נבדקו שנית מול מקורותיהן העיקריים ב-12 באוקטובר 2026, כאשר ה-release היציב העדכני ביותר היה 0.27.4, שפורסם ב-18 באוגוסט 2026.

מה עושות ארבע המכולות בפועל

affine הוא השרת והלקוח מבוסס הדפדפן בתמונה (image) אחת. הוא מאזין בפורט 3010.

affine_migration הוא משימה חד-פעמית המריצה את node ./scripts/self-host-predeploy.js, מחילה את עדכוני מסד הנתונים (migrations) ומסתיימת. היישום מגדיר condition: service_completed_successfully על משימה זו, כך שעדכון שמסתיים בסטטוס שאינו אפס גורם לכך ש-affine לעולם לא יופעל. כאשר ממשק האינטרנט אינו עולה, הלוג של משימה זו הוא הדבר הראשון שיש לקרוא.

postgres מאחסן את המסמכים, המשתמשים, סביבות העבודה וההרשאות שלך. התמונה המסופקת היא pgvector/pgvector:pg16, שהיא Postgres 16 רגיל עם תוסף pgvector מהודר בתוכו. pgvector מוסיף סוג עמודה vector ל-Postgres, הצורה הנומרית המשמשת לאחסון embeddings כדי שניתן יהיה לחפש טקסט לפי משמעות.

redis הוא תלות הכרחית: גם השרת וגם משימת העדכון ממתינים לבדיקת התקינות שלו לפני שהם מתחילים. שימו לב למה שקובץ ה-compose המסופק לא נותן ל-Redis, וזה volume. שום דבר בתוכו לא שורד docker compose down, וזה אומר לכם בבירור שהוא אינו מחזיק תוכן שלכם ואינו זקוק לגיבוי.

מדוע נעשה שימוש ב-image של pgvector ולא ב-Postgres סטנדרטי

הדרישה נובעת מה-schema של AFFiNE, ולא מהעדפה אישית. בגרסה v0.27.4, ה-schema.prisma עדיין מצהיר על extensions = [pgvector(map: "vector")], אך אינו מכיל עמודות embedding. ארבעת המודלים עם עמודות embedding מסוג vector(1024) שהיו קיימים ב-v0.27.3 אינם נמצאים ב-v0.27.4. יש להשתמש ב-image של pgvector/pgvector:pg16 שסופק: התוסף עדיין מוצהר, ו-postgres:16 סטנדרטי אינו כולל אותו.

התבנית הרשמית של v0.27.4 משתמשת ב-image של pgvector; התבנית של v0.21.0 עדיין השתמשה ב-postgres:16. בהתקנה ישנה, עריכת שורת ה-image אינה מספיקה להשלמת השדרוג, לכן יש לקרוא את דף השדרוג ב-תיעוד האירוח העצמי של AFFiNE לפני ביצוע פעולת pull כלשהי.

נקודה נוספת בנוגע ל-tag הזה. pg16 מציין Postgres 16, וגרסה ראשית (major version) של Postgres אינה מספר שניתן להעלות כרגע. שינוי ל-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 ושחזור לתוך ספריית נתונים נקייה, pg_upgrade, או שכפול לוגי (logical replication). בהתקנת Compose בודדת, ביצוע dump ושחזור הוא בדרך כלל הדרך הפשוטה ביותר, כיוון ש-pg_upgrade דורש את הקבצים הבינאריים של השרת הישן והחדש זה לצד זה.

כמה מעבד וזיכרון דורשת התקנה עצמית של AFFiNE

דף הדרישות של AFFiNE מציין צורך במינימום 4 ליבות מעבד ו-2 GB של RAM, וממליץ להעלות את הזיכרון ל-4 GB ברגע שהמסמכים שלכם עוברים את רף 10,000 המילים. אותו דף מסביר לאן הזיכרון הולך: למערכת הסנכרון ולמיזוג מסמכים. הוא מציין נתון אחד שחשוב לזכור: מיזוג מסמך עם 10,000 שינויים יכול להגיע לשיא של 1 GB.

כעת, השוו זאת לתוכנית של 2 GB עם שני כותבים. הממוצע תקין. תהליך ה-Postgres ותהליך ה-Node נשארים מתחת למגבלה עם מרווח נשימה. הבעיה היא בשיא. מיזוג גדול אחד יכול לדחוף את צריכת הזיכרון של השרת לשיא של כ-1 GB, ובשרת עם 2 GB ללא swap, השיא הזה יחד עם Postgres ושאר התהליכים עלול למצות את הזיכרון. מנגנון ה-out-of-memory (OOM) killer של ה-kernel יסיים אז תהליך כדי לפנות זיכרון. שרת ה-AFFiNE, כתהליך הגדול ביותר, הוא הקורבן הסביר ביותר, אם כי התיעוד של Docker מבהיר שכל תהליך עלול להיבחר, כולל Docker עצמו.

כאשר מדובר בשרת ה-AFFiNE, הקולגה שלכם לא יראה שגיאה. הוא יראה את הדף נטען מחדש, מכיוון ש-restart: unless-stopped מחזיר את ה-container לפעולה תוך שניות. אל תנחשו, אשרו זאת:

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 למהיר, ולא זו מטרתו. הוא נותן לקפיצה רגעית מקום להיפרק אליו, כך שהקפיצה תעלה לכם בשנייה של איטיות במקום ב-container שקרס. זהו מאגר, לא ערובה. הקצה השני של התיקון הוא למנוע מ-Postgres להגדיל את ה-cache שלו לתוך המרחב שהיישום צריך בזמן מיזוג, וזה בדיוק מה ש-מגבלות זיכרון בשירות 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 באוגוסט 2026, הקובץ שצורף לגרסה 0.27.3 עדיין קרא את הנתיבים שלו מקובץ .env, תוך שימוש ב-${UPLOAD_LOCATION}, ${CONFIG_LOCATION} ו-${DB_DATA_LOCATION}, בעוד שדף ההפניה בתיעוד הציג מבנה חדש יותר המציב את האחסון ואת נתוני ה-PostgreSQL תחת ./data, שומר את התצורה תחת ./config, ואינו זקוק ל-.env כלל. גרסה 0.27.4 העבירה את הקובץ המצורף למבנה הזה, ונכון ל-12 באוקטובר 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} עבורכם, כך שהסיסמה לעולם לא מופיעה בקובץ שהייתם מדביקים בשרשור תמיכה. כדאי לאמץ הרגל זה בכל 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' המקורי נקשר לכל הממשקים, וברוב תמונות ה-VPS זה כולל את הממשק הציבורי.
  • POSTGRES_HOST_AUTH_METHOD: trust הוסר ובמקומו הוגדרה סיסמה. אימות מסוג Trust מקבל כל חיבור למסד הנתונים הזה כמשתמש affine ללא סיסמה. הוא מוגבל לרשת ה-Compose הפרטית, וזה תקין עד היום שבו תחברו מכולה נוספת לאותה רשת או תפרסמו את 5432 בזמן ניפוי שגיאות (debugging).
  • redis:8-alpine מחליף את redis החשוף, שמתורגם ל-latest. נכון לאוגוסט 2026 מדובר ב-Redis 8, לכן הנעילה שומרת על הגרסה הראשית שבדקתם ומונעת מ-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 בונה קישורי שיתוף והזמנות למרחבי עבודה על בסיס ערך זה; אם תשאירו אותו כ-http://localhost:3010, הזמנה שתשלחו תפנה את הנמען למחשב שלו עצמו והיא תיכשל. הגדירו את הכתובת הציבורית ב-HTTPS לפני ההפעלה הראשונה, כדי שהקובץ ולוח הבקרה של הניהול יהיו מסונכרנים תמיד. הגדרות שתשנו מאוחר יותר בלוח הבקרה יישמרו במסד הנתונים, ולא ייכתבו חזרה לקובץ זה.

copilot שולט בתכונות ה-AI. copilot.byok.enabled הוא המתג המאפשר שימוש במפתח אישי (Bring-Your-Own-Key), המאפשר לבעל מרחב עבודה להזין מפתח של ספק מודלים בהגדרות המרחב. אירוח עצמי של AFFiNE אינו כולל מנוי AI. השאירו את שניהם כ-false אם אינכם מעוניינים בכך.

הפעילו את ה-stack:

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 מציג רק מכולות פעילות, כך שמשימת הגירה (migration) שהסתיימה בהצלחה לא תופיע כלל. כל קוד יציאה אחר במשימת ההגירה הוא הבעיה שיש לחקור, והלוג שלה יציין את השלב שבו התהליך נעצר:

docker compose logs affine_migration

קבעו את גרסת ה-image לפני שתשכחו

stable הוא תגית דינמית. תהליך ה-release של AFFiNE מצביע על כמה תגיות בכל build יציב, ושתיים מהן רלוונטיות כאן: stable, שמתעדכנת בכל release, ו-stable- שאחריה מופיע ה-git short hash, שאינו משתנה. אם תישאר עם stable, פקודת docker compose pull בעוד שישה חודשים תמשוך image שונה ותריץ את ה-migrations שלו מול מסד הנתונים שלכם ברגע שלא בחרתם בו. קבעו (pin) את ה-image המדויק שבדקתם:

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

הפקודה תדפיס שורה בסגנון ghcr.io/toeverything/affine@sha256: ואחריה hash ארוך. הדביקו את המחרוזת המלאה בשורת ה-image: בתוך שני הקבצים: affine ו-affine_migration. שני הקבצים הללו חייבים להיות זהים תמיד, כיוון שמדובר באותו image הממלא שני תפקידים; חוסר התאמה ביניהם משמעו הרצת migrations למסד הנתונים לפי סכימה אחת, בעוד השירות פועל לפי סכימה אחרת. שדרוג גרסה יהיה מעתה פעולה מכוונת ולא הפתעה: שנו את ה-digest, בצעו גיבוי, הריצו docker compose pull, ולאחר מכן docker compose up -d.

יצירת חשבון מנהל המערכת לפני שמישהו אחר יעשה זאת

פתחו את /admin במופע חדש, ו-AFFiNE תפנה אתכם לדף יצירת חשבון, כיוון שאין עדיין מנהל מערכת לשרת. בתהליך זה אין קוד הזמנה או אסימון הגדרה (setup token). האדם הראשון שמסיים את ההרשמה הופך למנהל המערכת של השרת שלכם, לכן הפורט חייב להישאר סגור עד שתסיימו את ההרשמה.

זו הסיבה שקובץ ה-compose לעיל מבצע bind ל-127.0.0.1. גשו אליו דרך מנהרת SSH מהמחשב האישי שלכם:

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

השאירו את המנהרה פועלת ופתחו את http://127.0.0.1:3010/admin בדפדפן המקומי שלכם. הירשמו והתחברו, ולאחר מכן סגרו את המנהרה. רק כעת בטוח לחשוף את המופע לשם מתחם ציבורי. מרוץ דומה מתרחש ביישומים אחרים המארחים את עצמם, והמצב חמור יותר כאשר ההתחברות הראשונה יוצרת passkey הקשור לשם המארח (hostname); זו הסיבה שחובה להגדיר TLS ואת שם המתחם הסופי לפני יצירת החשבון הראשון כאשר אתם מבצעים אירוח עצמי ל-openGym.

היכן AFFiNE שומרת את הנתונים שלך

שלושה נתיבים מכילים את כל המידע, וכולם נמצאים בתוך הספרייה שיצרת.

  • ./data/postgres היא ספריית הנתונים של Postgres: מסמכים, משתמשים, סביבות עבודה (workspaces), הרשאות וכל הגדרות השרת שנשמרו מלוח הבקרה של מנהל המערכת.
  • ./data/storage ממופה ל-/root/.affine/storage בתוך המכולה ומכילה את כל הקבצים שהועלו.
  • ./config ממופה ל-/root/.affine/config ומכילה את config.json ואת ה-private.key שנוצר על ידי משימת ה-migration.

הפרויקט משתמש ב-bind mounts במקום ב-named volumes, וזו בחירה מכוונת: ניתן לבצע 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 רץ בתוך המכולה מול ה־socket המקומי שלה, לכן הוא אינו מבקש סיסמה. בדקו את גודל הקובץ בפלט של 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 אינו מכיל אותם. משימת המיגרציה יוצרת גם את config/private.key, לכן העתקה של config.json בלבד תחסיר את הקובץ הזה. הגדרות שנשמרו בלוח הניהול מאוחסנות במסד הנתונים, כך שה-dump לעיל כבר כולל אותן. נכון ל-12 באוקטובר 2026, דף הגיבוי של AFFiNE מציין כי ניתן לייצא הגדרות שרת ששונו גם מתוך לוח הניהול. העתיקו את כל שלושת הקבצים אל מחוץ לשרת. גיבוי שנמצא על אותו דיסק של המידע שהוא אמור להגן עליו אינו נחשב לגיבוי. הפיצול הזה, הכולל 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. שחזור על גבי מסד נתונים שלא שמרתם לו עותק הוא הדרך שבה פקודה שגויה אחת הופכת לאובדן נתונים מוחלט, והעברת הספרייה הישנה הצידה אינה עולה דבר. שחזרו גם את ה-uploads, בעזרת tar xzf backup/storage-2026-08-08.tgz -C data, אחרת כל מסמך יוצג עם קבצים מצורפים שבורים. לאחר מכן התחברו ופתחו מסמך המכיל תמונה. זהו המבחן. שחזור שלא פתחתם בדפדפן הוא קובץ בלבד, לא גיבוי.

הצבת AFFiNE מאחורי proxy קיים

AFFiNE משתמש ב־WebSocket, וזהו רכיב הכרחי. התיעוד מבהיר זאת: WebSocket הוא הבסיס למערכת הסנכרון ושיתוף הפעולה של AFFiNE. לכן, proxy שאינו מבצע upgrade לחיבורים אלו יגרום לכך שהעריכה תפסיק להסתנכרן בשקט. הדף נטען, ההתחברות עובדת, אך עריכה שבוצעה בדפדפן אחד לעולם לא תגיע לאחר. בכלי המפתחים של הדפדפן, פתחו את לשונית Network וסננו לפי WS. חיבור שנפתח ונסגר שוב ושוב מעיד על proxy שאינו מעביר את ה־upgrade.

אם אתם כבר מריצים 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, לעולם לא פורט של ה-host. Traefik מבצע proxy לחיבורי WebSocket ללא צורך בתצורה נוספת, כך שאין מה להוסיף. אם שאר ה-stack שלכם כבר נמצא מאחורי Authentik עבור single sign-on, הוספת forward auth middleware ב-router הזה תחסום גישת דפדפן ל-AFFiNE. השאירו זאת כבוי עד שתבדקו את אפליקציית ה-desktop, שכן היא אינה מחזיקה session של דפדפן ופשוט תיכשל בסנכרון. הרצת כמה יישומים מאחורי מופע אחד של Traefik מוסברת ב-a single Traefik in front of several apps.

ב-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 upgrades בעצמו.

מה נותר מחוץ להתקנה העצמית

היו כנים עם עצמכם בנושא זה לפני שתעבירו צוות שלם.

שיתוף פעולה בזמן אמת קיים, וזהו המאפיין שעליו מבוססות כל ההמלצות לגבי גודל השרת, שכן התיעוד של AFFiNE מייחס את צריכת הזיכרון למערכת הסנכרון ולמיזוג מסמכים. עריכה במצב לא מקוון היא הסיבה לכך שאנשים רבים מעוניינים בכלי המבוסס על גישת local-first, ויישום שולחן העבודה מאפשר להוסיף את השרת המנוהל עצמית לרשימת סביבות העבודה ולהתחבר אליו. בדקו את התנהגות המצב הלא מקוון המדויקת שהצוות שלכם מסתמך עליה לפני שתתחייבו: בצעו עריכה ביישום שולחן העבודה ללא חיבור לרשת, התחברו מחדש, ולאחר מכן בדקו את התוצאה במכשיר שני. רשימות מאפיינים אינן מהוות הוכחה, וזה כולל גם את הרשימה הזו.

חיפוש טקסט מלא בצד השרת מושבת בקובץ ה-compose המסופק, שבו AFFINE_INDEXER_ENABLED=false מוגדר בשרת ובעבודת המיגרציה. הפעלתו מחייבת הוספת מכולת Manticore Search, שהיא שירות חמישי וצריכת זיכרון נוספת. בשרת עם 2 GB, זהו השינוי שדוחף את המערכת מעבר לקצה גבול היכולת. החיפוש בתוך הלקוח עדיין עובד על סביבת העבודה הפתוחה.

כדאי להכיר שתי מגבלות לפני שמזמינים משתמשים. סביבת עבודה מנוהלת עצמית מוגבלת לכל היותר ל-10 משתמשים, וחריגה מכך דורשת רישיון Team מ-AFFiNE. אחסון blob ללא הגבלה וגודל blob ללא הגבלה עבור מופעים מנוהלים עצמית מתוארים בתיעוד ככאלה המיועדים לעתיד אך טרם מומשו במלואם, נכון לאוקטובר 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 ישן יותר דורש עדכון של שורות ה-image כדי שפעולת ה-pull תמצא את הקבצים. החל מגרסה 0.27.4, תבנית ה-compose הרשמית שינתה את הנתיבים של Postgres, ה-uploads והתצורה, וכן את הגדרת החיבור למסד הנתונים כברירת מחדל; לכן, השוו את הקובץ החדש מול הקובץ הקיים שלכם במקום להעתיק אותו על התקנה עובדת.

FAQ

מדוע המכולה של AFFiNE לא עולה לעולם?

השירות affine מצהיר על condition: service_completed_successfully במשימת affine_migration, לכן אם תהליך ה-migration מסיים בכל סטטוס שאינו 0, השרת לעולם לא יופעל ולא יופיע ממשק אינטרנט כלל. הריצו את docker compose logs affine_migration כדי לראות איזה שלב עצר את התהליך. ודאו שקובץ ה-compose שערכתם ידנית עדיין משתמש ב-pgvector/pgvector:pg16: גרסת ה-Postgres הסטנדרטית אינה כוללת את תוסף ה-pgvector שסכימת ה-AFFiNE עדיין מצהירה עליו, אף על פי שגרסה v0.27.4 כבר אינה מגדירה את ארבעת מודלי ה-embedding שהיו קיימים ב-v0.27.3.

כמה זיכרון RAM דורש AFFiNE באירוח עצמי?

דף הדרישות של AFFiNE מבקש לפחות 4 ליבות CPU ו-2 GB של RAM, ועולה ל-4 GB כאשר מסמכים עוברים את ה-10,000 מילים. הוא מציין שמיזוג מסמך עם 10,000 שינויים יכול להגיע לשיא של 1 GB. בשרת עם 2 GB, השיא הזה הוא מה שמפיל את השירות, לא העומס במצב המתנה: מנגנון ה-out-of-memory killer של ה-kernel בוחר תהליך לעצירה, לרוב שרת ה-AFFiNE כיוון שהוא הגדול ביותר, ו-restart: unless-stopped מפעיל אותו מחדש, כך שהמשתמשים רואים רענון דף במקום שגיאה. אשרו זאת באמצעות docker inspect affine_server --format '{{.State.OOMKilled}}' ו-sudo dmesg -T | grep -i 'out of memory', לאחר מכן הוסיפו קובץ swap של 2 GB כחיץ נגד קפיצות קצרות, ועברו ל-4 GB של RAM אם ההפסקות נמשכות.

היכן 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 שומר אותן במסד הנתונים. בצעו tar ל-./data/storage עבור ההעלאות ושמרו את כל תיקיית config, את קובץ ה-Compose ואת .env, כיוון שקבצים אלו אינם חלק ממסד הנתונים.

האם שיתוף פעולה בזמן אמת עובד ב-AFFiNE באירוח עצמי?

כן, ואין צורך להפעיל דבר עבורו. הדרישה היחידה היא ה-reverse proxy שלכם, כיוון שהסנכרון רץ על גבי חיבורי WebSocket. ב-nginx המשמעות היא proxy_http_version 1.1 בתוספת ה-headers מסוג Upgrade ו-Connection: upgrade, בעוד ש-Traefik ו-Caddy מעבירים את החיבורים הללו ללא הגדרה נוספת. הסימפטום של proxy שלא מבצע להם upgrade הוא סביבת עבודה שנטענת ונכנסת כרגיל, בעוד עריכות שבוצעו בדפדפן אחד לעולם לא מופיעות באחר.

האם ניתן להריץ את AFFiNE עם image סטנדרטי של 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.

האם המאמר הזה היה מועיל?