📚 课程目录第4章环境搭建与依赖安装

4. 环境搭建与依赖安装：Python虚拟环境、Docker、Vault Server、Redis缓存配置

搭建一套可用的审计密钥边界环境，其实没那么玄乎。说白了就是把几个核心组件串起来：Python 虚拟环境隔离依赖、Docker 跑服务容器、Vault Server 管密钥、Redis 当缓存。我这些年搭过不下十次这种环境，踩过的坑比踩过的地雷还多。今天咱们就一步步来，把地基打牢。

4.1 Python 虚拟环境：隔离依赖的第一步

为什么非要用虚拟环境？你想，一个项目依赖 Flask 2.0，另一个项目依赖 Flask 1.x，不隔离的话就是一场灾难。我刚开始做项目时图省事，全局装了一堆包，结果升级一个库炸了三个项目……从那以后，我再也不敢偷懒了。

用 venv 就行，Python 3.3+ 自带，不用额外装。推荐 Python 3.10 或 3.11，生产上已经很稳了。

# 创建虚拟环境
python3 -m venv audit-env

# 激活（Linux/macOS）
source audit-env/bin/activate

# 激活（Windows）
audit-env\Scripts\activate

# 确认 Python 和 pip 都在虚拟环境里
which python    # 应该指向 audit-env/bin/python
pip --version   # 应该显示 audit-env 下的 pip

个人习惯：我一般把虚拟环境建在项目根目录下，命名为 .venv 并加到 .gitignore 里。这样其他开发者拉下来后自己激活，不会把环境文件传到仓库里。

激活后，安装核心依赖：

pip install hvac redis flask gunicorn
pip freeze > requirements.txt   # 锁定版本，方便复现

你看，这样你的项目依赖就干干净净了。每次新人加入，只需要 pip install -r requirements.txt，省心。

4.2 Docker：服务容器化的基石

Docker 在这里的主要用途是跑 Vault 和 Redis。为什么不直接装？因为开发环境经常要清数据、换版本、模拟集群，用容器一键搞定。我记得有次在客户现场，对方的服务器系统特别老，直接装 Vault 折腾了两小时，后来换成 Docker 镜像三分钟就跑起来了。

先装 Docker（略过安装步骤），验证一下：

docker --version
docker compose version    # 新版用 docker compose（无横杠）

然后写个 docker-compose.yml，把 Vault 和 Redis 一起编排起来。这是我的习惯——别单独启动两个容器，用 compose 统一管理网络和数据卷。

# docker-compose.yml
version: '3.8'

services:
  vault:
    image: vault:1.13.3
    container_name: vault-server
    ports:
      - "8200:8200"
    environment:
      VAULT_DEV_ROOT__ID: root-   # 开发模式，别用在生产！
      VAULT_DEV_LISTEN_ADDRESS: 0.0.0.0:8200
    cap_add:
      - IPC_LOCK   # Vault 需要锁定内存
    volumes:
      - ./vault/config:/vault/config   # 可挂载配置文件

  redis:
    image: redis:7.2-alpine
    container_name: redis-cache
    ports:
      - "6379:6379"
    volumes:
      - ./redis-data:/data   # 持久化数据
    command: redis-server --appendonly yes   # 开启 AOF 持久化

避坑：VAULT_DEV_ROOT__ID 只用于本地开发。我曾经有一次忘记在生产前改成正式配置，结果 Vault 用的是开发模式，密钥全在内存里，重启就丢。教训深刻啊。

启动服务：

docker compose up -d
docker compose ps   # 确认两个容器都在运行

现在，http://localhost:8200 应该能看到 Vault 的 UI 了。用你在环境变量里设的 root- 登录进去，就能看到空白的密钥引擎。

4.3 Vault Server 配置：密钥管理的核心

Vault 启动后，咱们要初始化一个密钥引擎。我一般用 KV（Key-Value）引擎，版本 2，支持版本回溯和删除。初始化用 hvac 客户端或者直接用 Vault 官方的 CLI（客户端工具）。

# 先设环境变量，方便 CLI 访问
export VAULT_ADDR='http://127.0.0.1:8200'
export VAULT_='root-'

# 创建一个名为 audit-kv 的 KV 引擎，路径为 secret
vault secrets enable -path=secret -version=2 kv

# 写入一个测试密钥
vault kv put secret/audit/database username=admin password=S3cur3P@ss

# 读取验证
vault kv get secret/audit/database

如果一切正常，你会看到类似这样的输出：

====== Metadata ======
Key              Value
---              -----
created_time     2025-03-21T10:30:00.123456Z
deletion_time    n/a
destroyed        false
version          1

====== Data ======
Key         Value
---         -----
password    S3cur3P@ss
username    admin

嗯，这里要注意：Vault 默认不允许跨域访问。如果前端要直接调 Vault API，你得在 Vault 配置里加上 CORS 相关设置。不过咱们这个项目是通过后端 Python 调用，所以暂时不用管。

环境变量	用途	示例值
VAULT_ADDR	Vault 服务地址	http://127.0.0.1:8200
VAULT_	认证令牌	root-
VAULT_SKIP_VERIFY	跳过 TLS 验证（开发用）	true

核心原则：永远不要在代码里硬编码 Vault 。正式生产时用 Kubernetes 的 Service Account 或者 AWS IAM 角色做身份认证。本地开发图方便用 root-，但记着用完就撤。

4.4 Redis 缓存配置：提升响应速度

为什么要用 Redis？审计密钥边界项目里，Vault 每次读取密钥都有网络开销和限流。把频繁读取的密钥缓存到 Redis 里，能大幅降低延迟。我在一个高并发场景下测过，直接从 Vault 读平均 15ms，加上 Redis 缓存后降到 0.5ms——差了三十倍。

Redis 已经在 Docker 里跑起来了。接下来配置连接参数。咱们用 Python 的 redis 库连接它：

import redis

# 连接 Redis（默认无密码）
cache = redis.Redis(
    host='localhost',
    port=6379,
    db=0,
    decode_responses=True   # 自动把 bytes 转成 str
)

# 测试连接
cache.ping()   # 返回 True 就说明通了

# 设置一个缓存，TTL 60 秒
cache.setex('db_password', 60, 'S3cur3P@ss')

# 读取
value = cache.get('db_password')
print(value)   # 输出 S3cur3P@ss

大概就这么简单。不过有几个点要留意：

Redis 默认没有密码，生产上必须设置 requirepass，开发环境无所谓。
缓存过期时间（TTL）要设得合理。密钥缓存我一般设 30–60 秒，审计日志缓存可以长一点，比如 5 分钟。
数据量大的话，注意 maxmemory 策略，别让 Redis 撑爆内存。

我曾经踩过的坑：有一次我把 Vault 的数据库密码缓存设成 24 小时过期。结果晚上运维轮换密码了，我的服务还在用旧密码跑了半天，数据库连不上炸了一大片。从那时起，所有密钥缓存的 TTL 不超过 120 秒，并且和 Vault 的 watch 机制配合强制刷新。

4.5 整体架构·一张图说清

上面拆成了四个部分，咱们来看看它们之间是怎么配合的。我画了张流程图，帮你理清脉络。

我的架构习惯：Vault 和 Redis 不要混在一台机器上（虽然开发环境可以）。生产上 Vault 至少 3 节点做 HA，Redis 也用 Sentinel 或 Cluster。开发阶段先用单机跑通流程，别一开始就上集群，否则调试起来会崩溃。

4.6 验证整体连通性

所有组件都启动后，我们来写个简单的验证脚本，确保整个链路通顺：

#!/usr/bin/env python3
import hvac
import redis

# 1. 连接 Vault
vault_client = hvac.Client(url='http://127.0.0.1:8200', ='root-')
assert vault_client.is_authenticated(), "Vault 认证失败"

# 2. 读取密钥
secret = vault_client.secrets.kv.v2.read_secret_version(path='audit/database')
db_password = secret['data']['data']['password']
print(f"从 Vault 读取到 password: {db_password}")

# 3. 写入 Redis 缓存
cache = redis.Redis(host='localhost', port=6379, db=0, decode_responses=True)
cache.setex('db_password', 60, db_password)

# 4. 从 Redis 读回
cached = cache.get('db_password')
assert cached == db_password, "缓存不一致"
print("Redis 缓存验证通过！")
print("全套环境搭建完成，所有依赖已就绪。")

如果这个脚本无差错运行完毕，恭喜你，环境已经搭好了。接下来就可以基于这套基础写业务逻辑了。嗯，最后说一句：别在 root 上做任何持久化，开发完记得清理掉。