Midway 3.x 集成阿里云 OSS:`@midwayjs/oss` 组件接入、集群与 STS 多场景实战
Midway 3.x 集成阿里云 OSS:@midwayjs/oss 组件接入、集群与 STS 多场景实战
导读:本文讲解 Midway 体系中面向阿里云对象存储(OSS)的官方 SDK 组件 @midwayjs/oss,覆盖从 Bucket 前置准备、依赖安装、组件引入到普通 Bucket / 集群(Cluster) / STS 临时凭证三种客户端配置,以及 OSSService、OSSSTSService、OSSServiceFactory 三类核心服务的实际用法。读完本文,你将能够在标准 Web 项目与 Serverless 场景下完成 OSS 上传、临时授权与多 Bucket 管理,并通过源码理解其底层客户端创建与链路追踪机制。
一、组件能力概览
OSS(Object Storage Service)是阿里云提供的海量、安全、低成本、高可靠的云存储服务,其数据设计持久性不低于 99.999999999%,服务设计可用性不低于 99.99%,并提供与平台无关的 RESTful API,让任意应用、任意时间、任意地点都可以存储和访问任意类型的数据。
@midwayjs/oss 正是 Midway 体系下对接 OSS 服务的 SDK 封装组件。它的整体能力矩阵如下:
| 描述 | 是否支持 |
|---|---|
| 可用于标准项目 | ✅ |
| 可用于 Serverless | ✅ |
| 可用于集成(integration) | ✅ |
| 包含独立主框架 | ❌ |
| 包含独立日志 | ❌ |
从能力矩阵可以看出,该组件不是一个独立的主框架,也不自带日志体系,而是作为能力模块挂载在 Midway 应用之上,通过依赖注入(DI)向业务代码暴露服务。
在仓库中,该组件的完整实现位于 packages/oss 目录,核心源码由 src/configuration.ts(组件配置入口)、src/manager.ts(服务工厂与服务实现)、src/interface.ts(类型定义)和 src/index.ts(导出)四部分组成。当前仓库内该包版本为 4.2.5,其运行依赖为 ali-oss(版本 6.23.0)与 @types/ali-oss,Node.js 运行环境要求不低于 20,详见 packages/oss/package.json。
二、前置准备:先申请 OSS Bucket
使用 OSS 组件之前,需要提前在阿里云控制台申请一个 OSS Bucket。Bucket 是 OSS 存储空间的概念,所有文件都存放在某个 Bucket 内。
需要准备的基础信息包括:
- Bucket 名称:存储空间的全局唯一名称,配置中通过
bucket字段指定; - AccessKey ID / AccessKey Secret:访问 OSS 的密钥对,配置中通过
accessKeyId/accessKeySecret字段指定; - Endpoint / Region:Bucket 所属地域的访问域名或地域标识,二者至少配置其一。
对应的申请与概念资料可在阿里云 OSS 产品页及其对象存储帮助文档中查阅(此处不再重复外部链接)。在正式编码前,建议先在控制台完成 Bucket 创建与密钥获取。
三、安装依赖
@midwayjs/oss 是 OSS 功能的主包,安装命令如下:
$ npm i @midwayjs/oss@3 --save
也可以在 package.json 中直接声明依赖并重新安装:
{
"dependencies": {
"@midwayjs/oss": "^3.0.0",
// ...
}
}
需要说明的是:本文档对应 3.0.0 版本文档;当前仓库 packages/oss/package.json 中该包的最新版本为 4.2.5,API 形态保持一致,安装 3.x 与 4.x 的使用方式相同。安装完成后,@midwayjs/oss 会自动拉取其底层依赖 ali-oss,组件内部正是基于 ali-oss 客户端进行封装。
四、引入组件
在 src/configuration.ts 中通过 imports 引入 oss 组件:
import { Configuration } from '@midwayjs/core';
import * as oss from '@midwayjs/oss';
import { join } from 'path'
@Configuration({
imports: [
// ...
oss // 引入 oss 组件
],
importConfigs: [
join(__dirname, 'config')
]
})
export class MainConfiguration {
}
从源码看,组件入口类 OSSConfiguration 声明了 namespace: 'oss',并注册了一个默认配置项 oss.default.timeout = '60s',随后在 onReady 生命周期中通过 container.getAsync(OSSServiceFactory) 提前实例化服务工厂,确保应用启动阶段就完成 OSS 客户端的初始化,详见 packages/oss/src/configuration.ts。
五、配置 OSS
OSS 组件使用前必须先配置,至少需要提供 bucket、accessKeyId、accessKeySecret 等必要信息。组件支持基于 ali-oss 的普通客户端和集群(cluster)客户端,同时也支持 STS 临时凭证模式。
5.1 普通 Bucket 配置
// src/config/config.default
export default {
// ...
oss: {
// 普通 oss bucket
client: {
accessKeyId: 'your access key',
accessKeySecret: 'your access secret',
bucket: 'your bucket name',
endpoint: 'oss-cn-hongkong.aliyuncs.com',
timeout: '60s',
},
},
}
其中 endpoint 是 Bucket 所在地域的访问域名,timeout 默认值为 60s(由组件默认配置提供,未显式声明时也生效)。
从源码角度看,客户端创建前会经过 checkBucketConfig 校验(见 packages/oss/src/manager.ts):
- 必须设置
endpoint或region,否则抛出错误[midway:oss] Must set 'endpoint' or 'region' in oss's config; - 必须同时设置
accessKeySecret与accessKeyId,否则抛出错误[midway:oss] Must set 'accessKeyId' and 'accessKeySecret' in oss's config。
对应地,测试用例 packages/oss/test/index.test.ts 中专门构造了缺少配置的 fixture(base-app-missing-config),断言应用启动时会抛出上述密钥缺失错误,保证误配置能被尽早发现。
5.2 集群(cluster)模式配置
当需要以集群模式访问多个 OSS 节点时,需要在 client 下配置多个集群端点信息,并可通过 schedule 指定调度策略(默认 roundRobin):
// src/config/config.default
export default {
// ...
oss: {
// 需要配置集群下所有 bucket 的信息
client: {
clusters: [{
endpoint: 'host1',
accessKeyId: 'id1',
accessKeySecret: 'secret1',
}, {
endpoint: 'host2',
accessKeyId: 'id2',
accessKeySecret: 'secret2',
}],
schedule: 'masterSlave', // 默认是 'roundRobin'
timeout: '60s',
}
},
}
源码层面对集群模式做了两处兼容处理(packages/oss/src/manager.ts 的 createClient 方法):
- 兼容旧写法:若配置使用
cluster键(数组形式)而非clusters,会自动转换赋值config.clusters = config['cluster']; - 对每个集群节点逐一执行
checkBucketConfig校验,全部通过后实例化OSS.ClusterClient。
类型层面,集群配置由 packages/oss/src/interface.ts 中的 MWOSSClusterOptions 描述,它要求 clusters 数组中的每一项都包含 endpoint 字符串字段,并允许携带 timeout。测试 fixture packages/oss/test/fixtures/base-app-cluster/src/config.default.ts 展示的正是使用 cluster 旧键名传入两个节点数组的写法。
5.3 STS 临时凭证配置
STS(Security Token Service)用于签发临时访问凭证,适合需要临时授权或最小权限控制的场景。配置中只需开启 sts: true:
// src/config/config.default
export default {
// ...
oss: {
// 如果 config.sts == true,oss 将创建 STS 客户端
client: {
sts: true
accessKeyId: 'your access key',
accessKeySecret: 'your access secret',
},
},
}
对应类型为 packages/oss/src/interface.ts 中的 MWOSSSTSOptions,它在 OSS.STSOptions 基础上强制要求 sts: boolean。在 createClient 中,当 config.sts === true 时组件会创建 OSS.STS 客户端;由于 STS 模式不需要绑定具体 Bucket,因此该分支不会触发 checkBucketConfig 的 Bucket 校验。测试 fixture packages/oss/test/fixtures/base-app-sts/src/config.default.ts 即采用 Object.assign({ sts: true }, ...) 的方式声明。
六、使用组件
配置完成后,可以直接注入 OSSService 并调用其接口,例如保存文件:
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
}
}
put 是 ali-oss 提供的上传接口,支持传入本地文件路径、Buffer 或可读流,返回结果中包含资源访问地址 result.url。测试用例中同样验证了 put 后 result.url 存在且响应状态为 200(见 packages/oss/test/index.test.ts)。
从源码看,OSSService 是一个单例服务(packages/oss/src/manager.ts),它在 @Init() 阶段从 OSSServiceFactory 中取出名为 default(即 getDefaultClientName())的客户端实例;若未找到则抛出 MidwayCommonError('oss default instance not found.')。由于 OSS 的 API 方法数量众多(put、get、delete、list、copy、multipartUpload、head、append 等),组件通过 delegateTargetPrototypeMethod(OSSService, [OSS]) 将 ali-oss 客户端的所有原型方法一次性代理到 OSSService 上,业务代码因此可以直接像调用普通对象一样调用全部 OSS 接口,测试文件中也列出了 abortMultipartUpload、completeMultipartUpload、createVod、getBucketCORS 等一整套代理方法清单。
6.1 STS 模式下的客户端
如果配置了 STS 模式,客户端应使用 OSSSTSService:
import { OSSSTSService } from '@midwayjs/oss';
import { join } from 'path';
@Provide()
export class UserService {
@Inject()
stsService: OSSSTSService;
async saveFile() {
const roleArn = '******'; // 阿里云角色的 arn
const result = await this.stsService.assumeRole(roleArn);
// result.credentials.AccessKeyId
// result.credentials.AccessKeySecret;
// result.credentials.SecurityToken;
}
}
assumeRole 用于扮演指定 RAM 角色以换取临时凭证,返回结果中的 credentials 对象包含 AccessKeyId、AccessKeySecret 与 SecurityToken 三个字段。源码中 OSSSTSService 与 OSSService 结构对称:同样以单例注入服务工厂、从 default 客户端取出 STS 实例,并将 assumeRole 透传给底层,且支持 policy、expirationSeconds、session 等可选参数(packages/oss/src/manager.ts)。
关于 OSS 客户端 API 的完整说明,可对照组件底层依赖 ali-oss(当前仓库锁定的版本为 6.23.0,见 packages/oss/package.json)的接口文档查阅。
6.2 内置链路追踪支持
除了基础调用,组件还内置了与 Midway 链路追踪(tracing)体系集成的能力。从源码可见,OSSServiceFactory 在创建每个客户端后都会调用 bindTraceContext(packages/oss/src/manager.ts),它会包装客户端底层的 request 方法,并以 oss.<方法名小写> 为名创建退出 Span(exit span),同时写入 midway.protocol: 'oss' 与 midway.oss.method 等属性。
相关开关均可通过配置控制:
oss.tracing.enable:是否开启追踪(默认开启,即this.traceEnabled !== false);oss.tracing.meta:元数据解析器(traceMetaResolver);oss.tracing.injector:自定义注入器,可将请求方法等信息写入链路载体(carrier)。
测试用例 packages/oss/test/trace.test.ts 通过 mock 的 runWithExitSpan 验证了 bindTraceContext 后 client.request 会触发退出 Span 的创建。
七、使用多个 OSS Bucket
部分应用需要同时访问多个 OSS Bucket,此时需要在 oss.clients 中按命名空间配置多个客户端:
// src/config/config.default
export default {
// ...
oss: {
clients: {
bucket1: {
bucket: 'bucket1',
// ...
},
bucket2: {
bucket: 'bucket2',
// ...
},
},
// client、clients、createInstance 方法共享的默认配置
default: {
endpoint: '',
accessKeyId: '',
accessKeySecret: '',
},
},
// 其他自定义配置
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() {
// 默认类型为 OSSService
const bucket1 = this.ossServiceFactory.get('bucket1');
const bucket2 = this.ossServiceFactory.get('bucket2');
// 如果是 STS,需要指定泛型
// const bucket1 = this.ossServiceFactory.get<OSSSTSService>('bucket1');
// config.bucket3 会与 config.oss.default 合并
const bucket3 = await this.ossServiceFactory.createInstance(this.bucket3Config, 'bucket3');
// 传入名称后,也可以从工厂中再次获取
bucket3 = this.ossServiceFactory.get('bucket3');
}
}
这里需要理清三个概念:
oss.clients:静态声明多个具名客户端,启动时由工厂统一初始化(init()中调用initClients(this.ossConfig, { concurrent: true }),即并发创建),之后通过factory.get('bucket1')等直接取出;oss.default:clients与createInstance共享的默认配置,用于填充各客户端缺失的公共字段(如公共的endpoint、密钥);createInstance(config, name):动态创建客户端,传入的配置会与oss.default合并,创建后也可凭name从工厂再次get出来,适合运行期动态注册 Bucket 的场景。
从源码看,OSSServiceFactory 是继承自 ServiceFactory 的单例工厂(packages/oss/src/manager.ts),其 createClient 按照「自定义客户端类 → 集群 → STS → 普通 OSS」的顺序分支创建实例,因此 get<OSSSTSService>('bucket1') 之所以可行,是因为工厂返回类型被定义为 XOR<XOR<OSS, OSS.STS>, OSS.ClusterClient>(见 packages/oss/src/interface.ts),即三种客户端形态取其一。测试 fixture packages/oss/test/fixtures/base-app-sts-clients/src/config.default.ts 正是「STS 客户端 + 普通客户端」混合多客户端配置的示例,其中 client1 开启 sts: true、client2 使用普通 Bucket 配置。
八、小结
本文围绕 @midwayjs/oss 组件,完整覆盖了从 Bucket 前置准备、依赖安装、组件引入,到普通 / 集群 / STS 三种客户端配置,以及 OSSService、OSSSTSService、OSSServiceFactory 的实际使用,并下钻到 packages/oss/src/manager.ts 的客户端创建校验、方法代理与链路追踪等实现细节。无论是标准 Web 项目、Serverless 应用还是多 Bucket 复杂场景,这套组件都能以统一的 DI 方式接入,且配置与使用方式在不同版本间保持一致(当前仓库版本为 4.2.5)。对实现细节感兴趣的读者,可继续在 packages/oss/test 目录下查阅各场景的 fixture 与测试用例。