第4章 开发环境准备：安装与配置
环境准备这一步，说来简单，但踩过的坑还真不少。我记得刚接触对象存储那会儿，光配置密钥和端点就折腾了大半天。嗯，今天咱们把这些坑提前填上。
4.1 安装依赖SDK包
选哪个SDK包？这其实取决于你用哪家云厂商。不过核心逻辑都差不多——发HTTP请求、处理签名、读写数据。
| SDK包 | 适用平台 | 安装命令 | 加密支持 |
|---|---|---|---|
| boto3 | AWS S3 | pip install boto3 | SSE-S3、SSE-KMS、SSE-C |
| oss2 | 阿里云OSS | pip install oss2 | 服务端加密、客户端加密 |
| obs-sdk | 华为云OBS | pip install esdk-obs-python | SSE-OBS、SSE-KMS |
| minio-py | MinIO (自建) | pip install minio | SSE-S3、SSE-C |
版本锁定很重要 —— 我在项目中遇到过，直接 pip install 拉最新版，结果跟内部依赖冲突，跑了两天才定位到是 SDK 版本问题。建议锁死小版本：
# requirements.txt
boto3==1.28.0
botocore==1.31.0
# 其他依赖同理你想想看，SDK 升级了签名算法怎么办？锁版本至少能保证生产环境不出幺蛾子。个人习惯是上线前在测试环境先升一遍。
还有一个坑：有些 SDK 依赖底层 C 扩展库（比如 crcmod），如果安装报错，先去装好 gcc 或 Visual Studio Build Tools。
4.2 配置密钥与端点
密钥这东西，说白了就是你的云上身份证。建议不要硬编码到代码里。
4.2.1 密钥从哪里来？
- 云控制台 → 访问控制 → 创建 AccessKey
- 一般包含：AccessKeyId（公钥）、AccessKeySecret（私钥）
- 有些平台还需要 SecurityToken（临时凭证）
4.2.2 三种配置方式
- 环境变量（推荐）：
export AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY export AWS_DEFAULT_REGION=cn-north-1 - 配置文件：
# ~/.aws/credentials [default] aws_access_key_id = AKIAIOSFODNN7EXAMPLE aws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY - 代码传参（仅限一次性脚本）：
client = boto3.client( 's3', aws_access_key_id='AKIAIOSFODNN7EXAMPLE', aws_secret_access_key='wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY', endpoint_url='https://s3.cn-north-1.amazonaws.com.cn' )
我曾经见过 GitHub 上有人把密钥硬编码提交上去了，当晚服务器就被挖矿程序光顾了。不要让密钥离开你的控制范围。环境变量和密钥管理服务（如 AWS Secrets Manager）才是正道。
4.2.3 端点（Endpoint）该怎么配？
端点就是存储服务的入口地址。不同区域、不同合规要求会影响端点格式。举个栗子：
| 场景 | 端点示例 |
|---|---|
| S3 标准端点 | https://s3.us-east-1.amazonaws.com |
| S3 中国区端点 | https://s3.cn-north-1.amazonaws.com.cn |
| 阿里云 OSS 内网 | https://oss-cn-beijing-internal.aliyuncs.com |
| MinIO 自建 | http://192.168.1.100:9000 |
我建议：如果只是开发测试阶段，用 HTTP 端点可以省去 TLS 握手时间。但生产环境必须走 HTTPS，别省那个证书钱。
4.3 初始化客户端的最佳实践
初始化客户端这一步，说白了就是告诉 SDK：「这是我的身份，这是我的服务地址，请开始工作。」
4.3.1 客户端生命周期
我个人习惯是：客户端只初始化一次，然后复用。每次请求都重新创建客户端？那性能就别提了。
import boto3
# 错误示范：每次请求都创建
def upload_file_bad(bucket, key, data):
s3 = boto3.client('s3')
s3.put_object(Bucket=bucket, Key=key, Body=data)
# 正确做法：全局复用
s3 = boto3.client('s3')
def upload_file_good(bucket, key, data):
s3.put_object(Bucket=bucket, Key=key, Body=data)4.3.2 配置参数的建议
- 超时时间：connect_timeout=5, read_timeout=30，避免网络抖动卡死
- 重试策略：max_attempts=3，指数退避
- 连接池：max_pool_connections=10，并发上传时很有用
- 签名版本：AWS 用 sigv4，其他厂商同理
我曾经在处理海量小文件上传时，没配连接池，结果并发一高就报连接超时。后来配了 max_pool_connections=50，问题就解决了。
from botocore.config import Config
my_config = Config(
region_name='cn-north-1',
signature_version='s3v4',
retries={
'max_attempts': 3,
'mode': 'adaptive'
},
connect_timeout=5,
read_timeout=30,
max_pool_connections=10
)
s3 = boto3.client('s3', config=my_config)4.3.3 加密相关的初始化
如果你的场景需要客户端加密，初始化时就要指定加密器。这点很容易忽略——很多人等跑通了再补加密，结果还得改代码。
from crypto import CryptoMaterial
material = CryptoMaterial(
key_id='arn:aws:kms:cn-north-1:123456789:key/xxxx',
encryption_algorithm='AES256'
)
s3_crypto = boto3.client('s3', config=my_config, crypto_material=material)注意：加密器初始化后，后续所有读写操作都会自动加密/解密。不要在初始化后手动更改加密方式，容易造成数据写入加密、读取时无法解密的尴尬情况。
4.4 知识体系结构图
下面这张图能帮你把本章的各个要点串起来：
把这张图记在脑子里，以后配任何对象存储 SDK，都是这个流程。嗯，我每次接新项目都会画一遍这个图。
4.5 第一个连接测试
要验证所有配置是否正确？写个最小的健康检查：
import boto3
from botocore.exceptions import ClientError, EndpointConnectionError
try:
s3 = boto3.client('s3')
s3.list_buckets()
print("✅ 连接成功，SDK 工作正常！")
except EndpointConnectionError:
print("❌ 端点不可达，检查网络或端点地址")
except ClientError as e:
print(f"❌ 认证失败：{e.response['Error']['Code']}")
print(" 请检查密钥和权限")那个「端点不可达」的报错，我见过好几次。原因往往是内网用了外网端点，或者反之。搞清楚了再往上写业务逻辑。