DOCAT 介绍与选型指南：多项目多版本文档托管的自托管方案
DOCAT 是开源自托管文档托管平台，按项目-版本-标签组织静态 HTML 文档。本文基于官方最新稳定版 1.6.1 溯源其定位、能力、架构，并与 MkDocs、Read the Docs 自建、Docusaurus 做量化选型对比，标注全部来源与查询日期。
DOCAT 介绍与选型指南：多项目多版本文档托管的自托管方案
一、项目概述
DOCAT（官方仓库 docat-org/docat）是一个开源的自托管文档托管平台，官方口号是 "Host your docs. Simple. Versioned. Fancy."。它要解决的问题非常明确：当团队使用 MkDocs、Sphinx、mdBook 等静态文档生成器产出 HTML 文档时，这些工具本身只负责"生成"，不负责"托管"；而实际业务中往往需要同时托管多个项目、每个项目的多个版本文档——旧版本的用户仍需阅读旧文档，新版本的用户需要最新文档。DOCAT 正是为这个"多项目 × 多版本"的托管缺口设计的轻量级服务（来源：DOCAT 官方 README "Why DOCAT?" 章节，查询日期 2026-10-28）。
需要特别强调官方的一个定位声明：DOCAT 不提供文档编写能力，它唯一的职责是托管编写好的静态 HTML 文档。文档的编写仍然交给 MkDocs、Sphinx、mdBook 等生成器完成，生成产物（静态 HTML 目录，通常打包为 zip）交给 DOCAT 托管（来源：官方 README "Using DOCAT" 章节，查询日期 2026-10-28）。
截至本文撰写（2026-10-28），DOCAT 官方最新稳定版为 1.6.1（发布标签提交于 2026-09-10，来源：GitHub Releases 页面），项目以 MIT 协议开源，GitHub 星标 911、派生 55、当前开放 issue 12 个（来源：shields.io 实时徽章数据，查询日期 2026-10-28）。
二、核心能力
依据官方 README 与 getting-started 指南（查询日期 2026-10-28），DOCAT 1.6.x 的能力面如下：
| 能力 | 说明 |
|---|---|
| 多项目托管 | 每个文档项目独立命名空间，首页按字母序列出全部项目（1.4.0 起排序） |
| 多版本管理 | 每个项目可上传任意多个版本（如 1.0.0、2.0.0），版本间独立存取 |
| 标签（tag） | 将某个版本打上 latest、stable 等标签，标签是指向版本的符号链接，可重复指向 |
| zip 上传 | Web 界面上传，或通过 HTTP API / 命令行工具上传 zip 压缩包，服务端自动解包 |
| 项目认领（claim） | 每个项目可认领一次，换取一个 API 令牌；后续覆盖上传、删除、重命名等操作需凭令牌 |
| 版本隐藏/显示 | 隐藏旧版本（不出现在版本列表与搜索结果中），可随时恢复 |
| 项目图标与收藏 | 上传项目 logo，前端支持收藏项目（favorite） |
| 系统统计 | 项目数、版本数、存储占用一览 |
| OpenAPI 文档 | 后端自动生成 OpenAPI 规范，内置 Swagger UI 与 ReDoc 页面 |
三、技术架构与工作原理
依据 DOCAT 1.6.1 官方源码（tag 1.6.1，查询日期 2026-10-28），其架构可以概括为"静态文件 + 极简元数据"三层：
- 前端：React 19 + Vite 8 构建的单页应用（SPA），构建产物为纯静态文件，由 Web 服务器托管，负责项目浏览、上传表单、认领与删除等操作界面。
- 后端 API：Python 3.10+ / FastAPI / Uvicorn 实现的 HTTP API，依赖极简——tinydb（嵌入式 JSON 数据库）、python-magic（文件类型识别）、python-multipart（表单上传），不需要任何外部数据库或消息队列。元数据全部存储在数据目录下的一个 JSON 文件（db.json）中。
- 静态文档服务：上传的 zip 解包到存储目录，按
<存储根>/<项目>/<版本>/组织，由 nginx 直接以静态文件方式对外提供；版本标签以符号链接实现（如latest -> 1.0.0），这也是标签"零成本切换指向"的原理。
官方发行形态是一个集成了 nginx + API 服务的单体安装包，同时官方仓库提供了从源码手动安装的完整路径（前端构建产物 + pip 安装后端 + nginx 配置模板），本专栏 B 篇 《DOCAT Ubuntu 22.04 安装部署指南》即按官方手动路径实测。官方还提供一个配套命令行工具 docatl（Go 语言编写的独立二进制，仓库 docat-org/docatl，当前版本 1.1.1），用于在 CI 中推送、打标、删除文档，详见 D 篇 《DOCAT 常用 CLI 命令详解》。
一个对部署决策很重要的细节：后端内置了一个可选的"直连模式"（环境变量 DOCAT_SERVE_FILES），开启后 API 进程自己提供文档静态服务，无需 nginx 也可完整访问——这对快速验证与内网小规模使用很方便；生产环境仍建议 nginx 托管静态文件（详见 C 篇 《DOCAT 配置参数详解》）。
四、量化选型对比
下面把 DOCAT 放到四类常见方案中做量化对比。对比对象：MkDocs（自托管构建产物）、Read the Docs（自建社区版）、Docusaurus（静态站点生成方案）。星标数据均来自 shields.io 徽章（查询日期 2026-10-28）：DOCAT 911、MkDocs 23k（mkdocs/mkdocs）、Docusaurus 67k（facebook/docusaurus）、Read the Docs 8.4k（readthedocs/readthedocs.org）。
4.1 定位差异（先分清"生成器"与"托管器"）
| 方案 | 本质定位 | 是否解决多项目托管 | 是否解决多版本文档 |
|---|---|---|---|
| DOCAT | 文档托管服务（不含编写） | 是（核心能力） | 是（版本 + 标签） |
| MkDocs | 文档生成器（Markdown → 静态 HTML） | 否，产物需自行部署 | 原生不支持，需配合 mike 等第三方工具且托管仍需自理 |
| Docusaurus | 文档生成器（React 静态站点） | 否（一个站点一个部署单元） | 部分（内置 docs versioning，但版本在构建期固化） |
| Read the Docs 自建 | 文档托管平台（含构建） | 是 | 是（按分支自动构建版本） |
4.2 资源与依赖量化对比
| 维度 | DOCAT | MkDocs + 自托管 | Read the Docs 自建 | Docusaurus + 自托管 |
|---|---|---|---|---|
| 语言栈 | Python (FastAPI) + Node（仅构建期） | Python（构建期）+ nginx | Python/Django 全栈 + PostgreSQL + 多组件 | Node/React（构建期）+ nginx |
| 外部数据库 | 无（内嵌 JSON 文件库） | 无 | 需要 PostgreSQL | 无 |
| 运行常驻进程 | nginx + 1 个 API 进程 | nginx（静态）即可 | Web + 构建 worker + 数据库等多个常驻组件 | nginx（静态）即可 |
| 元数据/状态存储 | 文件系统目录 + 单个 JSON 文件 | 无状态 | 数据库 + 对象存储 | 无状态 |
| 多版本上传机制 | zip/API/CLI 上传即生效 | 需自建发布脚本与目录约定 | git 分支推送自动构建 | 需重新构建发布整个站点 |
| 版本标签语义 | 服务端符号链接，切换零成本 | 无 | 版本即分支构建产物 | 构建期固化 |
| 认证/防误删 | 项目认领令牌（覆盖/删除需凭令牌） | 自理 | 完整用户体系 | 自理 |
| 许可证 | MIT | BSD-2-Clause | MIT | MIT |
| GitHub 星标（2026-10-28） | 911 | 23k | 8.4k | 67k |
4.3 对比解读
- 与 MkDocs 的关系是互补而非竞争。MkDocs（以及 Sphinx、mdBook）解决"从 Markdown 生成漂亮文档"，DOCAT 解决"把生成结果按项目/版本托管起来"。官方 README 明确把 MkDocs 列为推荐的配套编写工具。选 MkDocs + DOCAT 是"编写 + 托管"的完整链路；只选 MkDocs 则意味着自己设计"多项目多版本的目录结构、发布脚本与回滚策略"。
- 与 Read the Docs 自建的关键差异在重量级。RTD 社区版功能最全（git 推送自动构建、搜索广告、完整用户体系），但它是一个需要数据库与多个常驻组件的平台级系统，自建运维成本显著高于 DOCAT；如果团队只需要"上传 zip 即托管"，RTD 属于明显的过度供给。反之，若需要"提交代码自动出文档版本"的深度集成，RTD 更合适。
- 与 Docusaurus 的关键差异在版本生效方式。Docusaurus 的文档版本管理是构建期行为——版本被"烘焙"进静态产物，切换/新增版本需要重新构建整站；DOCAT 的版本是运行期数据——上传即生效、标签即时切换。对于"文档仓库分散在多个团队/仓库、版本发布节奏不同"的组织，DOCAT 的运行期模型明显更省事。
4.4 需要权衡的短板（依据官方仓库与文档，2026-10-28）
- 社区规模属于"小而稳"：不到 1k 星标，issue 存量 12 个，版本迭代节奏平缓（1.5.0 到 1.6.1 主要是依赖升级与体验修复），不适合期待大规模生态。
- 文档全文搜索依赖被托管文档自身的搜索能力（如 MkDocs 主题内置搜索），DOCAT 平台层提供的是项目名搜索。
- 认证粒度较粗：官方内置的只有"项目认领令牌"机制，没有用户体系；公网部署时官方 README 建议在 Web 服务器层叠加 HTTP Basic Auth 保护写操作（C 篇有实测配置）。
五、适用与不适用场景
适合选 DOCAT：
- 团队已用 MkDocs/Sphinx/mdBook 生成静态文档，痛点集中在"多项目、多版本怎么托管与切换"；
- 希望文档托管服务本身足够轻：无外部数据库、两个常驻进程即可运行，适合与其它内部服务同居一台服务器；
- CI 需要程序化发布文档：一条 curl 或 docatl 命令即可上传新版本并更新 latest 标签；
- 需要私有化部署、数据完全落在本机文件系统，备份即"打包一个目录"。
不适合选 DOCAT：
- 需要"从 git 仓库自动构建文档"的完整流水线（应看 Read the Docs 自建或 CI + docatl 自行编排）；
- 需要多人协作在线编辑文档（DOCAT 明确不做编写，应看 wiki 类系统）；
- 需要细粒度的用户/组权限体系（应看带权限的 wiki 或 DMS 系统）。
六、选型结论
DOCAT 是一个目标收敛、实现克制的文档托管组件：用"文件系统 + 嵌入式 JSON 库 + nginx 静态服务"扛住"多项目 × 多版本"的托管需求，把编写、构建、协作都留给专业工具。它在"轻量自托管"与"功能完备"之间坚定选择了前者。如果你的团队已有成熟的文档生成流程，只缺一个可靠的"文档发布与版本管理出口"，DOCAT 是当前开源方案里上手成本最低的一档；如果你的诉求是构建流水线一体化或在线协作，请回到第四节的对比表选择更重的方案。
后续实战请看：《DOCAT Ubuntu 22.04 安装部署指南》、《DOCAT 配置参数详解》、《DOCAT 常用 CLI 命令详解》。
参考来源（均于 2026-10-28 查询）：
- DOCAT 官方仓库与 README：https://github.com/docat-org/docat
- DOCAT Releases（版本 1.6.1，标签提交 2026-09-10）：https://github.com/docat-org/docat/releases
- DOCAT 官方 API 使用指南（getting-started）：仓库 doc/getting-started.md（1.6.1 标签）
- docatl CLI 仓库与 Releases：https://github.com/docat-org/docatl
- MkDocs 官方仓库：https://github.com/mkdocs/mkdocs
- Docusaurus 官方仓库：https://github.com/facebook/docusaurus
- Read the Docs 官方仓库：https://github.com/readthedocs/readthedocs.org
- 星标/版本数据：shields.io GitHub 徽章接口（img.shields.io），查询日期 2026-10-28