版本控制介绍 - 对象存储 OSS

版本控制是针对存储空间（Bucket）级别的数据保护功能。开启版本控制后，针对数据的覆盖和删除操作将会以历史版本的形式保存下来。您在错误覆盖或者删除对象（Object）后，能够将Bucket中存储的Object恢复至任意时刻的历史版本。

使用场景

建议您在以下场景中使用版本控制，为您的数据安全提供更好的保障。

数据误删除
当前OSS不提供回收站功能。您删除OSS数据后想要找回时，可使用版本控制功能，恢复已删除的数据。
文件被覆盖
对于网盘、在线协作类产品，文件会被频繁修改，针对文件的编辑会产生大量的临时版本。您可以使用版本控制功能找回某个时间点的版本。

注意事项

费用说明
版本控制功能本身不收取任何费用，但对当前版本和所有历史版本的文件都会收取存储费用。为避免不必要的存储费用，请及时删除不需要的历史版本文件；此外，若您对历史版本文件进行下载或恢复等操作，还会产生相应的请求费用、流量费用等。计费详情，请参见计量项与计费项。
权限说明
只有Bucket的拥有者及授予了PutBucketVersioning权限的RAM用户才能配置版本控制。
功能互斥
- 同一Bucket中，版本控制与合规保留策略无法同时配置。
- 如果Bucket已开启版本控制，上传文件时附加的覆盖同名文件请求头x-oss-forbid-overwrite将不生效。更多信息，请参见请求头。
版本控制与OSS-HDFS服务
同一个Bucket中，不建议同时开通OSS-HDFS服务并设置保留策略。
如果Bucket开通了OSS-HDFS服务并设置了保留策略，会导致通过OSS-HDFS提供的方式删除.dlsdata/目录下的数据时提示删除成功，但在保留策略有效期内OSS仍将保留该目录下被删除的数据，且在保留策略失效后也无法识别并删除.dlsdata/目录下相关的数据。

版本控制状态

Bucket包含三种版本控制状态，分别为未开启、开启或者暂停。

默认情况下，Bucket版本控制状态为“未开启”。一旦Bucket处于“开启”版本状态，将无法返回至“未开启”状态。但是，您可以暂停Bucket的版本控制状态。
当Bucket版本控制处于“开启”状态时，OSS将为新上传的Object生成全局唯一的随机字符串版本ID。有关启用版本控制状态下Object的相关操作详情，请参见开启版本控制下Object的操作。
当Bucket版本控制处于“暂停”状态时，OSS将为新上传的Object生成特殊字符串为“null”的版本ID。有关暂停版本控制状态下Object的相关操作详情，请参见暂停版本控制下Object的操作。

说明当Bucket版本控制处于“开启”状态时，由于Object的每个版本都被保存下来，每个版本都会占用存储空间，OSS会对Object的所有版本收取存储费用。建议结合您的使用场景通过生命周期规则，将当前版本或历史版本Object转换为低频或归档存储类型或删除不再需要的历史版本，以降低您的存储费用，详情请参见使用生命周期管理文件版本。

数据保护

以下表格详细阐述了不同版本控制状态下，OSS对覆盖和删除Object的处理逻辑，帮助您了解版本控制状态下的数据保护机制。


版本控制状态	覆盖Object	删除Object
未开启	已有Object被直接覆盖，且无法恢复，只能获取最新版本Object。	直接删除，无法再获取此Object。
开启	为此Object添加新的版本ID，历史版本不受影响。	为此Object添加删除标记（Delete Marker），删除标记将携带一个全局唯一的版本ID，历史版本不受影响。
暂停	为此Object产生版本ID为“null”的新版本。历史版本里若已存在版本号为“null”的Object或删除标记，则将会被新的“null”版本Object覆盖，其他非“null”版本的Object或删除标记不受影响。	为此Object产生版本ID为“null”的删除标记。历史版本里若已存在版本号为“null”的Object或删除标记，则将会被新的删除标记覆盖，其他非“null”版本的Object或删除标记不受影响。

以下以图示的方法说明在Bucket版本控制状态处于“开启”和“暂停”时，上传同名Object或删除Object时OSS的处理行为。图示中的版本号均以简短版本号代替。

开启版本控制下的Object覆盖操作
在开启版本控制的Bucket中连续执行上传Object操作，Object虽然被多次覆盖，但每次覆盖操作均会产生一个独立的版本ID。
开启版本控制下的Object删除操作
在开启版本控制下的Bucket中删除Object时，历史版本Object不会被真正删除，而是产生一个删除标记来标识Object的当前版本是删除状态。如果再重复上传同名Object，将产生新的版本ID。
暂停版本控制下的Object覆盖操作
在暂停版本控制状态Bucket中上传Object时，历史版本数据继续保留，新上传的Object版本号为“null”。如果再重复上传同名Object，将产生新的“null”版本，并自动把前一次的“null”版本覆盖。
暂停版本控制下的Object删除操作
在暂停版本控制下的Bucket中删除Object时，历史版本Object不会被真正删除，而是产生一个删除标记来标识Object的当前版本是删除状态。

从上述信息得知，当您的Bucket处于版本控制状态时，针对数据的覆盖和删除操作将会以历史版本的形式保存下来。您在错误覆盖或者删除Object后，能够将Bucket中存储的Object恢复至任意时刻的历史版本。

开启版本控制

使用OSS控制台

开启版本控制后，OSS会为Bucket中所有Object的每个版本指定唯一的versionId。

新建Bucket时开启版本控制。
1. 登录OSS管理控制台。
2. 单击Bucket列表，然后单击创建Bucket。
3. 在创建Bucket页面配置各项参数。
  其中，版本控制区域选择开通。其他参数的配置详情，请参见创建存储空间。
4. 单击确定。
对已创建的Bucket开启版本控制。
1. 单击Bucket列表，然后单击目标Bucket名称。
2. 在左侧导航栏，选择数据安全 > 版本控制。
3. 在版本控制页面，单击开启。
4. 在弹出的对话框，单击确定。

开启版本控制后，您可以在文件管理页面查看所有版本的文件。如果仅需查看文件的当前版本，请将历史版本状态设置为隐藏。隐藏历史版本并不能提升列举文件的性能，如果列举文件时页面响应过慢，请参见响应速度下降排查并解决。

使用阿里云SDK

以下仅列举常见SDK的开启版本控制的代码示例。关于其他SDK的开启版本控制的代码示例，请参见SDK简介。

Java

// Endpoint以杭州为例，其它Region请按实际情况填写。
String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
// 阿里云主账号AccessKey拥有所有API的访问权限，风险很高。强烈建议您创建并使用RAM用户进行API访问或日常运维，请登录RAM控制台创建RAM用户。
String accessKeyId = "<yourAccessKeyId>";
String accessKeySecret = "<yourAccessKeySecret>";

// 创建OSSClient实例。
OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);

// 设置存储空间版本控制状态为Enabled。
BucketVersioningConfiguration configuration = new BucketVersioningConfiguration();
configuration.setStatus(BucketVersioningConfiguration.ENABLED);
SetBucketVersioningRequest request = new SetBucketVersioningRequest(bucketName, configuration);
ossClient.setBucketVersioning(request);

// 关闭OSSClient。
ossClient.shutdown();

PHP

<?php
if (is_file(__DIR__ . '/../autoload.php')) {
    require_once __DIR__ . '/../autoload.php';
}
if (is_file(__DIR__ . '/../vendor/autoload.php')) {
    require_once __DIR__ . '/../vendor/autoload.php';
}

use OSS\OssClient;
use OSS\Core\OssException;

// 阿里云主账号AccessKey拥有所有API的访问权限，风险很高。强烈建议您创建并使用RAM账号进行API访问或日常运维，请登录RAM控制台创建RAM账号。
$accessKeyId = "<yourAccessKeyId>";
$accessKeySecret = "<yourAccessKeySecret>";
// Endpoint以杭州为例，其它Region请按实际情况填写。
$endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
$bucket= "<yourBucketName>";

$ossClient = new OssClient($accessKeyId, $accessKeySecret, $endpoint);

try {
    // 设置存储空间版本控制为开启版本控制（Enabled）。
    $ossClient->putBucketVersioning($bucket, "Enabled");
} catch (OssException $e) {
    printf(__FUNCTION__ . ": FAILED\n");
    printf($e->getMessage() . "\n");
    return;
}

print(__FUNCTION__ . ": OK" . "\n");

Node.js

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

const client = new OSS({
  bucket: '<Your BucketName>',
  // region以杭州为例（oss-cn-hangzhou），其他region按实际情况填写。
  region: '<Your Region>',
  // 阿里云账号AccessKey拥有所有API的访问权限，风险很高。强烈建议您创建并使用RAM用户进行API访问或日常运维，请登录RAM控制台创建RAM用户。
  accessKeyId: '<Your AccessKeyId>',
  accessKeySecret: '<Your AccessKeySecret>'
});

async function putBucketVersioning() {
  // 设置存储空间版本控制状态为Enabled。
  const status = 'Enabled';
  const result = await client.putBucketVersioning('<Bucket Name>', status);
  console.log(result);
}
putBucketVersioning();

Python

# -*- coding: utf-8 -*-
import oss2
from oss2.models import BucketVersioningConfig

# 阿里云主账号AccessKey拥有所有API的访问权限，风险很高。强烈建议您创建并使用RAM用户进行API访问或日常运维，请登录RAM控制台创建RAM用户。
auth = oss2.Auth('<yourAccessKeyId>', '<yourAccessKeySecret>')
# Endpoint以杭州为例，其它Region请按实际情况填写。
bucket = oss2.Bucket(auth, 'http://oss-cn-hangzhou.aliyuncs.com', '<yourBucketName>')

# 创建bucket版本控制配置。
config = BucketVersioningConfig()
# 状态配置为Enabled。
config.status = oss2.BUCKET_VERSIONING_ENABLE

# 设置bucket版本控制状态。
result = bucket.put_bucket_versioning(config)
# 查看http返回码。
print('http response code:', result.status)

using Aliyun.OSS;
// yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1（杭州）为例，Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
var endpoint = "yourEndpoint";
// 阿里云账号AccessKey拥有所有API的访问权限，风险很高。强烈建议您创建并使用RAM用户进行API访问或日常运维，请登录RAM控制台创建RAM用户。
var accessKeyId = "yourAccessKeyId";
var accessKeySecret = "yourAccessKeySecret";
// 填写Bucket名称，例如examplebucket。
var bucketName = "examplebucket";
// 初始化OSSClient。
var client = new OssClient(endpoint, accessKeyId, accessKeySecret);
try
{
    // 设置存储空间版本控制状态为Enabled。
    client.SetBucketVersioning(new SetBucketVersioningRequest(bucketName, VersioningStatus.Enabled));
    Console.WriteLine("Create bucket Version succeeded");
}
catch (Exception ex)
{
    Console.WriteLine("Create bucket Version failed. {0}", ex.Message);
}

package main

import (
  "fmt"
  "os"

  "github.com/aliyun/aliyun-oss-go-sdk/oss"
)

func main() {
  // 创建OSSClient实例。
  client, err := oss.New("<yourEndpoint>", "<yourAccessKeyId>", "<yourAccessKeySecret>")
  if err != nil {
    fmt.Println("Error:", err)
    os.Exit(-1)
  }

  // 创建一个存储空间。
  err = client.CreateBucket("<yourBucketName>")
  if err != nil {
    fmt.Println("Error:", err)
    os.Exit(-1)
  }
  // 设置存储空间版本控制状态为Enabled。
  config := oss.VersioningConfig{Status: "Enabled"}
  err = client.SetBucketVersioning("<yourBucketName>", config)
  if err != nil {
    fmt.Println("Error:", err)
    os.Exit(-1)
  }
}

C++

#include <alibabacloud/oss/OssClient.h>
using namespace AlibabaCloud::OSS;

int main(void)
{
    /*初始化OSS账号信息*/
    std::string AccessKeyId = "yourAccessKeyId";
    std::string AccessKeySecret = "yourAccessKeySecret";
    std::string Endpoint = "yourEndpoint";
    std::string BucketName = "yourBucketName";

    /*初始化网络等资源*/
    InitializeSdk();

    ClientConfiguration conf;
    OssClient client(Endpoint, AccessKeyId, AccessKeySecret, conf);

    /*创建bucket版本配置，状态设置为Enabled*/
    SetBucketVersioningRequest setrequest(BucketName, VersioningStatus::Enabled);
    auto outcome = client.SetBucketVersioning(setrequest);

    if (!outcome.isSuccess()) {
        /* 异常处理 */
        std::cout << "SetBucketVersioning fail" <<
        ",code:" << outcome.error().Code() <<
        ",message:" << outcome.error().Message() <<
        ",requestId:" << outcome.error().RequestId() << std::endl;
        ShutdownSdk();
        return -1;
    }

    /*释放网络等资源*/
    ShutdownSdk();
    return 0;
}

使用命令行工具ossutil

关于使用ossutil开启版本控制的具体步骤，请参见设置版本控制状态。

使用REST API

如果您的程序自定义要求较高，您可以直接发起REST API请求。直接发起REST API请求需要手动编写代码计算签名。更多信息，请参见PutBucketVersioning。

暂停版本控制

使用OSS控制台

开启版本控制后，您还可以随时暂停版本控制以停止在Bucket中继续累积同一Object的新版本。暂停版本控制后，OSS将为新生成的Object添加versionId为null的版本，已有的历史版本Object将继续保留。

暂停Bucket版本控制的操作步骤如下：

单击Bucket列表，然后单击目标Bucket名称。
在左侧导航栏，选择数据安全 > 版本控制。
在版本控制页面，单击暂停。
在弹出的对话框，单击确定。

使用阿里云SDK

以下仅列举常见SDK的暂停版本控制的代码示例。关于其他SDK的暂停版本控制的代码示例，请参见SDK简介。

Java

// Endpoint以杭州为例，其它Region请按实际情况填写。
String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
// 阿里云主账号AccessKey拥有所有API的访问权限，风险很高。强烈建议您创建并使用RAM用户进行API访问或日常运维，请登录RAM控制台创建RAM用户。
String accessKeyId = "<yourAccessKeyId>";
String accessKeySecret = "<yourAccessKeySecret>";

// 创建OSSClient实例。
OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);

// 设置存储空间版本控制状态为Suspended。
BucketVersioningConfiguration configuration = new BucketVersioningConfiguration();
configuration.setStatus(BucketVersioningConfiguration.SUSPENDED);
SetBucketVersioningRequest request = new SetBucketVersioningRequest(bucketName, configuration);
ossClient.setBucketVersioning(request);

// 关闭OSSClient。
ossClient.shutdown();

PHP

<?php
if (is_file(__DIR__ . '/../autoload.php')) {
    require_once __DIR__ . '/../autoload.php';
}
if (is_file(__DIR__ . '/../vendor/autoload.php')) {
    require_once __DIR__ . '/../vendor/autoload.php';
}

use OSS\OssClient;
use OSS\Core\OssException;

// 阿里云主账号AccessKey拥有所有API的访问权限，风险很高。强烈建议您创建并使用RAM账号进行API访问或日常运维，请登录RAM控制台创建RAM账号。
$accessKeyId = "<yourAccessKeyId>";
$accessKeySecret = "<yourAccessKeySecret>";
// Endpoint以杭州为例，其它Region请按实际情况填写。
$endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
$bucket= "<yourBucketName>";

$ossClient = new OssClient($accessKeyId, $accessKeySecret, $endpoint);

try {
    // 设置存储空间版本控制为暂停版本控制（Suspended）。
    $ossClient->putBucketVersioning($bucket, "Suspended");
} catch (OssException $e) {
    printf(__FUNCTION__ . ": FAILED\n");
    printf($e->getMessage() . "\n");
    return;
}

print(__FUNCTION__ . ": OK" . "\n");

Node.js

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

const client = new OSS({
  bucket: '<Your BucketName>',
  // region以杭州为例（oss-cn-hangzhou），其他region按实际情况填写。
  region: '<Your Region>',
  // 阿里云账号AccessKey拥有所有API的访问权限，风险很高。强烈建议您创建并使用RAM用户进行API访问或日常运维，请登录RAM控制台创建RAM用户。
  accessKeyId: '<Your AccessKeyId>',
  accessKeySecret: '<Your AccessKeySecret>'
});

async function putBucketVersioning() {
  // 设置存储空间版本控制状态为Suspended。
  const status = 'Suspended'; 
  const result = await client.putBucketVersioning('<Bucket Name>', status);
  console.log(result);
}
putBucketVersioning();

Python

# -*- coding: utf-8 -*-
import oss2
from oss2.models import BucketVersioningConfig

# 阿里云主账号AccessKey拥有所有API的访问权限，风险很高。强烈建议您创建并使用RAM用户进行API访问或日常运维，请登录RAM控制台创建RAM用户。
auth = oss2.Auth('<yourAccessKeyId>', '<yourAccessKeySecret>')
# Endpoint以杭州为例，其它Region请按实际情况填写。
bucket = oss2.Bucket(auth, 'http://oss-cn-hangzhou.aliyuncs.com', '<yourBucketName>')

# 创建bucket版本控制配置。
config = BucketVersioningConfig()
# 状态配置为Suspended。
config.status = oss2.BUCKET_VERSIONING_SUSPEND

# 设置bucket版本控制状态。
result = bucket.put_bucket_versioning(config)
# 查看http返回码。
print('http response code:', result.status)

using Aliyun.OSS;
var endpoint = "<yourEndpoint>";
var accessKeyId = "<yourAccessKeyId>";
var accessKeySecret = "<yourAccessKeySecret>";
var bucketName = "<yourBucketName>";
// 初始化OssClient。
var client = new OssClient(endpoint, accessKeyId, accessKeySecret);
try
{
    // 设置存储空间版本控制状态为Suspended。
    client.SetBucketVersioning(new SetBucketVersioningRequest(bucketName, VersioningStatus.Suspended));;
    Console.WriteLine("Create bucket Version succeeded");
}
catch (Exception ex)
{
    Console.WriteLine("Create bucket Version failed. {0}", ex.Message);
}

package main

import (
  "fmt"
  "os"

  "github.com/aliyun/aliyun-oss-go-sdk/oss"
)

func main() {
  // 创建OSSClient实例。
  client, err := oss.New("<yourEndpoint>", "<yourAccessKeyId>", "<yourAccessKeySecret>")
  if err != nil {
    fmt.Println("Error:", err)
    os.Exit(-1)
  }

  // 创建一个存储空间。
  err = client.CreateBucket("<yourBucketName>")
  if err != nil {
    fmt.Println("Error:", err)
    os.Exit(-1)
  }
  // 设置存储空间版本控制状态为Suspended。
  config := oss.VersioningConfig{Status: "Suspended"}
  err = client.SetBucketVersioning("<yourBucketName>", config)
  if err != nil {
    fmt.Println("Error:", err)
    os.Exit(-1)
  }
}

C++

#include <alibabacloud/oss/OssClient.h>
using namespace AlibabaCloud::OSS;

int main(void)
{
    /*初始化OSS账号信息*/
    std::string AccessKeyId = "yourAccessKeyId";
    std::string AccessKeySecret = "yourAccessKeySecret";
    std::string Endpoint = "yourEndpoint";
    std::string BucketName = "yourBucketName";

    /*初始化网络等资源*/
    InitializeSdk();

    ClientConfiguration conf;
    OssClient client(Endpoint, AccessKeyId, AccessKeySecret, conf);

    /*创建bucket版本配置，状态设置为Suspended*/
    SetBucketVersioningRequest setrequest(BucketName, VersioningStatus::Suspended);
    auto outcome = client.SetBucketVersioning(setrequest);

    if (!outcome.isSuccess()) {
        /* 异常处理 */
        std::cout << "SetBucketVersioning fail" <<
        ",code:" << outcome.error().Code() <<
        ",message:" << outcome.error().Message() <<
        ",requestId:" << outcome.error().RequestId() << std::endl;
        ShutdownSdk();
        return -1;
    }

    /*释放网络等资源*/
    ShutdownSdk();
    return 0;
}

使用命令行工具ossutil

关于使用ossutil暂停版本控制的具体步骤，请参见设置版本控制状态。

使用REST API

如果您的程序自定义要求较高，您可以直接发起REST API请求。直接发起REST API请求需要手动编写代码计算签名。更多信息，请参见PutBucketVersioning。

查看版本

您可以使用命令行ossutil查看某个Object的所有版本。例如，您希望查看examplebucket根目录下example.txt的所有版本。

./ossutil64 ls oss://examplebucket/example.txt --all-versions

更多信息，请参见列举Object。

恢复版本

使用OSS控制台

在开启版本控制下的Bucket中删除Object时，历史版本Object不会被真正删除，而是产生一个删除标记来标识Object的当前版本是删除状态。此时您可以在控制台恢复版本。

单击Bucket列表，然后单击目标Bucket名称。
在左侧导航栏，单击Bucket列表，然后单击目标Bucket名称。
选择文件管理 > 文件列表。
单击历史版本右侧的显示。
选中待恢复文件，然后单击页面下方的恢复。
在弹出的对话框，单击确定。

使用命令行工具ossutil

您可以使用revert-versioning（恢复版本）命令恢复已删除文件的历史版本。更多信息，请参见revert-versioning（恢复版本）。