serverpod_cos #

给 Serverpod 服务端使用的 Tencent COS 辅助包：从 passwords.yaml 读取 COS 配置，并生成预签名 URL。

你不需要先了解 tencent_cos_dart：本包已经把“读取配置 → 创建 signer”封装好了。

功能 #

• 从 passwords.yaml 读取 COS 配置
• 一行代码拿到 CosSigner：session.cosSigner()
• 提供通用的 Endpoint（可选）

安装 #

通过 pub 安装（推荐） #

dependencies:
  serverpod_cos: ^0.1.0

然后执行：

dart pub get

在中国网络环境下加速（可选） #

如果你访问 pub.dev 较慢，可配置 Flutter/Dart 官方提供的镜像（CFUG）：

• 参考文档：https://docs.flutter.cn/community/china

macOS / Linux（临时生效）：

export PUB_HOSTED_URL="https://pub.flutter-io.cn"
export FLUTTER_STORAGE_BASE_URL="https://storage.flutter-io.cn"

Windows PowerShell（临时生效）：

$env:PUB_HOSTED_URL="https://pub.flutter-io.cn"
$env:FLUTTER_STORAGE_BASE_URL="https://storage.flutter-io.cn"

配置 passwords.yaml #

将以下配置加入 config/passwords.yaml（建议放在 shared 或对应环境下）。

强烈建议：passwords.yaml 不要提交到 Git；请妥善保管。

shared:
  tencentCosSecretId: '<TENCENT_SECRET_ID>'
  tencentCosSecretKey: '<TENCENT_SECRET_KEY>'
  tencentCosBucket: '<COS_BUCKET_NAME>'
  tencentCosRegion: '<COS_REGION>'
  tencentCosCustomDomain: 'https://my-cdn.example.com' # 可选

tencentCosCustomDomain 支持 https://example.com 或 example.com。

这些参数去哪里找（腾讯云控制台） #

1) SecretId / SecretKey #

在“访问管理”的 API 密钥管理里创建/查看：

• 控制台入口：https://console.cloud.tencent.com/cam/capi

2) Bucket（存储桶名称） #

在 COS 控制台的 存储桶列表里可以看到（bucket 名称通常形如 my-bucket-125xxxxxxxx）：

• 控制台入口：https://console.cloud.tencent.com/cos5
• 参考文档（创建/概念）：https://cloud.tencent.com/document/product/436/13309

3) Region（地域） #

同样在存储桶列表/存储桶概览中查看（例如 ap-guangzhou）：

• 参考文档（地域与访问域名）：https://cloud.tencent.com/document/product/436/6224

4) customDomain（可选：自定义域名/加速域名） #

如果你为存储桶配置了自定义域名（CNAME / HTTPS 等），就可以填到 tencentCosCustomDomain：

• 参考文档（域名管理概述）：https://cloud.tencent.com/document/product/436/18424

与官方内建存储的关系（重要） #

本包生成的是 COS 预签名 URL + 自定义端点调用，不等同于 Serverpod 官方 session.storage 的内建对象存储接口。

如果你希望 兼容官方对象存储 API（createDirectFileUploadDescription 等）， 请使用 serverpod_cloud_storage_cos 包（推荐）。

dependencies:
  serverpod_cloud_storage_cos: ^0.1.0

使用（推荐方式） #

import 'package:serverpod/serverpod.dart';
import 'package:serverpod_cos/serverpod_cos.dart';

class MyEndpoint extends Endpoint {
  Future<String> createUploadUrl(Session session, String objectKey) async {
    final signer = session.cosSigner();
    return signer.generatePresignedUrl(
      'PUT',
      objectKey,
      expires: 3600,
    );
  }
}

高级：自定义 passwords.yaml 的 key 名 #

如果你的 passwords.yaml 里 key 名不是默认的这几个，可以传入 CosPasswordKeys：

import 'package:serverpod/serverpod.dart';
import 'package:serverpod_cos/serverpod_cos.dart';

class MyEndpoint extends Endpoint {
  Future<String> createUploadUrl(Session session, String objectKey) async {
    final signer = session.cosSigner(
      keys: const CosPasswordKeys(
        secretId: 'myCosSecretId',
        secretKey: 'myCosSecretKey',
        bucket: 'myCosBucket',
        region: 'myCosRegion',
        customDomain: 'myCosCustomDomain',
      ),
    );
    return signer.generatePresignedUrl('PUT', objectKey);
  }
}

可选：使用通用 Endpoint #

如果你想要一个“直接能被客户端调用”的通用端点，可以在你的服务端项目里做一个薄封装并注册：

import 'package:serverpod_cos/serverpod_cos.dart';

class CosEndpoint extends ServerpodCosEndpoint {}

维护与兼容性 #

• 维护说明：本包作为“高级/可选方案”，长期有效，故不做功能增添性维护。

• 可自行覆盖：如需扩展或修复，可直接在你的项目中复制并调整实现，或直接“extends ServerpodCosEndpoint”扩展方法。

• 版本策略：遵循语义化版本（SemVer）。

• 反馈渠道：欢迎提交 issue / PR（不保证及时响应）。