Apache Jena Docker Compose 部署指南

目标：介绍如何用 Docker Compose 快速部署 Apache Jena Fuseki 6.2.0 SPARQL 服务器，覆盖镜像选型、docker-compose.yml 编写、数据持久化、常用环境变量、JVM 堆内存限制与日常运维命令，读者可在此基础上直接落地生产。

一、环境信息

目标软件：Apache Jena Fuseki 6.2.0（SPARQL 服务器）
交付形态：Docker 镜像 stain/jena-fuseki（社区维护的标准 Fuseki 镜像）
默认服务端口：3030
管理账号：admin / 密码 q1w2e3r4
数据持久化目录：./fuseki-data（映射到镜像内 /fuseki）
参考版本：Compose 规范 3.8，Docker Engine 20.10+ / Docker Compose v2

💡 说明：stain/jena-fuseki 是 Apache Jena 社区官方维护的 Fuseki Docker 镜像（GitHub: stain/jena-fuseki-docker），镜像内即包含 apache-jena-fuseki-6.2.0 及所需 JDK。

二、镜像选型说明

镜像	维护方	是否含 JDK	特点
`stain/jena-fuseki:6.2.0`	Apache Jena 社区	含	官方推荐，支持环境变量配置数据集与 JVM 参数
`stain/jena-fuseki:latest`	Apache Jena 社区	含	跟随最新版
自行构建	用户	需自装	基于官方 tar.gz 制作，灵活但维护成本高

💡 建议：生产环境固定 stain/jena-fuseki 的具体版本标签（如 6.2.0），避免 latest 浮现不兼容变更。

三、前置条件

已安装 Docker Engine 与 Docker Compose（本文使用 Compose v2 语法）；
服务器可访问镜像仓库（或已配置镜像加速器）；
预留数据目录与端口 3030。

docker --version
docker compose version

回显（示例）：

Docker version 29.8.1, build 4a63305
Docker Compose version v5.5.1

四、部署步骤

4.1 编写 docker-compose.yml

在部署目录（如 /opt/data/jena-compose）创建 docker-compose.yml：

version: "3.8"

services:
  fuseki:
    image: stain/jena-fuseki:6.2.0
    container_name: jena-fuseki
    ports:
      - "3030:3030"
    environment:
      # JVM 堆内存限制（覆盖镜像默认的 4G）
      JVM_ARGS: "-Xms256m -Xmx256m -Xmn128m"
      # Fuseki 管理账号密码
      ADMIN_PASSWORD: "q1w2e3r4"
      # 允许 SPARQL Update
      ENABLE_UPDATE: "true"
      # 首次启动自动创建一个名为 mydataset 的 TDB2 数据集
      FUSEKI_DATASET_1: "mydataset|tdb2"
    volumes:
      # 数据与配置持久化到宿主机
      - ./fuseki-data:/fuseki
    restart: unless-stopped

4.2 启动服务

cd /opt/data/jena-compose
docker compose up -d

预期输出（docker compose up 首次会拉取镜像并创建容器）：

[+] Running 2/2
 ✔ Network jena-compose_default   Created
 ✔ Container jena-fuseki          Started

4.3 查看运行状态

docker compose ps

预期输出（fuseki 处于 Up 状态）：

NAME          IMAGE                    SERVICE   STATUS       PORTS
jena-fuseki   stain/jena-fuseki:6.2.0   fuseki    Up           3030->3030/tcp

4.4 验证服务与 SPARQL 查询

curl -s http://127.0.0.1:3030/$/ping

预期输出（心跳时间戳）：2026-10-11T11:17:01.823+00:00

curl -s -u admin:q1w2e3r4 "http://127.0.0.1:3030/mydataset/query" \
  --data-urlencode "query=SELECT (COUNT(*) AS ?c) WHERE { ?s ?p ?o }" \
  -H "Accept: application/sparql-results+json"

预期输出：

{ "head": { "vars": [ "c" ] } , "results": { "bindings": [ { "c": { "datatype": "http://www.w3.org/2001/XMLSchema#integer" , "type": "literal" , "value": "0" } } ] } }

💡 说明：FUSEKI_DATASET_1 创建的数据集会暴露标准端点 /<name>/query、/<name>/update、/<name>/data。

五、数据持久化说明

volumes 把镜像内 /fuseki（含 run/databases、run/configuration、run/backups）映射到宿主机 ./fuseki-data：

镜像挂载基目录：/fuseki
TDB2 数据集目录：/fuseki/databases/<name>/
配置管理目录：/fuseki/configuration/

⚠️ 注意：删除容器不会删除宿主机 ./fuseki-data 内的数据；重启用 docker compose up -d 会挂回同一目录，数据完整保留。

六、常用环境变量表

环境变量	默认值	说明
`ADMIN_PASSWORD`	无	Fuseki 管理账号密码（默认账号 `admin`）
`JVM_ARGS`	`-Xmx4G`	JVM 参数；生产建议设为 `-Xms256m -Xmx256m -Xmn128m`
`ENABLE_UPDATE`	`false`	是否启用 SPARQL Update
`FUSEKI_DATASET_1`	无	自动创建的数据集，格式 `名称\|存储类型`；类型可选 `tdb`、`tdb2`、`mem`
`FUSEKI_DATASET_2`	无	可继续声明多个数据集
`FUSEKI_BASE`	`/fuseki`	Fuseki 运行目录

七、常用配置参数说明（command）

如需完全自定义 Fuseki 服务（如同时加载自定义 config.ttl），可在 command 覆盖启动参数：

services:
  fuseki:
    image: stain/jena-fuseki:6.2.0
    command: ["--config=/fuseki/config.ttl", "--admin=admin:q1w2e3r4", "--port=3030"]

--config=/fuseki/config.ttl：使用挂载进容器的自定义配置（见「八、配置文件持久化」）；
--port=3030：监听端口；
--update：允许 SPARQL Update（与 --config 同时使用可能冲突，改用 ENABLE_UPDATE=true 更稳妥）。

八、配置文件持久化（conf 挂载）

将宿主机 ./conf/config.ttl 挂载进容器，即可用自定义 Fuseki 配置定义数据集与服务：

services:
  fuseki:
    image: stain/jena-fuseki:6.2.0
    volumes:
      - ./conf:/fuseki/conf:ro
      - ./fuseki-data:/fuseki
    command: ["--config=/fuseki/conf/config.ttl", "--admin=admin:q1w2e3r4", "--port=3030"]

宿主机 ./conf/config.ttl 示例（定义挂载在 /hello 的 TDB2 数据集）：

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

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

<#service_hello> rdf:type fuseki:Service ;
    fuseki:name "hello" ;
    fuseki:endpoint [ fuseki:operation fuseki:query ] ;
    fuseki:endpoint [ fuseki:operation fuseki:update ] ;
    fuseki:dataset [ rdf:type tdb2:DatasetTDB2 ;
                     tdb2:location "/fuseki/hello" ] .

⚠️ 说明：使用 --config 时，非 Compose 篇《Ubuntu 22.04 安装 Apache Jena 6.2.0 指南》中的 tdb2:DatasetTDB2 类型名与独立 fuseki:endpoint 语法同样适用。

九、等价 docker run 运行方式

不使用 Compose，也可用等价 docker run：

docker run -d --name jena-fuseki \
  -p 3030:3030 \
  -e JVM_ARGS="-Xms256m -Xmx256m -Xmn128m" \
  -e ADMIN_PASSWORD="q1w2e3r4" \
  -e ENABLE_UPDATE="true" \
  -e FUSEKI_DATASET_1="mydataset|tdb2" \
  -v /opt/data/jena-compose/fuseki-data:/fuseki \
  --restart unless-stopped \
  stain/jena-fuseki:6.2.0

十、常用运维命令

# 查看日志
docker compose logs -f fuseki

# 进入容器 shell
docker compose exec fuseki sh

# 查看容器内 JVM 参数（验证堆限制是否生效）
docker compose exec fuseki jps -v

# 重建并后台运行（改配置后）
docker compose up -d --build

# 停止（保留数据与容器）
docker compose stop

# 停止并移除容器（保留宿主机数据）
docker compose down

# 完全清除（含网络，不含 mount 卷数据）
docker compose down -v

⚠️ 注意：jps 需要镜像内存在 JDK；stain/jena-fuseki 含 JDK，可直接在容器内复核 -Xms256m -Xmx256m -Xmn128m 是否生效。

十一、常见问题（FAQ）

Q1：端口 3030 被占用？ 答：改宿主机映射端口，如 "13030:3030"，访问 http://主机IP:13030。

Q2：改了 docker-compose.yml 后如何生效？ 答：docker compose up -d 会按新配置重建发生变化的容器；数据卷不变则数据保留。

Q3：FUSEKI_DATASET_1 创建的数据集在哪？ 答：持久化在宿主机 ./fuseki-data/databases/<name>/，重启后仍在。

Q4：如何看到 Fuseki 启动日志？ 答：docker compose logs -f fuseki，应能看到 Apache Jena Fuseki 6.2.0 与 Port: http=3030 等行。

十二、参考链接

Apache Jena Fuseki：https://jena.apache.org/documentation/fuseki2/
stain/jena-fuseki 镜像仓库：https://hub.docker.com/r/stain/jena-fuseki
镜像源码：https://github.com/stain/jena-fuseki-docker
Docker Compose 规范：https://docs.docker.com/compose/compose-file/