在Kubernetes上自部署ShareLaTeX并启用中文支持

引言

最开始的时候，论文无法显示中文:

本着"亲自指挥，亲自部署(SaaS)"的原则，以及 LaTeX 在 Overleaf 端不是很支持中文字体，并且有很多的编译限制，协作功能也存在问题。因此，在 Kubernetes 集群上部署一个自托管的 ShareLaTeX 来实现多用户同时使用。

本项目不仅提供了完整的部署方案，还配置了 GitHub Actions CI/CD 流程，实现每日自动构建包含中文字体支持的 Docker 镜像。

主要的痛点

• GitHub Actions 自动化构建：每周自动构建 Docker 镜像，实时更新最新的 Overleaf
• 中文支持：集成 fandol 字体和完整的 TeX Live 中文包，及宋体，仿宋等中文环境
• 云原生架构：基于 Kubernetes 的高可用部署
• 容器化部署：使用 Helm Charts 简化部署过程

架构概览

ShareLaTeX 由三个核心组件构成：

• Redis：缓存和会话存储
• MongoDB：文档和用户数据存储
• ShareLaTeX：主应用服务（包含中文字体支持）

开始部署

准备环境

1. 安装 Bitnami Helm Repository

前两个组件（Redis 和 MongoDB）已经有 Bitnami 提供的稳定镜像，我们直接使用 Helm 安装：

# 添加 bitnami repo
helm repo add bitnami https://charts.bitnami.com/bitnami
helm repo update

2. 创建命名空间

kubectl create namespace latex

部署数据层

2.1 部署 MongoDB

创建 values-mongodb.yaml 配置文件：

auth:
  ## 启用认证
  enabled: true
  ## MongoDB root 用户
  rootUser: root
  ## MongoDB root 密码（建议使用 Secret 管理）
  rootPassword: "your-secure-password"
  ## 自定义用户和数据库
  usernames: ["sharelatex"]
  passwords: ["sharelatex-password"]
  databases: ["sharelatex"]

# 持久化存储配置
persistence:
  enabled: true
  size: 10Gi

# 副本集配置（高可用）
replicaCount: 2
architecture: replicaset

# 外部访问配置（可选，用于调试）
externalAccess:
  enabled: true
  service:
    type: LoadBalancer
  autoDiscovery:
    enabled: true

# RBAC 配置
serviceAccount:
  create: true
automountServiceAccountToken: true
rbac:
  create: true

部署 MongoDB：

helm install mongo-mongodb bitnami/mongodb \
  --namespace latex \
  --values values-mongodb.yaml

2.2 部署 Redis

创建 values-redis.yaml 配置文件：

global:
  redis:
    password: "your-redis-password"

部署 Redis：

helm install redis-master bitnami/redis \
  --namespace latex \
  --values values-redis.yaml

部署应用层

3.1 自定义 ShareLaTeX 镜像

我们的项目提供了一个增强版的 ShareLaTeX 镜像，包含仿宋等常见中文论文场景的中文字体支持。如果需要其他字体，可以留言给我，我可以酌情添加.

Dockerfile 特点：

FROM sharelatex/sharelatex:latest

# 设置环境变量避免交互式安装
ENV DEBIAN_FRONTEND=noninteractive

# 安装中文字体和 TeX Live 包
RUN apt-get update && apt-get install -y \
    latex-cjk-all \
    texlive-lang-chinese \
    texlive-lang-english \
    git \
    && rm -rf /var/lib/apt/lists/*

# 安装中文字体库
RUN git clone https://github.com/Haixing-Hu/latex-chinese-fonts \
    /usr/share/fonts/opentype/latex-chinese-fonts -b master

# 更新字体缓存
RUN fc-cache -fv

# 配置 TeX Live 并安装完整包
RUN tlmgr update --self && \
    tlmgr install fandol && \
    tlmgr install scheme-full

3.2 使用自动构建的镜像

项目配置了 GitHub Actions，每日自动构建镜像：

# 拉取最新的每日构建镜像
docker pull ghcr.io/evsio0n/sharelatex-helm/sharelatex-custom:$(date +%Y%m%d)

3.3 配置 ShareLaTeX

创建 configmap-sharelatex.yaml：

apiVersion: v1
kind: ConfigMap
metadata:
  namespace: latex
  name: sharelatex-config
data:
  OVERLEAF_SITE_URL: https://overleaf.your-domain.com
  OVERLEAF_BEHIND_PROXY: "true"
  EMAIL_CONFIRMATION_DISABLED: "true"     # 禁用邮箱验证
  ENABLE_CONVERSIONS: "true"
  ENABLED_LINKED_FILE_TYPES: project_file,project_output_file
  EXTERNAL_AUTH: none
  OVERLEAF_APP_NAME: "Your Lab Overleaf"   # 自定义名称
  OVERLEAF_MONGO_URL: mongodb://sharelatex:sharelatex-password@mongo-mongodb-headless.latex.svc.cluster.local/sharelatex
  OVERLEAF_REDIS_HOST: redis-master.latex.svc.cluster.local
  REDIS_HOST: redis-master.latex.svc.cluster.local
  REDIS_PORT: "6379"
  REDIS_PASSWORD: "your-redis-password"

应用配置：

kubectl apply -f configmap-sharelatex.yaml

3.4 部署 ShareLaTeX 应用

创建 overleaf-deployment.yaml：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: overleaf
  namespace: latex
spec:
  replicas: 1
  selector:
    matchLabels:
      app: overleaf
  template:
    metadata:
      labels:
        app: overleaf
    spec:
      nodeSelector:
        kubernetes.io/arch: amd64  # 确保调度到 amd64 节点
      containers:
      - name: overleaf
        image: ghcr.io/evsio0n/sharelatex-helm/sharelatex-custom:latest
        envFrom:
        - configMapRef:
            name: sharelatex-config
        ports:
        - containerPort: 80
        resources:
          requests:
            memory: "1Gi"
            cpu: "500m"
          limits:
            memory: "4Gi"
            cpu: "2000m"
        livenessProbe:
          httpGet:
            path: /status
            port: 80
          initialDelaySeconds: 60
          periodSeconds: 30
        readinessProbe:
          httpGet:
            path: /status
            port: 80
          initialDelaySeconds: 30
          periodSeconds: 10
---
apiVersion: v1
kind: Service
metadata:
  name: overleaf
  namespace: latex
spec:
  selector:
    app: overleaf
  ports:
    - protocol: TCP
      port: 80
      targetPort: 80
  type: ClusterIP

部署应用：

kubectl apply -f overleaf-deployment.yaml

配置入口访问

4.1 使用 Ingress（推荐）

创建 ingress.yaml：

略，这部分使用你们云服务商的Ingress

4.2 使用 LoadBalancer

如果你的集群支持 LoadBalancer：

kubectl patch svc overleaf -n latex -p '{"spec": {"type": "LoadBalancer"}}'

GitHub Actions CI/CD 流程

项目包含完整的自动化构建流程：

触发条件

• 每日构建：每天 UTC 时间 02:00（北京时间 10:00）
• 代码推送：当 Dockerfile 或构建配置发生变化时
• 手动触发：在 GitHub Actions 页面手动触发

构建产物

1. Docker 镜像：推送到 GitHub Container Registry
2. 构建报告：详细的构建日志和包信息
3. Artifacts：压缩的镜像文件供下载

本地开发和测试

项目提供了便捷的管理脚本：

# 查看帮助
./docker-manage.sh help

# 本地构建镜像
./docker-manage.sh build

# 测试镜像
./docker-manage.sh test

# 查看状态
./docker-manage.sh status

# 调试构建问题
./docker-manage.sh debug

验证部署

检查服务状态

# 检查 Pod 状态
kubectl get pods -n latex

# 检查服务
kubectl get svc -n latex

# 查看日志
kubectl logs -f deployment/overleaf -n latex

访问应用

1. 通过 Ingress 访问：https://overleaf.your-domain.com

2. 或通过端口转发测试：

   kubectl port-forward svc/overleaf 8080:80 -n latex

   然后访问：http://localhost:8080

测试中文支持

创建一个新项目并测试以下 LaTeX 代码：

\documentclass{article}
\usepackage{ctex}
\usepackage{fontspec}

\begin{document}
\title{中文测试文档}
\author{测试用户}
\date{\today}
\maketitle

\section{中文章节}
这是一个中文测试段落。ShareLaTeX 现在支持中文字体了！

\subsection{数学公式}
$$E = mc^2$$

\subsection{列表}
\begin{itemize}
\item 第一项
\item 第二项
\item 第三项
\end{itemize}

\end{document}

运维和监控

日志监控

# 查看应用日志
kubectl logs -f deployment/overleaf -n latex

# 查看 MongoDB 日志
kubectl logs -f deployment/mongo-mongodb -n latex

# 查看 Redis 日志
kubectl logs -f deployment/redis-master -n latex

扩缩和编排MongoDB

# 扩展 ShareLaTeX 实例
kubectl scale deployment overleaf --replicas=3 -n latex

# 扩展 MongoDB 副本
helm upgrade mongo-mongodb bitnami/mongodb \
  --namespace latex \
  --set replicaCount=3 \
  --values values-mongodb.yaml

备份策略

MongoDB 备份

# 创建备份作业
kubectl create job --from=cronjob/mongodb-backup mongodb-backup-$(date +%Y%m%d) -n latex

数据恢复

# 从备份恢复（示例）
kubectl exec -it mongo-mongodb-0 -n latex -- mongorestore --uri="mongodb://root:password@localhost:27017/sharelatex"

故障排除

常见问题

1. 中文字体显示问题

   # 检查字体安装
   kubectl exec -it deployment/overleaf -n latex -- fc-list | grep -i chinese

2. 编译超时

   # 增加资源限制
   kubectl patch deployment overleaf -n latex --patch='{"spec":{"template":{"spec":{"containers":[{"name":"overleaf","resources":{"limits":{"memory":"8Gi","cpu":"4000m"}}}]}}}}'

3. 数据库连接问题

   # 检查网络连接
   kubectl exec -it deployment/overleaf -n latex -- curl mongo-mongodb-headless.latex.svc.cluster.local:27017

参考资源

• ShareLaTeX GitHub Repository
• Bitnami MongoDB Helm Chart
• Bitnami Redis Helm Chart
• LaTeX Chinese Fonts
• 项目 GitHub Repository
• 在 Kubernetes 环境部署 Overleaf 2025