Bucket级别的访问权限控制-Bucket ACL-对象存储-阿里云

Bucket ACL（访问控制列表）是OSS提供的Bucket级别访问权限控制机制。通过Bucket ACL可直接设置Bucket的公开或私有访问权限，Object上传时若未指定ACL，将自动继承Bucket ACL设置。

工作原理

Bucket ACL通过预定义权限值控制Bucket的访问范围。OSS支持以下三种权限：

权限值	说明
private（默认值）	私有。只有Bucket拥有者或被授权用户可以对该Bucket内的文件进行读写操作，其他人无法访问。
public-read	公共读。只有Bucket拥有者或被授权用户可以写入，任何人（包括匿名访问者）都可以读取。
public-read-write	公共读写。任何人（包括匿名访问者）都可以对该Bucket内文件进行读写操作。

重要

public-read-write：互联网上任何用户都可以对该Bucket内的文件进行访问和写入。这可能造成数据外泄、费用激增，甚至被恶意写入违法信息。除特殊场景外，不建议配置此权限。
public-read：互联网上任何用户都可以访问该Bucket内文件，可能造成数据外泄和费用激增，请谨慎操作。

设置Bucket ACL

创建Bucket时默认开启阻止公共访问，Bucket ACL只能设置为private。如需设置为public-read或public-read-write，请先关闭阻止公共访问。

控制台

前往Bucket列表，单击目标Bucket名称。
在左侧导航栏，选择权限控制 > 读写权限。
单击设置，根据需求修改Bucket ACL。
单击保存，完成设置。

命令行工具ossutil

使用命令行工具ossutil 2.0的put-bucket-acl命令配置Bucket ACL。

ossutil api put-bucket-acl --bucket example-bucket --acl private

SDK

以下仅列举常见SDK修改Bucket ACL的代码示例，其他SDK的代码示例请参见SDK参考。

Java

// 本示例展示如何设置存储空间的访问权限（ACL）
// 使用前请配置环境变量 OSS_ACCESS_KEY_ID 和 OSS_ACCESS_KEY_SECRET

import com.aliyun.sdk.service.oss2.OSSClient;
import com.aliyun.sdk.service.oss2.credentials.CredentialsProvider;
import com.aliyun.sdk.service.oss2.credentials.StaticCredentialsProvider;
import com.aliyun.sdk.service.oss2.models.*;

public class SetBucketAcl {

    public static void main(String[] args) {
        String bucketName = "example-bucket";

        String accessKeyId = System.getenv("OSS_ACCESS_KEY_ID");
        String accessKeySecret = System.getenv("OSS_ACCESS_KEY_SECRET");
        CredentialsProvider provider = new StaticCredentialsProvider(accessKeyId, accessKeySecret);

        try (OSSClient client = OSSClient.newBuilder()
                .credentialsProvider(provider)
                .region("<region-id>")
                .build()) {

            // 设置存储空间 ACL 为私有
            // 可选值: "private", "public-read", "public-read-write"
            PutBucketAclRequest putRequest = PutBucketAclRequest.newBuilder()
                    .bucket(bucketName)
                    .acl("private")
                    .build();
            PutBucketAclResult putResult = client.putBucketAcl(putRequest);
            System.out.println("设置 Bucket ACL 成功，RequestId: " + putResult.requestId());

            // 获取存储空间 ACL
            GetBucketAclRequest getRequest = GetBucketAclRequest.newBuilder()
                    .bucket(bucketName)
                    .build();
            GetBucketAclResult getResult = client.getBucketAcl(getRequest);
            System.out.println("当前 Bucket ACL: " + getResult.accessControlPolicy().accessControlList().grant());

        } catch (Exception e) {
            System.err.println("操作失败: " + e.getMessage());
        }
    }
}

Python

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# 本示例展示如何设置存储空间的访问权限（ACL）
# 使用前请配置环境变量 OSS_ACCESS_KEY_ID 和 OSS_ACCESS_KEY_SECRET

import alibabacloud_oss_v2 as oss


def main() -> None:
    bucket_name = "example-bucket"

    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider
    cfg.region = "<region-id>"

    client = oss.Client(cfg)

    # 设置存储空间 ACL 为私有
    # 可选值: "private", "public-read", "public-read-write"
    put_result = client.put_bucket_acl(oss.PutBucketAclRequest(
        bucket=bucket_name,
        acl="private"
    ))
    print(f"设置 Bucket ACL 成功，RequestId: {put_result.request_id}")

    # 获取存储空间 ACL
    get_result = client.get_bucket_acl(oss.GetBucketAclRequest(
        bucket=bucket_name
    ))
    print(f"当前 Bucket ACL: {get_result.acl}")


if __name__ == "__main__":
    main()

// 本示例展示如何设置存储空间的访问权限（ACL）
// 使用前请配置环境变量 OSS_ACCESS_KEY_ID 和 OSS_ACCESS_KEY_SECRET

package main

import (
	"context"
	"log"

	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
)

func main() {
	bucketName := "example-bucket"

	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion("<region-id>")

	client := oss.NewClient(cfg)

	// 设置存储空间 ACL 为私有
	// 可选值: oss.BucketACLPrivate, oss.BucketACLPublicRead, oss.BucketACLPublicReadWrite
	putResult, err := client.PutBucketAcl(context.TODO(), &oss.PutBucketAclRequest{
		Bucket: oss.Ptr(bucketName),
		Acl:    oss.BucketACLPrivate,
	})
	if err != nil {
		log.Fatalf("设置 Bucket ACL 失败: %v", err)
	}
	log.Printf("设置 Bucket ACL 成功，RequestId: %s", putResult.Headers.Get("X-Oss-Request-Id"))

	// 获取存储空间 ACL
	getResult, err := client.GetBucketAcl(context.TODO(), &oss.GetBucketAclRequest{
		Bucket: oss.Ptr(bucketName),
	})
	if err != nil {
		log.Fatalf("获取 Bucket ACL 失败: %v", err)
	}
	log.Printf("当前 Bucket ACL: %s", *getResult.ACL)
}

PHP

<?php
// 本示例展示如何设置存储空间的访问权限（ACL）
// 使用前请配置环境变量 OSS_ACCESS_KEY_ID 和 OSS_ACCESS_KEY_SECRET

require_once __DIR__ . '/vendor/autoload.php';

use AlibabaCloud\Oss\V2 as Oss;

$bucketName = 'example-bucket';

$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();

$cfg = Oss\Config::loadDefault();
$cfg->setCredentialsProvider($credentialsProvider);
$cfg->setRegion('<region-id>');

$client = new Oss\Client($cfg);

try {
    // 设置存储空间 ACL 为私有
    // 可选值: BucketACLType::PRIVATE, BucketACLType::PUBLIC_READ, BucketACLType::PUBLIC_READ_WRITE
    $putResult = $client->putBucketAcl(new Oss\Models\PutBucketAclRequest(
        bucket: $bucketName,
        acl: Oss\Models\BucketACLType::PRIVATE
    ));
    printf("设置 Bucket ACL 成功，RequestId: %s\n", $putResult->requestId);

    // 获取存储空间 ACL
    $getResult = $client->getBucketAcl(new Oss\Models\GetBucketAclRequest(
        bucket: $bucketName
    ));
    printf("当前 Bucket ACL: %s\n", $getResult->accessControlList->grant);
} catch (Exception $e) {
    printf("操作失败: %s\n", $e->getMessage());
}

// 本示例展示如何设置存储空间的访问权限（ACL）
// 使用前请配置环境变量 OSS_ACCESS_KEY_ID 和 OSS_ACCESS_KEY_SECRET

using OSS = AlibabaCloud.OSS.V2;

var bucketName = "example-bucket";
var region = "<region-id>";

var cfg = OSS.Configuration.LoadDefault();
cfg.CredentialsProvider = new OSS.Credentials.EnvironmentVariableCredentialsProvider();
cfg.Region = region;

using var client = new OSS.Client(cfg);

try
{
    // 设置存储空间 ACL 为私有
    // 可选值: "private", "public-read", "public-read-write"
    var putResult = await client.PutBucketAclAsync(new OSS.Models.PutBucketAclRequest()
    {
        Bucket = bucketName,
        Acl = "private"
    });
    Console.WriteLine($"设置 Bucket ACL 成功，RequestId: {putResult.RequestId}");

    // 获取存储空间 ACL
    var getResult = await client.GetBucketAclAsync(new OSS.Models.GetBucketAclRequest()
    {
        Bucket = bucketName
    });
    Console.WriteLine($"当前 Bucket ACL: {getResult.AccessControlPolicy?.AccessControlList?.Grant}");
}
catch (Exception ex)
{
    Console.WriteLine($"操作失败: {ex.Message}");
}

Node.js

// 本示例展示如何设置存储空间的访问权限（ACL）
// 使用前请配置环境变量 OSS_ACCESS_KEY_ID 和 OSS_ACCESS_KEY_SECRET

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

async function main() {
    const bucketName = 'example-bucket';

    const client = new OSS({
        region: 'oss-<region-id>',
        accessKeyId: process.env.OSS_ACCESS_KEY_ID,
        accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
        authorizationV4: true,
    });

    try {
        // 设置存储空间 ACL 为私有
        // 可选值: 'private', 'public-read', 'public-read-write'
        await client.putBucketACL(bucketName, 'private');
        console.log('设置 Bucket ACL 成功');

        // 获取存储空间 ACL
        const result = await client.getBucketACL(bucketName);
        console.log(`当前 Bucket ACL: ${result.acl}`);
    } catch (err) {
        console.error('操作失败:', err.message);
    }
}

main();

查询Bucket ACL变更记录

当发现Bucket访问异常、数据意外公开、收到安全告警或进行定期审计时，可通过操作审计追踪Bucket ACL的修改记录，包括修改人员和修改时间。

前往操作审计控制台，在左侧菜单栏选择事件 > 事件查询。
在页面上方选择要查询的Bucket所在地域，设置服务名称为对象存储(Oss)、事件名称为PutBucketAcl，系统将自动查询符合条件的Bucket ACL变更记录。
在页面右侧关闭归纳列表选项，单击变更记录操作列的查看详情，然后单击配置时间线，查看Bucket ACL变更前后的记录值。

常见问题

CDN回源OSS时，OSS的Bucket ACL是否必须为公共读或者公共读写？

无需设置为公共读权限。Bucket ACL为私有时，可开启CDN回源私有Bucket功能。详情请参见设置回源私有Bucket。