跳轉到主要內容

先決條件

Overleaf 是典型採用微服務架構的開源專案,所有服務都在 Docker 中執行。 要建立 Overleaf 開發環境,您需要一台效能強大的伺服器;建議至少具備 8 核心與 16GB 記憶體,因為您需要同時執行超過 20 個容器。
由於擁有 8 個以上 CPU 核心的伺服器通常價格昂貴,強烈建議您使用本機電腦進行開發。
同時,身為開發者,我們相信您應該已經熟悉 Docker 安裝。我們強烈建議使用較新且穩定的 Ubuntu LTS(例如 2025–2026 年的 Ubuntu 24.04)以及最新版 Docker 進行開發,這可以降低遇到意外錯誤的可能性。 總結來說,您需要:
  • 一台效能強大的伺服器/桌上型電腦用於開發
  • 較新且穩定的 Ubuntu LTS(例如 Ubuntu 24.04)
  • Docker 與 Git 環境

設定教學

這裡以 Ayakaleaf Pro 為例,示範如何建置 Overleaf 開發環境。除非另有說明,以下所有指令都在 develop 目錄中執行。
1

拉取原始碼

首先,讓我們複製儲存庫:
bash
2

同步 yarn.lock

儲存庫使用 Yarn 4(根目錄 package.json 中的 packageManager),其 yarn.lock 可能與各 package.json 檔案不同步。首次複製後以及每次修改 package.json 後,請同步它:
bash
bin/sync 會在 node:24.18.1 容器中執行 yarn install --mode=update-lockfile,因此主機上不需要 Node.js。不要提交修改後的 yarn.lock。
3

建置開發映像檔

建置服務:
bash
如果 Docker 在平行建置服務時記憶體不足,請在此目錄中建立一個內容為 COMPOSE_PARALLEL_LIMIT=1 的 .env 檔案。
4

套用翻譯

Ayakaleaf Pro 的模組將其翻譯保存在 services/web/locales/locales_patches/ 中,已提交的語系檔不包含這些翻譯。請在首次啟動前套用一次,否則這些模組的頁面會顯示 about_to_permanently_delete_accounts 之類的鍵,而不是文字:
bash
它需要主機上安裝 jq。新增翻譯或切換分支後請再次執行,請參閱 更新 i18n 翻譯。
5

啟動所有微服務

接著啟動服務:
bash
服務執行後,開啟 http://localhost/launchpad 以建立第一個管理員帳號。 如果修改過 OVERLEAF_PORT,請加上連接埠(見下文)。
LDAP 預設為開啟(dev.rc 中的 LDAP_ENABLED=true)。此時 launchpad 會顯示 LDAP 管理員表單:它只要求填寫電子郵件,之後該管理員會透過 LDAP 登入,例如使用 professor / professor(professor@planetexpress.com)。測試使用者列在 develop/authentication/README.md 中。設定 LDAP_ENABLED=false 和 SAML_ENABLED=false 即可改為建立有密碼的本機管理員。
develop/dev.env 已經設定了 ADMIN_PRIVILEGE_AVAILABLE=true,因此管理員不需額外設定即可開啟管理面板。

設定(dev.rc)

develop/dev.rc 位於 dev.env 旁邊,保存開發環境的開關,類似 Overleaf Toolkit 中的 overleaf.rc。修改某個值後重新執行 bin/dev 即可生效;關閉的功能也會停止其容器。 每個功能都將其 docker-compose.yml 和其他檔案放在各自的資料夾中:authentication/ldap、authentication/saml、mail、s3、hoppscotch 和 grafana。需要沒有環境變數的 web 設定的功能,會將檔案掛載到 /etc/overleaf/settings.d/,由 develop/settings.dev-env.cjs 將它們全部合併。所有 bin/* 指令碼都經由 bin/docker-compose 執行,後者會加入已開啟功能的檔案。需要自行執行 compose 指令時,請使用 bin/docker-compose 而不是 docker compose。
本機磁碟區和 RustFS 是彼此獨立的儲存:在 S3_ENABLED=true 下建立的專案,切換到 false 後沒有歷史記錄和二進位檔案,反之亦然。若要把在 S3_ENABLED 出現之前就已執行的環境中的檔案複製到 RustFS,請依照 develop/README.md 中的「Moving existing data into RustFS」操作。

連接埠

網站、RustFS 主控台和 Hoppscotch 監聽主機的 127.0.0.1;在遠端機器上,請先轉送它們的連接埠,例如 ssh -L 9001:localhost:9001 <host>。網站使用 dev.rc 中的 OVERLEAF_PORT,因此如果修改過它,請在下方的位址中加上連接埠。 Mailpit、Grafana、Mongo Express 和 RedisInsight 由網站透過 webpack-dev-server 在各自的路徑上提供,因此不需要獨立的連接埠。登入後,網站導覽列中的 Dev tools 選單會連結到它們;在 dev.rc 中關閉了對應功能的頁面不會出現。設定開發工具 介紹了每個工具的作用。 S3 API(連接埠 9000)和 SMTP(連接埠 1025)只能在 Docker 網路內存取。Mongo(27017)、Redis(6379)、Mongo Express(8081)、RedisInsight(5540)和 git-bridge(8000)只發布在主機的 127.0.0.1 上。

TeX Live

沙箱編譯預設為開啟:develop/dev.env 設定了 SANDBOXED_COMPILES=true 以及映像檔 ghcr.io/ayaka-notes/texlive-full:2026.1 和 ghcr.io/ayaka-notes/texlive-full:2025.1。clsi 不會自行拉取映像檔,因此請拉取一次:
詳情請參閱 設定沙箱編譯。
在 SANDBOXED_COMPILES 關閉期間建立的專案沒有 TeX Live 映像檔。它仍能使用預設映像檔編譯,但在程式碼和 PDF 之間跳轉會失敗,並顯示「That didn’t work. Recompile and try again.」。請為這類專案設定一次 TEX_LIVE_DOCKER_IMAGE 的映像檔;不加 --commit 時,指令碼只會顯示將要修改的內容:
dev.env 也透過 PANDOC_IMAGE=overleaf-pandoc:local 開啟了 Pandoc 轉換。請在儲存庫根目錄下建置一次該映像檔:
要在 macOS 主機上編譯,可能需要在 develop 目錄中建立一個包含 DOCKER_SOCKET_PATH=/var/run/docker.sock.raw 的 .env 檔案,以覆寫 Docker 通訊端的路徑

開發

為了避免每次修改程式碼後都要執行 bin/build && bin/up,您可以在 開發模式 下執行 Overleaf Community Edition,此模式下服務會在程式碼變更時自動更新。 為此,請使用內附的 bin/dev 腳本:
這會使用 node --watch 啟動所有服務,自動監控程式碼並在必要時重新啟動服務。 修改 dev.rc 後請再次執行。 為了提升效能,您可以向 bin/dev 腳本提供以空格分隔的清單,僅以開發模式啟動部分服務:
以 開發模式 啟動 web 服務時,只有在後端程式碼變更時才會更新 web 服務。若要同時自動更新前端程式碼,請確保也以 開發模式 啟動 webpack 服務。
如果未指定任何服務,所有服務都會以開發模式啟動。 新增翻譯或切換分支後,請執行 bin/i18n,請參閱 更新 i18n 翻譯。

偵錯

在 開發模式 下執行時,大多數服務會開放一個除錯連接埠,你可以將除錯器(例如 Chrome Dev Tools 中的檢查器或 IDE 整合的除錯器)附加到該連接埠。下表列出每個服務在主機 的 127.0.0.1 上開放的連接埠: 若要使用 Chrome 的 遠端偵錯 附加到服務,請前往 chrome://inspect/ 並確認已勾選 Discover network targets。接著點選 Configure…,並為每個您要附加偵錯工具的服務新增一筆 localhost:[service port] 項目。 新增項目後,該服務會顯示為 Remote Target,您可以對其進行檢查與偵錯。

日誌

指令碼 bin/logs 會追蹤日誌並用 bunyan 格式化。它還需要 ggrep,這是在 macOS 上用 Homebrew 安裝 GNU grep 時的名稱;Ubuntu 沒有 ggrep 指令。
或者,您也可以直接執行:
請使用 bin/docker-compose 而不是 docker compose,這樣 dev.rc 中各功能的服務(mailpit、rustfs、ldap、saml、hoppscotch,以及帶有 Prometheus、Loki 和各 exporter 的 grafana)也能被找到。 設定 GRAFANA_ENABLED=true 後,每個容器的日誌也會出現在 Grafana 中,可以依服務、層級和文字篩選,請參閱 設定開發工具。

其他工具

完成以上所有步驟後,您可以參考下一節,為您的 Overleaf 開發環境加入一些偵錯工具。
最後修改於 2026年11月20日