Etherpad 3.3.9 配置参数详解

目标：逐项梳理 Etherpad 3.3.9 的配置体系——环境变量与 settings.json 两种配置方式的替换规则、约 130 个可配置参数按域分类详解（含义/官方默认值/实测行为）、3.3.9 新增的 padRetention 特性与一份生产配置模板。全部默认值实测提取自官方发行版内置 settings.json 模板，关键参数行为在 Ubuntu 22.04 实测验证（2026-10-22，部署形态见《Etherpad 3.3.9 Docker Compose 部署指南》）。

一、环境信息

• 操作系统：Ubuntu 22.04（x86_64）
• Etherpad：3.3.9（官方发行版部署，安装路径 /opt/etherpad-lite，配置文件 /opt/etherpad-lite/settings.json）
• 配置载体：官方发行版内置 settings.json 模板（约 900 行、含注释），环境变量经模板占位符注入
• 实测参数清单来源：对内置模板执行占位符提取，得到 133 条 ${ENV:默认值} 映射（去模板示例后约 127 个有效参数）

二、前置条件

# 服务运行中、配置文件可读
curl -s http://127.0.0.1:8134/health
ls -la /opt/etherpad-lite/settings.json

实测输出：

{"status":"pass","releaseId":"3.3.9"}
-rw-r--r--    1 etherpad root        32850 Oct 18 18:18 settings.json

三、参数查看与修改方式

3.1 查看：三种途径

一查内置模板原文（全部参数与注释都在这里）：

cat /opt/etherpad-lite/settings.json | head -30

实测输出（节选）：

/**
 * THIS IS THE SETTINGS FILE THAT IS COPIED INSIDE THE DOCKER CONTAINER.
 *
 * By default, some runtime customizations are supported (see the
 * documentation).
 ...
 *    "port":     "${PORT:9001}"
 *    "minify":   "${MINIFY}"
 *    "skinName": "${SKIN_NAME:colibris}"

二查运行日志（启动时打印加载路径与日志级别）：

grep -E "settings loaded|loglevel" <服务进程日志> | tail -2

服务日志随进程 stdout 输出，按托管方式获取（systemd 托管走 journalctl，脚本托管重定向到日志文件）。实测输出：

[INFO] settings - settings loaded from: /opt/etherpad-lite/settings.json
[WARN] settings - loglevel: INFO

三查管理台：浏览器访问 http://<IP>:8134/admin/（admin 账号登录），设置页直接展示当前生效配置（由 SHOW_SETTINGS_IN_ADMIN_PAGE 控制显示，默认 true）。

3.2 修改：环境变量优先，文件挂载兜底

方式一（推荐）：Compose 的 environment: 段注入环境变量。方式二：挂载自定义 settings.json（精细参数如 padRetention 用此方式）。两种方式可叠加——挂载文件里仍可用 ${ENV:default} 占位符，替换发生在读取时。

⚠️ 排障实录：挂载的 settings.json 若语法不合法，服务启动循环失败，日志报 There was an error processing your settings file from /opt/etherpad-lite/settings.json: PropertyNameExpected at offset <数字>。实测踩坑：在注释块 */ 结尾后接逗号再写新属性（*/\n ,\n "padRetention": {...}）会触发该错误；把新属性插到注释块之前即可。修复后重启正常。

3.3 环境变量替换规则（官方模板注释实测摘录）

⚠️ 注意：Compose 里布尔变量必须写成字符串 "true"/"false"，不能写 YAML 布尔（否则注入的是 True/False 字面量而非模板期望的替换串）。

四、参数总览

按功能域汇总 3.3.9 全部可配置参数域及代表参数（完整默认值见各域详解小节）：

五、核心参数分类详解

5.1 服务器与站点

实测：TITLE 与 SKIN_NAME 注入后启动日志出现 Using skin "colibris" in dir: /opt/etherpad-lite/src/static/skins/colibris；ENABLE_DARK_MODE 默认 true（跟随浏览器暗色偏好，3.3.9 已修复暗色模式下编辑器外部元素的配色，官方 #8271）。

5.2 数据库

实测：生产形态 DB_TYPE=postgres + 连接四件套启动成功，pad 写入后可在库中查到 pad:<padID> 键；数据库连接失败时服务启动报 Error: connect ECONNREFUSED <IP>:5432 并退出重试（restart: always 下自动恢复）。

5.3 认证与访问控制

实测：ADMIN_PASSWORD=q1w2e3r4 注入后管理台 admin 账号可登录；AUTHENTICATION_METHOD=apikey 下 HTTP API 用 APIKEY.txt 认证（API 侧实测见《Etherpad 3.3.9 常用 CLI 命令与工具详解》6.1/6.2 节），sso 模式下同请求报 {"code":4,"message":"no or wrong API Key"}。

5.4 pad 行为

实测：LOWER_CASE_PAD_IDS="true" 注入重启后，API 创建 padID=MiXeDcase99，库中实际键为 pad:mixedcase99（大小写全部归一）；DEFAULT_PAD_TEXT="Welcome to Etherpad" 生效于新建 pad 初始内容。

5.5 pad 保留（3.3.9 新增，仅文件配置）

padRetention 是 3.3.9 的新特性（官方 #8340）：定期清理 N 天无人编辑的 pad，替代已停止维护的 ep_delete_after_delay 插件，且不再产生 HTML 归档副本。它没有环境变量入口，只能在 settings.json 配置：

"padRetention": {
  "enabled": true,
  "deleteAfterDays": 180,
  "warnBeforeDays": 14,
  "sweepIntervalHours": 24,
  "excludeGroupPads": true,
  "excludePattern": "^archive_",
  "dryRun": true
}

逐项说明：enabled 总开关（默认关）；deleteAfterDays 超过 N 天无编辑即删（默认建议 180）；warnBeforeDays 删除前 N 天给出警告（面向通知类插件）；sweepIntervalHours 扫描间隔小时数；excludeGroupPads 跳过分组 pad；excludePattern 按正则豁免 padID；dryRun 预演模式——只打日志不真删，官方默认且强烈建议先观察。

实测：挂载含上述配置的 settings.json 重启后，启动日志出现：

[INFO] padRetention - pad retention in DRY RUN (nothing is deleted): pads unedited for 180 day(s) would be deleted

确认机制生效；生产观察一段时间（日志无误伤）后将 dryRun 改 false 才真正删除。

5.6 速率与资源限制

5.7 日志与隐私

实测：默认 LOG_LEVEL=INFO 启动日志报 [WARN] settings - loglevel: INFO（级别与输出一致）；进程退出遇到清理钩子阻塞时日志提示 Enable dumpOnUncleanExit setting to get a dump of objects preventing a clean exit。

5.8 导入导出

5.9 更新检查与遥测

六、生产配置模板

适用场景：8-16GB 内存服务器、NVMe SSD、团队规模 50-500 人的自托管协同写作实例。结构为「Compose 环境变量 + settings.json 文件」双层：环境变量管连接与开关，settings.json 管精细策略。

服务环境变量（生产值示例，密码请换强值；注入方式按部署形态——Compose 的 environment 段、systemd 的 Environment= 或启动脚本 export）：

    environment:
      NODE_ENV: production
      ADMIN_PASSWORD: q1w2e3r4
      DB_TYPE: postgres
      DB_HOST: postgres
      DB_PORT: "5432"
      DB_NAME: etherpad
      DB_USER: etherpad
      DB_PASS: q1w2e3r4
      DEFAULT_PAD_TEXT: "Welcome to Etherpad"
      LOG_LEVEL: INFO
      TRUST_PROXY: "true"
      AUTHENTICATION_METHOD: apikey
      LOWER_CASE_PAD_IDS: "true"
      DISABLE_IP_LOGGING: "true"

/opt/etherpad/data/settings.json 追加段（挂载方式见部署指南第八节，注意新属性插在注释块之前——3.2 节排障实录）：

  "padRetention": {
    "enabled": true,
    "deleteAfterDays": 180,
    "warnBeforeDays": 14,
    "sweepIntervalHours": 24,
    "excludeGroupPads": true,
    "excludePattern": "^archive_",
    "dryRun": true
  },

模板要点解读：

• TRUST_PROXY: "true" 仅在 Nginx 等可信反代之后启用，配合代理传递真实客户端 IP；
• DISABLE_IP_LOGGING: "true" 面向隐私合规要求；如无合规压力可保持默认以保留审计能力；
• padRetention 先以 dryRun: true 上线观察扫描日志，确认无误伤后翻 false；
• 数据库密码等敏感值可用 ${VAR} 占位由 Compose 从 .env 注入——这与 3.3 节的模板占位符是两层机制（Compose 层先注入，Etherpad 层再替换），互不冲突；
• 插件体系扩展（登录增强、Markdown、TOC 等）通过 ep_* 插件安装，操作与实测见《Etherpad 3.3.9 常用 CLI 命令与工具详解》5.1 节。

七、常见问题

Q1：改了环境变量不生效 确认配置修改后按部署形态完整重建服务实例（而非仅重启进程；进程重启不重读环境变量）。布尔值是否写成了字符串 "true"（YAML 布尔会静默失效）。

Q2：启动循环失败，日志报 PropertyNameExpected at offset N 挂载的 settings.json 语法错误（常见：注释块后接逗号新属性）。按 3.2 节排障实录调整插入位置。

Q3：某参数想恢复默认 环境变量方式：删掉该变量（模板默认值即生效）；文件方式：删除该键或把值改成 "undefined"（按 3.3 规则该键从配置移除，回落到代码内置默认）。

Q4：大文档导入报 413 或失败 调大 SOCKETIO_MAX_HTTP_BUFFER_SIZE（如 "10000000"）并确认 IMPORT_MAX_FILE_SIZE 覆盖目标文件大小。

Q5：管理台看不到设置页 SHOW_SETTINGS_IN_ADMIN_PAGE 被设为 "false"；或 ADMIN_PASSWORD 未设置导致无管理账号。

八、参考链接

1. 官方配置文档：https://docs.etherpad.org/settings.html （查询日期 2026-10-22）
2. 内置 settings.json 模板（参数与默认值的权威来源）：https://github.com/ether/etherpad/blob/HEAD/settings.json.template （查询日期 2026-10-22）
3. v3.3.9 Release Notes（padRetention / suppressPadDeletionTokenModal 等新参数）：https://github.com/ether/etherpad/releases/tag/v3.3.9 （查询日期 2026-10-22）
4. 站内延伸：《Etherpad 介绍与选型指南》《Etherpad 3.3.9 Docker Compose 部署指南》《Etherpad 3.3.9 常用 CLI 命令与工具详解》