HedgeDoc 1.12.0 配置参数详解

目标：系统梳理 HedgeDoc 1.12.0 的双轨配置体系（config.json 文件 / CMD_* 环境变量），逐项给出官方默认值与实测行为，并交付一份生产配置模板。本文默认值口径取自官方配置文档（docs.hedgedoc.org/configuration/，1.x，2026-10-22 查证），标注「实测」的行为均在 Ubuntu 22.04.4 LTS + HedgeDoc 1.12.0 实验实例上验证通过（部署过程见 《HedgeDoc 1.12.0 Docker Compose 部署指南》）。

一、环境信息

二、前置条件

1. 已按 《HedgeDoc 1.12.0 Docker Compose 部署指南》完成部署且 /_health 返回 {"ready":true}；
2. 知晓本文两条主线：环境变量（CMD_*）与 config.json 文件，两者任选其一或混用；
3. 改动配置后需要重建应用服务才生效（环境变量是启动时读取的），验证手段统一为「启动日志 + /_health + 对应端点行为」。

三、参数查看与修改方式

3.1 双轨体系与优先级

官方配置文档的规则（原文口径）：

• 环境变量优先于 config.json："Environment variables take precedence over configurations from the config files"；
• 环境变量以 CMD_ 前缀命名（历史上的 HMD_ 前缀改名而来，旧前缀仍兼容）；
• config.json 的查找路径可用 CMD_CONFIG_FILE 环境变量覆盖（默认无强制路径，官方建议从仓库 config.json.example 复制改造）；
• 参数解析代码在官方仓库 lib/config/environment.js（环境变量）与 lib/config/index.js（config.json），默认值定义在 lib/config/default.js。

3.2 修改方法（Compose 部署形态）

方式一：环境变量（推荐，改动即见，无需额外文件）——编辑 /opt/hedgedoc/docker-compose.yml 的 app.environment 段后重建：

cd /opt/hedgedoc
docker compose up -d    # environment 变化时 compose 会自动重建应用服务

 Container hedgedoc-1.12.0-app Recreate
 Container hedgedoc-1.12.0-app Recreated
 Container hedgedoc-1.12.0-app Starting
 Container hedgedoc-1.12.0-app Started

方式二：config.json 文件——创建 /opt/hedgedoc/config.json，在 compose 的 app 服务加挂载：

    volumes:
      - /opt/hedgedoc/config.json:/hedgedoc/config.json:ro
    environment:
      - CMD_CONFIG_FILE=/hedgedoc/config.json

config.json 是否被正确读取，可用「缺关键项」的方法实测确认：本文实验中曾挂载一份未含 sessionSecret 的最小 config.json（{"domain":"192.168.146.128","loglevel":"info"}），启动日志立即出现对应告警，证明文件被解析（实测回显）：

2026-10-21T16:29:42.034Z warn:  Session secret not set. Using random generated one. Please set `sessionSecret` in your config.json file. All users will be logged out.
2026-10-21T16:29:42.506Z info:  All migrations performed successfully
2026-10-21T16:29:42.511Z info:  HTTP Server listening at 0.0.0.0:3000

3.3 生效验证三板斧（每改必验）

1. 启动日志：docker compose logs --since 1m app，确认无 Session secret not set 类告警、无 config 解析报错；
2. 健康端点：curl -s http://192.168.146.128:8132/_health → {"ready":true}；
3. 行为端点：改了什么就验什么（如改 CMD_ENABLE_STATS_API 验 /status，改 CMD_ALLOW_EMAIL_REGISTER 验 /register），本文第五章各参数均附实测或官方口径的行为。

四、参数总览

HedgeDoc 1.x 的参数按域分为 8 组。下表为全景索引（★=本文有实测行为佐证）：

如何选：先用最小集（域名 + 数据库 + 会话密钥）跑通（见第六章模板），再按需逐域加参数——每加一个都用 3.3 节的三板斧验证，避免一次性堆参数排障困难。

五、核心参数分类详解

5.1 运行时与数据库

⚠️ 注意：官方镜像内置数据库驱动仅含 PostgreSQL；不要尝试把 CMD_DB_DIALECT 指向 sqlite/mysql——1.12.0 官方文档的安装矩阵只有 PostgreSQL。

5.2 网络与位置

5.3 用户与权限

5.4 笔记与内容

5.5 安全（CSP / HSTS / 限流 / Cookie）

💡 技术拓展：「登录限流」的常见实现路线对比——

路线	原理	适用场景
应用内窗口限流（HedgeDoc 内置）	按用户+5 分钟窗口计数	单实例，开箱即用（本文实测对象）
反向代理层限流（nginx limit_req 等）	在 HTTP 入口按 IP/键限流	多实例统一入口管控
专业网关/WAF	规则引擎 + 风险评分	高暴露面公网服务

HedgeDoc 单实例部署用内置 CMD_RATE_LIMIT_USER/CMD_RATE_LIMIT_NEW_NOTES 即可覆盖注册撞库与灌水场景。

5.6 登录方式集成（本地邮箱之外的 IdP）

以下均为「配了才启用」的集成项，默认全部关闭（无默认值）。完整字段见官方配置文档对应小节，此处列参数骨架与关键取值：

⚠️ 注意：1.12.0 发布说明的行为变更——「若未启用表单登录且恰好只配置了一个外部登录方式，登录弹窗会自动跳过」，即配置单一 IdP 后用户进入即是 IdP 认证页。自建企业站建议只保留一种 IdP + CMD_ALLOW_EMAIL_REGISTER=false，收敛入口。

5.7 图片与上传存储（filesystem 之外）

CMD_IMAGE_UPLOAD_TYPE 决定图片去向。选 s3/minio/azure 时需同步配置对应密钥组：

如何选：单机小团队用默认 filesystem（配合 uploads 目录持久化，见部署篇）即可；图片量大或多实例共享存储时选 MinIO/S3。CMD_MINIO_SECURE 默认 true，对接内网自建 MinIO（无 TLS）必须显式设 false，这是最常见踩坑点。

5.8 运维可观测

六、生产配置模板

适用场景：8–32 人团队、单服务器（4 核 8GB、NVMe SSD）、直接 http://IP:8132 访问、本地邮箱认证、filesystem 图片存储。文件：/opt/hedgedoc/docker-compose.yml 的 app 服务环境变量段（数据库段见部署篇）：

    environment:
      # —— 位置与访问 ——
      - CMD_DOMAIN=192.168.146.128          # 对外 IP 或域名
      - CMD_ALLOW_ORIGIN=['192.168.146.128']
      - CMD_URL_ADDPORT=true                # 分享链接拼接端口
      # —— 数据库 ——
      - CMD_DB_URL=postgres://hedgedoc:hedgedoc-db-2026@database:5432/hedgedoc
      # —— 会话 ——
      - CMD_SESSION_SECRET=hd-session-secret-2026-quzuo   # 用 pwgen -s 64 1 生成自己的
      - CMD_SESSION_LIFE=604800000          # 会话 7 天（毫秒）
      # —— 注册与权限收敛 ——
      - CMD_ALLOW_EMAIL_REGISTER=false      # 关自助注册，账号走 CLI 创建
      - CMD_ALLOW_ANONYMOUS=false           # 关匿名，全员实名
      - CMD_DEFAULT_PERMISSION=private      # 新笔记默认私有
      - CMD_ENABLE_UPLOADS=registered       # 仅注册用户可传图
      # —— 安全加固 ——
      - CMD_CSP_ALLOW_FRAMING=false         # 禁 iframe 嵌入
      - CMD_CSP_ALLOW_PDF_EMBED=false       # 禁 PDF 内嵌
      - CMD_ALLOW_GRAVATAR=false            # 内网不出外网头像请求
      - CMD_RATE_LIMIT_USER=10              # 登录/注册限流（默认值，显式声明）
      - CMD_RATE_LIMIT_NEW_NOTES=20
      # —— 运维 ——
      - CMD_LOGLEVEL=info
      - CMD_ENABLE_STATS_API=true           # 保留 /status 供监控采集

逐组解读：位置组三项决定「链接长什么样、谁能跨域访问」；数据库与会话密钥是「丢了就要命」的两项（密钥换 = 全员登出）；注册与权限组把实例从「开放维基」收敛为「实名知识库」——关闭自助注册后账号由管理员用命令行创建（逐条实测见 《HedgeDoc 1.12.0 常用 CLI 命令与工具详解》）；安全组默认值之外仅关闭 iframe/PDF 嵌入与外网头像请求，属于官方推荐的低风险加固。

⚠️ 注意：此模板按「IP + 非标准端口」直连形态书写。若改为域名 + 反向代理 + HTTPS：CMD_DOMAIN 换域名、CMD_URL_ADDPORT 删除（443 不拼端口）、CMD_PROTOCOL_USESSL=true、CMD_COOKIE_POLICY 保持 lax。

七、常见问题

Q1：启动日志出现 Session secret not set. Using random generated one...？ CMD_SESSION_SECRET 未设置（config.json 也没写 sessionSecret）。后果是每次重启全员登出（告警原文即说明）。实测该告警在最小 config.json 场景下必然出现（见 3.2 节回显）。解决：两轨任选一处设置固定密钥后重建服务。

Q2：应用日志反复出现 Database cannot be reached. Try N of 30. (SequelizeConnectionError: getaddrinfo EAI_AGAIN database)？ 数据库不可达。HedgeDoc 启动时会重试 30 次（实测回显中 Try 1 of 30）。依次检查：数据库服务是否 Up（docker compose ps）、CMD_DB_URL 主机名/密码、数据库容器是否就绪。实测数据库恢复后应用自动完成迁移并监听端口，无需人工干预。

Q3：开了 CMD_URL_ADDPORT=true，分享链接里的端口却是 3000 而不是对外端口？ 实测复现：宿主端口 8132 → 应用端口 3000 的映射下，CMD_URL_ADDPORT=true 生成的重定向是 http://192.168.146.128:3000/。原因：官方文档注明 URL 生成使用的是 CMD_PORT（应用监听端口），不是端口映射的外侧值。解决三选一：① 映射改为 3000:3000；② 设 CMD_PORT=8132 且映射 8132:8132；③ 域名 + 反代场景关掉 URL_ADDPORT（443/80 不需要拼）。

Q4：关闭邮箱注册后 /register 打不开？ 这是预期行为：实测 CMD_ALLOW_EMAIL_REGISTER=false 后 POST /register 返回 404。此时创建账号的正规途径是命令行工具（bin/hedgedoc 的 users 子命令，见 CLI 篇），或临时开注册建完再关。

Q5：/status 突然 302 跳首页、监控采不到数？ CMD_ENABLE_STATS_API 被设为 false（实测该值会把 /status、/metrics 一起关闭并重定向）。监控需要数据就保持 true；公网实例若担心信息暴露，改在反代层对这两个路径做访问控制，而不是关端点。

Q6：改了环境变量没生效？ 环境变量在启动时读取：必须 docker compose up -d（environment 有变化时会自动 Recreate）而非 restart（restart 不会应用新的 environment）。用 3.3 节三板斧验证。

八、参考链接

1. 官方配置文档：https://docs.hedgedoc.org/configuration/
2. 配置解析源码（环境变量）：https://github.com/hedgedoc/hedgedoc/tree/master/lib/config/environment.js
3. 默认值定义源码：https://github.com/hedgedoc/hedgedoc/tree/master/lib/config/default.js
4. 1.12.0 发布说明：https://github.com/hedgedoc/hedgedoc/releases/tag/1.12.0
5. 本专栏系列：《HedgeDoc 介绍与选型指南》、《HedgeDoc 1.12.0 Docker Compose 部署指南》、《HedgeDoc 1.12.0 常用 CLI 命令与工具详解》