執行伺服器
執行協作伺服器
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,例如 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安裝程式會:
- 檢查機器,以及連接埠 80 和 443 是否空閒。
- 檢查 Docker。如果沒有,安裝程式會先詢問,再用 Docker 自己的指令碼安裝它。
- 從 Oleafly Server 版本頁面 (在新分頁開啟)下載最新版本的檔案,並用該版本的
SHA256SUMS檢查每一個檔案。如果有檔案不符,它會停止,不做任何變更。 - 詢問你的網域、伺服器名稱,以及人們如何登入。它也會提議設定電子郵件,以及把檔案存放在 S3 儲存貯體中。兩者都是選用的。
- 顯示摘要,並在變更任何內容之前詢問。接著把它的檔案寫入
/opt/oleafly-server,你的設定放在.env中,只有 root 可以讀取。 - 啟動前面有 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 SHA256SUMSsudo 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會保留。刪除它們會移除伺服器上的每個共用專案、每個帳號和安全記錄。人們在自己的電腦上仍保有專案的副本。
如果安裝程式因為你無法解決的問題而停止,請回報 (在新分頁開啟),並附上它印出的內容。
手動使用 Docker Compose
標題為「手動使用 Docker Compose」的段落這個設定會執行兩個容器。oleafly-server 是伺服器,只有其他容器可以連到它。caddy 會從 Let’s Encrypt 取得憑證,在連接埠 80 和 443 上提供 HTTPS,並把要求(包括即時連線)傳遞給伺服器。
-
依照 Docker 的說明 (在新分頁開啟)安裝 Docker Engine 和 Compose 外掛程式。
-
把你網域的 DNS 記錄指向這台機器。在它前面的任何防火牆中開放 TCP 連接埠 80 和 443,以及 UDP 連接埠 443。Caddy 需要連接埠 80 來取得憑證。
-
為伺服器建立一個資料夾,把最新版本的檔案下載到其中,檢查它們,並建立你的設定檔:
終端機視窗 sudo mkdir -p /opt/oleafly-server && cd /opt/oleafly-serverbase=https://github.com/Oleafly/oleafly-server/releases/latest/downloadfor f in docker-compose.yml Caddyfile env.example litestream.yml SHA256SUMS; do sudo curl -fsSLO "$base/$f"; donesha256sum --check --ignore-missing SHA256SUMSsudo install -m 600 env.example .env -
用
sudoedit .env編輯.env。把OLEAFLY_DOMAIN設為你的網域(不含https://),設定OLEAFLY_SERVER_NAME,並至少填入一個登入供應商。你沒有使用的供應商那幾行請留空。如果值含有$或#,請用單引號括起來。 -
啟動它。第一次啟動時,會下載該版本對應的伺服器映像檔
ghcr.io/oleafly/oleafly-server。終端機視窗 sudo docker compose up -d -
檢查它是否回應。這會印出
200:終端機視窗 curl -sS -o /dev/null -w '%{http_code}\n' https://collab.example.org/healthz -
成為第一位管理員。設定碼在記錄中:
終端機視窗 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 裡
標題為「不要把密鑰放在 .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 那一行:
sudo chown 10001:10001 secrets/github_client_secretsudo 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
標題為「Coolify」的段落Coolify 會在伺服器前面放自己的代理伺服器並取得憑證,所以這個設定沒有 Caddy。Coolify 可以從 Oleafly 儲存庫建置伺服器,也可以執行已發布的映像檔,後者會略過建置。
開始之前,請把你網域的 DNS 記錄(例如 collab.example.org)指向 Coolify 伺服器。然後依照 GitHub 中的說明建立 GitHub OAuth 應用程式,回呼位址為 https://collab.example.org/auth/callback/github。請把它的 client ID 和密鑰放在手邊。
從儲存庫建置
標題為「從儲存庫建置」的段落- 在你的 Coolify 專案中,選取 + New,再選取 Public Repository,並輸入
https://github.com/Oleafly/Oleafly。分支保持main。 - 把 Build Pack 設為 Docker Compose,Base Directory 設為
/,Docker Compose Location 設為/deploy/server/docker-compose.coolify.yml,然後選取 Continue。 - 在 Advanced › Build 下,把 Build arguments 設為 Managed manually in Dockerfile。伺服器的映像檔不需要建置引數。如果保持自動,Coolify 會把每個變數(包括密鑰)寫進映像檔的建置歷史。
- 在 General 下,把
oleafly-server的網域設為https://collab.example.org:8080並儲存。:8080告訴 Coolify 的代理伺服器,伺服器在哪個連接埠上監聽。人們仍然使用一般的 HTTPS 連接埠連線,Coolify 會替你把OLEAFLY_PUBLIC_URL設為https://collab.example.org。 - 在 Environment Variables 下,填入 Coolify 標示為必填的
OLEAFLY_SERVER_NAME,接著填入OLEAFLY_GITHUB_CLIENT_ID和OLEAFLY_GITHUB_CLIENT_SECRET。你沒有使用的變數請留空。 - 選取 Deploy。第一次建置會編譯伺服器,需要幾分鐘。完成後,Coolify 會顯示該資源正在執行且狀況良好。
- 在瀏覽器中開啟
https://collab.example.org/healthz。它會顯示{"status":"ok"}。 - 開啟 Logs,選擇
oleafly-server容器,並從以Setup code:開頭的最新一行複製代碼。 - 用那組代碼成為第一位管理員。
如果伺服器無法啟動,它的記錄會指出它無法使用的設定。當記錄說 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
標題為「Render」的段落Deploy to Render (在新分頁開啟) 會讀取 Oleafly 儲存庫中的 Blueprint。它從已發布的映像檔建立一個網頁服務,並為資料資料夾配置 1 GB 的磁碟。Render 只會把磁碟連接到付費的執行個體類型,所以服務會從最小的付費類型開始,位於 Render 的 Oregon 區域。若要使用其他區域,請從分叉部署,並在 render.yaml 中設定 region。
- 開啟連結並登入 Render。
- Render 會要求輸入
OLEAFLY_SERVER_NAME以及 GitHub client ID 和密鑰。填入名稱,GitHub 欄位暫時留空。它們的回呼位址取決於服務的位址,而你現在還沒有。 - 選取 Deploy Blueprint。服務上線後,它的頁面會顯示它的位址,例如
https://oleafly-server.onrender.com。Blueprint 會把OLEAFLY_PUBLIC_URL設為該位址。 - 依照 GitHub 中的說明建立 GitHub OAuth 應用程式,以該位址加上
/auth/callback/github作為回呼位址。把 client ID 和密鑰加到服務的 Environment 下。Render 會帶著它們重新啟動伺服器。 - 在服務的 Logs 中找到最新的
Setup code:那一行,然後成為第一位管理員。
如果你為服務設定了自己的網域,請在 Environment 下把 OLEAFLY_PUBLIC_URL 設為該網域,並在 GitHub 上把回呼位址改成相符的內容。
由於有磁碟,Render 會先停止正在執行的伺服器,才啟動新的伺服器,所以每次部署都會讓伺服器離線幾秒。Oleafly 會自動重新連線。
Railway
標題為「Railway」的段落Railway 會執行已發布的映像檔,並為資料資料夾配置一個磁碟區。
-
在 Railway 專案中,選取 + New,再選取 Docker Image,並輸入
ghcr.io/oleafly/oleafly-server:latest。若要自行選擇何時升級,請改用版本頁面 (在新分頁開啟)上某個版本自己的標籤。Railway 可能會立刻開始第一次部署。它會以OLEAFLY_PUBLIC_URL is not set停止,這在此時是預期中的情況。 -
開啟服務。在 Settings › Networking 下,選取 Generate Domain 並輸入連接埠
8080。Railway 會顯示位址,例如oleafly-server-production.up.railway.app。 -
在 Settings › Deploy 下,把 Healthcheck Path 設為
/readyz。 -
在專案畫布上按右鍵,加入一個磁碟區,把它連接到伺服器的服務,並把它的掛載路徑設為
/data。 -
在 Variables 下,開啟 Raw Editor,貼上這幾行,並換成你自己的伺服器名稱。GitHub 的值請依照 GitHub 設定。回呼位址是第 2 步的位址,前面加上
https://,後面加上/auth/callback/github。OLEAFLY_PUBLIC_URL=https://${{RAILWAY_PUBLIC_DOMAIN}}OLEAFLY_BIND=0.0.0.0:8080OLEAFLY_DATA_DIR=/dataOLEAFLY_BEHIND_PROXY=trueOLEAFLY_SERVER_NAME=Smith LabOLEAFLY_GITHUB_CLIENT_ID=Ov23liExampleClientIdOLEAFLY_GITHUB_CLIENT_SECRET=example-client-secretPORT=8080RAILWAY_RUN_UID=0Railway 以 root 掛載磁碟區。
RAILWAY_RUN_UID=0讓伺服器以 root 執行,這樣它才能寫入磁碟區。 -
部署這些變更。在服務的 Deploy Logs 中找到最新的
Setup code:那一行,然後成為第一位管理員。
不使用 Docker 的 Linux
標題為「不使用 Docker 的 Linux」的段落在沒有 Docker 的機器上,伺服器會作為單一程式在 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 SHA256SUMStar -xzf oleafly-server-*-x86_64-unknown-linux-musl.tar.gzsudo install -m 0755 oleafly-server-*-x86_64-unknown-linux-musl/oleafly-server /usr/local/bin/oleafly-serveroleafly-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,並設為可執行。
用 systemd 執行
標題為「用 systemd 執行」的段落-
建立設定檔。只有 root 可以讀取它:
終端機視窗 sudo install -d -m 0755 /etc/oleafly-serversudo install -m 0600 /dev/null /etc/oleafly-server/oleafly-server.envsudoedit /etc/oleafly-server/oleafly-server.env每行放一項設定。
OLEAFLY_BIND=127.0.0.1:8080讓伺服器不出現在網路上,只有 Caddy 可以連到它。不要設定OLEAFLY_DATA_DIR,因為單元會設定它。OLEAFLY_PUBLIC_URL=https://collab.example.orgOLEAFLY_BIND=127.0.0.1:8080OLEAFLY_BEHIND_PROXY=trueOLEAFLY_SERVER_NAME=Smith LabOLEAFLY_GITHUB_CLIENT_ID=Ov23liExampleClientIdOLEAFLY_GITHUB_CLIENT_SECRET=example-client-secret -
從解開的封存檔,或從儲存庫複本中的
deploy/server,安裝並啟動該單元。然後找到設定碼:終端機視窗 sudo install -m 0644 oleafly-server.service /etc/systemd/system/oleafly-server.servicesudo systemctl daemon-reloadsudo systemctl enable --now oleafly-serversudo 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-secretEnvironment=OLEAFLY_GITHUB_CLIENT_SECRET_FILE=%d/github-client-secret然後執行 sudo systemctl restart oleafly-server。
在前面加上 HTTPS
標題為「在前面加上 HTTPS」的段落依照適用於你發行版的說明 (在新分頁開啟)安裝 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 算作能讀取傳往你伺服器的流量的一方。
-
照著手動使用 Docker Compose的步驟進行,直到編輯
.env為止。把OLEAFLY_DOMAIN設為你要使用的主機名稱,例如collab.example.org。一行指令的安裝程式不適用於這裡,因為它會啟動 Caddy。 -
只啟動伺服器。這裡不需要 Caddy:
終端機視窗 sudo docker compose up -d oleafly-server -
在 Cloudflare 儀表板中,前往 Networking › Tunnels,選取 Create Tunnel,為它命名,再選取一次 Create Tunnel。從它顯示的安裝指令中複製權杖。
-
在伺服器旁啟動通道。
read指令會等你貼上權杖,而且不會顯示它:終端機視窗 read -rs TUNNEL_TOKEN && export TUNNEL_TOKENsudo --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 -
回到儀表板,開啟該通道。在 Routes 下,選取 Add route,再選取 Published application。在 Hostname 下,輸入子網域並選擇你的網域。把 Service URL 設為
http://oleafly-server:8080,然後選取 Add route。 -
檢查它是否在
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。
成為第一位管理員
標題為「成為第一位管理員」的段落新的伺服器沒有管理員。在有人完成設定之前,伺服器每次啟動都會產生新的一次性設定碼,並寫入它的記錄。
- 在記錄中找到以
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'
- 一行指令安裝:安裝程式完成時會印出它。若要再次查看,請執行
- 在 Oleafly 中,開啟 設定 → 協作,選取 新增伺服器,並輸入你的伺服器位址。Oleafly 發現伺服器需要設定,並詢問 設定碼。
- 輸入代碼,並用你設定的任何供應商登入。你就成為伺服器的管理員,而代碼也隨之失效。
在你使用代碼之前,任何拿到它的人都可以讓自己成為管理員,所以只能把它貼到 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、版本、即時連線、登入選項和伺服器的時鐘。管理主控台中的 連線檢查 會執行相同的檢查。