Jelu 0.88.2 配置参数详解

目标：讲清 Jelu 0.88.2 的配置体系——jar 内置默认值、工作目录外置 application.yml、环境变量与命令行参数三层覆盖机制，逐项解读数据库、文件目录、端口、会话、日志、上传、认证、CORS、元数据提供方九类参数，并给出可落地的 512MB 内存家庭服务器生产模板；journalMode 切换、端口/环境变量覆盖等关键改动均在 Ubuntu 24.04.5 + OpenJDK 21.0.12.1 + Jelu v0.88.2 环境实测验证。安装部署见《《Ubuntu 24.04 安装 Jelu 0.88.2 指南》》，组件定位见《《Jelu 介绍与选型指南》》。

一、环境信息

本文实测与取证环境：

• 操作系统：Ubuntu 24.04.5 LTS（x86_64）；
• Java：OpenJDK 21.0.12.1（openjdk-21-jre-headless）；
• Jelu：v0.88.2（jar 直跑，systemd 单元 jelu.service，监听 11111）；
• 数据目录：/var/lib/jelu/（数据库 jelu.db、日志 jelu.log、外置配置 application.yml）；
• 示例管理员：admin / q1w2e3r4（演示账号）；
• 参数默认值来源：jar 内 BOOT-INF/classes/application.yml（0.88.2 资产解包实取）与官方配置文档（bayang.github.io/jelu-web/configuration/，查询日期 2026-10-28）；
• 改动验证手段：启动日志（DatabasePoolConfig、TomcatWebServer 行）、PRAGMA journal_mode、curl /api/v1/server-settings、ps -ef。

二、前置条件

本篇是配置专题：不需要重装系统，但改动配置涉及重启服务，请先确认：

1. Jelu 已按安装指南完成部署并能正常访问（systemctl is-active jelu 返回 active；尚未部署时先完成《《Ubuntu 24.04 安装 Jelu 0.88.2 指南》》第四章）；
2. 知道自己当前的配置加载位置：ls /var/lib/jelu/application.yml（本文示例环境存在该外置文件）；
3. 修改数据库类参数（路径、journalMode）前先备份数据库（安装指南 7.4 节的停机拷贝法）。

本篇所有参数改动示例均给出「改动 → 验证命令 → 实测回显」闭环，读者可对其中任意一项单独实验。

三、参数查看与修改方式

3.1 查看生效配置：三个信息源

信息源一：jar 内置默认值。 Jelu 把默认配置打在 jar 里，解包查看（只读操作，不影响运行）：

unzip -p /opt/jelu/jelu-0.88.2.jar BOOT-INF/classes/application.yml

实测输出（0.88.2 资产完整内置配置）：

jelu:
  database:
    path: ${user.home}/.jelu/database/
    journalMode: delete
  files:
    images: '${user.home}/.jelu/files/images/'
    imports: '${user.home}/.jelu/files/imports/'
  session:
    duration: 604800
server:
  port: 11111
spring:
  web:
    resources:
      add-mappings: false
  mvc:
    throw-exception-if-no-handler-found: true
  liquibase:
    enabled: true
    drop-first: false
    change-log: classpath:liquibase.xml
  datasource:
    url: jdbc:sqlite:${jelu.database.path}/jelu.db?journal_mode=${jelu.database.journal-mode:delete}&busy_timeout=10000&foreign_keys=on;
    username: jelu_user
    password: mypass1234
    driver-class-name: org.sqlite.JDBC
  exposed:
    generate-ddl: false
    show-sql: false
  servlet:
    multipart:
      enabled: true
      location: ${java.io.tmpdir}
      max-request-size: 10MB
      max-file-size: 10MB
logging:
  logback.rollingpolicy.max-history: 10
  file:
    name: ${jelu.database.path}/jelu.log
  level:
    io.github.bayang.jelu: DEBUG

这份内置文件本身就是参数权威清单：jelu.* 前缀是 Jelu 自有参数，spring.* 前缀继承 Spring Boot 标准参数；spring.datasource.url 里还能看到 busy_timeout=10000 与 foreign_keys=on 是写死在 JDBC URL 中的。

信息源二：外置覆盖文件。 工作目录下的 application.yml（本文环境为 /var/lib/jelu/application.yml）里写了什么，什么就覆盖了内置值：

cat /var/lib/jelu/application.yml

信息源三：启动日志。 两个关键行直接反映生效结果——连接池与日志模式行、监听端口行：

2026-10-28T11:09:10.041Z  INFO 6036 --- [main] i.g.b.jelu.config.DatabasePoolConfig     : Database pool size of 10 with journal mode WAL
2026-10-28T11:09:24.060Z  INFO 6106 --- [main] i.g.b.jelu.config.DatabasePoolConfig     : Database pool size of 1 with journal mode DELETE

2026-10-28T09:18:17.359Z  INFO 5204 --- [main] o.s.boot.tomcat.TomcatWebServer          : Tomcat started on port 11111 (http) with context path '/'

💡 技术拓展：Spring Boot 的配置覆盖优先级从高到低为——命令行参数（--key=value）→ 环境变量（KEY 大写下划线形式，即 relaxed binding）→ 工作目录/config/ 目录的 application.yml → jar 内 application.yml。Jelu 没有独立的「管理后台配置存储」，所有配置都走这三层文件与环境变量，改配置 = 改文件或环境变量 + 重启。

3.2 修改方式一：工作目录 application.yml（推荐）

把配置写在进程工作目录（systemd 单元 WorkingDirectory 指向的 /var/lib/jelu/）的 application.yml 中，systemctl restart jelu 后生效。安装指南 4.6 节已用它覆盖了数据库路径与封面目录；本篇 5.1 节的 wal 切换实验也走这条路。这是最推荐的方式：改动有文件可查、随 systemd 单元一起管理。

3.3 修改方式二：命令行参数（临时实验）

在 java -jar 命令后直接追加 --参数=值，优先级最高，适合临时验证。实测（独立库路径 + 换端口，避免与正式实例冲突）：

java -Djava.io.tmpdir=/var/lib/jelu/tmp -jar /opt/jelu/jelu-0.88.2.jar --server.port=11112 --jelu.database.path=/tmp/jelu-p12/

2026-10-28T11:01:24.674Z  INFO 5960 --- [main] o.s.boot.tomcat.TomcatWebServer          : Tomcat started on port 11112 (http) with context path '/'

命令行参数要写进 systemd 需改 ExecStart 行（见 3.4 的环境变量替代方案，后者更整洁）。

3.4 修改方式三：环境变量（systemd 注入推荐）

Jelu 官方配置文档给出了全部自有参数的环境变量形式（JELU_ 前缀，Spring relaxed binding 大写下划线）；systemd 单元中每行一个 Environment= 注入。实测两个环境变量（换端口 + 指定数据库目录）：

SERVER_PORT=11113 JELU_DATABASE_PATH=/tmp/jelu-env/ java -Djava.io.tmpdir=/var/lib/jelu/tmp -jar /opt/jelu/jelu-0.88.2.jar

2026-10-28T11:10:50.491Z  INFO 6173 --- [main] o.s.boot.tomcat.TomcatWebServer          : Tomcat started on port 11113 (http) with context path '/'

ls /tmp/jelu-env/

_0.cfe
_0.cfs
_0.si
jelu.db

jelu.db 落在 JELU_DATABASE_PATH 指定目录，端口监听 SERVER_PORT 指定值——环境变量绑定生效。systemd 中的等价写法（在 [Service] 段追加，每行一个变量）：

Environment=SERVER_PORT=11111
Environment=JELU_DATABASE_PATH=/var/lib/jelu/

四、参数总览

0.88.2 全部常用参数按域分组（默认值取自 3.1 节内置配置与官方配置文档，查询日期 2026-10-28）：

关键解读：Jelu 自有参数极少（两行就能数完数据库与文件目录），复杂度都在 spring.* 继承参数与 JVM 参数上。个人自托管真正需要动的只有 4 处：数据库路径、封面/导入目录（收集到数据盘）、calibre 路径（装了 calibre 才配）、JVM 内存。

五、核心参数分类详解

5.1 数据库三参数：path / journalMode / poolSize

jelu.database.path 决定 jelu.db 与 jelu.log 的落点，改它等于搬库（改完需重启，旧文件要手动迁移）。journalMode 是 0.88.0 引入的 SQLite 日志模式开关，poolSize 控制连接池——三者通过内置 JDBC URL 联动：journal_mode 参数注入 URL、池大小跟随模式（delete 模式写锁互斥读，池给 1 防自锁；wal 模式读写可并行，池给 Hikari 默认 10）。

wal 切换全流程实测——在外置配置的 jelu.database 段加一行 journalMode: wal：

jelu:
  database:
    path: /var/lib/jelu/
    journalMode: wal

sudo systemctl restart jelu 后验证日志与库文件：

grep 'pool size' /var/lib/jelu/jelu.log | tail -1
sqlite3 'file:/var/lib/jelu/jelu.db?mode=ro' 'PRAGMA journal_mode;'
ls -la /var/lib/jelu/jelu.db*

实测回显：

2026-10-28T11:09:10.041Z  INFO 6036 --- [main] i.g.b.jelu.config.DatabasePoolConfig     : Database pool size of 10 with journal mode WAL

wal

/var/lib/jelu/jelu.db 315392
/var/lib/jelu/jelu.db-shm 32768
/var/lib/jelu/jelu.db-wal 0

三重证据齐了：启动日志显示 pool size of 10 with journal mode WAL（池大小同步变 10）、库内 PRAGMA journal_mode 返回 wal、目录下出现 -wal/-shm 伴随文件。回退同理——删掉该行重启，实测回到 pool size of 1 with journal mode DELETE，PRAGMA journal_mode 返回 delete。

⚠️ 注意：内置 JDBC URL 总是显式设置 journal_mode（即使回 delete），因为 wal 标记持久化在库文件里，不显式重置会一直粘住。官方注释同时警告：wal 只能用在本地磁盘，NFS/SMB 网络盘上不安全；wal 模式下备份要连 jelu.db-wal、jelu.db-shm 一起拷贝（或先停服）。

5.2 文件目录：images / imports

两个目录分别收封面/作者图片与 CSV、ISBN 导入文件。默认都在 ${user.home}/.jelu/files/ 下；安装指南 4.6 节的示例把它们指到 /var/lib/jelu/files/。多用户场景下这两个目录是全实例共享的（封面按书共享）。目录不存在时 Jelu 启动会自动创建（启动日志实测行：Attempt to create non existing assets dir succeeded : true）。

5.3 端口：server.port 三种改法

三种方式在 3.2–3.4 节全部实测过：外置 yml 写 server.port: 11112（重启生效）、命令行 --server.port=11112（立即生效、临时）、环境变量 SERVER_PORT=11113（实测 Tomcat started on port 11113）。验证端口监听：

ss -tlnp | grep 11111

LISTEN 0      100                *:11111            *:*    users:(("java",pid=5300,fd=11))

改端口后记得同步放行防火墙与反代 upstream。

5.4 会话时长：jelu.session.duration

默认 604800 秒即 7 天，控制 Web UI 登录态保持时间。个人自托管建议保持默认；共享机器上可缩短（如 86400 一天）。修改后重启，登录态到期时间随之变化（已登录会话需重新登录一次）。

5.5 日志：位置、滚动与级别

三个要点：

• 位置联动：logging.file.name 默认取 ${jelu.database.path}/jelu.log——数据库路径挪到哪里，日志就跟到哪里（本环境即 /var/lib/jelu/jelu.log）；
• 滚动保留：logging.logback.rollingpolicy.max-history: 10，滚动后保留 10 份历史（jelu.log.1、jelu.log.2…）；
• 级别：io.github.bayang.jelu 默认 DEBUG（Jelu 自有代码包），排障信息全；长期运行可在外置配置提级降噪：

logging:
  level:
    io.github.bayang.jelu: INFO

除文件日志外，systemd 场景 journalctl -u jelu 同样能看到 stdout 输出，两个渠道内容一致。

5.6 上传限制：multipart 10MB 与临时目录陷阱

spring.servlet.multipart 默认单文件与整请求上限都是 10MB——传大封面或大 CSV 超限时前端报错、日志出现 MaxUploadSizeExceededException。location 默认取 ${java.io.tmpdir}：上传的分片先落到 Java 临时目录。这与安装指南 Q1 的 noexec 排障是同一个位置——-Djava.io.tmpdir 指到数据目录后，上传中转也一并落在那里，注意该目录要留足空间。

5.7 认证方式：LDAP / 反向代理认证 / OAuth2

内置数据库账号（JELU_DB 提供方）之外，0.88.2 官方支持三种外部认证（参数默认值见第四章总览表，均默认关闭）：

• LDAP：jelu.auth.ldap.enabled: true 接入企业 LDAP；没有 LDAP 服务器的环境保持 false（官方文档原话：没有 LDAP 就关掉）；
• 反向代理认证（进阶用法，官方标注 Danger）：反代完成认证后用请求头传递用户名（默认头 X-Authenticated-User），Jelu 按头里的用户名查库，存在即用、不存在自动建户；jelu.auth.proxy.adminName 指定的用户名会被授予管理员。官方同时警告：一旦有人绕过反代直连 Jelu 并伪造该请求头，即可冒充任意用户——因此启用代理认证时必须保证 Jelu 端口不对外暴露；
• OAuth2/OIDC：jelu.auth.oauth2AccountCreation（默认 false）控制首登自动建户，jelu.auth.oidcEmailVerification（默认 true）校验 email_verified 声明（官方提示仅在 Azure AD 这类不做邮箱校验的提供方下才关闭）。

家庭场景用内置账号即可；本章参数保持默认，认证链路实测（token 机制）见《Jelu 0.88.2 常用 CLI 命令与工具详解》。

5.8 CORS：jelu.cors.allowed-origins

默认 "*" 放行所有来源。只经同域反代访问时建议收紧为实际域名列表：

jelu:
  cors:
    allowed-origins:
      - "https://jelu.example.com"

改完重启生效；验证方法是从浏览器控制台或 curl -H "Origin: https://其他域名" 观察响应头中 Access-Control-Allow-Origin 的变化。

5.9 元数据提供方：calibre 与插件体系

默认只有 calibre 一个提供方（server-settings 实测回显："metadataPlugins":[{"name":"calibre","order":1000}]）。jelu.metadata.calibre.path 指向 fetch-ebook-metadata 二进制（安装指南 2.4 节安装后为 /usr/bin/fetch-ebook-metadata）。

官方配置文档给出的完整插件配置模板（查询日期 2026-10-28）：

jelu:
  metadata:
    calibre:
      path: /usr/bin/fetch-ebook-metadata
      order: 50000
  metadataProviders:
    - is-enabled: true
      apiKey: ""
      order: -100000
      name: "jelu-debug"
    - is-enabled: true
      apiKey: "${GOOGLE_BOOKS_API_KEY}"
      order: -10
      name: "google"
    - name: "inventaireio"
      is-enabled: true
      order: 200000
      config: "zh"
    - name: "databazeknih"
      is-enabled: true
      order: 200001

逐项说明：

• order 决定调用顺序：数值小的先被调用。未配置时 calibre 默认 order 1000，其余插件默认 -1000；
• jelu-debug：不做任何抓取，只把入参打进日志（排障用，order -100000）；
• google：Google Books API 提供方，必须自备 API Key 且仅支持 ISBN 检索；apiKey 是系统级密钥，用 ${GOOGLE_BOOKS_API_KEY} 占位并通过 systemd Environment=GOOGLE_BOOKS_API_KEY=… 注入，禁止明文写入配置文件入库；
• inventaireio：inventaire.io 开放书目数据，config 指定期望语言（2–3 位 ISO 码，如 zh/fr/en，无匹配时回退英文）；
• databazeknih：捷克语书库提供方，按需启用。

插件名必须与官方模板完全一致（google/inventaireio/databazeknih/jelu-debug），配置后重启，/api/v1/server-settings 的 metadataPlugins 数组会出现新提供方及其 order。

5.10 JVM 参数：堆内存与临时目录

JVM 参数不走 application.yml，写在 systemd ExecStart 行（安装指南 4.7 节）。生效验证：

ps -ef | grep '[j]ava'

jelu       5300       1  1 09:19 ?        00:00:22 /usr/bin/java -Xms256m -Xmx512m -Djava.io.tmpdir=/var/lib/jelu/tmp -jar /opt/jelu/jelu-0.88.2.jar

• -Xms256m -Xmx512m：初始/最大堆 256–512MB。实测该堆下服务常驻内存 477.2M（systemctl status jelu 的 Memory: 行），1GB 内存机器可跑；
• -Djava.io.tmpdir=/var/lib/jelu/tmp：原生库解压与上传中转目录，规避 noexec 挂载问题（安装指南 Q1 排障实录）。

调整后 sudo systemctl daemon-reload + sudo systemctl restart jelu，再跑一遍 ps -ef 确认新参数出现。

六、生产配置模板

适用场景：1–5 人家庭/个人服务器，1GB 内存、本地磁盘、nginx 同域反代、已装 calibre。外置 /var/lib/jelu/application.yml 全文：

jelu:
  database:
    path: /var/lib/jelu/
    journalMode: wal
  files:
    images: /var/lib/jelu/files/images/
    imports: /var/lib/jelu/files/imports/
  metadata:
    calibre:
      path: /usr/bin/fetch-ebook-metadata
  cors:
    allowed-origins:
      - "https://jelu.example.com"

server:
  port: 11111

logging:
  level:
    io.github.bayang.jelu: INFO

配套 systemd 单元 [Service] 段（与安装指南 4.7 节一致）：

[Service]
Type=simple
User=jelu
Group=jelu
WorkingDirectory=/var/lib/jelu
Environment=GOOGLE_BOOKS_API_KEY=${GOOGLE_BOOKS_API_KEY}
ExecStart=/usr/bin/java -Xms256m -Xmx512m -Djava.io.tmpdir=/var/lib/jelu/tmp -jar /opt/jelu/jelu-0.88.2.jar
Restart=on-failure
RestartSec=5

逐项解读：

• journalMode: wal：本地磁盘多读者场景（浏览书架是高频读）切换 wal，实测池自动扩到 10、读不再被写阻塞；数据落 NFS/SMB 时必须保持默认 delete；
• cors 收紧到实际域名：默认 * 在有反代域名后没有必要全开；
• 日志 INFO：DEBUG 级别下每次请求都打安全过滤链日志（本环境实测日志因此涨到 14 万字符量级），稳定运行后降噪；
• Environment=GOOGLE_BOOKS_API_KEY=${GOOGLE_BOOKS_API_KEY}：仅启用 google 插件时需要，密钥由单元文件引用宿主环境变量注入（systemctl edit jelu 或 drop-in 中定义 Environment= 前置变量），不落明文；
• 内存 256–512MB 堆不变：Jelu 功能再重也是单机 SQLite 场景，512MB 堆实测余量充足。

⚠️ 注意：本模板假设反代（nginx）与 Jelu 同机。若 Jelu 端口经反代认证对外（5.7 节代理认证），必须确认 11111 端口不对公网监听（ss -tlnp | grep 11111 中监听地址改为 127.0.0.1 或用防火墙封禁）。

七、常见问题（FAQ）

Q1：日志每次启动都报「The use of configuration keys that are no longer supported … spring.mvc.throw-exception-if-no-handler-found」

0.88.2 内置配置的该键在 Spring Boot 4 运行时已废弃，每次启动打印 PropertiesMigrationListener 报告。实测结论：该 ERROR 在成功启动的实例中持续出现、服务运行正常，属上游内置配置与新运行时的兼容性提示，可忽略；用户自写的外置配置里不要再添加这个键。

Q2：数据目录在 NFS/SMB 网络盘上，能开 wal 吗

不能。官方在配置注释中明确：wal 只在本地磁盘安全。网络盘保持默认 delete（实测该模式下池大小为 1、兼容性最好）。若确需 wal 的并发读又只有网络盘，把数据库放本地盘、仅图片目录放网络盘（两者路径独立可配）。

Q3：改了 application.yml 不生效

按顺序排查：① 改的是不是工作目录下的那份——systemd 场景即 WorkingDirectory（本环境 /var/lib/jelu/application.yml），放在 jar 旁边的 application.yml 在以 java -jar /opt/jelu/… 启动时不会被读取（工作目录才是加载基准，官方文档「put the application.yml file next to the jar」的说法默认 jar 所在目录同时是启动工作目录）；② 改完是否 sudo systemctl restart jelu；③ 参数名拼写——Spring relaxed binding 接受 journalMode/journal-mode/JELU_DATABASE_JOURNALMODE 三种形态，但拼错的键会静默忽略，用启动日志的 DatabasePoolConfig 行核对实际生效值。

Q4：spring.datasource.username/password 默认的 jelu_user/mypass1234 要改吗

官方配置文档把它们列为「Spring 继承配置」的示例项并给出默认值；Jelu 用 SQLite 本地文件库，这组凭据只是 JDBC 连接串占位，不构成网络暴露面（SQLite 无网络监听）。保持默认即可；真要改也只影响本进程对库文件的打开方式，不产生安全收益。

八、参考链接

• 官方配置文档（环境变量表/认证/元数据插件，查询日期 2026-10-28）：https://bayang.github.io/jelu-web/configuration/
• 内置默认配置源文件（main 分支 application.yml）：https://raw.githubusercontent.com/bayang/jelu/main/src/main/resources/application.yml
• 官方仓库：https://github.com/bayang/jelu
• v0.88.2 发布页（journalMode 特性自 v0.88.0 引入）：https://github.com/bayang/jelu/releases/tag/v0.88.2
• 站内延伸：《Jelu 介绍与选型指南》、《Ubuntu 24.04 安装 Jelu 0.88.2 指南》、《Jelu 0.88.2 常用 CLI 命令与工具详解》