跳转到主要内容

前提条件

Overleaf 是一个典型的微服务架构开源项目,所有服务都运行在 Docker 中。 要搭建 Overleaf 开发环境,你需要一台性能强劲的服务器;建议配置至少 8 核 CPU 和 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日