📚 课程目录第2章安装与配置

2. 安装与配置

说白了，安装配置这步是整个性能调优的地基。地基没打好，后面调再多的参数都是白搭。我在几个项目里都见过因为环境不一致导致的问题——开发环境跑得飞起，一上生产就各种报错。所以这一章，咱们稳扎稳打，把环境、安装、初始化这三个环节一次过。

2.1 环境要求

先看看你的环境达不达标。我个人习惯在项目一开始就用 Python 虚拟环境把版本锁死，省得后面被依赖冲突折腾。

操作系统：Linux（推荐 CentOS 7+ 或 Ubuntu 18.04+）、macOS 10.14+、Windows Server 2016+（生产环境不建议用 Windows）。
Python 版本：3.8 及以上。我遇到过有人在 Python 3.6 上装 SDK，结果有个加密库直接不兼容，折腾了大半天。
依赖库：libssl-dev（Linux）、openssl（macOS/Windows）、pip ≥ 21.0。如果用到硬件加速加密，还需要 libcrypto 的动态库。
网络：能正常访问对象存储服务的 endpoint，出网端口 443 要放开。

我的习惯：在项目根目录放一个 .python-version 文件，配合 pyenv 自动切换 Python 版本。团队里新人拉下代码就能直接装，不用在环境上浪费时间。

2.2 SDK 安装

安装方式有两种，我推荐大多数人直接用 pip 安装，省心。

方式一：pip 安装（推荐）

# 创建并激活虚拟环境（my_env 换成你喜欢的名字）
python -m venv my_env
source my_env/bin/activate  # Linux / macOS
# my_env\Scripts\activate   # Windows

# 安装 SDK
pip install oss-encrypt-sdk

嗯，这里要注意一点：如果你在内网环境，没法直接连 PyPI，可以先把包下载下来再离线装。我曾经在一个金融客户那边就是离线部署，用 pip download 提前把依赖都拉下来，省得到现场抓瞎。

方式二：源码安装

git clone https://github.com/your-org/oss-encrypt-sdk.git
cd oss-encrypt-sdk
pip install -e .

源码安装的好处是你可以直接调试 SDK 内部的逻辑，适合需要深度定制加密策略的团队。不过大多数场景下，pip 安装就够了。

验证安装

python -c "from oss_encrypt_sdk import EncryptClient; print('SDK 安装成功')"

如果没报错，说明 SDK 已经就位。我记得有一次在 ARM 架构的 Mac 上跑这个命令，蹦了个 openssl 的 ABI 错误，后来升级了 libressl 才解决。所以验证这步别跳过。

2.3 初始化参数

SDK 装好了，接下来就是初始化。初始化直接决定了后续的性能上限，尤其是加密相关的几个参数，设错了后面改起来成本很高。

下面这个表格列出了最核心的初始化参数，我用橙色标注了与性能直接相关的项（嗯，这里只是语义上强调，颜色交给页面模板）。

参数名	类型	默认值	说明	推荐值
`encrypt_algorithm`	str	`'aes-256-gcm'`	加密算法，GCM 模式支持认证加密	`'aes-256-gcm'`
`key_rotation_interval`	int	`86400`	密钥轮换间隔（秒），越短越安全但开销越大	`86400`（1 天）
`buffer_size`	int	`8192`	加密缓冲区大小（字节），太小影响吞吐	`16384`（16 KB）
`encrypt_threads`	int	`4`	加密线程数，建议不超过 CPU 物理核数	`min(8, cpu_count())`
`cache_enabled`	bool	`True`	是否启用密钥缓存，关闭会降低性能	`True`
`endpoint`	str	无默认值	对象存储服务的接入地址	必填，按实际区域配置

    性能关键参数：buffer_size 和 encrypt_threads 对吞吐影响最大。我曾经在生产环境中把 buffer_size 设成 4096，结果小文件加密性能骤降 40%。后来调到 16384，问题直接解决了。

初始化代码示例

from oss_encrypt_sdk import EncryptClient
import os

client = EncryptClient(
    access_key=os.getenv('OSS_ACCESS_KEY'),
    secret_key=os.getenv('OSS_SECRET_KEY'),
    endpoint='https://oss-cn-hangzhou.example.com',
    encrypt_algorithm='aes-256-gcm',
    buffer_size=16384,            # 16 KB
    encrypt_threads=min(8, os.cpu_count()),
    cache_enabled=True,
    key_rotation_interval=86400   # 1 天
)

# 检查初始化状态
print(f"客户端就绪，加密算法: {client.encrypt_algorithm}")

注意：不要把 access_key 和 secret_key 硬编码在代码里。用环境变量或者密钥管理服务来加载，否则一旦代码泄露，密钥就裸奔了。

初始化完成后，我建议先做一次简单的连通性测试——上传一个 1 KB 的小文件看看能不能正常加密并写入。这一步能快速暴露网络、权限、加密参数三方面的问题。

整个安装配置链路就是这样。每个环节我都踩过坑，尤其是第三步的初始化参数，看似简单，但对性能的影响是全局性的。你按这个流程走一遍，环境就算稳了。