跳到內容
Oleaflyv0.4.12

執行伺服器

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

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

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

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

伺服器把所有內容都存放在一個資料資料夾中,由 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 會給你一個位址。如果機器沒有公開位址,請閱讀沒有公開位址時。
  • 讓人們登入的方式:至少一個登入供應商,例如 GitHub OAuth 應用程式或你機構的登入。沒有它,伺服器無法啟動。伺服器可用來寄信的電子郵件帳號是選用的。有了它,管理員還可以讓人們用寄來的連結登入。請閱讀登入與存取。

每個版本都會以容器映像檔 ghcr.io/oleafly/oleafly-server 發布。安裝程式及其 Compose 檔案位於 Oleafly Server 版本頁面 (在新分頁開啟)。單一 Linux 程式形式的伺服器位於 Oleafly 版本頁面 (在新分頁開啟)。

選項適用情況
一行指令你自己維護的 Linux 機器。安裝程式會設定 Docker、Caddy 和 HTTPS,並問幾個問題。如果不確定,就從這裡開始。
手動使用 Docker Compose你比較想自己放置並編輯每個檔案。
Coolify你已經在執行 Coolify 伺服器。
Render或 Railway你寧可付費給代管服務,也不想自己維護機器。
不使用 Docker 的 Linux無法使用 Docker 的大學虛擬機器。

伺服器從環境變數讀取設定。儲存空間、備份與限制列出了每一項。

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

安裝程式做了什麼安裝程式會依序執行六個步驟。它會檢查機器是否執行 x86-64 或 ARM 的 Linux,且 80 和 443 連接埠沒有被占用。如果缺少 Docker,會先詢問再安裝。它會下載發行版本的檔案,並對照 SHA256SUMS 檢查每一個。它會詢問網域、伺服器名稱、人們如何登入,以及(可選)電子郵件。它會把設定寫入 .env,並在 /opt/oleafly-server 中啟動搭配 Caddy 的伺服器。伺服器透過 HTTPS 回應後,它會印出第一位管理員的設定碼。檢查機器Linux,x86-64 或 ARM80 與 443 連接埠未被占用Docker缺少時會安裝,安裝前會先詢問你下載並驗證發行版本的檔案,以 SHA256SUMS 檢查幾個問題網域、伺服器名稱、登入方式、電子郵件啟動伺服器與 Caddy在 /opt/oleafly-server 中設定碼伺服器回應後印出安裝程式做了什麼安裝程式會依序執行六個步驟。它會檢查機器是否執行 x86-64 或 ARM 的 Linux,且 80 和 443 連接埠沒有被占用。如果缺少 Docker,會先詢問再安裝。它會下載發行版本的檔案,並對照 SHA256SUMS 檢查每一個。它會詢問網域、伺服器名稱、人們如何登入,以及(可選)電子郵件。它會把設定寫入 .env,並在 /opt/oleafly-server 中啟動搭配 Caddy 的伺服器。伺服器透過 HTTPS 回應後,它會印出第一位管理員的設定碼。檢查機器Linux,x86-64 或 ARM80 與 443 連接埠未被占用Docker缺少時會安裝,安裝前會先詢問你下載並驗證發行版本的檔案,以 SHA256SUMS 檢查幾個問題網域、伺服器名稱、登入方式、電子郵件啟動伺服器與 Caddy在 /opt/oleafly-server 中設定碼伺服器回應後印出
一行指令:檢查、Docker、下載並驗證、回答幾個問題、啟動,最後取得設定碼。

執行之前,請確認:

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

然後執行:

終端機視窗
curl -fsSL https://oleafly.com/server/install.sh | sudo sh

安裝程式會:

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

然後成為第一位管理員。

你可以隨時再次執行安裝程式。當它在 /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,請從最新版本 (在新分頁開啟)把 install.sh 和 SHA256SUMS 下載到同一個資料夾。檢查指令碼、閱讀它,然後執行:

終端機視窗
sha256sum --check --ignore-missing SHA256SUMS
sudo sh install.sh

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

終端機視窗
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 以有效憑證回應。

  • 更新:先備份,如更新所述。然後執行下面的指令。它會下載最新版本的檔案和映像檔,保留 .env,重新啟動伺服器,並等到它回應。已連線的人會自動重新連線。安裝程式從不會把伺服器移到較舊的版本。

    終端機視窗
    curl -fsSL https://oleafly.com/server/install.sh | sudo sh -s -- update
  • 解除安裝:sudo sh /opt/oleafly-server/install.sh uninstall 會停止並移除容器。除非它詢問時你輸入 delete,否則你的資料和 .env 會保留。刪除它們會移除伺服器上的每個共用專案、每個帳號和安全記錄。人們在自己的電腦上仍保有專案的副本。

如果安裝程式因為你無法解決的問題而停止,請回報 (在新分頁開啟),並附上它印出的內容。

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

Docker Compose 部署每台電腦上的 Oleafly 會透過 HTTPS 連到你機器上的 Caddy。Caddy 持有憑證,並以一般 HTTP 把請求傳給 oleafly-server 容器。伺服器把資料庫和檔案存放在 Docker 資料磁碟區中,也可以改把檔案存放在 S3 儲存貯體。你的機器,使用 Docker ComposeOleafly在每台電腦上CaddyHTTPS憑證oleafly-server設定在 .env 中資料磁碟區資料庫、檔案S3 儲存貯體選用Docker Compose 部署每台電腦上的 Oleafly 會透過 HTTPS 連到你機器上的 Caddy。Caddy 持有憑證,並以一般 HTTP 把請求傳給 oleafly-server 容器。伺服器把資料庫和檔案存放在 Docker 資料磁碟區中,也可以改把檔案存放在 S3 儲存貯體。你的機器,使用 Docker ComposeOleafly在每台電腦上CaddyHTTPS 憑證oleafly-server設定在 .env 中資料磁碟區資料庫、檔案S3 儲存貯體選用,檔案HTTPSHTTP
Docker Compose:Caddy 在伺服器前面處理 HTTPS,資料磁碟區存放資料庫和檔案。
  1. 依照 Docker 的說明 (在新分頁開啟)安裝 Docker Engine 和 Compose 外掛程式。

  2. 把你網域的 DNS 記錄指向這台機器。在它前面的任何防火牆中開放 TCP 連接埠 80 和 443,以及 UDP 連接埠 443。Caddy 需要連接埠 80 來取得憑證。

  3. 為伺服器建立一個資料夾,把最新版本的檔案下載到其中,檢查它們,並建立你的設定檔:

    終端機視窗
    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,並至少填入一個登入供應商。你沒有使用的供應商那幾行請留空。如果值含有 $ 或 #,請用單引號括起來。

  5. 啟動它。第一次啟動時,會下載該版本對應的伺服器映像檔 ghcr.io/oleafly/oleafly-server。

    終端機視窗
    sudo docker compose up -d
  6. 檢查它是否回應。這會印出 200:

    終端機視窗
    curl -sS -o /dev/null -w '%{http_code}\n' https://collab.example.org/healthz
  7. 成為第一位管理員。設定碼在記錄中:

    終端機視窗
    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。

有七項設定可以存放密鑰: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 那一行:

終端機視窗
sudo chown 10001:10001 secrets/github_client_secret
sudo chmod 400 secrets/github_client_secret

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

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 會在伺服器前面放自己的代理伺服器並取得憑證,所以這個設定沒有 Caddy。Coolify 可以從 Oleafly 儲存庫建置伺服器,也可以執行已發布的映像檔,後者會略過建置。

Coolify 部署每台電腦上的 Oleafly 會連到 Coolify 的代理(可選擇經由 Cloudflare),由代理處理 HTTPS 並把請求傳給 oleafly-server。伺服器把資料存放在 Docker 磁碟區中。當 Cloudflare 位於 Coolify 的代理前面時,每個請求都會經過兩層代理,所以請把 OLEAFLY_PROXY_HOPS 設為 2。Oleafly在每台電腦上Cloudflare選用Coolify 的代理HTTPSoleafly-server在你的 Coolify伺服器上資料磁碟區兩者都在前面時,請設定OLEAFLY_PROXY_HOPS=2Coolify 部署每台電腦上的 Oleafly 會連到 Coolify 的代理(可選擇經由 Cloudflare),由代理處理 HTTPS 並把請求傳給 oleafly-server。伺服器把資料存放在 Docker 磁碟區中。當 Cloudflare 位於 Coolify 的代理前面時,每個請求都會經過兩層代理,所以請把 OLEAFLY_PROXY_HOPS 設為 2。Oleafly在每台電腦上Cloudflare選用Coolify 的代理HTTPSoleafly-server在你的 Coolify 伺服器上資料磁碟區兩者都在前面時,請設定OLEAFLY_PROXY_HOPS=2
Coolify:由它的代理處理 HTTPS。前面還有 Cloudflare 時,請設定 OLEAFLY_PROXY_HOPS=2。

開始之前,請把你網域的 DNS 記錄(例如 collab.example.org)指向 Coolify 伺服器。然後依照 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. 用那組代碼成為第一位管理員。

如果伺服器無法啟動,它的記錄會指出它無法使用的設定。當記錄說 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 都會拉取該系列中的最新版本。

Deploy to Render (在新分頁開啟) 會讀取 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 中的說明建立 GitHub OAuth 應用程式,以該位址加上 /auth/callback/github 作為回呼位址。把 client ID 和密鑰加到服務的 Environment 下。Render 會帶著它們重新啟動伺服器。
  5. 在服務的 Logs 中找到最新的 Setup code: 那一行,然後成為第一位管理員。

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

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

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

  1. 在 Railway 專案中,選取 + New,再選取 Docker Image,並輸入 ghcr.io/oleafly/oleafly-server:latest。若要自行選擇何時升級,請改用版本頁面 (在新分頁開啟)上某個版本自己的標籤。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 設定。回呼位址是第 2 步的位址,前面加上 https://,後面加上 /auth/callback/github。

    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: 那一行,然後成為第一位管理員。

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

不使用 Docker 的 Linux 部署每台電腦上的 Oleafly 會透過 HTTPS 連到你 Linux 機器上的 Caddy。Caddy 把請求傳給 oleafly-server,它以 systemd 服務的形式執行,監聽 127.0.0.1 的 8080 連接埠,並把資料存放在 /var/lib/oleafly-server。你的 Linux 機器Oleafly在每台電腦上CaddyHTTPS憑證oleafly-serversystemd 服務資料夾/var/lib/oleafly-server不使用 Docker 的 Linux 部署每台電腦上的 Oleafly 會透過 HTTPS 連到你 Linux 機器上的 Caddy。Caddy 把請求傳給 oleafly-server,它以 systemd 服務的形式執行,監聽 127.0.0.1 的 8080 連接埠,並把資料存放在 /var/lib/oleafly-server。你的 Linux 機器Oleafly在每台電腦上CaddyHTTPS 憑證oleafly-serversystemd 服務資料夾/var/lib/oleafly-serverHTTPSHTTP
不使用 Docker 的 Linux:由 systemd 執行伺服器,前面的 Caddy 處理 HTTPS。

版本頁面 (在新分頁開啟)上的每個伺服器版本,都有適用於 x86-64 和 ARM 的預先建置程式,以及用來檢查它的 SHA256SUMS 檔案。這個程式不需要安裝其他任何東西。

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

終端機視窗
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。

終端機視窗
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,並設為可執行。

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

    終端機視窗
    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,因為單元會設定它。

    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,安裝並啟動該單元。然後找到設定碼:

    終端機視窗
    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,並加入:

[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。

依照適用於你發行版的說明 (在新分頁開啟)安裝 Caddy。用這幾行取代 /etc/caddy/Caddyfile,並執行 sudo systemctl reload caddy。Caddy 會取得憑證並傳遞即時連線。

collab.example.org {
reverse_proxy 127.0.0.1:8080
}

若使用 nginx 或 Apache,或你的大學已經在執行的網頁伺服器,請閱讀在反向代理後方。

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

Cloudflare Tunnel 部署每台電腦上的 Oleafly 會透過 HTTPS 連到 Cloudflare。你機器上的 cloudflared 容器會向外開啟一條通往 Cloudflare 的通道,所以這台機器不需要公開位址。請求經由通道抵達 cloudflared,再由它傳給 oleafly-server。你的機器,沒有公開位址Oleafly在每台電腦上CloudflareHTTPScloudflared開啟通道oleafly-server資料磁碟區Cloudflare Tunnel 部署每台電腦上的 Oleafly 會透過 HTTPS 連到 Cloudflare。你機器上的 cloudflared 容器會向外開啟一條通往 Cloudflare 的通道,所以這台機器不需要公開位址。請求經由通道抵達 cloudflared,再由它傳給 oleafly-server。你的機器,沒有公開位址Oleafly在每台電腦上CloudflareHTTPScloudflared開啟通道oleafly-server資料磁碟區通道
Cloudflare Tunnel:由你的機器自己開啟通道,所以不需要公開位址。
  1. 照著手動使用 Docker Compose的步驟進行,直到編輯 .env 為止。把 OLEAFLY_DOMAIN 設為你要使用的主機名稱,例如 collab.example.org。一行指令的安裝程式不適用於這裡,因為它會啟動 Caddy。

  2. 只啟動伺服器。這裡不需要 Caddy:

    終端機視窗
    sudo docker compose up -d oleafly-server
  3. 在 Cloudflare 儀表板中,前往 Networking › Tunnels,選取 Create Tunnel,為它命名,再選取一次 Create Tunnel。從它顯示的安裝指令中複製權杖。

  4. 在伺服器旁啟動通道。read 指令會等你貼上權杖,而且不會顯示它:

    終端機視窗
    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 回應,然後成為第一位管理員。

在沒有 Docker 的機器上,請從 Cloudflare 的套件庫 (在新分頁開啟)安裝 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,而你輸入的是自己設定的值。設定完成後,請從你的設定中移除它。

接下來,讓人們進來。登入與存取說明了做法。

  • 使用一行指令安裝時,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、版本、即時連線、登入選項和伺服器的時鐘。管理主控台中的 連線檢查 會執行相同的檢查。
圖片預覽

無法載入 AI 回答

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