Midway 集成阿里云 OSS:@midwayjs/oss 组件配置与多 Bucket 实战指南

原创2026-10-08 22:59:391,851 阅读
文章标签:后端微服务云原生

Midway 集成阿里云 OSS:@midwayjs/oss 组件配置与多 Bucket 实战指南

阿里云对象存储 OSS(Object Storage Service)是海量、安全、低成本、高可靠的云存储服务,其数据设计持久性不低于 99.999999999%,服务设计可用性不低于 99.99%,并通过与平台无关的 RESTful API 让任意应用在任何时间、任何地点存储和访问任意类型的数据。@midwayjs/oss 是 Midway 体系下对接 OSS 服务的官方 SDK 组件,它将 ali-oss 客户端封装为可注入的 IoC 服务,并额外提供集群客户端、STS 临时凭证、多 Bucket 工厂与链路追踪能力。读完本文,你将掌握在 Midway 项目中完成 OSS 组件安装、单 Bucket / 集群 / STS 三种配置、文件上传下载、多 Bucket 实例管理以及自定义客户端与追踪插桩的全部实战方法。

组件能力概览

@midwayjs/oss 组件的定位在官方文档中有明确的适用性说明:

能力 是否支持
可用于标准项目(Web 应用) ✅
可用于 Serverless(函数计算) ✅
可用于一体化(integration)项目 ✅
包含独立主框架 ❌
包含独立日志 ❌

也就是说,它不是一个独立框架,而是依附于 Midway 主框架的组件;组件本身不提供独立日志体系,日志与请求追踪能力由 Midway 主框架统一管理。从源码看,组件通过 configuration.ts 以 namespace: 'oss' 注册,并在 onReady 阶段异步加载 OSSServiceFactory,确保容器启动时客户端已就绪。

组件在 interface.ts 中同时导出了 ali-oss 的 OSS 命名空间,因此你可以在 TypeScript 中直接复用 ali-oss 的类型定义,例如 MWOSSOptions extends OSS.Options、MWOSSClusterOptions extends OSS.ClusterOptions 等,获得完整的类型提示。

前置准备:申请 OSS Bucket 与访问凭证

使用 OSS 组件前,需要先在阿里云控制台申请一个 OSS Bucket。Bucket 是 OSS 中存储文件的容器概念,所有对象(Object)都存放在某个 Bucket 下。

  • 前往阿里云 OSS 产品页开通对象存储服务,并按需创建 Bucket;
  • 在 RAM 访问控制中创建 AccessKey,获取 accessKeyId 与 accessKeySecret;
  • 记录 Bucket 所在区域的 Endpoint(如 oss-cn-hongkong.aliyuncs.com)或 Region(如 oss-cn-hongkong)。

组件在创建客户端时会强制校验上述信息,校验逻辑位于 manager.ts 的 checkBucketConfig:

function checkBucketConfig(config) {
  assert.ok(
    config.endpoint || config.region,
    "[midway:oss] Must set `endpoint` or `region` in oss's config"
  );
  assert.ok(
    config.accessKeySecret && config.accessKeyId,
    "[midway:oss] Must set `accessKeyId` and `accessKeySecret` in oss's config"
  );
}

因此 endpoint 与 region 至少配置其一,accessKeyId 与 accessKeySecret 必须同时提供,否则启动阶段会直接抛出对应错误。这一行为在测试用例 packages/oss/test/index.test.ts 中也有验证。

安装依赖

@midwayjs/oss 是 OSS 组件的核心功能包,在当前仓库中的版本为 4.x(见 packages/oss/package.json),运行时依赖 ali-oss 与 @types/ali-oss。在项目中执行:

$ npm i @midwayjs/oss@4 --save

或者直接在 package.json 中声明依赖:

{
  "dependencies": {
    "@midwayjs/oss": "^4.0.0"
    // ...
  }
}

引入组件

在 src/configuration.ts 中通过 imports 引入 oss 组件,并加载配置文件目录:

import { Configuration } from '@midwayjs/core';
import * as oss from '@midwayjs/oss';
import { join } from 'path';

@Configuration({
  imports: [
    // ...
    oss // import oss components
  ],
  importConfigs: [
    join(__dirname, 'config')
  ]
})
export class MainConfiguration {
}

配置 OSS

组件支持基于 ali-oss 的普通客户端、集群(Cluster)客户端与 STS 客户端三种形态,分别对应 MWOSSOptions、MWOSSClusterOptions、MWOSSSTSOptions 三种配置类型。创建客户端的完整分发逻辑见 manager.ts 的 createClient 方法,优先级为:自定义客户端类(customClientClass)→ 集群客户端(clusters / cluster)→ STS 客户端(sts: true)→ 普通客户端。

普通 Bucket 配置

// src/config/config.default.ts
export default {
  // ...
  oss: {
    // normal oss bucket
    client: {
      accessKeyId: 'your access key',
      accessKeySecret: 'your access secret',
      bucket: 'your bucket name',
      endpoint: 'oss-cn-hongkong.aliyuncs.com',
      timeout: '60s',
    },
  },
}

其中 timeout: '60s' 正是组件默认配置——configuration.ts 在注册组件时内置了 oss.default.timeout = '60s',即使你不显式声明,普通客户端也会继承该超时时间。

集群(Cluster)模式配置

集群模式需要配置多个节点,ali-oss 的 ClusterClient 会按调度策略在这些节点之间分发请求:

// src/config/config.default.ts
export default {
  // ...
  oss: {
    // need to config all bucket information under cluster
    client: {
      clusters: [{
        endpoint: 'host1',
        accessKeyId: 'id1',
        accessKeySecret: 'secret1',
      }, {
        endpoint: 'host2',
        accessKeyId: 'id2',
        accessKeySecret: 'secret2',
      }],
      schedule: 'masterSlave', // default is 'roundRobin'
      timeout: '60s',
    }
  },
}

schedule 用于指定集群调度策略,未配置时默认是 roundRobin(轮询),配置为 masterSlave 时走主从模式。值得注意的是,源码中 createClient 也兼容了 cluster 字段写法:当配置 cluster: <a href="https://link.gitcode.com/i/d1a7e791ad321877eebaa547b47e2018" target="_blank">...](数组形式)且未提供 clusters 时,会自动将其归一化为 clusters(见 [manager.ts)。测试夹具 packages/oss/test/fixtures/base-app-cluster/src/config.default.ts 使用的正是 cluster 数组写法,并通过流式上传验证了集群客户端可用。

STS 临时凭证配置

STS(Security Token Service)用于生成临时访问凭证,适合授权给第三方或用于安全性要求较高的场景。配置 sts: true 后,组件将创建 OSS.STS 客户端而非普通客户端:

// src/config/config.default.ts
export default {
  // ...
  oss: {
    // if config.sts == true, oss will create STS client
    client: {
      sts: true,
      accessKeyId: 'your access key',
      accessKeySecret: 'your access secret',
    },
  },
}

STS 客户端的类型定义要求 sts: true 必须显式声明(见 interface.ts),而 createClient 中正是通过 config.sts === true 这个分支来决定创建 OSS.STS 实例的。

使用组件:上传文件与 STS 取号

通过 OSSService 保存文件

组件把客户端封装为 OSSService,你可以在任意业务类中直接注入并调用 OSS 接口:

import { OSSService } from '@midwayjs/oss';
import { join } from 'path';

@Provide()
export class UserService {

  @Inject()
  ossService: OSSService;

  async saveFile() {
    const localFile = join(__dirname, 'test.log');
    const result = await this.ossService.put('/test/test.log', localFile);

    // => result.url
  }
}

OSSService 本身并不重复实现 OSS 的每个 API:它在 @Init 阶段从 OSSServiceFactory 获取默认实例,然后通过 delegateTargetPrototypeMethod(OSSService, <a href="https://link.gitcode.com/i/52eb5bd4a1b1e973bb5899f64339451b" target="_blank">OSS])(见 [manager.ts)把 ali-oss 原型链上的全部方法委托给内部实例,因此 put、get、delete、list、multipartUpload、signatureUrl 等 60 余个方法均可直接调用。测试 packages/oss/test/index.test.ts 逐一验证了这些代理方法确实被正确转发。若默认实例不存在(例如未配置 oss.client 或 oss.clients.default),init 时会抛出 oss default instance not found. 错误。

通过 OSSSTSService 获取临时凭证

配置了 STS 模式后,可以注入 OSSSTSService 调用 assumeRole 换取临时凭证:

import { OSSSTSService } from '@midwayjs/oss';
import { join } from 'path';

@Provide()
export class UserService {

  @Inject()
  stsService: OSSSTSService;

  async saveFile() {
    const roleArn = '******'; // This is arn of aliyun role
    const result = await this.stsService.assumeRole(roleArn);

    // result.credentials.AccessKeyId
    // result.credentials.AccessKeySecret
    // result.credentials.SecurityToken
  }
}

OSSSTSService.assumeRole 在 manager.ts 中封装了 roleArn、policy、expirationSeconds、session、options 等完整参数透传,返回结果中的 credentials 对象可直接用于初始化临时客户端(测试 packages/oss/test/index.test.ts 展示了用返回的 AccessKeyId / AccessKeySecret / SecurityToken 创建临时客户端并 list() 的完整流程)。ali-oss 客户端更丰富的 API 细节可参考 OSS 官方 SDK 文档。

使用多个 OSS Bucket

当应用需要访问多个 Bucket 时,改用 oss.clients 按名称注册多个客户端实例:

// src/config/config.default.ts
export default {
  // ...
  oss: {
    clients: {
      bucket1: {
        bucket: 'bucket1',
        // ...
      },
      bucket2: {
        bucket: 'bucket2',
        // ...
      },
    },
    // client、clients 与 createInstance 方法共享的公共配置
    default: {
      endpoint: '',
      accessKeyId: '',
      accessKeySecret: '',
    },
  },
  // other custom config
  bucket3: {
    bucket: 'bucket3',
    // ...
  },
}

随后通过 OSSServiceFactory 按名称获取不同实例:

import { OSSServiceFactory } from '@midwayjs/oss';
import { join } from 'path';

@Provide()
export class UserService {

  @Inject()
  ossServiceFactory: OSSServiceFactory;

  @Config('bucket3')
  bucket3Config;

  async saveFile() {
    // The default type is OSSService
    const bucket1 = this.ossServiceFactory.get('bucket1');
    const bucket2 = this.ossServiceFactory.get('bucket2');

    // If it is STS, you need to set a generic contact.
    // const bucket1 = this.ossServiceFactory.get<OSSSTSService>('bucket1');

    // config.bucket3 and config.oss.default will be merged
    const bucket3 = await this.ossServiceFactory.createInstance(this.bucket3Config, 'bucket3');
    // After passing the name, you can also get it from the factory.
    bucket3 = this.ossServiceFactory.get('bucket3');
  }
}

这里有几个值得注意的设计点:

  • get(name) 与默认实例:get() 不传参数时返回默认客户端(default 名称),OSSService 内部正是用 getDefaultClientName?.() || 'default' 来定位默认实例的(见 manager.ts)。
  • createInstance(config, name):可以将散落在应用其他配置项(如 config.bucket3)中的 Bucket 配置动态创建实例,创建时与 oss.default 公共配置合并,创建后同样可以按名称从工厂取出复用。
  • STS 泛型:当某 Bucket 是 STS 客户端时,通过 get<OSSSTSService>('bucket1') 指定泛型即可获得正确类型;测试 packages/oss/test/index.test.ts 验证了同一工厂中同时管理 STS 客户端与普通客户端的混合场景。

自定义客户端与链路追踪

自定义客户端类(customClientClass)

从 customClient.test.ts 可以看出,组件支持在配置中传入 customClientClass 来替换默认的 ali-oss 实现。createClient 会优先分支处理:

const { customClientClass, ...otherConfig } = config as any;
if (customClientClass) {
  const client = new customClientClass(otherConfig);
  this.bindTraceContext(client as any);
  return client;
}

只要自定义类实现 request(options) 方法即可,例如测试中的 CustomOSS。该能力适用于需要 Mock、接入私有存储实现或做协议扩展的场景,且自定义客户端同样会挂载链路追踪包装。

OSS 链路追踪插桩

组件内置了基于 Midway 追踪体系的 OSS 埋点能力,对应三个可选配置项:

// src/config/config.default.ts
export default {
  oss: {
    tracing: {
      enable: true,                  // 是否开启追踪,默认开启
      meta: (carrier, request, custom) => { /* 自定义 meta 解析 */ },
      injector: ({ request, custom }) => { /* 自定义 carrier 注入,需返回对象 */ },
    },
  },
}

对应源码中的三个 @Config 注入点:oss.tracing.enable、oss.tracing.meta、oss.tracing.injector(见 manager.ts)。bindTraceContext(manager.ts)会包装客户端的 request 方法:每次请求以 oss.<METHOD>(如 oss.put)为 span 名创建出口 Span,并附带 midway.protocol: 'oss' 与 midway.oss.method 等属性。injector 可以返回 carrier 对象用于在请求头注入追踪上下文,meta 则用于自定义附加元数据。测试 customClient.test.ts 验证了自定义客户端请求会触发 runWithExitSpan 调用。

验证与运行

组件测试位于 packages/oss/test,覆盖了普通上传、集群流式上传、STS 取号、多客户端混合、缺失配置报错、代理方法完整性、自定义客户端与追踪插桩等场景。其中需要真实 OSS 凭证的用例通过环境变量 ALI_SDK_OSS_ID、ALI_SDK_OSS_SECRET、ALI_SDK_OSS_REGION、ALI_SDK_OSS_BUCKET 注入(见 packages/oss/test/config.ts),在 CI 的 PR 环境(无凭证)下会自动跳过,避免误报。本地可按需运行:

$ cd packages/oss
$ npm test

在实际项目中,将配置填入 src/config/config.default.ts 并引入组件后,即可通过注入 OSSService、OSSSTSService 与 OSSServiceFactory 完成对象存储的读写、临时凭证下发与多 Bucket 管理,同时借助内置追踪能力把 OSS 调用纳入应用的分布式链路体系。

登录后查看全文
midway