powerjob-go-cli

PowerJob 调度中心的命令行控制台 -- 单文件 Go 二进制，零运行时依赖

为什么

PowerJob 是分布式调度和任务编排框架。每次调试都要：

打开浏览器 → 登录控制台 → 点若干级菜单 → 找 job → 看实例
或者翻 API 文档，拼 curl -X POST -H "Content-Type: application/json" -d '...' 几十个参数

这个 CLI 解决了什么问题：

之前	之后
打开浏览器，点 5 次鼠标	`powerjob-cli fetch-all-job --format table`
从文档复制 curl 参数	`powerjob-cli query-instance --job-id 42 --status SUCCEED --all`
写脚本调用 OpenAPI 处理鉴权	`powerjob-cli history --name "MyFlow" --since 7d --format csv`

单文件二进制，下载即用，不需要 Python/pip/venv。

安装

下载 Release 二进制（推荐）

从 Releases 下载对应平台的压缩包：

平台	文件
Linux amd64	`powerjob-go-cli-linux-amd64`
Linux arm64	`powerjob-go-cli-linux-arm64`
macOS amd64 (Intel)	`powerjob-go-cli-macos-amd64`
macOS arm64 (Apple Silicon)	`powerjob-go-cli-macos-arm64`
Windows amd64	`powerjob-go-cli-windows-amd64.exe`
Windows arm64	`powerjob-go-cli-windows-arm64.exe`

# macOS 示例
curl -sL https://github.com/just-a-stone/powerjob-cli/releases/latest/download/powerjob-go-cli-macos-arm64 -o powerjob-cli
chmod +x powerjob-cli
./powerjob-cli --version

go install

go install github.com/just-a-stone/powerjob-cli/cmd/powerjob-cli@latest

从源码构建

展开

需要 Go 1.22+：

git clone https://github.com/just-a-stone/powerjob-cli.git
cd powerjob-cli
go build -trimpath -ldflags='-s -w' -o powerjob-cli ./cmd/powerjob-cli
./powerjob-cli --help

交叉编译：

GOOS=linux GOARCH=amd64 go build -trimpath -ldflags='-s -w' -o dist/powerjob-cli-linux-amd64 ./cmd/powerjob-cli
GOOS=darwin GOARCH=arm64 go build -trimpath -ldflags='-s -w' -o dist/powerjob-cli-darwin-arm64 ./cmd/powerjob-cli

60 秒上手

0. 配置

创建 .env 文件（放在当前目录或 ~/.config/powerjob/.env）：

POWERJOB_ADDRESS=192.168.1.100:7700
POWERJOB_APP_NAME=my-app
POWERJOB_PASSWORD=your-app-password
POWERJOB_PROTOCOL=http
POWERJOB_READONLY=true

1. 列出所有 Job

powerjob-cli fetch-all-job --format table

输出：

id    jobName                           statusDesc  timeExpressionTypeDesc  timeExpression  processorInfo
1001  OrderSyncJob                      启用         固定频率                 60000           com.example.OrderSyncProcessor
1002  DailyReportGenerator              启用         CRON                    0 0 8 * * ?     com.example.ReportProcessor
1003  DataCleanupTask                   禁用         固定频率                 86400000        com.example.CleanupProcessor
1004  PaymentReconciliation             启用         CRON                    0 30 2 * * ?    com.example.ReconciliationProcessor
1005  UserStatsRefresh                  启用         固定频率                 300000          com.example.StatsProcessor

2. 查询实例状态

powerjob-cli query-instance --job-id 1001 --status SUCCEED --all --format table

输出：

instanceId  jobId  statusDesc  actualTriggerTimeStr      finishedTimeStr
50001       1001   成功        2026-08-06 08:00:00 +0800  2026-08-06 08:00:12 +0800
50002       1001   成功        2026-08-06 08:10:00 +0800  2026-08-06 08:10:15 +0800
50003       1001   成功        2026-08-06 08:20:00 +0800  2026-08-06 08:20:11 +0800
50004       1001   失败        2026-08-06 08:30:00 +0800  2026-08-06 08:30:05 +0800
50005       1001   成功        2026-08-06 08:40:00 +0800  2026-08-06 08:40:14 +0800

3. 查看 Workflow DAG

powerjob-cli workflow-dag --workflow-id 12 --format table

输出：

depth  nodeId  nodeName        nodeTypeDesc  jobId  enable  dependsOn
0      1       OrderSyncJob    任务节点       1001   启用    []
1      2       PaymentCheck    任务节点       1004   启用    [1]
1      3       ReportGen       任务节点       1002   启用    [1]
2      4       NotifyComplete  任务节点       1005   启用    [2 3]

4. 查看运行历史

powerjob-cli history --name "DailyFlow" --since 7d --nodes --format table

输出：

wfInstanceId  statusDesc  actualTriggerTimeStr      finishedTimeStr         nodes  failed  failedNodes
60001         成功        2026-08-06 08:00:00 +0800  2026-08-06 08:01:30 +0800  4      0
60002         失败        2026-08-05 08:00:00 +0800  2026-08-05 08:00:45 +0800  4      1       [NotifyComplete]
60003         成功        2026-08-04 08:00:00 +0800  2026-08-04 08:01:15 +0800  4      0

常用场景

查询

命令	用途
`fetch-all-job`	列出当前应用所有 Job
`fetch-job --id 42`	查看单个 Job 详情
`query-job --name "Order*" --status ENABLE`	按条件筛选 Job
`query-instance --job-id 42 --status SUCCEED --all`	查询实例历史
`instance-status --instance-id 50001`	查看单个实例状态
`fetch-workflow --name "MyFlow"`	按名称查找 Workflow
`workflow-dag --name "MyFlow"`	查看 Workflow 编排图
`history --name "MyFlow" --since 7d --nodes`	近期运行历史（含节点详情）

管理

命令	用途
`run-job --job-id 42`	手动触发一次执行
`stop-instance --instance-id 50001`	停止正在运行的实例
`enable-job --job-id 42` / `disable-job --job-id 42`	启用/禁用 Job
`retry-instance --instance-id 50001`	重试失败实例
`mark-wf-node-success --wf-instance-id 60002 --node-id 4`	标记 Workflow 节点成功（跳过失败节点继续执行）
`save-job --file job.json`	从 JSON 文件创建/更新 Job
`copy-job --job-id 42 --app-id 7`	跨应用复制 Job
`export-job --job-id 42`	导出 Job 定义为 JSON

输出格式

所有查询命令支持 --format json|jsonl|table|csv：

# 默认 JSON
powerjob-cli fetch-all-job

# 表格（人眼友好）
powerjob-cli fetch-all-job --format table

# CSV（导入 Excel / 数据分析）
powerjob-cli history --name "MyFlow" --since 30d --format csv

# JSONL（逐行处理）
powerjob-cli query-instance --job-id 42 --all --format jsonl

选择列：

powerjob-cli fetch-all-job --format table --fields id,jobName,statusDesc

配置

配置文件

CLI 按以下顺序寻找 .env：当前目录 → 最多五级父目录 → ~/.config/powerjob/.env。也可显式指定：

powerjob-cli --env-file /path/to/.env fetch-all-job
powerjob-cli --profile production fetch-all-job  # 加载 .env.production

配置变量

变量	作用	默认值
`POWERJOB_ADDRESS` / `POWERJOB_ADDRESS_LIST`	Server 地址（列表优先）	必填
`POWERJOB_APP_NAME`	应用名	必填
`POWERJOB_PASSWORD`	应用密码	必填
`POWERJOB_PROTOCOL`	http 或 https	`http`
`POWERJOB_TIMEOUT`	总请求超时（秒）	`30`
`POWERJOB_CONNECTION_TIMEOUT`	连接超时（秒）	`5`
`POWERJOB_READ_TIMEOUT`	读取超时（秒）	`5`
`POWERJOB_VERIFY_SSL`	HTTPS 证书校验	`false`
`POWERJOB_ENV_FILE`	配置文件路径	—
`POWERJOB_PROFILE`	Profile 名	—
`POWERJOB_READONLY`	拒绝写操作	`false`

安全

密码保护

密码不会通过 --password 传入（拒绝进程列表泄露），只能通过 .env 文件或 stdin 的 --password-stdin 传入：

# 交互输入
powerjob-cli --password-stdin fetch-all-job

# 管道输入（CI/脚本）
printf '%s\n' "$POWERJOB_PASSWORD" | powerjob-cli --password-stdin fetch-all-job

只读模式

设置 POWERJOB_READONLY=true 或 --readonly 后，所有写操作（run-job、save-job、enable-job 等）在网络连接建立前即被拒绝：

powerjob-cli --readonly run-job --job-id 42
# REFUSED: run-job changes server state and read-only mode is on

日志脱敏

HTTP 日志中的 password / token / secret / authorization 自动脱敏为 ***。

确认机制

写操作（run-job、stop-instance、delete-job 等）默认需要交互确认。批处理/CI 使用 --yes：

powerjob-cli --yes run-job --job-id 42

命令参考

展开完整命令列表

Job

命令	说明
`fetch-all-job`	列出所有 Job
`fetch-job --id N`	获取单个 Job
`query-job`	按条件筛选
`save-job --file path`	创建/更新
`copy-job --id N --app-id M`	复制到其他应用
`export-job --id N`	导出 JSON
`run-job --id N`	立即执行一次
`enable-job --id N`	启用
`disable-job --id N`	禁用
`delete-job --id N`	删除

Instance

命令	说明
`fetch-instance --instance-id N`	获取实例详情
`instance-status --instance-id N`	查看状态
`query-instance --job-id N`	查询实例历史
`stop-instance --instance-id N`	停止运行
`cancel-instance --instance-id N`	取消
`retry-instance --instance-id N`	重试失败实例

Workflow

命令	说明
`fetch-workflow --id N / --name X`	获取 Workflow
`list-workflow`	列出当前应用所有 Workflow
`save-workflow --file path`	创建/更新
`save-workflow-node --file path`	创建/更新节点
`copy-workflow --id N --app-id M`	复制
`run-workflow --id N`	手动触发
`enable-workflow --id N`	启用
`disable-workflow --id N`	禁用
`delete-workflow --id N`	删除

Workflow 实例

命令	说明
`fetch-wf-instance --wf-instance-id N`	获取实例详情
`stop-wf-instance --wf-instance-id N`	停止
`retry-wf-instance --wf-instance-id N`	重试
`mark-wf-node-success --wf-instance-id N --node-id M`	标记节点成功

诊断

命令	说明
`workflow-dag --workflow-id N / --name X`	查看 Workflow 编排图
`history --name X --since 7d`	运行历史

全局选项

展开

选项	作用
`--format json/jsonl/table/csv`	输出格式
`--fields id,statusDesc`	选择列
`--tz Asia/Shanghai`	时区
`--timeout 30`	请求超时（秒）
`-v` / `-vv`	日志级别
`-y, --yes`	跳过确认
`--readonly`	只读模式
`--version`	版本信息

表格/CSV/JSONL 会自动为状态码附加 *Desc 字段、为 epoch 毫秒时间附加 *Str 字段。

退出码

退出码	含义
`0`	成功
`1`	传输或配置错误
`2`	参数/用法错误
`3`	服务端返回 `success=false`
`4`	只读策略拒绝或用户取消确认

FAQ

常见问题

Q: 提示鉴权失败 / 401 A: 检查 POWERJOB_ADDRESS 和应用密码是否正确。PowerJob 服务端 /openApi/authApp 接口使用 MD5 鉴权，CLI 会自动处理 token 刷新。

Q: 请求超时或连接失败 A: 确认服务端地址可达。多地址配置自动做 HA：POWERJOB_ADDRESS_LIST=10.0.0.1:7700,10.0.0.2:7700，当前地址失败后自动切换。

Q: 服务端返回 success=false A: 使用 -v 或 -vv 查看详细请求和响应，便于定位问题。

Q: HTTPS 证书校验失败 A: 开发环境设 POWERJOB_VERIFY_SSL=false；生产环境建议设为 true 并确保证书有效。

Q: 如何确保不会误操作 A: 日常查询使用 --readonly（或设置 POWERJOB_READONLY=true），所有写操作默认需要交互确认。

Q: 如何获取 shell 补全 A: powerjob-cli completion zsh > ~/.zfunc/_powerjob-cli（需要将 ~/.zfunc 加入 fpath）。

开发

展开

# 运行测试
go test ./...
go test -race ./...
go vet ./...

# 构建
go build -trimpath -ldflags='-s -w -X main.version=dev' -o powerjob-cli ./cmd/powerjob-cli

# 运行
./powerjob-cli --help

项目结构

├── cmd/powerjob-cli/          # 入口 + 命令注册
│   ├── main.go                # cobra root + 全局选项
│   ├── commands_job.go        # job 相关命令
│   ├── commands_instance.go   # instance 相关命令
│   ├── commands_workflow.go   # workflow 相关命令
│   └── commands_wf_instance.go
├── internal/powerjob/         # 核心逻辑
│   ├── client.go              # OpenAPI 客户端
│   ├── transport.go           # HTTP 传输（鉴权/HA/重试/脱敏）
│   ├── output.go              # 输出格式化（json/table/csv）
│   ├── dag.go                 # Workflow DAG 解析
│   ├── history.go             # 历史记录聚合
│   ├── constants.go           # 常量
│   ├── enums.go               # 枚举映射
│   ├── errors.go              # 类型化错误
│   ├── settings.go            # 配置加载
│   └── models/                # 数据模型
├── .github/workflows/         # CI/CD
│   ├── ci.yml                 # push/PR 自动测试
│   └── release.yml            # tag 发布 6 平台二进制
└── LICENSE

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 7 Commits
.github		.github
cmd/powerjob-cli		cmd/powerjob-cli
internal/powerjob		internal/powerjob
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
go.mod		go.mod
go.sum		go.sum

Folders and files

Latest commit

History

Repository files navigation

powerjob-go-cli

为什么

安装

下载 Release 二进制（推荐）

go install

从源码构建

60 秒上手

0. 配置

1. 列出所有 Job

2. 查询实例状态

3. 查看 Workflow DAG

4. 查看运行历史

常用场景

查询

管理

输出格式

配置

配置文件

配置变量

安全

密码保护

只读模式

日志脱敏

确认机制

命令参考

Job

Instance

Workflow

Workflow 实例

诊断

全局选项

退出码

FAQ

开发

项目结构

License

About

Topics

Resources

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages