Apache Jena 配置参数详解

目标：集中讲解 Apache Jena Fuseki 6.2.0 的各类配置参数——启动命令行参数、config.ttl 数据集配置、log4j2.properties 日志配置、JVM 堆内存参数，并给出生产配置模板。所有参数默认值均来自本次实测环境的真实 help 输出与配置文件。

一、环境信息

Apache Jena Fuseki：6.2.0，目录 /usr/local/apache-jena-fuseki-6.2.0
启动脚本：/usr/local/apache-jena-fuseki-6.2.0/fuseki-server
日志配置：/usr/local/apache-jena-fuseki-6.2.0/log4j2.properties
运行目录（FUSEKI_BASE）：/usr/local/apache-jena-fuseki-6.2.0/run（含 databases/、configuration/、backups/、shiro.ini）
JDK：OpenJDK 21，JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64

二、前置条件

已完成 Jena 6.2.0 与 Fuseki 的解压部署（见《Ubuntu 22.04 安装 Apache Jena 6.2.0 指南》）；
JAVA_HOME 指向 JDK 21，FUSEKI_HOME 已导出；
配置修改后用 source /etc/profile.d/jena.sh 刷新环境。

三、参数查看与修改方式

命令行参数：运行 ./fuseki-server --help 查看全部启动参数；
数据集（service）配置：编辑 config.ttl 后重启（pkill -f fuseki-server 再启动）；
日志配置：编辑 log4j2.properties，并用环境变量 LOGGING 指向该文件；
JVM 参数：启动前设置环境变量 JVM_ARGS 覆盖（脚本第 97 行默认 -Xmx4G）。

查看命令行参数：

cd /usr/local/apache-jena-fuseki-6.2.0
./fuseki-server --help

回显（节选，实测）：

fuseki [--config=FILE|--mem|--loc=DIR|--file=FILE] [--port PORT] /DatasetPathName
      --admin                Enable server admin with user:password
      --adminRun             Directory for server configuration
      --config=FILE          Use a configuration file to determine the services
      --mem                  Create an in-memory, non-persistent dataset for the server
      --file=FILE            Create an in-memory dataset, initialised with the contents of the file
      --loc=DIR              Use an existing TDB database (or create if does not exist)
      --tdb2                 Use TDB2 for command line persistent datasets (default is TDB2)
      --update               Allow updates (via SPARQL Update)
      --port                 Listen on this port number
      --gzip=on|off          Enable GZip compression (HTTP Accept-Encoding)

四、参数总览

类别	配置载体	主要参数/键
启动参数	`fuseki-server` 命令行	`--config`、`--admin`、`--port`、`--mem`、`--loc`、`--update`
数据集	`config.ttl`（Turtle）	`fuseki:name`、`fuseki:endpoint`、`fuseki:operation`、`fuseki:dataset`、`tdb2:DatasetTDB2`、`tdb2:location`
日志	`log4j2.properties`	`rootLogger.level`、`logger.<name>.level`
JVM	环境变量 `JVM_ARGS`	`-Xms`、`-Xmx`、`-Xmn`

五、核心配置参数分类详解

5.1 启动命令行参数

以下参数通过 fuseki-server 启动脚本传入：

参数	默认值	说明
`--config=FILE`	无	使用配置文件（config.ttl）定义服务；与 `--update` 冲突
`--admin=user:pass`	admin 空口令体系	启用管理账号，如 `--admin=admin:q1w2e3r4`
`--port N`	3030	监听端口
`--mem`	无	创建内存非持久化数据集
`--loc=DIR`	无	使用/创建指定目录的 TDB 数据库
`--tdb2`	默认 TDB2	命令行持久化数据集用 TDB2 存储
`--update`	关	允许 SPARQL Update；与 `--config` 同用会报错

⚠️ 说明：--admin=admin:q1w2e3r4 中 q1w2e3r4 为本文演示密码。

5.2 config.ttl：数据集与服务配置

config.ttl 用 RDF/Turtle 描述一个（或多个）fuseki:Server 及其 fuseki:Service。核心键：

键	取值	说明
`rdf:type fuseki:Server`	布尔	声明节点为 Fuseki 服务器
`fuseki:services`	列表	列出服务器下所有服务（数据集）
`fuseki:name`	字符串	数据集路径名，如 `"hello"`（对外即 `/hello`）
`fuseki:endpoint`	对象	端点声明；`query` / `update` / `gsp-rw` 各自独立成一个对象
`fuseki:operation`	`fuseki:query` 等	端点操作类型
`fuseki:dataset`	对象	数据集实现
`tdb2:DatasetTDB2`	类型	TDB2 持久数据集类型（必须写此名）
`tdb2:location`	路径	TDB2 数据库目录

典型配置（挂载在 /hello 的 TDB2 数据集）：

@prefix fuseki: <http://jena.apache.org/fuseki#> .
@prefix rdf:     <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix rdfs:    <http://www.w3.org/2000/01/rdf-schema#> .
@prefix tdb2:    <http://jena.apache.org/2016/tdb#> .

[] rdf:type fuseki:Server ;
   fuseki:services ( <#service_hello> ) .

<#service_hello> rdf:type fuseki:Service ;
    rdfs:label "hello-dataset" ;
    fuseki:name "hello" ;
    fuseki:endpoint [ fuseki:operation fuseki:query ] ;
    fuseki:endpoint [ fuseki:operation fuseki:update ] ;
    fuseki:endpoint [ fuseki:operation fuseki:gsp-rw ] ;
    fuseki:dataset [ rdf:type tdb2:DatasetTDB2 ;
                     tdb2:location "/opt/data/jena/db/hello" ] .

⚠️ 三个「避坑」要点（实测踩坑沉淀）：

类型名是 tdb2:DatasetTDB2，写成 tdb2:TDB2Dataset 会报 NoSpecificTypeException；

query/update/gsp-rw 必须各自 fuseki:endpoint 独立对象；写进同一个空白节点对象用 ; 重复 fuseki:operation 会报 Multiple properties 'fuseki:operation'；

--update 与 --config 不可同用，更新权限由 config.ttl 的 update 端点控制。

5.3 JVM 堆内存参数

启动脚本 fuseki-server 第 97 行：

JVM_ARGS=${JVM_ARGS:--Xmx4G}

默认 -Xmx4G。生产环境将堆限制在 256–512 MB，通过环境变量覆盖：

export JVM_ARGS="-Xms256m -Xmx256m -Xmn128m"

参数含义表：

参数	作用
`-Xms256m`	初始堆大小 256 MB
`-Xmx256m`	最大堆大小 256 MB
`-Xmn128m`	新生代大小 128 MB

systemd 托管场景（Environment= 每行仅一个变量）：

[Service]
Environment=JVM_ARGS=-Xms256m -Xmx256m -Xmn128m

⚠️ 若进程开启了 -XX:+UseContainerSupport/AggressiveHeap，需用 jps -v 复核实际生效堆，见 5.5。

5.4 日志配置 log4j2.properties

Fuseki 默认日志基于 Log4j2，配置文件 log4j2.properties：

status = error
rootLogger.level                  = INFO
logger.jena.name  = org.apache.jena
logger.jena.level = INFO
logger.fuseki-server.name  = org.apache.jena.fuseki.Server
logger.fuseki-server.level = INFO
logger.jetty.name  = org.eclipse.jetty
logger.jetty.level = WARN
logger.shiro.name = org.apache.shiro
logger.shiro.level = WARN

全局级别由 rootLogger.level 控制（默认 INFO）；
各组件可单独设级别（如把 logger.jetty.level 调 WARN 抑制 Jetty 冗长日志）；
用环境变量 LOGGING 指定自定义文件形如 -Dlog4j.configurationFile=/opt/data/jena/custom-log4j2.properties。

5.5 生效验证 jps -v

jps -v | grep Fuseki

回显（确认 JVM 参数生效）：

6514 FusekiServerUICmd -Xms256m -Xmx256m -Xmn128m -Dlog4j.configurationFile=/usr/local/apache-jena-fuseki-6.2.0/log4j2.properties

六、生产配置模板

以下模板面向「16 GB 内存、NVMe SSD、SPARQL 读写型（OLTP）中等数据集」场景：

JVM 堆：-Xms512m -Xmx512m -Xmn256m（保守预留系统内存给 OS/Jetty）
Fuseki 启动：

export JVM_ARGS="-Xms512m -Xmx512m -Xmn256m"
cd /usr/local/apache-jena-fuseki-6.2.0
nohup ./fuseki-server --config=config.ttl --admin=admin:q1w2e3r4 --port 3030 \
    > /opt/data/jena/fuseki.log 2>&1 &

systemd 单元（/etc/systemd/system/fuseki.service）：

[Unit]
Description=Apache Jena Fuseki 6.2.0
After=network.target

[Service]
User=root
Environment=JVM_ARGS=-Xms512m -Xmx512m -Xmn256m
ExecStart=/usr/local/apache-jena-fuseki-6.2.0/fuseki-server --config=/usr/local/apache-jena-fuseki-6.2.0/config.ttl --admin=admin:q1w2e3r4 --port=3030
ExecStop=/usr/bin/pkill -f fuseki-server
Restart=on-failure

[Install]
WantedBy=multi-user.target

⚠️ 说明：systemd 托管方式需要运行 systemd 的 Linux 真机（如 Ubuntu 22.04 服务器默认即满足）。若宿主机内存紧张，改回 -Xms256m -Xmx256m -Xmn128m。启动时分别执行 systemctl enable fuseki 与 systemctl start fuseki（每行仅针对 fuseki 一个单元）。

七、常见问题（FAQ）

Q1：改 JVM 参数后没生效？ 答：确认启动前已 export JVM_ARGS="-Xms256m -Xmx256m -Xmn128m" 并用 jps -v 复核；若进程启用了 -XX:+AggressiveHeap/-XX:+UseContainerSupport，会按系统可用内存自适应，需在 JVM_ARGS 中显式覆盖。

Q2：--update 和 --config 一起用报错？ 答：Fuseki 不允许二者并用。用 config.ttl 中声明 fuseki:endpoint [ fuseki:operation fuseki:update ] 来开启更新。

Q3：config.ttl 报 Multiple properties 'fuseki:operation'？ 答：把三个操作拆成三个独立 fuseki:endpoint 对象，不要放在同一对象内。

Q4：日志太吵？ 答：调高对应组件的 level，例如把 logger.jetty.level 改为 WARN、logger.shiro.level 改为 WARN（默认已是 WARN）。

八、参考链接

Apache Jena Fuseki 配置文档：https://jena.apache.org/documentation/fuseki2/fuseki-configuration.html
Jena Fuseki 服务数据说明：https://jena.apache.org/documentation/fuseki2/
Log4j2 配置：https://logging.apache.org/log4j/2.x/configuration.html
JVM 选项：https://docs.oracle.com/en/java/javase/21/vm/mainoptions.html