Zulip Server 使用 Google Cloud Storage 上传文件问题的解决方案

问题背景

Zulip 是一个开源的团队协作平台，在最新版本中集成了 tusd 服务用于处理大文件上传功能。近期有用户反馈在 Google 云环境中部署时，使用 Google Storage Bucket 作为存储后端时出现了 403 访问被拒绝的错误。

错误分析

当系统尝试通过 S3 API 向 Google Cloud Storage (GCS) 创建分段上传时，会收到以下错误：

SignatureDoesNotMatch: Access denied

这个错误表明 AWS SDK 生成的签名与 GCS 期望的签名格式不匹配。根本原因是 GCS 虽然提供了 S3 兼容接口，但在签名验证方面存在一些细微差异。

技术背景

Zulip 使用 tusd 作为文件上传服务，支持两种存储后端：

1. 本地文件系统
2. 云存储服务（通过 S3 API）

在 Google 云环境中，虽然 GCS 提供了 S3 兼容接口，但 AWS SDK 生成的签名在某些情况下无法被 GCS 正确验证。

解决方案

经过技术团队分析，推荐使用 GCS 原生后端替代 S3 兼容接口。具体实现方式如下：

1. 修改 Zulip 的 tusd 启动脚本，当检测到使用 GCS 时自动切换到 GCS 后端
2. 配置 GCS 服务账户密钥文件

实现的核心代码变更是在 runtusd.py 中添加对 GCS 的特殊处理：

if settings.S3_ENDPOINT_URL.startswith("https://storage.googleapis.com"):
    tusd_args.append(f"-gcs-bucket={settings.S3_AUTH_UPLOADS_BUCKET}")
    env_vars["GCS_SERVICE_ACCOUNT_FILE"] = "/etc/zulip/gcp_key.json"

实施步骤

1. 在服务器上创建 /etc/zulip/gcp_key.json 文件，包含有效的 GCS 服务账户凭证
2. 确保服务账户具有对目标存储桶的读写权限
3. 重启 Zulip 服务使配置生效

注意事项

1. 使用 GCS 原生后端需要 tusd 1.12.0 或更高版本
2. 服务账户密钥文件需要妥善保管，建议设置适当的文件权限
3. 此方案已在实际环境中验证可行，但可能因 tusd 版本不同而有所差异

替代方案

如果暂时无法使用 GCS 原生后端，可以考虑以下临时方案：

1. 回退到不使用 tusd 的传统上传方式（不支持大文件）
2. 使用其他兼容性更好的 S3 存储服务

结论

通过切换到 GCS 原生后端，可以彻底解决签名不匹配的问题，同时保持所有上传功能完整可用。这是目前最稳定可靠的解决方案，推荐所有在 Google 云环境中部署 Zulip 的用户采用。