Apache StreamPipes 0.98.0 安装指南

目标：在 Ubuntu 22.04 服务器上从零部署 Apache StreamPipes 0.98.0 流式数据处理平台（backend / ui / extensions-all-iiot 三服务 + CouchDB / InfluxDB / NATS 三中间件全栈），覆盖官方发行形态说明、编排文件获取、一键启动、Web 管理台登录验证与卸载。以下命令与回显均在 Ubuntu 22.04.5 真实环境实测。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS（x86_64）
Apache StreamPipes：0.98.0（2025-11-28 发布，官方最新稳定版）
运行环境：Docker 29.8.1、Docker Compose v5.5.1（docker compose 子命令）
服务构成与端口：

服务	说明	端口
backend	核心后端（Spring Boot，Java 17）	8030
ui	Web 管理台（nginx）	宿主机 80 → 8088
extensions-all-iiot	流水线元素扩展服务（适配器/处理器/输出器）	8090
couchdb	元数据存储	5984
influxdb	时序数据存储	8086
nats	消息代理	4222

默认管理员账号：admin@streampipes.apache.org / admin（登录用户名为邮箱）
数据目录：backend 数据卷 /root/.streampipes、couchdb 数据卷 /opt/couchdb/data、influxdb 数据卷 /var/lib/influxdb2

二、版本选型说明

组件	版本	说明
Apache StreamPipes	0.98.0	2025-11-28 发布，官方最新稳定版
backend / ui / extensions-all-iiot 镜像	0.98.0	官方镜像仓库 `apachestreampipes/*`
couchdb	3.3.1	官方 CouchDB 镜像（实测 `"version":"3.3.1"`）
influxdb	2.6	官方 InfluxDB 2.x 镜像（实测 2.6.1）
nats	latest	官方 NATS 镜像（实测 `nats-server: v2.15.1`）

⚠️ 官方发行形态说明（前置说明）：Apache StreamPipes 官方仅以 Docker 形态发行——提供预构建镜像与官方 docker compose 编排文件（installer/compose/docker-compose.yml），没有独立的 Linux 二进制安装包、RPM/deb 包或 systemd 安装脚本。官方推荐的部署方式即「一条 docker compose up -d 拉起全栈」，安装即部署。以下步骤按官方形态给出完整流程。

三、前置条件

一台 Ubuntu 22.04 服务器，root 权限。
已安装 Docker（≥ 17.06 即可，实测 29.8.1）与 Docker Compose v2（实测 v5.5.1）。
服务器可访问 Docker Hub（如网络受限，需配置镜像加速，见「常见问题 Q1」）与 Apache 下载站（downloads.apache.org）。
浏览器（Chrome / Firefox / Edge）用于访问 Web 管理台。

四、部署步骤（官方 Docker 形态）

4.1 下载官方源码包（含官方编排文件）

官方编排文件随源码包发布，先下载 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

真实回显（文件大小与校验）：

total 18M
-rw-r--r-- 1 root root  18M Oct 12 21:25 apache-streampipes-0.98.0-source-release.zip
-rw-r--r-- 1 root root  128 Oct 12 21:25 apache-streampipes-0.98.0-source-release.zip.sha512
9b491580a4920dde3cf54b7fea1f0fd035690238f480c968bf82ad765cdbf584e558a3c1836d65189e5b6fabe30f0ce734812fce661a631156605ce3ad1f8292  apache-streampipes-0.98.0-source-release.zip

解压并确认编排文件：

unzip -q apache-streampipes-0.98.0-source-release.zip
ls apache-streampipes-0.98.0/installer/compose/

回显：

docker-compose.kafka.yml  docker-compose.minimal.yml  docker-compose.yml

4.2 准备编排文件与 .env

cp apache-streampipes-0.98.0/installer/compose/docker-compose.yml /opt/streampipes/
cd /opt/streampipes

编写环境变量文件 .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 注释说明）。

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），耗时取决于网络带宽。

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 管理台，使用该账号登录后可创建数据流、适配器与流水线。

4.6 验证版本与系统信息

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/versions \
  -H "Authorization: Bearer $TOKEN"

回显：

{"backendVersion":"0.98.0","itemVersions":[]}

curl -s http://localhost/streampipes-backend/api/v2/info/system -H "Authorization: Bearer $TOKEN"

回显（节选）：

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

五、配置说明

5.1 管理账号

默认管理员：admin@streampipes.apache.org / admin（0.98.0 源码默认值，登录用户名为邮箱）。
首次登录后请在管理台修改密码；示例演示账号按惯例可改为 q1w2e3r4 等强口令。
服务账号：sp-service-client / my-apache-streampipes-secret-key-change-me（供扩展服务调用后端 API）。

5.2 JVM 堆内存（256-512MB）

backend 与 extensions-all-iiot 均为 Java 17 进程（Spring Boot，入口 org.springframework.boot.loader.launch.JarLauncher），默认无显式堆参数。生产建议把堆限制在 256-512MB，在编排文件的环境变量区注入：

    environment:
      - JAVA_TOOL_OPTIONS=-Xms256m -Xmx512m

修改后重建服务并核对生效值（日志回显）：

Picked up JAVA_TOOL_OPTIONS: -Xms256m -Xmx512m

同时可用 GET /api/v2/info/system 的 totalMemory 核对堆：注入前约 155MB（151552KB），注入后 totalMemoryKB 为 262144（256MB，对应 -Xms256m）。详见《Apache StreamPipes 0.98.0 配置参数详解》4.9。

5.3 端口与访问

官方编排文件刻意只映射 ui 的 80 端口（注释说明「减少端口冲突面」），backend 8030 / influxdb 8086 等仅在内部网络供服务间互访。
如需对外暴露 backend REST API，在编排文件的 ui 服务旁给 backend 增加 ports: - "8030:8030"。

六、注意事项

首次启动自动安装（SP_INITIAL_WAIT_BEFORE_INSTALLATION_MS 默认 5000ms 后开始），约 10-20 秒完成建库与创建 admin 账号；期间 /api/v2/auth/login 可能返回 401，等待初始化完成即可。
登录用户名是邮箱 admin@streampipes.apache.org，不是 admin。
extensions-all-iiot 是官方「轻量版」流水线元素集，实测注册 59 个元素（Welford Change Detection、JavaScript Eval、Math Expression、Sensor Limit Alert 等）；需要更完整元素集可换用官方 docker-compose.kafka.yml（Kafka 消息形态）或自行构建 all-jvm 全量镜像。
官方编排未对 ui 之外的服务做端口映射；80 端口被占用时先排查。

七、常见问题

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

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

八、卸载方式

cd /opt/streampipes
docker compose down        # 停止并删除全部服务实例（保留数据卷）
docker compose down -v     # 如需连数据卷一并删除（清空平台数据）
rm -rf /opt/streampipes    # 删除源码包、编排文件与 .env

九、参考链接

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/