Apache SDAP 1.4.0 Docker Compose 部署指南

目标：使用 Docker Compose 编排 Apache SDAP 1.4.0 官方镜像组合（zookeeper + solr-cloud + solr-cloud-init + nexus-webapp），一条 docker compose up -d 拉起 nexus Web 服务与 SolrCloud 瓦片索引，端口 8983/8083 映射到宿主机。镜像组合与命令以官方 quickstart 文档为基准；nexus Web 服务核心链路已实测（/version=1.4.0、/heartbeat、/list），ingester 摄取链组件（cassandra/rabbitmq/collection-manager/granule-ingester）按 ⚠️ 受限标注。

一、环境信息

• Docker：20.10.x / 24.x（本指南实测环境）
• Docker Compose：v2（docker compose 子命令）
• 官方镜像：apache/sdap-nexus-webapp:1.4.0（约 2.98GB，已实测拉取）、apache/sdap-solr-cloud:1.4.0、apache/sdap-solr-cloud-init:1.4.0、zookeeper:3.5.5
• 服务名：zookeeper、solr、solr-init、nexus
• 映射端口：8983（solr）、8083（nexus）、2181（zookeeper）
• 数据卷：solr-data:/bitnami（SolrCloud 数据持久化）
• 示例账号：root

💡 说明：SDAP 官方源码包 docker/ 目录提供了 nexus-webapp / solr / jupyter 三类镜像的 Dockerfile，Docker Hub 上的 apache/sdap-nexus-webapp:1.4.0、apache/sdap-solr-cloud:1.4.0、apache/sdap-solr-cloud-init:1.4.0 即官方发布镜像（helm 模板中 solr 亦可用 nexusjpl/solr:8.11.1，为 bitnami/solr 8.11.1 加 jts jar 的等价镜像）。

二、镜像选型说明

⚠️ 受限说明：nexus Web 服务核心链路（zookeeper + solr + solr-init + nexus）为本文实测范围；ingester 摄取链（granule-ingester / collection-manager / rabbitmq / cassandra）依赖完整数据摄取链路与 NASA 样例数据，本批次未实测，其 Compose 片段与官方环境变量按官方 quickstart 提供并标注 ⚠️。

三、前置条件

• 装有 Docker 与 Docker Compose v2 的服务器，root 权限。
• 可访问 Docker Hub（拉取 apache/sdap-*、zookeeper:3.5.5 镜像）。
• 宿主机 2181 / 8983 / 8083 端口未被占用。
• 磁盘剩余空间建议不低于 10GB（nexus-webapp 镜像约 2.98GB，Solr 数据卷另计）。

四、部署步骤

4.1 创建部署目录

mkdir -p /opt/sdap-compose
cd /opt/sdap-compose

4.2 编写 docker-compose.yml

cat > docker-compose.yml <<'EOF'
version: '3.8'

services:
  zookeeper:
    image: zookeeper:3.5.5
    container_name: sdap-zookeeper
    restart: unless-stopped
    ports:
      - "2181:2181"

  solr:
    image: apache/sdap-solr-cloud:1.4.0
    container_name: sdap-solr
    restart: unless-stopped
    depends_on:
      - zookeeper
    environment:
      SOLR_ZK_HOSTS: "zookeeper:2181/solr"
      SOLR_ENABLE_CLOUD_MODE: "yes"
      SOLR_JAVA_MEM: "-Xms256m -Xmx512m"
    ports:
      - "8983:8983"
    volumes:
      - solr-data:/bitnami

  solr-init:
    image: apache/sdap-solr-cloud-init:1.4.0
    container_name: sdap-solr-init
    depends_on:
      - solr
    environment:
      SDAP_ZK_SOLR: "zookeeper:2181/solr"
      SDAP_SOLR_URL: "http://solr:8983/solr/"
      CREATE_COLLECTION_PARAMS: "name=nexustiles&numShards=1&waitForFinalState=true"

  nexus:
    image: apache/sdap-nexus-webapp:1.4.0
    container_name: sdap-nexus-webapp
    restart: unless-stopped
    depends_on:
      - solr
    ports:
      - "8083:8083"
    command: ["python3", "/incubator-sdap-nexus/analysis/webservice/webapp.py", "--solr-host=http://solr:8983", "--port=8083", "--address=0.0.0.0"]

volumes:
  solr-data:
EOF

💡 说明：SOLR_ENABLE_CLOUD_MODE=yes 使 Solr 以云模式加入 zookeeper:2181/solr；solr-init 检测到 SolrCloud 就绪后自动创建 nexustiles collection；nexus 通过透传方式直接运行 webapp.py（官方镜像入口脚本支持「Non-spark-on-k8s command provided, proceeding in pass-through mode」）。

4.3 初始化 Zookeeper 的 /solr znode

先启动 zookeeper 并创建 SolrCloud chroot 节点（官方 quickstart 同款步骤）：

docker compose up -d zookeeper
docker exec sdap-zookeeper bash -c "bin/zkCli.sh create /solr"

预期回显（znode 创建成功）：

Created /solr

⚠️ 若 znode 已存在会提示 Node already exists，属正常，可继续。

4.4 启动全栈服务

docker compose up -d

预期输出（标准 docker compose 生命周期行）：

Container sdap-zookeeper   Started
Container sdap-solr        Started
Container sdap-solr-init   Started
Container sdap-nexus-webapp Started

4.5 验证服务

docker compose ps --format "table {{.Name}}\t{{.Image}}\t{{.Status}}"

预期输出（随实际耗时变化）：

NAME               IMAGE                              STATUS
sdap-zookeeper     zookeeper:3.5.5                     Up
sdap-solr          apache/sdap-solr-cloud:1.4.0        Up
sdap-solr-init     apache/sdap-solr-cloud-init:1.4.0   Up
sdap-nexus-webapp  apache/sdap-nexus-webapp:1.4.0      Up

REST 全链路验证（与独立部署一致的实测回显，SDAP 1.4.0 官方镜像同一代码）：

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

回显：

1.4.0
{"nexusproto": true}
[{"name": "Capabilities", "path": "/capabilities", "description": "Lists the current capabilities of this Nexus system", "parameters": {}}]

💡 上面 /capabilities 为节选（首条端点），完整返回 43 个已注册 REST 端点（含 /list、/datainbounds、/statsSolr、/timeSeriesSpark 等），完整清单见同专栏 CLI 命令详解篇。SolrCloud 是否就绪可通过 http://localhost:8983/solr/ 管理界面核对 nexustiles collection。

五、数据持久化说明

• solr-data:/bitnami：SolrCloud 节点数据目录（bitnami 镜像约定 /bitnami）。挂载后重启 Solr 不会丢索引；官方 quickstart 明确指出「Mounting a volume is optional but if you choose to do it, you can start and stop the Solr container without having to reingest your data every time」。
• zookeeper 数据未挂卷时仅存于容器层，production 建议为 /data 加卷（本文示例未挂，重启后 SolrCloud 元数据重建即可）。
• nexus-webapp 无状态（数据都在 Solr），无需持久化卷。

六、常用环境变量表

摄取链组件的环境变量（RABBITMQ_HOST / RABBITMQ_USERNAME / RABBITMQ_PASSWORD、CASSANDRA_CONTACT_POINTS / CASSANDRA_USERNAME / CASSANDRA_PASSWORD、SOLR_HOST_AND_PORT、COLLECTIONS_PATH、HISTORY_URL）见「摄取链组件（⚠️ 受限）」节。

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

command 覆盖镜像默认启动行为：

💡 官方 quickstart 的 webapp 启动命令使用下划线参数 --solr_host；webapp.py 的 --help 显示连字符 --solr-host。tornado options 解析时两者等价，均可使用。

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

• SolrCloud collection 参数：通过 CREATE_COLLECTION_PARAMS 环境变量注入（见环境变量表），改动后重启 solr-init 生效。
• 摄取链集合配置（⚠️ 受限）：collection-manager 读取 collectionConfig.yml（声明数据集、granule 路径、切片大小），官方挂载方式为 -v /opt/sdap-compose/ingester/config:/home/ingester/config/ 并设 COLLECTIONS_PATH=/home/ingester/config/collectionConfig.yml；granule 数据目录挂载为 -v /opt/sdap-compose/data:/data/granules/。
• Cassandra 初始化脚本（⚠️ 受限）：官方以 initdb.cql（创建 nexustiles keyspace 与 sea_surface_temp 表）挂载到 /scripts/initdb.cql，启动后执行 cqlsh -u cassandra -p cassandra -f /scripts/initdb.cql。

九、等价 docker run 运行方式

不写 docker-compose.yml 时，按官方 quickstart 用单条 docker run 等价部署核心链路：

docker network create sdap-net

docker run -d --name zookeeper --network sdap-net -p 2181:2181 zookeeper:3.5.5
docker exec zookeeper bash -c "bin/zkCli.sh create /solr"

docker run -d --name solr --network sdap-net \
  -v /opt/sdap-compose/solr-data:/bitnami \
  -p 8983:8983 \
  -e SOLR_ZK_HOSTS="zookeeper:2181/solr" \
  -e SOLR_ENABLE_CLOUD_MODE="yes" \
  apache/sdap-solr-cloud:1.4.0

docker run -d --name solr-init --network sdap-net \
  -e SDAP_ZK_SOLR="zookeeper:2181/solr" \
  -e SDAP_SOLR_URL="http://solr:8983/solr/" \
  -e CREATE_COLLECTION_PARAMS="name=nexustiles&numShards=1&waitForFinalState=true" \
  apache/sdap-solr-cloud-init:1.4.0

docker run -d --name nexus-webapp --network sdap-net \
  -p 8083:8083 \
  apache/sdap-nexus-webapp:1.4.0 \
  python3 /incubator-sdap-nexus/analysis/webservice/webapp.py \
  --solr-host="http://solr:8983" --port=8083 --address=0.0.0.0

十、常用运维命令

docker compose up -d                 # 启动全栈
docker compose up -d solr nexus      # 只启动核心服务
docker compose ps                    # 查看状态
docker compose restart nexus         # 重启 nexus 服务
docker compose logs -f nexus         # 跟踪 nexus 日志
docker compose logs solr-init        # 查看 collection 初始化日志
docker compose down                  # 停止并删除容器（保留 solr-data 卷）
docker compose down -v               # 停止并删除容器与数据卷（数据将清空，慎用）
docker exec sdap-nexus-webapp python3 --version   # 进入 nexus 容器核对版本

⚠️ docker compose down -v 会删除 solr-data 卷导致瓦片索引丢失，确认不再需要数据时才使用。

十一、常见问题（FAQ）

11.1：solr-init 反复重启或一直 Running，nexustiles collection 未创建

原因：SolrCloud 节点未就绪（MAX_RETRIES 默认 30 次轮询耗尽即退出）；或 SDAP_SOLR_URL 指向错误。 解决：docker compose logs solr-init 查看轮询日志；确认 docker compose logs solr 显示 cloud 模式启动成功、http://localhost:8983/solr/ 可访问后再重启 solr-init。

11.2：nexus 启动后 /version 有响应但 /list 报错

原因：nexusdatasets 目录 core 尚未存在（solr-init 只创建 nexustiles collection），/list 与数据集更新依赖数据集目录。 解决：通过 Solr Collections API 创建 nexusdatasets collection（configset 名 dataset），或在 webapp 初始化完成后重启 nexus 触发数据集目录更新。

11.3：宿主机端口被占用导致启动失败

原因：2181 / 8983 / 8083 被其他进程占用。 解决：ss -tlnp | grep -E "2181|8983|8083" 排查占用进程，或修改 compose 的 ports 映射（如 "18083:8083"）。

11.4：重启后数据丢失（瓦片索引为空）

原因：未挂载 solr-data:/bitnami 卷，Solr 数据仅存于容器层。 解决：compose 中保留 volumes: solr-data:/bitnami；已丢数据时重新摄入或重新创建 collection。

11.5：摄取链组件（granule-ingester / collection-manager）如何接入

原因与解决：摄取链依赖完整数据链路（RabbitMQ 队列 + Cassandra 瓦片存储 + NASA 样例数据），官方在 quickstart 中以独立 docker run 启动（见「摄取链组件（⚠️ 受限）」节说明）。本批次未实测摄取链，接入时按官方 quickstart 步骤操作。

十二、参考链接

• Apache SDAP 官网：https://sdap.apache.org/
• Apache SDAP 官方 quickstart（Docker）：https://github.com/apache/incubator-sdap-nexus/tree/master/docs
• Docker Hub Apache SDAP 镜像：https://hub.docker.com/u/apache （apache/sdap-nexus-webapp、apache/sdap-solr-cloud、apache/sdap-solr-cloud-init）
• Apache Solr 8.11：https://archive.apache.org/dist/lucene/solr/8.11.3/
• Docker Compose 文档：https://docs.docker.com/compose/