那天下午，我盯着屏幕上红色的报错日志，脑子里全是问号。明明代码没动，AccessKey 也是从控制台复制的，怎么 suddenly 就报 “SignatureDoesNotMatch” 了？这一排查，就是整整三个小时。为了不让各位踩同样的坑，我把这3小时里经历的所有曲折、怀疑人生、以及最终绝处逢生的瞬间，都还原在这儿。如果你现在也正被青云（QingCloud）对象存储的签名问题折磨，这篇文章就是为你准备的。
第一幕：平静的表面下，暗流涌动
事情是这样的，我有一个Python小脚本，用来往青云对象存储里上传一些日志文件。逻辑很简单：构建请求 -> 生成签名 -> 发送HTTP PUT -> 上传成功。这套逻辑跑了半年，稳如老狗。
直到那天下午，代码突然罢工。
错误信息很标准，也很讨厌：
An error occurred (SignatureDoesNotMatch) on request
我的第一反应是：肯定是时序问题。云服务的签名生成，极其依赖时间戳。如果客户端时间和服务器时间差超过几分钟，签名就会失效。
我立刻检查了本机时间：
$ date
Mon Oct 23 14:32:05 CST 2023
时间看起来正常，而且是NTP同步过的。我又尝试在代码里强制打印当前Unix时间戳，和青云控制台的时间比对，误差在毫秒级。
时间没问题，那会是啥？
我开始怀疑AccessKey。是不是我的Key泄露了被重置了？我登录青云控制台，找到IAM（身份访问管理）页面，准备创建新的Key。
等等，我注意到一个细节。我创建Key的时候，界面提示：”AccessKey ID” 和 “Secret Access Key”。我复制粘贴的时候，习惯性地选了整个字符串，包括可能存在的不可见字符。
为了排除这个干扰，我新建了一组AccessKey，小心翼翼地逐个字符复制，确保没有任何多余的空格或换行符。我把新Key写进环境变量，重新运行脚本。
结果：SignatureDoesNotMatch。
新建Key也没用。 这时候，我的情绪开始有点崩了。是不是青云的API变了？是不是我的SDK版本太老？
第二幕：深入“S3兼容”的泥潭
青云对象存储是S3兼容的，这意味着它的签名机制和AWS S3是一模一样的。我决定换一种思路：不用Python自带的boto3库，而是用requests库手动构建请求，这样能更清晰地看到签名的生成过程。
我写了一个最小化的测试脚本：
import hashlib
import hmac
import base64
import requests
from datetime import datetime
import time
# 配置信息
AK = '你的AccessKey_ID'
SK = '你的SecretAccessKey'
REGION = 'cn-bj2'
BUCKET = 'my-test-bucket'
ENDPOINT = f'https://{BUCKET}.s3.{REGION}.qingcloud.com'
OBJECT_KEY = 'hello.txt'
def sign(key, msg):
return hmac.new(key, msg.encode('utf-8'), hashlib.sha256).digest()
def getSignatureKey(key, dateStamp, regionName, serviceName):
kDate = sign(('AWS4' + key).encode('utf-8'), dateStamp)
kRegion = sign(kDate, regionName)
kService = sign(kRegion, serviceName)
kSigning = sign(kService, 'aws4_request')
return kSigning
# 当前时间
now = datetime.utcnow()
amz_date = now.strftime('%Y%m%dT%H%M%SZ')
date_stamp = now.strftime('%Y%m%d')
# 构建Canonical Request（标准请求）
content_type = 'text/plain'
payload_hash = hashlib.sha256(b'hello qingcloud').hexdigest()
host = f'{BUCKET}.s3.{REGION}.qingcloud.com'
algorithm = 'AWS4-HMAC-SHA256'
canonical_uri = '/' + OBJECT_KEY
canonical_querystring = ''
canonical_headers = 'host:' + host + '\n' + 'x-amz-date:' + amz_date + '\n'
signed_headers = 'host;x-amz-date'
payload = payload_hash
canonical_request = algorithm + '\n' + \
canonical_uri + '\n' + \
canonical_querystring + '\n' + \
canonical_headers + '\n' + \
signed_headers + '\n' + \
payload_hash
# 构建String to Sign（待签名字符串）
credential_scope = date_stamp + '/' + REGION + '/s3/aws4_request'
string_to_sign = algorithm + '\n' + \
amz_date + '\n' + \
credential_scope + '\n' + \
hashlib.sha256(canonical_request.encode('utf-8')).hexdigest()
# 计算签名
signing_key = getSignatureKey(SK, date_stamp, REGION, 's3')
signature = hmac.new(signing_key, string_to_sign.encode('utf-8'), hashlib.sha256).hexdigest()
# 发送请求
headers = {
'Host': host,
'x-amz-date': amz_date,
'Authorization': algorithm + ' ' + 'Credential=' + AK + '/' + credential_scope + ', SignedHeaders=' + signed_headers + ', Signature=' + signature,
'Content-Type': content_type
}
url = f'https://{host}/{OBJECT_KEY}'
response = requests.put(url, data='hello qingcloud', headers=headers)
print(response.status_code)
print(response.text)
我满怀希望地运行起来……
403 Forbidden。错误码依然是 SignatureDoesNotMatch。
这次，我连调试的余地都没了。我决定把string_to_sign和signature打印出来，去对比青云官方文档的示例，或者找网上的类似案例。
第三幕：那个该死的“区域”陷阱
就在我要放弃，准备联系青云技术支持的时候，我瞥了一眼我的代码里的REGION变量。
REGION = 'cn-bj2'
我用的青云华北2区。这个没错啊，我的Bucket就在这个区域。
等等。
我突然想起，之前配置IAM用户权限的时候，我好像在哪里看到过关于”权限区域”的说明。青云的S3兼容服务，对于某些特定的区域，Endpoint的写法可能有细微差别。
我开始疯狂搜索青云官方文档，关键词是“S3兼容 签名错误 区域”。
在一篇很不起眼的FAQ里，我找到了线索：
注意： 青云对象存储的S3兼容接口，对于部分区域，
CanonicalizedResource（规范化资源路径）的计算可能涉及到Endpoint的特殊处理。特别是当Bucket名称中包含特殊字符，或者使用了虚拟主机式URL时，签名计算的基础URL可能与你预期的不同。
更重要的是，我注意到青云的S3 Endpoint有两种模式：
- 路径式（Path-Style）:
https://s3.cn-bj2.qingcloud.com/my-bucket/object - 虚拟主机式（Virtual-Hosted-Style）:
https://my-bucket.s3.cn-bj2.qingcloud.com/object
AWS的SDK默认通常使用虚拟主机式。而我之前的代码里，host变量我写的是：
host = f'{BUCKET}.s3.{REGION}.qingcloud.com'
这看起来是虚拟主机式。但是，我忽略了一个极其重要的点：青云的部分旧版本SDK，或者某些特定配置下，可能要求使用路径式URL进行签名计算，但请求发送时又用了虚拟主机式，或者反过来。
签名是和请求的HTTP Header里的Host字段以及URL的路径严格绑定的。 如果Host和URL不匹配，或者Region在签名计算和实际请求中存在不一致，就会报签名错误。
我尝试修改代码，强制使用路径式的Endpoint和签名逻辑：
# 修改为路径式
ENDPOINT = f'https://s3.{REGION}.qingcloud.com'
host = f's3.{REGION}.qingcloud.com'
canonical_uri = '/' + BUCKET + '/' + OBJECT_KEY
canonical_headers = 'host:' + host + '\n' + 'x-amz-date:' + amz_date + '\n'
# ... 其余逻辑不变，但请求的URL也要改为路径式
url = f'https://{host}/{BUCKET}/{OBJECT_KEY}'
重新运行。
200 OK！上传成功！
第四幕：真相大白——AccessKey的“隐藏”配置错误
虽然请求成功了，但我的心里还是有个疙瘩：为什么之前会失败？我明明用的是同一个AccessKey。
我回去复盘之前的代码。我之前用的是boto3，并且这样初始化：
import boto3
s3_client = boto3.client(
's3',
region_name=REGION,
aws_access_key_id=AK,
aws_secret_access_key=SK,
endpoint_url=f'https://s3.{REGION}.qingcloud.com'
)
看起来也没错啊。但是，boto3在内部生成签名时，会根据endpoint_url和region_name来计算Host Header和签名。
关键问题来了：
青云的S3兼容服务，在某些区域（尤其是早期开通的区域），其IAM用户的权限策略（Policy） 中，可能显式指定了该用户只能访问特定格式Endpoint的资源。
更有可能的情况是：我之前的代码中，虽然设置了endpoint_url，但boto3在某些操作（比如列出Bucket）时，可能会 fallback 到默认的虚拟主机式签名逻辑，而我手动构建的签名逻辑却使用了路径式，导致不一致。
或者，更简单的解释是：我最初的代码里，host变量我搞错了。
让我回到最开始的脚本。第一次失败时，我用的Endpoint是：
https://{BUCKET}.s3.{REGION}.qingcloud.com
而我计算签名时用的canonical_headers是：
'host:' + host + '\n'，其中host是f'{BUCKET}.s3.{REGION}.qingcloud.com'
这在逻辑上是对的。但是，青云的S3服务，在某些情况下，不接受虚拟主机式URL进行签名计算，除非你的Bucket名称符合特定的DNS规范（比如不包含大写字母，不包含连字符等）。
我的Bucket名字叫My-Test-Bucket，包含了大写字母和连字符！这在标准的AWS S3中是不允许的（Bucket名只能小写，不能包含连字符在某些旧规范下），但青云可能允许。然而，当Bucket名包含大写字母时，虚拟主机式的URL会产生大小写不一致的问题，从而导致签名计算中的Host Header和实际请求的Host Header不匹配，或者云服务商在内部解析时出现歧义。
这就是根本原因！
访问密钥配置错误，不仅仅指Key本身错了，更指的是Key对应的权限和Endpoint使用方式不匹配，以及Bucket命名规范与签名计算方式的冲突。
第五幕：给小朋友也能听懂的“签名”比喻
为了让你彻底理解，我用一个比喻来解释。
想象一下，你要去青云的“仓库”（对象存储）存东西。仓库的大门（Endpoint）有两个入口：
- 入口A（路径式）: 你得先说“我要去cn-bj2区的仓库”，然后说“我要存东西到My-Test-Bucket这个房间”，最后说“我要存hello.txt”。
- 入口B（虚拟主机式）: 你得说“我要去My-Test-Bucket这个房间”，然后说“我要在cn-bj2区的仓库存hello.txt”。
为了安全，仓库管理员（S3服务）会给你一把特殊的钥匙（AccessKey）和一个密码（SecretKey）。你用这把钥匙和密码，写一张“通行证”（签名），通行证上必须清楚地写着：“我要通过入口A/B，去具体的房间，存具体的东西”。
签名失效，就是因为你写的“通行证”上的信息，和实际你要走的路线、要去的地方不一致。
在我的案例里：
- 我的Bucket名
My-Test-Bucket里有大写字母和连字符。 - 当我尝试用“入口B”（虚拟主机式）时，URL变成
https://My-Test-Bucket.s3.cn-bj2.qingcloud.com。 - 青云的服务端在解析这个URL时，可能因为大小写不敏感或者某些内部转换，导致它认为我要去的“房间”名称和我在“通行证”上写的名称不完全匹配。
- 于是，管理员一看：“嘿，你通行证上写的是
My-Test-Bucket，但我查到的房间名可能是my-test-bucket（规范化后），这不匹配啊！拒绝进入！”
而当我改用“入口A”（路径式）时，URL是https://s3.cn-bj2.qingcloud.com/My-Test-Bucket/hello.txt。这时，Host Header是s3.cn-bj2.qingcloud.com，路径是/My-Test-Bucket/hello.txt。青云的服务端可以明确地、无歧义地解析出“房间名”就是My-Test-Bucket，因为它是通过路径来识别的，而不是通过子域名。这样就匹配了，签名验证通过。
终极解决方案与最佳实践
如果你也遇到了青云对象存储签名生成失败的问题，请按以下步骤排查：
1. 检查Bucket命名规范
- 强烈建议：使用小写字母、数字、连字符命名的Bucket，例如
my-test-bucket-2023。 - 避免：大写字母、下划线（某些情况下可能有问题）、过长的名称。
- 如果你的Bucket名不规范，必须使用路径式（Path-Style）Endpoint。
2. 统一使用路径式Endpoint（最稳妥）
在SDK配置中，强制使用路径式：
Python (boto3):
import boto3
from botocore.config import Config
config = Config(s3={'addressing_style': 'path'})
s3_client = boto3.client(
's3',
region_name='cn-bj2',
aws_access_key_id='YOUR_AK',
aws_secret_access_key='YOUR_SK',
endpoint_url='https://s3.cn-bj2.qingcloud.com',
config=config
)
Java (AWS SDK v2):
S3Client s3 = S3Client.builder()
.region(Region.CN_NORTH_1) // 根据你的实际区域
.endpointOverride(URI.create("https://s3.cn-bj2.qingcloud.com"))
.serviceConfiguration(S3Configuration.builder()
.pathStyleAccessEnabled(true)
.build())
.credentialsProvider(DefaultCredentialsProvider.create())
.build();
3. 仔细核对AccessKey
- 登录青云控制台，进入 IAM -> 用户 -> 你的用户 -> 安全设置 -> AccessKey。
- 确认AK和SK完全匹配，没有多余的空格、换行符。
- 复制时，建议使用“复制”按钮，而不是手动选中。
- 如果怀疑Key有问题，新建一对Key，并撤销旧的Key。
4. 检查网络时间和时区
虽然不太常见，但确保你的服务器时间与NTP服务器同步。
timedatectl status
ntpstat
5. 使用官方SDK，避免手动签名
除非你有特殊需求，否则尽量使用青云官方推荐的SDK，它们已经处理了大多数签名细节。手动签名时，务必对照官方文档的Canonical Request格式，一步步调试，打印中间变量。
写在最后
这三个小时的排查，让我深刻体会到，云服务的“兼容”二字背后，藏着多少细微的差异和坑。S3兼容，并不意味着100%的行为一致。青云的对象存储，在签名计算、Endpoint选择、Bucket命名规范上，都有一些自己的“小脾气”。
希望我的这段“血泪史”，能帮你节省宝贵的时间。如果还有问题，记得先看Bucket名，再换路径式Endpoint，最后怀疑AccessKey。
记住，细节决定成败，尤其是在云服务的海洋里。