先決條件
Overleaf 是典型採用微服務架構的開源專案,所有服務都在 Docker 中執行。- 官方 Community Edition 原始碼位於 GitHub Overleaf Official。
- Overleaf-CEP 的原始碼可在 GitHub Yu-i-i/Overleaf 取得。
- Ayakaleaf Pro 發布在 GitHub ayaka-notes/ayakaleaf-pro。
由於擁有 8 個以上 CPU 核心的伺服器通常價格昂貴,強烈建議您使用本機電腦進行開發。
- 一台效能強大的伺服器/桌上型電腦用於開發
- 較新且穩定的 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
啟動所有微服務
接著啟動服務:服務執行後,開啟 http://localhost/launchpad 以建立第一個管理員帳號。 如果修改過
bash
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 主控台和 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 不會自行拉取映像檔,因此請拉取一次:
dev.env 也透過 PANDOC_IMAGE=overleaf-pandoc:local 開啟了 Pandoc 轉換。請在儲存庫根目錄下建置一次該映像檔:
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 中,可以依服務、層級和文字篩選,請參閱 設定開發工具。

