最稳省事的部署方式是直接用docker运行linuxserver/hedgedoc镜像，因其免去源码编译、node.js环境配置、依赖兼容性问题及手动运维细节，官方已明确推荐容器化部署并停止保障node.js运行时兼容性。
直接用 Docker 部署 linuxserver/hedgedoc 是目前最稳、最省事的方式，不建议从源码编译或手动装 Node.js 环境——踩坑成本高，更新维护麻烦，且官方已明确推荐容器化部署。
为什么不用 git clone + npm start？
官方早已将主开发分支转向容器优先策略，hedgedoc/hedgedoc 镜像自 2025 年底起不再提供 Node.js 运行时兼容性保证；实测在 Ubuntu 22.04 上手动 npm install 后常报 node-gyp 编译失败、sharp 依赖缺失、pg 版本与 PostgreSQL 15 不匹配等错误。这些不是配置问题，而是生态断层导致的必然结果。
- 源码方式需自行处理反向代理、HTTPS 终止、静态资源路径、会话密钥生成等运维细节
- 数据库迁移脚本（如从 v3.x 升级到 v4.0）只在镜像启动时自动触发，手动运行易遗漏
- 健康检查端点
/healthz在非容器环境下默认不启用，无法被 systemd 或 nginx 监控
docker run 命令必须带的关键参数
跳过 docker-compose 也能快速跑起来，但以下 5 个参数缺一不可，否则服务要么起不来，要么文档存不住：
-
-e DB_URL=postgres://hedgedoc:pass@host.docker.internal:5432/hedgedoc_db：注意用host.docker.internal而非localhost，否则容器内连不上宿主机数据库 -
-e CMD_DOMAIN=https://notes.yourdomain.com：必须带协议和完整域名，否则导出 PDF/分享链接生成错误、WebSocket 连接被浏览器拦截 -
-e CMD_ALLOW_ANONYMOUS=false：默认为 true，公开部署时务必关掉，否则未登录用户可创建、编辑、删除任意文档 -
-v /opt/hedgedoc/uploads:/app/public/uploads：上传的图片/附件必须挂载，否则重启容器后全部丢失 -
--restart=unless-stopped：避免服务器重启后服务静默退出
PostgreSQL 初始化容易漏的三件事
即使你用了 linuxserver/hedgedoc 镜像，数据库仍需手动准备——镜像不会帮你建库、设权限、调参数：
- 必须提前执行
CREATE DATABASE hedgedoc_db WITH ENCODING 'UTF8' LC_COLLATE='en_US.UTF-8' LC_CTYPE='en_US.UTF-8';，否则启动时报invalid locale name - 用户密码不能含
@、/、:等 URL 特殊字符，否则DB_URL解析失败（常见错误信息：error: invalid URI query parameter: "user"） - PostgreSQL 需开启
password_encryption = scram-sha-256（9.6+ 默认），若用 md5 认证，HedgeDoc 会拒绝连接并静默退出，日志里只显示connection failed
反向代理配置的硬性要求
Nginx 或 Caddy 必须透传 WebSocket 和特定 header，否则实时协作光标不同步、多人编辑卡顿：
- 必须设置
proxy_set_header Upgrade $http_upgrade;和proxy_set_header Connection "upgrade"; - 必须透传
X-Forwarded-For和X-Forwarded-Proto，否则CMD_DOMAIN判断失效，PDF 导出里的超链接变成http://开头 - 若启用了 Let’s Encrypt，证书不能只配在 Nginx 层——HedgeDoc 内部的邮件发送模块（如 SMTP 密码重置）会校验
CMD_DOMAIN的 HTTPS 可达性，否则发信失败且无明确报错
真正麻烦的从来不是“怎么跑起来”，而是“怎么让协作不掉帧、上传不丢图、导出不乱码、升级不丢历史”。这些细节藏在环境变量拼写、数据库 locale 设置、反向代理 header 透传里，而不是文档首页那行 docker run 示例中。
