# 執行協作伺服器

Oleafly Server 存放什麼、需要什麼，以及如何用一行指令安裝，或用 Docker Compose、Coolify、Render、Railway 或一般的 Linux 服務執行它，然後成為第一位管理員。

Oleafly Server 是即時協作背後的協作伺服器。你的實驗室、系所或機構在自己的機器或自己的雲端帳號上執行它。人們在 Oleafly 中新增它，並用已有的帳號登入，例如 GitHub 或大學的登入。有人在伺服器上共用專案時，被他們加入的人會取得一份完整的副本，並在編輯期間保持同步。開啟[瀏覽器存取](/docs/collaboration/server-access/#browser-access)後，他們也可以在網頁瀏覽器中開啟專案。

本指南寫給替實驗室、課程或共同作者群組執行伺服器的人。你應該習慣使用終端機。部分安裝方式也會要求你編輯設定檔。你不需要撰寫程式碼。

進行安全性審查時，請閱讀[伺服器安全性](/security/)。它涵蓋自行架設、登入、裝置金鑰、已簽署的變更、安全記錄和存取記錄，以及容器映像檔及其軟體物料清單。

## 伺服器存放什麼

伺服器把所有內容都存放在一個資料資料夾中，由 `OLEAFLY_DATA_DIR` 設定：

- **帳號**：每位成員的顯示名稱、頭像位址、已驗證的電子郵件地址，以及他們在登入供應商的使用者 ID 和登入名稱。伺服器從不看到或儲存密碼。
- **裝置**：每一台登入過的電腦，包含它的名稱、作業系統、公開金鑰和最後一次出現的時間。登入權杖只以雜湊值儲存。
- **安全記錄**：登入和被拒絕的登入、新增和登出的裝置、成員、角色和設定的變更、已共用、已封存和已還原的專案、誰能開啟專案的變更，以及訪客邀請。每筆項目都有時間和 IP 位址。
- 管理員在 Oleafly 中變更的**伺服器設定**。
- **專案存取記錄**，適用於擁有者開啟此功能的專案：誰開啟了專案、加入專案或下載了副本，並附上裝置名稱和時間。只有專案的擁有者可以閱讀。
- **訪客邀請**：受邀的電子郵件地址、專案、角色，以及寄出邀請的人。
- **共用專案**：每個檔案以及完整的變更歷史，還有屬於它們的留言、建議、聊天與版本名稱。
- **編譯的 PDF**：每個共用專案最新的 PDF 及其 SyncTeX 檔案，由擁有者或編輯者的應用程式在編譯成功後送出，並記錄是誰在何時編譯的。

安全記錄和存取記錄中的項目，以及已回覆或已過期的訪客邀請，會在 `OLEAFLY_SECURITY_LOG_DAYS` 天後刪除，預設為 365 天。專案不再使用的檔案，例如被取代的圖片的舊副本，會在專案最後一次使用它們的 30 天後刪除。每份編譯的 PDF 都會取代前一份。擁有者停止共用專案時，伺服器會讓它保持唯讀 `OLEAFLY_ARCHIVE_DAYS` 天，預設為 30 天，然後刪除。在這段期間內，只有擁有者和專案中的管理員可以下載它。

### 誰能讀取專案

專案在伺服器上沒有加密。任何能讀取資料資料夾、機器磁碟或你的備份的人，都能讀取存放在那裡的每個專案。這包括執行這台機器的人，以及代管它的公司。

在 Oleafly 內部，規則更嚴格。除非專案的擁有者把他們加進去，否則沒有任何伺服器角色（包括管理員）能開啟專案。如果某個專案必須避開執行伺服器的人，請為它另外執行一台伺服器。

每位成員的電腦也會保留與他們共用的每個專案的完整副本。請要求成員開啟磁碟加密，例如 macOS 上的 FileVault、Windows 上的 BitLocker，或 Linux 上的 LUKS。

## 你需要什麼

- **一台持續開機的機器**。任何 Linux 機器都可以，也可以使用 Render 或 Railway 這類代管服務的帳號。一台小型虛擬機器就足以開始。隨著專案增加，請留意它的記憶體和磁碟。伺服器可在 x86-64 和 ARM 上執行。
- 伺服器用的**網域名稱**，例如 `collab.example.org`，並有一筆指向該機器的 DNS 記錄。如果你沒有網域，Render 和 Railway 會給你一個位址。如果機器沒有公開位址，請閱讀[沒有公開位址時](#without-a-public-address)。
- **讓人們登入的方式**：至少一個登入供應商，例如 GitHub OAuth 應用程式或你機構的登入。沒有它，伺服器無法啟動。伺服器可用來寄信的電子郵件帳號是選用的。有了它，管理員還可以讓人們用寄來的連結登入。請閱讀[登入與存取](/docs/collaboration/server-access/)。

每個版本都會以容器映像檔 `ghcr.io/oleafly/oleafly-server` 發布。安裝程式及其 Compose 檔案位於 [Oleafly Server 版本頁面](https://github.com/Oleafly/oleafly-server/releases)。單一 Linux 程式形式的伺服器位於 [Oleafly 版本頁面](https://github.com/Oleafly/Oleafly/releases)。

## 選擇執行方式

| 選項 | 適用情況 |
| --- | --- |
| [一行指令](#install-with-one-command) | 你自己維護的 Linux 機器。安裝程式會設定 Docker、Caddy 和 HTTPS，並問幾個問題。如果不確定，就從這裡開始。 |
| [手動使用 Docker Compose](#docker-compose-by-hand) | 你比較想自己放置並編輯每個檔案。 |
| [Coolify](#coolify) | 你已經在執行 Coolify 伺服器。 |
| [Render](#render)或 [Railway](#railway) | 你寧可付費給代管服務，也不想自己維護機器。 |
| [不使用 Docker 的 Linux](#linux-without-docker) | 無法使用 Docker 的大學虛擬機器。 |

伺服器從環境變數讀取設定。[儲存空間、備份與限制](/docs/collaboration/server-operations/#settings)列出了每一項。

## 用一行指令安裝

在你自己維護的 Linux 機器上，安裝程式會設定好一切，並且只問它需要知道的事。

執行之前，請確認：

- 機器執行的是 x86-64 或 ARM 上的 Linux，例如 Ubuntu 24.04 或 Debian 13，而且你可以在上面使用 `sudo`。
- 機器上沒有其他程式使用連接埠 80 和 443。請在它前面的任何防火牆中開放 TCP 連接埠 80 和 443，以及 UDP 連接埠 443。
- 你網域的 DNS 記錄指向這台機器。如果還沒有，安裝仍會完成，Caddy 會持續嘗試取得憑證，直到記錄就位。
- 你有至少一個[登入供應商](/docs/collaboration/server-access/#sign-in-providers)的詳細資料，例如 GitHub OAuth 應用程式的 client ID 和密鑰。對 GitHub 而言，回呼位址是 `https://` 加上你的網域，再接 `/auth/callback/github`。

:::note[測試期間]
請安裝候選版本 Oleafly Server 0.1.1-rc，讓伺服器與 Oleafly 0.4.7-rc 相符：

```sh
curl -fsSL https://github.com/Oleafly/oleafly-server/releases/download/server-v0.1.1-rc/install.sh | sudo sh
```

下面的指令安裝的是較舊的 0.1.0。如果你用其他方式執行映像檔，例如 Compose、Coolify、Render 或 Railway，請使用 `ghcr.io/oleafly/oleafly-server:0.1.1-rc`。
:::

然後執行：

```sh
curl -fsSL https://oleafly.com/server/install.sh | sudo sh
```

安裝程式會：

1. 檢查機器，以及連接埠 80 和 443 是否空閒。
2. 檢查 Docker。如果沒有，安裝程式會先詢問，再用 Docker 自己的指令碼安裝它。
3. 從 [Oleafly Server 版本頁面](https://github.com/Oleafly/oleafly-server/releases)下載最新版本的檔案，並用該版本的 `SHA256SUMS` 檢查每一個檔案。如果有檔案不符，它會停止，不做任何變更。
4. 詢問你的網域、伺服器名稱，以及人們如何登入。它也會提議設定電子郵件，以及把檔案存放在 S3 儲存貯體中。兩者都是選用的。
5. 顯示摘要，並在變更任何內容之前詢問。接著把它的檔案寫入 `/opt/oleafly-server`，你的設定放在 `.env` 中，只有 root 可以讀取。
6. 啟動前面有 Caddy 的伺服器，等到你的網域透過 HTTPS 回應，然後印出位址和設定碼。

然後[成為第一位管理員](#become-the-first-admin)。

你可以隨時再次執行安裝程式。當它在 `/opt/oleafly-server` 中找到伺服器時，會保留 `.env` 原樣，補回其他檔案，並重新啟動伺服器。這可以修復大多數壞掉的設定。

你的資料存放在 Docker 磁碟區 `oleafly-server_oleafly-data` 中。若要安裝在 `/opt/oleafly-server` 以外的位置，請設定 `OLEAFLY_DIR`，例如 `curl -fsSL https://oleafly.com/server/install.sh | sudo OLEAFLY_DIR=/srv/oleafly sh`，並在下面的指令中使用該資料夾。

### 先閱讀安裝程式

如果你的機構不允許把指令碼透過管道傳給 shell，請從[最新版本](https://github.com/Oleafly/oleafly-server/releases/latest)把 `install.sh` 和 `SHA256SUMS` 下載到同一個資料夾。檢查指令碼、閱讀它，然後執行：

```sh
sha256sum --check --ignore-missing SHA256SUMS
sudo sh install.sh
```

### 不經提問的安裝

若要用於指令碼或佈建工具，請加上 `--yes`，並以環境變數傳入答案。`OLEAFLY_INSTALL_DOCKER=yes` 讓安裝程式在缺少 Docker 時自行加入。

```sh
curl -fsSL https://oleafly.com/server/install.sh | sudo \
  OLEAFLY_DOMAIN=collab.example.org \
  OLEAFLY_SERVER_NAME='Smith Lab' \
  OLEAFLY_GITHUB_CLIENT_ID=Ov23liExampleClientId \
  OLEAFLY_GITHUB_CLIENT_SECRET=example-client-secret \
  OLEAFLY_INSTALL_DOCKER=yes \
  sh -s -- --yes
```

無論有沒有 `--yes`，安裝程式都會直接使用它在環境中找到的任何設定，不會再詢問。`sudo sh /opt/oleafly-server/install.sh --help` 會列出所有設定，包括 OpenID Connect、電子郵件和 S3。在指令列上輸入的值可能會留在你的 shell 歷史記錄中，所以佈建工具應該從自己的密鑰儲存區傳入密鑰。

### 狀態、更新與移除

- **狀態**：`sudo sh /opt/oleafly-server/install.sh status` 會顯示伺服器是否正在執行，以及你的網域是否透過 HTTPS 以有效憑證回應。
- **更新**：先備份，如[更新](/docs/collaboration/server-operations/#updating)所述。然後執行下面的指令。它會下載最新版本的檔案和映像檔，保留 `.env`，重新啟動伺服器，並等到它回應。已連線的人會自動重新連線。安裝程式從不會把伺服器移到較舊的版本。

  ```sh
  curl -fsSL https://oleafly.com/server/install.sh | sudo sh -s -- update
  ```

- **解除安裝**：`sudo sh /opt/oleafly-server/install.sh uninstall` 會停止並移除容器。除非它詢問時你輸入 `delete`，否則你的資料和 `.env` 會保留。刪除它們會移除伺服器上的每個共用專案、每個帳號和安全記錄。人們在自己的電腦上仍保有專案的副本。

如果安裝程式因為你無法解決的問題而停止，請[回報](https://github.com/Oleafly/oleafly-server/issues/new/choose)，並附上它印出的內容。

## 手動使用 Docker Compose

這個設定會執行兩個容器。`oleafly-server` 是伺服器，只有其他容器可以連到它。`caddy` 會從 Let's Encrypt 取得憑證，在連接埠 80 和 443 上提供 HTTPS，並把要求（包括即時連線）傳遞給伺服器。

1. 依照 [Docker 的說明](https://docs.docker.com/engine/install/)安裝 Docker Engine 和 Compose 外掛程式。
2. 把你網域的 DNS 記錄指向這台機器。在它前面的任何防火牆中開放 TCP 連接埠 80 和 443，以及 UDP 連接埠 443。Caddy 需要連接埠 80 來取得憑證。
3. 為伺服器建立一個資料夾，把最新版本的檔案下載到其中，檢查它們，並建立你的設定檔：

   ```sh
   sudo mkdir -p /opt/oleafly-server && cd /opt/oleafly-server
   base=https://github.com/Oleafly/oleafly-server/releases/latest/download
   for f in docker-compose.yml Caddyfile env.example litestream.yml SHA256SUMS; do sudo curl -fsSLO "$base/$f"; done
   sha256sum --check --ignore-missing SHA256SUMS
   sudo install -m 600 env.example .env
   ```

4. 用 `sudoedit .env` 編輯 `.env`。把 `OLEAFLY_DOMAIN` 設為你的網域（不含 `https://`），設定 `OLEAFLY_SERVER_NAME`，並至少填入一個[登入供應商](/docs/collaboration/server-access/#sign-in-providers)。你沒有使用的供應商那幾行請留空。如果值含有 `$` 或 `#`，請用單引號括起來。
5. 啟動它。第一次啟動時，會下載該版本對應的伺服器映像檔 `ghcr.io/oleafly/oleafly-server`。

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

6. 檢查它是否回應。這會印出 `200`：

   ```sh
   curl -sS -o /dev/null -w '%{http_code}\n' https://collab.example.org/healthz
   ```

7. [成為第一位管理員](#become-the-first-admin)。設定碼在記錄中：

   ```sh
   sudo docker compose logs oleafly-server | grep 'Setup code'
   ```

你的資料存放在 Docker 磁碟區 `oleafly-server_oleafly-data` 中。Caddy 把它的憑證存放在 `oleafly-server_caddy-data` 中。

即使主機防火牆（例如 `ufw`）已開啟，Docker 也會自行開放連接埠 80 和 443。這正是 Caddy 所需要的。不要在 `oleafly-server` 服務中加入 `ports:` 項目。若要從機器本身連到伺服器，請把它發布為 `127.0.0.1:8080:8080`，讓它不出現在網路上。

如果你變更了 `Caddyfile`，請執行 `sudo docker compose up -d --force-recreate caddy`。之後要更新時，用同樣的方式下載新版本的檔案，再執行一次 `sudo docker compose up -d`。

### 不要把密鑰放在 .env 裡

有七項設定可以存放密鑰：`OLEAFLY_SETUP_CODE`、`OLEAFLY_GITHUB_CLIENT_SECRET`、`OLEAFLY_OIDC_<NAME>_CLIENT_SECRET`、`OLEAFLY_SMTP_URL`、`OLEAFLY_BLOB_STORE`、`OLEAFLY_S3_ACCESS_KEY_ID` 和 `OLEAFLY_S3_SECRET_ACCESS_KEY`。每一項也都有一個 `_FILE` 版本，指定存放該值的檔案。兩者擇一設定，不要同時設定。

例如，若要把 GitHub client 密鑰當成 Docker 密鑰傳入，請把它存到 `docker-compose.yml` 旁的 `secrets/github_client_secret`，讓伺服器的使用者（ID 10001）可以讀取，並刪除 `.env` 中的 `OLEAFLY_GITHUB_CLIENT_SECRET` 那一行：

```sh
sudo chown 10001:10001 secrets/github_client_secret
sudo chmod 400 secrets/github_client_secret
```

然後在 `docker-compose.yml` 旁建立 `docker-compose.override.yml`。Compose 會自動讀取它，安裝程式更新其他檔案時也不會動它。

```yaml
services:
  oleafly-server:
    environment:
      OLEAFLY_GITHUB_CLIENT_SECRET_FILE: /run/secrets/github_client_secret
    secrets:
      - github_client_secret

secrets:
  github_client_secret:
    file: ./secrets/github_client_secret
```

再執行一次 `sudo docker compose up -d`。

## Coolify

Coolify 會在伺服器前面放自己的代理伺服器並取得憑證，所以這個設定沒有 Caddy。Coolify 可以從 Oleafly 儲存庫建置伺服器，也可以執行[已發布的映像檔](#deploy-the-published-image)，後者會略過建置。

開始之前，請把你網域的 DNS 記錄（例如 `collab.example.org`）指向 Coolify 伺服器。然後依照 [GitHub](/docs/collaboration/server-access/#github) 中的說明建立 GitHub OAuth 應用程式，回呼位址為 `https://collab.example.org/auth/callback/github`。請把它的 client ID 和密鑰放在手邊。

### 從儲存庫建置

1. 在你的 Coolify 專案中，選取 **+ New**，再選取 **Public Repository**，並輸入 `https://github.com/Oleafly/Oleafly`。分支保持 `main`。
2. 把 **Build Pack** 設為 **Docker Compose**，**Base Directory** 設為 `/`，**Docker Compose Location** 設為 `/deploy/server/docker-compose.coolify.yml`，然後選取 **Continue**。
3. 在 **Advanced › Build** 下，把 **Build arguments** 設為 **Managed manually in Dockerfile**。伺服器的映像檔不需要建置引數。如果保持自動，Coolify 會把每個變數（包括密鑰）寫進映像檔的建置歷史。
4. 在 **General** 下，把 `oleafly-server` 的網域設為 `https://collab.example.org:8080` 並儲存。`:8080` 告訴 Coolify 的代理伺服器，伺服器在哪個連接埠上監聽。人們仍然使用一般的 HTTPS 連接埠連線，Coolify 會替你把 `OLEAFLY_PUBLIC_URL` 設為 `https://collab.example.org`。
5. 在 **Environment Variables** 下，填入 Coolify 標示為必填的 `OLEAFLY_SERVER_NAME`，接著填入 `OLEAFLY_GITHUB_CLIENT_ID` 和 `OLEAFLY_GITHUB_CLIENT_SECRET`。你沒有使用的變數請留空。
6. 選取 **Deploy**。第一次建置會編譯伺服器，需要幾分鐘。完成後，Coolify 會顯示該資源正在執行且狀況良好。
7. 在瀏覽器中開啟 `https://collab.example.org/healthz`。它會顯示 `{"status":"ok"}`。
8. 開啟 **Logs**，選擇 `oleafly-server` 容器，並從以 `Setup code:` 開頭的最新一行複製代碼。
9. 用那組代碼[成為第一位管理員](#become-the-first-admin)。

如果伺服器無法啟動，它的記錄會指出它無法使用的設定。當記錄說 `OLEAFLY_PUBLIC_URL` 沒有設定時，就是少了第 4 步。以 `http://` 開頭的網域會被拒絕，因為伺服器需要 HTTPS。

如果 Cloudflare 位於 Coolify 前面，也就是你的 DNS 記錄經過 Cloudflare 的代理，或有通道通往 Coolify 的代理伺服器，請把 `OLEAFLY_PROXY_HOPS` 設為 `2`。沒有它，安全記錄會替所有人顯示代理伺服器的位址，他們也會共用同一個登入限制。

Coolify 檔案中預留了 GitHub，以及一個名為 `UNIVERSITY` 的 OpenID Connect 供應商。請把 `OLEAFLY_OIDC_UNIVERSITY_LABEL` 設為人們應該看到的文字，例如 `GitLab`。它的回呼位址以 `/auth/callback/university` 結尾。若要使用更多供應商，請從你的分叉部署，並使用你自己的檔案副本。

資料存放在名稱以 `oleafly-data` 結尾的 Docker 磁碟區中。用 `docker volume ls --filter name=oleafly-data` 找出它。映像檔沒有 shell，所以 Coolify 的 **Terminal** 無法在伺服器的容器中開啟 shell。記錄和健康檢查則照常運作。

### 部署已發布的映像檔

執行已發布的映像檔會略過建置，適合小型的 Coolify 伺服器。依照上面的步驟進行，只有兩處不同。在第 2 步，把 **Docker Compose Location** 設為 `/deploy/server/docker-compose.coolify-image.yml`。跳過第 3 步，因為不會建置任何東西。該檔案追蹤單一版本系列，所以每次 **Redeploy** 都會拉取該系列中的最新版本。

## Render

[Deploy to Render](https://render.com/deploy?repo=https://github.com/Oleafly/Oleafly) 會讀取 Oleafly 儲存庫中的 Blueprint。它從已發布的映像檔建立一個網頁服務，並為資料資料夾配置 1 GB 的磁碟。Render 只會把磁碟連接到付費的執行個體類型，所以服務會從最小的付費類型開始，位於 Render 的 Oregon 區域。若要使用其他區域，請從分叉部署，並在 `render.yaml` 中設定 `region`。

1. 開啟連結並登入 Render。
2. Render 會要求輸入 `OLEAFLY_SERVER_NAME` 以及 GitHub client ID 和密鑰。填入名稱，GitHub 欄位暫時留空。它們的回呼位址取決於服務的位址，而你現在還沒有。
3. 選取 **Deploy Blueprint**。服務上線後，它的頁面會顯示它的位址，例如 `https://oleafly-server.onrender.com`。Blueprint 會把 `OLEAFLY_PUBLIC_URL` 設為該位址。
4. 依照 [GitHub](/docs/collaboration/server-access/#github) 中的說明建立 GitHub OAuth 應用程式，以該位址加上 `/auth/callback/github` 作為回呼位址。把 client ID 和密鑰加到服務的 **Environment** 下。Render 會帶著它們重新啟動伺服器。
5. 在服務的 **Logs** 中找到最新的 `Setup code:` 那一行，然後[成為第一位管理員](#become-the-first-admin)。

如果你為服務設定了自己的網域，請在 **Environment** 下把 `OLEAFLY_PUBLIC_URL` 設為該網域，並在 GitHub 上把回呼位址改成相符的內容。

由於有磁碟，Render 會先停止正在執行的伺服器，才啟動新的伺服器，所以每次部署都會讓伺服器離線幾秒。Oleafly 會自動重新連線。

## Railway

Railway 會執行已發布的映像檔，並為資料資料夾配置一個磁碟區。

1. 在 Railway 專案中，選取 **+ New**，再選取 **Docker Image**，並輸入 `ghcr.io/oleafly/oleafly-server:latest`。若要自行選擇何時升級，請改用[版本頁面](https://github.com/Oleafly/Oleafly/releases)上某個版本自己的標籤。Railway 可能會立刻開始第一次部署。它會以 `OLEAFLY_PUBLIC_URL is not set` 停止，這在此時是預期中的情況。
2. 開啟服務。在 **Settings › Networking** 下，選取 **Generate Domain** 並輸入連接埠 `8080`。Railway 會顯示位址，例如 `oleafly-server-production.up.railway.app`。
3. 在 **Settings › Deploy** 下，把 **Healthcheck Path** 設為 `/readyz`。
4. 在專案畫布上按右鍵，加入一個磁碟區，把它連接到伺服器的服務，並把它的掛載路徑設為 `/data`。
5. 在 **Variables** 下，開啟 **Raw Editor**，貼上這幾行，並換成你自己的伺服器名稱。GitHub 的值請依照 [GitHub](/docs/collaboration/server-access/#github) 設定。回呼位址是第 2 步的位址，前面加上 `https://`，後面加上 `/auth/callback/github`。

   ```ini
   OLEAFLY_PUBLIC_URL=https://${{RAILWAY_PUBLIC_DOMAIN}}
   OLEAFLY_BIND=0.0.0.0:8080
   OLEAFLY_DATA_DIR=/data
   OLEAFLY_BEHIND_PROXY=true
   OLEAFLY_SERVER_NAME=Smith Lab
   OLEAFLY_GITHUB_CLIENT_ID=Ov23liExampleClientId
   OLEAFLY_GITHUB_CLIENT_SECRET=example-client-secret
   PORT=8080
   RAILWAY_RUN_UID=0
   ```

   Railway 以 root 掛載磁碟區。`RAILWAY_RUN_UID=0` 讓伺服器以 root 執行，這樣它才能寫入磁碟區。

6. 部署這些變更。在服務的 **Deploy Logs** 中找到最新的 `Setup code:` 那一行，然後[成為第一位管理員](#become-the-first-admin)。

## 不使用 Docker 的 Linux

在沒有 Docker 的機器上，伺服器會作為單一程式在 systemd 下執行，前面由 Caddy 處理 HTTPS。

### 下載伺服器

[版本頁面](https://github.com/Oleafly/Oleafly/releases)上的每個伺服器版本，都有適用於 x86-64 和 ARM 的預先建置程式，以及用來檢查它的 `SHA256SUMS` 檔案。這個程式不需要安裝其他任何東西。

請下載適合你機器的封存檔（檔名以 `x86_64-unknown-linux-musl.tar.gz` 或 `aarch64-unknown-linux-musl.tar.gz` 結尾）和 `SHA256SUMS`，放進同一個資料夾。然後檢查並安裝它。在 ARM 機器上，請用 `aarch64` 取代 `x86_64`：

```sh
sha256sum --check --ignore-missing SHA256SUMS
tar -xzf oleafly-server-*-x86_64-unknown-linux-musl.tar.gz
sudo install -m 0755 oleafly-server-*-x86_64-unknown-linux-musl/oleafly-server /usr/local/bin/oleafly-server
oleafly-server --version
```

如果已安裝 GitHub CLI，`gh attestation verify oleafly-server-*-x86_64-unknown-linux-musl.tar.gz --repo Oleafly/Oleafly` 也會檢查該封存檔是否由 GitHub 從 Oleafly 儲存庫建置。封存檔中包含 systemd 單元 `oleafly-server.service`。

如果你想自己建置程式，請在任何有 Docker 的電腦上，從 Oleafly 儲存庫的複本執行這個指令。ARM 伺服器請使用 `--platform linux/arm64`。

```sh
docker buildx build --platform linux/amd64 --target binary --output type=local,dest=dist -f crates/oleafly-server/Dockerfile .
```

這會寫出 `dist/oleafly-server`。把它複製到伺服器上的 `/usr/local/bin/oleafly-server`，並設為可執行。

### 用 systemd 執行

1. 建立設定檔。只有 root 可以讀取它：

   ```sh
   sudo install -d -m 0755 /etc/oleafly-server
   sudo install -m 0600 /dev/null /etc/oleafly-server/oleafly-server.env
   sudoedit /etc/oleafly-server/oleafly-server.env
   ```

   每行放一項設定。`OLEAFLY_BIND=127.0.0.1:8080` 讓伺服器不出現在網路上，只有 Caddy 可以連到它。不要設定 `OLEAFLY_DATA_DIR`，因為單元會設定它。

   ```ini
   OLEAFLY_PUBLIC_URL=https://collab.example.org
   OLEAFLY_BIND=127.0.0.1:8080
   OLEAFLY_BEHIND_PROXY=true
   OLEAFLY_SERVER_NAME=Smith Lab
   OLEAFLY_GITHUB_CLIENT_ID=Ov23liExampleClientId
   OLEAFLY_GITHUB_CLIENT_SECRET=example-client-secret
   ```

2. 從解開的封存檔，或從儲存庫複本中的 `deploy/server`，安裝並啟動該單元。然後找到設定碼：

   ```sh
   sudo install -m 0644 oleafly-server.service /etc/systemd/system/oleafly-server.service
   sudo systemctl daemon-reload
   sudo systemctl enable --now oleafly-server
   sudo journalctl -u oleafly-server | grep 'Setup code'
   ```

該單元會以 systemd 為它建立的使用者執行伺服器，並讓它以唯讀方式檢視系統的其餘部分。它唯一能寫入的地方是 `/var/lib/oleafly-server`，它在那裡保存自己的資料。在磁碟上，該資料夾是 `/var/lib/private/oleafly-server`。

若要讓 client 密鑰不出現在設定檔中，請使用 systemd 憑證。把密鑰儲存到 `/etc/oleafly-server/github-client-secret`，權限設為 600，刪除設定檔中的 `OLEAFLY_GITHUB_CLIENT_SECRET` 那一行，執行 `sudo systemctl edit oleafly-server`，並加入：

```ini
[Service]
LoadCredential=github-client-secret:/etc/oleafly-server/github-client-secret
Environment=OLEAFLY_GITHUB_CLIENT_SECRET_FILE=%d/github-client-secret
```

然後執行 `sudo systemctl restart oleafly-server`。

### 在前面加上 HTTPS

依照[適用於你發行版的說明](https://caddyserver.com/docs/install)安裝 Caddy。用這幾行取代 `/etc/caddy/Caddyfile`，並執行 `sudo systemctl reload caddy`。Caddy 會取得憑證並傳遞即時連線。

```
collab.example.org {
	reverse_proxy 127.0.0.1:8080
}
```

若使用 nginx 或 Apache，或你的大學已經在執行的網頁伺服器，請閱讀[在反向代理後方](/docs/collaboration/server-operations/#behind-a-reverse-proxy)。

## 沒有公開位址時

如果機器沒有公開位址，例如位於大學防火牆後方的實驗室電腦，可以用 Cloudflare Tunnel 讓它可被連到。你需要一個 Cloudflare 帳號，並且網域已加入其中。Cloudflare 會處理主機名稱的 HTTPS，所以要求在抵達你的機器之前，會先在 Cloudflare 的網路上解密。請把 Cloudflare 算作能讀取傳往你伺服器的流量的一方。

1. 照著[手動使用 Docker Compose](#docker-compose-by-hand)的步驟進行，直到編輯 `.env` 為止。把 `OLEAFLY_DOMAIN` 設為你要使用的主機名稱，例如 `collab.example.org`。一行指令的安裝程式不適用於這裡，因為它會啟動 Caddy。
2. 只啟動伺服器。這裡不需要 Caddy：

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

3. 在 Cloudflare 儀表板中，前往 **Networking › Tunnels**，選取 **Create Tunnel**，為它命名，再選取一次 **Create Tunnel**。從它顯示的安裝指令中複製權杖。
4. 在伺服器旁啟動通道。`read` 指令會等你貼上權杖，而且不會顯示它：

   ```sh
   read -rs TUNNEL_TOKEN && export TUNNEL_TOKEN
   sudo --preserve-env=TUNNEL_TOKEN docker run -d --name oleafly-tunnel --restart unless-stopped --network oleafly-server_default -e TUNNEL_TOKEN cloudflare/cloudflared:2026.10.0 tunnel --no-autoupdate run
   ```

5. 回到儀表板，開啟該通道。在 **Routes** 下，選取 **Add route**，再選取 **Published application**。在 **Hostname** 下，輸入子網域並選擇你的網域。把 **Service URL** 設為 `http://oleafly-server:8080`，然後選取 **Add route**。
6. 檢查它是否在 `https://collab.example.org/healthz` 回應，然後[成為第一位管理員](#become-the-first-admin)。

在沒有 Docker 的機器上，請從 [Cloudflare 的套件庫](https://pkg.cloudflare.com/)安裝 `cloudflared`，執行 `sudo cloudflared service install` 並接上權杖，然後把 **Service URL** 設為 `http://127.0.0.1:8080`。

Cloudflare 會傳遞即時連線，並把訪客的位址放在 `X-Forwarded-For` 的最後，所以請保持 `OLEAFLY_BEHIND_PROXY=true`。當通道通往另一個代理伺服器（例如 Coolify 的），而不是直接通往伺服器時，還要設定 `OLEAFLY_PROXY_HOPS=2`。Cloudflare 在其 Free 和 Pro 方案上會拒絕大於 100 MB 的要求，所以請把 `OLEAFLY_MAX_PROJECT_MB` 設為 100 或更小，否則大型專案會上傳失敗。不要在伺服器前面放 Cloudflare Access，因為 Oleafly 無法通過它的登入頁面。

之後更新伺服器時，請下載新版本的檔案，並指定服務名稱，讓 Caddy 保持關閉：`sudo docker compose up -d oleafly-server`。

## 成為第一位管理員

新的伺服器沒有管理員。在有人完成設定之前，伺服器每次啟動都會產生新的一次性設定碼，並寫入它的記錄。

1. 在記錄中找到以 `Setup code:` 開頭的最新一行：
   - 一行指令安裝：安裝程式完成時會印出它。若要再次查看，請執行 `cd /opt/oleafly-server && sudo docker compose logs oleafly-server | grep 'Setup code'`
   - 手動使用 Docker Compose：在伺服器的資料夾中執行 `sudo docker compose logs oleafly-server | grep 'Setup code'`
   - Coolify：`oleafly-server` 服務的記錄
   - systemd：`sudo journalctl -u oleafly-server | grep 'Setup code'`
2. 在 Oleafly 中，開啟 **設定 → 協作**，選取 **新增伺服器**，並輸入你的伺服器位址。Oleafly 發現伺服器需要設定，並詢問 **設定碼**。
3. 輸入代碼，並用你設定的任何供應商登入。你就成為伺服器的管理員，而代碼也隨之失效。

在你使用代碼之前，任何拿到它的人都可以讓自己成為管理員，所以只能把它貼到 Oleafly 中。

你也可以用 `OLEAFLY_SETUP_CODE` 自己選擇代碼：至少 12 個字母或數字，也可以加上連字號或空格。這樣伺服器就不會印出它。記錄只會說 `Setup code: set by OLEAFLY_SETUP_CODE`，而你輸入的是自己設定的值。設定完成後，請從你的設定中移除它。

接下來，讓人們進來。[登入與存取](/docs/collaboration/server-access/#access-rules)說明了做法。

## 檢查伺服器

- 使用一行指令安裝時，`sudo sh /opt/oleafly-server/install.sh status` 會一次檢查容器和 HTTPS。
- 伺服器程序在執行時，`https://collab.example.org/healthz` 會回應 `200`。
- 只有在伺服器能寫入它的資料庫和資料資料夾時，`/readyz` 才會回應 `200`。無法寫入時，例如磁碟已滿，它會回應 `503`，並指出失敗的是什麼：`database` 或 `storage`。
- Docker 映像檔會自行檢查 `/readyz`，所以 `docker ps` 和 Coolify 會把有問題的伺服器顯示為不健康，而不是顯示為仍在執行但什麼都存不了。
- 在 Oleafly 中，**設定 → 協作** 下的 **測試連線** 會檢查位址、HTTPS、版本、即時連線、登入選項和伺服器的時鐘。[管理主控台](/docs/collaboration/server-access/#admin-console)中的 **連線檢查** 會執行相同的檢查。
