从零部署CodiMD：搭建自托管实时协作Markdown编辑器的完整指南

说实话，看到不少人在 NAS、云服务器上折腾文档系统，我的第一反应往往不是知识库，也不是 Nextcloud，而是先把一个轻量的协作 Markdown 工具跑起来。Markdown 写作的门槛低、格式干净、可迁移性强，但要解决多人同时改一份文档、还想把数据掌握在自己手里的需求，直接搭一个 CodiMD 是最省心的路线之一。这个项目后来社区改名成了 HedgeDoc，不过老用户还是习惯叫它 CodiMD，搜资料的时候两个关键词都会用到。这篇文章就记录我从零部署 CodiMD、接入内外网访问、再到日常维护的完整过程，重点讲清楚那些“配置完了页面也能打开，但一协作就出问题”的隐藏坑。

1. 场景与选型：为什么是 CodiMD 而不是别的工具

1.1 CodiMD 和 HedgeDoc 到底是什么关系

CodiMD 是从 HackMD 开源分支里出来的一个社区版本，最初由一群开发者维护，目标是做一个可以自己托管、不依赖第三方服务的实时协作 Markdown 编辑器。后来这个项目因为商标等问题改名为 HedgeDoc，所以你在 GitHub 上搜到的仓库很可能是 hedgedoc/hedgedoc，官方 Docker 镜像也大多放在了 quay.io/hedgedoc 下。网上大量旧教程还在用 CodiMD 这个名字，这并不奇怪，很多老镜像和文档也没删，只是长期维护的话我更建议直接使用当前活跃维护的镜像名称。

它的核心能力其实很聚焦：浏览器里写 Markdown，左侧编辑右侧预览，多人同时打开同一篇文档可以看到彼此的实时光标和编辑内容。不需要安装客户端，不需要单独配置 Git 仓库，打开链接就能编辑。对于团队内部的技术方案、会议纪要、接口文档这类需要长期沉淀又偶尔需要多人协同的文本内容，它比 Word 在线协作要轻，比公司内部 Wiki 要灵活。

1.2 适用场景和边界

我实际用它最多的地方是两类：一类是技术团队内部文档，比如架构设计、环境搭建步骤、日常操作手册，这些东西用 Markdown 记录非常合适，之后还能导出或直接转成其他格式；另一类是个人或小团队的临时协作，比如几个人共同维护一份对外发布的说明文档，不需要复杂的审批流和权限体系，只想快速进入编辑状态。

当然也要说清楚它不擅长什么。CodiMD 本质上还是面向 Markdown 文档的协作工具，不是结构化数据库，不是项目管理面板，不是富文本编辑器。如果你需要的是在线表格里面多人同时填数据，或者需要一个带评论工作流的企业级知识库，那它的很多能力是缺失的。它更适合的做法是：你先确定内容形态是 Markdown 文档，然后把它作为文档的承载点和协作入口。

1.3 为什么数据自主可控是硬需求

我之所以坚持本地部署而不是直接用在线笔记平台，核心原因有两个。第一是数据所有权，文档内容存放在自己的服务器或者家里的存储设备上，不用担心某个在线服务调整策略导致内容不可访问；第二是环境隔离，部分文档可能只对特定团队成员或特定网络环境开放，自己部署可以把访问控制做在网关层和容器层，灵活度远高于只能在别人页面上设置权限。再加上后期还能接自己的域名、HTTPS 证书、甚至统一登录系统，长期用下来明显更顺手。

2. 部署前需要先想清楚的几个设计问题

2.1 跑在哪：云服务器还是局域网里的机器

部署位置决定了后面的网络方案，这是第一步就要定的。如果你有一台带公网 IP 的云服务器，那路径最直接，容器跑在上面，公网用户直接通过域名或 IP 访问；如果你打算把它放在办公室或家里的机器上，还要考虑如何让外部人员稳定访问。两种模式下，CodiMD 的容器配置差异不大，区别主要在端口暴露和反向代理以及隧道工具的选择上。

我的建议是：如果只是自己或局域网团队使用，先跑在一台内网设备上，用 IP 访问就够了；如果明确需要外部协作，最好一开始就准备一台公网服务器。尽量不要把 CodiMD 容器长期裸奔在某个公网 IP 的随机端口上，后面我会专门讲安全问题。

2.2 数据库选型：为什么直接选 PostgreSQL

CodiMD 支持 SQLite 和 PostgreSQL，但绝大多数部署方案都建议使用 PostgreSQL。原因是 CodiMD 的实时协作、历史记录等功能依赖数据库处理大量高频写入和并发事务，SQLite 在低负载下能用，但多人同时高频编辑时容易出现锁写和性能瓶颈。另外一个实际问题是很多官方镜像和部署模板默认就用 PostgreSQL，如果你用 SQLite，后续升级或迁移时可选路径会窄不少。

PostgreSQL 在 Docker Compose 里启动也简单，拉一个官方镜像、挂一个数据卷就行。唯一要注意的是不要图省事把数据库密码设得太简单，毕竟这个库里面存着你的全部文档内容和用户信息，一旦泄露就是整个知识库都交出去了。

2.3 访问形态决定环境变量

CodiMD 生成页面链接时会依赖一组和访问域名相关的环境变量，这组变量如果配错，会出现一种特别迷惑的现象：你自己在服务器本机打开一切正常，但一旦把链接发给别人，对方打开之后指向的是他自己电脑的 localhost，或者明明配置了 HTTPS 却还在用 HTTP 回调。为了避免这种情况，部署前就得确定到底是用 IP 访问、用域名 HTTP 访问还是用域名 HTTPS 访问。后面容器配置里所有和域名、协议相关的变量都要围绕这个最终访问地址来写。

3. 用 Docker Compose 完整拉起 CodiMD 服务

3.1 项目目录和 compose 文件

我这里以 Linux 服务器或 NAS 上的 Docker 环境为例，Docker Compose 最终可以把数据库和应用两个容器一次性管理起来，比手工 docker run 两个容器要方便得多。先创建目录结构：

bash复制mkdir -p /opt/codimd && cd /opt/codimd
vi docker-compose.yml

完整的 docker-compose.yml 如下：

yaml复制services:
  codimd-db:
    image: postgres:13-alpine
    container_name: codimd-db
    environment:
      POSTGRES_USER: hedgedoc
      POSTGRES_PASSWORD: change_this_db_password
      POSTGRES_DB: hedgedoc
    volumes:
      - db-data:/var/lib/postgresql/data
    restart: unless-stopped
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U hedgedoc"]
      interval: 10s
      timeout: 5s
      retries: 5

  codimd:
    image: quay.io/hedgedoc/hedgedoc:1.9.9
    container_name: codimd
    depends_on:
      codimd-db:
        condition: service_healthy
    environment:
      CMD_DOMAIN: md.example.com
      CMD_PROTOCOL_USES_HTTPS: "true"
      CMD_PORT: "3000"
      CMD_DB_URL: postgres://hedgedoc:change_this_db_password@codimd-db:5432/hedgedoc
      CMD_SESSION_SECRET: use_a_long_random_string_here
      CMD_ALLOW_ANONYMOUS: "false"
      CMD_ALLOW_EMAIL_REGISTER: "false"
      CMD_ALLOW_FREEURL: "false"
      CMD_IMAGE_UPLOAD_TYPE: filesystem
      CMD_MAX_IMAGE_SIZE: "10485760"
    volumes:
      - upload-data:/hedgedoc/public/uploads
    ports:
      - "127.0.0.1:3000:3000"
    restart: unless-stopped

volumes:
  db-data:
  upload-data:

这个文件里有个容易被忽视的细节：应用容器的端口映射写的是 127.0.0.1:3000:3000，意思是不对宿主机外网直接暴露 3000 端口，只允许本机反向代理访问。如果你暂时没有反向代理，只想先在内网用 http://服务器IP:3000 测试，那可以临时改成 "3000:3000"，但公网场景下请务必加上回环地址限制。

3.2 关键环境变量逐个拆解

很多配置看起来都是英文字母缩写，实际含义却直接决定服务能不能正常工作。

• CMD_DOMAIN：这是整套配置里最容易被忽略又影响最大的一项。它决定了 CodiMD 生成文档链接时使用的主机名。如果这里写成 localhost，那么容器内部生成的所有可分享链接都会带 localhost，发给别人后对方点开就会访问他自己的电脑。局域网或公网使用时应改成实际访问的 IP 或域名，比如 192.168.1.100 或 md.example.com。

• CMD_PROTOCOL_USES_HTTPS：如果前面打算用 Nginx 或 Caddy 终止 HTTPS，这里必须设为 true，否则 CodiMD 生成的回调地址会是 HTTP，浏览器会报不安全或混合内容错误。

• CMD_PORT：这是 CodiMD 应用监听端口，默认 3000，容器内部保持不变即可。如果你的反向代理把外部 443 端口映射到容器 3000，那么用户在浏览器里看到的是 443，但 CodiMD 内部生成链接还是依据 CMD_PORT。所以当你外网发布端口不是默认的 443/80 时，可能需要关注端口覆盖类参数，具体变量在不同版本里不太一样，重点看官方文档，思路就是保证“浏览器地址栏里的端口”和“CodiMD 生成链接时携带的端口”一致。

• CMD_DB_URL：新版镜像推荐用数据库 URL 连接 PostgreSQL。要注意密码里如果包含 @、#、: 这些特殊字符，需要做 URL 编码，否则连接字符串会被解析错。这个坑我遇到过，很多教程里密码都是简单明文，实际生产环境密码一复杂就废了。

• CMD_SESSION_SECRET：这是用于加密用户会话和 Cookie 的密钥，必须手动指定一个足够长的随机字符串，不能所有部署都用同一个默认值。可以用 openssl rand -hex 32 生成。

• CMD_ALLOW_ANONYMOUS：是否允许匿名用户直接创建和编辑文档。如果只是自己团队用，我强烈建议设为 false，否则任何能打开你页面的人都能写内容。有些场景确实需要匿名协作，比如网页上公开收集信息，那你至少要配合其他访问控制手段。

• CMD_ALLOW_EMAIL_REGISTER：是否开放邮箱注册。对外服务如果你不想让陌生人随便注册账号，就设成 false，然后通过预置账号或者接入其他认证方式管理用户。

• CMD_ALLOW_FREEURL：允许登录用户自由创建任意 URL 路径的文档。这个选项开起来很方便，但也容易出现页面路径混乱的问题。我更倾向于关闭它，让系统自动生成链接或按规范创建。

• CMD_IMAGE_UPLOAD_TYPE 和 CMD_MAX_IMAGE_SIZE：控制图片等附件上传方式。设成 filesystem 会存到容器内的上传目录，并通过 volume 持久化；CMD_MAX_IMAGE_SIZE 的单位是字节，10MB 的配置是 10485760。

3.3 启动和首次验证

配置完成后执行：

bash复制docker compose up -d
docker compose ps

正常情况下 codimd-db 会先启动并完成健康检查，随后 codimd 容器启动。如果某个容器启动失败，用以下命令看日志：

bash复制docker compose logs codimd

很多新手在这一步就会看到数据库连接失败。常见原因有两个：数据库容器还没准备好就启动了应用容器，或者 CMD_DB_URL 写错了。我这里用 depends_on 条件等待健康检查，就是为了降低这个概率。如果是旧版本 compose 不支持这种写法，可以用 restart: always 加延时等待来兜底。

首次打开页面后，会看到 CodiMD 的欢迎界面，界面上有创建笔记入口。如果此时页面能正常加载，说明基础部署已经通了。

3.4 不同镜像版本的变量兼容问题

网上能搜到大量 CodiMD 部署文章，但镜像版本差异挺大。旧版 CodiMD 镜像有的使用 CMD_DB_HOST、CMD_DB_PORT、CMD_DB_USER、CMD_DB_PASSWORD、CMD_DB_NAME 这一组分段变量，而不是 CMD_DB_URL；部分老镜像还存在其他配置项命名差异。如果你参考的教程是两三年前的，变量名大概率对不上新镜像。部署前最好去官方仓库或镜像页面确认当前版本支持的变量名，以免照着老文章填了半天，容器日志依然报错。

另外一个容易踩的坑是镜像源拉取问题。quay.io 的镜像在国内网络环境下有时会拉得很慢，可以配置 Docker 镜像加速源，或者直接使用你所在网络环境能稳定访问的镜像仓库。总之就是把稳定的镜像源和正确的镜像版本作为环境准备的一部分提前解决。

4. 局域网先跑通：那些“看起来能用但协作不了”的坑

4.1 CMD_DOMAIN 不对引发的链接歧义

我第一次部署完，在服务器本机开了一个文档，然后复制链接发给另一台电脑上的同事，结果同事点开以后页面一直转圈，最后发现他打开的是他自己电脑的 3000 端口。这就是 CMD_DOMAIN 设置错误导致的典型现象。因为我在配置文件里填了 localhost，虽然服务器本机访问确实没问题，但生成的分享链接是 http://localhost:3000/xxx，到了同事的电脑上，localhost 自然指向了他自己的机器。

解决办法是把这个变量改成局域网内所有用户都能访问到的地址，比如那台部署主机的局域网 IP。重启容器之后，重新创建文档或手动刷新页面，分享链接就会变成 http://192.168.1.100:3000/xxx。

4.2 多个设备编辑时保持地址一致

局域网内多人协作时，还有一点经常被忽略：大家尽量通过同一个地址访问实例，不要一些人用主机名、一些人用内网 IP、另一些人用 localhost。CodiMD 的实时协作依赖 WebSocket 连接，连接地址和页面地址必须保持一致。如果 A 用 localhost:3000 开文档，B 用 192.168.1.100:3000 打开同一个链接，虽然数据都在同一个实例上，但同步连接可能会建立异常，表现为在线用户列表看不到对方，编辑内容不同步。

更稳妥的方案是直接把 CMD_DOMAIN 固定成一个大家都好记的内网地址，比如 http://codimd.local:3000，并且确保所有参与者的电脑都能解析这个主机名。否则就用纯 IP，简单直接，不容易出问题。

4.3 如何判断 WebSocket 是否正常

CodiMD 的实时协作不是靠普通的 HTTP 请求轮询，而是靠 WebSocket 长连接。如果部署在反向代理后面，而代理层没有正确转发 WebSocket 升级请求，那么用户打开页面是正常的，因为静态页面和普通接口走 HTTP 没问题，但协作功能就不工作。

验证方式很直接：在浏览器开发者工具里打开 Network 面板，筛选 WS，然后进入一篇文档，正常情况能看到一条到 /socket.io/ 的 WebSocket 连接，状态码是 101 Switching Protocols。如果看不到这条连接，或者经常断开重连，说明代理层或网络策略没有放行 WebSocket。这个问题在我最初接 Nginx 的时候出现过，下面一章会详细写配置。

5. 接入外部访问的完整方案和安全加固

5.1 方案A：有公网服务器的标准反向代理

如果你有一台公网服务器，最推荐的方案是把 CodiMD 跑在这台服务器上，然后通过 Caddy 或 Nginx 做反向代理，统一走 80/443 端口。这时候 compose 文件的端口映射就应该像我前面那样只绑 127.0.0.1:3000:3000，外部流量全部交给反向代理转发。

Caddy 配置非常简单，而且它会自动申请和续期 HTTPS 证书，也默认支持 WebSocket 转发，所以如果服务器上还没有现成的 Nginx，我建议直接用 Caddy：

caddyfile复制md.example.com {
	reverse_proxy 127.0.0.1:3000
}

启动 Caddy 后，浏览器访问 https://md.example.com 即可。Caddy 会自动把流量转发到本机 3000 端口，同时处理 WebSocket 升级，不需要额外写 upgrade 头。

如果你已经有一套 Nginx 在管理多个站点，那就用 Nginx。配置 HTTP 时简单，但 WebSocket 必须显式加上升级相关的请求头：

nginx复制server {
    listen 80;
    server_name md.example.com;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

配置完成后用 nginx -t 检查语法，再 reload 一次。随后修改 CodiMD 的 CMD_DOMAIN 为 md.example.com，CMD_PROTOCOL_USES_HTTPS 设为 true，重启容器。

很多人在这一步只改了域名没改 HTTPS 开关，结果页面能打开，但 CodiMD 回调生成的一直是 HTTP 地址，导致登录跳转、图片上传这些功能变得异常。这也是典型的“配置项联动”问题，不能只看某一个变量。

关于防火墙和安全组，记得去云控制台把 80/443 端口开给公网，同时确认服务器本机防火墙也放行了这两个端口。部署早期为了调试可以暂时打开 3000 端口，但调试完成后应立即关掉。

5.2 方案B：没有公网 IPv4 时的隧道方案

如果你的 CodiMD 跑在家里或办公室内网，又确实希望外网的人能访问，常规做法是使用隧道类工具，比如 frp 或 cloudflared。这类工具的原理都是用一台有公网 IP 的服务器做流量中转，把公网请求转发到内网机器的某个端口。思路大致是：在公网服务器上运行服务端程序，在内网运行客户端程序，客户端主动连到服务端并声明“把公网某个域名的流量转发到我这里的 3000 端口”。

以 cloudflared 的快速隧道为例，最简单的方式是：

bash复制cloudflared tunnel --url http://127.0.0.1:3000

它会生成一个临时域名，外网通过这个域名访问到你内网的 CodiMD。这种方式胜在启动快、不需要自己有公网服务器，但临时域名不稳定，也不适合作为长期业务入口。

frp 则更适合有一定运维基础的人。你需要一台公网服务器部署 frps，在内网机器上部署 frpc，然后把公网服务器的某个端口映射到内网机器的 3000 端口。之后用户访问公网服务器的域名或 IP，流量就被送到内网 CodiMD。这种方式可控性强，但前提是你得有一台公网服务器，那不如直接把服务部署在公网服务器上更省事。

需要提醒的是，无论用哪种隧道方案，都相当于把你的内网应用暴露到了公网。如果 CodiMD 还处于允许匿名编辑的状态，那危险程度会明显上升。所以隧道方案至少要先满足两个条件：关闭匿名访问、限制注册或者彻底关掉注册，然后在条件允许时再接入 HTTPS。

5.3 外部访问前必须完成的安全设置

把 CodiMD 开放到公网之前，有几道和产品无关但必须做的安全动作。

第一是用户注册策略。如果你不是要做公开写作平台，就关闭邮箱注册。CodiMD 的用户体系不算复杂，开放注册很容易被爬虫或垃圾账号塞满，到时候你还得手动清理。更好的做法是用预置账号或者接入企业已有的 OIDC/LDAP 认证，这能让用户管理和权限管理都集中到统一体系里。

第二是 HTTPS 必须到位。Markdown 内容可能包含内部系统地址、密钥片段、会议链接等敏感信息，走明文 HTTP 的话，任何中间环节都可能被截获。用 Caddy 或 Nginx 把 HTTPS 套上之后，CodiMD 内部的 CMD_PROTOCOL_USES_HTTPS 也要同步打开，否则又会回到上一节说的回调协议错误。

第三是不要直接把数据库端口暴露出去。PostgreSQL 的 5432 端口只应该在内网 Docker 网络里被 CodiMD 应用容器访问，宿主机层面不要把它映射到公网。即使有必要远程管理数据库，也应通过 SSH 隧道方式而不是直接开放端口。

第四是上传目录要持久化并限制大小。很多人在容器里传图，结果容器一删图片全没，就是因为没有把上传目录挂载到宿主机。我的 compose 文件里用了一个 upload-data 卷来保存上传文件，这就避免了容器重建导致的数据丢失。如果多人长期高频传图，建议时不时检查一下上传目录的磁盘占用，别等到磁盘满了才发现。

6. 上线后的权限模型、运维习惯与实践经验

6.1 匿名、注册和 freeURL 的取舍

CodiMD 的权限模型和很多在线文档工具不太一样，它把权限分成几个维度。匿名用户可以不可以新建页面，注册用户能不能随便创建任意路径，文档创建后其他登录用户能不能看到，这些都会直接影响你这个实例是否“安全”和“好用”。

我实际跑了一段时间后形成的配置经验是：内部团队使用时，CMD_ALLOW_ANONYMOUS=false，CMD_ALLOW_EMAIL_REGISTER=false，用户走预置账号或统一认证；CMD_ALLOW_FREEURL 也设为 false，这样页面 URL 由系统生成，不会出现有人随意创建一个一眼就能猜到的路径来放敏感内容。文档创建后的可见范围在编辑器右上角或设置的权限位置可以调整，设为 limited 或 private 会更安全。

如果你希望不需要账号也能让访客看文档，那可以在文档权限里选择可读，但创建文档仍然要求登录。匿名协作这种模式建议只在可信网络环境里用，公网开着匿名等于给全网发了一把编辑钥匙。

6.2 日常使用中那些提升效率的小功能

CodiMD 不只是个多人 Markdown 编辑器，它内置了不少实用能力。其中一个很有用的习惯是在文档开头写 YAML 格式的元信息，用来设置标题、标签和权限，比如：

markdown复制title: 部署检查清单
tags: devops, checklist
---

这里是正文。

带元信息的文档在列表页展示会更清晰，标签也便于后期查找。

另一个常见需求是做幻灯片。用 Markdown 写幻灯片时，CodiMD 会走 reveal.js 风格的渲染，你可以用 --- 分页，然后进入幻灯片模式演示。我经常用它给团队做内部技术分享，不用额外安装 PPT 工具，改完 Markdown 直接全屏演示，非常轻。

导出功能也值得提一下。CodiMD 支持把单个文档导出为 HTML、PDF 等多种形式。用浏览器的打印功能更可控，但 CodiMD 帮你去掉了大部分页面导航，打印出来的排版会比较干净。只是导出 PDF 时中文字体渲染依赖服务器安装的字体库，如果发现中文变成方块或者缺字，需要在容器或系统里补上中文字体。

6.3 版本升级和备份是长期运维的核心

本地部署服务，最怕的不是功能不会配，而是数据丢了或者版本乱升级把数据搞坏。CodiMD 的数据主要分两部分：PostgreSQL 里的文档和用户数据，以及上传目录里的图片附件。

备份数据库可以用 pg_dump。我的备份命令类似这样：

bash复制docker exec codimd-db pg_dump -U hedgedoc hedgedoc | gzip > codimd_backup_$(date +%F).sql.gz

恢复时先确认容器在运行，再执行：

bash复制gunzip -c codimd_backup_xxx.sql.gz | docker exec -i codimd-db psql -U hedgedoc hedgedoc

上传目录的备份更简单，直接把宿主机上挂载的 volume 所在目录做增量同步或打包即可。如果你用 Docker 命名卷，卷的物理位置会藏在 Docker 数据目录中，我习惯在 compose 里把上传目录改用具名目录挂载，比如 ./uploads:/hedgedoc/public/uploads，这样备份时一目了然。

升级版本时别急着 docker compose pull 后直接重启。先把数据库和上传目录备份好，再拉新镜像启动，观察容器日志里有没有数据库迁移的报错。CodiMD 在数据库结构有变更时会自动执行迁移，多数情况下能顺利完成，但万一中断，起码有备份可以回滚。

6.4 高频问题排查对照表

结合我自己的使用经验，整理一份高频问题排查表，方便你出问题时按图索骥。

6.5 几个从实际部署中总结的小习惯

在完整跑过几轮部署、升级、迁移之后，我现在每部署一套 CodiMD 都会先做几件看似不起眼但很关键的事。第一，把 compose 文件和配置文件纳入 Git 管理，这样改坏了可以随时回看版本；第二，在服务器上用一个独立用户跑 Docker Compose，而不是直接用 root，这样即使容器被攻破，攻击者能拿到的权限也有限；第三，把备份做成定时任务，每天凌晨自动备份数据库和上传目录，保留最近 7 天或 30 天的备份文件，具体保留周期看团队对历史版本的需求。

另外，如果你打算长期使用这个实例，最好在页面里给团队写一个简短的“使用约定”，比如哪些类型的文档放这里、是否需要遵循统一的命名前缀、多人同时编辑时的注意事项等。Markdown 协作工具本身不会替你解决文档规范，但这个工具一旦用起来，文档数量增长会很快，提前定好规则能让后续维护省心很多。