Joplin 3.7.2 配置参数详解

目标：系统性讲清 Joplin 3.7.2 的两层配置——服务端（Joplin Server）环境变量的含义、官方默认值与实测行为，以及客户端（终端 CLI）配置键的读写方式，并给出生产配置模板。全部参数清单提取自 Joplin Server 3.7.2 镜像内置的 env.js 默认值定义，关键参数的开关行为均在部署环境（Ubuntu 22.04、Joplin Server 3.7.2、PostgreSQL 16，服务地址 http://192.168.146.128:8136）实测验证。

一、环境信息

本篇参数实测环境与版本基线如下：

• 服务端：Joplin Server 3.7.2（官方 Docker 镜像，部署形态为官方 docker compose：app + PostgreSQL 16 双服务）
• 客户端：Joplin 终端客户端（CLI）3.7.1（npm 包 joplin，Node.js v20.20.2）
• 操作系统：Ubuntu 22.04.4 LTS
• 服务地址：http://192.168.146.128:8136（`APP_BASE_URL`，容器内端口 22300 对外发布为 8136）
• 数据库：PostgreSQL 16（DB_CLIENT=pg，库名/用户名均为 joplin）
• 参数权威来源：镜像内 /home/joplin/packages/server/dist/env.js 的 defaultEnvValues 定义（即官方默认值的第一手出处），查询日期 2026-10-22
• 部署篇：从零部署过程见 《Joplin 3.7.2 Docker Compose 部署指南》

💡 说明：Joplin 的配置分两层——服务端环境变量（决定服务行为，全部在部署时注入）与客户端配置键（每个客户端实例自己的同步/编辑器/端口等设置，存在客户端配置文件里）。两层互相独立：服务端不感知客户端配置，客户端通过同步协议与服务端协作。

二、前置条件

阅读与动手本篇前，确认以下前提：

1. Joplin Server 已部署并健康（验证：curl http://192.168.146.128:8136/api/ping 返回 {"status":"ok","message":"Joplin Server is running"}；部署方法见部署指南篇）；
2. 有一台装好 Joplin CLI 或桌面端的客户端设备（用于客户端配置分域实测；CLI 安装方法见命令详解篇）；
3. 服务端配置修改涉及重启服务，业务低峰操作。

三、参数查看与修改方式

3.1 服务端：查看生效参数

Joplin Server 启动日志会打印三类核心配置的生效值，这是核实配置是否注入成功的最直接手段（实测回显，节选自 docker compose logs app）：

App: DB Config: {
  client: 'pg',
  name: 'joplin',
  slowQueryLogEnabled: false,
  slowQueryLogMinDuration: 1000,
  maxConnections: 10,
  autoMigration: true,
  user: 'joplin',
  password: '********',
  port: 5432,
  host: 'db'
}
App: Mailer Config: {
  enabled: false,
  host: '',
  port: 465,
  security: 'tls',
  authUser: '',
  authPassword: '********',
  noReplyName: '',
  noReplyEmail: ''
}
App: Content driver: { type: 1 }
App: Content driver (fallback): null

要点解读：Content driver: { type: 1 } 表示附件内容存数据库（type 2 为文件系统），Content driver (fallback): null 表示未配置回退驱动。另确认容器内环境变量是否注入成功（官方 Docker 部署形态下）：

docker exec joplin-3.7.2-server printenv | grep -E 'APP_|DB_|SIGNUP'

实测回显（节选）：

APP_BASE_URL=http://192.168.146.128:8136
APP_PORT=22300
DB_CLIENT=pg
SIGNUP_ENABLED=true

3.2 服务端：修改参数

服务端参数全部通过环境变量注入，标准修改路径（官方 Docker Compose 部署形态）：

1. 编辑部署目录下 .env（如 /opt/joplin/.env）修改目标变量；
2. 确认 compose 文件 environment: 列表引用了该变量（只有被引用的变量才会传进服务进程，实测漏引用时变量静默失效）；
3. docker compose up -d 重建使配置生效；
4. 按 3.1 的日志核对新值。

⚠️ 两类变量修改后需要额外动作：DEFAULT_ADMIN_PASSWORD 只在数据库首次初始化时读取，改它不影响已存在的管理员账号（改密码走 Web 界面）；STORAGE_DRIVER 从数据库切到文件系统涉及存量内容迁移，见 5.4。

3.3 客户端：查看与修改配置键

客户端配置键通过 joplin config 命令读写（终端客户端）：

joplin config sync.target            # 查看单个键
joplin config sync.target 9          # 设置单个键

实测查看回显（键值带枚举说明）：

sync.target = 9 (0: (None), 2: File system, 3: OneDrive, 5: Nextcloud, 6: WebDAV, 7: Dropbox, 8: S3, 9: Joplin Server, 10: Joplin Cloud, 11: Joplin Server (SAML))

客户端配置持久化在配置目录的 settings.json（本篇实测实例的节选，密码类键已脱敏）：

{
  "locale": "en_GB",
  "sync.9.path": "http://192.168.146.128:8136",
  "sync.9.username": "admin@localhost",
  "sync.target": 9
}

（实测该实例共 9 个键；sync.9.password 写入后也在其中，展示时脱敏。）直接改 settings.json 需先完全退出客户端进程，否则会被内存态覆盖；常规修改一律走 joplin config 命令。

四、参数总览

服务端环境变量全集（提取自镜像内置 env.js，按功能域分组；「默认值」列为官方定义）：

如何读这张表：个人/小团队自托管实际会动到的只有「URL、数据库、账号」三个域共十来个变量；Mailer（找回密码邮件）、数据清理、企业认证（LDAP/SAML）按需启用；其余保持默认即可。

五、核心参数分类详解

5.1 服务地址类：APP_BASE_URL 与端口

APP_BASE_URL 是整个服务最关键的参数：客户端同步、Web 界面、附件外链都以它为基准。实测确认它同时是请求来源校验的基准——用非 APP_BASE_URL 形态的地址访问会被直接拒绝：

curl -s http://127.0.0.1:8136/api/ping

实测回显：

Invalid origin: http://127.0.0.1:8136

换成 APP_BASE_URL 配置的地址即正常：

curl -s http://192.168.146.128:8136/api/ping

实测回显：

{"status":"ok","message":"Joplin Server is running"}

选型要点：APP_BASE_URL 必须写「客户端实际可达」的地址。直接 IP 访问写 http://<IP>:<端口>；走反向代理对外提供 https 时写 https 域名，并配合 COOKIES_SECURE=true。APP_PORT 是服务进程监听端口（默认 22300），一般不动，对外换端口由端口映射/反代解决。USER_CONTENT_BASE_URL 仅当附件需要独立域名（如 CDN）时设置，默认留空即随 APP_BASE_URL。

5.2 数据库类：DB_CLIENT 与 POSTGRES_*

DB_CLIENT 决定存储引擎，官方默认 sqlite3（零依赖试用），生产推荐 pg。连接 PostgreSQL 有两种等价写法（官方 README 定义）：

# 写法一：分散变量（本篇实测采用）
DB_CLIENT=pg
POSTGRES_HOST=db
POSTGRES_PORT=5432
POSTGRES_USER=joplin
POSTGRES_PASSWORD=q1w2e3r4
POSTGRES_DATABASE=joplin

# 写法二：连接串
DB_CLIENT=pg
POSTGRES_CONNECTION_STRING=postgresql://joplin:q1w2e3r4@db:5432/joplin

实测行为要点：

• 自动迁移：DB_AUTO_MIGRATION=true（默认）时服务启动自动建表/升级表结构，实测首次启动日志 App: Auto-migrating database... 后出现 Latest migration: { name: '20260821120000_token_purpose.js', done: true }；若把数据库清空但只重启数据库不重启 app，登录接口会报 relation "users" does not exist（错误码 42P01）——重启 app 触发迁移即可修复；
• 连接失败重试：数据库暂时不可达时服务不会退出，实测日志 db: Could not connect. Will try again. 周期重试（主机名解析不通时错误为 getaddrinfo EAI_AGAIN db，需检查网络归属，见部署篇排障）；
• 库与用户需预先存在：Joplin Server 不代建 PostgreSQL 的库与用户（官方 README 明确说明）；
• 连接池：DB_MAX_CONNECTIONS=10 官方注释明确「保持较小值」即可，中小规模（几十用户）无需调整；
• 慢查询：DB_SLOW_QUERY_LOG_ENABLED=true 后超过 DB_SLOW_QUERY_LOG_MIN_DURATION（默认 1000ms）的 SQL 会进日志，排障时临时打开。

5.3 账号与注册类：DEFAULT_ADMIN_PASSWORD、SIGNUP_ENABLED 等

DEFAULT_ADMIN_PASSWORD（默认 admin）：数据库首次初始化时自动创建管理员 admin@localhost，密码取该变量。实测行为：

• 显式设置 DEFAULT_ADMIN_PASSWORD=q1w2e3r4 并全新初始化后，admin@localhost + q1w2e3r4 登录成功（返回 session JSON），旧默认口令 admin 返回 403 Invalid email or password；
• 该变量只在初始化时读取：先初始化再改 .env 不会改已有管理员密码（管理员改密码走 Web 界面的账户设置）；
• 若从未设置该变量就完成初始化，则管理员口令为默认 admin——生产部署务必在首次启动前设强口令。

SIGNUP_ENABLED（默认 false）：控制 /signup 自助注册页的可用性。实测两态行为：

SIGNUP_ENABLED=true   → GET /signup 出表单；POST 合规表单 302 跳 /home，账号创建并可登录
SIGNUP_ENABLED=false  → POST /signup 返回 HTTP 403 Forbidden（页面提示注册未开放）

且 signup 流程内置密码强度校验（zxcvbn 规则），实测弱口令注册被拒（422，提示「This is a very common password. Add another word or two. Uncommon words are better.」），强口令（实测 Uncommon-Joplin-2026 形态）通过。个人私有部署建议保持 false，用管理员在后台建号；开放团队自助注册才置 true。

LOCAL_AUTH_ENABLED（默认 true）：关掉后账密登录禁用，必须配 SAML 单点登录（5.7），一般自托管保持默认。

5.4 存储类：STORAGE_DRIVER 与内容迁移

STORAGE_DRIVER 控制笔记附件内容（图片、PDF 等二进制）的存放位置，官方默认 Type=Database（存数据库）。支持三种类型（官方 README）：

实测切换：设置 STORAGE_DRIVER=Type=Filesystem; Path=/home/joplin/.joplin-storage 后重启，日志确认生效：

App: Content driver: { type: 2, path: '/home/joplin/.joplin-storage' }

（对比默认形态 Content driver: { type: 1 }；type 2 即文件系统。）切回时把变量设回 Type=Database，日志恢复 Content driver: { type: 1 }、(fallback): null。

实测排障实录：连接串格式错误会直接导致服务崩溃循环。实测把值误写成 Type=DatabaseType=Filesystem; Path=...（拼接事故）后服务反复退出，错误原文：

Error: In connection string "Type=DatabaseType=Filesystem; Path=/home/joplin/.joplin-storage": Invalid type: "DatabaseType"
    at parseType (.../parseStorageConnectionString.ts:10:8)

同时实测：变量引用了但值为空串时，日志显示 Content driver: null 且服务不可用——要么删掉引用，要么给完整合法连接串。

存量内容迁移（官方 README 方案）：从数据库切文件系统时，配一个回退驱动实现平滑迁移：

STORAGE_DRIVER=Type=Filesystem; Path=/path/to/dir
STORAGE_DRIVER_FALLBACK=Type=Database; Mode=ReadAndWrite

Mode=ReadAndWrite（推荐起步）新旧双写便于回退；Mode=ReadAndClear 则随迁移逐步清空旧存储。历史不更新的内容可再用 storage import 命令批量搬迁（命令用法见 《Joplin 3.7.2 常用 CLI 命令与工具详解》服务端命令一节）。

5.5 邮件类：MAILER_*

MAILER_ENABLED=false（默认）时邮件功能整体关闭，表现为：用户忘记密码无法自助重置、管理员不能从后台发邀请邮件。启用示例（官方默认端口 465 + TLS）：

MAILER_ENABLED=true
MAILER_HOST=smtp.example.com
MAILER_PORT=465
MAILER_SECURITY=tls
MAILER_AUTH_USER=no-reply@example.com
MAILER_AUTH_PASSWORD=${MAILER_AUTH_PASSWORD}
MAILER_NOREPLY_EMAIL=no-reply@example.com
MAILER_NOREPLY_NAME=Joplin

MAILER_SECURITY 取值 none / tls / starttls（镜像内置定义枚举）。生效验证看启动日志 Mailer Config 块的 enabled: true。密码类值按敏感值规范用 ${VAR} 占位并在部署环境实际注入，不落明文。

5.6 运维与安全类

• COOKIES_SECURE（默认 false）：对外提供 https 时置 true，给会话 Cookie 加 Secure 标记；纯 http 内网部署保持 false（置 true 会导致 http 下登录态异常）。
• ERROR_STACK_TRACES（默认 false）：排障期临时置 true，让 Web 错误页带堆栈；平时关闭避免泄露内部路径。
• LOG_LEVEL（默认 info）：debug 用于排障，生产保持 info。
• MAX_TIME_DRIFT（默认 2000 毫秒）与 NTP_SERVER（默认 pool.ntp.org:123）：服务端会校验时钟漂移，超过阈值拒绝写操作——官方注释说明这是防止多客户端因时钟偏差制造大量同步冲突（关联 issue #5738）。内网无法出网校时的场景，把 NTP_SERVER 指向内网 NTP 服务器，确实无 NTP 时 MAX_TIME_DRIFT=0 可关闭检查（放弃这层保护）。
• USER_DATA_AUTO_DELETE_ENABLED / USER_DATA_AUTO_DELETE_AFTER_DAYS（默认 false / 90 天）：用户注销后数据自动清理的等待期，默认不启用。
• EVENTS_AUTO_DELETE_ENABLED / EVENTS_AUTO_DELETE_AFTER_DAYS（默认 false / 30 天）：同步事件流水（changes/events 表）的自动清理，大容量长期运行建议开启控制库膨胀。
• MFA_ENABLED / MFA_ENCRYPTION_KEY（默认 0 / 空）：服务端 MFA 能力开关，密钥要求 32+ 字节 hex 字符串。
• IS_ADMIN_INSTANCE / INSTANCE_NAME（默认 true / 空）：横向扩展多实例时，仅一个实例置 true（跑后台任务：邮件处理、共享处理、会话清理等定时任务），其余实例置 false 并配不同 INSTANCE_NAME。

5.7 企业认证类：LDAP 与 SAML（速览）

两组企业级认证各自的开关与参数族（默认全部关闭）：

• LDAP（两组，LDAP_1_ / LDAP_2_）**：LDAP_1_ENABLED、LDAP_1_HOST（格式 ldaps://server:port）、LDAP_1_BASE_DN、LDAP_1_BIND_DN、LDAP_1_BIND_PW、LDAP_1_MAIL_ATTRIBUTE（默认 mail）、LDAP_1_FULLNAME_ATTRIBUTE（默认 displayName）、LDAP_1_TLS_CA_FILE（自签证书场景）、LDAP_1_USER_AUTO_CREATION（默认 true，登录即建号）。
• SAML：SAML_ENABLED、SAML_IDP_CONFIG_FILE（IdP 元数据 XML）、SAML_SP_CONFIG_FILE（SP 元数据 XML）、SAML_ORGANIZATION_DISPLAY_NAME（登录页组织名）。官方注释要求 IdP 必须为每个用户提供 email 与 displayName 两个属性。

💡 技术拓展：LDAP 与 SAML 是两类企业身份对接协议——LDAP 目录协议实时查询校验口令（绑定认证），适合内网目录直连；SAML 基于 XML 断言的联邦单点登录，适合已有 IdP（Okta、ADFS、Keycloak）统一入口的场景。Joplin Server 两者都支持且可与本地账密（LOCAL_AUTH_ENABLED）组合，按已有基础设施选择即可。本文自托管场景保持默认本地认证。

5.8 客户端配置键（终端 CLI 实测）

客户端常用配置键（joplin config <键> [值] 读写，实测于 CLI 3.7.1）：

💡 技术拓展：同步目标编号是「客户端 → 存储后端」的适配器选择。Joplin Server（9）与 WebDAV（6）的差别在冲突处理与服务端能力——Server 走事务化同步 API 且支持共享/E2EE 配合，WebDAV 是纯文件级同步；多设备团队选 9，复用已有网盘选 6。配置方法与同步实测见 《Joplin 3.7.2 Docker Compose 部署指南》第九章。

api.port 与 joplin server start 子命令相关（CLI 内置的本机 API 服务，实测默认端口 41184），命令细节见命令详解篇。客户端配置文件 settings.json 位于配置目录（Linux 为 ~/.config/joplin/），是 joplin config 的持久化载体，手工编辑前须完全退出客户端。

六、生产配置模板

适用场景：50 人以内团队、8GB 内存 / 100GB 磁盘服务器、对外提供 https 反向代理、PostgreSQL 同机 compose 部署。模板给出全部建议值并附理由，未列出的变量保持官方默认：

# ── 服务地址 ──────────────────────────────
# 对外 https 域名；反代终止 TLS，服务本体仍在 22300
APP_BASE_URL=https://joplin.example.com
APP_PORT=22300
# https 部署必须，会话 Cookie 加 Secure
COOKIES_SECURE=true

# ── 数据库（生产必用 PostgreSQL）──────────
DB_CLIENT=pg
POSTGRES_HOST=db
POSTGRES_PORT=5432
POSTGRES_USER=joplin
POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
POSTGRES_DATABASE=joplin
# 默认 10 即官方推荐小池；仅当出现连接等待告警再调大
DB_MAX_CONNECTIONS=10
# 慢查询观察（排障期开启，平时 false）
DB_SLOW_QUERY_LOG_ENABLED=false

# ── 账号 ────────────────────────────────
# 首次启动前必须设强口令（只在初始化时生效）
DEFAULT_ADMIN_PASSWORD=${DEFAULT_ADMIN_PASSWORD}
# 团队统一由管理员建号则关闭自助注册
SIGNUP_ENABLED=false

# ── 邮件（忘记密码/邀请）────────────────
MAILER_ENABLED=true
MAILER_HOST=smtp.example.com
MAILER_PORT=465
MAILER_SECURITY=tls
MAILER_AUTH_USER=no-reply@example.com
MAILER_AUTH_PASSWORD=${MAILER_AUTH_PASSWORD}
MAILER_NOREPLY_EMAIL=no-reply@example.com
MAILER_NOREPLY_NAME=Joplin

# ── 数据治理 ────────────────────────────
# 长期运行开启同步事件清理，控制库体积
EVENTS_AUTO_DELETE_ENABLED=true
EVENTS_AUTO_DELETE_AFTER_DAYS=30

# ── 日志 ────────────────────────────────
LOG_LEVEL=info

模板要点：附件内容 50 人以内默认数据库存储即可（备份简单），附件量超过数十 GB 再按 5.4 切文件系统；${POSTGRES_PASSWORD} 等敏感值在部署环境的 .env/密管中实际注入。若为多实例横向扩展，追加 IS_ADMIN_INSTANCE=false + INSTANCE_NAME（仅一个实例除外）。

七、常见问题

Q1：改了 .env 为什么服务行为没变？ 最常见原因是 compose 的 environment: 列表没有引用该变量——变量只存在于 .env 不会自动进容器。用 docker exec <server 容器> printenv | grep <变量名> 核实注入情况，补引用后 docker compose up -d。

Q2：DEFAULT_ADMIN_PASSWORD 改了却不生效？ 该变量只在数据库首次初始化时创建管理员生效，之后改它不影响既有账号。改管理员密码走 Web 界面；全新初始化需清空数据库目录（会删数据，仅限测试环境）。

Q3：服务启动反复崩溃，日志报 Invalid type: "DatabaseType"？ STORAGE_DRIVER 连接串格式错误（本文 5.4 实测实录）。合法格式为 Type=Database、Type=Filesystem; Path=<绝对路径>，分号分隔、键值等号相连；修正后重启即可。同理，变量传了空值会出现 Content driver: null，要么删掉引用要么给合法值。

Q4：/api/ping 返回 Invalid origin？ 访问地址与 APP_BASE_URL 不一致被拒（5.1 实测）。统一按 APP_BASE_URL 形态访问；需要换地址先改 APP_BASE_URL 再重启。

Q5：注册接口返回 422？ signup 内置密码强度校验（zxcvbn），弱口令被拒（5.3 实测）。换强口令，或改由管理员建号。

Q6：SQLite 和 PostgreSQL 怎么选？ 试用/单人用 SQLite 最省事（不配 DB_CLIENT 即默认）；多用户生产选 PostgreSQL（官方 README 建议），切换需要重新初始化（两库数据结构独立，不做在线迁移）。

八、参考链接

• Joplin Server 官方安装与配置 README：https://github.com/laurent22/joplin/blob/dev/packages/server/README.md
• 官方 .env 样例：https://raw.githubusercontent.com/laurent22/joplin/dev/.env-sample
• Joplin Server 镜像：https://hub.docker.com/r/joplin/server
• 站内姊妹篇：《Joplin 介绍与选型指南》、《Joplin 3.7.2 Docker Compose 部署指南》、《Joplin 3.7.2 常用 CLI 命令与工具详解》