OpenBao 2.7.1 常用 CLI 命令与工具详解
bao CLI 全命令族实测手册：server/status/operator、secrets/kv、policy、auth/login/token、lease 与通用读写命令，含参数表与 v2.7.1 真实回显（敏感值脱敏）。
OpenBaoOpenBao2026/10/17
OpenBao 2.7.1 常用 CLI 命令与工具详解
> 目标：把 bao CLI 的常用命令族一次讲全——服务端与运维（server/status/operator）、密钥引擎（secrets/kv）、策略（policy）、认证与令牌（auth/login/token）、租约（lease）与通用读写命令；每条命令配参数表与 Ubuntu 22.04 + OpenBao v2.7.1 的真实回显（敏感密钥值已脱敏）。
一、环境信息
- 操作系统：Ubuntu 22.04 LTS（x86_64）
- bao CLI：官方 zip 包安装，路径
/usr/local/bin/bao，版本OpenBao v2.7.1 (a5db72cef75c24b920ade02065b18dd8eb666bac), committed 2026-10-01T15:32:54Z - 服务端：本机
http://127.0.0.1:8200，pebbledb 存储、5 分片阈值 3（生产形态，部署方式见部署指南篇） - 客户端环境变量（本文所有命令的前提）：
export BAO_ADDR=http://127.0.0.1:8200
export BAO_TOKEN=s.xxxx… # 当前令牌；回显中以掩码展示
版本与状态自检回显：
bao version && bao status
OpenBao v2.7.1 (a5db72cef75c24b920ade02065b18dd8eb666bac), committed 2026-10-01T15:32:54Z
Key Value
--- -----
Seal Type shamir
Initialized true
Sealed false
Total Shares 5
Threshold 3
Version 2.7.1
Commit Date 2026-10-01T15:32:54Z
Storage Type pebbledb
Cluster Name vault-cluster-d251eddc
Cluster ID 7e256ece-27ab-a3ac-caaf-200742c37ae0
HA Enabled false
二、命令体系总览
2.1 全局环境变量与通用参数
| 环境变量 | 对应参数 | 作用 |
|---|---|---|
BAO_ADDR | -address | 服务 API 地址（默认 https://127.0.0.1:8200） |
BAO_TOKEN | -token（一般不显式传） | 认证令牌 |
BAO_CACERT / BAO_CAPATH | -ca-cert / -ca-path | TLS 校验所用 CA |
BAO_CLIENT_CERT / BAO_CLIENT_KEY | -client-cert / -client-key | mTLS 客户端证书 |
BAO_NAMESPACE | -namespace | 命名空间（企业特性场景） |
通用输出参数（几乎全命令族可用）：
| 参数 | 作用 | 示例 |
|---|---|---|
-format=json|yaml|table | 输出格式，默认 table | bao read -format=json sys/health |
-field=<name> | 只输出指定字段（便于脚本取值） | bao token create -field=token |
💡 说明：
bao login成功后会把 token 写入 token helper 文件（默认~/.vault-token），之后本机 CLI 免传BAO_TOKEN；脚本里更推荐显式export BAO_TOKEN，避免相互覆盖。
2.2 常用命令族速查
bao -h 中的常用命令分组（实测截取）：
Common commands:
read Read data and retrieves secrets
write Write data, configuration, and secrets
delete Delete secrets and configuration
list List data or secrets
login Authenticate locally
agent Start an OpenBao agent
server Start an OpenBao server
status Print seal and HA status
unwrap Unwrap a wrapped secret
Other commands:
audit Interact with audit devices
auth Interact with auth methods
kv Interact with OpenBao's Key-Value storage
lease Interact with leases
operator Perform operator-specific tasks
policy Interact with policies
secrets Interact with secrets engines
token Interact with tokens
...
本篇章节与命令族对应：服务端与运维→第三节、密钥引擎→第四节、策略→第五节、认证与令牌→第六节、租约→第七节、通用命令→第八节。
三、服务端与运维命令
3.1 bao server（启动服务端）
| 参数 | 作用 |
|---|---|
-config=<path> | 指定 HCL/JSON 配置文件（生产形态） |
-dev | 开发模式（内存存储、自动初始化解封） |
-dev-listen-address=<addr> | dev 模式监听地址（默认仅 127.0.0.1） |
-dev-root-token-id=<id> | dev 模式固定 root token（便于联调） |
-log-level=<level> | 日志级别（trace/debug/info/warn/error） |
生产形态启动（配置文件写法见部署指南篇）：
sudo bao server -config=/opt/data/openbao/config/config.hcl
dev 模式启动与实测横幅（节选）：
bao server -dev -dev-listen-address=0.0.0.0:8200 -dev-root-token-id=dev-root-token-123456
==> OpenBao server configuration:
Api Address: http://0.0.0.0:8200
Cgo: disabled
Cluster Address: https://0.0.0.0:8201
Go Version: go1.27.1
Storage: inmem
Version: OpenBao v2.7.1, committed 2026-10-01T15:32:54Z
The unseal key and root token are displayed below in case you want to
seal/unseal the Vault or re-authenticate.
Unseal Key: Ygne6VQzgq3knwdb3BbP…（已脱敏）
Root Token: dev-root-token-123456
Development mode should NOT be used in production installations!
⚠️ 注意：dev 模式默认监听
127.0.0.1，跨机/端口转发访问必须显式-dev-listen-address=0.0.0.0:8200（实测遗漏该参数时远程一直连不上）。
3.2 bao status（状态查看）
bao status
实测回显见第一节；封印态下输出会退化为只有 Initialized/Sealed/Unseal Progress 与版本信息（Total Shares 0 / Threshold 0），这是解封前的正常表现。
3.3 bao operator（运维子命令组）
bao operator -h 实测子命令清单：
Subcommands:
diagnose Troubleshoot problems starting OpenBao
generate-root Generates a new root token
init Initializes a server
key-status Provides information about specific namespace barrier encryption key
members Returns the list of nodes in the cluster
migrate Migrates OpenBao data between storage backends
raft Interact with OpenBao's raft storage backend
rekey Generates new unseal keys
rotate Rotates the underlying encryption key
rotate-keys Rotates barrier root key, unseal keys or recovery keys ...
seal Seals the OpenBao server
step-down Forces Vault to resign active duty
unseal Unseals the OpenBao server
validate-config Validate OpenBao configuration files
init（初始化）：
| 参数 | 作用 | 本文实测值 |
|---|---|---|
-key-shares=<int> | 分片总数 N | 5 |
-key-threshold=<int> | 解封阈值 T | 3 |
-pgp-keys=<k1,k2,…> | 分片用公钥加密后输出（防明文落终端） | 未使用 |
-format=json | JSON 输出便于程序保存 | 未使用 |
bao operator init -key-shares=5 -key-threshold=3
实测回显（脱敏）：
Unseal Key 1: Uyk0sLyLo3KaUmPO…（已脱敏）
Unseal Key 2: F1fuKDeJ7dV9J2Fo…（已脱敏）
Unseal Key 3: 0ivLIsIlqMsnlHOUs…（已脱敏）
Unseal Key 4: VmNp+7IJbaVbsJgmF…（已脱敏）
Unseal Key 5: qVq4kACxlt92QiQz…（已脱敏）
Initial Root Token: s.FIAFf5Ee…（已脱敏）
Vault initialized with 5 key shares and a key threshold of 3. Please securely
distribute the key shares printed above. ...
unseal（解封）：参数只有 -reset（清零进度）与 HTTP 选项；分片值作为位置参数传入，也可回车进入交互式逐片输入。实测三次解封进度（1/3 → 2/3 → Sealed false）见第三节回显，此处不再重复。
seal（手动封印）：无专用参数，立即封印并清零解封进度。
bao operator seal
Success! Vault is sealed.
rotate-keys（换分片）：
| 参数 | 作用 |
|---|---|
-init | 发起换片，产出 Nonce |
-key-shares=<int> / -key-threshold=<int> | 新分片 N/T |
-nonce=<uuid> | 提交分片时必须带上 init 产出的 Nonce（实测漏带报 Missing nonce value） |
-pgp-keys | 新分片公钥加密输出（推荐） |
-cancel | 取消进行中的换片 |
-status | 查看换片进度 |
实测全流程（init → 提交 3 片旧分片 → 输出新分片组）见《OpenBao 2.7.1 核心原理详解》3.1 节。
⚠️ 注意：v2.7.1 中
bao operator rekey已废弃（子命令仍在清单里但实测返回 405unsupported operation），换片一律用rotate-keys。
四、密钥引擎命令
4.1 secrets 组（引擎管理）
| 子命令 | 作用 | 常用参数 |
|---|---|---|
secrets enable | 启用引擎 | -path（挂载点）、-version（kv 引擎版本）、-description |
secrets list | 列出已启用引擎 | -detailed |
secrets tune | 调整引擎参数 | -max-lease-ttl、-default-lease-ttl |
secrets disable | 停用引擎 | — |
secrets move | 迁移挂载点 | — |
实测启用 K/V v2 与查看（列表为本实例依次启用 kv/pki/transit/database 后的最终状态）：
bao secrets enable -path=secret kv-v2
bao secrets list
Success! Enabled the kv secrets engine at: secret/
Path Type Accessor Description
---- ---- -------- -----------
apps/ kv kv_c33b9b13 n/a
cubbyhole/ cubbyhole cubbyhole_838ca962 per-token private secret storage
database/ database database_9a7e9282 n/a
identity/ identity identity_e2635d2b identity store
pki/ pki pki_9dc02bb5 n/a
secret/ kv kv_7fc441d8 n/a
sys/ system system_670a41b8 system endpoints used for control, policy and debugging
transit/ transit transit_e5966d46 n/a
⚠️ 注意：全新初始化的正式模式没有默认
secret/挂载（首启时secrets list只有 cubbyhole/identity/sys 三项），第一件事就是secrets enable -path=secret kv-v2。
4.2 kv 子命令组（K/V v2 数据操作）
bao kv -h 实测子命令清单：
Subcommands:
delete Deletes versions in the KV store
destroy Permanently removes one or more versions in the KV store
enable-versioning Turns on versioning for a KV store
get Retrieves data from the KV store
list List data or secrets
metadata Interact with OpenBao's Key-Value storage
patch Sets or updates data in the KV store without overwriting
put Sets or updates data in the KV store
rollback Rolls back to a previous version of data
scan Scan data or secrets
undelete Undeletes versions in the KV store
kv put（写入）：
| 参数/用法 | 作用 |
|---|---|
kv put <mount>/<key> k1=v1 k2=v2 | 写键值对（可多对） |
kv put -mount=secret <key> k=v | 显式指定挂载点（推荐写法，语义清晰） |
kv put <mount>/<key> @file.json / key=@file | 从 JSON 文件/文件内容导入 |
-cas=<int> | check-and-set：要求当前版本号匹配才写入（0 表示必须新建） |
bao kv put secret/app config=v1
= Secret Path =
secret/data/app
======= Metadata =======
Key Value
--- -----
created_time 2026-10-17T09:22:50.661122436Z
custom_metadata <nil>
deletion_time n/a
destroyed false
version 1
kv get（读取）：
| 参数/用法 | 作用 |
|---|---|
kv get <mount>/<key> | 读最新版本 |
-version=<int> | 读指定历史版本 |
-field=<name> | 只输出某字段值 |
-mount=secret <key> | 显式挂载点写法 |
bao kv get -version=1 secret/app
======= Metadata =======
Key Value
--- -----
created_time 2026-10-17T09:22:50.661122436Z
custom_metadata <nil>
deletion_time n/a
destroyed false
version 1
===== Data =====
Key Value
--- -----
config v1
kv delete / undelete（软删与恢复）：
| 参数 | 作用 |
|---|---|
（无参数）kv delete <key> | 软删最新版本 |
-versions=<n[,m]> | 软删/恢复指定版本（undelete 同参数） |
bao kv delete secret/app
bao kv undelete -versions=4 secret/app
实测回显：
Success! Data deleted (if it existed) at: secret/data/app
Success! Data written to: secret/undelete/app
kv destroy / rollback（销毁与回滚）：
| 参数 | 作用 |
|---|---|
destroy -versions=<n[,m]> | 密码学销毁指定版本（元数据留 destroyed: true） |
rollback -version=<int> | 以指定历史版本生成新版本 |
bao kv destroy -versions=2 secret/app
bao kv rollback -version=2 secret/app
实测回显（destroy 后版本元数据）：
Success! Data written to: secret/destroy/app
======= Metadata =======
Key Value
--- -----
...
destroyed true
version 2
Key Value
--- -----
created_time 2026-10-17T09:23:01.521237296Z
custom_metadata <nil>
deletion_time n/a
destroyed false
version 4
kv metadata 子命令（元数据与硬删）：
| 用法 | 作用 |
|---|---|
kv metadata get <key> | 看版本链全貌（每版本的 created/deletion/destroyed） |
kv metadata put <key> max_versions=10 | 配置该路径元数据（保留版本数等） |
kv metadata delete <key> | 整路径硬删（版本链全部消失，不可逆） |
bao kv metadata delete secret/app
bao kv get secret/app
实测回显：
Success! Data deleted (if it existed) at: secret/metadata/app
No value found at secret/data/app
kv list / scan（列表）：
bao kv list secret/
bao kv list apps/
实测回显：
Keys
----
app
db/
Keys
----
db
💡 说明：kv 子命令的
secret/app是"短路径"，CLI 内部映射到 API 的secret/data/app；bao kv metadata get secret/app映射到secret/metadata/app。写自动化脚本时注意这一层转换。
五、策略命令
bao policy 子命令：write / read / list / delete / fmt。
| 用法 | 作用 |
|---|---|
policy write <name> <file.hcl> | 上传/更新策略 |
policy read <name> | 打印策略内容 |
policy list | 列出策略（始终含 root） |
policy delete <name> | 删除策略 |
policy fmt <file> | 格式化本地 HCL 文件 |
实测：
bao policy write app-reader /tmp/app-reader.hcl
bao policy read app-reader
bao policy list
实测回显（策略内容为第四节的 app-reader HCL，此处列出结果）：
Success! Uploaded policy: app-reader
# 允许读取 secret/app 本身与其子路径
path "secret/data/app" {
capabilities = ["read"]
}
path "secret/data/app/*" {
capabilities = ["read", "list"]
}
path "secret/metadata/app" {
capabilities = ["read"]
}
path "secret/metadata/app/*" {
capabilities = ["read", "list"]
}
app-reader
default
root
常用 capabilities 对照（HCL 中使用）：
| capability | 等价 API 动作 |
|---|---|
read | GET |
create / update | PUT/POST（新键/更新） |
delete | DELETE |
list | LIST（路径需以 / 结尾语义） |
sudo | 允许访问受 sudo 保护的端点 |
deny | 显式拒绝（优先级最高） |
六、认证与令牌命令
6.1 auth 组（认证方式管理）
| 用法 | 作用 |
|---|---|
auth enable <method> | 启用认证方式（userpass/ldap/approle/oidc…） |
auth list | 列出已启用认证方式 |
auth disable <path> | 停用 |
auth tune <path> | 调整（如 max-lease-ttl） |
实测启用 userpass：
bao auth enable userpass
bao auth list
Success! Enabled userpass auth method at: userpass/
Path Type Accessor Description Version
---- ---- -------- ----------- -------
token/ token auth_token_9d087a35 token based credentials n/a
userpass/ userpass auth_userpass_7be34997 n/a n/a
6.2 login（登录）
| 参数 | 作用 |
|---|---|
-method=<name> | 认证方式（token/userpass/…） |
username=<u> password=<p> | method 参数以 k=v 形式跟在后面 |
-token-only | 只输出 token 不写入 helper 文件 |
-no-store | 不写入 helper 文件 |
bao login -method=userpass username=admin password=q1w2e3r4
实测回显（token 已脱敏）：
Success! You are now authenticated. The token information displayed below
is already stored in the token helper. You do NOT need to run "bao login"
again. Future OpenBao requests will automatically use this token.
Key Value
--- -----
token s.VXRxjOMHoHGDyK7s…（已脱敏）
token_accessor zvhd4i5jjpv0EqMj17QasB7d
token_duration 1h
token_renewable true
token_policies ["app-reader" "default"]
identity_policies []
policies ["app-reader" "default"]
token_meta_username admin
⚠️ 注意（实测踩坑）：用
-field=token取值时参数必须放在位置参数之前——bao login -method=userpass -field=token username=admin password=...可正确输出裸 token；把-field写在username=之后会解析失败。
6.3 token 组（令牌管理）
bao token 子命令：create / lookup / renew / revoke / capabilities。
token create：
| 参数 | 作用 | 本文实测 |
|---|---|---|
-policy=<name> | 附加策略（可重复） | -policy=app-reader |
-ttl=<duration> | 有效期 | -ttl=10m |
-renewable | 允许续约 | 已使用 |
-explicit-max-ttl=<d> | 硬上限（续约不可超越） | — |
-orphan | 无父 token（revoke 父 token 不株连） | — |
-period=<d> | 周期性 token（服务账号场景） | — |
-display-name=<s> | 展示名 | — |
bao token create -ttl=10m -renewable=true -field=token
s.ZC7Ow7Ez7Lq8t82O…（已脱敏）
token lookup / renew / revoke：
T=$(bao token create -ttl=10m -renewable=true -field=token)
bao token renew -increment=30m "$T"
bao token revoke "$T"
bao token lookup "$T"
实测回显（renew）：
Key Value
--- -----
token s.ZC7Ow7Ez7Lq8t82O…（已脱敏）
token_accessor 8gNce7vYH9y5RJnkXMKs9MSB
token_duration 30m
token_renewable true
token_policies ["root"]
revoke 后 lookup（立即失效）：
Error looking up token: Error making API request.
URL: POST http://127.0.0.1:8200/v1/auth/token/lookup
Code: 403. Errors:
* bad token
token capabilities（排查权限）：把"这条路径我能不能动"变成一条命令：
bao token capabilities secret/app
read
七、租约命令
bao lease 子命令：lookup / renew / revoke，均作用于动态凭据租约（token 租约请用第六节的 token 组）。
| 用法 | 作用 |
|---|---|
lease lookup <lease_id> | 查看到期时间/renewable |
lease renew -increment=<d> <lease_id> | 续约 |
lease revoke <lease_id> | 吊销（回收底层凭据，如 DROP 数据库账号） |
lease revoke -prefix <path> | 按前缀批量吊销 |
实测（database 引擎动态凭据，签发过程见原理篇 3.4 节）：
bao lease lookup database/creds/app-role/2mhRFYIUeBXuLHRTScql93S7
bao lease renew -increment=30m database/creds/app-role/2mhRFYIUeBXuLHRTScql93S7
bao lease revoke database/creds/app-role/2mhRFYIUeBXuLHRTScql93S7
实测回显（lookup）：
Key Value
--- -----
expire_time 2026-10-17T10:26:34.789360236Z
id database/creds/app-role/2mhRFYIUeBXuLHRTScql93S7
issue_time 2026-10-17T09:26:34.78936009Z
last_renewal 2026-10-17T09:27:12.402281815Z
renewable true
ttl 59m22s
renew 回显：
Key Value
--- -----
lease_id database/creds/app-role/2mhRFYIUeBXuLHRTScql93S7
lease_duration 30m
lease_renewable true
revoke 回显：
All revocation operations queued successfully!
吊销后再 lookup 返回 Code: 400. Errors: * invalid lease。
八、通用命令与 API 调试
8.1 write / read / list / delete（底层通用四件套）
kv/policy/auth 等高层命令之外，write/read/list/delete 直接对着 API 路径操作，适合访问没有专用子命令的端点（sys/、transit/、database/…）：
bao write -f transit/keys/app-key # -f 表示无参数写（创建默认密钥环）
bao read -format=json database/creds/app-role
bao write transit/encrypt/app-key plaintext=SGVsbG8=
bao list sys/policies/acl
实测回显（创建 transit 密钥环）：
keys map[1:1792229039]
latest_version 1
name app-key
type aes256-gcm96
| 参数 | 作用 |
|---|---|
-f / -force | 无数据写（触发创建动作） |
-format=json|yaml|table | 输出格式 |
-field=<name> | 取单字段 |
-mount-info | read 时附带挂载信息 |
8.2 HTTP API 调试（curl）
CLI 的本质是 HTTP API 的封装；排查问题或从程序侧接入时用 curl 直接打 API（认证头为 X-Vault-Token，与 CLI 的 BAO_TOKEN 等价）：
curl -s http://127.0.0.1:8200/v1/sys/health
curl -s -H "X-Vault-Token: s.xxxx…（token 完整值）" http://127.0.0.1:8200/v1/secret/data/app
curl -s -o /dev/null -w 'HTTP %{http_code}\n' -H "X-Vault-Token: s.受限token" http://127.0.0.1:8200/v1/apps/data/db
实测回显（health 与读 KV）：
{"initialized":true,"sealed":false,"standby":false,"replication_performance_mode":"disabled","replication_dr_mode":"disabled","server_time_utc":1792229217,"version":"2.7.1","cluster_name":"vault-cluster-d251eddc","cluster_id":"7e256ece-27ab-a3ac-caaf-200742c37ae0"}
{"request_id":"1270ed26-5953-21fa-187f-13ca64e95156","lease_id":"","renewable":false,"lease_duration":0,"data":{"data":{"config":"v4-restored","note":"for-policy-test"},"metadata":{"created_time":"2026-10-17T09:23:44.561457018Z","custom_metadata":null,"deletion_time":"","destroyed":false,"version":1}},"wrap_info":null,"warnings":null,"auth":null}
被拒路径（受限 token）实测返回 HTTP 403 与：
{"errors":["1 error occurred:\n\t* permission denied\n\n"]}
常用调试端点速查：
| 端点 | 用途 |
|---|---|
GET /v1/sys/health | 健康检查（免认证，可探测封印/初始化状态） |
GET /v1/sys/seal-status | 封印状态（解封进度监控脚本常用） |
GET /v1/sys/mounts | 引擎挂载表 |
GET /v1/sys/internal/ui/mounts/<path> | 排查"路径是否可达/挂载在哪个引擎"（403 时 CLI 会先打这个端点） |
九、参考链接
- OpenBao CLI 命令手册（含各子命令参数）：https://openbao.org/docs/commands/
- OpenBao API 文档（curl 调试依据）：https://openbao.org/api-docs/
- OpenBao Secrets Engines 文档（kv/transit/database/pki）：https://openbao.org/docs/secrets/
- OpenBao Auth Methods 文档（userpass/approle/oidc…）：https://openbao.org/docs/auth/
- OpenBao CHANGELOG（v2.7.x 行为变更与命令废弃依据）：https://github.com/openbao/openbao/blob/main/CHANGELOG.md
- 本平台相关篇目：《OpenBao 介绍与选型指南》《OpenBao 2.7.1 核心原理详解》《OpenBao Docker Compose 部署指南》
- 相关文档：《Keycloak Admin API 使用详解》《Vaultwarden 运维手册》
章节目录