Jotty 1.29.2 配置参数详解

目标：梳理 Jotty 1.29.2 的配置体系与全部环境变量，给出推荐取值与组合示例。参数语义依据仓库 howto/ENV-VARIABLES.md、howto/DOCKER.md 与 docker-compose.yml（查询日期 2026-10-30），开关行为与排障均在 1.29.2 实测环境验证。部署步骤见《Jotty 1.29.2 Docker Compose 部署指南》。

一、配置体系总览

Jotty 无独立配置文件，配置分两轨：

1. 环境变量（部署层）：随服务注入，覆盖运行模式、身份、反代、SSO、安全、多实例等，本文全部收录；
2. 数据目录内 JSON 文件（业务层）：data/users/users.json（账户与 API 密钥）、data/users/sessions.json（会话）、data/sharing/shared-items.json（分享）等由系统自动维护，不建议手工编辑（结构依据 README"Data Storage"章节）。

环境变量分九组逐一说明。以下未标注"可选"者均为官方标注的必填或强推荐项。

二、基础运行参数

实测记录：以 NODE_ENV=production 启动后日志出现 Ready on http://0.0.0.0:3000；启动时运行时补丁器输出 [patch:patches] freebsd_20260427: skipped (JOTTY_FREEBSD not set)，与上表语义一致。

三、反向代理与 HTTPS 参数

排障经验（官方 howto/ENV-VARIABLES.md 明示的典型场景）：反代后登录失败，第一步设 APP_URL，仍失败再设 DEBUGGER=proxy 观察日志；多实例集群还需代理正确转发 WebSocket 升级头并保持 Host 不变（howto/DOCKER.md"Running more than one instance"）。

四、附件公开访问参数

安全提示：三者一旦开启即等于"知道链接的任何人可读"。1.29.0 的附件重构已将附件可见性收敛到笔记权限（release notes：附件仅对拥有/可访问该笔记的用户可见），这三个开关属于面向外链嵌入场景的显式放行，公开实例建议保持默认关闭。官方发布说明同时表示这三个变量将随附件权限重构逐步退役。

五、安全与账号保护参数

六、SSO / OIDC 参数（可选组）

启用 SSO 的最小集：APP_URL + AUTH_MODE=oidc + OIDC_ISSUER + OIDC_CLIENT_ID。

七、多实例（HA）参数

集群工作原理（howto/DOCKER.md，查询日期 2026-10-30）：实例间通过 data/.replica/ 下的一次性小文件交换打开中笔记的实时内容与持有者，全部关闭后该文件删除；持久副本始终只有笔记本身，不引入数据库或消息队列。故障表现：单实例宕机时编辑器显示 Offline 并继续接受输入，恢复后重新同步。

八、API 与 MCP 相关开关

开关行为实测（1.29.2）：

# 默认（未设置 ENABLE_API_DOCS）：
curl -s -o /dev/null -w "HTTP %{http_code}\n" http://127.0.0.1:8131/api/docs
# 实测回显：HTTP 404

# compose 追加 ENABLE_API_DOCS=true 并重建后：
curl -s -o /dev/null -w "HTTP %{http_code}\n" http://127.0.0.1:8131/api/docs
# 实测回显：HTTP 200
curl -s "http://127.0.0.1:8131/api/docs?format=yaml"
# 实测回显（节选）：
# openapi: 3.1.0
# info:
#   title: Jotty API
#   version: 1.29.2

对比之下，需密钥的 GET /api/openapi.json 在未认证时实测返回 401。公开实例若不想暴露 API 全貌，保持 ENABLE_API_DOCS 关闭即可（上述端口为实测环境取值，按你的部署替换）。MCP 网关为独立伴生发布物（ghcr.io/fccview/jotty-mcp），通过 JOTTY_MCP_AUTH_TOKEN、JOTTY_MCP_TRANSPORT=http、JOTTY_MCP_PORT 三个自身环境变量接入主服务，见仓库 docker-compose.mcp.yml。

九、组合示例

个人实例（本机实测基线）：

environment:
  - NODE_ENV=production
  - STOP_CHECK_UPDATES=yes
  - DEFAULT_LOCALE=en

反代 + SSO 实例（Authentik）：

environment:
  - NODE_ENV=production
  - HTTPS=true
  - APP_URL=https://notes.example.com
  - AUTH_MODE=oidc
  - OIDC_ISSUER=https://auth.example.com/application/o/jotty
  - OIDC_CLIENT_ID_FILE=/run/secrets/oidc_client_id
  - OIDC_CLIENT_SECRET_FILE=/run/secrets/oidc_client_secret
  - SSO_FALLBACK_LOCAL=yes
  - OIDC_ADMIN_GROUPS=jotty-admins

双实例高可用（共享 data/ 目录 + 独立节点名）：

# 实例 A
environment:
  - NODE_ENV=production
  - JOTTY_NODE=node1
# 实例 B（共享同一 data/ 挂载）
environment:
  - NODE_ENV=production
  - JOTTY_NODE=node2

十、排障实录（实测沉淀）

1. /api/docs 返回 404：不是故障，ENABLE_API_DOCS 默认关闭（实测关态 404、开态 200，见第八节）。排查其他接口异常时勿将此 404 误判为服务未就绪——服务就绪以启动日志 Ready on http://0.0.0.0:3000 为准。
2. 改环境变量不生效：docker compose up -d 只在检测到配置变化时重建服务；确认 compose 文件已保存后观察其输出是否出现 Recreated 行。实测追加 ENABLE_API_DOCS 后重建输出包含 Container jotty Starting / Started，新值随即生效。
3. 登录页循环重定向：反代场景优先补 APP_URL；仍异常时临时开启 DEBUGGER=proxy 查看登录链路日志，定位后关闭。
4. NAS 上权限报错：user: "1000:1000" 与目录属主不一致所致，将 PUID/PGID 与 chown 目标对齐（属主核对方法见部署指南 6.2 节）。
5. 多实例实时协作无头像：代理未保留 Host 头或未转发 WebSocket 升级，页面仍可用（打字照常保存），按第七节要求修正代理。

十一、参数速查表（一页版）

配置到位后，建议按《Jotty 1.29.2 REST API 实战指南》完成 API 链路的端到端验收；组件定位回看《Jotty 1.29.2 介绍与选型指南》。