Apache SDAP 1.4.0 常用 CLI 命令与工具详解

Apache SDAP 1.4.0 常用 CLI 命令与工具详解：webapp.py 启动参数、curl REST API（/version 等）、Solr 管理命令、tools 脚本与 ps 校验 JVM，回显均实测

Apache SDAPApache SDAP2026/10/13

Apache SDAP 1.4.0 常用 CLI 命令与工具详解

目标：详解 Apache SDAP 1.4.0 的常用命令行工具——webapp.py 服务启动、curl 调用 REST API（/version、/heartbeat、/capabilities、/list 等 43 个端点）、Solr 8.11.3 管理命令、tools/ 目录脚本与 ps 校验 JVM 生效参数。所有命令与回显均为真实环境实测（Ubuntu 22.04.5 + Solr 8.11.3 双 core）。

一、环境信息

  • 操作系统：Ubuntu 22.04.5 LTS（x86_64）
  • Apache SDAP：1.4.0（nexus 源码部署于 /opt/sdap-nexus）
  • 服务脚本：/opt/sdap-nexus/analysis/webservice/webapp.py
  • 配套 Solr：8.11.3（/opt/solr，端口 8983，双 core：nexustiles / nexusdatasets）
  • REST 端口：8083
  • 示例账号：root

二、工具概览

工具位置用途
webapp.py/opt/sdap-nexus/analysis/webservice/nexus Web 服务启动入口（tornado）
curl系统自带调用 nexus REST API 与 Solr Admin API
/opt/solr/bin/solr/opt/solr/bin/Solr 启动/停止/状态/创建 core
tools/*.py/opt/sdap-nexus/tools/辅助脚本（build / deletebyquery / cdms / domspurge / rmqmonitor / doms-data-tools）
systemctl系统自带systemd 托管 solr 与 nexus 服务
ps / netstatprocps / net-tools核对 JVM 参数与监听端口

三、前置条件

  • nexus 已部署到 /opt/sdap-nexus，Solr 已部署到 /opt/solr 并创建 nexustiles / nexusdatasets 双 core（见《Apache SDAP 1.4.0 安装指南》）。
  • 已安装 python3、curl、procps、net-tools；运行 Python 依赖脚本需 PYTHONPATH=/opt/sdap-nexus/analysis:/opt/sdap-nexus/data-access。

四、工具详解

4.1 webapp.py 服务启动命令

启动 nexus Web 服务（手动前台方式）：

cd /opt/sdap-nexus
PYTHONPATH=/opt/sdap-nexus/analysis:/opt/sdap-nexus/data-access \
  python3 analysis/webservice/webapp.py --port=8083 --address=0.0.0.0

启动日志关键行（实测）：

- webservice.NexusHandler - INFO - Adding algorithm module 'Backend Services Status' with path '/heartbeat'
- nexus-tile-svc.backends - INFO - Finished dataset update: 1 added, 0 removed, 1 total
- __main__ - INFO - SDAP started in 0:00:04.490194. Starting HTTP listener...

命令行参数速查（实测 --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)

⚠️ 启动时若 Solr core 未就绪，后台数据集更新线程抛 pysolr.SolrError 导致进程 exit(-1)，务必先确认 Solr 正常。

4.2 curl 调用 REST API

nexus 对外提供 HTTP REST 接口，均可用 curl 直接调用。

4.2.1 版本与心跳

curl -s http://localhost:8083/version
curl -s http://localhost:8083/heartbeat

回显：

1.4.0
{"nexusproto": true}

4.2.2 能力清单（capabilities）

curl -s http://localhost:8083/capabilities

回显（节选，完整返回 43 个已注册端点）：

[
    {
        "name": "Capabilities",
        "path": "/capabilities",
        "description": "Lists the current capabilities of this Nexus system",
        "parameters": {}
    },
    {
        "name": "Correlation Map",
        "path": "/correlationMap",
        "description": "Computes a correlation map between two datasets given an arbitrary geographical area and time range",
        "parameters": {}
    },
    {
        "name": "Dataset List",
        "path": "/list",
        "description": "Returns a list of datasets known to this Nexus instance",
        "parameters": {}
    }
]

已注册端点清单（实测 /capabilities 返回）：

/capabilities /correlationMap /dailydifferenceaverage /datainbounds /list
/delay /makeerror /heartbeat /latitudeTimeHofMoeller /longitudeTimeHofMoeller
/longitudeLatitudeMap /standardDeviation /stats /statsSolr
/tomogram/longitude /tomogram/latitude /tomogram/profile /tomogram/3d
/climMapSpark /corrMapSpark /dailydifferenceaverage_spark
/latitudeTimeHofMoellerSpark /longitudeTimeHofMoellerSpark /job /job/cancel
/cdmslist /domsmatchup /cdmscatalog /domsmetadata /cdmsresults /domsstats
/domsvalues /domsinsitusubset /cdmssubset /match_spark /match_spark_doms
/maxMinMapSpark /timeAvgMapSpark /timeSeriesSpark /varianceSpark
/datasets/add /datasets/update /datasets/remove

4.2.3 数据集列表（/list）

curl -s http://localhost:8083/list

回显（实测，含摄入的 test-dataset）：

[{"shortName": "test-dataset", "title": "test-dataset", "tileCount": 1, "type": "nexusproto", "start": 1577836800.0, "end": 1609459199.0, "iso_start": "2020-01-01T00:00:00+0000", "iso_end": "2020-12-31T23:59:59+0000", "spatial_extent": "-121.00,30.00,-119.00,31.00"}]

4.2.4 常用分析端点（示例）

# 时间序列统计（statsSolr，无数据时返回错误 JSON）
curl -s "http://localhost:8083/statsSolr?ds=test-dataset"
# 边界框内瓦片查询（b 参数格式：minLon,minLat,maxLon,maxLat）
curl -s "http://localhost:8083/datainbounds?ds=test-dataset&b=-121.0,30.0,-119.0,31.0"

/statsSolr 无数据时的实测回显：

{"error": "No data found for selected timeframe", "code": 400}

/datainbounds 参数格式错误时的实测回显（b 错传为 -122.0,29.0 两个坐标）：

500: [Reason: Can't parse point '-122.0,29.0' because: Bad Y value -122.0]

瓦片 id 非 UUID 时的实测回显：

{"error": "badly formed hexadecimal UUID string", "code": 500}

4.3 Solr 管理命令（/opt/solr/bin/solr）

4.3.1 启动 / 停止

/opt/solr/bin/solr start -force
/opt/solr/bin/solr stop -force

启动回显（实测）：

NOTE: Please install lsof as this script needs it to determine if Solr is listening on port 8983.
Started Solr server on port 8983 (pid=6691). Happy searching!

4.3.2 状态查看

/opt/solr/bin/solr status

回显（实测）：

Found 1 Solr nodes:
Solr process 14161 running on port 8983
{
  "solr_home":"/opt/solr/server/solr",
  "version":"8.11.3 baa7c80af4278cc8951a344d8e9320386588d12d - houstonputman - 2024-02-05 15:08:45",
  "startTime":"2026-10-13T00:08:05.953Z",
  "uptime":"0 days, 0 hours, 1 minutes, 4 seconds",
  "memory":"74.2 MB (%14.5) of 258 MB"}

4.3.3 创建 core

cd /opt/solr
./bin/solr create_core -c nexustiles -d nexustiles -force
./bin/solr create_core -c nexusdatasets -d dataset -force

回显：

Created new core 'nexustiles'
Created new core 'nexusdatasets'

4.3.4 查询 core 状态（Admin API）

curl -s "http://localhost:8983/solr/admin/cores?action=STATUS"

响应 JSON 中 cores 数组应包含 nexusdatasets 与 nexustiles。

4.4 tools 目录辅助脚本

工具位于 /opt/sdap-nexus/tools/，均为 Python 脚本，运行需 PYTHONPATH 指向 nexus 源码（部分脚本依赖未打包，见各脚本 requirements.txt）。

脚本用途
build/build.py发布构建辅助脚本（从官方发布包构建 SDAP 制品，依赖 bs4/requests）
deletebyquery/deletebyquery.py按查询条件删除数据集（依赖 solrcloudpy）
cdms/cdms_reader.py读取 CDMS netCDF 匹配文件并输出 CSV / 元数据
domspurge/purge.py清理 DOMS/CDMS 执行数据（依赖 tqdm）
doms-data-tools/update_doms_data_pk.py、update_values_type.pyDOMS 数据主键与值类型更新脚本
rmqmonitor/monitor.py监控 RabbitMQ 消息队列消费进度（摄取链）

cdms_reader.py 实测帮助回显：

usage:
cdms_reader.py -h OR --help
cdms_reader.py filename -c -g
cdms_reader.py filename --csv --meta
Use -l OR -l1 to modify destination of logs

positional arguments:
  filename              CDMS netCDF file to read

options:
  -h, --help            show this help message and exit
  -c [CSV], --csv [CSV]
                        Use -c or --csv to retrieve CSV output
  -g [META], --meta [META]
                        Use -g or --meta to retrieve global attributes / metadata
  -l [LOG], --log [LOG]
                        Use -l or --log to AVOID creating log files, OR use -l1 to print to stdout/console

rmqmonitor/monitor.py 实测帮助回显：

usage: monitor.py [-h] [--username USERNAME] [--password PASSWORD]

options:
  -h, --help           show this help message and exit
  --username USERNAME  RabbitMQ username
  --password PASSWORD  RabbitMQ password

⚠️ 依赖缺失提示（实测）：deletebyquery.py 缺 solrcloudpy、build.py 缺 bs4、purge.py 缺 tqdm 时会分别报 ModuleNotFoundError，按各脚本目录 requirements.txt 补齐依赖即可。 ⚠️ 受限说明：rmqmonitor 与摄取链相关，依赖 RabbitMQ 消息队列，本批次未做摄取链实测。

4.5 systemd 服务管理命令

依次管理两个服务单元（每行仅一个单元名）：

systemctl enable solr
systemctl enable nexus
systemctl start solr
systemctl start nexus
systemctl status solr
systemctl status nexus

回显（节选，实测）：

● solr.service - Apache Solr 8.11.3
     Active: active (running) since Tue 2026-10-13 00:04:40 UTC; 8s ago
   Main PID: 8900 (java)

● nexus.service - Apache SDAP 1.4.0 Nexus Web Service
     Active: active (running) since Tue 2026-10-13 00:08:36 UTC; 18s ago
   Main PID: 14426 (python3)

重启 / 查看日志：

systemctl restart nexus
journalctl -u nexus -n 50

4.6 JVM 参数与端口校验

核对 Solr JVM 堆生效值（实测回显）：

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

-Xms256m
-Xmx512m

核对监听端口：

netstat -tlnp | grep -E "8083|8983"

回显（实测）：

tcp        0      0 0.0.0.0:8083            0.0.0.0:*               LISTEN      14426/python3
tcp6       0      0 :::8983                 :::*                    LISTEN      14161/java

五、注意事项

  • 启动顺序：先 Solr 后 nexus；Solr core 未就绪时启动 nexus 会反复重启。
  • 每条命令逐个单独执行，不要在多个服务实例上使用循环批量操作。
  • /list 有 1 小时 TTL 缓存：摄入新数据集后需重启 nexus 才能在 /list 看到。
  • REST 端点格式：/datainbounds 的 b 参数必须为 minLon,minLat,maxLon,maxLat；瓦片 id 必须为 UUID。
  • tools 脚本依赖：按各目录 requirements.txt 补齐 Python 依赖后再运行。

六、常见问题

6.1：curl http://localhost:8083/version 返回 500

解决：pkg_resources.get_distribution("sdap-nexus") 找不到发行元数据；在项目内注册 sdap_nexus.egg-info/PKG-INFO（Name: sdap-nexus、Version: 1.4.0）后重启 nexus。

6.2：/statsSolr 返回 {"error": "No data found for selected timeframe", "code": 400}

解决：目标数据集在 nexustiles core 中无匹配瓦片（无值字段数据）；先确认 curl http://localhost:8083/list 中数据集存在且瓦片已摄入。

6.3：/datainbounds 报 Bad Y value

解决：b 参数格式错误；正确格式为 minLon,minLat,maxLon,maxLat（如 -121.0,30.0,-119.0,31.0）。

6.4：tools 脚本报 ModuleNotFoundError

解决：按脚本目录 requirements.txt 安装依赖；例如 deletebyquery.py 需要 solrcloudpy，build.py 需要 bs4，purge.py 需要 tqdm。

6.5：solr status 找不到进程

解决：Solr 以 systemd 托管时 solr status 用 PID 文件判断；若未找到进程，用 ps -ef | grep [j]ava 与 netstat -tlnp | grep 8983 复核，必要时 systemctl restart solr。

七、参考链接