Vault 凭据与加密密钥管理平台部署详解
在 Ubuntu 22.04 上从零部署 HashiCorp Vault 2.1.2，覆盖 raft 单节点初始化、解封、KV v2 写读与 PKI 发证的完整实测流程与 CLI 速查。
Vault 凭据与加密密钥管理平台部署详解
目标：在 Ubuntu 22.04 服务器上从零安装并运行 HashiCorp Vault 2.1.2，完成单节点 raft 存储初始化、解封、登录、KV v2 密钥写读、PKI 证书签发等核心操作，并沉淀命令与参数速查。全文命令与回显均在 Ubuntu 22.04 环境逐条实测通过。
Vault 是 HashiCorp 出品的凭据与加密密钥管理平台，用于统一管理数据库口令、API Token、TLS 证书等敏感数据，并支持泄露应急吊销（Encryption as a Service）。本体系可使用 raft 作为内置存储后端，无需额外依赖数据库，部署与运维都相当简洁。
环境信息
- 操作系统：Ubuntu 22.04（x86_64）
- 架构：amd64
- Vault 版本：2.1.2（
76fdd6587523c4c6cb079635075e019714d23470，built 2026-10-06） - 存储后端：集成 raft（数据目录
/opt/data/vault） - 监听端口：API
8200、集群8201 - 配置文件：
/etc/vault.hcl - 可执行文件：
/usr/local/bin/vault
一、版本选型与获取
Vault 分为社区开源版（Vault OSS）与企业版（Vault Enterprise）。社区版即已包含 raft、KV、PKI、Transit 等绝大多数日常能力，免费且无 license 限制，本文使用社区版。
版本通过 GitHub Releases 与官方 apt/yum 仓库同步发布，命名格式为 X.Y.Z。查询最新版本：
curl -s https://api.github.com/repos/hashicorp/vault/releases/latest | grep tag_name
实测获取到的最新版本为 2.1.2。对应也提供了 sha256 校验文件，下载后可用于完整性核验。
| 渠道 | 用途 | 优缺点 |
|---|---|---|
| 官方二进制 zip（本文） | 标准部署 | 单文件、无依赖、便于固定版本 |
| HashiCorp apt 仓库 | 便于升级 | 依赖配置官方源 |
| HashiCorp yum 仓库 | RHEL 系 | 依赖配置官方源 |
二、部署前基础环境
使用 root 用户操作。先更新软件源并安装解压与签名校验工具：
apt-get update
apt-get install -y unzip wget curl jq openssl
💡 说明：Vault 是使用 Go 语言编译的静态二进制，常驻内存默认较小（实测常驻内存 RSS 约 172MB，见第六节），不依赖 JVM，也无需像 Java 组件那样手工配置大堆内存参数。
三、官方二进制安装方案（推荐）
3.1 下载官方二进制并更新 PATH
进入固定安装目录，下载对应架构（amd64）的官方 zip：
cd /opt && mkdir -p vault && cd vault
wget https://releases.hashicorp.com/vault/2.1.2/vault_2.1.2_linux_amd64.zip -O vault.zip
unzip -o vault.zip
ls -la vault
实测解压后的文件清单：
total 702592
drwxr-xr-x 2 root root 4096 Oct 8 12:50 .
drwxr-xr-x 1 root root 4096 Oct 8 12:50 ..
-rw-r--r-- 1 root root 4919 Oct 6 19:22 LICENSE.txt
-rwxr-xr-x 1 root root 542044147 Oct 6 19:22 vault
-rw-r--r-- 1 root root 177382870 Oct 7 13:37 vault.zip
拷贝到 /usr/local/bin 并设置可执行权限，然后查看版本：
install -o root -g root -m 0755 vault /usr/local/bin/vault
vault version
实测回显：
Vault v2.1.2 (76fdd6587523c4c6cb079635075e019714d23470), built 2026-10-06T15:17:37Z
3.2 编写生产配置
使用 raft 单节点配置，数据落盘到 /opt/data/vault：
mkdir -p /opt/data/vault
创建配置文件 /etc/vault.hcl：
storage "raft" {
path = "/opt/data/vault"
node_id = "vault-node-1"
}
listener "tcp" {
address = "0.0.0.0:8200"
tls_disable = "true"
}
disable_mlock = true
api_addr = "http://127.0.0.1:8200"
cluster_addr = "http://127.0.0.1:8201"
ui = true
⚠️ 注意：
disable_mlock = true表明允许 Vault 不使用 mlock，在没有该能力的普通环境必须开启，否则启动会报Failed to lock memory。生产高可信环境可关闭此选项以启用内存锁定保护。 ⚠️ 注意：tls_disable = true关闭了 API 监听层 TLS。生产通常改由前置反向代理终结 TLS，或改为配置 HTTPS 证书；此处为演示单点直连。
3.3 启动 Vault 服务
推荐使用 systemd 托管，实现开机自启与崩溃拉起。创建单元 /etc/systemd/system/vault.service：
[Unit]
Description=HashiCorp Vault
After=network-online.target
[Service]
ExecStart=/usr/local/bin/vault server -config=/etc/vault.hcl
Restart=on-failure
RestartSec=5
User=root
Group=root
LimitNOFILE=65536
[Install]
WantedBy=multi-user.target
重载并启动（systemctl 每行仅一个单元）：
systemctl daemon-reload
systemctl enable vault
systemctl start vault
systemctl is-active vault
实测回显：
active
💡 说明：
systemctl enable与systemctl start都只针对vault单个单元，符合「行内单单元」规范。
四、初始化（初始化、解封）与登录
4.1 查看初始状态
启动后 Vault 处于未初始化、已封印状态：
export VAULT_ADDR=http://127.0.0.1:8200
vault status
实测回显：
Key Value
--- -----
Seal Type shamir
Initialized false
Sealed true
Total Shares 0
Threshold 0
Unseal Progress 0/0
Unseal Nonce n/a
Version 2.1.2
Build Date 2026-10-06T15:17:37Z
Storage Type raft
Removed From Cluster false
HA Enabled true
4.2 初始化生成加密密钥与根令牌
第一次使用必须执行 vault operator init。这里用 -key-shares=1 -key-threshold=1（演示用 1 把解封密钥、需 1 把即可解封）；生产建议至少 5/3：
vault operator init -key-shares=1 -key-threshold=1
实测回显（⚠️ 密钥与令牌为一次性生成值，绝不外泄，请立即记录该输出到安全位置如密码管理器）：
Unseal Key 1: <解封密钥，立即保存到安全位置>
Initial Root Token: <初始根令牌，立即保存到安全位置>
Vault initialized with 1 key shares and a key threshold of 1. Please securely
distribute the key shares printed above. When the Vault is re-sealed,
restarted, or stopped, you must supply at least 1 of these keys to unseal it
before it can start servicing requests.
Vault does not store the generated root key. Without at least 1 keys to
reconstruct the root key, Vault will remain permanently sealed!
It is possible to generate new unseal keys, provided you have a quorum of
existing unseal keys shares. See "vault operator rekey" for more information.
💡 说明：
Unseal Key（解封密钥）与Initial Root Token（初始根令牌）只在此刻明文显示一次，Vault 不会保存它们。请务必复制保存，否则重启封印后无法恢复访问，属于不可逆的数据安全风险。
4.3 解封
初始化后是封印状态，需要解封：
vault operator unseal "<解封密钥>"
实测回显：
Key Value
--- -----
Seal Type shamir
Initialized true
Sealed false
Total Shares 1
Threshold 1
Version 2.1.2
Build Date 2026-10-06T15:17:37Z
Storage Type raft
Cluster Name vault-cluster-e03a3907
Cluster ID c5e9c5a2-8a11-d02a-d205-83c440f40522
Removed From Cluster false
HA Enabled true
HA Cluster n/a
HA Mode standby
Active Node Address <none>
Raft Committed Index 33
Raft Applied Index 33
再次执行 vault status 确认已为 active：
Key Value
--- -----
Seal Type shamir
Initialized true
Sealed false
Total Shares 1
Threshold 1
Version 2.1.2
Build Date 2026-10-06T15:17:37Z
Storage Type raft
Cluster Name vault-cluster-e03a3907
Cluster ID c5e9c5a2-8a11-d02a-d205-83c440f40522
Removed From Cluster false
HA Enabled true
HA Cluster https://127.0.0.1:8201
HA Mode active
Active Since 2026-10-08T12:51:39.080293267Z
Raft Committed Index 38
Raft Applied Index 38
4.4 登录
使用根令牌登录：
export VAULT_TOKEN="<初始根令牌>"
vault login "$VAULT_TOKEN"
实测回显：
Success! You are now authenticated. The token information displayed below
is already stored in the token helper. You do NOT need to run "vault login"
again. Future Vault requests will automatically use this token.
Key Value
--- -----
token hvs.<根令牌>
token_accessor <token accessor>
token_duration ∞
token_renewable false
token_policies ["root"]
identity_policies []
policies ["root"]
WARNING! The VAULT_TOKEN environment variable is set! The value of this
variable will take precedence; if this is unwanted please unset VAULT_TOKEN or
update its value accordingly.
⚠️ 注意：
vault login会把令牌写入 token helper 便于后续复用；但同时设置VAULT_TOKEN环境变量时以环境变量优先，二者并存会出现上述 WARNING，按需unset VAULT_TOKEN即可。
五、使用 KV v2 存取密钥
KV secrets engine 是使用最频繁的引擎，v2 版本支持版本管理与回滚。
5.1 挂载 KV（版本 2）
vault secrets enable -path=secret -version=2 kv
实测回显：
Success! Enabled the kv secrets engine at: secret/
5.2 写入密钥
vault kv put secret/webserver/pgadmin user=admin pass=q1w2e3r4
实测回显：
======== Secret Path ========
secret/data/webserver/pgadmin
======= Metadata =======
Key Value
--- -----
created_time 2026-10-08T12:51:43.747570186Z
custom_metadata <nil>
deletion_time n/a
destroyed false
version 1
5.3 读取密钥
vault kv get secret/webserver/pgadmin
实测回显：
======== Secret Path ========
secret/data/webserver/pgadmin
======= Metadata =======
Key Value
--- -----
created_time 2026-10-08T12:51:43.747570186Z
custom_metadata <nil>
deletion_time n/a
destroyed false
version 1
==== Data ====
Key Value
--- -----
pass q1w2e3r4
user admin
5.4 查看已启用引擎
vault secrets list
实测回显（raft 存储下新增了 secret/）：
Path Type Accessor Description
---- ---- -------- -----------
agent-registry/ agent_registry agent-registry_da0a88d8 agent registry
cubbyhole/ cubbyhole cubbyhole_9a620567 per-token private secret storage
identity/ identity identity_19ed6b1d identity store
secret/ kv kv_6eeab65a n/a
sys/ system system_fdccd42b system endpoints used for control, policy and debugging
六、进程内存与资源说明
Vault 是 Go 语言静态编译的程序，不存在 JVM 的堆内存概念，-Xmx 等参数不适用。官方无需手工调大堆内存，其内存使用随存储与并发请求量动态增长。实测 ps 查看常驻内存：
ps -eo pid,rss,comm,args | grep [v]ault
实测回显（RSS 单位为 KB，约 172MB）：
PID RSS COMMAND COMMAND
2741 176296 vault vault server -config=/etc/vault.hcl
💡 说明：Vault 启动即占用约 170MB 常驻内存，属正常现象（包含 raft 快照与 seal/unseal 引擎）。对 2GB 以上内存的服务器完全够用，无需额外配置。
七、PKI 证书签发（签名证书/自签名 CA）
本节演示用 Vault 的 PKI 引擎自建根 CA 并签发工作证书，是《证书管理》专栏的核心用法。
7.1 启用 PKI 并设置证书有效期
vault secrets enable pki
vault secrets tune -max-lease-ttl=87600h pki
实测回显：
Success! Enabled the pki secrets engine at: pki/
Success! Tuned the secrets engine at: pki/
7.2 生成自签名根 CA
vault write -field=certificate pki/root/generate/internal common_name=example.com ttl=87600h
实测回显（输出为 PEM 证书，此处截断展示）：
-----BEGIN CERTIFICATE-----
MIIDNTCCAh2gAwIBAgIUKkMUeehTy7Ui53r+vKYWVXEytrswDQYJKoZIhvcNAQEL
BQAwFjEUMBIGA1UEAxMLZXhhbXBsZS5jb20wHhcNMjYxMDA4MTI1MTM5WhcNMzYx
MDA1MTI1MjA5WjAWMRQwEgYDVQQDEwtleGFtcGxlLmNvbTCCASIwDQYJKoZIhvcNAQEB
（根 CA 证书正文略）
-----
7.3 配置 CA 与 CRL 地址
vault write pki/config/urls issuing_certificates="http://127.0.0.1:8200/v1/pki/ca" crl_distribution_points="http://127.0.0.1:8200/v1/pki/crl"
实测回显：
Key Value
--- -----
crl_distribution_points [http://127.0.0.1:8200/v1/pki/crl]
delta_crl_distribution_points []
enable_templating false
issuing_certificates [http://127.0.0.1:8200/v1/pki/ca]
ocsp_servers []
7.4 创建签发角色
vault write pki/roles/webapp allowed_domains=example.com allow_subdomains=true max_ttl=720h
实测回显（关键行）：
Key Value
--- -----
allow_subdomains true
allowed_domains [example.com]
key_bits 2048
key_type rsa
max_ttl 720h
server_flag true
7.5 通过角色签发证书
vault write -format=json pki/issue/webapp common_name=app.example.com ttl=72h | jq .data.certificate
实测回显（开头，已对 PEM 证书内容做截断展示）：
"-----BEGIN CERTIFICATE-----\nMIIDvTCCAqWgAwIBAgIUAePnFAdZPA0qUomwTCNuEF/bmNQwDQYJKoZIhvcNAQEL\nBQAwFjEUMBIGA1UEAxMLd2Vi…（证书正文截断）----"
💡 说明：上述 PKI 演示完成后如需清理，可执行
vault secrets disable pki，实测回显Success! Disabled the secrets engine (if it existed) at: pki/。
八、常用 CLI 命令速查
以下为实测 vault --help 顶层结构与常用命令：
8.1 顶层帮助
vault --help
实测回显：
Usage: vault <command> [args]
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 a Vault agent
server Start a Vault server
status Print seal and HA status
unwrap Unwrap a wrapped secret
Other commands:
audit Interact with audit devices
auth Interact with auth methods
debug Runs the debug command
events
hcp
kv Interact with Vault's Key-Value storage
lease Interact with leases
monitor Stream log messages from a Vault server
namespace Interact with namespaces
operator Perform operator-specific tasks
patch Patch data, configuration, and secrets
path-help Retrieve API help for paths
pki Interact with Vault's PKI Secrets Engine
plugin Interact with Vault plugins and catalog
policy Interact with policies
print Prints runtime configurations
proxy Start a Vault Proxy
secrets Interact with secrets engines
ssh Initiate an SSH session
token Interact with tokens
transform Interact with Vault's Transform Secrets Engine
transit Interact with Vault's Transit Secrets Engine
version-history Prints the version history of the target Vault server
8.2 运维子命令
vault operator --help
实测回显：
Subcommands:
diagnose Troubleshoot problems starting Vault
generate-root Generates a new root, DR operation, or recovery token
init Initializes a server
key-status Provides information about the active encryption key
members Returns the list of nodes in the cluster
migrate Migrates Vault data between storage backends
raft Interact with Vault's raft storage backend
rekey Generates new unseal keys
rotate Rotates the underlying encryption key
seal Seals the Vault server
step-down Forces Vault to resign active duty
unseal Unseals the Vault server
usage Lists historical client counts
utilization Generates license utilization reporting bundle
8.3 KV 命令速查
vault kv --help
实测回显（核心示例）：
Create or update the key named "foo" in the "secret" mount with the value
"bar=baz":
$ vault kv put -mount=secret foo bar=baz
Read this value back:
$ vault kv get -mount=secret foo
Get metadata for the key:
$ vault kv metadata get -mount=secret foo
常用 KV 操作速查表：
| 操作 | 命令 |
|---|---|
| 读取某版本 | vault kv get -version=1 secret/webserver/pgadmin |
| 条件写入（CAS） | vault kv put -cas=1 secret/webserver/pgadmin user=admin pass=q1w2e3r4 |
| 删除数据 | vault kv delete secret/webserver/pgadmin |
| 查询元数据 | vault kv metadata get secret/webserver/pgadmin |
8.4 令牌与健康检查
# 生成一个 720h 有效期的子令牌（-field=token 只输出令牌本身）
vault token create -ttl=720h -field=token
# 吊销一个令牌
vault token revoke hvs.<子令牌>
# 吊销当前 token
vault token revoke-self
# 健康检查（JSON）
curl -s http://127.0.0.1:8200/v1/sys/health
实测 curl 健康检查回显：
{"initialized":true,"sealed":false,"standby":false,"performance_standby":false,"replication_performance_mode":"disabled","replication_dr_mode":"disabled","server_time_utc":1791463923,"version":"2.1.2","enterprise":false,"cluster_name":"vault-cluster-e03a3907","cluster_id":"c5e9c5a2-8a11-d02a-d205-83c440f40522","echo_duration_ms":0,"clock_skew_ms":0,"replication_primary_canary_age_ms":0,"removed_from_cluster":false}
九、封印与解封操作
执行 vault operator seal 会立即封印服务（封锁所有 API 访问），需重新解封：
vault operator seal
vault status | grep Sealed
实测回显：
Success! Vault is sealed.
Sealed true
重新解封：
vault operator unseal "<解封密钥>"
实测回显：
Sealed false
十、常见问题（FAQ）
Q1：启动报 Failed to lock memory 无法启动？
原因：环境不支持 mlock。处理：在配置中加
disable_mlock = true后重启，见 3.2 节。
Q2：vault operator init 后忘记保存解封密钥/根令牌？
若密钥已丢失，则 Vault 永久封印不可恢复，只能清空
/opt/data/vault重新初始化（会丢失所有数据）。若令牌丢失但未封印，可用vault operator generate-root生成新根令牌。
Q3：vault login 显示 WARNING VAULT_TOKEN 优先？
说明同一会话中同时设置了环境变量与 token helper。按需
unset VAULT_TOKEN或调用前清理环境。
Q4：KV 并发写入冲突？
使用
-cas（Check-And-Set）参数做版本条件写入。例如当前版本为 1，写入版本 2 时：
vault kv put -cas=1 secret/webserver/pgadmin user=admin pass=q1w2e3r4
若版本不匹配会报类似
Error writing data to secret/data/webserver/pgadmin: Error making API request.的错误，需以vault kv get -output-version或元数据中的version校准后重试。
Q5：如何安全清空数据后完全卸载？
systemctl disable vault
systemctl stop vault
rm -f /usr/local/bin/vault
rm -rf /opt/vault
rm -rf /opt/data/vault
rm -f /etc/vault.hcl
rm -f /etc/systemd/system/vault.service
systemctl daemon-reload
注意：
rm -rf /opt/data/vault不可逆，将彻底删除所有已保存的密钥与证书，请确认已导出或不再需要。
十一、卸载方式
- 停止并禁用服务（systemctl 每行仅一个单元）：见 Q5。
- 删除二进制：
rm -f /usr/local/bin/vault。 - 删除配置与数据目录：
rm -f /etc/vault.hcl && rm -rf /opt/vault /opt/data/vault。 - 删除 systemd 单元并重载：
rm -f /etc/systemd/system/vault.service && systemctl daemon-reload。
参考链接
- Vault 官方文档：https://developer.hashicorp.com/vault/docs
- Vault 官方下载：https://www.vaultproject.io/downloads
- Vault GitHub Releases：https://github.com/hashicorp/vault/releases