# 儲存空間、備份與限制

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

本頁說明如何日常維運 Oleafly Server。若要安裝，請先閱讀[執行協作伺服器](/docs/collaboration/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_URL` | GitHub Enterprise Server 的位址。 | `https://github.com` |
| `OLEAFLY_GITHUB_API_URL` | GitHub API 位址，適用於你的位址不尋常的情況。 | `https://api.github.com`，或 `OLEAFLY_GITHUB_URL` 下的 `/api/v3` |
| `OLEAFLY_GITHUB_LABEL` | GitHub 登入按鈕上的文字。 | `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` | 把這個供應商提供的每個電子郵件地址都視為已驗證。請先閱讀[已驗證的電子郵件地址](/docs/collaboration/server-access/#verified-email-addresses)。 | `false` |
| `OLEAFLY_SMTP_URL`、`OLEAFLY_MAIL_FROM` | 電子郵件。請閱讀[電子郵件](/docs/collaboration/server-access/#email)。 | 關閉 |
| `OLEAFLY_OPEN_SIGNUP` | 讓任何用你設定的其中一個供應商登入的人，都取得一個成員帳號。請閱讀[開放註冊](/docs/collaboration/server-access/#open-sign-up)。 | `false` |
| `OLEAFLY_WEB` | 開啟瀏覽器存取。請閱讀[瀏覽器存取](/docs/collaboration/server-access/#browser-access)。 | `false` |
| `OLEAFLY_BLOB_STORE` | 圖片和 PDF 等檔案的存放位置。`fs` 會把它們存放在 `OLEAFLY_DATA_DIR`。`s3://lab-bucket` 或 `s3://lab-bucket/oleafly` 這類位址則把它們存放在儲存貯體中。 | `fs` |
| `OLEAFLY_S3_ENDPOINT` | Amazon 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。請閱讀[每個帳號的限制](#limits-per-account)。 | 無限制，開放註冊時為 `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 裡](/docs/collaboration/server/#keep-secrets-out-of-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` 中：

   ```sh
   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

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

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

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

## 在反向代理後方

伺服器使用純 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 連線，常見於使用過濾代理伺服器的大學或公司網路。即時編輯在那裡仍然可以運作，只是比較慢。當連續兩次 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 會改變什麼

伺服器在兩個地方記錄用戶端位址：安全記錄，以及限制單一位址多常開始登入或開啟即時連線的[限制](#limits-for-a-class-on-one-network)。

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

設定 `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

Caddy 不需要額外設定就會傳遞 WebSocket 連線和 `X-Forwarded-For`，並自行取得憑證。[在前面加上 HTTPS](/docs/collaboration/server/#put-https-in-front) 有完整的 `Caddyfile`。

### nginx

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

```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

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

```sh
sudo a2enmod proxy proxy_http ssl
```

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

```apache
<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 位址都算作一個位址。只有在伺服器看到每個人的真實位址時，這些限制才會逐人生效，所以請[正確設定你的代理伺服器](#what-oleafly_behind_proxy-changes)。

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

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

## 每個帳號的限制

有三項限制適用於每個帳號。在你設定之前，它們都是關閉的，除非[開放註冊](/docs/collaboration/server-access/#open-sign-up)已開啟，這時會以下列預設值開啟它們：

| 限制 | 設定 | 開放註冊時 |
| --- | --- | --- |
| 帳號擁有的專案的儲存空間 | `OLEAFLY_ACCOUNT_STORAGE_MB` | 100 MB |
| 帳號擁有的共用專案 | `OLEAFLY_MAX_PROJECTS_PER_ACCOUNT` | 50 |
| 帳號一小時內的上傳次數 | `OLEAFLY_UPLOADS_PER_HOUR` | 300 |

你設定的值一律優先於預設值。每個值都必須是至少為 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`，預設）：資料庫、檔案和快照都在資料資料夾中。備份整個資料夾。
- **儲存貯體中的檔案**：資料資料夾存放資料庫，儲存貯體存放檔案和快照。資料庫的副本加上儲存貯體就是完整備份。請為儲存貯體開啟版本控制，這樣誤刪的物件才能找回來。

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

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

```sh
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：

```sh
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`。

```sh
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 登入佔位設定，也沒有開放的連接埠，所以沒有人能使用它。完成後請移除它：

```sh
sudo docker rm -f oleafly-restore-drill
sudo docker volume rm oleafly-restore-drill
```

### 還原

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

```sh
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：

```sh
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 持續複製

封存檔只包含你製作時當下的內容。[Litestream](https://litestream.io) 會在伺服器資料庫的每筆變更發生後約一秒，把它複製到 S3 相容的儲存貯體。Compose 檔案內含它作為選用服務。

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

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

   ```sh
   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. 啟動它：

   ```sh
   sudo docker compose up -d
   ```

4. 檢查它是否已複製資料庫。這會印出含有 `snapshot complete` 的一行：

   ```sh
   sudo docker compose logs litestream | grep 'snapshot complete'
   ```

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

#### Litestream 還原演練

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

```sh
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` 必須相符。完成後請移除副本：

```sh
sudo docker rm -f oleafly-litestream-drill
sudo docker volume rm oleafly-litestream-drill
```

#### 從 Litestream 還原資料庫

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

```sh
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` 中保留相同的儲存貯體設定。每個專案都會連同它的檔案和快照一起回來。

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

## 更新

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

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

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