Apache StreamPipes 0.98.0 常用 CLI 命令与工具详解

目标：详解 Apache StreamPipes 0.98.0 的命令行工具——curl 调用平台 REST API（登录认证、安装状态、版本、系统信息、流水线、数据流、适配器、流水线元素、用户）、官方环境管理 CLI（streampipes 的 env/up/down/ps/logs/restart/stop/start/pull/info/clean 等子命令）以及 JVM 堆 256-512MB 的校验方法。所有回显均为真实环境实测。

一、环境信息

Apache StreamPipes：0.98.0（2025-11-28 发布）
REST API 基址：http://<服务器IP>/streampipes-backend/api/v2（ui 代理后端 REST；后端直连端口 8030）
默认管理员：admin@streampipes.apache.org / admin（登录用户名为邮箱）
认证方式：JWT（HMAC 签名，请求头 Authorization: Bearer $TOKEN）
官方环境管理 CLI：源码包 installer/cli/streampipes（0.98.0）

二、工具概览

工具	用途
`curl`	调用平台 REST API（管理台同款接口），登录/查状态/管理资源
`streampipes`（官方 CLI）	开发环境管理：选择环境模板、启动/停止/重启/日志/清理
日志 + REST 组合	校验配置生效值（如 JVM 堆）

三、登录与 JWT 认证

先取得 token（后续所有请求携带）：

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"])')
echo ${TOKEN:0:40}...

真实回显（截断展示）：

eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhZG1pbkBzdHJlYW1waXBlcy5hcGFjaGUub3JnIi...

⚠️ 登录用户名是邮箱 admin@streampipes.apache.org，不是 admin；JWT 默认有效期 15 分钟（实测 exp - iat = 900s），过期后重新登录取新 token。

四、平台 REST API 常用命令

4.1 安装状态（setup/configured）

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

真实回显：

{"configured":true}

true 表示首次安装初始化已完成（backend 日志可见 Creating admin user...）。

4.2 版本信息（info/versions）

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

真实回显：

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

4.3 系统信息（info/system）

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}

totalMemoryKB=262144 即 256MB 堆（对应 -Xms256m），用于校验 JVM 参数生效（见第六节）。

4.4 流水线（pipelines）

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

真实回显（全新安装无流水线）：

[]

4.5 数据流（streams）

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

真实回显（全新安装无数据流）：

[]

4.6 适配器（connect/master/adapters）

curl -s http://localhost/streampipes-backend/api/v2/connect/master/adapters \
  -H "Authorization: Bearer $TOKEN"

真实回显（全新安装无适配器实例）：

[]

💡 适配器实例在管理台「Connect」页创建；创建后本接口返回各适配器运行状态与配置。

4.7 流水线元素（sepas）

curl -s http://localhost/streampipes-backend/api/v2/sepas \
  -H "Authorization: Bearer $TOKEN" \
  | python3 -c 'import json,sys; d=json.load(sys.stdin); print(len(d)); print([e.get("name") for e in d[:6]])'

真实回显：

59
['Welford Change Detection', 'JavaScript Eval', 'Math Expression', 'Sensor Limit Alert', 'Quality Control Limits Enrichment', 'Math']

extensions-all-iiot 为官方轻量元素集（IIoT），实测注册 59 个元素；如需更全元素集换用 Kafka 消息形态编排（全量元素集）。

4.8 用户（users）

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

真实回显：

[{"principalId":"1328cf5b2eee44dbb4a2fd379ac87909","email":"admin@streampipes.apache.org","displayName":null}]

五、官方环境管理 CLI（streampipes）

官方在源码包 installer/cli/streampipes 提供环境管理 CLI（当前版本 0.98.0），面向开发与本地环境管理。它是底层环境编排命令的包装，把「环境模板选择 + 服务编排 + 生命周期管理」收敛为单一入口。用法：

cd apache-streampipes-0.98.0/installer/cli
./streampipes --help

真实回显（帮助节选）：

Usage: streampipes COMMAND [OPTIONS]

Options:
  --help, -h      show help
  --version, -v   show version

Commands:
  add         Add new StreamPipes service (e.g., adapter, processor, sink)
  clean       Remove StreamPipes data volumes, dangling images and network
  down        Stop and remove StreamPipes services
  env         Inspect and select StreamPipes environments
  info        Get information
  logs        Get logs for specific service
  ps          List all StreamPipes services of running environment
  pull        Download latest images from registry
  restart     Restart StreamPipes service
  start       Start StreamPipes service
  stop        Stop StreamPipes service
  up          Create and start StreamPipes service environment

5.1 环境模板（env）

./streampipes env --list
./streampipes env --inspect pipeline-element
./streampipes env --set pipeline-element
./streampipes env          # 查看当前已选环境

--list：列出可用环境模板（如 pipeline-element、backend 等）。
--inspect <模板>：查看该模板由哪些服务组成。
--set <模板>：选定环境（写入 .spenv），之后 up 按该模板拉起。
不带参数：显示当前环境。

5.2 启动与停止（up / down / start / stop / restart）

./streampipes up -d            # 创建并后台启动当前环境全栈
./streampipes up -d --no-ports # 生产模式：除 UI 端口外不映射端口
./streampipes up -d kafka couchdb  # 只启动模板中的指定服务
./streampipes down             # 停止并移除运行实例
./streampipes down -v          # 同时清理数据卷
./streampipes stop extensions-all-jvm
./streampipes start extensions-all-jvm
./streampipes restart backend couchdb        # 重启指定服务
./streampipes restart --force-create extensions-all-jvm  # 重建后重启

说明：up 默认 dev 模式（开放核心服务端口便于 IDE 联调）；不开端口映射用 --no-ports。restart 按服务名操作，--force-create 会先移除再重建运行实例。

5.3 状态查看（ps / logs / info）

./streampipes ps               # 列出当前环境全部运行实例（含状态）
./streampipes ps --all         # 含已停止实例
./streampipes logs backend     # 查看 backend 日志
./streampipes logs --follow backend   # 跟踪日志
./streampipes info             # 环境信息

排障首选 logs backend（初始化、注册、报错均打印于此）；ps 查看各服务运行状态与端口。

5.4 更新与清理（pull / clean / add）

./streampipes pull             # 拉取当前环境全部服务的最新镜像
./streampipes clean            # 清理数据卷、网络与悬空镜像
./streampipes clean --volumes  # 连同数据卷一并清理（清空数据，谨慎）
./streampipes add my-processor --image myrepo/myprocessor:0.68.0 --ports 8090:8090

add 用于把自研流水线元素加入本地服务目录（cli/deploy/standalone/my-processor/ 下的编排文件），--store lite --activate 可持久化登记并激活到当前环境；适合开发扩展元素时使用。

六、JVM 堆 256-512MB 校验

backend 与 extensions-all-iiot 为 Java 17 进程，生产建议把堆限制在 256-512MB。注入方式：在部署编排文件对应服务的 environment 区设置 JAVA_TOOL_OPTIONS=-Xms256m -Xmx512m（详见《Apache StreamPipes 0.98.0 配置参数详解》4.9）。校验分两步：

1）日志核对（启动时 JVM 打印）：

./streampipes logs backend | grep "Picked up"

真实回显：

Picked up JAVA_TOOL_OPTIONS: -Xms256m -Xmx512m

2）REST 系统信息核对（堆大小对应 -Xms）：

curl -s http://localhost/streampipes-backend/api/v2/info/system \
  -H "Authorization: Bearer $TOKEN" | python3 -c \
  'import json,sys; d=json.load(sys.stdin); print("totalMemoryKB =", d["totalMemoryKB"])'

真实回显（注入 256MB 后）：

totalMemoryKB = 262144

注入前默认约 148MB（151552KB）；两处回显一致说明堆参数已生效。

七、常见问题

Q1：curl 请求返回 401？ 定位：token 缺失、过期或用户名错误。解决：用邮箱 admin@streampipes.apache.org 重新登录取新 token，并确认所有请求带 Authorization: Bearer $TOKEN。

Q2：./streampipes 提示 command not found？ 定位：未给执行权限或未在源码包目录内。解决：chmod +x installer/cli/streampipes，用 ./installer/cli/streampipes 调用；或按官方 README 加入 PATH 并 source。

Q3：streampipes ps 看不到全部服务？ 定位：当前环境模板（.spenv）与运行的服务不一致。解决：streampipes env 查看当前环境，env --set <模板> 切换后用 up -d 拉起。

Q4：/api/v2/sepas 返回元素太少？ 定位：使用的是官方轻量元素集（extensions-all-iiot）。解决：需要更全元素集时换用官方 Kafka 消息形态编排（扩展服务为全量元素集）。

Q5：totalMemoryKB 没有变化？ 定位：JAVA_TOOL_OPTIONS 未注入对应服务或未重建。解决：确认环境变量加在 backend / extensions-all-iiot 两个服务，重新执行编排启动命令重建后重试校验。

八、参考链接

Apache StreamPipes 官网：https://streampipes.apache.org/
官方文档：https://streampipes.apache.org/docs/
源码仓库（installer/cli）：https://github.com/apache/streampipes/tree/rel/0.98.0/installer/cli
REST API 参考：https://streampipes.apache.org/docs/docs/streampipes-rest-api
下载页：https://downloads.apache.org/streampipes/