如何在树莓派上编译并在 Docker上部署 Overleaf

请注意，本文编写于 153 天前，最后修改于 149 天前，其中某些信息可能已经过时。

写在开头

又到了一年毕业季，也到了要水论文的时间了，众所周知一般的大学毕业论文都要求使用 latex 撰写，而据我所知相当比例的大学生一直到开始动手写论文前都没听说过 latex，最后百度一搜索一整页的广告。

就算你不小心忽略了所有的广告，基本也是推荐的一些十几年前的方案，比如 CTeX 或者 TeX Live+TeXstudio ，限定电脑编辑，界面复杂，但是最重要的是，这种方案不适合使用 AI 评审论文或者检查问题，只适合那些真正的学术狂人使用而不是水水的大学生（雾）。

作为计算机系的学生，最重要的应该是好用的界面和 AI，这样才能大大提升写论文的体验。

这个时候很多学生就会使用比较新的多人协作在线编辑器，但是这种编辑器最大的问题是 -- 要氪金！而且一般收费还不便宜，如果使用免费版不仅编译时间有限制，而且多人协作、AI 工具、GitHub 集成、版本管理什么的统统不给用。

作为一名 Overleaf 社区版重度用户，我一般直接把 Overleaf 部署在电脑的 WSL2 内的 Docker 内，这么做虽然方便，但是每次重启电脑都要重启服务，而且 WSL 的 IO 速度实在是太太太慢了，每次调试我都要在电脑前面挂几个小时，非常的影响体验。

正好前几天把树莓派系统从 SD 卡迁移到了 NVME SSD 上，这下 IO 性能应该就不是瓶颈了，因此就准备将 Overleaf 服务迁移到树莓派上。

环境准备

树莓派 5 代并使用 SSD 启动（四代也可以，需要使用 USB 硬盘）
Ubuntu 25.1 Server（或者类似环境的服务器系统）
流畅的网络环境或者镜像环境
Docker 以及 Docker compose
一个域名和 Cloudflare 的连接器（将 HTTP://sharelatex:80 映射到你的域名）

如果不会的可以去看上一篇部署博客的文章

基础环境配置

老规矩，干任何事情之前都先更新：

# 更新系统
sudo apt update && sudo apt upgrade -y

然后新建文件夹并创建配置文件：

mkdir ~/overleaf && cd ~/overleaf
nano docker-compose.yml

填入以下内容：

services:
  sharelatex:
    container_name: sharelatex
    restart: always
    image: my-overleaf:v1    # 此处的容器是待会将要创建的
    ports:
      - 8080:80
    depends_on:
      mongo:
        condition: service_healthy
      redis:
        condition: service_started
    volumes:
      - ./overleaf_data:/var/lib/overleaf
    environment:
      - OVERLEAF_MONGO_URL=mongodb://mongo:27017/sharelatex?replicaSet=rs0
      - OVERLEAF_REDIS_HOST=redis
      - OVERLEAF_SITE_URL=https://example.com # 填写你隧道对应的域名
      - OVERLEAF_BEHIND_PROXY=true
      - OVERLEAF_APP_NAME=My Local Overleaf    # 自定义 Overleaf 的名字
      - [email protected]    # 如果有人想要注册账户，此邮箱将会显示
      - NODE_OPTIONS=--max-old-space-size=2048

  mongo:
    container_name: mongo
    image: mongo:8.0
    restart: always
    command: ["--replSet", "rs0", "--bind_ip_all", "--wiredTigerCacheSizeGB", "1"]
    volumes:
      - ./mongo_data:/data/db
    healthcheck:
      test: ["CMD", "mongosh", "--eval", "db.adminCommand('ping')"]
      interval: 10s
      timeout: 5s
      retries: 5

  redis:
    container_name: redis
    image: redis:7.2-alpine
    restart: always
    volumes:
      - ./redis_data:/data

  tunnel:
    container_name: cloudflare-tunnel
    image: cloudflare/cloudflared:latest
    restart: always
    command: tunnel --no-autoupdate run --token eyJhI....   # 替换成你的 cloudflared Token

可以看到创建了 4 个容器，分别是：

sharelatex：用来放置 Overleaf 的主容器，如配置文件所示，所使用的镜像是待会编译源代码后下载宏并上传字体的完整包。
mongo：数据库容器，用来存储 Overleaf 的配置信息和你写的论文的源文件。
redis：数据库容器，用来高速存储实时的编辑操作，提高系统响应速度。
tunnel：Cloudflare 的代理隧道容器，用来把服务映射到公网。

编译源码

之后需要在官方 GitHub 仓库拉取 Overleaf 社区版的源代码并编译。

拉取源码的同时创建目录：

cd ~
git clone https://github.com/overleaf/overleaf.git overleaf-src

因为在容器环境内运行，后台自动补丁可能会触发一些非零的返回码导致 exit code: 100 ，为了提升编译稳定性建议执行下面的命令修改配置文件禁用后台自动升级：

先打开配置文件：

nano server-ce/Dockerfile-base

找到第 25 行到 29 行左右，如下所示操作：

把25行 unattended-upgrades \ 删掉。
把29行 && unattended-upgrade --verbose --no-minimal-upgrade-steps \ 删掉。

然后回到对应的目录并编译 Overleaf 基础镜像，这里编译的镜像是底层依赖、Node.js 环境和 TeX Live 骨架：

cd ~/overleaf-src
DOCKER_BUILDKIT=1 docker build \
  -f server-ce/Dockerfile-base \
  -t sharelatex/sharelatex-base:latest .

如果提示没有 buildx 组件则执行下面的命令安装最新版 Docker，执行后重新运行上面的编译命令。

# 下载官方安装脚本
curl -fsSL https://get.docker.com -o get-docker.sh

# 运行脚本进行升级
sudo sh get-docker.sh

# 修复依赖
sudo apt-get install -f

# 安装最新的 Docker 核心组件和 buildx 插件
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

接下来需要编译 Overleaf 应用的源代码并安装到刚才编译好的基础镜像中，执行下面的命令编译：

DOCKER_BUILDKIT=1 docker build \
  -f server-ce/Dockerfile \
  -t my-overleaf:v1 .

这个步骤树莓派耗时大约在20分钟 - 1小时左右，观察命令输出，如果没有报错就慢慢等吧，搞杯咖啡，坐和放宽（乱入），如果编译完成，尝试执行 docker images 命令看看有没有叫做 my-overleaf:v1 的镜像，如果有的话那么可以准备启动了。

启动镜像

使用 docker compose 拉起 Overleaf 架构

docker compose up -d

此时应该会跑完长长的一串拉取镜像后启动四个容器，执行

docker ps

如果显示四个容器都是 up 或者 healthy 的话就说明启动成功了。初次启动需要执行命令配置 Mongo 数据库：

# 进入 mongo 容器内部并执行初始化命令
docker exec -it mongo mongosh --eval "rs.initiate()"

# 给数据库改名
docker exec -it mongo mongosh --eval 'cfg = rs.conf(); cfg.members[0].host = "mongo:27017"; rs.reconfig(cfg, {force: true});'

# 重新启动容器
docker compose up -d

等待几分钟后尝试浏览器访问 http://你的树莓派IP:8080/launchpad 此时应该可以进入到管理员设置界面了，可以选择在此时设置账户，也可以待会完整所有操作后再设置。

安装完整宏

从官方编译的 Overleaf 默认是极简版 LaTeX 很多论文常用的宏包都没有，如果想要正常的写论文的话需要在容器内进行升级。

将要下载 4800 个左右的宏包和大约 2 - 3 GB 的数据库，所以接下来又是坐和放宽的咖啡时间了，根据网络条件大约会花费 1 - 2 小时。

首先先进入容器，如果有代理记得设置：

docker exec -it sharelatex bash

然后安装完整宏包：

# 首先更新 tlmgr
tlmgr update --self

# 安装完整宏
tlmgr install scheme-full    # 如果想快一点可以安装标准宏 scheme-medium

然后是漫长的等待，安装完成后清理缓存：

# 进入容器（如果你已经退出了）
docker exec -it sharelatex bash

# 清理所有宏包备份
tlmgr backup --clean --all

# 清理格式文件的临时目录
rm -rf /usr/local/texlive/2025/texmf-var/web2c/*.log
rm -rf /usr/local/texlive/2025/tlpkg/backups/*
rm -rf /tmp/*

# 清理系统的缓存
apt-get autoremove -y
apt-get clean
rm -rf /var/lib/apt/lists/*

# 清理 Overleaf 的临时编译日志
rm -rf /var/lib/sharelatex/tmp/*

上传字体

安装 Overleaf 的精简版 Linux 容器内部不会像标准版系统或者 Windows 一样自带常用字体，所以需要手动把字体拷贝到容器内，不然绝大多数 LaTeX 都会提示字体缺失而无法编译。

首先在树莓派里面新建一个字体文件夹：

# 如果没有退出容器
exit

mkdir ~/overleaf_fonts

然后需要在你的 Windows 主机里面找到 C:\Windows\Fonts 字体目录，然后用 WinSCP 拷贝这些常用的字体到这个目录：

中文字体

标准宋体
标准黑体
标准楷体
标准仿宋
微软雅黑
思源宋体
思源黑体

英文字体

Times New Roman
Arial / Helvetica
Courier New
Consolas / JetBrains Mono
Latin Modern Roman

日文字体

标准明朝
标准哥特
游明朝
游哥特
思源日文

完成后执行：

# 将字体拷贝进正在运行的 sharelatex 容器
docker cp ~/overleaf_fonts/ sharelatex:/usr/share/fonts/truetype/custom

# 进入容器
docker exec -it sharelatex bash

# 安装字体管理工具（如果镜像里没有的话）
apt-get update && apt-get install -y fontconfig

# 刷新系统字体缓存
fc-cache -fv

# 验证字体是否安装成功
fc-list :lang=zh

如果列表里面看到了你上传的这些字体则说明以及成功上传，接下来需要固化镜像。

固化镜像并保存

刚刚的这些操作都是保存在容器中的，一旦容器被删除，这些操作都会丢失，所以需要提交镜像，然后保存一份压缩包到本地方便迁移和备份。

先提交镜像：

docker commit sharelatex my-overleaf:v1-full-with-fonts

等待一会提示提交成功后就可以保存为压缩包了，执行：

# 导出并压缩
docker save my-overleaf:v1-full-with-fonts | gzip > my_overleaf_full_backup.tar.gz

之后就可以把这个 my_overleaf_full_backup.tar.gz 压缩包导出到电脑上了，如果嫌弃 WinSCP 速度太慢可以直接拿 Python 开个服务器下载：

# 执行后访问 http://树莓派IP:13000
python3 -m http.server 13000

备份完之后就需要将容器迁移到新的镜像了，首先先删除旧容器：

docker compose down

然后修改 docker-compose.yml，指定镜像为刚刚固化的：

nano docker-compose.yml

将原来的

services:
  sharelatex:
    container_name: sharelatex
    image: my-overleaf:v1

改为：

services:
  sharelatex:
    container_name: sharelatex
    image: my-overleaf:v1-full-with-fonts

然后重新拉起容器：

docker compose up -d

一些收尾工作

当这些都完成后记得删除已经不再需要的源代码文件夹和字体文件夹：

# 删除字体
rm -rf ~/overleaf_fonts/

# 删除源码
rm -rf ~/overleaf_src/

# 记得确认已经传输到电脑上再删
rm ~/overleaf/my_overleaf_full_backup.tar.gz

之前构建的镜像也可以删除：

# 删除最初的 v1 和没有字体的镜像
docker rmi my-overleaf:v1
docker rmi sharelatex/sharelatex:latest
docker image prune -f

清理构建的缓存：

# 清理所有停止的容器、未使用的网络和构建缓存
docker system prune --volumes -f

结尾

此时一个完整的私人 Overleaf 就已经配置好了，可以通过公网访问，支持多人协作，可以使用网页在线写，也可以使用 VSCode 的插件写论文，这样就可以直接接入 MCP 服务器问 AI :)

可以直接使用网页在线编辑：

VSCode 插件建议使用 Overleaf Workshop 效果如图所示：

也可以使用 VSCode 自带的 Git 集成实现版本管理，总之玩法无限，比那些老东西酷炫多了（雾）。

如何在树莓派上编译并在 Docker上部署 Overleaf

写在开头

环境准备

基础环境配置

编译源码

启动镜像

安装完整宏

上传字体

固化镜像并保存

一些收尾工作

结尾

添加新评论

评论列表

如何在树莓派上编译并在 Docker上部署 Overleaf

写在开头

环境准备

基础环境配置

编译源码

启动镜像

安装完整宏

上传字体

固化镜像并保存

一些收尾工作

结尾

如何使用吃灰的树莓派搭建博客并魔改主题

没有了

添加新评论

评论列表