阿里云 OSS

欢迎来到阿里云 OSS 知识库！

☁️ 阿里云 OSS 简介

阿里云对象存储（Object Storage Service，简称 OSS）是阿里云提供的海量、安全、低成本、高可靠的云存储服务。特别适合国内业务，在中国大陆地区访问速度快，与阿里云其他服务集成良好。

🎯 OSS 特点

✅ 核心优势

国内访问快 - 在中国大陆多个地域部署
低成本 - 按量付费，价格实惠
高可靠 - 99.9999999999% 数据持久性
生态完善 - 与阿里云服务深度集成
图片处理 - 内置图片处理服务（OSS 处理）
CDN 加速 - 无缝对接阿里云 CDN
音视频处理 - 集成媒体处理服务

📊 OSS vs S3 vs MinIO

特性	阿里云 OSS	AWS S3	MinIO
国内访问	⭐⭐⭐⭐⭐	⭐⭐	⭐⭐⭐⭐⭐
价格（国内）	⭐⭐⭐⭐	⭐⭐	⭐⭐⭐⭐⭐
功能	⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐
图片处理	✅ 内置	❌ 需第三方	❌ 需第三方
文档	中文	英文为主	英文

🚀 快速开始

1. 开通 OSS 服务

注册阿里云账号
访问 OSS 控制台
开通 OSS 服务
创建 AccessKey

2. 创建 Bucket

bash

# 通过控制台创建
# 或使用 ossutil 命令行工具

# 安装 ossutil
wget https://gosspublic.alicdn.com/ossutil/1.7.15/ossutil64
chmod +x ossutil64

# 配置
./ossutil64 config

# 创建 Bucket
./ossutil64 mb oss://my-bucket --acl private

3. 安装 SDK

bash

# Node.js
npm install ali-oss

# Python
pip install oss2

# Java
# Maven 添加依赖
<dependency>
    <groupId>com.aliyun.oss</groupId>
    <artifactId>aliyun-sdk-oss</artifactId>
    <version>3.17.0</version>
</dependency>

# Go
go get github.com/aliyun/aliyun-oss-go-sdk/oss

💻 SDK 使用

Node.js

javascript

const OSS = require('ali-oss');

// 创建客户端
const client = new OSS({
  region: 'oss-cn-hangzhou',  // 地域
  accessKeyId: 'your-access-key-id',
  accessKeySecret: 'your-access-key-secret',
  bucket: 'your-bucket-name'
});

// 上传文件
const uploadFile = async (objectName, filePath) => {
  try {
    const result = await client.put(objectName, filePath);
    console.log('File uploaded:', result.url);
    return result;
  } catch (err) {
    console.error(err);
  }
};

// 上传 Buffer
const uploadBuffer = async (objectName, buffer) => {
  try {
    const result = await client.put(objectName, buffer);
    console.log('Buffer uploaded:', result.url);
    return result;
  } catch (err) {
    console.error(err);
  }
};

// 上传 Stream
const uploadStream = async (objectName, stream) => {
  try {
    const result = await client.putStream(objectName, stream);
    console.log('Stream uploaded:', result.url);
    return result;
  } catch (err) {
    console.error(err);
  }
};

// 分片上传大文件
const multipartUpload = async (objectName, filePath) => {
  try {
    const result = await client.multipartUpload(objectName, filePath, {
      parallel: 4,  // 并发上传数
      partSize: 1024 * 1024  // 分片大小 1MB
    });
    console.log('Multipart upload completed:', result.url);
    return result;
  } catch (err) {
    console.error(err);
  }
};

// 下载文件
const downloadFile = async (objectName, localPath) => {
  try {
    const result = await client.get(objectName, localPath);
    console.log('File downloaded to:', localPath);
    return result;
  } catch (err) {
    console.error(err);
  }
};

// 获取文件 Stream
const getStream = async (objectName) => {
  try {
    const result = await client.getStream(objectName);
    return result.stream;
  } catch (err) {
    console.error(err);
  }
};

// 列出文件
const listFiles = async (prefix = '', maxKeys = 100) => {
  try {
    const result = await client.list({
      prefix: prefix,
      'max-keys': maxKeys
    });
    return result.objects;
  } catch (err) {
    console.error(err);
  }
};

// 删除文件
const deleteFile = async (objectName) => {
  try {
    await client.delete(objectName);
    console.log('File deleted:', objectName);
  } catch (err) {
    console.error(err);
  }
};

// 批量删除
const deleteMultiple = async (objectNames) => {
  try {
    const result = await client.deleteMulti(objectNames);
    console.log('Deleted:', result.deleted.length);
    return result;
  } catch (err) {
    console.error(err);
  }
};

// 生成签名 URL
const getSignedUrl = async (objectName, expires = 3600) => {
  try {
    const url = client.signatureUrl(objectName, {
      expires: expires  // 秒
    });
    return url;
  } catch (err) {
    console.error(err);
  }
};

// 上传签名 URL
const getUploadSignedUrl = (objectName, expires = 3600) => {
  const url = client.signatureUrl(objectName, {
    method: 'PUT',
    expires: expires,
    'Content-Type': 'application/octet-stream'
  });
  return url;
};

Python

python

import oss2

# 认证
auth = oss2.Auth('your-access-key-id', 'your-access-key-secret')

# 创建 Bucket 对象
bucket = oss2.Bucket(auth, 'http://oss-cn-hangzhou.aliyuncs.com', 'your-bucket-name')

# 上传文件
def upload_file(object_name, file_path):
    result = bucket.put_object_from_file(object_name, file_path)
    print(f'HTTP Status: {result.status}')
    return result

# 上传字符串
def upload_string(object_name, content):
    result = bucket.put_object(object_name, content)
    return result

# 分片上传
def multipart_upload(object_name, file_path):
    result = oss2.resumable_upload(bucket, object_name, file_path,
                                    multipart_threshold=100*1024)  # 100KB
    return result

# 下载文件
def download_file(object_name, local_path):
    bucket.get_object_to_file(object_name, local_path)
    print(f'File downloaded to {local_path}')

# 获取对象
def get_object(object_name):
    result = bucket.get_object(object_name)
    content = result.read()
    return content

# 列出文件
def list_files(prefix=''):
    for obj in oss2.ObjectIterator(bucket, prefix=prefix):
        print(f'{obj.key}, {obj.size}, {obj.last_modified}')

# 删除文件
def delete_file(object_name):
    bucket.delete_object(object_name)
    print(f'{object_name} deleted')

# 批量删除
def delete_multiple(object_names):
    result = bucket.batch_delete_objects(object_names)
    print(f'Deleted: {len(result.deleted_keys)}')

# 生成签名 URL
def generate_signed_url(object_name, expires=3600):
    url = bucket.sign_url('GET', object_name, expires)
    return url

🖼️ 图片处理

OSS 内置图片处理服务，无需额外部署。

图片缩放

javascript

// 方式一：通过 URL 参数
const imageUrl = 'https://your-bucket.oss-cn-hangzhou.aliyuncs.com/photo.jpg';
const resizedUrl = `${imageUrl}?x-oss-process=image/resize,w_200,h_200`;

// 方式二：通过 SDK
const processImage = async (objectName) => {
  const result = await client.get(objectName, {
    process: 'image/resize,w_200,h_200'
  });
  return result;
};

// 常用参数
// resize,w_200               - 宽度200
// resize,h_200               - 高度200
// resize,w_200,h_200         - 宽高200
// resize,m_fill,w_200,h_200  - 填充模式
// resize,m_lfit,w_200,h_200  - 缩略模式

图片裁剪

javascript

// 裁剪
const cropUrl = `${imageUrl}?x-oss-process=image/crop,x_10,y_10,w_100,h_100`;

// 圆角
const roundUrl = `${imageUrl}?x-oss-process=image/rounded-corners,r_50`;

// 圆形
const circleUrl = `${imageUrl}?x-oss-process=image/circle,r_100`;

图片水印

javascript

// 文字水印
const textWatermark = `${imageUrl}?x-oss-process=image/watermark,text_5rC05Y2w5paH5a2X,size_40,color_FF0000`;

// 图片水印
const imageWatermark = `${imageUrl}?x-oss-process=image/watermark,image_d2F0ZXJtYXJrLnBuZw,g_se,x_10,y_10`;

格式转换

javascript

// 转换格式
const webpUrl = `${imageUrl}?x-oss-process=image/format,webp`;

// 质量调整
const qualityUrl = `${imageUrl}?x-oss-process=image/quality,q_80`;

// 组合处理
const combinedUrl = `${imageUrl}?x-oss-process=image/resize,w_200/quality,q_80/format,webp`;

获取图片信息

javascript

const getImageInfo = async (objectName) => {
  const result = await client.get(objectName, {
    process: 'image/info'
  });
  const info = JSON.parse(result.content.toString());
  console.log('Image Info:', info);
  // { FileSize: {value: "100"}, Format: {value: "jpg"}, ImageHeight: {...}, ImageWidth: {...} }
};

🔐 访问控制

1. Bucket ACL

javascript

// 设置 Bucket 为公共读
const setBucketPublicRead = async () => {
  await client.putBucketACL('your-bucket', 'public-read');
};

// 设置 Bucket 为私有
const setBucketPrivate = async () => {
  await client.putBucketACL('your-bucket', 'private');
};

2. 对象 ACL

javascript

// 上传时设置为公共读
const uploadPublicFile = async (objectName, filePath) => {
  await client.put(objectName, filePath, {
    headers: {
      'x-oss-object-acl': 'public-read'
    }
  });
};

// 修改已有对象的 ACL
const setObjectACL = async (objectName) => {
  await client.putACL(objectName, 'public-read');
};

3. Bucket Policy

javascript

const setBucketPolicy = async () => {
  const policy = {
    Statement: [
      {
        Effect: 'Allow',
        Principal: ['*'],
        Action: ['oss:GetObject'],
        Resource: ['acs:oss:*:*:your-bucket/*']
      }
    ]
  };
  
  await client.putBucketPolicy('your-bucket', JSON.stringify(policy));
};

4. 防盗链

javascript

// 通过控制台设置 Referer 白名单
// 或使用 SDK
const setReferer = async () => {
  await client.putBucketReferer('your-bucket', true, [
    'https://yourdomain.com',
    'https://*.yourdomain.com'
  ]);
};

🚀 前端直传

服务端生成签名

javascript

// Express 示例
app.post('/api/oss/signature', (req, res) => {
  const { filename, contentType } = req.body;
  
  const policy = {
    expiration: new Date(Date.now() + 3600 * 1000).toISOString(),
    conditions: [
      ['content-length-range', 0, 10485760], // 最大10MB
      ['eq', '$key', `uploads/${Date.now()}-${filename}`]
    ]
  };
  
  const policyBase64 = Buffer.from(JSON.stringify(policy)).toString('base64');
  const signature = crypto
    .createHmac('sha1', accessKeySecret)
    .update(policyBase64)
    .digest('base64');
  
  res.json({
    accessKeyId: accessKeyId,
    policy: policyBase64,
    signature: signature,
    host: `https://your-bucket.oss-cn-hangzhou.aliyuncs.com`,
    key: `uploads/${Date.now()}-${filename}`
  });
});

前端上传

javascript

async function uploadFile(file) {
  // 1. 获取签名
  const response = await fetch('/api/oss/signature', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      filename: file.name,
      contentType: file.type
    })
  });
  
  const { accessKeyId, policy, signature, host, key } = await response.json();
  
  // 2. 构造表单
  const formData = new FormData();
  formData.append('key', key);
  formData.append('OSSAccessKeyId', accessKeyId);
  formData.append('policy', policy);
  formData.append('signature', signature);
  formData.append('file', file);
  
  // 3. 上传到 OSS
  await fetch(host, {
    method: 'POST',
    body: formData
  });
  
  console.log('File uploaded:', `${host}/${key}`);
}

💰 成本优化

1. 存储类型

javascript

// 上传时指定存储类型
await client.put('archive.zip', './archive.zip', {
  headers: {
    'x-oss-storage-class': 'Archive'  // 归档存储
  }
});

// 存储类型:
// Standard - 标准存储（默认）
// IA - 低频访问
// Archive - 归档存储
// ColdArchive - 冷归档存储

2. 生命周期

javascript

const setLifecycle = async () => {
  const lifecycle = [
    {
      id: 'rule1',
      status: 'Enabled',
      prefix: 'logs/',
      transitions: [
        {
          days: 30,
          storageClass: 'IA'
        },
        {
          days: 180,
          storageClass: 'Archive'
        }
      ],
      expiration: {
        days: 365
      }
    }
  ];
  
  await client.putBucketLifecycle('your-bucket', lifecycle);
};

💡 最佳实践

1. CDN 加速

javascript

// 绑定自定义域名并开启 CDN
// 1. 在 OSS 控制台绑定域名
// 2. 在 CDN 控制台添加加速域名
// 3. 使用 CDN 域名访问

const cdnUrl = 'https://cdn.yourdomain.com/photo.jpg';

2. 跨域配置

javascript

const setCORS = async () => {
  const corsRules = [
    {
      allowedOrigin: ['*'],
      allowedMethod: ['GET', 'POST', 'PUT', 'DELETE'],
      allowedHeader: ['*'],
      exposeHeader: ['ETag'],
      maxAgeSeconds: 3600
    }
  ];
  
  await client.putBucketCORS('your-bucket', corsRules);
};

3. 监控与日志

javascript

// 开启日志记录
const setLogging = async () => {
  await client.putBucketLogging('your-bucket', 'logs/');
};

📖 学习资源

官方资源

工具推荐

ossutil - 命令行工具
ossbrowser - 图形化工具
OSS 控制台 - Web 管理界面

阿里云 OSS ​

☁️ 阿里云 OSS 简介 ​

🎯 OSS 特点 ​

✅ 核心优势 ​

📊 OSS vs S3 vs MinIO ​

🚀 快速开始 ​

1. 开通 OSS 服务 ​

2. 创建 Bucket ​

3. 安装 SDK ​

💻 SDK 使用 ​

Node.js ​

Python ​

🖼️ 图片处理 ​

图片缩放 ​

图片裁剪 ​

图片水印 ​

格式转换 ​

获取图片信息 ​

🔐 访问控制 ​

1. Bucket ACL ​

2. 对象 ACL ​

3. Bucket Policy ​

4. 防盗链 ​

🚀 前端直传 ​

服务端生成签名 ​

前端上传 ​

💰 成本优化 ​

1. 存储类型 ​

2. 生命周期 ​

💡 最佳实践 ​

1. CDN 加速 ​

2. 跨域配置 ​

3. 监控与日志 ​

📖 学习资源 ​

官方资源 ​

工具推荐 ​

阿里云 OSS

☁️ 阿里云 OSS 简介

🎯 OSS 特点

✅ 核心优势

📊 OSS vs S3 vs MinIO

🚀 快速开始

1. 开通 OSS 服务

2. 创建 Bucket

3. 安装 SDK

💻 SDK 使用

Node.js

Python

🖼️ 图片处理

图片缩放

图片裁剪

图片水印

格式转换

获取图片信息

🔐 访问控制

1. Bucket ACL

2. 对象 ACL

3. Bucket Policy

4. 防盗链

🚀 前端直传

服务端生成签名

前端上传

💰 成本优化

1. 存储类型

2. 生命周期

💡 最佳实践

1. CDN 加速

2. 跨域配置

3. 监控与日志

📖 学习资源

官方资源

工具推荐