Shaper 0.26.4 裸机安装指南

在 Ubuntu 24.04 从零安装 Shaper 0.26.4 官方预编译二进制：下载安装、systemd 托管、启动验证与 JWT 管理员登录，含 GLIBC 版本/监听地址/DuckDB 锁文件踩坑实录与 pip、npm 备用方案。

ShaperDuckDBGo2026/10/30

Shaper 0.26.4 裸机安装指南

目标：在一台全新的 Ubuntu 24.04 LTS 服务器上从零安装 Shaper v0.26.4（官方预编译二进制），完成数据目录规划、systemd 托管、启动验证与 JWT 管理员登录，最终得到一个可访问 http://<服务器IP>:5454 的自托管分析仪表盘服务。本文全部命令与回显均在 Ubuntu 24.04 x86_64 实测通过（2026-10-30），并提供 pip 与 npm 两种备用安装方案。

一、环境信息

本文实测环境与目标形态：

  • 操作系统：Ubuntu 24.04 LTS（x86_64，GLIBC 2.39）
  • 软件版本：Shaper 0.26.4（官方最新稳定版，2026-10-30 查询）
  • 部署形态：单二进制裸机部署，systemd 托管
  • Web 端口：5454（Shaper 默认端口）
  • 数据目录：/var/lib/shaper（本指南规划的专用数据目录）
  • 二进制安装位置：/opt/shaper，可执行文件软链至 /usr/local/bin/shaper
  • 运行用户：root（演示环境；生产建议独立系统用户）

二、前置条件

安装前确认系统满足以下条件，逐项给出验证命令：

1. 系统架构与 GLIBC 版本（Shaper 预编译二进制要求 GLIBC ≥ 2.38，Ubuntu 24.04 的 2.39 满足）：

ldd --version | head -1

实测回显：

ldd (Ubuntu GLIBC 2.39-0ubuntu8.4) 2.39

2. 基础下载工具（curl 与 tar，Ubuntu 24.04 最小安装自带，缺失则补装）：

apt-get update && apt-get install -y curl ca-certificates

3. 端口确认（5454 未被占用；如被占用请规划其他端口并在启动参数中同步修改）：

ss -ltn | grep 5454 || echo "port 5454 free"

实测回显：

port 5454 free

⚠️ 注意：PDF/PNG 导出功能依赖 headless Chrome（官方文档 Chrome Dependency 章节）。基础部署与仪表盘查询不需要 Chrome，可在需要导出图片/PDF 时再安装（见「十一、常见问题」11.3）。

三、版本选型说明

1. 版本实查：本文撰写时（2026-10-30）Shaper 最新稳定 tag 为 v0.26.4，与 npm 官方包 @taleshape/shaper latest 版本、PyPI 包 shaper-bin 版本一致（三渠道交叉核对）。版本查询方法：

# 查询官方 npm 包最新版本（镜像站与官方源数据一致）
curl -s https://registry.npmmirror.com/@taleshape/shaper/latest | grep -o '"version":"[^"]*"'

实测回显：

"version":"0.26.4"

2. 渠道对照：

渠道产物适用场景
GitHub Releasesshaper 各平台二进制（含 SHA256 校验和）官方主渠道，需能访问 GitHub
npm 平台包@taleshape/shaper-linux-x64 等 optional dependency 包，内含同一二进制GitHub 不可达时的实测可用替代
PyPI 包 shaper-bin / npm 包 @taleshape/shaper安装器包，按平台拉取上述二进制本地开发、版本托管
官方 Docker 镜像 taleshape/shaper内置 Chrome 的完整运行环境需要开箱即用的导出功能

⚠️ 网络说明：本环境实测时 GitHub Releases 直连与代理均不可达（HTTP 000），改从官方 npm 平台包镜像站（registry.npmmirror.com）下载二进制 tarball，该包由 Shaper 官方发布、与 GitHub Releases 为同一产物（npm 安装器的 get-binary.js 逻辑即从该平台包取二进制），实测下载/解压/运行全程可用。

3. 平台支持：官方仅发布 Linux 与 macOS 的 AMD64/ARM64 二进制（npm 平台包清单：darwin-arm64/darwin-x64/linux-arm64/linux-x64），Windows 无官方二进制。

四、方案 A：官方预编译二进制安装（推荐主线）

4.1 方案说明

从官方发布渠道下载 linux-x64 平台的 Shaper 0.26.4 二进制 tarball，解压到 /opt/shaper 并软链进 PATH。该方案无任何运行时依赖（单二进制内嵌 DuckDB/NATS），是服务器部署的最轻路径。

4.2 下载二进制

创建工作目录并下载官方平台包（URL 实测可达，40MB 级别，耐心等待）：

mkdir -p /opt/data/shaper-pkg && cd /opt/data/shaper-pkg
curl -sL https://registry.npmmirror.com/@taleshape/shaper-linux-x64/-/shaper-linux-x64-0.26.4.tgz -o shaper-linux-x64-0.26.4.tgz

说明：能直连 GitHub 的环境可直接到 https://github.com/taleshape-com/shaper/releases 页面（tag v0.26.4）下载二进制并按官方建议核对 SHA256 校验和；两种渠道产物一致。

核对包内容与体积（实测）：

ls -la && tar tzf shaper-linux-x64-0.26.4.tgz

实测回显：

-rw-r--r-- 1 root root 40329795 Oct 30 10:34 shaper-linux-x64-0.26.4.tgz
package/LICENSE
package/bin/shaper
package/package.json
package/README.md

4.3 解压与安装

解压到 /opt/shaper，赋予执行权限并软链进 PATH：

mkdir -p /opt/shaper
tar xzf shaper-linux-x64-0.26.4.tgz -C /opt/shaper
chmod +x /opt/shaper/package/bin/shaper
ln -sf /opt/shaper/package/bin/shaper /usr/local/bin/shaper

验证版本（实测）：

shaper version 2>/dev/null || shaper --version

实测回显：

shaper version 0.26.4

⚠️ 排障实录：若在 Ubuntu 22.04（GLIBC 2.35）等老发行版执行，会直接报错 shaper: /lib/x86_64-linux-gnu/libm.so.6: version 'GLIBC_2.38' not found (required by shaper)。这是预编译二进制的 glibc 硬要求，解决办法只有两条：升级到 Ubuntu 24.04+/Debian 13+，或改用官方 Docker 镜像 taleshape/shaper。

4.4 创建数据目录

规划专用数据目录（存放 DuckDB 库、SQLite 状态、NATS JetStream 数据）：

mkdir -p /var/lib/shaper

确认 Shaper 内嵌组件即将写入的文件布局（首次启动后可见，见 4.6）。

4.5 首次启动

前台启动做首次冒烟验证（--addr 0.0.0.0:5454 绑定全部网卡，--dir 指定数据目录）：

shaper --addr 0.0.0.0:5454 --dir /var/lib/shaper

实测启动日志（节选）：

time=2026-10-30T02:34:54.769Z level=INFO msg="nats: Starting nats-server"
time=2026-10-30T02:34:54.769Z level=INFO msg="nats:   Version:  2.15.1"
time=2026-10-30T02:34:54.770Z level=INFO msg="nats: Starting JetStream"
time=2026-10-30T02:34:54.770Z level=INFO msg="nats:   Store Directory: \"/var/lib/shaper/nats/jetstream\""
time=2026-10-30T02:34:54.778Z level=INFO msg="Loaded scheduled tasks"
time=2026-10-30T02:34:54.778Z level=INFO msg="Snapshots disabled"
time=2026-10-30T02:34:54.779Z level=INFO msg="Web server is listening at 0.0.0.0:5454"
time=2026-10-30T02:34:54.779Z level=INFO msg="Open http://0.0.0.0:5454 in your browser"

日志要点：内嵌 NATS 2.15.1 + JetStream 随主进程启动；未配置 S3 快照桶时自动提示 Snapshots disabled；最后一行确认 Web 端口监听成功。

⚠️ 注意：--addr 默认值是 localhost:5454，只监听本机回环。生产部署必须显式传 --addr 0.0.0.0:5454（或经反向代理转发），否则外部浏览器无法访问——这是 Shaper 新手部署最常见的「服务起了但打不开」问题。

4.6 验证运行

另开终端做三项验证（服务保持运行）：

1. 数据目录布局（实测，DuckDB/SQLite/NATS 三个内嵌部件就位）：

ls -la /var/lib/shaper

实测回显：

total 324
drwxr-xr-x 4 root root   4096 Oct 30 02:34 .
drwxr-xr-x 9 root root   4096 Oct 30 02:34 ..
-rw-r--r-- 1 root root  77824 Oct 30 02:39 shaper.duckdb
-rw-r--r-- 1 root root 114688 Oct 30 02:39 shaper_internal.sqlite
drwxr-xr-x 4 root root   4096 Oct 30 02:34 nats

2. Web 首页与健康检查：

curl -s -o /dev/null -w "index %{http_code}\n" http://localhost:5454/
curl -s -o /dev/null -w "healthcheck %{http_code}\n" http://localhost:5454/healthcheck

实测回显：

index 200
healthcheck 200

3. 管理接口未认证时应返回 401（认证打通见「九、首次登录验证」）：

curl -s -o /dev/null -w "api %{http_code}\n" http://localhost:5454/api/schema

实测回显：

api 401

4.7 停止进程

冒烟验证结束后停掉前台进程，为 systemd 托管让路（Ctrl+C 或）：

pkill -x shaper

⚠️ 排障实录：重启 Shaper 前务必确认旧进程已完全退出（ps -ef | grep [s]haper），否则新进程会因 DuckDB 文件锁报错退出：IO Error: Could not set lock on file "/var/lib/shaper/shaper.duckdb": Conflicting lock is held in /opt/shaper/package/bin/shaper (PID 48)。DuckDB 为单写者锁，同一数据目录同时只能有一个 Shaper 进程。

五、方案 B：pip / pipx 安装

5.1 方案说明

官方 PyPI 包 shaper-bin 面向已有 Python 环境的本地开发场景：pip 负责按平台下载二进制并托管版本，最终 PATH 中得到的仍是同一个 shaper 二进制。适合个人开发机快速上手，不建议作为生产部署主形态（版本生命周期与 Python 虚拟环境绑定）。

5.2 安装步骤

# 方式一：pipx（推荐，隔离环境）
pipx install shaper-bin
# 方式二：pip（装入当前环境）
pip install shaper-bin

验证：

shaper --version

预期输出 shaper version 0.26.4（与二进制方案一致）。更新只需重跑安装命令，pip 会拉取最新版。

六、方案 C：npm 安装

6.1 方案说明

官方 npm 包 @taleshape/shaper 面向 Node.js 项目：包本身是轻量启动器（bin/shaper.js），真正的二进制由平台子包（如 @taleshape/shaper-linux-x64）以 optional dependencies 形式分发。适合前端/全栈团队把 Shaper 纳入 npm 依赖统一管理。

6.2 安装步骤

# 方式一：npx 免安装试用
npx @taleshape/shaper --help
# 方式二：全局安装
sudo npm install -g @taleshape/shaper

验证：

shaper --version

预期输出 shaper version 0.26.4。官方提示：重跑安装命令即可升级到最新版。

七、多方案对比与选择建议

维度方案 A 二进制方案 B pip/pipx方案 C npm
是否需运行时依赖无Python/pipNode.js/npm
版本管理手动（替换二进制）pip 托管npm 托管
升级方式重新下载替换 + 重启重跑 pipx/pip install重跑 npm install -g
systemd 托管友好度最高（直指二进制路径）中（需定位 venv 内路径）中（需定位全局 bin 路径）
适用场景生产服务器开发机Node 技术栈团队

选择建议：生产环境一律选方案 A（路径确定、无运行时耦合、systemd 直接托管）；方案 B/C 面向本地开发与仪表盘文件编辑（配合 shaper dev/preview 工作流，见《Shaper 0.26.4 常用 CLI 命令与运维实操》）。

八、systemd 托管（生产运行形态）

把冒烟验证通过的服务固化为 systemd 单元。创建 /etc/systemd/system/shaper.service：

[Unit]
Description=Shaper embedded analytics platform
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
ExecStart=/usr/local/bin/shaper --addr 0.0.0.0:5454 --dir /var/lib/shaper
Restart=on-failure
RestartSec=5
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target

逐项说明：--addr 0.0.0.0:5454 显式绑定全部网卡（默认 localhost 会导致外部不可访问）；--dir /var/lib/shaper 数据目录与冒烟验证一致；Restart=on-failure 进程异常退出 5 秒后自动拉起；LimitNOFILE=65536 保障内嵌 NATS/DuckDB 的文件句柄余量。认证、快照等更多参数的注入方式（Environment= 或配置文件）见《Shaper 0.26.4 配置参数详解》。

⚠️ 注意：systemd 托管需要带 systemd 的 Linux 真机（Ubuntu 24.04 服务器默认满足）。

启用并启动（每行一个单元）：

systemctl daemon-reload
systemctl enable shaper
systemctl start shaper

验证服务状态：

systemctl is-active shaper

预期输出：

active

九、首次登录验证（JWT SSO 管理员打通）

Shaper 不内置用户名密码注册，管理界面登录走 JWT SSO（官方 Single Sign-On 文档）：用户由外部登录端点认证后，用与 Shaper 相同的 --jwt-secret 签发含 userId（必填）、userEmail、userName（选填）三个 claim 的 JWT，浏览器经 页面URL#token=<jwt> 进入。本节用最小脚本验证「签发 → 认证 → 访问管理 API」全链路，为无现成 IdP 的环境提供自托管最小方案。

1. 以固定密钥启动服务（在 systemd 的 ExecStart 中追加，或测试环境直接前台启动）：

shaper --addr 0.0.0.0:5454 --dir /var/lib/shaper --jwt-secret q1w2e3r4

⚠️ 注意：q1w2e3r4 是本文演示环境的示例密钥（配合演示用户 root），生产环境务必替换为高强度随机值并纳入密钥管理。

2. 用 Python 标准库签发演示管理员 JWT（HS256，claims：userId=root）：

# /opt/data/jwt_sign.py —— HS256 手工签名，无第三方依赖
import base64, hashlib, hmac, json, time

def b64(d):
    return base64.urlsafe_b64encode(d).rstrip(b'=')

secret = b'q1w2e3r4'
header = b64(json.dumps({"alg": "HS256", "typ": "JWT"}).encode())
payload = b64(json.dumps({
    "userId": "root",
    "userEmail": "root@shaper.local",
    "userName": "root",
    "exp": int(time.time()) + 86400
}).encode())
sig = b64(hmac.new(secret, header + b'.' + payload, hashlib.sha256).digest())
print((header + b'.' + payload + b'.' + sig).decode())

实测执行与浏览器免登地址拼接：

TOKEN=$(python3 /opt/data/jwt_sign.py)
echo "http://<服务器IP>:5454/#token=$TOKEN"

3. 用该 JWT 调用管理 API 验证认证生效（/api/schema 返回内嵌 DuckDB 库结构）：

TOKEN=$(python3 /opt/data/jwt_sign.py)
curl -s -H "Authorization: Bearer $TOKEN" http://localhost:5454/api/schema

实测回显（节选，空库状态）：

{
  "databases": [
    {
      "name": "shaper",
      "schemas": [
        {
          "name": "main",
          "tables": [],
          "views": [],
          "enums": []
        }
      ]
    }
  ]
}

浏览器侧把第 2 步输出的完整 URL 粘贴到地址栏回车，即以 root 身份进入仪表盘工作台。API Key 的生成（UI Admin 区）与 Bearer 用法见《Shaper 0.26.4 常用 CLI 命令与运维实操》。

十、升级与多版本管理

  • 升级：下载新版本 tarball → 解压到 /opt/shaper-v<新版本> → 停服务（systemctl stop shaper）→ 切换软链 ln -sf /opt/shaper-v<新版本>/package/bin/shaper /usr/local/bin/shaper → systemctl start shaper。数据目录由 --dir 独立于二进制，升级不动数据；
  • 回滚：把软链切回旧版本目录后重启即可（Shaper 0.x 阶段建议升级前备份 /var/lib/shaper 全目录）；
  • 多版本共存：按 /opt/shaper-v<版本> 目录命名保留多个解压目录，用软链切换，验证 shaper --version 确认生效。

十一、常见问题（FAQ）

Q1：启动报 version 'GLIBC_2.38' not found？ 预编译二进制要求 GLIBC ≥ 2.38（实测 Ubuntu 22.04 的 GLIBC 2.35 必现该错）。解决：升级到 Ubuntu 24.04/Debian 13+，或改用官方 Docker 镜像 taleshape/shaper（内置兼容运行环境与 Chrome）。

Q2：服务已启动，浏览器打不开 5454？ 默认 --addr localhost:5454 只监听回环。加 --addr 0.0.0.0:5454 重启；云服务器还需放行安全组 5454 端口（生产建议反向代理 + TLS 后仅暴露 443）。

Q3：PDF/PNG 导出报 exec: "google-chrome": executable file not found in $PATH？ 裸机形态未装 Chrome（实测报错原文）。安装 Chromium/Google Chrome 后恢复；官方镜像已内置轻量 Chrome。该错误可在服务日志中检索 failed to generate png 定位。

Q4：重启报 Conflicting lock is held (PID 48) 类错误？ 旧进程未退出仍持有 DuckDB 文件锁（实测 PID 48 案例）。pkill -x shaper 后确认进程消失再启动；systemd 形态用 systemctl restart shaper 由单元管理生命周期，可避免手工时序问题。

Q5：/api/schema 等 API 返回 401？ 管理 API 默认要求认证（实测未认证即 401，日志报 missing or malformed jwt）。按「九、首次登录验证」签发 JWT 携带 Authorization: Bearer 头，或在 UI 中生成 API Key。

Q6：日志出现 Snapshots disabled 是故障吗？ 不是。未配置 --snapshot-s3-bucket 时的正常提示，快照功能详见《Shaper 0.26.4 配置参数详解》。

十二、卸载与清理

systemctl stop shaper && systemctl disable shaper   # 停止并禁用服务（先 stop 后 disable，每行一个单元见上）
rm -f /etc/systemd/system/shaper.service && systemctl daemon-reload
rm -f /usr/local/bin/shaper                          # 移除软链
rm -rf /opt/shaper /var/lib/shaper                   # 移除二进制与数据（数据删除前先确认已备份）

十三、参考链接

  1. 官方安装文档：https://taleshape.com/shaper/docs/installing-shaper/
  2. 官方 Single Sign-On 文档：https://taleshape.com/shaper/docs/single-sign-on/
  3. 官方 GitHub Releases：https://github.com/taleshape-com/shaper/releases
  4. 官方 npm 平台包：https://www.npmjs.com/package/@taleshape/shaper-linux-x64
  5. 本专栏篇章：《Shaper 介绍与选型指南》 、《Shaper 0.26.4 配置参数详解》 、《Shaper 0.26.4 常用 CLI 命令与运维实操》
  6. 数据引擎背景：《DuckDB 1.5 介绍与选型指南》