前提条件
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 中,可以按服务、级别和文本筛选,参见 设置开发工具。

