AFFiNE 自架教學:Docker Compose 與備份
用 Docker Compose 在單一 VPS 自架 AFFiNE,了解 4 個容器、固定 image tags、資料位置與備份方式,以及 2 GB RAM 實際能支援的規模。
自架 AFFiNE 的內容
自架 AFFiNE 可在由你管理的伺服器上提供類似 Notion 的工作區,並以 4 個容器執行:應用程式、一次性 migration 工作、Postgres 及 Redis。系統內建即時協作功能,自架工作區預設最多支援 10 個席位。安裝只需要 1 個 compose 檔案和 1 個 JSON 設定檔。需要仔細規劃的是 image tags、磁碟配置、記憶體上限,以及前端的 proxy。
AFFiNE 在同一個工作區中整合文件編輯器和無限畫布,因此同一頁面可以作為文件閱讀,也可以展開成白板。如果你仍在決定要執行哪個系統,請先閱讀 自架 Notion 替代方案的比較。本指南假設你已經做出選擇,內容涵蓋如何正確執行 AFFiNE,而不是再次進行比較。
本頁內容已於 2026 年 8 月 8 日,依據 AFFiNE 的自架文件及已發布的 release files 完成查核。當日最新的 stable release 為 0.27.3,發布於 2026 年 7 月 23 日。下文標示較晚日期的資訊,已於 2026 年 10 月 12 日依據 primary sources 再次查核;當時最新的 stable release 為 0.27.4,發布於 2026 年 8 月 18 日。
四個容器實際負責的工作
affine 將伺服器與 Web 用戶端整合在同一個映像檔中。它監聽 3010 埠。
affine_migration 是一次性工作,會執行 node ./scripts/self-host-predeploy.js、套用資料庫遷移,然後結束。應用程式對該工作宣告 condition: service_completed_successfully,因此遷移以非零狀態結束時,affine 完全不會啟動。Web 介面無法啟動時,應先查看該工作的日誌。
postgres 儲存您的文件、使用者、工作區與權限。發布的映像檔是 pgvector/pgvector:pg16,也就是內建 pgvector 擴充功能的標準 Postgres 16。pgvector 將 vector 欄位類型加入 Postgres。這種數值格式用於儲存 embedding,讓系統能依文字的語意進行搜尋。
redis 是必要相依服務:伺服器與遷移工作都會等待其健康檢查通過後才啟動。請注意,發布的 compose 檔案並未為 Redis 提供 volume。其中的任何內容都不會在 docker compose down 後保留。這清楚表示其中不含您的資料,也不需要備份。
為什麼 Postgres 映像檔是 pgvector,而不是原版 postgres
這項需求來自 AFFiNE 的結構描述,而不是偏好設定。在 v0.27.4 中,schema.prisma 仍宣告 extensions = [pgvector(map: "vector")],但不含任何 embedding 欄位。在 v0.27.3 中,四個含有 embedding 欄位且型別為 vector(1024) 的模型,已不再出現在 v0.27.4。請保留提供的 pgvector/pgvector:pg16 映像檔:其中仍宣告該擴充功能,而原版 postgres:16 不包含此擴充功能。
官方的 v0.27.4 範本使用 pgvector 映像檔;v0.21.0 範本仍使用 postgres:16。如果是較舊的安裝,編輯映像檔那一行並不足以完成升級。因此,在拉取任何內容前,請先閱讀 AFFiNE 自架文件 中的升級頁面。
另外,請注意該標籤。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 release notes 列出的三種方式之一:將資料 dump 後還原至新的資料目錄、pg_upgrade,或使用邏輯複寫。在單一 Compose 安裝中,dump 與還原通常最簡單,因為 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 與其他常駐程序後,可能耗盡記憶體。接著,核心的 out-of-memory (OOM) killer 會終止程序以釋放記憶體。AFFiNE server 是最大的程序,因此很可能成為受害者;不過 Docker 文件也明確指出,任何程序都可能被選中,包括 Docker 本身。
如果被終止的是 AFFiNE server,同事不會看到錯誤訊息。他們只會看到頁面重新載入,因為 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 行,表示記憶體已耗盡,而不是發生程式錯誤。請從兩端處理。先加入 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 -hfree -h 現在應回報總計 2.0Gi 的 swap。swap 不會讓 AFFiNE 執行得更快,也不是為此設計的。它提供暫時的緩衝空間,讓突發的記憶體需求更可能只造成短暫延遲,而不是讓容器停止。這是緩衝,不是保證。另一端的修正方式,是停止 Postgres 將快取持續擴大到應用程式在合併時需要的空間;這就是 Compose 服務的記憶體限制 的用途。如果完成這兩項設定後仍持續發生程序遭終止的情況,使用較大型文件時,伺服器就需要 AFFiNE 需求頁面所要求的 4 GB。
儲存空間則容易得多。以下是 AFFiNE 在同一頁面發布的數據:
此圖表背後的資料
[
{
"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 下載現成檔案。這種方式可以正常運作。不過,在依賴該檔案前,有一項細節值得了解:截至 8 August 2026,隨附於 release 0.27.3 的檔案仍會使用 ${UPLOAD_LOCATION}、${CONFIG_LOCATION} 與 ${DB_DATA_LOCATION},從 .env 檔案讀取路徑;文件的參考頁面則已顯示較新的配置,將儲存資料與 PostgreSQL 資料放在 ./data 下、將設定放在 ./config 下,且完全不需要 .env。Release 0.27.4 已將隨附檔案改為該配置;截至 12 October 2026,兩者已一致。如果你是使用較舊的檔案完成安裝,路徑仍來自 .env。AFFiNE 的升級頁面警告,若替換 compose 檔案時未保留這些設定,Postgres 可能會以空白資料目錄啟動。自行撰寫檔案即可完全避免這個問題,而且你仍必須編輯檔案,以固定映像版本並設定資料庫密碼。
mkdir -p ~/affine/config ~/affine/data
cd ~/affine
printf 'DB_PASSWORD=%s\n' "$(openssl rand -hex 24)" > .env
chmod 600 .envCompose 會自行從專案目錄讀取 .env,並替你代入 ${DB_PASSWORD},因此密碼不會出現在你可能貼到支援討論串的檔案中。你執行的每個 stack 都應維持這項習慣,相關原因請參閱將 secret 排除在 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這份檔案與上游提供的檔案有 4 項差異,每一項都有其原因。
127.0.0.1:3010:3010只會在 loopback 位址上發布連接埠。28.0.0 之前的 Docker 版本允許同一個 L2 網段上的主機連線到發布至 localhost 的連接埠;如果啟用了 direct routing,即使發布至 loopback,也可能暴露容器連接埠。請使用 Docker 28.0.0 或更新版本,並在設定期間停用 direct routing。上游的'3010:3010'會繫結所有介面,而在多數 VPS 映像中,這也包含公開介面。POSTGRES_HOST_AUTH_METHOD: trust已移除,改為設定密碼。Trust authentication 允許任何連線到該資料庫的用戶端,以affine使用者身分且不需密碼通過驗證。這項設定僅限於私有 Compose network;但只要日後再將一個容器加入該 network,或為除錯而發布 5432,就可能造成問題。redis:8-alpine取代了單獨使用的redis,後者會解析至latest。截至 August 2026,該版本為 Redis 8,因此固定版本可保留已測試的 major version,並避免未來 Redis 9 在無關的docker compose pull期間到來。pgvector/pgvector:pg16維持上游的原設定,原因如上所述。
POSTGRES_PASSWORD 只會在 Postgres 首次建立資料目錄時讀取。對於已存在的 instance,請使用 docker compose exec postgres psql -U affine -c "ALTER USER affine WITH PASSWORD 'yourpassword'" 設定密碼,然後更新 DATABASE_URL 以保持一致。
設定位於 config/config.json
AFFiNE 會從 config/config.json 讀取設定;這就是您掛載到 /root/.affine/config 的目錄。系統不會替您建立該檔案,因此請在首次啟動前先建立。使用編輯器開啟 ~/affine/config/config.json,填入以下內容,並將範例中的網域替換成您自己的網域:
{
"$schema": "https://github.com/toeverything/affine/releases/latest/download/config.schema.json",
"server": {
"name": "Team workspace",
"externalUrl": "https://affine.example.com"
},
"copilot": {
"enabled": false,
"byok": {
"enabled": false
}
}
}server.externalUrl 必須是使用者實際在瀏覽器中開啟的網址。AFFiNE 會根據這個值建立分享連結與工作區邀請;如果保留為 http://localhost:3010,您發出的邀請會指向收件者自己的電腦,並在該處失效。請在首次啟動前將它設為公開的 HTTPS 位址,確保檔案中的設定與管理面板一致。之後在管理面板中變更的設定會儲存至資料庫,不會寫回此檔案。
copilot 控制 AI 功能。copilot.byok.enabled 是「自備金鑰」開關,可讓工作區擁有者在工作區設定中貼上自己的模型供應商金鑰。自行架設 AFFiNE 不包含 AI 訂閱。如果不需要 AI 功能,請保留兩者為 false。
啟動服務堆疊:
docker compose up -d
docker compose ps --alldocker compose ps --all 應將 affine_postgres 與 affine_redis 列為 healthy,將 affine_server 列為 running,並將 affine_migration_job 的狀態列為 exited (0)。--all 很重要:沒有它時,docker compose ps 只會顯示正在執行的容器,因此已正常完成的 migration 工作根本不會出現。migration 工作若回傳其他結束代碼,就必須進一步處理;其日誌會指出停止的步驟:
docker compose logs affine_migration固定映像版本,避免日後遺忘
stable 是會變動的 tag。AFFiNE 的發布流程會為每個穩定版本指向數個 tag,其中有兩個與此處相關:stable 會在每次發布時重新指向新版本,stable- 則會接在 git short hash 後方,且不會變動。若持續使用 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: 加上一長串 hash 的內容。將完整字串貼到 affine 與 affine_migration 的 image: 行。這兩處必須始終一致,因為它們是同一個映像所扮演的兩個角色;若不一致,可能會將資料庫 migration 至一種 schema,卻使用另一種 schema 提供服務。如此一來,升級會變成有意執行的編輯,而不是突發變更:修改 digest、備份、docker compose pull、docker compose up -d。
在其他人之前建立管理員帳號
在全新的 instance 上開啟 /admin 時,AFFiNE 會將你導向帳號建立頁面,因為伺服器尚未設定管理員。這個流程不需要 invitation code,也沒有 setup token。第一個完成註冊的人會成為伺服器的管理員,因此在完成註冊前,必須保持該連接埠關閉。
因此,上方的 compose file 會繫結至 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。此時才適合讓 instance 使用公開網域名稱。其他 self-hosted 應用程式也有相同的競爭問題;如果第一次登入會建立與主機名稱繫結的 passkey,風險會更高。因此,使用最終網域 self-host openGym 時,必須在建立第一個帳號前先完成 TLS 與最終網域的設定,詳見 自行架設 openGym。
AFFiNE 儲存資料的位置
以下 3 個路徑包含所有資料,而且都位於您建立的目錄中。
./data/postgres是 Postgres 資料目錄,包含文件、使用者、工作區、權限,以及從管理面板儲存的伺服器設定。./data/storage會掛載至容器中的/root/.affine/storage,包含所有上傳的檔案。./config會掛載至/root/.affine/config,包含config.json及 migration job 產生的private.key。
Upstream 在此使用 bind mount,而不是 named volume。這是刻意的設計:您可以使用一般指令 tar 和複製這些路徑,不必查詢 Docker 將資料存放在哪裡。代價是,主機上的檔案擁有者與權限由您負責。相關取捨請參閱 bind mount 與 named volume。
如何備份 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 輸出中的檔案大小。若檔案只有幾百 bytes,表示 dump 失敗,但 shell 仍然建立了檔案;這通常要到 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 一併納入備份,因為 dump 不包含這些內容。migration job 也會建立 config/private.key,因此只複製 config.json 會漏掉該檔案。儲存在管理面板中的設定位於資料庫內,因此上述 dump 已包含這些設定;截至 12 October 2026,AFFiNE 的備份頁面也指出,修改過的伺服器設定可從管理面板匯出。請將這 3 個檔案全部複製到伺服器外部。備份若與受保護的資料位於同一個磁碟上,就不算備份。這種資料庫 dump 搭配 uploads 目錄 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請注意使用 mv,而不是 rm。直接覆寫未保留副本的資料庫,可能讓一個錯誤指令造成全部資料遺失;先將舊目錄移到其他位置不會增加成本。也要使用 tar xzf backup/storage-2026-08-08.tgz -C data 復原上傳檔案,否則每份文件中的附件都會無法正常顯示。接著登入,開啟一份包含圖片的文件。這就是驗證方式。尚未在瀏覽器中開啟確認的復原結果只是檔案,不能算是備份。
將 AFFiNE 放在既有的 proxy 後方
AFFiNE 使用 WebSocket,而且這不是可選功能。官方文件明確指出:WebSocket 是 AFFiNE 同步與協作系統的基礎。因此,未升級這些連線的 proxy 會讓工作區停止同步,且不會明顯顯示錯誤。頁面可以載入,登入也能成功,但在一個瀏覽器中所做的修改不會出現在另一個瀏覽器中。請在瀏覽器的開發人員工具中開啟 Network 分頁,並篩選 WS。若某個連線反覆開啟又關閉,表示 proxy 未傳遞 upgrade。
如果你已經使用 Traefik 處理其他容器,AFFiNE 可作為一般服務加入其中。從 affine service 移除 ports: 區塊,然後加入:
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: truecertificate resolver 名稱必須與 Traefik 設定中定義的名稱一致,而 loadbalancer.server.port 是容器埠 3010,不是 host port。Traefik 不需額外設定即可 proxy WebSocket 連線,因此無須再加入其他內容。如果你的其他服務已經透過 Authentik 單一登入,可以在此 router 上加入 forward auth middleware,以限制瀏覽器對 AFFiNE 的存取;但請先不要啟用,直到你測試過 desktop app。desktop app 沒有瀏覽器 session,啟用後只會同步失敗。若要讓多個 app 由同一個 Traefik instance 處理,請參閱在多個 app 前方使用單一 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;
}nginx 中的 client_max_body_size 預設為 1 MB。因此,若沒有這一行,所有大於小型相片的上傳都會失敗並回傳 413 status,而 AFFiNE log 中不會出現任何內容,因為 request 根本沒有抵達。Caddy 只需加入一行 reverse_proxy http://127.0.0.1:3010,即可自行處理憑證與 WebSocket upgrade。
自架版本未包含的功能
在把團隊遷移過來之前,請先如實評估這些限制。
自架版本提供即時協作。這也是所有規模估算都著重的功能,因為 AFFiNE 官方文件指出,記憶體用量主要來自同步系統與文件合併。離線編輯是許多人選擇 local-first 工具的原因。桌面應用程式也能將自架伺服器加入工作區清單,並連線登入該伺服器。正式採用前,請先測試團隊實際依賴的離線行為:關閉網路後在桌面應用程式中編輯,重新連線,再於第二台裝置上檢查結果。功能清單不能作為證據,這份清單也一樣。
隨附的 compose 檔案未啟用伺服器端全文搜尋,其中 AFFINE_INDEXER_ENABLED=false 在伺服器與 migration job 上都設為該值。啟用全文搜尋需要加入 Manticore Search 容器。這會增加第 5 個服務,也會提高記憶體用量。在 2 GB 的主機上,這項變更可能讓整體資源需求超出上限。用戶端內建的搜尋仍可在目前開啟的工作區中使用。
邀請其他人加入前,有 2 項限制值得了解。自架工作區最多只能配置 10 個席位。超過此數量需要向 AFFiNE 取得 Team license。文件將自架實例的 unlimited blob storage 與 unlimited blob size 描述為預定支援的功能,但截至 2026 年 10 月仍未完全實作。對家庭或小型團隊而言,這 2 項限制通常沒有影響。如果你原本計畫讓 40 人使用,這 2 項限制都必須納入考量。
升級
先閱讀發行說明,尤其是 0.26 升至 0.27 這類次要版本升級,因為其中可能包含不相容變更。執行任何操作前,先備份資料庫與儲存目錄,因為遷移工作會在下次啟動時修改資料庫結構,而且無法復原。接著變更固定的 digest,執行 docker compose pull,再執行 docker compose up -d,並監看 docker compose logs -f affine_migration,直到程序正常結束。之後執行 docker image prune 清除舊的映像層。對於使用非常舊版本的安裝,還有一點歷史變更需要注意:自 0.23.0 起,映像名稱已從 affine-graphql 改為 affine,因此在執行 pull 前,較舊的 compose 檔案必須先改寫其中的映像名稱。自 0.27.4 起,官方 compose 範本也移動了 Postgres、upload 與 configuration 路徑,並變更預設資料庫連線設定。因此,請將新檔案與現有檔案比對,不要直接覆寫仍在運作的安裝。
FAQ
為什麼 AFFiNE 容器始終無法啟動?
affine 服務在 affine_migration 工作中宣告了 condition: service_completed_successfully。因此,只要遷移程序以非 0 狀態結束,伺服器就不會啟動,完全不會出現 Web 介面。執行 docker compose logs affine_migration,查看停止在哪個步驟。確認手動編輯的 Compose 檔案仍使用 pgvector/pgvector:pg16:標準 Postgres 不包含 pgvector 擴充功能,而 AFFiNE 的 schema 仍宣告需要此擴充功能;即使 v0.27.4 已不再定義 v0.27.3 中存在的 4 個 embedding model,情況仍然如此。
自架 AFFiNE 需要多少 RAM?
AFFiNE 的需求頁面要求至少 4 個 CPU 核心與 2 GB RAM。當文件超過 10,000 個字時,需求會提高至 4 GB。頁面也指出,合併包含 10,000 項修改的文件時,記憶體使用量可能暫時達到 1 GB。對 2 GB 伺服器而言,造成問題的是這個峰值,而不是閒置時的負載:kernel 的 out-of-memory killer 會選擇要停止的程序,最可能是占用量最大的 AFFiNE 伺服器,而 restart: unless-stopped 會再次啟動它。因此,使用者看到的是頁面重新載入,而不是錯誤訊息。使用 docker inspect affine_server --format '{{.State.OOMKilled}}' 和 sudo dmesg -T | grep -i 'out of memory' 確認此問題,接著新增 2 GB swap 檔案,以緩衝短暫的記憶體尖峰。如果程序仍持續被終止,請將 RAM 增加至 4 GB。
AFFiNE 將資料儲存在哪裡?應備份哪些內容?
Compose 目錄下的 3 個路徑包含所有資料:./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 支援即時協作嗎?
支援,不需要啟用任何額外設定。唯一的要求是反向代理設定正確,因為同步功能使用 WebSocket 連線。對 nginx 而言,這表示需要 proxy_http_version 1.1,以及 Upgrade 和 Connection: upgrade 標頭;Traefik 與 Caddy 會直接轉送這些連線,不需要額外設定。如果代理無法將連線升級,工作區仍會正常載入並完成登入,但在一個瀏覽器中所做的編輯不會出現在其他瀏覽器中。
可以使用標準 Postgres 映像執行 AFFiNE 嗎?
請使用 pgvector/pgvector:pg16,這是已編譯內建 pgvector 擴充功能的 Postgres 16。AFFiNE v0.27.4 仍在 schema.prisma 中宣告 extensions = [pgvector(map: "vector")],但已不再定義 v0.27.3 中具有 vector(1024) embedding 欄位的 4 個 model。標準 Postgres 不包含所宣告的擴充功能。如果改用外部 Postgres 伺服器,請在該伺服器上安裝 pgvector,並在目標資料庫中建立此擴充功能,再執行遷移程序。