Overleaf社区版搭建基础教程

概述

#

TL；DR

#

如果仅仅想要体验社区服务，可以直接访问https://latex.baos.eu.org通过在当前页面评论区留下邮箱或者发送邮件至chas5wasl@duck.com，不保证即时反馈，接收到验证链接后自行设置密码进行体验。

验证链接可能以 http://localhost 开头，请将链接修改为 https://latex.baos.eu.org

前言

#

Overleaf是一个在线的LaTeX编辑器，支持多人协作编辑，提供了丰富的模板和宏包，可以在线编译LaTeX文档。Overleaf有免费版和付费版，免费版有一些限制，如编译时间限制、项目数限制等。Overleaf的付费版提供了更多的功能，如无限编译时间、无限项目数、Git同步等。

开源版本的Overleaf称为"Overleaf Community Edition"，简称"Overleaf CE"。它是Overleaf团队推出的开源LaTeX协作编辑器，可让用户在自己的服务器上创建类似Overleaf的在线LaTeX编辑环境。这种自托管方式赋予用户在内部网络或私人服务器上创建、编辑和共享LaTeX文档的完全控制权。

• 数据隐私和安全性： 在某些情况下，可能对数据隐私和安全性有严格要求，不希望文档和敏感信息存储在第三方云服务上。独立部署Overleaf允许您完全掌握数据存储和访问，确保合规和安全标准。
• 机构内部部署： 一些大学、研究机构或企业可能需要在内部网络提供LaTeX编辑和协作功能，以支持学术、研究和文档创作。独立部署Overleaf能够满足这一需求，使机构内部用户轻松创建和编辑LaTeX文档。 定制需求： 如果您有特定的定制需求，希望对编辑器界面、功能或工作流程进行个性化定制，独立部署Overleaf提供更大的灵活性，可满足各种需求，实现编辑环境的定制化。
• 带宽和访问限制： 在某些地区或网络环境中，外部云服务的访问可能受到带宽或访问限制。独立部署Overleaf可为用户提供更流畅的内部网络访问体验。
• 成本效益： 对于一些组织而言，长期使用第三方云服务可能会导致高昂费用。独立部署Overleaf有助于节省成本，尤其是在大规模使用情况下。
• 技术支持和控制： 独立部署Overleaf让您在技术层面上更具掌控力，可以根据需要进行维护、升级和修复，与内部技术团队直接合作解决问题。

前提

#

1. 使用Linux或者Window服务器均可，性能稍强。（搭建的环境使用甲骨文的4H24GArm服务器,性能足够使用，操作系统使用Debian12.）
2. 安装Docker和Docker Compose。该部分比较简单，直接省略。如果是linux系统，直接运行curl -fsSL https://get.docker.com | sh --mirror=Aliyun即可。
3. 具有自己的二级域名（自建latex编译服务），使用caddy进行反向代理和自动https。

安装方法

#

使用Docker来方便快捷地搭建Overleaf社区版服务。这里有两种安装方式：一种是直接使用Overleaf社区版仓库里提供的docker-compose.yml文件，另一种是使用Overleaf官方提供的工具箱。Overleaf官方推荐使用第二种方式，但这里两种方式都介绍一下。

方法一：使用docker-compose.yml文件安装

#

待续

可以在Overleaf社区版仓库中找到docker-compose.yml文件，下载到本地，然后使用命令docker-compose up -d启动服务。这里可能需要根据自己的实际情况修改docker-compose.yml文件，如修改端口、数据卷路径等。

方法二：使用Overleaf工具箱安装

#

Overleaf官方提供了一个工具箱，包装了一些常用的docker命令，可以初始化、启动、停止、诊断、升级Overleaf服务。虽然我觉得相比直接使用docker-compose.yml，这个工具箱使部署docker的流程更复杂了，但这个工具箱的确提供了更多更灵活的定制选项。

使用这个工具箱部署Overleaf社区版服务，可以参考Overleaf社区版工具箱文档。简单来讲，有以下几步：

1. 下载工具箱git clone https://github.com/overleaf/toolkit.git
2. 进入工具箱目录cd toolkit
3. 初始化安装配置bin/init，运行此命令，将在当前目录下生成一个config文件夹，里面包含了三个配置文件：
   • overleaf.rc：Overleaf配置文件。用户可以在这个文件中配置Overleaf的一些参数，如端口、数据卷路径等。
   • variables.env：环境变量配置文件
   • version：选择Overleaf版本。注意在5.0.0版本之后，Overleaf将原来的ShareLaTeX商标替换为Overleaf商标，所以如果环境变量配置文件中如果使用OVERLEAF前缀的变量，需要选择5.0.0之后的版本。
4. 在修改完配置文件后，运行命令bin/up启动服务，在运行后可以看到服务的输出日志。如果想要停止服务，可以按Ctrl+C。 **检查无误之后，使用bin/up -d以后台模式启动服务。
5. 如果想要停止服务，可以使用命令bin/stop。
6. 配置Nginx反向代理（可选）。Overleaf社区版的docker-compose.yml文件中有一个nginx容器，如果使用Overleaf工具箱，在overleaf.rc配置文件中也可以配置Nginx。如果需要TSL/SSL加密，可以使用在初始化时使用bin/init –tls命令。这样会在config目录中生成一个nginx文件夹，里面包含了Nginx的配置文件和作为示例的SSL证书。

由于之前在服务器上已经部署了单独的Caddy服务来管理所有的网站，所以不使用Nginx服务来反向代理Overleaf服务。

其他常见问题

#

1. 升级TexLive

#

Overleaf的docker镜像中自带了一个基础版本的TeX Live，但是这个版本可能不包含所有的宏包。如果需要编译一些特殊的LaTeX文档，可能需要安装完整版的TeX Live。可参考Overleaf工具箱文档中升级Tex Live的文档。安装完整版TeX Live主要步骤如下：

docker exec -it overleaf bash #进入Overleaf容器
tlmgr --version #查看当前TeX Live版本
tlmgr install scheme-full  #更新TeX Live
tlmgr path add

如果不执行路径添加的命令，在Overleaf中编译LaTeX文档时，可能会出现无法编译EPS图片等问题。做完上述更改后，升级的TeX Live只会保存在当前的容器中，如果容器被删除，这些更改也会丢失。如果想要将这些更改保存到镜像中并在之后创建容器时使用，可以执行下面的操作： docker commit sharelatex sharelatex/sharelatex:with-texlive-full 然后直接在overleaf-toolkit/config/overleaf.rc文件当中修改OVERLEAF_IMAGE_NAME=sharelatex/sharelatex:with-texlive-full，按照上面的方法运行/bin/up或者/bin/up -d实现服务重新部署。

2. 更改Overleaf实例为简体中文

#

直接增加overleaf-toolkit/config/variables.env文件内部的环境变量，设置OVERLEAF_SITE_LANGUAGE=zh-CN即可

3. ARM架构镜像选择

#

实际操作当中发现，ARM版本的Overleaf版本总存在各种各样的问题，因此需要选择合适的版本镜像。具体来说，需要修改文件overleaf-toolkit/config/overleaf.rc当中修改变量OVERLEAF_IMAGE_NAME=kylindemons/sharelatex（镜像当前版本为5.1.0，官方工具箱最新版本为5.4.0，但是并未更新太多的新特性，不必特意求更新，稳定是第一位的）。

出现Email Protect提示

#

出现这种情况是因为使用CF小黄云的代理，为避免邮箱受到垃圾邮件的骚扰启用的保护措施。将邮箱地址使用<!--email_off-->contact@example.com<!--/email_off-->进行包裹即可

添加中文字体

#

使用 ShareLaTeX Docker 镜像时，为了支持中文显示，需要安装中文字体并更新字体缓存。以下是具体步骤：

1. 获取中文字体文件:

首先，下载包含中文字体的压缩包。例如，你可以使用以下命令下载一个常用字体集合：

wget "https://github.com/zhyounger/FontsFromWindows/archive/refs/heads/master.zip"

当然，你也可以从其他来源获取字体文件，只要是 TTF (TrueType Font) 格式即可。 确保下载的字体文件是合法的，并且拥有相应的许可证。

2. 复制字体文件到 Docker 容器:

将下载的字体文件解压，并将 TTF 文件复制到 ShareLaTeX 容器的字体目录下。 首先，确定你已经运行了 ShareLaTeX 容器。 假设你的 ShareLaTeX 容器名为 sharelatex，并且你已经将宿主机的 ~/sharelatex/fonts 目录绑定到了容器内的 /usr/share/fonts 目录。 那么，可以按以下操作：

# 如果 ~/sharelatex/fonts 目录不存在，先创建它
mkdir -p ~/sharelatex/fonts

# 创建一个子目录用于存放中文字体，例如 "zh-cn"。这个目录名可以自定义，但不要覆盖 /usr/share/fonts 本身。
mkdir -p ~/sharelatex/fonts/zh-cn

# 解压下载的字体文件
unzip master.zip

# 假设解压后的字体文件位于 FontsFromWindows-master/Fonts 目录下，将其复制到容器的字体目录
cp FontsFromWindows-master/Fonts/*.ttf ~/sharelatex/fonts/zh-cn/

# 进入容器内部执行更新字体缓存操作
docker exec -it sharelatex bash

注意： 请将 sharelatex 替换为你的实际容器名称，并将 FontsFromWindows-master/Fonts/*.ttf 替换为你实际的字体文件路径。

3. 更新容器内的字体缓存:

进入容器后，更新字体缓存以使系统识别新安装的字体。在容器内的 shell 中执行：

mkdir -p /usr/share/fonts/windows/fonts #创建一个新的字体存放路径，不覆盖原来的目录

fc-cache -fv

fc-cache -fv 命令会强制刷新字体缓存。

4. 提交 Docker 容器变更:

重要提示： 在更新字体缓存后，需要将更改提交到新的 Docker 镜像，否则容器重启后更改将会丢失。

首先，退出容器的 shell (输入 exit 并按回车)。 然后，执行以下命令：

docker commit sharelatex sharelatex:with-fonts

这里 sharelatex 是你的容器名称，sharelatex:with-fonts 是新镜像的名称。 你可以根据需要更改新镜像的名称。

5. 重启容器 (使用新镜像):

最后，停止并删除旧的容器，然后使用新镜像启动一个新容器：

docker stop sharelatex
docker rm sharelatex

#使用新的镜像运行容器
docker run --name sharelatex -d -v ~/sharelatex/fonts:/usr/share/fonts  <你的 ShareLatex 镜像名称>

请将 <你的 ShareLatex 镜像名称> 替换为你所使用的 ShareLaTeX 镜像名称。

注意事项：

• 目录绑定： 确保宿主机的 ~/sharelatex/fonts 目录正确地绑定到了容器的 /usr/share/fonts 目录。
• 容器名称： 在所有 Docker 命令中，将 sharelatex 替换为你的实际容器名称。
• 字体文件权限： 确保字体文件具有正确的权限，以便 ShareLaTeX 可以访问它们。 如果遇到权限问题，可以尝试在容器内执行 chmod 644 /usr/share/fonts/zh-cn/*.ttf。
• 字体缓存问题： 如果更新字体缓存后仍然无法显示中文，可以尝试清除字体缓存并重新生成。
• 镜像大小： 每次 docker commit 都会生成一个新的镜像。 为了避免镜像过于庞大，建议只在必要时提交更改。

这个修改后的版本更全面，考虑了各种可能遇到的问题，并提供了更详细的步骤和解释。希望对你有所帮助!

参考资料

#

1. Overleaf
2. Quick-Start-Guide