Apache StreamPipes 0.98.0 Docker Compose 部署指南

目标：使用 Docker Compose 编排 Apache StreamPipes 0.98.0 官方六服务全栈（backend / ui / extensions-all-iiot 与 couchdb / influxdb / nats），一条 docker compose up -d 拉起平台，覆盖官方编排文件解析、环境变量注入、数据卷持久化、JVM 堆 256-512MB 验证与日常运维命令。以下命令与回显均为实际执行结果。

一、环境信息

Docker：29.8.1（本指南实测环境）
Docker Compose：v2（docker compose 子命令，实测版本 v5.5.1）
Apache StreamPipes：0.98.0（2025-11-28 发布，官方最新稳定版）
官方编排文件：源码包内 installer/compose/docker-compose.yml（本指南实测部署用文件）
项目名：streampipes（COMPOSE_PROJECT_NAME 指定），因此服务实例名为 streampipes-backend-1 等
网络：Compose 自动创建 spnet bridge 网络（官方 yaml 声明）
映射端口：仅 ui 的 80 → 8088 对外映射（官方刻意减少端口冲突面）
数据卷：backend（/root/.streampipes）、couchdb（/opt/couchdb/data）、influxdb（/var/lib/influxdb）、influxdb2（/var/lib/influxdb2）、nginx（/etc/nginx/）

二、镜像选型说明

镜像	说明
`apachestreampipes/backend:0.98.0`	核心后端（Spring Boot，Java 17 / Temurin 17.0.15+6），约 434MB，端口 8030
`apachestreampipes/ui:0.98.0`	Web 管理台（nginx），约 68.7MB，映射 80→8088
`apachestreampipes/extensions-all-iiot:0.98.0`	流水线元素扩展服务（IIoT 轻量元素集，实测注册 59 个元素），约 665MB，端口 8090
`couchdb:3.3.1`	元数据存储（实测 `"version":"3.3.1"`），端口 5984
`influxdb:2.6`	时序数据存储（实测 `InfluxDB v2.6.1`），端口 8086
`nats`	消息代理（实测 `nats-server: v2.15.1`），端口 4222

说明：官方仅发行 Docker 镜像，无独立二进制安装包；本指南使用官方镜像仓库 apachestreampipes 与官方编排文件部署。若需更完整的流水线元素集，官方另提供 installer/compose/docker-compose.kafka.yml（Kafka 消息形态，扩展服务为全量元素集）。

三、前置条件

装有 Docker（≥ 17.06，实测 29.8.1）与 Docker Compose v2 的服务器，root 权限。
服务器可访问 Docker Hub（网络受限时配置镜像加速，见「常见问题 Q1」）与 Apache 下载站（downloads.apache.org）。
浏览器（Chrome / Firefox / Edge）用于访问 Web 管理台。
磁盘空间：首次拉取 6 个镜像合计约 1.7GB，另需数据卷空间。

四、部署步骤

4.1 获取官方编排文件与 .env

官方编排文件随源码包发布（Apache 下载站），先下载 0.98.0 源码包：

mkdir -p /opt/streampipes
cd /opt/streampipes
wget -O apache-streampipes-0.98.0-source-release.zip \
  https://downloads.apache.org/streampipes/0.98.0/apache-streampipes-0.98.0-source-release.zip
wget -O apache-streampipes-0.98.0-source-release.zip.sha512 \
  https://downloads.apache.org/streampipes/0.98.0/apache-streampipes-0.98.0-source-release.zip.sha512
sha512sum -c apache-streampipes-0.98.0-source-release.zip.sha512

真实回显（校验通过，OK 于文件末尾）：

apache-streampipes-0.98.0-source-release.zip: OK

解压并把编排文件复制到工作目录：

unzip -q apache-streampipes-0.98.0-source-release.zip
cp apache-streampipes-0.98.0/installer/compose/docker-compose.yml .

编写环境变量文件 .env（官方默认值）：

cat > .env <<'EOF'
SP_VERSION=0.98.0
SP_DOCKER_REGISTRY=apachestreampipes
COMPOSE_PROJECT_NAME=streampipes
SP_INFLUX_INIT_MODE=setup
EOF

💡 SP_INFLUX_INIT_MODE：全新安装用 setup；从 0.91.0 及更早版本升级迁移时改为 upgrade（官方 .env 注释说明）。COMPOSE_PROJECT_NAME 决定服务实例名前缀（本项目为 streampipes）。

4.2 官方 docker-compose.yml 解析

官方编排文件核心内容如下（不含 Apache License 注释头）：

# global logging
x-logging:
  &default-logging
  options:
    max-size: '12m'
    max-file: '5'
  driver: json-file

services:

  backend:
    image: "${SP_DOCKER_REGISTRY}/backend:${SP_VERSION}"
    depends_on:
      - couchdb
    environment:
      - SP_PRIORITIZED_PROTOCOL=nats
    volumes:
      - backend:/root/.streampipes
    logging: *default-logging
    restart: unless-stopped
    networks:
      spnet:

  ui:
    image: "${SP_DOCKER_REGISTRY}/ui:${SP_VERSION}"
    environment:
      - SP_HTTP_SERVER_ADAPTER_ENDPOINT=extensions-all-iiot:8090
    ports:
      - "80:8088"
    depends_on:
      - couchdb
      - backend
    volumes:
      - nginx:/etc/nginx/
    logging: *default-logging
    restart: unless-stopped
    networks:
      spnet:

  couchdb:
    image: couchdb:3.3.1
    environment:
      - COUCHDB_USER=admin
      - COUCHDB_PASSWORD=admin
    volumes:
      - couchdb:/opt/couchdb/data
    logging: *default-logging
    restart: unless-stopped
    networks:
      spnet:

  influxdb:
    image: influxdb:2.6
    environment:
      - INFLUXDB_DATA_ENGINE=tsm1
      - INFLUXDB_REPORTING_DISABLED=false
      - INFLUXDB_ADMIN_ENABLED=true
      - DOCKER_INFLUXDB_INIT_USERNAME=admin
      - DOCKER_INFLUXDB_INIT_PASSWORD=sp-admin
      - DOCKER_INFLUXDB_INIT_ADMIN_TOKEN=sp-admin
      - DOCKER_INFLUXDB_INIT_ORG=sp
      - DOCKER_INFLUXDB_INIT_BUCKET=sp
      - DOCKER_INFLUXDB_INIT_MODE=${SP_INFLUX_INIT_MODE}
    volumes:
      - influxdb:/var/lib/influxdb
      - influxdb2:/var/lib/influxdb2
    logging: *default-logging
    restart: unless-stopped
    networks:
      spnet:

  nats:
    image: nats
    restart: unless-stopped
    networks:
      spnet:

  # Lite version pipeline elements
  extensions-all-iiot:
    image: "${SP_DOCKER_REGISTRY}/extensions-all-iiot:${SP_VERSION}"
    logging: *default-logging
    restart: unless-stopped
    networks:
      spnet:

volumes:
  backend:
  couchdb:
  influxdb:
  influxdb2:
  nginx:

networks:
  spnet:
    driver: bridge

要点说明：

三个 StreamPipes 服务的镜像名由 .env 变量拼装：${SP_DOCKER_REGISTRY}/backend:${SP_VERSION} 即 apachestreampipes/backend:0.98.0。
backend 依赖 couchdb 启动；ui 依赖 couchdb 与 backend；influxdb 用 DOCKER_INFLUXDB_INIT_* 系列变量完成首次初始化（org/bucket 均为 sp，管理员 token 默认 sp-admin）。
日志统一走 json-file 驱动且限制 max-size: 12m、max-file: 5，避免日志无限膨胀。
所有服务 restart: unless-stopped，服务器重启后自动拉起。
官方刻意只映射 ui 的 80 端口（注释说明「减少端口冲突面」），backend 8030、influxdb 8086 等仅供内部网络互访。

4.3 一键启动全栈

docker compose up -d

真实回显（节选）：

 Container streampipes-couchdb-1  Started
 Container streampipes-influxdb-1  Started
 Container streampipes-nats-1  Started
 Container streampipes-backend-1  Started
 Container streampipes-extensions-all-iiot-1  Started
 Container streampipes-ui-1  Started

⚠️ 首次执行会从 Docker Hub 拉取全部 6 个镜像（backend 434MB、extensions-all-iiot 665MB 等，合计约 1.7GB），耗时取决于网络带宽；如超时见「常见问题 Q1」。

4.4 确认服务状态

docker compose ps

真实回显：

NAME                                IMAGE                                          COMMAND                  SERVICE               CREATED              STATUS              PORTS
streampipes-backend-1               apachestreampipes/backend:0.98.0               "java org.springfram…"   backend               About a minute ago   Up About a minute
streampipes-couchdb-1               couchdb:3.3.1                                  "tini -- /docker-ent…"   couchdb               2 minutes ago        Up About a minute   4369/tcp, 5984/tcp, 9100/tcp
streampipes-extensions-all-iiot-1   apachestreampipes/extensions-all-iiot:0.98.0   "java org.springfram…"   extensions-all-iiot   2 minutes ago        Up About a minute
streampipes-influxdb-1              influxdb:2.6                                   "/entrypoint.sh infl…"   influxdb              2 minutes ago        Up About a minute   8086/tcp
streampipes-nats-1                  nats                                           "/nats-server --conf…"   nats                  2 minutes ago        Up About a minute   4222/tcp, 6222/tcp, 8222/tcp
streampipes-ui-1                    apachestreampipes/ui:0.98.0                    "sh /docker-entrypoi…"   ui                    About a minute ago   Up About a minute   80/tcp, 0.0.0.0:80->8088/tcp, [::]:80->8088/tcp

4.5 验证 Web 管理台与登录

后台自动完成首次安装初始化（backend 日志可见 Auto-setup will start in 5000 milliseconds → Creating admin user...）。验证安装完成状态：

curl -s http://localhost/streampipes-backend/api/v2/setup/configured

回显：

{"configured":true}

用默认管理员登录（登录用户名为邮箱），返回 JWT：

curl -s -X POST http://localhost/streampipes-backend/api/v2/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin@streampipes.apache.org","password":"admin"}'

回显（accessToken 为完整 JWT 原文）：

{"accessToken":"eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhZG1pbkBzdHJlYW1waXBlcy5hcGFjaGUub3JnIiwiaWF0IjoxNzkxODQ5Njg5LCJleHAiOjE3OTE4NTA1ODksInVzZXIiOnsidXNlcm5hbWUiOiJhZG1pbkBzdHJlYW1waXBlcy5hcGFjaGUub3JnIiwiZGlzcGxheU5hbWUiOiJhZG1pbkBzdHJlYW1waXBlcy5hcGFjaGUub3JnIiwicm9sZXMiOlsiUk9MRV9BRE1JTiJdLCJzaG93VHV0b3JpYWwiOnRydWUsImRhcmtNb2RlIjpmYWxzZSwiaGFzQWNrbm93bGVkZ2VkIjpmYWxzZSwibGFuZ3VhZ2UiOm51bGx9fQ.RAmpm4WYZRPq7wSyMt27hvGfxK5hm2J3-2EDGvTwoFo"}

浏览器打开 http://<服务器IP>/ 即可进入 Web 管理台。

⚠️ 默认管理员账号：admin@streampipes.apache.org / admin（登录用户名是邮箱，不是 admin）。首次登录后请在管理台修改密码，示例演示账号按惯例可改为 q1w2e3r4 等强口令。

4.6 JVM 堆 256-512MB 验证

backend 与 extensions-all-iiot 默认无显式堆参数（实测 cmdline 仅 java org.springframework.boot.loader.launch.JarLauncher）。生产建议把堆限制在 256-512MB，编写 docker-compose.override.yml 注入：

services:
  backend:
    environment:
      - JAVA_TOOL_OPTIONS=-Xms256m -Xmx512m
  extensions-all-iiot:
    environment:
      - JAVA_TOOL_OPTIONS=-Xms256m -Xmx512m

重建后核对生效值（日志回显）：

docker compose up -d
docker compose logs backend | grep "Picked up"

真实回显：

Picked up JAVA_TOOL_OPTIONS: -Xms256m -Xmx512m

同时可用系统信息接口核对堆：

TOKEN=$(curl -s -X POST http://localhost/streampipes-backend/api/v2/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin@streampipes.apache.org","password":"admin"}' \
  | python3 -c 'import json,sys; print(json.load(sys.stdin)["accessToken"])')
curl -s http://localhost/streampipes-backend/api/v2/info/system -H "Authorization: Bearer $TOKEN"

真实回显（节选，totalMemoryKB 为 262144 即 256MB，对应 -Xms256m；注入前默认约 148MB）：

{"javaVmName":"OpenJDK 64-Bit Server VM","javaVmVendor":"Eclipse Adoptium","javaVmVersion":"17.0.15+6","osName":"Linux","osVersion":"6.8.0-138-generic","cpu":"","totalMemory":268435456,"freeMemory":129463648,"totalMemoryKB":262144,"freeMemoryKB":126429}

五、数据持久化说明

backend 卷挂在 /root/.streampipes：backend 配置与加密密钥等落盘，docker compose down 后重建不丢。
couchdb 卷挂在 /opt/couchdb/data：元数据库（adapterdescription、pipeline、users 等 14 个业务库）持久化。
influxdb（/var/lib/influxdb）与 influxdb2（/var/lib/influxdb2）卷：时序数据（data lake 存储）持久化。
nginx 卷挂在 /etc/nginx/：ui 的 nginx 配置持久化。
命名卷在 docker compose down（不带 -v）时保留；docker compose down -v 会连数据卷一并删除（清空平台数据，谨慎操作）。

实测持久化验证：docker compose restart backend 后登录接口仍正常返回用户数据，/api/v2/users 仍列出 admin 账号，证明元数据在卷中保留。

六、常用环境变量表

.env 文件（Compose 顶层变量，供 yaml 中 ${...} 引用）：

环境变量	说明	本指南值
`SP_VERSION`	StreamPipes 版本，决定三个镜像 tag	`0.98.0`
`SP_DOCKER_REGISTRY`	镜像仓库前缀	`apachestreampipes`
`COMPOSE_PROJECT_NAME`	Compose 项目名（服务实例名前缀）	`streampipes`
`SP_INFLUX_INIT_MODE`	InfluxDB 初始化模式：`setup`（新装）/ `upgrade`（从 0.91.0 前升级）	`setup`

服务级环境变量（官方 yaml 内置）：

环境变量	所属服务	说明
`SP_PRIORITIZED_PROTOCOL`	backend	消息协议优先级，`nats`
`SP_HTTP_SERVER_ADAPTER_ENDPOINT`	ui	HTTP 服务器适配器端点，`extensions-all-iiot:8090`
`COUCHDB_USER` / `COUCHDB_PASSWORD`	couchdb	元数据库管理员账号，默认 `admin` / `admin`
`INFLUXDB_DATA_ENGINE`	influxdb	时序存储引擎，`tsm1`
`DOCKER_INFLUXDB_INIT_USERNAME` / `_PASSWORD`	influxdb	首次初始化管理员账号，`admin` / `sp-admin`
`DOCKER_INFLUXDB_INIT_ADMIN_TOKEN`	influxdb	首次初始化管理员 token，`sp-admin`
`DOCKER_INFLUXDB_INIT_ORG` / `_BUCKET`	influxdb	初始化 org / bucket，均为 `sp`
`JAVA_TOOL_OPTIONS`	backend / extensions-all-iiot	JVM 参数（override 注入，见 4.6），`-Xms256m -Xmx512m`

💡 backend 与扩展服务还支持大量 SP_* 运行期变量（JWT 密钥、Kafka/NATS 地址、加密口令等），详见《Apache StreamPipes 0.98.0 配置参数详解》。

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

官方编排未自定义任何服务的 command，全部使用镜像默认启动命令（ps 的 COMMAND 列可见：backend / extensions-all-iiot 为 java org.springfram…，couchdb 为 tini -- /docker-ent… 等）。如需覆盖启动命令，在服务下追加：

  backend:
    command: ["java", "-Xms256m", "-Xmx512m", "org.springframework.boot.loader.launch.JarLauncher"]

说明：backend 与 extensions-all-iiot 的入口是 Spring Boot fat jar 的 org.springframework.boot.loader.launch.JarLauncher；覆盖 command 时可在此追加 JVM 参数（效果与 JAVA_TOOL_OPTIONS 注入相同，二选一即可，推荐优先用环境变量方式）。其余服务一般不需要覆盖启动命令。

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

backend 的可配置文件（application.yml 等）位于镜像内 /opt/streampipes/backend/conf/，默认值由镜像内嵌。如需持久化并随时修改配置而不重建镜像，追加 bind mount 覆盖：

services:
  backend:
    volumes:
      - backend:/root/.streampipes
      - ./backend-conf:/opt/streampipes/backend/conf:ro

⚠️ 官方编排不推荐直接改镜像内配置，优先用环境变量（SP_* / JAVA_TOOL_OPTIONS）调整；bind mount 覆盖需先 mkdir backend-conf 并把镜像内 conf 目录拷出作为基准，避免覆盖后缺文件导致启动失败。

九、等价 docker run（单服务手动启动）

不用 Compose 时，可用 docker run 等价拉起各服务。以 backend 为例（网络须先建好 spnet，且依赖 couchdb 已启动）：

docker network create spnet
docker run -d --name streampipes-backend-1 \
  --network spnet \
  -e SP_PRIORITIZED_PROTOCOL=nats \
  -v streampipes_backend:/root/.streampipes \
  -e JAVA_TOOL_OPTIONS=-Xms256m -Xmx512m \
  apachestreampipes/backend:0.98.0

说明：docker compose up -d 会自动创建网络与卷、按依赖顺序启动并统一日志策略，日常使用推荐 Compose 方式；docker run 仅在单服务排障或快速验证时使用（服务实例名需与官方命名一致 streampipes-<服务>-1 才能与既有编排互通）。

十、常用运维命令

cd /opt/streampipes

docker compose ps                 # 查看全栈状态
docker compose logs backend        # 查看 backend 日志（排障首选）
docker compose logs -f ui          # 跟踪 ui 日志
docker compose restart backend     # 重启单个服务
docker compose stop                # 停止全栈（保留数据卷）
docker compose start               # 重新启动全栈
docker compose down                # 停止并删除服务实例（保留数据卷）
docker compose down -v             # 连数据卷一并删除（清空平台数据，谨慎）
docker compose pull                # 仅拉取/更新镜像
docker compose up -d               # 启动（含重建，使 override/配置变更生效）

💡 配置变更（如 .env、override 或镜像更新）后需重新 docker compose up -d（必要时先 docker compose down 再 up）才能生效；仅改数据不影响编排的重启用 docker compose restart。

十一、常见问题

Q1：拉取镜像超时 / 报 request canceled while waiting for connection？ 定位：服务器到 Docker Hub（registry-1.docker.io）网络不通或过慢。解决：配置镜像加速（/etc/docker/daemon.json 的 registry-mirrors 数组，如 https://docker.1ms.run、https://docker.m.daocloud.io），重启 Docker 后重试 docker compose up -d。

Q2：登录返回 401 Unauthorized request to /api/v2/auth/login？ 定位：backend 日志出现 None or to many users with matching username，多为初始化未完成或用户名写错。解决：等首次安装完成（/api/v2/setup/configured 返回 {"configured":true}）；登录用户名必须用邮箱 admin@streampipes.apache.org。

Q3：浏览器打不开管理台？ 定位：ui 服务未就绪或 80 端口被占用。解决：docker compose ps 确认 streampipes-ui-1 为 Up 且 PORTS 列显示 0.0.0.0:80->8088/tcp；docker compose logs ui 排障。

Q4：docker compose up -d 报端口冲突？ 定位：80 端口已被其他程序占用（官方编排只映射 ui 的 80 端口）。解决：先 ss -lntp | grep :80 排查占用进程；或在 ui 服务下改为 ports: - "8080:8088" 等自定义映射。

Q5：需要重置平台数据重新安装？ 解决：docker compose down -v 连同数据卷一并删除后重新 docker compose up -d（注意清库，谨慎操作）。

Q6：backend 日志提示 Found 0 extensions？ 定位：backend 初始化时扩展服务尚未注册完成，属时序正常现象（实测后续 extensions-all-iiot 完成 REGISTERED/HEALTHY 状态流转）。解决：无需处理，初始化任务会自动等待并重试；最终以管理台能列出适配器/处理器为准。

十二、参考链接

Apache StreamPipes 官网：https://streampipes.apache.org/
下载页：https://downloads.apache.org/streampipes/
官方文档：https://streampipes.apache.org/docs/
GitHub 仓库：https://github.com/apache/streampipes
Docker Compose 文档：https://docs.docker.com/compose/