Apache Sling 配置参数详解
详解 Apache Sling 9 的配置参数：启动命令行参数、sling.properties 框架属性、HTTP 端口、运行模式、存储目录、日志与 JVM 堆，逐项给出实测生效结果与生产配置模板，参数含义与默认值均来自真实环境验证
Apache Sling 配置参数详解
目标：系统梳理 Apache Sling 9（launchpad standalone jar 运行形态）的配置体系——启动命令行参数、sling home 中的 sling.properties 框架属性、HTTP 端口、运行模式、存储目录、日志与 JVM 参数，每项参数给出实测默认值与修改后的生效结果。全部回显在 Ubuntu 22.04.5 真实环境验证。
一、环境信息
- 操作系统：Ubuntu 22.04.5 LTS（x86_64）
- Java：OpenJDK 1.8.0_504（
openjdk-8-jre-headless+openjdk-8-jdk-headless，后者提供jps） - Apache Sling：9（
org.apache.sling.launchpad-9.jar） - 安装目录：
/opt/sling-lp9 - sling home：
/opt/sling-lp9/sling - 默认端口：8080；默认运行模式：
oak_tar - 管理账号：
admin，口令q1w2e3r4（由默认口令admin修改而来）
二、前置条件
- 已按《Apache Sling 安装指南》完成方案 A 安装，服务可正常访问（
curl http://localhost:8080/返回 302）。 - 已安装
openjdk-8-jdk-headless（提供jps）、iproute2（提供ss）、procps（提供ps）。 - 理解修改原则：命令行参数 → 启动命令追加；框架属性 → 编辑 sling home 的 sling.properties；两者均需重启进程生效。
三、参数查看与修改方式
| 方式 | 查看方法 | 修改方法 | 生效条件 |
|---|---|---|---|
| 启动命令行参数 | `ps -ef | grep [j]ava` 查看进程参数 | 启动命令追加（如 -p 8888、-Dsling.run.modes=author） |
| sling.properties | 直接查看 /opt/sling-lp9/sling/sling.properties | 编辑该文件（键值格式） | 重启进程 |
| 运行时状态 | Web Console 状态接口（curl 查询 JSON） | /system/console 控制台页面 | 即时 |
| JVM 参数 | jps -v | 启动命令/systemd 单元中改 JAVA 参数 | 重启进程 |
运行时状态查询（真实回显）：
# curl -s -u admin:q1w2e3r4 "http://localhost:8080/system/console/status-slingsettings.json" | head -c 600
[
"Apache Sling Settings",
"Sling ID = d1f2c3a5-5402-4132-aa87-616e157b768e",
"Sling Name = Instance d1f2c3a5-5402-4132-aa87-616e157b768e",
"Sling Description = Instance with id d1f2c3a5-5402-4132-aa87-616e157b768e and run modes [oak_tar]",
"Sling Home = /opt/sling-lp9/sling",
"Sling Home URL = file:/opt/sling-lp9/sling/",
"Run Modes = [oak_tar]"]
该接口可直接读出当前生效的 Sling ID、sling home 与运行模式，是核对配置是否生效的首选途径。
四、参数总览
| 参数 | 层级 | 默认值 | 作用 |
|---|---|---|---|
-p <port> | 启动命令行 | 8080 | 指定 HTTP 监听端口 |
-Dsling.run.modes=<modes> | 启动命令行 | oak_tar | 追加运行模式 |
org.osgi.service.http.port | sling.properties | 8080 | HTTP 端口（框架属性层） |
org.osgi.framework.storage | sling.properties | sling home 下 felix 子目录 | OSGi bundle 缓存目录 |
felix.cm.dir | sling.properties | sling home 下 config 子目录 | configadmin 配置存储目录 |
sling.installer.dir | sling.properties | sling home 下 installer 子目录 | OSGi 安装器资源目录 |
repository.home | sling.properties | sling home 下 repository 子目录 | Oak 仓储根目录 |
localIndexDir | sling.properties | sling home 下 repository/index | Lucene 本地索引目录 |
org.apache.sling.commons.log.file | sling.properties | sling home 下 logs/error.log | 主日志文件 |
org.apache.sling.commons.log.level | sling.properties | INFO | 日志级别 |
org.apache.sling.commons.log.file.size | sling.properties | '.'yyyy-MM-dd | 日志滚动策略（按天） |
org.apache.sling.commons.log.file.number | sling.properties | 5 | 保留的历史日志个数 |
org.osgi.framework.startlevel.beginning | sling.properties | 30 | 框架起始 Start Level |
felix.startlevel.bundle | sling.properties | 20 | bundle 默认 Start Level |
-Xms / -Xmx | JVM 参数 | 默认堆 | 本文统一 256m / 512m |
💡 sling.properties 首次启动自动生成，文件头注释为
#Overlay properties for configuration（实测 14,452 字节），即「覆盖层属性」：启动时先取内置默认，再用该文件覆盖，最后应用命令行系统属性。
五、核心参数分类详解
5.1 启动命令行参数
-p <port>：HTTP 监听端口。 实测 8888：
# cd /opt/sling-lp9 && nohup java -jar org.apache.sling.launchpad-9.jar -p 8888 > boot-p8888.log 2>&1 &
# grep -E "HTTP server port|Startup completed" boot-p8888.log
12.10.2026 05:16:41.008 *INFO * [main] HTTP server port: 8888
12.10.2026 05:16:44.699 *INFO * [main] Startup completed
# ss -tlnp | grep -E "8888|8080"
LISTEN 0 50 *:8888 *:* users:(("java",pid=4772,fd=185))
# curl -s -o /dev/null -w "curl_8888=%{http_code}\n" -u admin:q1w2e3r4 http://localhost:8888/index.html
curl_8888=200
结论：-p 优先级高于 sling.properties 中的端口值，适合临时换端口。
-Dsling.run.modes=<modes>：追加运行模式。 实测 author：
# cd /opt/sling-lp9 && nohup java -Dsling.run.modes=author -jar org.apache.sling.launchpad-9.jar > boot-rm.log 2>&1 &
# curl -s -u admin:q1w2e3r4 "http://localhost:8080/system/console/status-slingsettings.json" | grep "Run Modes"
"Run Modes = [oak_tar, author]"]
结论：该参数把 author 追加到默认 oak_tar 之后（不是替换），可用于按模式装配 bundle 与配置。
JVM 参数： 统一 -Xms256m -Xmx512m（详见 5.6 节）。
5.2 HTTP 端口参数（org.osgi.service.http.port）
sling.properties 中默认第 16 行为 org.osgi.service.http.port=8080。实测改为 8081（不带 -p 启动）：
# sed -i "s/^org.osgi.service.http.port=8080/org.osgi.service.http.port=8081/" /opt/sling-lp9/sling/sling.properties
# grep -n "^org.osgi.service.http.port" /opt/sling-lp9/sling/sling.properties
16:org.osgi.service.http.port=8081
# cd /opt/sling-lp9 && nohup java -jar org.apache.sling.launchpad-9.jar > boot-sp.log 2>&1 &
# grep -E "HTTP server port|Startup completed" boot-sp.log
12.10.2026 05:18:10.172 *INFO * [main] HTTP server port: 8081
12.10.2026 05:18:13.855 *INFO * [main] Startup completed
# ss -tlnp | grep -E "808[01]"
LISTEN 0 50 *:8081 *:* users:(("java",pid=5360,fd=18))
结论：不带 -p 时端口完全由该键决定；持久改端口优先改此文件（命令行 -p 只对当次启动有效）。恢复默认执行反向 sed 改回 8080 即可。
5.3 运行模式参数
| 键/参数 | 默认值 | 说明 |
|---|---|---|
| （当前生效模式） | oak_tar | status-slingsettings.json 的 Run Modes 实测输出 |
sling.run.mode.install.options | oak_tar,oak_mongo | sling.properties 中声明可选的存储运行模式（oak_tar 为文件段存储，oak_mongo 为 MongoDB 存储） |
-Dsling.run.modes=author | 无 | 命令行追加模式，实测结果 [oak_tar, author] |
💡 运行模式决定哪些按模式注册的 bundle 与配置参与装配。launchpad 内置 oak_tar 单机存储，绝大多数单机部署保持默认即可。
5.4 存储与目录参数
sling.properties 中以下键以 sling home 变量引用组织，解析后的实际位置如下（以本文 sling home 为 /opt/sling-lp9/sling 为例）：
| 键 | 解析后实际路径 | 目录实测内容 |
|---|---|---|
org.osgi.framework.storage | /opt/sling-lp9/sling/felix | bundle0、bundle1 等编号缓存文件（157 项） |
felix.cm.dir | /opt/sling-lp9/sling/config | configadmin 配置文件、DynamicBindings.config |
sling.installer.dir | /opt/sling-lp9/sling/installer | RegisteredResourceList.ser（85,852 字节资源清单） |
repository.home | /opt/sling-lp9/sling/repository | index、segmentstore（Oak 数据落盘处） |
localIndexDir | /opt/sling-lp9/sling/repository/index | Lucene 索引文件 |
⚠️ 迁移或备份实例时，以上目录整体随 sling home 拷贝即可；单独改这些键会把对应数据迁到新路径，改动前必须先停进程并搬移旧数据。
5.5 日志参数
| 键 | 默认值 | 说明 |
|---|---|---|
org.apache.sling.commons.log.file | sling home 下 logs/error.log | 主日志（实测 12.10.2026 05:25:50.088 *INFO* [async-index-update-async] org.apache.jackrabbit.oak... 格式） |
org.apache.sling.commons.log.level | INFO | 级别可选 ERROR/WARN/INFO/DEBUG |
org.apache.sling.commons.log.file.size | '.'yyyy-MM-dd | 按天滚动 |
org.apache.sling.commons.log.file.number | 5 | 保留历史份数 |
除主日志外，logs/ 下还有 request.log 与 access.log 两份请求日志（格式实测）：
# tail -2 /opt/sling-lp9/sling/logs/request.log
12/Oct/2026:05:25:53 +0000 [3] -> GET /content/mynode.json HTTP/1.1
12/Oct/2026:05:25:53 +0000 [3] <- 404 text/html 8ms
# tail -2 /opt/sling-lp9/sling/logs/access.log
127.0.0.1 - admin 12/Oct/2026:05:25:53 +0000 "DELETE /content/mynode HTTP/1.1" 204 - "-" "curl/7.81.0"
127.0.0.1 - admin 12/Oct/2026:05:25:53 +0000 "GET /content/mynode.json HTTP/1.1" 404 2537 "-" "curl/7.81.0"
排障时建议：改 level 为 DEBUG 仅临时使用，否则日志量增长明显。
5.6 JVM 参数（堆内存 256-512MB）
启动命令或 systemd 单元中固定：
java -Xms256m -Xmx512m -jar /opt/sling-lp9/org.apache.sling.launchpad-9.jar
生效核验（jps 由 openjdk-8-jdk-headless 提供）：
# jps -v | grep -i sling
5757 org.apache.sling.launchpad-9.jar -Xms256m -Xmx512m
# ps -ef | grep "[j]ava" | head -1
root 5757 1 0 05:19 ? 00:00:25 /usr/bin/java -Xms256m -Xmx512m -jar /opt/sling-lp9/org.apache.sling.launchpad-9.jar
实测该实例稳定运行常驻内存约 414MB（systemctl status sling 的 Memory 值），512MB 堆上限满足单机验证与中小流量场景。
5.7 框架与 Start Level 参数
| 键 | 默认值 | 说明 |
|---|---|---|
org.osgi.framework.startlevel.beginning | 30 | 框架启动到达的 Start Level |
felix.startlevel.bundle | 20 | bundle 安装后的默认 Start Level |
org.osgi.framework.bootdelegation | 含扩展委托包列表 | 允许 bundle 委托给 JVM 类加载器的包前缀（含 sling.bootdelegation.sun=sun.*,com.sun.* 等） |
obr.repository.url | http://sling.apache.org/obr/repository.xml | OSGi Bundle Repository 地址（离线环境可忽略） |
💡 Start Level 参数一般保持默认；只有做裁剪部署（延迟加载部分 bundle）时才需要调整。
六、生产配置模板
适用场景：8GB 内存、SSD 磁盘、单机中小型内容服务（日请求 10 万级以内）。
systemd 单元（/etc/systemd/system/sling.service）：
[Unit]
Description=Apache Sling Launchpad 9
After=network.target
[Service]
Type=simple
WorkingDirectory=/opt/sling-lp9
ExecStart=/usr/bin/java -Xms256m -Xmx512m -jar /opt/sling-lp9/org.apache.sling.launchpad-9.jar
Restart=on-failure
RestartSec=5
SuccessExitStatus=143
[Install]
WantedBy=multi-user.target
sling.properties 生产建议键值（编辑后重启生效）：
org.osgi.service.http.port=8080
org.apache.sling.commons.log.level=INFO
org.apache.sling.commons.log.file.size='.'yyyy-MM-dd
org.apache.sling.commons.log.file.number=10
💡 依据：512MB 堆实测常驻约 414MB，1GB 以上内存服务器即可承载；日志保留 10 份按天滚动约覆盖两周排障窗口；存储、索引目录保持 sling home 默认布局便于整目录备份。
七、常见问题（FAQ）
Q1：改了 sling.properties 不生效？
原因：该文件仅在进程启动时读取。解决：重启 Sling 进程（systemd 场景 systemctl restart sling），再经 status-slingsettings.json 或日志核对新值。
Q2：-p 与 sling.properties 的端口哪个生效？
实测：命令行 -p 优先生效（-p 8888 时 sling.properties 仍写 8080，监听为 8888）。两者都改且不一致时，以 -p 为准，排查时先看启动命令再查文件。
Q3：-Dsling.run.modes=author 后原有 oak_tar 模式丢失？
实测不丢失：结果为 [oak_tar, author]，命令行模式是追加而非替换；若需完全自定义集合，检查 sling.properties 中 sling.run.mode.install.options 与启动参数的组合。
Q4：日志文件涨到数 GB？
定位：level 为 DEBUG 或未配置滚动。解决：log.level 调回 INFO，确认 file.size 为按天滚动、file.number 控制份数（默认 5 份）。
Q5：sling.properties 被删了会怎样？
下次启动会重新生成默认内容（文件头注释 #Overlay properties for configuration），但其中的手工定制会丢失，建议定制后随 sling home 一并纳入备份。
八、参考链接
- Apache Sling 配置文档（The Sling Settings and Run Modes）：https://sling.apache.org/documentation/bundles/the-sling-settings-and-run-modes.html
- Apache Sling 日志配置：https://sling.apache.org/documentation/bundles/sling-commons-log.html
- Apache Sling 入门文档：https://sling.apache.org/documentation/getting-started.html
- launchpad 归档发行目录：https://archive.apache.org/dist/sling/