直接用 docker run 启动 linuxserver/hedgedoc 是目前唯一稳、快、可维护的安装方式；源码编译或 npm start 因 Node.js 20+ 与 sharp、pg、node-gyp 兼容性断层已不可靠，官方自 2025 年底起停止保障 Node.js 运行时兼容性。
直接用 docker run 启动 linuxserver/hedgedoc 镜像是目前唯一稳、快、可维护的安装方式。源码编译或 npm start 在 2026 年已不可靠——Node.js 20+ 与 sharp、pg、node-gyp 的兼容性断层是硬伤，不是配置问题。
为什么不能用 git clone + yarn start
官方自 2025 年底起停止保障 Node.js 运行时兼容性；实测在 Ubuntu 22.04/24.04 上常见报错包括：
-
error: invalid URI query parameter: "user"（DB_URL 中密码含@或/未 URL 编码） -
gyp ERR! build error（node-gyp编译失败，因缺少 Python 3.11+ 或 libc++ dev 包） -
pg version mismatch with PostgreSQL 15（pg包版本锁死，无法适配新 PostgreSQL 协议） - 健康检查端点
/healthz不启用，systemd 无法感知服务状态
docker run 必须带的 5 个参数
跳过 docker-compose 也能快速启动，但以下参数缺一不可，否则服务起不来或数据不持久：
Docker Image Puller
下载
使用 Python 脚本下载 Docker 镜像并打包为 tar 文件。用户说“下载镜像”“拉取镜像”“pull xxx”“帮我下载 nginx 镜像”等时触发。支持 SOCKS5 代理直连（推荐）和国内镜像站加速两种模式。
-
-e DB_URL=postgres://hedgedoc:pass@host.docker.internal:5432/hedgedoc_db：容器内必须用host.docker.internal，写localhost会连不上宿主机 PostgreSQL -
-e CMD_DOMAIN=https://notes.yourdomain.com：必须带协议和完整域名，否则 WebSocket 被浏览器拦截、PDF 导出链接错误 -
-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 - 数据库用户密码不能含
@、/、:等字符，否则DB_URL解析失败 - PostgreSQL 配置中需确认
password_encryption = scram-sha-256，若仍用md5，HedgeDoc 会拒绝连接
真正麻烦的从来不是“怎么跑起来”，而是 HD_BASE_URL、反向代理的 X-Forwarded-Proto、数据库 locale、密码特殊字符这四个点同时对齐——漏一个，实时协作就断、上传就 404、登录就跳转回 http://localhost:3000。这些不是 bug，是容器网络和 Web 安全模型下的必然约束。
