基于 1Panel 的 Overleaf 5.0 完整部署与汉化指南

这是一篇基于真实部署案例整理的技术指南，旨在帮助用户在 1Panel 环境下成功搭建并配置 Overleaf (ShareLaTeX) 5.0+ 社区版。

1. 环境概述

本文档适用于使用 1Panel 面板进行容器化部署的场景。核心架构基于 Docker Compose，包含 Web 容器、MongoDB 8.0 数据库和 Redis 6.2 缓存。

注意： Overleaf 5.0+ 版本对数据库版本及运行模式有严格要求，必须使用 MongoDB 5.0+（本案例使用 8.0）且必须开启**副本集（Replica Set）**模式以支持事务处理。

2. 核心部署配置 (Docker Compose)

在 1Panel 的编排页面中，使用以下配置作为基础。该配置已修正 5.0 版本的环境变量前缀（由 SHARELATEX_ 变更为 OVERLEAF_）。

YAML

services:
  sharelatex:
    container_name: overleaf
    image: sharelatex/sharelatex:latest
    restart: always
    depends_on:
      mongo:
        condition: service_healthy
      redis:
        condition: service_started
    ports:
      - 9000:80
    volumes:
      - ./data:/var/lib/overleaf
    environment:
      OVERLEAF_SITE_URL: http://hui.scuhui.top:9000
      OVERLEAF_APP_NAME: SCU LaTeX Admin
      OVERLEAF_MONGO_URL: mongodb://mongo/sharelatex?replicaSet=rs0
      OVERLEAF_REDIS_HOST: redis
      OVERLEAF_SITE_LANGUAGE: zh-CN
      EMAIL_CONFIRMATION_DISABLED: 'true'

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

  redis:
    image: redis:6.2
    container_name: overleaf-redis
    restart: always
    volumes:
      - ./redis_data:/data

3. 关键部署流程

第一步：初始化 MongoDB 副本集

Overleaf 5.0 会在启动时自检数据库事务支持。若未初始化副本集，容器将反复重启并报错 IllegalOperation。

1. 在 1Panel 启动容器后，进入 overleaf-mongo 容器终端。

2. 执行初始化命令：

   Bash

   mongosh --eval "rs.initiate()"
   

3. 确认返回结果包含 { ok: 1 }。

第二步：管理员账号激活

1. 访问初始化专用地址：http://your-domain:9000/launchpad。

2. 按照页面提示设置管理员邮箱及密码。注意： 请勿直接访问 /register 页面，社区版默认禁用普通用户自注册。

第三步：全家桶宏包安装 (TeX Live Full)

默认镜像仅包含基础宏包，对于学术论文（如四川大学毕设模板）通常需要完整版。

1. 进入 overleaf 容器终端。

2. 版本对齐与换源（解决 2025/2026 版本冲突）：

   Bash

   # 下载并运行升级脚本
   wget https://mirrors.tuna.tsinghua.edu.cn/CTAN/systems/texlive/tlnet/update-tlmgr-latest.sh
   sh update-tlmgr-latest.sh -- --upgrade
   
   # 设置最新镜像源
   tlmgr option repository https://mirrors.sustech.edu.cn/CTAN/systems/texlive/tlnet/
   

3. 安装完整版（需 5GB+ 空间，耗时较长）：

   Bash

   tlmgr install scheme-full
   

4. 界面汉化与中文支持

界面汉化

若环境变量 OVERLEAF_SITE_LANGUAGE: zh-CN 未生效，可手动修改容器内配置文件：

1. 编辑 /etc/overleaf/settings.js。

2. 将 i18n 模块下的 defaultLng 修改为 'zh-CN'。

3. 重启容器（勿重建，否则 scheme-full 将丢失）。

中文编译配置

在项目内实现中文正常显示：

• 编译器设置：项目菜单中将 Compiler 切换为 XeLaTeX。

• 宏包引入：文档开头添加 \usepackage[UTF8]{ctex}。

5. 常见问题与试错总结 (Troubleshooting)