跳到內容
Oleaflyv0.4.12

執行伺服器

為 Oleafly Server 設定登入供應商與電子郵件,用存取規則、開放註冊、角色和訪客決定誰能進入,開啟瀏覽器存取,並從管理主控台管理伺服器。

人們透過你設定的供應商登入 Oleafly Server,所以伺服器從不處理密碼。你用存取規則決定誰能進入。管理員則在 Oleafly 中透過管理主控台管理其餘事項。

至少設定一個供應商。沒有供應商時伺服器無法啟動,它的記錄會指出要加入哪些設定。第一位管理員要用供應商登入,因為在管理員開啟之前,以電子郵件連結登入一直是關閉的。每個供應商都會把使用者導回你伺服器上的回呼位址:

https://collab.example.org/auth/callback/<provider>

如果 OLEAFLY_PUBLIC_URL 含有路徑,回呼位址也會帶著同樣的路徑,例如 https://www.cs.example.edu/oleafly/auth/callback/github。

  1. 在 GitHub 上,選取你的大頭貼,然後選取 Settings › Developer settings › OAuth apps,再選取 New OAuth App。如果應用程式屬於某個組織,請改用該組織設定中的 Developer settings。
  2. 填寫 Application name(例如 Smith Lab Oleafly)、Homepage URL(https://collab.example.org)和 Authorization callback URL(https://collab.example.org/auth/callback/github)。Enable Device Flow 保持關閉。
  3. 選取 Register application。複製 Client ID,接著選取 Generate a new client secret 並複製該密鑰。
  4. 設定 OLEAFLY_GITHUB_CLIENT_ID 和 OLEAFLY_GITHUB_CLIENT_SECRET,然後重新啟動伺服器。

伺服器只會向 GitHub 要求使用者的個人資料和電子郵件地址(read:user 和 user:email)。OLEAFLY_GITHUB_LABEL 可以變更登入按鈕上的文字。

若使用 GitHub Enterprise Server,請在該處註冊應用程式,並把 OLEAFLY_GITHUB_URL 也設為它的位址,例如 https://github.example.edu。只有在你的 API 位址不尋常時,才需要設定 OLEAFLY_GITHUB_API_URL。

OpenID Connect 涵蓋 GitLab、Google、Microsoft Entra ID、Keycloak、Authentik、Okta,以及大多數大學的單一登入系統。如果你的大學只提供 SAML,請在中間加一層 Keycloak 或 Dex。

  1. 取一個由字母和數字組成的簡短名稱,例如 GITLAB。它會成為變數名稱的一部分,小寫後也會成為回呼位址的一部分。在 Compose 的 .env 中,請改掉 UNIVERSITY 那幾行,或另外加一個區塊。

  2. 向你的供應商註冊應用程式。選擇機密型或網頁應用程式,把重新導向 URI 設為 https://collab.example.org/auth/callback/gitlab,並允許 openid、email 和 profile 這幾個範圍。

  3. 加入供應商的詳細資料:

    OLEAFLY_OIDC_GITLAB_ISSUER=https://gitlab.com
    OLEAFLY_OIDC_GITLAB_CLIENT_ID=example-client-id
    OLEAFLY_OIDC_GITLAB_CLIENT_SECRET=example-client-secret
    OLEAFLY_OIDC_GITLAB_LABEL=GitLab
  4. 重新啟動伺服器。

標籤是登入按鈕上的文字,例如 University login。簽發者(issuer)是供應商發布 /.well-known/openid-configuration 的位址。以下是一些常見的簽發者:

供應商簽發者
GitLab.comhttps://gitlab.com
自行管理的 GitLab你的 GitLab 位址,例如 https://gitlab.example.edu
Googlehttps://accounts.google.com
Microsoft Entra IDhttps://login.microsoftonline.com/,後面接你的租用戶 ID 和 /v2.0
Keycloakhttps://sso.example.edu/realms/,後面接領域(realm)名稱

允許清單項目和網域規則只會比對已驗證的電子郵件地址。只有供應商表示地址已驗證時,伺服器才會視為已驗證:GitHub 將它標示為已驗證,或 OpenID Connect 的 email_verified 宣告為 true。

有些機構的供應商不提供這個宣告。如果你的供應商也是如此,而且它只發出貴機構掌控的地址,請設定 OLEAFLY_OIDC_<NAME>_TRUST_EMAIL=true。如果供應商允許使用者隨意填寫任何電子郵件地址,就絕對不要設定它,否則任何人都能冒充你允許清單上的人登入。

如果你的大學為自己的代理伺服器或登入服務自行簽發憑證,伺服器就必須信任該憑證授權單位,每一台執行 Oleafly 的電腦也一樣。

不使用 Docker 時,請把憑證加入作業系統。在 Debian 和 Ubuntu 上,把憑證複製到 /usr/local/share/ca-certificates/,檔名以 .crt 結尾,再執行 sudo update-ca-certificates。

Docker 映像檔沒有套件管理員,所以要給它一份包含你憑證的憑證清單。在 Debian 或 Ubuntu 機器上,於 docker-compose.yml 旁執行:

終端機視窗
cat /etc/ssl/certs/ca-certificates.crt university-ca.pem > ca-bundle.pem
chmod 644 ca-bundle.pem

接著在 docker-compose.override.yml 中把這個檔案加到伺服器,再執行一次 docker compose up -d:

services:
oleafly-server:
volumes:
- ./ca-bundle.pem:/etc/ssl/certs/ca-certificates.crt:ro

電子郵件是選用的,沒有它其他功能都能運作。沒有電子郵件時,你要自己把伺服器位址傳給對方,而 Oleafly 會在 與你分享的專案 下列出與每個人共用的專案。

要設定電子郵件,請給伺服器一個 SMTP 帳號:

OLEAFLY_SMTP_URL=smtps://oleafly%40example.org:example-app-password@smtp.example.org:465
OLEAFLY_MAIL_FROM=Smith Lab <oleafly@example.org>

兩行都要設定,或兩行都不設定。使用者名稱和密碼中的特殊字元要寫成 URL 形式,例如用 %40 代表 @。

  • smtps:// 從一開始就使用 TLS,除非你指定其他連接埠,否則使用連接埠 465。
  • smtp:// 除非你指定其他連接埠,否則使用連接埠 587,然後以 STARTTLS 切換成 TLS。如果郵件伺服器不提供 STARTTLS,伺服器就不會寄信。
  • 同一台機器上的郵件中繼是例外:smtp://localhost、smtp://127.0.0.1 和 smtp://[::1] 不使用 TLS 寄信。
  • 位於同一個私人網路上的郵件中繼,在加上 ?tls=none 後可以略過 TLS,例如 smtp://mailpit:1025?tls=none。此時位址中不能包含使用者名稱或密碼,因為它們會以未加密的方式經過網路。只有在其他人無法連到該網路時才使用。

伺服器會用系統信任的憑證檢查郵件伺服器的憑證。

共有六種電子郵件。寄給已有帳號者的信,只會寄到他們已驗證的地址,而且一律略過 GitHub 的 noreply 地址。

電子郵件寄出時機
加入伺服器管理員用電子郵件地址把某人加入允許清單。內容有伺服器名稱、加入 Oleafly 連結和伺服器位址。用 GitHub 使用者名稱或網域規則加入某人時不會寄信,因為伺服器還沒有他們的地址。
專案已共用專案擁有者把某人加入專案。內容有專案標題、共用者、對方的角色,以及開啟專案的連結,還有專案的網頁,供連結無法開啟應用程式時使用。之後變更角色不會寄信。每個人都可以在 設定 → 協作 中該伺服器的卡片上關閉這類信件。
新裝置帳號在另一台裝置上登入。內容有裝置名稱、其系統,以及以伺服器時區表示的時間,並提醒如果不是本人,請把該裝置登出。新帳號的第一台裝置不會收到信。設定 TZ 可以選擇時區,例如 TZ=Europe/Berlin。
訪客邀請專案擁有者邀請訪客。內容有專案標題、邀請者、加入 Oleafly 連結,以及用來登入的位址。開啟核准時,會在邀請獲得核准後寄出。
提及有人在留言或回覆中提及某位成員。內容會說明是誰提及他們、專案和檔案、留言所附著的文字,以及留言內容,並附上在 Oleafly 中開啟該留言的連結。信件在留言送達伺服器約一分鐘後寄出,同一個人在這一分鐘內被提及的內容會合併成一封信。自己的留言,或關於自己無法開啟的專案的留言,都不會寄信,編輯留言也不會重複寄出同一則提及。每個人都可以在 設定 → 協作 中該伺服器的卡片上,用 有人在評論中提及我時寄郵件給我 關閉這類信件。
登入連結有人在伺服器的登入頁面上要求寄送。

管理員可以用伺服器設定中的 電子郵件通知,停止寄出除了登入連結以外的所有信件。登入連結一律會寄出,因為沒有它們就無法登入。

在管理主控台中開啟 電子郵件。它會顯示電子郵件是否已開啟以及寄件者地址,絕不會顯示密碼。管理員可以選取 寄送測試郵件,寄到自己已驗證的地址。頁面接著會說明信件是否已寄出,或郵件伺服器的回應是什麼。

電子郵件關閉時,頁面會顯示 加入 Oleafly 連結和伺服器位址,讓你自己傳給對方。

寄信從不會拖慢它背後的操作。伺服器把信件保留在記憶體中的佇列裡,並在 30 秒、2 分鐘、10 分鐘、30 分鐘和 2 小時後重試。每次失敗的嘗試都會在伺服器記錄中留下警告,電子郵件 頁面會顯示最近一次的失敗。如果最後一次嘗試也失敗,伺服器會記錄錯誤並丟棄該封信。伺服器重新啟動時仍在等待的信件會遺失。

人們也可以用伺服器寄給他們的連結登入,這樣就不需要 GitHub 或 OpenID Connect 帳號。這需要先設定電子郵件。接著由管理員在伺服器設定中開啟 透過電子郵件登入。預設是關閉的。

使用者在 Oleafly 中選取 使用電子郵件繼續,在瀏覽器中輸入自己的地址,再選取 寄連結給我。連結只能使用一次,有效 15 分鐘,且只能在要求它的電腦上使用。開啟連結會顯示一個帶有 登入 按鈕的頁面。單單開啟連結並不會用掉它,所以會自動點擊連結的郵件掃描程式無法把它用掉。

你的存取規則仍然決定誰能進入:該電子郵件地址的允許清單項目、網域規則或訪客邀請。以 GitHub 使用者名稱建立的允許清單項目不符合電子郵件連結。無論伺服器是否讓該地址進入,頁面顯示的內容都一樣,因此沒有人能用它查出誰有帳號。

開啟這項功能也會讓既有帳號可以使用電子郵件連結。連結會登入已把該地址列為已驗證地址的帳號。伺服器會保留供應商為帳號回報的每一個已驗證地址,而不只是主要地址,即使使用者之後從供應商移除該地址,伺服器仍會保留。例如,GitHub 會回報 GitHub 帳號上的每一個已驗證地址。因此,任何能在其中一個地址收信的人,都可以用電子郵件登入該帳號。開啟之前,請確認使用者仍然掌控帳號上的每一個地址。

如果一個地址屬於多個帳號,連結不會登入其中任何一個。如果擁有該地址的唯一帳號已被停權或移除,連結會被拒絕,直到你讓這個人重新加入。

伺服器在 15 分鐘內,對同一個電子郵件地址最多寄出 3 個連結,對同一個 IP 位址最多寄出 100 個連結,所以同一個位址下的 50 人班級都能登入。OLEAFLY_EMAIL_LINKS_PER_ADDRESS 和 OLEAFLY_EMAIL_LINKS_PER_IP 可以變更這些數字。同一個 /64 網路中的所有 IPv6 位址都算作一個位址。關閉 透過電子郵件登入 會讓已經寄出的連結失效。

如果瀏覽器在登入後無法回到 Oleafly,例如在受到嚴格限制的電腦上,使用者可以用代碼登入。它不需要任何設定,並且適用於伺服器擁有的所有登入選項。

Oleafly 會顯示你的伺服器位址後面加上 /auth/device,以及一組八個字母的代碼。使用者在任何手機或電腦上開啟該位址,輸入代碼,確認頁面顯示的電腦名稱,然後登入。登入必須在他們輸入代碼的那個瀏覽器中完成,所以別人以連結傳給他們的登入頁面不會讓任何人登入。

代碼只能使用一次,10 分鐘後失效,而且只有要求它的那份 Oleafly 才能完成登入。停止,這不是我 會取消它。同一個 IP 位址在 10 分鐘內可以要求 100 組代碼,並輸入 10 次錯誤的代碼。這足夠讓 50 人的班級共用一個位址,OLEAFLY_DEVICE_CODES_PER_IP 可以變更這個數字。

只有登入並不足以進入。必須有存取規則讓這個人進入。請在管理主控台的 存取規則 下管理它們:

  • 允許名單:用電子郵件地址或 GitHub 使用者名稱加入某人,並指定他們獲得的角色。使用者名稱只適用於 GitHub,因為其他供應商允許使用者自行選擇或變更使用者名稱。如果伺服器會寄電子郵件,用電子郵件地址加入某人時,會把伺服器位址和 加入 Oleafly 連結寄給他們。
  • 網域:讓在某個網域(例如 cs.example.edu)擁有已驗證電子郵件地址的所有人,以你選擇的角色登入。

加入人員之後,他們就能在 Oleafly 中新增這台伺服器並登入。

在 人員 下,你可以變更某人的角色、停權或恢復他們、移除他們,以及把他們的裝置登出。被停權的人保留帳號,但在你恢復之前無法同步。他們的變更會留在自己的電腦上。

被你移除的人會一直被擋在外面,即使有網域規則涵蓋他們的地址,或專案擁有者邀請他們成為訪客也一樣。要讓他們回來,請再次以電子郵件地址或使用者名稱加入他們。他們會取回舊帳號,以及原有的所有專案。

如果伺服器開放給任何人使用,請設定 OLEAFLY_OPEN_SIGNUP=true 並重新啟動伺服器。之後,任何人只要用你設定的其中一個供應商登入,就會取得具有成員角色的帳號,不需要允許清單項目或網域規則。開啟 透過電子郵件登入 時,電子郵件連結也是如此。

開放註冊仍會擋下你移除或停權的人,以及已驗證地址屬於已移除帳號的任何人。允許訪客時,持有訪客邀請的人登入後會成為成員,並且仍會取得他們受邀的專案。

它也會開啟每個帳號的限制:除非你設定其他值,否則每個帳號最多可以儲存 100 MB、擁有 50 個共用專案,並在一小時內上傳 300 次。

管理主控台不會顯示開放註冊是否開啟。伺服器每次啟動時,記錄都會說明這一點:「Open sign-up is on, so anyone who signs in gets an account as a member.」成員在共用專案時可以互相查詢,所以在開放的伺服器上,請考慮在伺服器設定中關閉 成員目錄。

每個人都有一個伺服器角色,由管理員和維護者授予。在他們被加入的每個專案中,還有一個專案角色,由該專案的擁有者授予。角色列出了專案角色:擁有者、編輯者、審閱者、評論者和檢視者。

任何伺服器角色都無法單獨開啟專案。專案的存取權只來自專案的擁有者。

動作管理員維護者成員訪客
把伺服器新增到 Oleafly是是是是
查看成員清單是是是,除非管理員將其隱藏否
共用專案是是是否
閱讀安全記錄是是否否
把成員加入伺服器是是否否
任命維護者是否否否
變更伺服器設定是否否否
刪除專案以釋放儲存空間是否否否
登出某人的裝置是是,但不包括其他管理員或維護者的裝置僅限自己的裝置僅限自己的裝置
以伺服器的直接存取權讀取已儲存的專案應用程式中不行應用程式中不行應用程式中不行應用程式中不行

最後一列最重要。專案在伺服器上沒有加密,所以無論角色為何,執行這台機器的人都能讀取每一個已儲存的專案。Oleafly 不給任何角色(包括管理員)在應用程式內這麼做的方式。管理員為了釋放儲存空間而刪除專案時,專案的擁有者和成員會收到通知,他們自己的副本會留在各自的電腦上。

訪客是你伺服器以外的人,例如另一所大學的共同作者,由專案擁有者邀請加入專案。訪客只能看到他們受邀的專案。

新伺服器預設關閉訪客功能。管理員在伺服器設定中用 允許訪客 開啟。訪客需先經核准 預設是開啟的,所以管理員或維護者必須先核准每一份邀請,邀請才會生效。關閉它,邀請就會立即生效。管理員或維護者寄出的邀請會立即獲得核准。

如果你之後關閉 允許訪客,擁有者就無法再寄出新邀請,尚未使用的邀請也會失效。已經登入的訪客會保留他們的專案,直到擁有者把他們移除,或你在 人員 下把他們移除。

只有專案的擁有者可以從專案的 分享 對話方塊邀請訪客加入該專案。

  • 一份邀請只對應一個地址和一個專案,14 天後到期。
  • 一個人每小時最多可以寄出 20 份邀請。
  • 開啟核准時,邀請會在 人員 頂端的 待處理的訪客 下等待。管理員和維護者可以在那裡核准、拒絕或撤回。擁有者也可以撤回。
  • 如果伺服器會寄電子郵件,而且 電子郵件通知 是開啟的,訪客會收到邀請信。否則 Oleafly 會給擁有者一個 加入 Oleafly 連結,讓他們自己傳送。
  • 如果專案的人數已達伺服器允許的上限,邀請會先等待,並在有人離開後、對方下次登入時生效。

訪客新增伺服器,並用任何能讓伺服器取得受邀地址作為已驗證地址的選項登入:GitHub、OpenID Connect 供應商或電子郵件連結。未驗證的地址不算數。第一次登入會建立訪客帳號,並開啟該地址受邀的每一個專案。

訪客可以開啟並編譯受邀的專案,在角色允許時編輯專案,並登出自己的裝置。他們看不到成員目錄,也看不到任何人的電子郵件地址,不能共用專案、不能邀請其他人,也不能透過專案連結加入專案。要讓訪客取得另一個專案,該專案的擁有者要用同一個地址邀請他。

訪客被移出最後一個專案,或自行離開時,伺服器會終止他們的存取權。它會移除帳號並登出每一台裝置。新的邀請會把同一個帳號帶回來。如果你在訪客仍有專案時於 人員 下移除他,新的邀請不會把他帶回來。

擁有者把某人從專案中移除後,不論是否為訪客,那個人都無法再透過專案連結回來,即使連結共用是開啟的也一樣。每一次嘗試都會顯示在安全記錄中。要讓他們回來,擁有者要再次加入他們,如果對方是訪客,則寄出新的邀請。自行離開專案的人仍然可以透過專案連結重新加入。

開啟瀏覽器存取後,人們不必安裝 Oleafly,就能在網頁瀏覽器中開啟與他們共用的專案。他們可以編輯、建議變更、留言、聊天,以及閱讀最新編譯的 PDF。在瀏覽器中工作說明他們會看到什麼。

設定 OLEAFLY_WEB=true 並重新啟動伺服器。發布的容器映像檔已包含瀏覽器應用程式。不含瀏覽器應用程式的組建會記錄「OLEAFLY_WEB is true, but this build of Oleafly Server has no browser app, so browser access stays off.」

開啟之後:

  • 瀏覽器應用程式位於你的伺服器位址後面加上 /web/,例如 https://collab.example.org/web/。每個專案在 /p/ 下的頁面也會多一個 在瀏覽器中開啟 連結。
  • 人們在 /web/sign-in 登入,使用與 Oleafly 中相同的供應商和電子郵件連結,並由相同的存取規則決定誰能進入。瀏覽器會保持登入 30 天。
  • 每個瀏覽器都算作該帳號的一台裝置,名稱類似「Safari on macOS」。它會出現在該人員的裝置清單和安全記錄中,將它登出就會結束該瀏覽器的工作階段。
  • 瀏覽器透過 WebSocket 連線到 /web/ws,沒有較慢的替代途徑,所以你的代理伺服器必須在那裡傳遞 WebSocket 升級要求。Caddy 以及在反向代理後方中的 nginx 和 Apache 範例都已經這樣做。
  • 人們閱讀的 PDF 是擁有者或編輯者在 Oleafly 中最新編譯的那一份。編譯的 PDF說明它是怎麼送到那裡的。

瀏覽器應用程式無法嵌入其他網站的框架中顯示。除了載入人們的頭像圖片之外,它只會連線到你的伺服器。

管理主控台是在 Oleafly 中管理一台伺服器的視窗。管理員和維護者可以開啟。在 設定 → 協作 中,選取伺服器卡片上的 開啟管理主控台,或 管理伺服器 頂端的同名按鈕。每台伺服器都有自己的視窗。

區段顯示與可執行的操作
總覽伺服器是否正常、有多少人員、裝置和專案、誰在線上、使用了多少儲存空間、它的電子郵件和登入選項,以及一目了然的設定。伺服器沒有任何登入選項時,會警告 沒有人能登入;資料資料夾無法寫入時,會警告 伺服器無法儲存檔案。
人員所有登入過的人。變更角色、停權或移除人員,並登出他們的裝置。等待核准的訪客邀請在頂端。
存取規則允許的人員清單和網域規則。
專案伺服器上共用的每一個專案,包含擁有者、人數、大小和最近活動。可依標題或擁有者搜尋,只顯示已共用、已封存或上傳中的專案,並封存或還原專案。
設定伺服器設定。
電子郵件電子郵件是否已設定、寄件者地址和最近一次的失敗。可從這裡傳送測試電子郵件。
安全性記錄登入和被拒絕的登入、裝置、人員、設定、專案和訪客。每筆項目都會說明是誰、何時、從哪個 IP 位址所做,並附上詳細資料,例如專案、使用的登入選項,或登入被拒絕的原因。
連線檢查與 測試連線 相同的檢查,從你的電腦對伺服器執行。

維護者可以使用每一個區段,但不能讓任何人成為管理員或維護者,不能查看或登出其他管理員或維護者的裝置,不能查看儲存空間用量、封存或還原專案、變更伺服器設定,或傳送測試電子郵件。管理員全部都可以做。

封存專案會對所有人停止共用。人們停止同步該專案並保留自己的副本,伺服器會在 OLEAFLY_ARCHIVE_DAYS 天後刪除它,除非管理員先把它還原。還原會重新與同樣的人共用。從未完成第一次上傳的專案無法還原。兩者都會顯示在安全記錄中。

主控台從不開啟專案。它顯示標題、擁有者和大小,專案內部的內容則一概不顯示。

這些設定套用於伺服器上的所有人。只有管理員可以變更。

設定作用
允許訪客成員可以邀請伺服器以外的人加入自己擁有的專案。
訪客需先經核准維護者或管理員先核准每一份訪客邀請,邀請才會生效。
成員目錄成員在共用專案時,可以依名稱互相查詢。
在目錄中顯示電子郵件地址成員查詢某人時,可以看到彼此的電子郵件地址。
允許透過連結分享專案擁有者可以讓任何成員從連結開啟專案。
允許筆記公開連結成員可以在一個連結上發佈筆記的唯讀副本,任何人不必登入就能開啟。預設為關閉。關閉後,所有已發佈的連結都會停止運作,直到你再次開啟。請參閱發佈唯讀副本。
允許專案存取記錄專案擁有者可以保留一份記錄,記下誰開啟過他們的專案。
允許留言共用專案中的人可以對文字留言並回覆。關閉它會在所有地方隱藏留言,但仍會保留儲存。
電子郵件通知關閉後,會對所有人停止伺服器寄出的信件,登入連結除外。
透過電子郵件登入人們可以用寄到電子郵件地址的連結登入。這需要伺服器的電子郵件設定。
圖片預覽

無法載入 AI 回答

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