Apache Sling 安装指南

目标：在真实 Ubuntu 22.04 服务器上从零安装 Apache Sling（基于 JCR 与 OSGi 的 Web 框架），覆盖两套官方运行形态（launchpad standalone jar 与 Sling Starter 14 + Feature Launcher）、Java 版本适配、启动验证、REST 内容写读、管理密码修改与 systemd 托管。以下命令与回显均在 Ubuntu 22.04.5 环境逐步实测。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS（x86_64）
Java：OpenJDK 1.8.0_504（openjdk-8-jre-headless，方案 A 使用）；OpenJDK 17.0.20.1（openjdk-17-jre-headless，方案 B 使用）
Apache Sling：9（org.apache.sling.launchpad-9.jar，102,350,955 字节，方案 A）；Sling Starter 14（org.apache.sling.starter-14-oak_tar_far.far，114,132,675 字节，方案 B）
安装目录：/opt/sling-lp9（方案 A）；/opt/sling-starter（方案 B）
sling home：/opt/sling-lp9/sling（方案 A，默认在启动目录下创建 sling 子目录）
默认端口：8080
运行用户：root
默认管理账号：admin，首次默认口令 admin（建议按 4.7 节改为强口令）

💡 说明：Sling 即 "Servlet + JCR" 的组合词，应用以 OSGi bundle 形式运行在内嵌的 Apache Felix 框架中，内容存储默认使用 Jackrabbit Oak（segment 存储）。

二、前置条件

一台 Ubuntu 22.04 服务器，root 权限。
网络可访问 Apache 发行站（archive.apache.org 或 dlcdn.apache.org）与 Maven Central（方案 B 首次启动需联网下载依赖）。
安装基础工具：curl、wget、unzip、procps（含 ps）、iproute2（含 ss）、net-tools。

apt-get update -qq
DEBIAN_FRONTEND=noninteractive apt-get install -y curl wget unzip procps iproute2 net-tools

⚠️ Java 版本是 Sling 安装成败的关键：经典 launchpad standalone jar（Sling 9）实测必须 Java 8，在 Java 11 上核心 bundle 无法解析、HTTP 端口不会监听（见「常见问题」Q1）；Sling Starter 14 实测必须 Java 17，在 Java 11 上 Jetty 12 bundle 解析失败。两套方案的 JDK 要求互不兼容，请按所选方案安装对应 JDK。

三、版本选型说明

方案	发行物	Sling 版本	Java 要求	获取渠道	特点
A：launchpad standalone jar	`org.apache.sling.launchpad-9.jar`	Sling 9	Java 8	`archive.apache.org/dist/sling/`	单 jar 自包含全部 bundle，离线可启动，经典运行形态
B：Starter + Feature Launcher	`org.apache.sling.starter-14-oak_tar_far.far` + `org.apache.sling.feature.launcher-1.3.4.zip`	Sling Starter 14	Java 17	`dlcdn.apache.org/sling/` 与 Maven Central	官方当前推荐形态，bundle 首次启动时联网解析

版本选型实测依据（重要）：

dlcdn.apache.org/sling/ 目录下 org.apache.sling.starter-14.jar 仅 10,740 字节，内部只有 META-INF 元数据（unzip -l 共 10 个文件，无任何 class），不可直接运行；官方 downloads.cgi 为 Starter 14 列出的可运行形态是 FAR 文件 + Feature Launcher。
经典 launchpad standalone jar 在官方归档保留 org.apache.sling.launchpad-6-standalone.jar、-7-standalone.jar、-8.jar、-9.jar 四个；Maven Central 中 org.apache.sling.launchpad 只有 6/7/8/9 版本。
Java 兼容矩阵（实测）：

运行形态	Java 8	Java 11	Java 17
launchpad-9.jar	可用（实测通过）	失败（slf4j.api 等要求 JavaSE ≤ 1.8）	未要求
starter-14 FAR	未要求	失败（jetty12 要求 JavaSE 17）	可用（实测通过）

四、方案 A：launchpad standalone jar 安装（Sling 9，Java 8）

4.1 安装 OpenJDK 8

DEBIAN_FRONTEND=noninteractive apt-get install -y openjdk-8-jre-headless
update-alternatives --set java /usr/lib/jvm/java-8-openjdk-amd64/jre/bin/java

验证版本回显：

# java -version
openjdk version "1.8.0_504"
OpenJDK Runtime Environment (build 1.8.0_504-8u504-ga-1ubuntu1~22.04.3-b01)
OpenJDK 64-Bit Server VM (build 25.504-b01, mixed mode)

4.2 下载 launchpad standalone jar

mkdir -p /opt/sling-lp9 && cd /opt/sling-lp9
curl -sL -o org.apache.sling.launchpad-9.jar \
  https://archive.apache.org/dist/sling/org.apache.sling.launchpad-9.jar
ls -l org.apache.sling.launchpad-9.jar
sha256sum org.apache.sling.launchpad-9.jar

真实回显：

-rw-r--r-- 1 root root 102350955 Oct 12 05:12 org.apache.sling.launchpad-9.jar
851b38b6ce988795cbc04ffada570e17cf23d3c17ddfa6ad004283f1f7f3b68d  org.apache.sling.launchpad-9.jar

💡 该 jar 自包含全部 OSGi bundle（约 98MB），首次启动不依赖外网；后续版本若在 archive.apache.org/dist/sling/ 找不到，可用 curl -s https://archive.apache.org/dist/sling/ | grep launchpad 查询现存文件名。

4.3 首次启动与启动日志确认

cd /opt/sling-lp9
nohup java -Xms256m -Xmx512m -jar org.apache.sling.launchpad-9.jar > boot.log 2>&1 &

启动日志关键行（head -20 boot.log）：

12.10.2026 05:13:34.406 *INFO * [main] Setting sling.home=sling (default)
12.10.2026 05:13:34.407 *INFO * [main] Starting Apache Sling in /opt/sling-lp9/sling
12.10.2026 05:13:34.421 *INFO * [main] Installing new launcher: jar:file:/opt/sling-lp9/org.apache.sling.launchpad-9.jar!/resources/org.apache.sling.launchpad.base.jar, 5.6.4.2_6_18 (org.apache.sling.launchpad.base.jar.1791782014421)
12.10.2026 05:13:34.433 *INFO * [main] Setting sling.launchpad=/opt/sling-lp9/sling
12.10.2026 05:13:34.441 *INFO * [main] HTTP server port: 8080

OsgiInstaller 安装配置的关键行（grep 节选）：

12.10.2026 05:13:35.417 *INFO* [OsgiInstallerImpl] org.apache.sling.audit.osgi.installer Installed configuration org.apache.sling.commons.log.LogManager.factory.config.4a94fcd5-2d6a-4758-9632-741ad612da0e from resource TaskResource(url=launchpad:resources/config/org.apache.sling.commons.log.LogManager.factory.config-access.log.config, entity=config:org.apache.sling.commons.log.LogManager.factory.config.access.log, state=INSTALL, attributes=[org.apache.sling.installer.api.tasks.ResourceTransformer=:28:, service.factoryPid=org.apache.sling.commons.log.LogManager.factory.config, service.pid=access.log], digest=d0b046907e86658768af8c21c3213723)
12.10.2026 05:13:35.421 *INFO* [OsgiInstallerImpl] org.apache.sling.audit.osgi.installer Installed configuration org.apache.sling.engine.impl.log.RequestLogger from resource TaskResource(url=launchpad:resources/config/org.apache.sling.engine.impl.log.RequestLogger.config, entity=config:org.apache.sling.engine.impl.log.RequestLogger, state=INSTALL, attributes=[org.apache.sling.installer.api.tasks.ResourceTransformer=:28:, service.pid=org.apache.sling.engine.impl.log.RequestLogger], digest=a475207c9e345f2a0e987500d3df7fc4)

启动完成标志行：

12.10.2026 05:13:35.321 *INFO * [main] Startup completed

💡 首次启动需完成 bundle 解压安装与 Oak 仓储初始化，约 20~40 秒；以日志出现 Startup completed 且端口监听为准。

4.4 监听端口与首页验证

# ss -tlnp | grep 8080
LISTEN 0      50                 *:8080            *:*    users:(("java",pid=4310,fd=205))

# curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8080/
302
# curl -sL http://localhost:8080/ | head -8
<html>
<!--
  Licensed to the Apache Software Foundation (ASF) under one
  or more contributor license agreements.  See the NOTICE file
  distributed with this work for additional information
  regarding copyright ownership.  The ASF licenses this file
  to you under the Apache License, Version 2.0 (the

首页 302 跳转到欢迎页，返回 HTML 即代表 HTTP 服务正常。

4.5 内容写入与读取验证（SlingPostServlet）

默认凭据为 admin/admin，先创建一个内容节点：

# curl -s -i -u admin:admin -F"sling:resourceType=foo" -F"title=hello" http://localhost:8080/content/mynode | head -8
HTTP/1.1 201 Created
Date: Mon, 12 Oct 2026 05:14:58 GMT
X-Content-Type-Options: nosniff
X-Frame-Options: SAMEORIGIN
Location: /mynode
Content-Type: text/html;charset=utf-8
Transfer-Encoding: chunked

GET 该节点 JSON 与缩进格式回显：

# curl -s -u admin:admin http://localhost:8080/content/mynode.json
{"jcr:primaryType":"sling:OrderedFolder","jcr:createdBy":"admin","jcr:created":"Mon Oct 12 2026 05:14:58 GMT+0000","title":"hello","sling:resourceType":"foo"}

# curl -s -u admin:admin http://localhost:8080/content/mynode.tidy.json
{
  "jcr:primaryType": "sling:OrderedFolder",
  "jcr:createdBy": "admin",
  "jcr:created": "Mon Oct 12 2026 05:14:58 GMT+0000",
  "title": "hello",
  "sling:resourceType": "foo"
  }

4.6 OSGi 控制台检查 bundle 状态

# curl -s -u admin:admin "http://localhost:8080/system/console/bundles.json" | head -c 200
{"status":"Bundle information: 155 bundles in total - all 155 bundles active.","s":[155,151,4,0,0],"data":[{"id":0,"name":"System Bundle","fragment":false,"stateRaw":32,"state":"Active","version":"5.6.4","symbolicName":"org.apache.felix.framework",...

返回 155 bundles in total - all 155 bundles active 表示全部 bundle 处于 Active 状态。无凭据访问返回 401：

# curl -s -o /dev/null -w "noauth_console=%{http_code}\n" http://localhost:8080/system/console/bundles.json
noauth_console=401

4.7 修改默认管理密码

默认口令 admin 必须第一时间修改。通过内置用户管理端点改为强口令（本文后续示例统一使用 admin/q1w2e3r4）：

# curl -s -i -u admin:admin -X POST -F"oldPwd=admin" -F"newPwd=q1w2e3r4" -F"newPwdConfirm=q1w2e3r4" http://localhost:8080/system/userManager/user/admin.changePassword.html | head -3
HTTP/1.1 200 OK
Date: Mon, 12 Oct 2026 05:15:29 GMT
X-Content-Type-Options: nosniff

双向验证（旧口令拒绝、新口令放行）：

# curl -s -o /dev/null -w "%{http_code}\n" -u admin:admin http://localhost:8080/index.html
401
# curl -s -o /dev/null -w "%{http_code}\n" -u admin:q1w2e3r4 http://localhost:8080/index.html
200

⚠️ 端点路径必须是 user/admin.changePassword.html（user 与 admin 之间为斜杠）。写成 user.admin.changePassword.html 会返回 500（见「常见问题」Q2）。

五、方案 B：Sling Starter 14 + Feature Launcher 安装（最新版，Java 17）

5.1 安装 OpenJDK 17

DEBIAN_FRONTEND=noninteractive apt-get install -y openjdk-17-jre-headless

# /usr/lib/jvm/java-17-openjdk-amd64/bin/java -version 2>&1 | head -1
openjdk version "17.0.20.1" 2026-08-18

⚠️ Starter 14 实测不能在 Java 11 上运行：Jetty 12 bundle 声明要求 JavaSE 17，导致依赖链上的 sling.api、http 服务全部无法解析，8080 不监听（见「常见问题」Q3）。

5.2 下载 Feature Launcher 与 FAR

mkdir -p /opt/sling-starter && cd /opt/sling-starter
curl -sL -o launcher.zip \
  https://repo1.maven.org/maven2/org/apache/sling/org.apache.sling.feature.launcher/1.3.4/org.apache.sling.feature.launcher-1.3.4.zip
curl -sL -o org.apache.sling.starter-14-oak_tar_far.far \
  https://dlcdn.apache.org/sling/org.apache.sling.starter-14-oak_tar_far.far
unzip -q launcher.zip
ls -l launcher.zip org.apache.sling.starter-14-oak_tar_far.far

真实回显：

-rw-r--r-- 1 root root  2000554 Oct 12 05:22 launcher.zip
-rw-r--r-- 1 root root 114132675 Oct 12 05:21 org.apache.sling.starter-14-oak_tar_far.far

💡 dlcdn.apache.org 仅保留最新版本，官方 downloads.cgi 中指向 launcher-1.3.4.zip 的链接会 404，此时按上面的 Maven Central 路径下载即可；FAR 有 oak_tar（segment 文件存储）与 oak_mongo（MongoDB 存储）两种，单机选 oak_tar。

5.3 启动与验证

Feature Launcher 主类为 org.apache.sling.feature.launcher.impl.Main，JVM 参数经环境变量 JAVA_OPTS 注入：

cd /opt/sling-starter
JAVA_OPTS="-Xms256m -Xmx512m" nohup /usr/lib/jvm/java-17-openjdk-amd64/bin/java \
  -cp "org.apache.sling.feature.launcher-1.3.4/lib/*" \
  org.apache.sling.feature.launcher.impl.Main \
  -f org.apache.sling.starter-14-oak_tar_far.far > starter-boot.log 2>&1 &

验证（首启需联网解析并下载依赖，耗时数分钟）：

# grep -c "ERROR" starter-boot.log
0
# tail -1 starter-boot.log
[INFO] Framework started
# ss -tlnp | grep 8080
LISTEN 0      50                 *:8080            *:*    users:(("java",pid=6724,fd=258))
# curl -s -o /dev/null -w "home=%{http_code}\n" http://localhost:8080/
home=302

写读与 bundle 检查：

# curl -s -o /dev/null -w "%{http_code}\n" -u admin:admin -F"sling:resourceType=foo" -F"title=hello14" http://localhost:8080/content/starter14
201
# curl -s -u admin:admin http://localhost:8080/content/starter14.json
{"jcr:primaryType":"sling:OrderedFolder","jcr:createdBy":"admin","jcr:created":"Mon Oct 12 2026 05:25:27 GMT+0000","title":"hello14","sling:resourceType":"foo"}
# curl -s -u admin:admin "http://localhost:8080/system/console/bundles.json" | head -c 160
{"status":"Bundle information: 234 bundles in total - all 234 bundles active.","s":[234,233,1,0,0],...

运行数据落在启动目录的 launcher/ 下（实测共 187MB，含 cache、framework、install、logs、repository、resources）。密码修改方法与方案 A 相同（见 4.7 节）。

六、多方案对照与选择建议

维度	方案 A：launchpad-9.jar	方案 B：Starter 14 + Launcher
Sling 版本	9	Starter 14（官方最新）
Java	8	17
是否需联网	首启离线可用	首启必须联网解析依赖
运行目录	启动目录下 `sling/`	启动目录下 `launcher/`
bundle 数	155	234
官方维护状态	归档形态，不再更新	当前主线形态
适用场景	内网离线环境、教学与原型	生产与长期演进项目

选择建议：可联网的新装环境优先方案 B（官方主线、bundle 更全）；完全离线或需快速验证的存量环境用方案 A，单 jar 拷贝即用。

七、systemd 托管（开机自启）

7.1 编写服务单元

cat > /etc/systemd/system/sling.service <<EOF
[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
EOF

💡 WorkingDirectory 决定 sling home 位置（默认在启动目录下建 sling 子目录），务必指向安装目录；SuccessExitStatus=143 让 kill 信号触发的退出不判为失败。

7.2 启用与启动

# systemctl daemon-reload && systemctl enable sling
Created symlink /etc/systemd/system/multi-user.target.wants/sling.service → /etc/systemd/system/sling.service.
# systemctl start sling
# systemctl is-active sling
active

7.3 运行状态与 JVM 参数核验

# systemctl status sling --no-pager -n 3 | head -10
● sling.service - Apache Sling Launchpad 9
     Loaded: loaded (/etc/systemd/system/sling.service; enabled; vendor preset: enabled)
     Active: active (running) since Mon 2026-10-12 05:19:07 UTC; 25s ago
   Main PID: 5757 (java)
      Tasks: 126 (limit: 5753)
     Memory: 414.1M
        CPU: 25.922s
     CGroup: /system.slice/sling.service
             └─5757 /usr/bin/java -Xms256m -Xmx512m -jar /opt/sling-lp9/org.apache.sling.launchpad-9.jar

# jps -v | grep -i sling
5757 org.apache.sling.launchpad-9.jar -Xms256m -Xmx512m
# ss -tlnp | grep 8080
LISTEN 0      50                 *:8080            *:*    users:(("java",pid=5757,fd=249))
# curl -s -o /dev/null -w "index=%{http_code}\n" -u admin:q1w2e3r4 http://localhost:8080/index.html
index=200

jps 由 apt-get install -y openjdk-8-jdk-headless 提供。停启周期实测：systemctl stop sling 后 is-active 返回 inactive，再次 systemctl start sling 返回 active。

八、配置说明

8.1 sling home 目录结构

sling home（/opt/sling-lp9/sling）实测结构：

conf/         launchpad-timestamp.txt（启动时间戳）
config/       OSGi configadmin 配置文件（含 DynamicBindings.config）
felix/        OSGi bundle 缓存（bundle0、bundle1 等编号文件）
installer/    RegisteredResourceList.ser（安装器资源清单）
logs/         access.log、error.log、request.log
repository/   Oak 仓储（index、segmentstore），内容数据落盘处
startup/      启动状态目录
sling.properties  OSGi 框架属性覆盖文件（首次启动自动生成）

内容节点持久化实测：systemd 重启服务后再次 GET http://localhost:8080/content/mynode.json，仍返回原节点数据（"title":"hello"）。

8.2 JVM 堆内存（256-512MB）

启动命令与 systemd 单元中固定 -Xms256m -Xmx512m，生效核验见 7.3 节 jps -v 回显（-Xms256m -Xmx512m）。实测稳定运行时进程常驻内存约 414MB（systemd status 的 Memory 值）。

8.3 日志文件

三份日志都在 sling home 的 logs/ 下：

error.log：Sling 主日志（含 OSGi、Oak 索引、请求处理异常）；
request.log：请求进出明细（-> GET ... 与 <- 404 text/html 8ms 形式）；
access.log：访问日志（"DELETE /content/mynode HTTP/1.1" 204 形式）。

九、注意事项

首次启动慢是正常现象：OsgiInstaller 需逐个安装配置与 bundle，判断依据是 Startup completed 日志行加端口监听，不要凭几秒无输出就杀进程重启。
修改 sling.properties 与 JVM 参数后必须重启进程才生效。
升级 Sling 版本等于更换 jar 重启新 sling home，repository/ 不跨大版本自动迁移，切换前先备份 sling home。
管理口令务必离开默认值 admin；Web Console（/system/console）暴露框架级操作，生产环境应限制访问来源。

十、常见问题（FAQ）

Q1：Java 11 启动 launchpad-9.jar，日志大量 ERROR 且 8080 不监听？

真实报错节选：

12.10.2026 05:12:05.959 *ERROR* [FelixStartLevel] ERROR: Bundle '17' Error starting slinginstall:jcl-over-slf4j-1.7.21.jar (org.osgi.framework.BundleException: Unable to resolve jcl.over.slf4j [17](R 17.0): missing requirement [jcl.over.slf4j [17](R 17.0)] osgi.wiring.package; (&(osgi.wiring.package=org.slf4j.spi)(version>=1.7.21)) [caused by: Unable to resolve slf4j.api [4](R 4.0): missing requirement [slf4j.api [4](R 4.0)] osgi.ee; (&(osgi.ee=JavaSE)(version=1.5.0))] ...)

定位：slf4j.api 等 bundle 声明的 OSGi 运行环境上限为 JavaSE 1.8，Java 11 无法匹配。解决：改用 OpenJDK 8 并清理半安装数据（删除 sling home 的 sling 目录）后重新首启。

Q2：改密接口返回 500，报 UnsupportedOperationException？

错误回显正文：java.lang.UnsupportedOperationException: create 'userManager' at /system。定位：URL 写成了 user.admin.changePassword.html（点号连接），未被用户管理 Servlet 匹配，落到了通用 POST 处理器。解决：改为 user/admin.changePassword.html（斜杠连接）。

Q3：Starter 14 在 Java 11 上 Framework started 但无端口？

真实报错链：org.apache.felix.http.jetty12 [55] ... missing requirement ... osgi.ee; (&(osgi.ee=JavaSE)(version=17))，导致 sling.api 依赖链整体不解析。解决：Starter 14 换 OpenJDK 17 运行。

Q4：端口 8080 被其他进程占用？

用 ss -tlnp | grep 8080 先确认占用者；临时换端口可直接在启动命令追加 -p 8888（实测日志打印 HTTP server port: 8888 且 8888 监听），长期改法见《Apache Sling 配置参数详解》。

十一、卸载方式

systemctl stop sling                  # 停止服务
systemctl disable sling               # 取消开机自启
rm -f /etc/systemd/system/sling.service
systemctl daemon-reload
rm -rf /opt/sling-lp9                 # 删除安装目录与 sling home（含仓储数据，先确认备份）
apt-get remove -y openjdk-8-jre-headless   # 可选：卸载 JDK

方案 B 对应：结束 launcher 的 java 进程后删除 /opt/sling-starter 目录即可。

十二、参考链接

Apache Sling 官方下载页：https://sling.apache.org/downloads.cgi
Apache Sling 入门文档：https://sling.apache.org/documentation/getting-started.html
launchpad 归档发行目录：https://archive.apache.org/dist/sling/
最新发行目录：https://dlcdn.apache.org/sling/
Feature Launcher（Maven Central）：https://repo1.maven.org/maven2/org/apache/sling/org.apache.sling.feature.launcher/
Apache Sling 源码仓库：https://github.com/apache/sling-org-apache-sling-starter