Shaper 0.26.4 常用 CLI 命令与运维实操

目标：把 Shaper 0.26.4 的 9 个 CLI 子命令逐一讲透并配实测回显，覆盖「本地编辑 → 校验 → 部署 → 拉取 → 健康巡检」的日常运维闭环，以及管理 REST API 的认证与调用实操。全部命令与回显在 Ubuntu 24.04 x86_64 + Shaper 0.26.4 实测通过（2026-10-30），命令均可独立执行。

一、环境信息

操作系统：Ubuntu 24.04 LTS（x86_64）
软件版本：Shaper 0.26.4（/opt/shaper/package/bin/shaper，软链 /usr/local/bin/shaper）
服务端：已按《Shaper 0.26.4 裸机安装指南》部署并运行，监听 0.0.0.0:5454，数据目录 /var/lib/shaper，启动参数含 --jwt-secret q1w2e3r4 与 --init-sql 建立的演示表 sales(day, channel, amount)
工作目录：/opt/shaper-work/（本文演示用仪表盘文件目录）
演示账号：JWT 用户 root（密钥 q1w2e3r4，仅演示环境）

二、工具概览

Shaper 是「单二进制 = 服务端 + CLI 工具箱」的形态：同一个二进制不带子命令就是服务器，带子命令就是本地开发/运维工具。子命令全景（shaper --help 实测回显的 SUBCOMMANDS 段）：

SUBCOMMANDS:
  dev          watch local dashboard files and show preview
  preview      create a temporary dashboard preview
  pull         pull dashboards from server to local files
  ids          add missing IDs to all dashboards in the configured directory
  deploy       Deploy dashboards from files using API key or user auth. Set SHAPER_DEPLOY_API_KEY to authenticate or log in.
  validate     Validate dashboards
  schema       Show database schema as Markdown
  login        log in to shaper server
  healthcheck  check the health of a shaper server

命令分工解读：

命令	运行位置	是否需服务在线	运维场景
dev / preview	本地开发机	否（内置预览服务）	编写仪表盘 SQL
ids / validate	本地	validate 校验 SQL 语法时需连服务	Git 提交前检查
deploy / pull	任意	是	生产发布与变更回读
schema	任意	是（连服务读库）	巡检数据结构
login / healthcheck	任意	是	凭据获取 / 存活巡检

三、前置条件

二进制可用：shaper --version 输出 shaper version 0.26.4；
服务端在线：shaper healthcheck 输出 OK（实测；命令详解见 5.8）；
工作目录就绪并完成一次性初始化（首次运行 CLI 子命令会交互式创建 shaper.json，实测两次回车用默认值即可）：

mkdir -p /opt/shaper-work && cd /opt/shaper-work
printf '\n\n' | shaper validate 2>/dev/null | head -5

实测回显（节选）：

Saved config to ./shaper.json

生成的 ./shaper.json 内容（实测，存储 CLI 工作流的连接信息）：

{
  "url": "http://localhost:5454",
  "watch_dir": "."
}

认凭据就位：deploy/pull 需要认证。两条路径——UI 生成 API Key 后导出 SHAPER_DEPLOY_API_KEY，或直接使用 JWT（实测 JWT 同样被接受，见 5.5）。本文用 JWT 文件方式：

# 签发脚本与密钥说明见[《Shaper 0.26.4 裸机安装指南》](https://www.quzuo.net/document/Fz4l4MK7FHPq)第九章（演示密钥 q1w2e3r4，claims userId=root）
python3 /opt/data/jwt_sign.py > /opt/shaper-work/.shaper-auth

⚠️ 注意：.shaper-auth 是明文凭据文件（preview/login/dev 的默认读取路径），纳入 .gitignore 并控制文件权限（chmod 600）。

四、演示仪表盘文件（.dashboard.sql）

Shaper 的仪表盘资产是带元数据注释头的 SQL 文件。创建首个文件：

cat > /opt/shaper-work/summary.dashboard.sql <<'EOF'
SELECT channel, COUNT(*) AS days, SUM(amount) AS total
FROM sales
GROUP BY channel
ORDER BY channel
EOF

文件此刻还缺资产 ID 注释头（-- shaperid:...），这是 Shaper 识别/同步仪表盘的身份键——由 shaper ids 补齐（见 5.4）。

五、各工具详解

5.1 shaper --version / --help

版本与帮助是每次运维动作前的例行确认：

shaper --version

实测回显：

shaper version 0.26.4

shaper --help

实测回显：输出 NAME/USAGE/FLAGS/SUBCOMMANDS 四段——USAGE 段含官方自述与三通道配置说明；FLAGS 段约 70 个参数含全部默认值；SUBCOMMANDS 段即本章目录。全文较长，参数逐域详解见《Shaper 0.26.4 配置参数详解》。

5.2 shaper schema

把服务端 DuckDB 的库结构导出为 Markdown 格式 DDL，巡检数据结构的快捷手段：

shaper schema

实测回显（节选）：

# Database Schema

## Database: shaper

### Schema: main

#### Tables

```sql
CREATE TABLE "shaper"."main"."sales" (
    "day" TIMESTAMP,
    "channel" VARCHAR,
    "amount" INTEGER
);


解读：库名 `shaper` 对应内嵌 DuckDB（`--duckdb` DSN 的默认库），表结构与服务端 `--init-sql` 建表一致。该命令适合放进巡检脚本比对「生产库结构 vs Git 中的预期 DDL」。

### 5.3 shaper validate

校验仪表盘文件（SQL 语法 + 元数据头完整性），Git 提交前与发布前的强制关卡：

```bash
cd /opt/shaper-work && shaper validate summary.dashboard.sql

首次校验的实测报错形态（缺 shaperid 头）：

Validating 1 dashboards...

❌ summary.dashboard.sql
   Error: missing shaperid comment. Run `shaper ids` to generate IDs for all apps.
validation failed for 1 dashboard(s)

补齐 ID 后再校验（实测）：

Validating 1 dashboards...

✅ summary.dashboard.sql (1ms)

All dashboards are valid!

解读：❌/✅ 与耗时逐文件列出，validation failed 时进程退出码非 0，可直接接入 CI 流水线作门禁。

5.4 shaper ids

为目录内全部仪表盘文件补齐缺失的资产 ID（24 位随机标识，本地生成、全局唯一）：

cd /opt/shaper-work && shaper ids

实测回显：

Adding missing IDs to apps in /opt/shaper-work...
Set id 'dppqrdiyne5e04nnr8z9xu7n' for file '/opt/shaper-work/summary.dashboard.sql'

Done. Processed 1 app.

文件头随之变为（实测内容）：

-- shaperid:dppqrdiyne5e04nnr8z9xu7n

SELECT channel, COUNT(*) AS days, SUM(amount) AS total
FROM sales
GROUP BY channel
ORDER BY channel

⚠️ 注意：shaperid 一经生成请勿手工改动——它是 deploy/pull 时本地文件与远端仪表盘的匹配键，改了会导致「远端更新冲突」（实测提示 run shaper pull first）。

5.5 shaper deploy

把本地仪表盘/任务文件推送到服务端（认证：SHAPER_DEPLOY_API_KEY 环境变量或 .shaper-auth 登录态；实测两种均可用）：

cd /opt/shaper-work
export SHAPER_DEPLOY_API_KEY=$(cat .shaper-auth)
printf 'y\n' | shaper deploy

实测回显（首次推送成功形态）：

Deploying dashboards and tasks...

Current time:  2026-10-30T02:50:44Z

Fetching remote apps from http://localhost:5454
Found 2 remote apps.
Loading apps from folder /opt/shaper-work
Found 1 local apps.

Changes: create=1, update=0, delete=0

create dppqrdiyne5e04nnr8z9xu7n: /summary.dashboard.sql

Deploy completed.
Updating local shapersync timestamps...
Successfully updated shapersync timestamps for 1 local files.

回显要点：Changes: create/update/delete 三计数先汇总、再逐文件执行，Deploy completed 后自动回写本地 -- shapersync:<UTC时间> 同步戳（防重复推送）。变更明细可审计：每行 create/update 都带 shaperid 与文件名。

⚠️ 排障实录：若远端同名仪表盘已被他人经 UI 修改，deploy 拒绝盲推并提示 remote app sales-table (ud1px8sj7ojnhy7naedzif3h) was updated in prod by user:root; run shaper pull first（实测原文）——先 pull 合并再 deploy，这是多人协作的防覆盖机制。

5.6 shaper pull

反向操作：把服务端全部仪表盘拉回本地文件（UI 手改后的变更回收入 Git 的标准路径）：

cd /opt/shaper-work && unset SHAPER_DEPLOY_API_KEY
printf 'y\ny\n' | shaper pull

实测回显：

Pulling app changes...

Fetching apps and folders from http://localhost:5454
Found 2 remote apps
Found 0 remote folders
Loading apps from folder /opt/shaper-work
Found 1 local apps.

Apps to create (2):
  + sales-table.dashboard.sql
  + sales-demo.dashboard.sql

Proceed with pull? [y/N]: Wrote app: /sales-table.dashboard.sql
Wrote app: /sales-demo.dashboard.sql

Pull complete.

拉取文件带双注释头（实测内容，UI/API 创建的仪表盘同样有身份键）：

-- shaperid:atas4zr88ykx9hgiy9oiv9l9
-- shapersync:2026-10-30T02:39:16Z

解读：pull 把 API POST /api/dashboards 创建的临时仪表盘（sales-demo/sales-table，创建过程见 5.9）也物化为文件——「先原型后固化进 Git」的正向工作流。

5.7 shaper dev 与 shaper preview

本地开发工作流（在开发机执行，无需生产服务写权限）：

# 开发模式：监视目录内 .dashboard.sql 增量改动并起本地预览（默认浏览器自动打开）
shaper dev

# 预览模式：把当前文件以临时仪表盘形式推到服务端预览
shaper preview --no-open

dev/preview 共用参数（--help 实测）：--config（默认 ./shaper.json）、--url（覆盖 config 中 url）、--auth-file（默认 .shaper-auth）、--no-open（禁止自动开浏览器）。两命令区别：dev 常驻监视适合边写边看；preview 单次推送适合给同事甩一个链接看效果。

5.8 shaper healthcheck

存活巡检命令，适合纳入监控探针/定时任务：

shaper healthcheck

实测回显：

OK

服务停止时该命令连接失败、退出码非 0（对端连接拒绝）。解读：等价于对 /healthcheck 端点的探测（服务端实测该端点无需认证返回 200），CLI 形态免写 curl，退出码可直接做告警判定。注意服务优雅退出需要数秒，kill 后立即探测仍可能得到 OK，巡检脚本判定失败前建议重试一次。

交互式获取登录态写入 .shaper-auth（--help 实测参数：--config/--url/--auth-file/--no-open）。默认流程会拉起浏览器走 SSO 登录页；无浏览器环境（纯终端运维机）的等价做法：用与服务端一致的 jwt-secret 自签 JWT 直接写入 auth 文件（本文 5.5 实测 deploy/pull 均接受该凭据），或签好 JWT 后拼 http://<服务器IP>:5454/#token=<jwt> 在浏览器完成 UI 登录。

六、管理 REST API 运维实操

服务端开放的管理 API 以 Bearer 凭据认证（API Key 或 JWT 均实测可用）。API Key 在 UI 的 Admin 区生成；本节用 JWT 实测四个高频端点。

1. 认证基准测试（无凭据 401 → 带 JWT 200，实测）：

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

TOKEN=$(cat /opt/shaper-work/.shaper-auth)
curl -s -o /dev/null -w "%{http_code}\n" -H "Authorization: Bearer $TOKEN" http://localhost:5454/api/schema

2. 查询库结构 GET /api/schema（实测回显见《Shaper 0.26.4 裸机安装指南》第九章，返回 JSON 形态的 databases/schemas/tables 树）。

3. 创建临时仪表盘 POST /api/dashboards（卡片=类型+标题+SQL，实测）：

curl -s -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"sales-demo","cards":[{"type":"bar","title":"Daily Amount","sql":"SELECT day, SUM(amount) AS total FROM sales GROUP BY day ORDER BY day"}]}' \
  http://localhost:5454/api/dashboards

实测回显（201 Created）：

{
  "id": "atas4zr88ykx9hgiy9oiv9l9"
}

4. 导出文件 GET /api/dashboards/:id/download/:file（按扩展名出 PDF/PNG/CSV/XLSX/JSON）。实测两种失败形态（排障价值高）：

# CSV：非表格卡片/未声明下载按钮时拒绝
{"error": "error downloading file"}          # 日志: could not find a matching query for CSV download

# PNG：裸机未装 Chrome 时拒绝
{"error": "error downloading file"}          # 日志: failed to generate png: exec: "google-chrome": executable file not found in $PATH

解读：CSV/XLSX/JSON 导出要求仪表盘含对应 DOWNLOAD_* 按钮或仅含单个 table/chart 且查询可匹配；PNG/PDF 需 headless Chrome（见《Shaper 0.26.4 裸机安装指南》FAQ Q3）。临时仪表盘 TTL 默认 24h（--tmp-dashboards-ttl），适合告警消息里按需生成、到点自动清理的集成场景。

七、注意事项

凭据文件三处放行：.shaper-auth（CLI 登录态）、SHAPER_DEPLOY_API_KEY（deploy 环境变量）、UI API Key 是三条等价凭据通道，权限收敛与轮换策略要统一管理，避免「一个人轮了另外两条还在用」；
shaperid 是身份键：手工复制 dashboard.sql 会连带 shaperid 造成两端冲突，新文件应删除注释头后用 shaper ids 重新生成；
deploy/pull 的交互确认：批量变更时会 [y/N] 确认（实测），脚本化时用管道喂 y，但生产建议先看 Changes: 预检输出再放行；
schema 命令读的是服务端库：本地改了 init.sql 不代表生产生效，巡检以 shaper schema 输出为准；
时钟一致性：shapersync 时间戳为 UTC，多节点部署（NATS 集群共享流）务必保证 NTP 校时，否则 pull/deploy 的同步戳比较会出现假冲突。

八、常见问题（FAQ）

Q1：deploy 报 run shaper pull first？ 远端同名仪表盘已被更新（实测原文见 5.5）。shaper pull 拉回远端版本 → 合并本地改动 → 再 deploy；确认要本地覆盖远端时，删除本地文件的 shapersync 行后重试。

Q2：validate 报 missing shaperid comment？ 新文件缺身份头（实测形态见 5.3），执行 shaper ids 自动补齐。

Q3：healthcheck 通但浏览器 401？ healthcheck 端点本身免认证（实测 200），401 出现在 UI 跳转——JWT 过期（默认 --jwtexp 15m）或密钥与服务端 --jwt-secret 不一致（日志报 token signature is invalid，实测形态）。重新签发或核对密钥。

Q4：pull 列出远端 app 但本地已有同名文件？ 本地文件与远端 shaperid 不一致（通常是复制文件导致）。保留远端（pull 后手工合并改动）或删除本地冗余文件后重新 pull。

Q5：dev/preview 在服务器上起不来？ 这两个命令面向本地开发机；服务器（尤其无桌面环境）执行 dev 试图开浏览器会失败，加 --no-open 或改在本地环境使用。

九、参考链接

官方 Git Workflow 文档：https://taleshape.com/shaper/docs/git-workflow/
官方 Dashboard SQL Reference：https://taleshape.com/shaper/docs/dashboard-sql-reference/
官方 API Endpoints 文档：https://taleshape.com/shaper/docs/api-endpoints/
本专栏篇章：《Shaper 介绍与选型指南》、《Shaper 0.26.4 裸机安装指南》、《Shaper 0.26.4 配置参数详解》
查询能力纵深：《DuckDB 命令行与 SQL 工具详解》

Shaper 0.26.4 常用 CLI 命令与运维实操

Shaper 0.26.4 常用 CLI 命令与运维实操

一、环境信息

二、工具概览

三、前置条件

四、演示仪表盘文件（.dashboard.sql）

五、各工具详解

5.1 shaper --version / --help

5.2 shaper schema

5.4 shaper ids

5.5 shaper deploy

5.6 shaper pull

5.7 shaper dev 与 shaper preview

5.8 shaper healthcheck

5.9 shaper login

六、管理 REST API 运维实操

七、注意事项

八、常见问题（FAQ）

九、参考链接