Vault Enterprise Docker 镜像文档

1. 镜像概述

1.1 许可说明

本镜像包含 HashiCorp 企业版软件，仅授权给与 HashiCorp 或其授权经销商签订有效许可协议的客户使用。未获得有效许可的用户不得下载或使用本软件。软件的所有使用均受许可协议条款约束，其他所有权利均明确保留。

除非您的组织已签署单独协议规范本软件的使用，否则以下条款适用：软件受许可条款或社区许可（如 Mozilla Public License 2.0 或 Business Source License）约束（视情况而定），相关许可文件位于软件下载包中、IBM International Program License Agreement、IBM International License Agreement for Evaluation of Programs（评估用途）或 IBM International License Agreement for Early Release of Programs（alpha 和 beta 版本），以及适用的许可信息（副本可在 [***] 获取）。若下载包中的许可文件与上述 IBM 许可存在冲突，以相关 IBM 条款为准。使用前请参阅许可条款，安装和使用软件即表示您接受这些条款；如不接受，请勿使用。

1.2 主要用途

Vault 是一款用于安全访问机密信息的工具。机密信息指任何需要严格控制访问的内容，如 API 密钥、密码、证书等。Vault 提供统一的机密访问接口，同时实现细粒度访问控制和详细审计日志记录。

2. 核心功能和特性

2.1 Vault 核心功能

• 机密统一管理：支持各类机密信息（API 密钥、密码、证书等）的集中存储与访问。
• 细粒度访问控制：通过策略和身份验证机制严格控制机密访问权限。
• 详细审计日志：记录所有机密访问操作，支持合规审计与安全追溯。

2.2 Docker 镜像特性

• 轻量安全基础：基于 Alpine 镜像构建，具有较小的攻击面和足够的开发调试功能。
• 进程管理：通过 dumb-init 处理僵尸进程回收并转发信号，确保容器内进程稳定运行（dumb-init 二进制由 HashiCorp 构建并使用其 GPG 密钥签名）。
• 灵活配置方式：支持通过目录挂载（/vault/config）或环境变量（VAULT_LOCAL_CONFIG）注入配置。
• 持久化支持：提供 /vault/logs（审计日志）和 /vault/file（文件存储后端数据）两个可选卷，支持数据持久化。

3. 使用场景和适用范围

3.1 开发环境

• 快速启动：通过开发模式（dev server）运行完全基于内存的 Vault 服务器，适合本地开发和测试。
• 简化配置：无需复杂的持久化存储和 TLS 配置，通过环境变量快速自定义根令牌和监听地址。

3.2 生产环境

• 安全部署：需配置持久化存储后端（如 file、Consul 等）、启用 TLS 加密，并通过容器编排工具（如 Kubernetes、OpenShift）实现高可用。
• 集群扩展：支持通过 VAULT_REDIRECT_INTERFACE 和 VAULT_CLUSTER_INTERFACE 环境变量配置集群网络接口，适应分布式部署需求。

4. 使用方法和配置说明

4.1 容器基础信息

4.1.1 基础镜像与进程管理

• 基础镜像：Alpine Linux，轻量且安全。
• 进程管理：Vault 始终在 dumb-init 下运行，负责信号转发和僵尸进程回收。

4.1.2 卷定义

容器暴露两个可选卷，需手动启用对应功能后生效：

• /vault/logs：审计日志存储路径，需启用 file 审计后端并指定此目录下的路径。
• /vault/file：文件存储后端数据路径，需在配置中启用 file 存储后端。

4.1.3 配置加载方式

• 配置目录：容器默认配置目录为 /vault/config，挂载卷或构建新镜像时添加的 HCL/JSON 文件会被自动加载。
• 环境变量配置：通过 VAULT_LOCAL_CONFIG 环境变量传入 JSON 格式配置，容器会将其写入 /vault/config/local.json 并加载。

4.2 内存锁定与 setcap

4.2.1 内存锁定必要性

Vault 会尝试锁定内存以防止敏感数据交换到磁盘，因此启动容器时需添加 --cap-add=IPC_LOCK 权限。由于 Vault 以非 root 用户运行，容器通过 setcap 为二进制授予内存锁定能力。

4.2.2 兼容性处理

部分 Docker 存储插件（如 AUFS）可能导致 setcap 调用失败，可通过设置环境变量 SKIP_SETCAP 为任意非空值禁用内存锁定功能。

4.3 开发模式运行

4.3.1 基本命令

docker run --cap-add=IPC_LOCK -d --name=dev-vault hashicorp/vault

• 说明：启动基于内存的开发模式服务器，默认监听 0.0.0.0:8200，生成随机根令牌。

4.3.2 自定义开发模式配置

通过环境变量自定义开发模式参数：

• VAULT_DEV_ROOT_TOKEN_ID：设置初始根令牌 ID（默认随机生成）。
• VAULT_DEV_LISTEN_ADDRESS：设置监听地址（默认 0.0.0.0:8200）。

示例：

docker run --cap-add=IPC_LOCK -e 'VAULT_DEV_ROOT_TOKEN_ID=myroot' -e 'VAULT_DEV_LISTEN_ADDRESS=0.0.0.0:1234' hashicorp/vault

4.4 服务器模式运行（开发用）

4.4.1 基本配置示例

以下命令启动带文件存储后端的 Vault 服务器（注意：禁用 TLS 和文件存储不推荐生产环境使用）：

docker run \
  --cap-add=IPC_LOCK \
  -e 'VAULT_LOCAL_CONFIG={"storage": {"file": {"path": "/vault/file"}}, "listener": [{"tcp": {"address": "0.0.0.0:8200", "tls_disable": true}}], "default_lease_ttl": "168h", "max_lease_ttl": "720h", "ui": true}' \
  -p 8200:8200 \
  hashicorp/vault server

• 配置说明：文件存储路径 /vault/file，监听 0.0.0.0:8200（禁用 TLS），默认租约 168 小时（7 天），最大租约 720 小时（30 天），启用 Web UI。

4.4.2 目录挂载配置

通过卷挂载注入配置文件和 TLS 证书：

docker run \
  --cap-add=IPC_LOCK \
  --volume ./config:/vault/config \  # 挂载本地配置目录至容器 /vault/config
  -p 8200:8200 \
  hashicorp/vault server

• 说明：本地 ./config 目录下的 HCL/JSON 文件会被自动加载。

4.5 环境变量说明

5. Docker 部署示例

5.1 开发模式部署

# 启动开发模式 Vault，自动生成根令牌
docker run --cap-add=IPC_LOCK -d --name=dev-vault -p 8200:8200 hashicorp/vault

# 自定义根令牌和监听地址
docker run --cap-add=IPC_LOCK -d \
  --name=custom-dev-vault \
  -e 'VAULT_DEV_ROOT_TOKEN_ID=dev-root-token' \
  -e 'VAULT_DEV_LISTEN_ADDRESS=0.0.0.0:8201' \
  -p 8201:8201 \
  hashicorp/vault

5.2 服务器模式（开发用）部署

# 使用文件存储后端和禁用 TLS（仅开发用）
docker run --cap-add=IPC_LOCK -d \
  --name=server-vault \
  -e 'VAULT_LOCAL_CONFIG={"storage": {"file": {"path": "/vault/file"}}, "listener": [{"tcp": {"address": "0.0.0.0:8200", "tls_disable": true}}], "ui": true}' \
  -v ./vault-data:/vault/file \  # 挂载本地目录持久化文件存储数据
  -p 8200:8200 \
  hashicorp/vault server

5.3 docker-compose 示例（开发环境）

version: '3'
services:
  vault:
    image: hashicorp/vault
    container_name: dev-vault
    cap_add:
      - IPC_LOCK
    ports:
      - "8200:8200"
    environment:
      - VAULT_DEV_ROOT_TOKEN_ID=dev-root-token
      - VAULT_DEV_LISTEN_ADDRESS=0.0.0.0:8200
    restart: unless-stopped

6. 参考链接

• Vault 官方文档
• Vault GitHub 仓库
• Vault 开发服务器文档
• Vault 配置文档