Midway 集成阿里云 OSS:@midwayjs/oss 组件配置与多 Bucket 实战指南
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 调用纳入应用的分布式链路体系。