跳到內容
Oleaflyv0.4.12

執行伺服器

儲存空間、備份與限制

Oleafly Server 的所有設定、把檔案存放在磁碟或 S3 儲存貯體、編譯的 PDF、在代理伺服器後方執行、適用於同一網路班級與每個帳號的限制、記錄、備份、還原與更新。

本頁說明如何日常維運 Oleafly Server。若要安裝,請先閱讀執行協作伺服器。

伺服器從環境變數讀取設定。已設定但內容為空的變數視同未設定。如果設定缺少或格式有誤,伺服器不會啟動,它的記錄會指出是哪一項。

變數作用預設值
OLEAFLY_PUBLIC_URL人們在 Oleafly 中輸入的 HTTPS 位址。可以包含路徑,例如 https://www.cs.example.edu/oleafly。必填。Compose 和 Coolify 的檔案會替你設定。無
OLEAFLY_BIND伺服器監聽的位址和連接埠。0.0.0.0:8080
OLEAFLY_DATA_DIR存放資料庫和已儲存檔案的資料夾。/data
OLEAFLY_SERVER_NAME人們在 Oleafly 中看到的名稱,例如 Smith Lab。Oleafly Server
OLEAFLY_SERVER_ICON_URL顯示在名稱旁邊的方形圖片的 HTTPS 位址。無
OLEAFLY_SETUP_CODE你自己訂的一次性設定碼:至少 12 個字母或數字,也可以加上連字號或空格。沒有設定時,伺服器會自己產生。自動產生
OLEAFLY_GITHUB_CLIENT_ID、OLEAFLY_GITHUB_CLIENT_SECRET開啟以 GitHub 登入。關閉
OLEAFLY_GITHUB_URLGitHub Enterprise Server 的位址。https://github.com
OLEAFLY_GITHUB_API_URLGitHub API 位址,適用於你的位址不尋常的情況。https://api.github.com,或 OLEAFLY_GITHUB_URL 下的 /api/v3
OLEAFLY_GITHUB_LABELGitHub 登入按鈕上的文字。GitHub
OLEAFLY_OIDC_<NAME>_ISSUER、OLEAFLY_OIDC_<NAME>_CLIENT_ID、OLEAFLY_OIDC_<NAME>_CLIENT_SECRET開啟名為 <NAME> 的 OpenID Connect 供應商。關閉
OLEAFLY_OIDC_<NAME>_LABEL該供應商登入按鈕上的文字,例如 University login。<NAME>
OLEAFLY_OIDC_<NAME>_TRUST_EMAIL把這個供應商提供的每個電子郵件地址都視為已驗證。請先閱讀已驗證的電子郵件地址。false
OLEAFLY_SMTP_URL、OLEAFLY_MAIL_FROM電子郵件。請閱讀電子郵件。關閉
OLEAFLY_OPEN_SIGNUP讓任何用你設定的其中一個供應商登入的人,都取得一個成員帳號。請閱讀開放註冊。false
OLEAFLY_WEB開啟瀏覽器存取。請閱讀瀏覽器存取。false
OLEAFLY_BLOB_STORE圖片和 PDF 等檔案的存放位置。fs 會把它們存放在 OLEAFLY_DATA_DIR。s3://lab-bucket 或 s3://lab-bucket/oleafly 這類位址則把它們存放在儲存貯體中。fs
OLEAFLY_S3_ENDPOINTAmazon S3 以外的 S3 相容儲存服務的位址,例如 MinIO 或 Cloudflare R2。使用 Amazon S3 時留空。Amazon S3
OLEAFLY_S3_REGION儲存貯體所在的區域。us-east-1
OLEAFLY_S3_ACCESS_KEY_ID、OLEAFLY_S3_SECRET_ACCESS_KEY伺服器存取儲存貯體所用的金鑰。使用 s3:// 位址時必填。無
OLEAFLY_MAX_PROJECT_MB伺服器接受的最大專案大小,單位為 MB。200
OLEAFLY_MAX_FILE_MB單一檔案的最大大小,單位為 MB。50
OLEAFLY_MAX_MEMBERS_PER_PROJECT單一專案的最多人數。20
OLEAFLY_ACCOUNT_STORAGE_MB單一帳號擁有的專案最多可以儲存多少,單位為 MB。請閱讀每個帳號的限制。無限制,開放註冊時為 100
OLEAFLY_MAX_PROJECTS_PER_ACCOUNT單一帳號最多可以擁有多少個共用專案。無限制,開放註冊時為 50
OLEAFLY_UPLOADS_PER_HOUR單一帳號在一小時內最多可以上傳多少次檔案和快照。無限制,開放註冊時為 300
OLEAFLY_SIGN_IN_BURST單一網路位址在一次突發中可以發出多少登入要求。一次登入大約需要六個要求,所以預設值足以讓同一位址下的 50 個人同時登入。300
OLEAFLY_SIGN_IN_PER_MINUTE突發用完之後,單一網路位址每分鐘可以補回多少登入要求。120
OLEAFLY_EMAIL_LINKS_PER_IP伺服器在 15 分鐘內,最多向同一個網路位址下的人寄出多少封登入信件。100
OLEAFLY_EMAIL_LINKS_PER_ADDRESS同一個電子郵件地址在 15 分鐘內最多可以收到多少封登入信件。不能超過 OLEAFLY_EMAIL_LINKS_PER_IP。3
OLEAFLY_DEVICE_CODES_PER_IP同一個網路位址下的人在 10 分鐘內最多可以要求多少組登入代碼。100
OLEAFLY_SNAPSHOT_MEMORY_MB伺服器建立專案快照時最多可以使用多少記憶體,單位為 MB。容器記憶體上限的一半,沒有上限時為 1024
OLEAFLY_BEHIND_PROXY從你的代理伺服器加入的 X-Forwarded-For 標頭取得每個人的位址。Compose、Coolify 和 Render 的檔案會將它開啟。false
OLEAFLY_PROXY_HOPS每個要求在抵達伺服器之前經過多少層代理伺服器。需要搭配 OLEAFLY_BEHIND_PROXY=true。1
OLEAFLY_LOG_LEVEL伺服器記錄多少內容:error、warn、info、debug 或 trace。除非你選擇 debug 或 trace,伺服器所用的程式庫只會記錄警告。info
OLEAFLY_SECURITY_LOG_DAYS安全記錄項目、專案存取記錄項目,以及已回覆或已過期的訪客邀請要保留多少天。365
OLEAFLY_ARCHIVE_DAYS專案的擁有者停止共用之後,要保留該專案多少天。30
OLEAFLY_POLL_HOLD_SECONDS沒有等待中的編輯時,伺服器讓一個長輪詢要求保持開啟多久,範圍是 1 到 40 秒。請讓它比伺服器前方任何代理伺服器的閒置逾時短幾秒。25

在 Compose 的 .env 檔案中,如果值含有 $ 或 #,請用單引號括起來。含有密鑰的設定也可以從檔案讀取。請閱讀不要把密鑰放在 .env 裡。

伺服器預設把所有內容都存放在 OLEAFLY_DATA_DIR:資料庫、人們共用的檔案和專案快照。快照是每個專案的已儲存副本,讓人們可以快速加入並趕上進度。

伺服器可以改把檔案和快照存放在 Amazon S3,或其他具有 S3 相容 API 的儲存服務,例如 MinIO 或 Cloudflare R2。無論哪種方式,資料庫都留在 OLEAFLY_DATA_DIR,所以伺服器仍然需要它的資料資料夾。

  1. 建立儲存貯體,並封鎖對它的公開存取。

  2. 建立一組金鑰,只能對該儲存貯體中的物件進行讀取、寫入和刪除,不能做其他事。在 Amazon S3 上,這表示對 arn:aws:s3:::lab-bucket/* 擁有 s3:GetObject、s3:PutObject 和 s3:DeleteObject;如果你使用資料夾,則是對 arn:aws:s3:::lab-bucket/oleafly/*。

  3. 設定變數,例如放在 .env 中:

    終端機視窗
    OLEAFLY_BLOB_STORE=s3://lab-bucket/oleafly
    OLEAFLY_S3_REGION=eu-west-1
    OLEAFLY_S3_ACCESS_KEY_ID=your-access-key-id
    OLEAFLY_S3_SECRET_ACCESS_KEY=your-secret-access-key

如果使用 Amazon S3 以外的儲存服務,還要把 OLEAFLY_S3_ENDPOINT 設為它的位址,例如 https://minio.example.org:9000 或 https://<account-id>.r2.cloudflarestorage.com,並把 OLEAFLY_S3_REGION 設為它預期的區域(R2 用 auto)。純 http:// 也可以使用,但只應在儲存服務與伺服器位於同一個私人網路時使用。

儲存貯體名稱之後的部分是選用的資料夾。每個檔案都以它的 SHA-256 雜湊值命名,並放在雜湊值前兩個字元所對應的資料夾下,所以雜湊值以 3f9a 開頭的檔案會存成 oleafly/3f/3f9a...。快照有自己的 snapshots 資料夾,每個專案各有一個資料夾。伺服器讀回檔案或快照時,會用雜湊值檢查位元組,並拒絕不符的內容。沒有使用儲存貯體時,同樣的結構位於 OLEAFLY_DATA_DIR 內的 blobs 資料夾。

如果儲存貯體拒絕某個要求,該次上傳或下載會失敗,伺服器記錄會顯示儲存貯體的回應,例如 403 Forbidden (AccessDenied)。伺服器錯誤、逾時或連線中斷則不同:伺服器最多會重試三次,每次之間隨機暫停一小段時間。如果無法刪除某個物件,伺服器會記下這件事,並在每次維護作業(每 6 小時一次)時再試一次,這樣中斷期間就不會留下殘留的物件。

專案共用時,擁有者的應用程式會上傳第一份快照,並用該裝置的金鑰簽署。從那之後,伺服器會自己建立每一份快照,依據前一份快照以及之後人們送出的變更。專案距離上一份快照累積 1,000 筆變更時,就會建立新的快照。伺服器永遠至少保留最近 2,000 筆變更,所以短暫離開的裝置可以從這些變更趕上進度,不必重新下載整個專案。

建立快照需要的記憶體,大約是前一份快照的大小加上之後變更大小的十倍。伺服器只會啟動符合 OLEAFLY_SNAPSHOT_MEMORY_MB 的建立作業,同時進行的建立作業共用這個額度。如果某次建立不符合額度,伺服器會略過它,記錄需要多少記憶體,並保留該專案的所有變更。裝置接著會從這些變更一次幾 MB 地趕上進度。調高這項設定,下一份快照就會建立。伺服器不會儲存大於 OLEAFLY_MAX_PROJECT_MB 的快照。

擁有者或編輯者成功編譯共用專案時,他們的應用程式會把 PDF 送到伺服器,如果有 SyncTeX 檔案也會一併送出。每個專案每分鐘最多送出一次。伺服器為每個專案保留一個 PDF 和一個 SyncTeX 檔案,並記錄主檔案的名稱,以及是誰在何時編譯的。瀏覽器存取會把這個 PDF 顯示給專案中的人。

每次上傳都會取代前一份,舊檔案在不再被使用後就會刪除。編譯的檔案與其他檔案存放在一起,也就是在磁碟上或儲存貯體中,並會隨專案一起刪除。編譯的檔案最大可以達到 OLEAFLY_MAX_FILE_MB。它會計入擁有者的帳號儲存空間,但不計入每小時的上傳次數。

專案的每個成員都可以讀取它的編譯檔案。只有擁有者和編輯者可以取代它們。

伺服器使用純 HTTP,所以前面要有東西處理 HTTPS:Compose 設定中的 Caddy、Coolify 的代理伺服器,或你已經在執行的網頁伺服器,例如你大學的網頁伺服器。無論前面是什麼,都必須:

  • 接受大小達 OLEAFLY_MAX_PROJECT_MB 的要求
  • 把用戶端的位址加入 X-Forwarded-For

它也應該把 WebSocket 升級要求傳遞到 /ws,並讓這些連線保持開啟至少一小時。即時編輯在可能時會使用它們。開啟瀏覽器存取時,它也必須把這些要求傳遞到 /web/ws,因為瀏覽器應用程式沒有較慢的替代途徑。

請讓伺服器只能由代理伺服器連到。在同一台機器上,設定 OLEAFLY_BIND=127.0.0.1:8080。然後設定 OLEAFLY_BEHIND_PROXY=true。

有些網路會封鎖 WebSocket 連線,常見於使用過濾代理伺服器的大學或公司網路。即時編輯在那裡仍然可以運作,只是比較慢。當連續兩次 WebSocket 嘗試都失敗,而伺服器仍能透過 HTTPS 回應時,Oleafly 會改用 HTTP 長輪詢。它把編輯送到 /api/v1/projects/<project>/frames,並在 /api/v1/projects/<project>/poll 等候其他人的編輯,每個要求最多保持開啟 OLEAFLY_POLL_HOLD_SECONDS。每一筆編輯仍然會送達。Oleafly 每分鐘會再試一次 WebSocket,一旦連上就立刻切換回去。

Oleafly 中的 測試連線 和管理主控台中的 連線檢查 會在這種情況發生時說明:「此網路封鎖了一般通道,所以即時編輯改走較慢的通道。編輯仍會送達。」

如果代理伺服器是你自己架設在伺服器前面的,無論如何都請讓它傳遞 WebSocket 升級要求。長輪詢可以運作,但每批編輯都要多一個要求,延遲也稍微多一些。

有些代理伺服器的逾時短於 30 秒,要求安靜超過這段時間就會被關閉,例如 proxy_read_timeout 設得很短的 nginx。它們會以 502 或 504 錯誤回應長輪詢要求,導致編輯延遲送達。請把 OLEAFLY_POLL_HOLD_SECONDS 設為比該逾時短幾秒,例如逾時為 10 秒時設為 8。

伺服器在兩個地方記錄用戶端位址:安全記錄,以及限制單一位址多常開始登入或開啟即時連線的限制。

沒有這項設定時,伺服器使用連到它的那個對象的位址。在代理伺服器後方,那永遠是代理伺服器,所以所有人共用同一個限制,安全記錄也只會顯示代理伺服器的位址。

設定 OLEAFLY_BEHIND_PROXY=true 後,伺服器會讀取 X-Forwarded-For 標頭,並使用其中最後一個位址,也就是你的代理伺服器加入的那一個。如果沒有這個標頭,或標頭中沒有有效的位址,伺服器會退回使用連線的位址。其他都不變。伺服器會忽略 X-Forwarded-Proto、X-Forwarded-Host 和 Forwarded,並根據 OLEAFLY_PUBLIC_URL 建立它發出的每一個位址。

只有在每個要求都經過你的代理伺服器時,才開啟這項設定。如果人們也能直接連到伺服器,任何人都可以送出捏造的 X-Forwarded-For,在安全記錄中放進任意位址,並繞過登入限制。

如果有兩個代理伺服器串在一起,例如 Cloudflare 位於 Coolify 的代理伺服器前面,請設定 OLEAFLY_PROXY_HOPS=2。伺服器接著會取倒數第二個位址。只計算每個要求都會經過的代理伺服器。直接通往伺服器的 Cloudflare Tunnel 算一個。

要檢查這個數字,請從你自己的電腦登入,並開啟管理主控台中的 安全性記錄。最新的項目應該顯示你的公開位址,也就是 ifconfig.me 這類網站回報的位址。如果它顯示的是私人位址或 Cloudflare 位址,請把 OLEAFLY_PROXY_HOPS 加一。

Caddy 不需要額外設定就會傳遞 WebSocket 連線和 X-Forwarded-For,並自行取得憑證。在前面加上 HTTPS 有完整的 Caddyfile。

請先為網域取得憑證,例如用 certbot。然後把以下內容儲存為 /etc/nginx/conf.d/oleafly.conf,並執行 sudo nginx -t && sudo systemctl reload nginx:

map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
server {
listen 443 ssl;
server_name collab.example.org;
ssl_certificate /etc/letsencrypt/live/collab.example.org/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/collab.example.org/privkey.pem;
location / {
proxy_pass http://127.0.0.1:8080;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
proxy_set_header X-Forwarded-For $remote_addr;
proxy_read_timeout 1h;
proxy_send_timeout 1h;
client_max_body_size 200m;
}
}

client_max_body_size 與 OLEAFLY_MAX_PROJECT_MB 的預設值 200 相符。調高其中一個時,另一個也要調高。

你需要 Apache 2.4.47 或更新版本,Debian 12 以及 Ubuntu 22.04 和之後的版本都有。請開啟這些模組:

終端機視窗
sudo a2enmod proxy proxy_http ssl

把以下內容儲存為 /etc/apache2/sites-available/oleafly.conf,然後執行 sudo a2ensite oleafly && sudo systemctl reload apache2:

<VirtualHost *:443>
ServerName collab.example.org
SSLEngine on
SSLCertificateFile /etc/letsencrypt/live/collab.example.org/fullchain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/collab.example.org/privkey.pem
ProxyPreserveHost On
ProxyPass / http://127.0.0.1:8080/ upgrade=websocket timeout=3600
ProxyPassReverse / http://127.0.0.1:8080/
</VirtualHost>

upgrade=websocket 會傳遞 WebSocket 連線,timeout=3600 讓它們保持開啟一小時。Apache 會自行把用戶端的位址加入 X-Forwarded-For。

如果伺服器位於某個路徑底下,請把該路徑包含在 OLEAFLY_PUBLIC_URL 中,例如 https://www.cs.example.edu/oleafly,以及你向登入供應商註冊的回呼位址中。伺服器對有路徑和沒有路徑的位址都會回應,所以你的代理伺服器可以保留路徑,也可以去掉它。使用 nginx 時,請用 location /oleafly/ {,裡面放同樣的幾行,並保持 proxy_pass http://127.0.0.1:8080; 不帶路徑,讓 nginx 把路徑傳遞下去。

整個班級經常從同一個網路位址登入,例如大學的 NAT。預設值就是為此設定的:

  • 登入:一個位址可以有 300 個登入要求的突發量,之後每秒兩個。一次登入大約需要六個要求,所以 50 個人可以同時登入。用 OLEAFLY_SIGN_IN_BURST 和 OLEAFLY_SIGN_IN_PER_MINUTE 變更這些數字。
  • 電子郵件連結:15 分鐘內寄給一個位址 100 個,寄給一個電子郵件地址 3 個。用 OLEAFLY_EMAIL_LINKS_PER_IP 和 OLEAFLY_EMAIL_LINKS_PER_ADDRESS 變更這些數字。
  • 登入代碼:同一個位址 10 分鐘內可以要求 100 組代碼,並輸入 10 次錯誤的代碼。用 OLEAFLY_DEVICE_CODES_PER_IP 變更。
  • 即時連線有自己較大的限制,所以同一個位址後方的整個班級可以在重新啟動後同時重新連線。只有無法證明自己工作階段的連線才會用掉這個額度:300 的突發量,之後每秒十個。能證明自己工作階段的連線,則是計入它自己的裝置,該裝置在一次突發中可以重新連線 60 次,之後每秒一次。

同一個 /64 網路中的所有 IPv6 位址都算作一個位址。只有在伺服器看到每個人的真實位址時,這些限制才會逐人生效,所以請正確設定你的代理伺服器。

伺服器每 30 秒會對每個即時連線發出一次 ping。如果連線 90 秒內都不回應這些 ping,或不再讀取伺服器送出的內容,伺服器就會關閉該連線。

專案限制對所有人都適用:整個專案用 OLEAFLY_MAX_PROJECT_MB(預設 200 MB),單一檔案用 OLEAFLY_MAX_FILE_MB(50 MB),單一專案的人數用 OLEAFLY_MAX_MEMBERS_PER_PROJECT(20)。管理主控台的 總覽 會顯示目前的限制。

有三項限制適用於每個帳號。在你設定之前,它們都是關閉的,除非開放註冊已開啟,這時會以下列預設值開啟它們:

限制設定開放註冊時
帳號擁有的專案的儲存空間OLEAFLY_ACCOUNT_STORAGE_MB100 MB
帳號擁有的共用專案OLEAFLY_MAX_PROJECTS_PER_ACCOUNT50
帳號一小時內的上傳次數OLEAFLY_UPLOADS_PER_HOUR300

你設定的值一律優先於預設值。每個值都必須是至少為 1 的整數。

  • 儲存空間:加總帳號擁有的每個專案(包括已封存的專案)的檔案和變更歷史,以及它們編譯的 PDF。快照不計入。任何人加入專案的檔案,都計入專案擁有者的額度。擁有者的帳號額滿後,伺服器會拒絕他們專案的新檔案和編譯的 PDF,他們也無法再共用其他專案。檔案會留在加入它的人的電腦上。人們輸入的文字仍會同步。
  • 共用專案:計算帳號共用的專案,包括仍在上傳中的專案。已封存的專案不計入,所以停止共用一個專案就能騰出空間。
  • 上傳:計算一小時期間內的每一次檔案和快照上傳。編譯的 PDF 不計入。被拒絕的檔案,Oleafly 稍後會自行再送一次。

管理主控台的 總覽 不會顯示這些限制。開放註冊開啟時,伺服器每次啟動都會在記錄中列出它們。

  • 伺服器記錄是 docker compose logs oleafly-server、Coolify 的 Logs 或 journalctl -u oleafly-server 所顯示的內容。OLEAFLY_LOG_LEVEL 決定它記錄多少。
  • 安全記錄記錄登入和被拒絕的登入、裝置、人員、角色、設定、專案和訪客,每一筆都有時間和 IP 位址。管理員和維護者在管理主控台的 安全性記錄 下閱讀。超過 OLEAFLY_SECURITY_LOG_DAYS 天的項目會被刪除。
  • 專案存取記錄記錄誰開啟過專案、加入專案或下載副本,並附上裝置名稱和時間。專案的擁有者在 允許專案存取記錄 開啟時可以將它開啟,而且只有該擁有者能閱讀。同樣適用上述保留期限。

完整備份需要什麼,取決於檔案存放在哪裡:

  • 磁碟上的檔案(OLEAFLY_BLOB_STORE=fs,預設):資料庫、檔案和快照都在資料資料夾中。備份整個資料夾。
  • 儲存貯體中的檔案:資料資料夾存放資料庫,儲存貯體存放檔案和快照。資料庫的副本加上儲存貯體就是完整備份。請為儲存貯體開啟版本控制,這樣誤刪的物件才能找回來。
伺服器把資料存在哪裡,以及要備份什麼檔案存放在磁碟上(預設)時,資料夾中有資料庫和 blobs 資料夾,後者存放檔案和快照,所以你要備份整個資料夾。檔案存放在儲存貯體時,資料夾中有資料庫,S3 儲存貯體存放檔案和快照,所以你要備份資料庫和儲存貯體。檔案在磁碟上(預設)檔案在儲存貯體中oleafly-server資料夾資料庫:帳號、設定、記錄blobs:檔案和快照備份整個資料夾oleafly-server資料夾資料庫S3 儲存貯體檔案與快照備份資料庫和儲存貯體伺服器把資料存在哪裡,以及要備份什麼檔案存放在磁碟上(預設)時,資料夾中有資料庫和 blobs 資料夾,後者存放檔案和快照,所以你要備份整個資料夾。檔案存放在儲存貯體時,資料夾中有資料庫,S3 儲存貯體存放檔案和快照,所以你要備份資料庫和儲存貯體。檔案在磁碟上(預設)檔案在儲存貯體中oleafly-server資料夾資料庫與 blobs(檔案、快照)備份整個資料夾oleafly-server資料夾資料庫S3 儲存貯體檔案與快照備份資料庫和儲存貯體
完整備份需要什麼,取決於檔案存放在哪裡。

請定期備份,並讓副本保持私密,因為它們含有每一個專案。你的設定(例如 .env)不在資料資料夾中,所以也要另外保留一份副本。

使用 Docker 時,複製磁碟區期間伺服器會停止幾秒。Oleafly 會自動重新連線。請在伺服器的資料夾中執行這些指令,如果你用了安裝程式,就是 /opt/oleafly-server。

終端機視窗
cd /opt/oleafly-server
sudo docker compose stop oleafly-server
sudo docker run --rm -v oleafly-server_oleafly-data:/data:ro -v "$PWD":/backup debian:13.7-slim tar -C /data -czf /backup/oleafly-data-$(date +%F).tar.gz .
sudo docker compose start oleafly-server

使用 systemd:

終端機視窗
sudo systemctl stop oleafly-server
sudo tar -C /var/lib/private/oleafly-server -czf /root/oleafly-data-$(date +%F).tar.gz .
sudo systemctl start oleafly-server

把封存檔複製到另一台機器。

在 Coolify 上,磁碟區的名稱以資源的 ID 開頭。用 docker volume ls --filter name=oleafly-data 找出它,用它取代 oleafly-server_oleafly-data,並從 Coolify 的儀表板停止和啟動伺服器,而不是使用 docker compose。

從未還原過的備份只是一種期望。這個演練會用備份啟動伺服器的第二個副本,不動正在執行的那一個,並檢查兩者是同一台伺服器。請用你自己封存檔的日期取代 2026-10-11。

終端機視窗
cd /opt/oleafly-server
sudo docker volume create oleafly-restore-drill
sudo docker run --rm -v oleafly-restore-drill:/data -v "$PWD":/backup:ro debian:13.7-slim tar -C /data -xzf /backup/oleafly-data-2026-10-11.tar.gz
sudo docker run -d --name oleafly-restore-drill -v oleafly-restore-drill:/data -e OLEAFLY_PUBLIC_URL=https://restore-drill.invalid -e OLEAFLY_GITHUB_CLIENT_ID=restore-drill -e OLEAFLY_GITHUB_CLIENT_SECRET=restore-drill "$(sudo docker compose images -q oleafly-server)"
sudo docker run --rm --network container:oleafly-restore-drill curlimages/curl:8.22.0 -fsS --retry 10 --retry-connrefused --retry-delay 1 http://127.0.0.1:8080/.well-known/oleafly-server
curl -fsS https://collab.example.org/.well-known/oleafly-server

兩個回應中的 server_id 必須相符。演練用的副本有一個無法讓任何人登入的 GitHub 登入佔位設定,也沒有開放的連接埠,所以沒有人能使用它。完成後請移除它:

終端機視窗
sudo docker rm -f oleafly-restore-drill
sudo docker volume rm oleafly-restore-drill

要用 Docker Compose 進行真正的還原,請停止伺服器,用封存檔取代磁碟區的內容,然後再次啟動:

終端機視窗
cd /opt/oleafly-server
sudo docker compose stop oleafly-server
sudo docker run --rm -v oleafly-server_oleafly-data:/data -v "$PWD":/backup:ro debian:13.7-slim sh -c 'find /data -mindepth 1 -delete && tar -C /data -xzf /backup/oleafly-data-2026-10-11.tar.gz'
sudo docker compose start oleafly-server

使用 systemd:

終端機視窗
sudo systemctl stop oleafly-server
sudo find /var/lib/private/oleafly-server -mindepth 1 -delete
sudo tar -C /var/lib/private/oleafly-server -xzf /root/oleafly-data-2026-10-11.tar.gz
sudo systemctl start oleafly-server

還原後的伺服器會缺少人們在備份之後所做的變更。每個應用程式重新連線時(無論是一直開著,還是之後才開啟)都會發現這件事,並重新送出自己缺少的變更。這不需要任何人動手。建立在別人缺少的變更之上的變更,會等到那個人開啟專案才處理,因為只有他們的應用程式能送出他們的變更。請要求在故障前後正在編輯的每個人各開啟專案一次。

封存檔只包含你製作時當下的內容。Litestream (在新分頁開啟) 會在伺服器資料庫的每筆變更發生後約一秒,把它複製到 S3 相容的儲存貯體。Compose 檔案內含它作為選用服務。

Litestream 只複製資料庫。如果檔案在儲存貯體中,儲存貯體已經包含檔案和快照,所以 Litestream 的副本加上儲存貯體,就能讓遺失的磁碟復原。如果檔案在磁碟上,請繼續為磁碟區製作封存檔,因為 Litestream 不會複製 blobs 資料夾。

  1. 建立一個只供這台伺服器的 Litestream 使用的儲存貯體,或儲存貯體中的資料夾。不要與 OLEAFLY_BLOB_STORE 共用。給 Litestream 一組金鑰,可以列出儲存貯體,並對其中的物件進行讀取、寫入和刪除。

  2. 把詳細資料加入 .env:

    終端機視窗
    LITESTREAM_REPLICA_URL=s3://lab-backups/oleafly-server
    LITESTREAM_REGION=eu-west-1
    LITESTREAM_ACCESS_KEY_ID=your-access-key-id
    LITESTREAM_SECRET_ACCESS_KEY=your-secret-access-key
    COMPOSE_PROFILES=litestream

    如果使用 Amazon S3 以外的儲存服務,還要把 LITESTREAM_ENDPOINT 設為它的位址,並把 LITESTREAM_REGION 設為它預期的區域(R2 用 auto)。COMPOSE_PROFILES 會讓每個 docker compose 指令都包含 Litestream。

  3. 啟動它:

    終端機視窗
    sudo docker compose up -d
  4. 檢查它是否已複製資料庫。這會印出含有 snapshot complete 的一行:

    終端機視窗
    sudo docker compose logs litestream | grep 'snapshot complete'

Litestream 每天做一次完整複製,並保留一週的副本以及其間的變更。排程在 litestream.yml 中。

這個演練會把資料庫從儲存貯體還原到暫用的磁碟區,在其上啟動伺服器的第二個副本,並檢查兩者是同一台伺服器。正在執行的伺服器不會受到影響。

終端機視窗
cd /opt/oleafly-server
sudo docker run --rm -v oleafly-litestream-drill:/data "$(sudo docker compose images -q oleafly-server)" --version
sudo docker compose run --rm --no-deps -v oleafly-litestream-drill:/restore litestream restore -config /etc/litestream.yml -o /restore/oleafly-server.sqlite3 /data/oleafly-server.sqlite3
sudo docker run -d --name oleafly-litestream-drill -v oleafly-litestream-drill:/data -e OLEAFLY_PUBLIC_URL=https://restore-drill.invalid -e OLEAFLY_GITHUB_CLIENT_ID=restore-drill -e OLEAFLY_GITHUB_CLIENT_SECRET=restore-drill "$(sudo docker compose images -q oleafly-server)"
sudo docker run --rm --network container:oleafly-litestream-drill curlimages/curl:8.22.0 -fsS --retry 10 --retry-connrefused --retry-delay 1 http://127.0.0.1:8080/.well-known/oleafly-server
curl -fsS https://collab.example.org/.well-known/oleafly-server

第一個指令會以伺服器需要的擁有者建立暫用的磁碟區。最後兩個回應中的 server_id 必須相符。完成後請移除副本:

終端機視窗
sudo docker rm -f oleafly-litestream-drill
sudo docker volume rm oleafly-litestream-drill

當資料庫檔案損毀或不見,但資料資料夾的其餘部分沒有問題時,請停止伺服器和 Litestream,移除資料庫的殘餘內容,還原後再重新啟動:

終端機視窗
cd /opt/oleafly-server
sudo docker compose stop oleafly-server litestream
sudo docker run --rm -v oleafly-server_oleafly-data:/data debian:13.7-slim rm -rf /data/oleafly-server.sqlite3 /data/oleafly-server.sqlite3-wal /data/oleafly-server.sqlite3-shm /data/.oleafly-server.sqlite3-litestream
sudo docker compose run --rm --no-deps litestream restore -config /etc/litestream.yml /data/oleafly-server.sqlite3
sudo docker compose up -d

如果磁碟遺失,而檔案在儲存貯體中,請在新的空磁碟區上執行上面的指令,並在 .env 中保留相同的儲存貯體設定。每個專案都會連同它的檔案和快照一起回來。

如果磁碟遺失,而檔案在磁碟上,請還原你最新的封存檔,到此為止。不要把 Litestream 較新的資料庫疊在較舊的封存檔上。資料庫會指向封存檔中沒有的檔案和快照,那些專案將無法開啟。

請先備份。伺服器會在新版本第一次啟動時更新它的資料庫,所以要回到較舊的版本,就必須還原你在更新前所做的備份。

  • 一行指令安裝:執行 curl -fsSL https://oleafly.com/server/install.sh | sudo sh -s -- update。它會保留 .env,取得新版本的檔案和映像檔,並重新啟動伺服器。
  • 手動使用 Docker Compose:照手動使用 Docker Compose的做法,把新版本的檔案下載到伺服器的資料夾,然後執行 sudo docker compose up -d。
  • Coolify:選取 Redeploy。使用已發布的映像檔時,這會拉取該映像檔標籤下的最新版本。
  • Render:開啟服務並啟動手動部署,這會再次拉取映像檔。
  • Railway:從它的選單重新部署服務。Railway 也可以自行更新來自 GitHub 登錄庫的映像檔。
  • systemd:照下載伺服器的做法安裝新版本,然後執行 sudo systemctl restart oleafly-server。

Oleafly 每次連線時都會檢查伺服器的版本。如果應用程式和伺服器無法搭配運作,Oleafly 會說明哪一個需要更新。

圖片預覽

無法載入 AI 回答

請再試一次,或搜尋文件。