HedgeDoc 介绍与选型指南

目标：本文面向正在评估「自托管 Markdown 实时协作文档」方案的运维与团队负责人，从官方一手来源（官网 hedgedoc.org、官方仓库 github.com/hedgedoc/hedgedoc、官方文档 docs.hedgedoc.org）溯源 HedgeDoc 的定位、架构、功能与量化选型对比，帮助读者在 HedgeDoc、CodiMD、HackMD、Etherpad、Outline 之间做出有依据的选择。

一、环境信息

本文为认知与选型篇，全部结论均来自官方一手来源的联网溯源，未混入任何本地实测结论。溯源信息清单如下：

💡 说明：HedgeDoc 官方对外口径以 docs.hedgedoc.org（由仓库 docs/ 目录生成的文档站）与 hedgedoc.org 官网为准；hedgedoc.org 站点启用了 Cloudflare 人机校验，脚本化抓取会被拦截（实测返回 "Just a moment... Enable JavaScript and cookies to continue"），因此本文溯源以 GitHub 官方仓库、Releases 接口与官方文档站为准，两者内容由同一维护团队发布，口径一致。

二、软件概述

HedgeDoc（曾用名 CodiMD）是一款开源的实时协作 Markdown 笔记平台。官方 README 对其定义只有一句话："HedgeDoc lets you create real-time collaborative markdown notes"（HedgeDoc 让你可以创建实时协作的 Markdown 笔记）。它解决的核心痛点是：团队多人同时编辑同一篇 Markdown 文档且互不冲突，编辑完成即可通过一个 URL 分享阅读，无需经过 IM 来回传文件或粘贴正文。

核心特征：

• 实时协同编辑：多人同时编辑一篇笔记，基于 WebSocket 的实时同步，光标与内容变更实时可见；
• 多视图模式：编辑视图、视图模式（纯预览）、分屏模式（左右分栏同时看编辑与预览）；
• 纯 Markdown 源码驱动：笔记以 Markdown 源码存储，可随时导出，不存在私有无形格式锁定；
• 可自托管：官方提供 Docker 镜像与安装文档，数据完全掌握在自建服务器上；
• 开放许可：AGPL-3.0 许可证（shields.io 徽章取证，2026-10-22）。

项目状态（官方 README 口径，2026-10-22 查询）：HedgeDoc 1.x 目前稳定且在全球范围被使用，但代码库随着时间推移变得难以继续添加新功能，团队正在重写 HedgeDoc 2（完全重写版本）。官方明确说明：1.x 版本处于「仅维护」状态——不再接受针对 1.x 的功能请求或 PR，仅接受 bug 修复、安全修复与翻译贡献；同时官方仍在持续发布 1.x 版本（见下文版本节奏），1.x 依然是当前的"可用、可部署"版本。选型时应知晓：新功能将出现在 2.x，而 2.x 截至 2026-10-22 尚未发布稳定版。

💡 技术拓展：「实时协同编辑」不止一种实现路线。常见实现对比——

实现路线	原理/特点	适用场景
OT（Operational Transformation，操作变换）	服务器对并发操作做变换重排，保证最终一致	协同编辑的经典方案（Etherpad、HackMD 系均属此类）
CRDT（无冲突复制数据类型）	数据结构本身保证无冲突合并，弱网/离线友好	新一代协同编辑器（如 Yjs 生态）
锁定/轮转（悲观锁）	一次只允许一人编辑或整段锁定	实现简单但体验差，现代平台基本不用

HedgeDoc/CodiMD/HackMD 系产品属于 OT 路线（服务器集中式变换同步），配合 WebSocket 推送；这也是其对"稳定网络环境下的团队协作"优化最好的原因。本文选型语境下，HedgeDoc 采用的即 OT + WebSocket 方案。

三、核心架构

以下架构描述基于官方仓库结构与官方文档的溯源（2026-10-22）。

3.1 组件构成

HedgeDoc 1.x 是一个 Node.js 单体应用 + 关系型数据库的两层结构：

• Web 应用进程（HedgeDoc 本体）：Node.js 编写，承担 HTTP 页面渲染、笔记编辑 API、图片上传、认证等全部业务逻辑；
• PostgreSQL 数据库：存储用户、笔记（Markdown 源码）、修订历史等全部结构化数据。官方 1.x 对 PostgreSQL 是硬性要求，不支持 MySQL/SQLite 作为主库（与 CodiMD 的差异之一）；
• 浏览器端编辑器：实时协同的前端逻辑在浏览器执行，与服务器经 WebSocket 通道同步操作。

3.2 部署形态

官方支持的部署形态（溯源自官方文档 docs.hedgedoc.org 安装指南，2026-10-22）：

1. Docker Compose（官方推荐）：hedgedoc 应用容器 + PostgreSQL 容器，官方仓库 docs/content/setup/docker.md 提供标准 compose 参考；
2. 手动安装：直接在服务器上以 Node.js 运行源码（要求 Node 20.17 或更高版本——1.12.0 发布说明明确写明 "HedgeDoc 1.12.0 and onwards will require Node 20.17 or later in order to run"）；
3. 官方容器镜像：发布在 Quay.io quay.io/hedgedoc/hedgedoc，提供 latest、1.12.0、debian、alpine 等标签（2026-10-22 查询）。

对应的官方部署实操与逐条实测回显，见本专栏《HedgeDoc 1.12.0 Docker Compose 部署指南》。

3.3 存储与外部依赖

四、功能特性

以下功能清单溯源自官方 README 功能页指引与官方文档（docs.hedgedoc.org），为 HedgeDoc 1.x 具备的能力（2026-10-22）：

1. 实时协同编辑：多人编辑同一笔记，实时看到彼此光标与内容；官方 1.12.0 发布说明显示仍在修复弱网连接下的实时同步数据丢失问题（"Fixed multiple bugs in the realtime connection handling that could lead to data-loss of users with a flaky connection"），说明实时通道是维护重点；
2. 多视图：编辑/预览/分屏三种视图模式切换；
3. 扩展 Markdown 语法：在标准 Markdown 之上支持流程图（flowchart）、序列图（sequence diagram）、Mermaid、Gantt、PlantUML 风格图表占位、数学公式（MathJax）、Emoji 短代码、目录生成（[TOC]）、折叠块、代码高亮等扩展语法；
4. 笔记管理：修订历史（可回看/恢复历史版本）、置顶、标签、权限分级（拥有者/可编辑/可阅读，按用户或按登录态开放）；
5. 导出：Markdown 原文导出、HTML、PDF 打印导出等；
6. 多种登录方式：本地账号、邮箱注册、匿名可编辑、以及 LDAP、OAuth2（GitHub/Google/GitLab 等）、SAML 等外部认证集成；
7. 账号与权限：1.12.0 起若只配置了一个外部登录方式且无表单登录，登录弹窗会自动跳过（"Automatically skip the login modal if no form-based login and exactly one external login provider is configured"，1.12.0 发布说明原文）；
8. 管理命令行工具：内置 bin/hedgedoc CLI，可进行用户创建、密码重置、会话管理等运维操作，逐条实测详见本专栏《HedgeDoc 1.12.0 API 使用详解》；
9. 配置体系：config.json 文件与 CMD_* 环境变量双轨配置（环境变量优先），覆盖域名、数据库、认证、上传、CSP 等，逐项解析见本专栏《HedgeDoc 1.12.0 配置参数详解》。

五、快速开始（最小可用示例）

本节内容溯源自官方文档（docs.hedgedoc.org 安装指南的 Docker 部分与官方仓库 compose 参考，2026-10-22），给出最小可用的官方推荐形态——hedgedoc 应用 + PostgreSQL 数据库的 Docker Compose 双服务栈。以下命令的逐条实测回显、部署排障与数据持久化验证，见本专栏《HedgeDoc 1.12.0 Docker Compose 部署指南》，此处仅为认知快速通道：

# 官方推荐形态（溯源自官方文档，2026-10-22）：应用 + PostgreSQL 两服务
version: "3"
services:
  database:
    image: postgres:16-alpine
    environment:
      - POSTGRES_USER=hedgedoc
      - POSTGRES_PASSWORD=change-me
      - POSTGRES_DB=hedgedoc
    volumes:
      - database:/var/lib/postgresql/data
    restart: unless-stopped
  app:
    image: quay.io/hedgedoc/hedgedoc:1.12.0
    environment:
      - CMD_DOMAIN=localhost
      - CMD_DB_URL=postgres://hedgedoc:change-me@database:5432/hedgedoc
      - CMD_ALLOW_ORIGIN=['localhost']
    ports:
      - "3000:3000"
    depends_on:
      - database
    restart: unless-stopped
volumes:
  database:

docker compose up -d        # 启动后浏览器访问 http://<服务器IP>:3000

⚠️ 注意：上方 change-me 为占位演示，实际部署必须换成强密码；镜像统一建议写 quay.io/hedgedoc/hedgedoc:1.12.0 这种「锁定版本号」的形式而非 latest，保证可重复部署。完整的生产 compose 文件（含健康检查、卷持久化、升级流程）与全部实测回显见部署篇。

六、适用场景与限制

6.1 适用场景

• 团队内部知识沉淀：会议纪要、运维手册、排查记录多人共创，编辑完一个 URL 即可分发；
• 教学/结对写作：导师与学生同屏编辑讲义或代码片段，实时看到输入；
• 技术文档预审：Markdown 源码直接进 Git 仓库，协作评审阶段用 HedgeDoc，定稿后落库；
• 轻量 Wiki 替代：需要「随手开一篇、链接即分享」的笔记场景，比完整 Wiki 的建页流程轻得多。

6.2 限制（官方口径）

• 1.x 仅维护：官方 README 明确 1.x 不再接受功能请求/PR，新功能集中于尚未发布的 2.x 重写版；选型即意味着「锁定 1.x 的功能面」；
• 运行时要求：1.12.0 起要求 Node 20.17 或更高（1.12.0 发布说明原文）；
• 数据库锁定 PostgreSQL：不支持以 MySQL/SQLite 为主库；
• 语法高亮语言集变化：1.12.0 随 highlight.js 11 升级，部分代码语言的高亮被移除/改名（发布说明原文指向 highlight.js 官方升级文档）；
• 链接行为：1.12.0 起笔记内所有链接改为新标签页打开（恢复旧行为，发布说明原文）。

七、同类选型对比

7.1 量化对比表

以下星数/许可证/活跃度均以 shields.io 徽章接口取证（https://img.shields.io/github/<…>.json，查询日期 2026-10-22），版本号取自各官方仓库 GitHub Releases（同日查询）：

关键差异与如何选型：

1. HedgeDoc vs CodiMD：两者同源（CodiMD 是 HedgeDoc 的曾用名与上游社区版）。官方 README 说明 HedgeDoc 项目即从 CodiMD 分化而来。量化证据显示 CodiMD 已明显停滞——最近提交停留在 2025-10，最新版 2.6.1 发布于 2025-10-01；HedgeDoc 最近提交为 2026-10 当月，1.12.0 发布于 2026-08-21。新部署选 HedgeDoc，仅在深度定制 CodiMD 遗留系统时才考虑它；
2. HedgeDoc vs HackMD：HackMD 是托管 SaaS（其开源社区版即 CodiMD），数据在第三方云端；HedgeDoc 是同源能力的自托管实现。要求数据不出内网/合规自主可控 → HedgeDoc；愿意托管换省心且需要其企业功能 → HackMD；
3. HedgeDoc vs Etherpad：Etherpad 星数更高（19k）、协同粒度更细、极活跃（Apache-2.0 对二次开发更友好），但它是「共写板」而非「Markdown 笔记平台」——默认无 Markdown 源码视图、扩展语法（公式/流程图）与笔记管理生态弱于 HedgeDoc。以 Markdown 源码为中心的知识沉淀 → HedgeDoc；纯多人快写/脑暴板 → Etherpad；
4. HedgeDoc vs Outline：Outline 星数最高（41k）但有三点硬差异：采用 BSL 1.1 许可证（非开源许可，源码可查但限制商用托管——本文化验自官方 LICENSE 文件 "Business Source License 1.1"，2026-10-22）；定位是结构化知识库（文档树+集合+权限）而非轻量协同笔记；非字符级实时协同。团队 Wiki/知识库中枢 → Outline；轻量多人 Markdown 共创 → HedgeDoc；
5. 一句话结论：需要「自托管 + 实时协同 + Markdown 源码 + PostgreSQL 单库」且接受 1.x 仅维护现状的团队，HedgeDoc 是该交叉域内证据最充分的默认选项。

7.2 社区活跃度补充

解读：以月为粒度的稳定发版节奏（近一年平均每月 1 个左右版本）、当月仍有提交，属于活跃维护状态；与「仅维护、不接受功能 PR」的官方口径合起来看，正确的预期是「安全与缺陷修复持续，功能面冻结」。

八、参考链接

1. 官方网站：https://hedgedoc.org
2. 官方文档（安装指南）：https://docs.hedgedoc.org/setup/getting-started/
3. 官方仓库：https://github.com/hedgedoc/hedgedoc
4. 1.12.0 发布说明：https://github.com/hedgedoc/hedgedoc/releases/tag/1.12.0
5. 官方容器镜像：https://quay.io/repository/hedgedoc/hedgedoc
6. 项目历史（CodiMD→HedgeDoc 演变）：https://hedgedoc.org/history/
7. 本专栏实操文档：《HedgeDoc 1.12.0 Docker Compose 部署指南》（部署与实测）、《HedgeDoc 1.12.0 配置参数详解》（配置逐项解析）、《HedgeDoc 1.12.0 常用 CLI 命令与工具详解》（管理命令实测）

注：参考链接 7 为本专栏系列文档，链接中的 slug 将随各篇发布填充；外部链接（1-6）均为官方来源，查询日期统一为 2026-10-22。