ayaka-notes/ayakaleaf-pro · 上手攻略

  • 仓库：ayaka-notes/ayakaleaf-pro
  • 链接：https://github.com/ayaka-notes/ayakaleaf-pro
  • 分类：academic-writing / LaTeX 协作 / Overleaf 自托管替代
  • 作者：spark
  • 更新：2026-09-24

⚠️ 本文基于仓库 server-pro 分支 README、官网文档站 https://ayakaleaf-pro.ayaka.space/、博客与 GitHub Releases 元信息（GitHub 已验 · 200 OK · 抓取于 2026-09-23）撰写，未 clone 源码、未跑通部署。功能列表、依赖均按官方声明。

1. 这是什么

ayaka-notes/ayakaleaf-pro 是一个对 Overleaf Community Edition 的强化 fork，目标是把 Overleaf 商业版（Server Pro / SaaS Platform）几乎所有功能开源 + 免费 + 可自托管地实现出来。前身是 @Ayaka-notes Overleaf Pro Edition。

它不是 Overleaf Inc. 的产品，也不是 Overleaf Server Pro（那个是 Overleaf Inc. 的商业产品）。官方明写：与 Overleaf, Inc. 及其母公司 Digital Science 无关联；是独立项目由 ayaka-notes 维护。

底层就是 Overleaf CE 代码树（services/web/locales/ 里仍是 Overleaf 官方翻译文件，不要直接改），增强部分以 patch / 扩展的方式叠加。License 是 GNU AGPL v3。

⚠️ 立标候选位：academic-writing / LaTeX 协作 / 自托管 Overleaf 替代（主）+ 学术写作 / 团队协作 LaTeX（副）。

2. 解决什么问题

Overleaf 是事实标准的在线 LaTeX 协作平台，但有几条硬墙：

  1. CE 版功能太薄：没有 SSO、Track Changes、Zotero、Mendeley、Pandoc、Admin Panel、Git-Bridge 等 Pro 功能。
  2. Server Pro / SaaS 是付费商业版：机构 / 研究组想自托管这些功能要付授权费。
  3. 数据合规 / 隐私：学术、医疗、金融、政府场景常要求不能把未发表论文放在第三方 SaaS。

ayakaleaf-pro 用一份 AGPLv3 开源代码把「Pro 体验」拼回来——既能 Docker 一键起，又能用官方 ayaka-notes/Toolkit 做生产级部署。

3. 功能清单（README 原文 · 标注来源）

⚠️ 以下条目全部来自 README 自报，未独立核实。括号里「SaaS Platform」/「Server Pro」是 README 标注的功能归属——读者需要区分「跟 Overleaf 商业版某档对齐」 vs 「是 Ayakaleaf 自己的 Pro Edition 扩展」。

  • Pandoc Import/Export（SaaS Platform 对齐功能）
  • Python Script Runner（SaaS Platform 对齐功能）
  • 2-way GitHub Sync（SaaS Platform 对齐功能）
  • Zotero Integration（含 Zotero OAuth 支持）
  • Mendeley Integration（含 Mendeley OAuth 支持）
  • Advanced Reference Search（SaaS Platform 对齐功能）
  • Git-Bridge Support（Server Pro 对齐功能）
  • Admin Panel（全局用户 / 项目管理）
  • SSO（LDAP / SAML / OAuth 2.0）
  • Unlimited Compile Times（可在 Admin Panel 调节）
  • Self Register（可选，可按 mail domain 限制）
  • Sandbox Compile（配合 texlive-full 镜像）
  • Template System（含 Template Gallery）
  • Track Changes（含 Review + Comment Panel）
  • Full Project History（含 Restore + Download）
  • Symbol Palette（Server Pro / SaaS Platform 对齐功能）
  • ARM Support（x86_64 / arm64 Docker）

4. 快速安装

4.1 零部署试用：Playground / Codespaces

最快路径：直接用 Ayakaleaf Pro Playground——预配置的 GitHub Codespaces 环境，浏览器里就能跑。

Open in GitHub Codespaces

4.2 Docker 镜像（生产可用）

仓库提供 Docker 镜像，配合 texlive-full 镜像做 sandbox compile。

⚠️ README 推荐用 ayaka-notes/Toolkit 做生产部署——一键脚本 + compose 模板都在那。详细步骤见 官方文档站。

4.3 升级路径

从旧版本升级时，去 Releases 看每个版本之间的变更。

5. 核心用法

5.1 SSO 接入

SSO 支持 LDAP / SAML / OAuth 2.0；机构落地时一般先配 LDAP（绝大多数高校 / 研究院已有 AD / OpenLDAP）。

5.2 学术参考工作流

  • Zotero OAuth：从 Zotero 用户端 OAuth 授权 → Ayakaleaf Pro 拉文献库
  • Mendeley OAuth：同 Zotero
  • Advanced Reference Search：跨库检索，README 标 SaaS Platform 对齐

⚠️ Zotero / Mendeley OAuth 走的是官方 OAuth 流程，不是私设 proxy——这点对合规审查友好。

5.3 版本控制 / 协作

  • 2-way GitHub Sync：项目可直接同步到 GitHub 仓库；Ayakaleaf 内部编辑 → GitHub commit，反向亦然（典型用法：GitHub 当论文版本归档 + CI 触发 PDF 构建）
  • Git-Bridge（Server Pro 对齐）：比单纯 sync 更细的桥接能力

5.4 Track Changes

论文同行评议常用，含 Review / Comment Panel；与 \todo 之类宏相比，UI 层 track changes 不污染源文件。

5.5 模板系统

Template System + Template Gallery——把模板发到 Gallery，机构 / 实验室可以统一强制使用某套模板（会议 / 期刊）。

5.6 编译策略

  • Sandbox Compile + texlive-full 镜像：编译隔离 + 完整 TeXLive 套件；适合严格环境（编译不能污染主进程）
  • Unlimited Compile Times（可在 Admin Panel 调节）：CE 默认有编译时长上限，这里可放宽
  • ARM (x86_64 / arm64) Docker：Mac M 系列、Apple Silicon 服务器、ARM 云实例都能原生跑

5.7 Admin Panel / 用户治理

全局用户 / 项目管理；Self Register 可选，可按 mail domain 限流（只允许 @your-institution.edu 注册）。

5.8 Pandoc + Python Script Runner

  • Pandoc Import/Export：把 .md / .docx 等转 LaTeX（或反向）；很多非 LaTeX 工作流的协作者入口更顺
  • Python Script Runner：在项目里跑 Python（数据预处理、绘图、表格生成）——可控环境，权限边界要审

6. 典型适用场景

  • 高校 / 研究院内部 LaTeX 协作平台：要 SSO、Admin Panel、Track Changes、Unlimited Compile，不想把论文放 SaaS
  • 论文同步 GitHub 做长期归档：2-way GitHub Sync 让 Overleaf 编辑 ↔ GitHub 仓库双向同步；可同时享受「协作编辑体验」+「Git 版本控制 + CI PDF 构建」
  • 会议 / 期刊模板统一派发：Template Gallery + Admin Panel 限流；投稿截止前改模板一键同步
  • macOS / ARM 云原生部署：ARM Docker 支持；AWS Graviton / Apple Silicon 服务器 / Oracle ARM A1 都能跑
  • 有 Pandoc / Python 预处理需求的工作流：把 Markdown 草稿 → LaTeX 排版，或在 LaTeX 项目里跑数据脚本

不适用：

  • 单人偶尔写短论文：直接用 Overleaf SaaS / 开源 CE 更轻；自托管的运维负担不值
  • 机构合规要求完全脱离 Overleaf 代码树：AGPLv3 仍基于 Overleaf CE；如果合规要求「零 Overleaf」，这条路不通
  • 对协议有顾虑：AGPLv3 对某些商业集成是障碍；用前让法务看一眼

7. 坑与注意

  1. 不是 Overleaf 官方产品：与 Overleaf, Inc. 无关——商业支持要去 Overleaf Inc. 找 Server Pro；这里只有社区维护。
  2. AGPLv3：所有修改 / 分发都要开源（包括网络服务场景）；企业内部分发通常 OK，但若要做商业 SaaS 二次封装，要看条款。
  3. 官方翻译文件别直接改：services/web/locales/ 是 Overleaf 官方翻译文件，README 明确禁止直接改——改翻译要去 services/web/locales/locales_patches/。
  4. 翻译工作流是 AI 辅助：README 说「一般用 claude/codex 把英文翻译成其他语言」——如果你发现翻译错误，提交 PR 时要知道这是预期路径。
  5. 功能对齐声明要验证：README 把功能标成「SaaS Platform 对齐 / Server Pro 对齐」——这是仓库自述，不是 Overleaf Inc. 的功能矩阵承诺；生产决策别只看这条 README，先用 Playground 跑一遍关键流程。
  6. arm64 Docker 的 sandbox compile：要配 texlive-full 镜像；这个镜像体积大（TeXLive 全集），首次拉取久。
  7. Zotero / Mendeley OAuth 配置：走官方 OAuth，要在 Zotero / Mendeley 后台注册 client + 配 callback——首次接入要花时间。
  8. Playground ≠ 生产：Playground 是 GitHub Codespaces demo，给「试一下」用；不要把 Codespaces 当生产环境。
  9. GitHub Releases 链接与仓库名不一致：升级指南里的 Releases 链到 ayaka-notes/overleaf-pro 而非 ayakaleaf-pro——可能是历史重命名/分叉痕迹；不要据此怀疑是钓鱼，但升级前确认下当前仓库名。

8. 与同类对比

方案 形态 自托管 Pro 功能覆盖 License
ayakaleaf-pro（本仓库） Overleaf CE 强化 fork ✅ Docker / Codespaces 大部分 Pro（自报） AGPLv3
Overleaf CE 开源社区版 ✅ 基础 AGPLv3
Overleaf Server Pro Overleaf Inc. 商业版 ✅ 全 商业许可
Overleaf SaaS 官方托管 ❌ 全 商业
shareLaTeX / TeXMaker 离线 IDE ✅ 无协作 看具体
自建 GitLab + CI LaTeX Git 仓库 + CI ✅ 无实时协作 看具体

ayakaleaf-pro 的差异化在「开源 + 自托管 + Pro 体验」三角。CE 太薄，Server Pro 要钱，SaaS 不合规——这里在中间位置。代价是 AGPLv3 + 与上游 CE 的同步维护成本。

9. 一句话推荐结论

要在自有基础设施上跑「接近 Overleaf Pro 体验」的 LaTeX 协作平台，AGPLv3 可接受、愿意承担 fork 同步成本——ayakaleaf-pro 是目前性价比最高的开源路径；先用 Playground 试一遍关键工作流再决定生产部署。