README_zh.md

Saola CLI

English | 中文

OpenSaola 的命令行管理工具 — 管理 Kubernetes 上的中间件生命周期：包安装、实例创建、状态查询、版本升级与资源清理。

特性

• kubectl 风格 — get/create/delete/describe 等动词 + 资源类型，学习成本低
• 交互式创建 — TUI 表单引导选择 Baseline、填写参数，无需手写 YAML
• 中英双语 — --lang zh|en 切换所有命令帮助和输出信息
• 包管理 — 打包、安装、升级、卸载中间件包（zstd 压缩 TAR 格式）
• 实例升级 — 通过 annotation 触发 controller 执行滚动升级，支持 --wait 等待完成
• 多格式输出 — table/yaml/json/wide/name，便于脚本集成

支持的中间件

Saola 通过 OpenSaola Operator 包管理以下中间件：

中间件	说明	仓库
MySQL	关系型数据库，支持主从和代理模式	harmonycloud/mysql
PostgreSQL	高级关系型数据库，支持高可用	harmonycloud/postgresql
Apache Kafka	分布式事件流平台	harmonycloud/kafka
Redis	内存数据存储，支持哨兵和集群模式	harmonycloud/redis
Elasticsearch	分布式搜索和分析引擎	harmonycloud/elasticsearch
Apache ZooKeeper	分布式协调服务	harmonycloud/zookeeper
RabbitMQ	AMQP 消息代理	harmonycloud/rabbitmq

安装

从源码构建

git clone https://github.com/harmonycloud/saola-cli.git
cd saola-cli
make build

构建产物在 bin/saola，拷贝到 $PATH 即可使用：

cp bin/saola /usr/local/bin/

go install

go install github.com/harmonycloud/saola-cli/cmd/saola@latest

快速上手

# 1. 安装中间件包
saola install ./redis-pkg -n middleware-operator --wait 5m

# 2. 交互式创建 Middleware 和 MiddlewareOperator
saola create

# 3. 查看实例状态
saola get middleware -n my-ns
saola get operator -n my-ns

# 4. 查看实例详情
saola describe middleware my-redis -n my-ns

# 5. 升级实例版本
saola upgrade middleware my-redis --to-version 2.0.0 -n my-ns --wait 5m

# 6. 删除实例
saola delete middleware my-redis -n my-ns

命令参考

顶级命令

命令	说明
create	从 YAML 文件或交互式 TUI 创建 Middleware / MiddlewareOperator
get	列出或查看资源
describe	显示资源详细信息（Spec、Status、Conditions）
delete	删除资源
run	触发 MiddlewareAction（一次性运维操作）
upgrade	升级包或 Middleware / MiddlewareOperator 实例
install	安装中间件包到集群
uninstall	卸载中间件包
build	打包本地目录为 zstd 压缩 TAR（不安装）
inspect	查看已安装包的内容和元数据
version	显示版本信息

资源子命令

以 get 为例，其他动词（describe/delete/upgrade）结构类似：

子命令	别名	说明
get middleware [name]	mw	列出或查看 Middleware
get operator [name]	op	列出或查看 MiddlewareOperator
get action [name]	act	列出或查看 MiddlewareAction
get baseline [name]	bl	查看已安装包中的 Baseline
get package [name]	pkg	列出或查看已安装包
get all	-	聚合输出 middleware + operator + action

upgrade 子命令

# 包升级（替换已安装的 Package Secret）
saola upgrade <pkg-dir>

# 实例升级（通过 annotation 触发 controller）
saola upgrade middleware <name> --to-version <version> [--baseline <bl>] [--wait 5m]
saola upgrade operator <name>   --to-version <version> [--baseline <bl>] [--wait 5m]

run 命令

# 触发 Action（如备份、恢复）
saola run <action-name> --middleware <mw-name> --params key1=val1,key2=val2 -n my-ns

全局 Flags

Flag	简写	默认值	说明
--kubeconfig	-	$KUBECONFIG 或 ~/.kube/config	kubeconfig 文件路径
--context	-	-	kubeconfig context
--namespace	-n	-	目标命名空间
--pkg-namespace	-	middleware-operator	包 Secret 所在命名空间
--lang	-	zh	语言：zh（中文）/ en（英文）
--no-color	-	false	禁用彩色输出

常用资源命令还支持：

Flag	简写	说明
--all-namespaces	-A	列出所有命名空间的资源
--output	-o	输出格式：table/yaml/json/wide/name
--wait	-	等待操作完成的超时时间（如 5m）
--dry-run	-	预览变更，不实际执行

配置

环境变量

变量	说明
KUBECONFIG	kubeconfig 文件路径
SAOLA_NAMESPACE	默认命名空间
SAOLA_PKG_NAMESPACE	包 Secret 命名空间（默认 middleware-operator）

优先级

CLI Flag > 环境变量 > 默认值

项目结构

saola-cli/
├── cmd/saola/          # 入口
├── internal/
│   ├── app/            # 根命令注册
│   ├── cmd/            # 所有子命令实现
│   │   ├── action/     # MiddlewareAction
│   │   ├── baseline/   # Baseline 查询
│   │   ├── build/      # 包构建
│   │   ├── create/     # 资源创建（含交互式 TUI）
│   │   ├── delete/     # 资源删除
│   │   ├── describe/   # 资源详情
│   │   ├── get/        # 资源列表
│   │   ├── inspect/    # 包检查
│   │   ├── install/    # 包安装
│   │   ├── middleware/  # Middleware 资源组
│   │   ├── operator/   # MiddlewareOperator 资源组
│   │   ├── pkgcmd/     # 包管理命令
│   │   ├── upgrade/    # 升级
│   │   ├── uninstall/  # 卸载
│   │   ├── run/        # Action 执行
│   │   └── version/    # 版本信息
│   ├── client/         # Kubernetes client 封装
│   ├── config/         # 配置管理
│   ├── consts/         # 项目常量
│   ├── lang/           # 中英双语支持
│   ├── packager/       # TAR/zstd 打包解包
│   ├── printer/        # 输出格式化（table/yaml/json）
│   ├── version/        # 版本信息注入
│   └── waiter/         # 异步等待逻辑
├── Makefile
└── go.mod

构建与测试

# 构建
make build          # 编译到 bin/saola

# 测试
make test           # 运行单元测试
make lint           # go vet 静态检查

# 其他
make tidy           # 整理 go modules
make clean          # 清理构建产物

版本信息通过 ldflags 注入：

saola version
# Version: v0.1.0
# Git Commit: 6bd4f94
# Build Date: 2026-03-31T07:46:11Z

自动发布

发布工作流由 Saola CLI 独立完成：

• 推送到 main 时，仅以 dev-<12 位 sha> 版本生成工作流产物，不创建 GitHub Release。
• 推送 vMAJOR.MINOR.PATCH tag（可带 SemVer 预发布后缀）时，发布不可变的 GitHub Release，其中包含两个 Linux 二进制、SHA256SUMS、SBOM、签名和 attestations。
• OpenSaola 从自身 Docker 工作流解析已发布的最终 Release。
• 不需要 OPENSAOLA_DISPATCH_TOKEN，也不发送 repository_dispatch 事件。

每次发布包含静态的 linux/amd64、linux/arm64 二进制、SHA256SUMS、SPDX JSON SBOM 和无密钥 Sigstore bundle。GitHub provenance attestation 通过 GitHub artifact attestation 服务与这些文件关联，不是 dist/ 中的文件，也不是 GitHub Release asset。stable Release asset 不可变：已有资产必须逐字节一致，已发布 Release 不允许原地修补，draft 只有在每项上传资产均被重新下载并验证后才会发布。版本、完整 commit SHA 与 UTC 构建时间均从触发提交确定。可在本地复现发布产物：

make release-build
make release-checksums

管理的 CRD 类型

Saola 通过 OpenSaola Operator 管理以下 Kubernetes 自定义资源：

CRD	缩写	说明
Middleware	mid	中间件实例
MiddlewareOperator	mo	管理某类中间件的 Operator 实例
MiddlewareAction	ma	一次性运维操作（备份、恢复等）
MiddlewareBaseline	mb	Middleware 基线配置模板
MiddlewareOperatorBaseline	mob	Operator 基线配置模板
MiddlewarePackage	mp	中间件分发包

文档

• 使用文档 | Usage Guide (English)
• 测试指南 | Testing Guide (English)
• OpenSaola 技术文档
• 包适配指南
• 故障排查指南

参与贡献

欢迎贡献！请参阅 CONTRIBUTING.md 了解贡献指南。

许可证

Copyright 2025 The OpenSaola Authors.

基于 Apache License 2.0 许可证开源。详见 LICENSE。