Apache SDAP 1.4.0 配置参数详解

目标：详解 Apache SDAP 1.4.0 nexus Web 服务的核心配置——web.ini（监听端口/并发）、algorithms.ini（算法并发）、datasets.ini（数据集目录）、datastores.ini（瓦片存储后端）、webapp.py 命令行参数与 Solr 8.11.3 的 JVM 堆配置，并给出可直接套用的生产模板。参数与默认值均基于真实环境实测（Ubuntu 22.04.5 + Solr 8.11.3 双 core）。

一、环境信息

• 操作系统：Ubuntu 22.04.5 LTS（x86_64）
• Apache SDAP：1.4.0（nexus 源码部署，Web 服务端口 8083）
• 安装目录：/opt/sdap-nexus
• Web 配置目录：/opt/sdap-nexus/analysis/webservice/config/
• 数据访问配置：/opt/sdap-nexus/data-access/nexustiles/config/ 与 data-access/nexustiles/backends/nexusproto/config/
• 配套 Solr：8.11.3（/opt/solr，端口 8983，双 core：nexustiles / nexusdatasets）
• 运行用户：root

二、前置条件

• 已按《Apache SDAP 1.4.0 安装指南》完成 nexus 与 Solr 8.11.3 部署。
• 修改配置后需重启服务生效：nexus 用 systemctl restart nexus，Solr 用 systemctl restart solr。
• 本文所有参数值均读取自 1.4.0 源码包自带配置文件与实测运行状态。

三、参数查看与修改方式

nexus 的配置以 .ini 文件形式随源码包提供，启动时由 webapp.py 通过 pkg_resources.resource_filename 读取包内配置（.ini 优先，缺失时回退 .ini.default）：

ls /opt/sdap-nexus/analysis/webservice/config/
ls /opt/sdap-nexus/data-access/nexustiles/config/
ls /opt/sdap-nexus/data-access/nexustiles/backends/nexusproto/config/

回显：

algorithms.ini
scheduler.xml
web.ini
datasets.ini.default
datastores.ini.default

修改方式：

• 直接编辑上述 .ini 文件（或从 .ini.default 拷贝为 .ini 后编辑），改完重启 nexus 生效。
• 运行时可通过 webapp.py 命令行参数临时覆盖（优先级高于 ini，见 5.5）。
• Solr 的 JVM 堆在 /opt/solr/bin/solr.in.sh 修改（见 5.6），改完重启 Solr 生效。

四、参数总览

五、核心参数分类详解

5.1 Web 服务参数（web.ini）

文件位置：/opt/sdap-nexus/analysis/webservice/config/web.ini。

[global]
server.socket_port=8083
server.socket_host = '127.0.0.1'
server.max_simultaneous_requests = 10

[livy]
livy_port = 8998
livy_host = localhost
server.socket_port = 8084
server.socket_host = '127.0.0.1'

[static]
static_enabled=true
static_dir=static

[modules]
module_dirs=webservice.algorithms,webservice.algorithms_spark,webservice.algorithms.doms,webservice.management

• server.socket_port / server.socket_host：REST 监听端口与地址。默认 127.0.0.1:8083 只允许本机访问；对外提供服务需改为 0.0.0.0（实测部署通过命令行 --address=0.0.0.0 覆盖，netstat 确认监听 0.0.0.0:8083）。
• server.max_simultaneous_requests：tornado 最大并发请求数，按服务负载调整。
• [livy] 段：分布式模式下 Livy 网关地址与端口（livy_port=8998、server.socket_port=8084），单机 Solr 后端场景不涉及。
• [static] static_enabled：是否提供静态资源（static_dir=static）。
• [modules] module_dirs：算法模块包名列表（逗号分隔），启动时逐个注册 REST 端点；增删算法模块在此调整。

💡 实测启动日志会逐个打印模块注册信息，例如 Adding algorithm module 'Capabilities' with path '/capabilities'，可用作模块加载是否成功的核对依据。

5.2 算法与并发参数（algorithms.ini）

文件位置：/opt/sdap-nexus/analysis/webservice/config/algorithms.ini。

[multiprocessing]
maxprocesses=8

[spark]
maxconcurrentjobs=10

• [multiprocessing] maxprocesses：多进程类算法的最大进程数，受服务器 CPU 核数约束。
• [spark] maxconcurrentjobs：Spark 类算法（如 /timeSeriesSpark、/corrMapSpark）的最大并发作业数；Spark 作业排队等待空闲槽位，超过该值会排队。

5.3 数据集目录参数（datasets.ini）

文件位置：/opt/sdap-nexus/data-access/nexustiles/config/datasets.ini.default（源码包默认值；生产可拷贝为 datasets.ini 修改）。

[solr]
host=http://localhost:8983
core=nexusdatasets

• host：存放数据集目录（数据集清单）的 Solr 地址。nexus 启动时后台线程 _update_datasets 会拉取该 core 的全量数据集并缓存（实测日志 Finished dataset update: 1 added, 0 removed, 1 total）。
• core：数据集目录 core 名，默认 nexusdatasets（安装篇创建的双 core 之一）。
• 该 core 不可达时 nexus 无法完成数据集更新，进程会以 exit(-1) 退出（见常见问题）。

5.4 数据存储后端参数（datastores.ini）

文件位置：/opt/sdap-nexus/data-access/nexustiles/backends/nexusproto/config/datastores.ini.default（瓦片数据后端默认配置；测试配置在 data-access/tests/config/datastores.ini）。

[cassandra]
host=localhost
port=9042
keyspace=nexustiles
local_datacenter=datacenter1
protocol_version=4
dc_policy=DCAwareRoundRobinPolicy
username=
password=

[s3]
bucket=nexus-jpl
region=us-west-2

[dynamo]
table=nexus-jpl-table
region=us-west-2

[solr]
host=http://localhost:8983
core=nexustiles

[datastore]
store=cassandra

• [datastore] store：默认瓦片后端类型，可选 cassandra / solr / s3 / dynamo。本批次实测以 solr 为主后端（[solr] host/core 指向 nexustiles core），Cassandra 后端未做集群实测（⚠️ 受限）。
• [cassandra] 段：host / port / keyspace / local_datacenter / protocol_version / dc_policy 等连接参数；测试配置中 protocol_version=3、keyspace=nexustiles。
• [solr] 段：瓦片元数据索引后端，host=http://localhost:8983、core=nexustiles。
• [s3] / [dynamo] 段：AWS 后端占位配置（bucket / region / table），本地部署无需启用。

5.5 命令行参数（webapp.py）

analysis/webservice/webapp.py 启动参数（实测 --help 输出节选）：

--address       Bind to the given address (default '127.0.0.1')
--cassandra-host  cassandra host
--cassandra-password / --cassandra-username
--collections-path  collection config path
--debug         run in debug mode (default False)
--port          run on the given port (default 8083)
--solr-host     solr host and port
--solr-time-out time out for solr requests in seconds (default 60)
--logging=debug|info|warning|error|none (default info)

实测启动方式（systemd unit 中的 ExecStart）：

/usr/bin/python3 /opt/sdap-nexus/analysis/webservice/webapp.py --port=8083 --address=0.0.0.0

5.6 Solr 参数与 JVM（solr.in.sh）

文件位置：/opt/solr/bin/solr.in.sh。

• SOLR_JAVA_MEM：Solr JVM 堆。SDAP 文档规范要求堆限制在 256-512MB，实测修改为：

SOLR_JAVA_MEM="-Xms256m -Xmx512m"

• 生效核对（实测回显）：

ps -ef | grep [j]ava | head -1 | tr ' ' '\n' | grep -E "^-X(mx|ms)"

-Xms256m
-Xmx512m

• solr status 中 "memory":"74.2 MB (%14.5) of 258 MB" 的 258MB 即 256MB 堆上限的运行时表达。
• bitnami 形态镜像另支持 SOLR_HEAP（默认 512m，见官方镜像说明），与 SOLR_JAVA_MEM 二选一。

六、生产配置模板

适用场景：16GB 内存、SSD 磁盘、对外提供 40+ REST 分析端点、单 Solr 双 core 部署、以 Solr 为瓦片主后端。

web.ini（/opt/sdap-nexus/analysis/webservice/config/web.ini）：

[global]
server.socket_port=8083
server.socket_host = '0.0.0.0'
server.max_simultaneous_requests = 20

[static]
static_enabled=true
static_dir=static

[modules]
module_dirs=webservice.algorithms,webservice.algorithms_spark,webservice.algorithms.doms,webservice.management

algorithms.ini：

[multiprocessing]
maxprocesses=8

[spark]
maxconcurrentjobs=10

datasets.ini（拷贝自 .default 后修改生产 Solr 地址）：

[solr]
host=http://10.0.0.10:8983
core=nexusdatasets

datastores.ini（以 Solr 为瓦片主后端）：

[solr]
host=http://10.0.0.10:8983
core=nexustiles

[datastore]
store=solr

/opt/solr/bin/solr.in.sh：

SOLR_JAVA_MEM="-Xms256m -Xmx512m"

内存说明：nexus 是 tornado 单进程 Python 服务，不设大堆；Solr 负责瓦片索引与查询，-Xms256m -Xmx512m 满足 1 亿级瓦片规模前的常规负载。若瓦片量持续增长，可把堆上调至 512MB-1GB（仍建议先压测）；maxprocesses / maxconcurrentjobs 按 CPU 核数调整。

七、常见问题

7.1：改了 web.ini 的端口不生效

原因：命令行参数优先级高于 ini，若启动命令带 --port=8083，以命令行为准。 解决：检查 systemd unit 的 ExecStart 是否显式传了 --port / --address；改 ini 后需 systemctl restart nexus 生效，并用 netstat -tlnp | grep 8083 核对实际监听。

7.2：/version 返回 500

原因：pkg_resources.get_distribution("sdap-nexus") 找不到发行元数据（直接运行源码未注册）。 解决：在项目内注册 sdap_nexus.egg-info/PKG-INFO（写入 Name: sdap-nexus、Version: 1.4.0）后重启 nexus。

7.3：Solr 内存占用超过预期

原因：SOLR_JAVA_MEM 未生效（比如被其他启动参数覆盖，或改后未重启）。 解决：用 5.6 的命令核对 -Xms/-Xmx 实际值，确认无误后 systemctl restart solr。

7.4：切 Cassandra 后端需要改什么

原因与解决：在 datastores.ini 中设 [datastore] store=cassandra，并填写 [cassandra] 段（host / keyspace / local_datacenter / protocol_version）。⚠️ 受限说明：Cassandra 后端本批次未做集群实测，切换后需自测瓦片读写链路。

7.5：Spark 算法作业一直排队

原因：algorithms.ini [spark] maxconcurrentjobs（默认 10）槽位占满。 解决：按需上调 maxconcurrentjobs，或减少并发请求；同时检查 Spark 本地模式资源（pyspark 3.2.1）。

八、参考链接

• Apache SDAP 官网：https://sdap.apache.org/
• Apache SDAP nexus 源码仓库：https://github.com/apache/incubator-sdap-nexus
• Apache Solr 8.11 官方文档：https://solr.apache.org/guide/8_11/
• Apache SDAP 官方 quickstart：https://github.com/apache/incubator-sdap-nexus/tree/master/docs