---
title: OpenBao 使用指南
lifecycle: active
evidence: documented
last_reviewed: 2026-09-16
last_verified: null
---

# OpenBao

OpenBao 提供秘密管理与内部 CA，部署在 Kubernetes 之外的独立主机上。
日常使用是以自己的身份登录，按已有 policy 读取秘密或申请短期凭据。

本页依据 homelab-infra 工作区 `infrastructure/openbao/README.md` 整理，
CLI 语法参考下列官方文档。本轮未登录服务、读取秘密或验证现场。

## 人的登录入口

前提是客户端能解析并访问内部域名，已安装 `bao` CLI，且账号具备相应 OIDC 授权。

```bash
export BAO_ADDR=https://bao.ad.ddupan.top:8200
bao login -method=oidc -no-print
```

按提示通过浏览器进入 Authelia，完成登录和二次认证。
使用域名进行 TLS 校验，不用 IP 地址代替，也不关闭证书校验。
`-no-print` 避免显示 token，但成功登录后仍会把它存入本机 token helper，供后续命令使用。
因此应在自己的受控会话中登录。参见 [OpenBao login](https://openbao.org/docs/commands/login/)。

登录成功后，只查看当前会话的权限与有效期：

```bash
bao token lookup -field=policies
bao token lookup -field=ttl
```

这两个命令不打印完整 token；字段选项见
[token lookup](https://openbao.org/docs/commands/token/lookup/)。能登录不代表能读取任意秘密。

## 按授权路径读取一个字段

先由服务所有者提供准确的 mount、秘密路径和字段名。
下例 `YOUR_AUTHORIZED_PATH` 是占位符，须替换为 `kv` mount 下已授权且存在的路径；
`password` 也应替换为实际字段名。命令仅适合已获相应权限的会话。

```bash
set +x
APP_PASSWORD="$(bao kv get -mount=kv -field=password YOUR_AUTHORIZED_PATH)"
# 在当前会话中交给实际消费者；不要 echo，也不要放入命令行参数或日志。
unset APP_PASSWORD
```

示例只演示接收字段后清除变量，不会配置任何应用；接入脚本还应检查命令失败并停止后续操作。
`kv get` 会处理 KV 引擎的 API 路径，CLI 的相对路径无需自行插入 `data/`。
参见 [OpenBao kv get](https://openbao.org/docs/commands/kv/get/)。

Kubernetes 应用通常消费 ESO 投射的 Secret。修改秘密应通过其受管来源及对应服务的轮换流程，
不能只编辑 ESO 生成的副本。不要把完整秘密内容粘贴到 AI 上下文、issue 或 wiki。

## 机器身份的使用边界

| 调用者 | 本库已记录的认证路径 |
|---|---|
| 人 | Authelia OIDC 登录 |
| laptop 本地 AI agent | 独立客户端证书，cert auth role 为 `local-agent` |
| SPIFFE workload | 按 [SPIRE 接入说明](spire.md) 与对应 OpenBao role 配置换取 token |

源码记录的本地 agent 证书与私钥由 Ansible 安装在 `/etc/homelab-agent/openbao/`，
不要复制到仓库或 workflow。其 token TTL 为 15 分钟、最长 1 小时；权限包括受限的 SSH 签名、
自身证书续期及 `kv/agents/local/*`，明确不包含 `kv/k8s/*`。
证书注册、登录与续期按源码 README 操作，不能从 SPIFFE 的整体设计推断该路径已迁移。

SPIFFE 验证机器身份，OpenBao 自己签发 token 并维护 policy。
Dynamic Runner 提供执行环境和 workload 身份，具体向 OpenBao 请求什么 token 由 workflow 决定。

## 权限申请与故障入口

申请权限时提供调用者身份、准确路径、所需动作、有效期及用途，由维护者调整受管 role/policy。
遇到拒绝访问先核对上述信息及会话有效期，不用管理员 token 代替应用身份。
连接失败时先区分内部 DNS、网络、TLS 与认证问题；OIDC 回调问题需结合客户端浏览器所在位置排查。

部署、PKI、SSH 签名、本地 agent 身份和恢复细节见 homelab-infra
`infrastructure/openbao/README.md`。服务依赖主机持久存储及 Raft 数据，人的登录还依赖 Authelia。
根密钥与恢复身份不应依赖 Kubernetes 或只能由 OpenBao 自身解密的秘密；
日常登录成功不等于已完成备份或灾难恢复验收。

来源文件的固定版本与工作区差异见[来源追溯](../sources.md#openbao)。