Apache SIS 配置参数详解

Apache SIS 1.6 配置参数详解：SIS_DATA 数据目录、SIS_OPTS 启动选项与命令行全局选项逐条说明，EPSG 数据集三种接入方式对比，conf/logging.properties 日志配置，bin/sis 启动脚本 JVM 参数与堆内存限制，含生产配置模板与常见问题。

Apache SISApache SIS2026/10/12

Apache SIS 配置参数详解

目标：梳理 Apache SIS 1.6 的完整配置面——环境变量（SIS_DATA、SIS_OPTS）、命令行全局选项、EPSG 数据集接入方式、日志配置文件与 JVM 参数。全部条目均在 Ubuntu 22.04.5 + JDK 17 + SIS 1.6 环境核实（配置文件与启动脚本为实机原文，行为结论有真实回显支撑），并给出可直接套用的生产配置模板。

一、环境信息

  • 操作系统：Ubuntu 22.04.5 LTS（x86_64）
  • Java：OpenJDK 17.0.20.1
  • Apache SIS：1.6（二进制发行包装于 /opt/sis/apache-sis-1.6）
  • 配置载体：/etc/profile.d/sis.sh（环境变量）、conf/logging.properties（日志）、bin/sis（启动脚本）
  • 演示账号：root

二、参数体系与总览

2.1 三层配置入口

SIS 1.6 的配置入口分三层，作用域由广到窄：

  1. 环境变量层：SIS_DATA（数据目录定位）、SIS_OPTS（默认启动选项注入）、JDK_JAVA_OPTIONS（JVM 通用选项注入）；
  2. 配置文件层：conf/logging.properties（JUL 日志级别与格式）；
  3. 单次调用层：sis 命令行全局选项（--format、--encoding、--brief 等），优先级最高，覆盖 SIS_OPTS 中的同名项。

2.2 参数总览表

参数作用域默认值说明
SIS_DATA进程安装目录下 data数据目录（EPSG 数据库、基准变化文件）
SIS_OPTS进程空注入每次 sis 调用的默认选项
JDK_JAVA_OPTIONS进程空JDK 9+ 通用机制，注入 JVM 参数
--format单次命令text输出格式：xml、wkt、wkt1、text
--encoding单次命令US-ASCII输出编码（推荐 UTF-8）
--colors单次命令自动是否彩色输出
--locale / --timezone单次命令系统值本地化与时区
--brief / --verbose / --debug单次命令关精简 / 详情 / 全栈调试
--sourceCRS / --targetCRS / --operation / --inversetransform无转换目标定义
--metadatacrs/metadata/transform无辅助元数据文件
--outputtranslate无输出文件

三、数据目录与 EPSG 数据集

3.1 SIS_DATA 环境变量

SIS_DATA 是 SIS 全局数据目录的唯一入口。启动脚本 bin/sis 的逻辑为：SIS_DATA 未设置时默认取安装目录（BASE_DIR）下 data 并 export，同时脚本会 unset SIS_HOME（安装位置标识变量不参与运行时定位）。

数据目录内置 README 的官方说明原文：

This directory is the default location of Apache SIS data.
If desired, an alternative location can be defined with the
SIS_DATA environment variable. Example:

    export SIS_DATA=/my/data/directory

实测 sis about 的 Paths 段直接回显生效目录（Data directory… /opt/sis/apache-sis-1.6/bin/../data），可作为排查配置是否生效的第一入口。

3.2 数据目录结构

按需创建，实测安装完整 EPSG 后为：

data/
├── Databases/SpatialMetadata/   （EPSG 数据库，Derby 格式，实测约 25M）
├── DatumChanges/                （NADCON 等基准变化文件检索路径）
└── README

DatumChanges 目录由 sis transform 的日志明示：

INFO    [NADCON] Datum shift files are searched in the
?       ?/opt/sis/apache-sis-1.6/data/DatumChanges? directory.

3.3 EPSG 数据集接入方式对比

EPSG 数据许可与 Apache 2.0 不兼容，发行包只内置常用 CRS 常量子集（sis about 显示 Subset of EPSG），完整库需另行接入。实测对比三种官方方式：

方式原理优点注意点
命令行交互安装查询子集外代码触发下载（约 24 MB 入 SIS_DATA/Databases）命令行与 Java 应用（设 SIS_DATA）共用需交互终端确认两次条款；无人值守管道不弹提示直接报错（退出码 199）
Maven 依赖 org.apache.sis.non-free:sis-embedded-data（实测采用）EPSG 数据库随 jar 分发（约 4.8 MB）引入即用，无需任何环境变量Java 应用侧推荐；引入即视为接受 EPSG 条款；须搭配 Derby 10.15.2.0 驱动
Maven 依赖 org.apache.sis.non-free:sis-epsg首次使用时从 Maven Central 下载并装入 SIS_DATA自动化程度高官方文档提供，本文环境未实测，按需选用

接入后 sis about 的 Geodetic dataset 一栏由 Subset of EPSG 变为：

  │   └─Geodetic dataset………………… EPSG geodetic dataset version 12.047 on "Apache Derby" version 10.15.

3.4 derby.system.home 兜底属性

官方 EPSG 页明确：无法设置 SIS_DATA 时，可改用 Java 属性指向数据库父目录。官方原文（节选）：

 Set the SIS_DATA environment variable to the path of apache-sis-1.6/data directory (recommended) .
 Set the derby.system.home Java property to the path of apache-sis-1.6/data/Databases directory.

 java -Dderby.system.home = apache-sis-1.6/data/Databases \
 --class-path apache-sis-1.6/lib/sis-referencing.jar:myApp.jar \
 MyMainClass

⚠️ 注意：classpath 方式运行 Java 应用时，即使设置了 SIS_DATA，SIS 1.6 的 EPSG 工厂也可能退化为 EPSGFactoryFallback（仅内置子集），坐标操作查询返回空集。应用内使用完整 EPSG 的可靠途径是 Maven 依赖 sis-embedded-data（实测结论，详见《Apache SIS 构建并运行示例应用指南》）。

四、SIS_OPTS 启动选项

SIS_OPTS 的内容会被启动脚本拼接到每一次 sis 调用（脚本尾部 $SIS_OPTS "$@"）。官方下载页推荐配置：

export SIS_OPTS="--encoding UTF-8"

实测收益：命令输出（WKT、元数据树表格）中的非 ASCII 字符（树形连线、本地化引号、度分秒符号）正常显示；不设置时这类字符显示为问号。

两点实测行为需注意：

  1. 作用范围是所有子命令：SIS_OPTS 里的选项对不支持的子命令会报错。实测 SIS_OPTS="--encoding UTF-8" 时执行 sis translate --help：

    Option ?encoding? is not recognized.
（退出码 2）

    即 translate 子命令不接受 --encoding。需要为 translate 排障时，可临时 unset SIS_OPTS。

  2. 单次命令选项可覆盖默认值：sis crs --format wkt1 EPSG:4326 这类显式选项与 SIS_OPTS 并存时，命令行选项优先生效。

五、命令行全局选项详解

sis help 输出的完整选项清单（实测原文，全局级）：

Options:
  --sourceCRS  The Coordinate Reference System of input data.
  --targetCRS  The Coordinate Reference System of output data.
  --operation  The Coordinate Operation to apply on data (alternative to source and target CRS).
  --inverse    Use the inverse of the coordinate operation.
  --metadata   Relative path to an auxiliary metadata file.
  --output     The output file.
  --format     The output format. Examples: xml, wkt, wkt1 or text.
  --locale     The locale to use for the console output.
  --timezone   The timezone for the dates printed to the console output.
  --encoding   The encoding to use for some text inputs and for console output.
  --colors     Whether colorized output shall be enabled.
  --brief      Reduce the output to only brief information.
  --verbose    Request the output to contain more detailed information.
  --debug      Prints full stack trace in case of failure.
  --help       Lists the options available for a specific command.

5.1 输出控制

  • --format：支持 xml（ISO 19115 元数据 XML）、wkt（WKT 2）、wkt1（WKT 1）、text（默认树形文本）。适用于 crs、metadata、identifier、translate 等子命令（各子命令支持子集见 sis <command> --help）。
  • --encoding：输出编码，中文环境建议固定 UTF-8（经 SIS_OPTS 全局注入）。
  • --colors：彩色输出开关，重定向到文件时建议关闭。
  • --locale / --timezone：控制输出语言与日期时区。

5.2 调试与详情

  • --brief：精简输出。注意它是子命令级选项而非全局命令都可用：实测 sis metadata --brief <file> 报 Option ?brief? is not recognized.（退出码 2），以 sis metadata --help 列出的选项为准。
  • --verbose：更详细输出（如元数据完整字段）。
  • --debug：失败时打印完整堆栈，排障首选。

5.3 数据定位与转换选项

  • --sourceCRS / --targetCRS：transform 子命令的源/目标坐标参照系（EPSG 代码或 WKT），实测：

    sis transform --sourceCRS EPSG:4267 --targetCRS EPSG:4326 AmericanCities.csv

  • --operation：直接指定坐标操作（与 source/target 二选一）；--inverse 使用逆变换。

  • --metadata：为缺乏元数据的数据文件补充辅助元数据。

  • --output：translate 子命令输出文件，实测 sis translate --output demo.tiff demo.asc 完成 ASCII Grid 转 GeoTIFF。

六、日志配置（conf/logging.properties）

6.1 实测默认内容

SIS 用 JUL（java.util.logging），默认配置文件在安装目录 conf/logging.properties（启动脚本经 -Djava.util.logging.config.file 挂载）。实测文件内容（去注释行）：

handlers = java.util.logging.FileHandler, \
           java.util.logging.ConsoleHandler
.level = CONFIG
org.apache.sis.level = FINE
java.util.logging.FileHandler.level = FINE
java.util.logging.ConsoleHandler.level = INFO
java.util.logging.FileHandler.pattern      = %p/log/sis.log
java.util.logging.FileHandler.formatter    = java.util.logging.SimpleFormatter
java.util.logging.ConsoleHandler.formatter = org.apache.sis.util.logging.MonolineFormatter
org.apache.sis.util.logging.MonolineFormatter.source = class:short

要点：根级别 CONFIG、SIS 包 FINE；文件日志 log/sis.log（%p 展开为安装目录，实测写入 /opt/sis/apache-sis-1.6/log/sis.log）；控制台仅 INFO，用 SIS 自带的 MonolineFormatter 单行格式（class:short 为短类名前缀）。

6.2 级别调整示例

控制台也要看调试日志时，把 ConsoleHandler 级别调到 FINE：

java.util.logging.ConsoleHandler.level = FINE

临时排障更简单：给命令加 --debug，失败堆栈直接上控制台。

七、JVM 与启动脚本参数

7.1 bin/sis 启动脚本的 java 参数

bin/sis 最终执行的 JVM 命令（脚本原文）：

java --module-path "$BASE_DIR/lib:$BASE_DIR/lib/app/org.apache.sis.console.jar" \
     -Djava.util.logging.config.class="org.apache.sis.util.logging.Initializer" \
     -Djava.util.logging.config.file="$BASE_DIR/conf/logging.properties" \
     -Dderby.stream.error.file="$BASE_DIR/log/derby.log" \
     --module org.apache.sis.console/org.apache.sis.console.Command \
     $SIS_OPTS "$@"

含义：模块路径指发行包 lib/；日志配置经系统属性挂载；Derby 错误流重定向到 log/derby.log（避免 Derby 日志污染控制台）。

7.2 堆内存限制

脚本本身未预设 -Xmx，JVM 使用默认堆策略。服务器资源受限时可用 JDK 9+ 的通用机制 JDK_JAVA_OPTIONS 注入（无需改脚本）。实测：

export JDK_JAVA_OPTIONS="-Xms256m -Xmx512m"
sis about

实测回显（首行即注入确认）：

NOTE: Picked up JDK_JAVA_OPTIONS: -Xms256m -Xmx512m
Local configuration
  ├─Versions
  │   ├─Apache SIS………………………………… 1.6

也可以直接编辑 bin/sis，在 java 命令中固定 -Xms256m -Xmx512m。

八、生产配置模板

把以下内容落为 /etc/profile.d/sis.sh，即可作为服务器标准配置（与实测环境一致）：

# Apache SIS 1.6 生产环境变量模板
export SIS_HOME=/opt/sis/apache-sis-1.6          # 安装位置（便于运维管理）
export PATH=$SIS_HOME/bin:$PATH                  # 命令行工具
export SIS_DATA=/opt/sis/apache-sis-1.6/data     # 数据目录（可指向共享存储）
export SIS_OPTS="--encoding UTF-8"               # 输出编码（命令行交互环境推荐）
export JDK_JAVA_OPTIONS="-Xms256m -Xmx512m"      # JVM 堆限制（按需调整）

配合 conf/logging.properties（文件日志 FINE、控制台 INFO）与 log/derby.log 重定向，即构成可观测的默认运行面。批量/无人值守脚本环境建议去掉 SIS_OPTS 中的 --encoding 并显式指定每条命令所需选项（见第四章第 1 点）。

九、注意事项

⚠️ 注意：

  1. SIS_OPTS 会注入所有子命令，translate 不支持 --encoding，混用时先 unset SIS_OPTS。
  2. EPSG 完整库交互安装需要 TTY；管道/无人值守下不弹提示、直接报错退出码 199，请改用 sis-embedded-data 依赖或预先人工安装。
  3. --brief 等选项按子命令生效，出现 Option ?brief? is not recognized. 时查该子命令的 --help 清单。
  4. 修改 SIS_DATA 后，sis about 的 Paths 段是验证生效的最快途径。
  5. JDK_JAVA_OPTIONS 会打印一行 NOTE 提示，属正常行为；用 -XX:+PerfDisableSharedMem 等更精细 JVM 参数时同理。

十、常见问题

Q1：设置了 SIS_OPTS="--encoding UTF-8"，日志行仍显示问号？ --encoding 只作用于命令输出通道；INFO/WARNING 日志走 java.util.logging 控制台处理器，默认编码为 US-ASCII。日志内容（数据值）不受影响；确需美化可调整 conf/logging.properties。

Q2：如何确认 EPSG 完整库已生效？ sis about 看 Geodetic dataset：显示 EPSG geodetic dataset version 12.047 on "Apache Derby" version 10.15. 即完整库；显示 Subset of EPSG 仍是内置子集。

Q3：想自定义数据目录到共享盘？ export SIS_DATA=/my/data/directory（官方 README 原文机制），首次使用时会自动创建 Databases/、DatumChanges/ 子目录；已安装的 EPSG 库可直接整体拷贝迁移。

Q4：Derby 启动报 ERROR XSLAN 版本不兼容？ 数据库由 Derby 10.15 创建而驱动版本更低。统一 SIS 1.6 生态的 Derby 版本为 10.15.2.0（发行包 lib/org.apache.derby.engine.jar 的 Bundle-Version 为 10.15.2000000.1873585，sis-embedded-data 依赖同版本 derbytools）。

Q5：无人值守脚本如何消费完整 EPSG？ 三选一：预先在交互终端完成一次 EPSG 安装（结果落在 SIS_DATA/Databases，之后脚本直接用）；应用侧改用 Maven 依赖 sis-embedded-data；或选用 sis-epsg 依赖（官方提供，未实测）。

十一、参考链接

  • 命令行工具与选项：https://sis.apache.org/command-line.html
  • EPSG 数据集接入：https://sis.apache.org/epsg.html
  • 下载与环境变量推荐：https://sis.apache.org/downloads.html
  • 源码（conf/ 与 bin/sis 原文）：https://github.com/apache/sis