本文中含有需要您注意的重要提示信息,忽略该信息可能对您的业务造成影响,请务必仔细阅读。
文件上传到OSS后,OSS会使用Bucket默认域名生成文件访问地址。使用浏览器访问该地址时,会触发强制下载行为。如果您有在浏览器中预览文件的需求,需要为Bucket绑定自定义域名,然后通过自定义域名访问该Bucket中的文件。绑定自定义域名后,不影响继续使用OSS提供的域名。
前提条件
已创建Bucket。具体步骤,请参见创建存储空间。
已注册二级域名。支持绑定非阿里云注册的域名。如果您还未注册域名,您可以在阿里云域名服务平台注册域名。具体步骤,请参见注册域名。
如果要绑定的Bucket在中国内地,确保域名已备案,且账号已实名认证。如何备案和实名认证,请参见ICP备案全流程、个人实名认证、企业实名认证和个体工商户认证。
使用场景
文件预览:通过自定义域名访问OSS Bucket,避免OSS强制增加下载响应头,实现在浏览器中预览文件。
品牌形象和专业性:将自定义域名绑定到OSS Bucket,提供个性化域名,增强品牌形象和专业性,增加用户信任度。
防止域名被拦截:一些应用或平台可能会对Bucket默认域名进行拦截。您可以为Bucket绑定自定义域名,以确保您的OSS Bucket中的资源能够被正常访问。
访问方便性:使用自定义域名访问OSS Bucket,方便易记,相比使用OSS默认域名,更简洁友好,轻松访问和分享资源。
用户体验优化:通过自定义域名,提高访问速度,结合CDN加速技术,实现快速内容分发和下载,减少延迟,提升用户体验。
链接的持久性:绑定自定义域名到OSS Bucket后,即使后续存储位置或服务有变化,用户仍可使用相同域名访问资源,确保链接的持久性,长期可访问和使用存储资源。
背景信息
访问Bucket默认域名或传输加速域名会默认下载文件,而访问自定义域名会默认预览文件的原因如下:
访问Bucket默认域名或传输加速域名
出于数据传输安全考虑,使用OSS提供的Bucket默认域名(<bucketName>.oss-<regionId>.aliyuncs.com
)或传输加速域名(<bucketName>.oss-accelerate.aliyuncs.com
)访问Bucket的文件(网页、图片)时,OSS会在返回中强制增加下载响应头(x-oss-force-download: true
和Content-Disposition: attachment
)。浏览器检测到Content-Disposition: attachment
时,会触发强制下载行为。使用OSS提供的域名访问文件时,触发下载行为的请求流程如下:
关于使用OSS的默认Bucket域名或传输加速域名访问文件,触发自动下载的生效时间和生效对象,请参见附录:强制下载命中的x-oss-ec规则。
访问自定义域名
您可以在已注册的域名(例如example.com)上自定义一个子域名(例如static.example.com),并将其绑定至Bucket,然后使用自定义域名访问文件。此时,OSS不会在返回中强制增加下载响应头。由于OSS没有设置Content-Disposition
字段,浏览器会默认将其设置为inline
。浏览器会直接显示文件内容,而不是下载文件。使用自定义域名访问文件,默认预览行为的请求流程如下:
使用限制
不支持绑定中文域名。
每个域名只能绑定至一个Bucket。
每个Bucket最多可以绑定100个域名。
通过OSS管理控制台绑定自定义域名时,不允许绑定泛域名(将域名前缀设置为*,从而将二级域名的所有子域名都指向Bucket默认域名)。通过CDN加速OSS时,允许绑定泛域名,但该域名不会在OSS管理控制台显示。
操作步骤
步骤一:绑定自定义域名
根据域名所属服务提供商和所属账号,参考对应的步骤将域名绑定至OSS Bucket。
如果您不确定域名所属服务提供商,您可以在域名信息查询(WHOIS)页面进行查询。
如果您不确定域名是否属于当前阿里云账号,您可以在云解析DNS控制台进行查询。
绑定的自定义域名中涉及的顶级域名必须满足指定后缀的要求,否则会被视为无效域名,最终导致域名绑定失败。更多信息,请参见顶级域名后缀列表。
绑定当前阿里云账号注册的域名
将当前阿里云账号注册的域名,绑定至OSS Bucket的操作步骤如下:
绑定其他阿里云账号注册的域名
将阿里云A账号注册的域名,绑定至阿里云B账号的OSS Bucket的操作步骤如下:
使用阿里云B账号,获取TXT记录的主机记录和记录值。
登录OSS管理控制台。
单击Bucket 列表,然后单击目标Bucket名称。
在左侧导航栏,选择Bucket 配置>域名管理。
在域名管理页面,单击绑定域名。
在绑定域名面板,输入要绑定的阿里云A账号的自定义域名,例如
static.example.com
,然后复制页面显示的主机记录中的_dnsauth
和记录值。重要复制TXT记录值后,请保持绑定域名面板,直到最终完成提交。如果关闭绑定域名面板,TXT记录值会失效,导致之后验证域名所有权失败。
使用阿里云A账号,添加TXT记录。
登录云解析DNS控制台。
在域名解析列表中,单击目标域名右侧的解析设置。
单击添加记录,填写域名解析信息。
参数
说明
示例值
记录类型
选择域名指向的类型为TXT。
TXT
主机记录
填写使用阿里云B账号获取的TXT记录的主机记录。
_dnsauth
解析请求来源
解析域名时使用的线路。 建议选择默认,系统将自动选择最佳线路。
默认
记录值
填写使用阿里云B账号获取的TXT记录中的CnameToken。
b0d777f7ccddeae93358d908ed59****
TTL
域名的更新周期,保留默认值即可。
说明生效TTL的时间有一定的延迟,请以实际为准。
10分钟
单击确定。
使用阿里云B账号,在OSS控制台的绑定域名面板,单击验证域名所有权并绑定。
使用阿里云A账号,添加CNAME记录。
在域名解析列表中,单击目标域名右侧的解析设置。
单击添加记录,填写域名解析信息。
参数
说明
示例值
记录类型
选择域名指向的类型为CNAME。
CNAME
主机记录
根据域名前缀填写主机记录。
如果是二级域名,例如
example.com
,输入@。如果是三级域名,输入三级域名的前缀。例如域名为
static.example.com
,输入static。
static
解析请求来源
解析域名时使用的线路。 建议选择默认,系统将自动选择最佳线路。
默认
记录值
填写Bucket的外网访问域名。Bucket域名的结构为<bucketname>.<endpoint>。关于不同地域的外网Endpoint,请参见访问域名和数据中心。
examplebucket.oss-cn-hangzhou.aliyuncs.com
TTL
域名的更新周期,保留默认值即可。
说明生效TTL的时间有一定的延迟,请以实际为准。
10分钟
单击确定。
绑定非阿里云账号注册的域名
将在其他域名服务提供商注册的域名,绑定至OSS Bucket的操作步骤如下:
在阿里云OSS,生成TXT记录的主机记录和记录值。
登录OSS管理控制台。
单击Bucket 列表,然后单击目标Bucket名称。
在左侧导航栏,选择Bucket 配置>域名管理。
在域名管理页面,单击绑定域名。
在绑定域名面板,输入在其他域名服务提供商注册的域名,例如
static.example.com
,然后复制页面显示的主机记录中的_dnsauth
和记录值。重要复制TXT记录值后,请保持绑定域名面板,直到最终完成提交。如果关闭绑定域名面板,TXT记录值会失效,导致之后验证域名所有权失败。
在域名服务提供商的DNS解析平台,参考下表添加TXT记录。
参数
说明
示例值
记录类型
选择域名指向的类型为TXT。
TXT
主机记录
填写从阿里云OSS获取的TXT记录的主机记录,并按照域名服务提供商的DNS解析平台要求进行填写。
_dnsauth
记录值
填写从阿里云OSS获取的TXT记录中的CnameToken。
b0d777f7ccddeae93358d908ed59****
在阿里云OSS控制台的绑定域名面板,单击验证域名所有权并绑定。
在域名服务提供商的DNS解析平台,参考下表添加CNAME记录。
参数
说明
示例值
记录类型
选择域名指向的类型为CNAME。
CNAME
主机记录
根据域名前缀填写主机记录。
如果是二级域名,例如
example.com
,输入@。如果是三级域名,输入三级域名的前缀。例如域名为
static.example.com
,输入static。
static
记录值
填写Bucket的外网访问域名。Bucket域名的结构为<bucketname>.<endpoint>。关于不同地域的外网Endpoint,请参见访问域名和数据中心。
examplebucket.oss-cn-hangzhou.aliyuncs.com
步骤二:验证自定义域名
绑定自定义域名后,您可以使用nslookup
或dig
命令来检查CNAME解析的结果。如果域名解析结果显示为您绑定的Bucket的外网访问域名,则说明自定义域名的CNAME解析已生效。
nslookup
将example.com替换为您要查询的域名,然后执行以下命令。
nslookup -type=CNAME example.com
成功返回示例如下。
dig
将example.com替换为您要查询的域名,然后执行以下命令。
dig CNAME example.com
成功返回示例如下。
步骤三:使用自定义域名
自定义域名生效后,您可以直接通过HTTP协议访问文件。
HTTP协议无法确保数据在传输过程中的安全性,即数据可能存在被第三方截取或篡改的风险。考虑到数据安全的重要性,强烈推荐您采用HTTPS协议进行访问。具体操作,请参见使用HTTPS协议。
上传文件。
具体操作,请参见简单上传。
获取文件URL。
临时文件URL
获取临时有效的文件URL的操作步骤如下:
设置文件读写权限ACL为私有。
具体操作,请参见设置Object ACL。
私有文件URL的格式为
http://YourDomain/ObjectName?签名参数
。您可以通过以下方法获取文件URL并设置URL的有效时长。
使用OSS控制台
登录OSS管理控制台。
单击Bucket列表,然后单击目标Bucket名称。
在左侧导航栏,选择
。在文件列表页面,单击目标文件名称。
在详情面板的自有域名,选择绑定的自定义域名,其他保持默认值,然后单击复制文件URL。
使用图形化管理工具ossbrowser
ossbrowser支持Object级别的操作与控制台支持的操作类似,请按照ossbrowser界面指引完成获取签名URL的操作。关于如何使用ossbrowser,请参见快速使用ossbrowser。
使用阿里云SDK
使用自定义域名新建OssClient。
使用OssClient调用generatePresignedUrl接口获取签名URL。
各语言SDK示例,请参见签名版本1。
Java
// yourEndpoint填写自定义域名。 String endpoint = "yourEndpoint"; // 从环境变量中获取访问凭证。运行本代码示例之前,请先配置环境变量。 EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider(); // 创建ClientBuilderConfiguration实例,您可以根据实际情况修改默认参数。 ClientBuilderConfiguration conf = new ClientBuilderConfiguration(); // 设置是否支持CNAME。CNAME用于将自定义域名绑定到目标Bucket。 conf.setSupportCname(true); // 创建OSSClient实例。 OSS ossClient = new OSSClientBuilder().build(endpoint, credentialsProvider, conf); // 关闭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\Credentials\EnvironmentVariableCredentialsProvider; use OSS\OssClient; use OSS\CoreOssException; // 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。 $provider = new EnvironmentVariableCredentialsProvider(); // 填写自定义域名,例如http://example.com。 $endpoint = "http://example.com"; try { $config = array( "provider" => $provider, "endpoint" => $endpoint, "cname" => true ); $ossClient = new OssClient($config); } catch (OssException $e) { print $e->getMessage(); }
Node.js
const OSS = require('ali-oss') const client = new OSS({ // 使用自定义域名作为Endpoint。 endpoint: 'http://img.example.com', // 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。 accessKeyId: process.env.OSS_ACCESS_KEY_ID, accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET, cname: true });
Python
# -*- coding: utf-8 -*- import oss2 from oss2.credentials import EnvironmentVariableCredentialsProvider # 从环境变量中获取访问凭证。运行本代码示例之前,请先配置环境变量。 auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider()) # 填写自定义域名,例如example.com。 cname = 'http://example.com' # 填写Bucket名称,并设置is_cname=True来开启CNAME。CNAME是指将自定义域名绑定到存储空间。 bucket = oss2.Bucket(auth, cname, 'examplebucket', is_cname=True)
Browser.js
<!DOCTYPE html> <html lang="en"> <head> <meta charset="UTF-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>Document</title> <script src="https://gosspublic.alicdn.com/aliyun-oss-sdk-6.18.0.min.js"></script> </head> <body> <script> const client = new OSS({ // 填写自定义域名,例如example.com。 endpoint: "example.com", // 从STS服务获取的临时访问密钥(AccessKey ID和AccessKey Secret)。 accessKeyId: "yourAccessKeyId", accessKeySecret: "yourAccessKeySecret", // 从STS服务获取的安全令牌(SecurityToken)。 stsToken: 'yourSecurityToken', // 填写Bucket名称,例如examplebucket。 bucket: "examplebucket", cname: true, }); </script> </body> </html>
.NET
using Aliyun.OSS; using Aliyun.OSS.Common; // 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。 var accessKeyId = Environment.GetEnvironmentVariable("OSS_ACCESS_KEY_ID"); var accessKeySecret = Environment.GetEnvironmentVariable("OSS_ACCESS_KEY_SECRET"); // 填写自定义域名。 const string endpoint = "yourDomain"; // 创建ClientConfiguration实例,按照您的需要修改默认参数。 var conf = new ClientConfiguration(); // 打开CNAME开关。CNAME是指将自定义域名绑定到存储空间的过程。 conf.IsCname = true; // 创建OssClient实例。 var client = new OssClient(endpoint, accessKeyId, accessKeySecret, conf);
Android
// yourEndpoint填写自定义域名。 String endpoint = "yourEndpoint"; // 从STS服务获取的临时访问密钥(AccessKey ID和AccessKey Secret)。 String accessKeyId = "yourAccessKeyId"; String accessKeySecret = "yourAccessKeySecret"; // 从STS服务获取的安全令牌(SecurityToken)。 String securityToken = "yourSecurityToken"; OSSCredentialProvider credentialProvider = new OSSStsTokenCredentialProvider(accessKeyId, accessKeySecret, securityToken); // 创建OSSClient实例。 OSSClient oss = new OSSClient(getApplicationContext(), endpoint, credentialProvider);
Go
package main import ( "fmt" "github.com/aliyun/aliyun-oss-go-sdk/oss" "os" ) func main(){ // 从环境变量中获取访问凭证。运行本代码示例之前,请先配置环境变量。 provider, err := oss.NewEnvironmentVariableCredentialsProvider() if err != nil { fmt.Println("Error:", err) os.Exit(-1) } // yourEndpoint填写Bucket对应的自定义域名。 // oss.UseCname(true)用于开启CNAME。CNAME用于将自定义域名绑定至存储空间。 client, err := oss.New("yourEndpoint", "", "", oss.SetCredentialsProvider(&provider),oss.UseCname(true)) if err != nil { fmt.Println("Error:", err) os.Exit(-1) } fmt.Printf("client:%#v\n", client) }
iOS
// yourEndpoint填写自定义域名。 NSString *endpoint = @"yourEndpoint"; // 从STS服务获取的临时访问密钥(AccessKey ID和AccessKey Secret)。 NSString *accessKeyId = @"yourAccessKeyId"; NSString *accessKeySecret = @"yourAccessKeySecret"; // 从STS服务获取的安全令牌(SecurityToken)。 NSString *securityToken = @"yourSecurityToken"; id<OSSCredentialProvider> credentialProvider = [[OSSStsTokenCredentialProvider alloc] initWithAccessKeyId:accessKeyId secretKeyId:accessKeySecret securityToken:securityToken]; OSSClient *client = [[OSSClient alloc] initWithEndpoint:endpoint credentialProvider:credentialProvider];
C++
#include <alibabacloud/oss/OssClient.h> using namespace AlibabaCloud::OSS; int main(void) { /* 初始化OSS账号信息。*/ /* yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1(杭州)为例,Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。*/ std::string Endpoint = "yourEndpoint"; /* 初始化网络等资源。*/ InitializeSdk(); ClientConfiguration conf; /* 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。*/ auto credentialsProvider = std::make_shared<EnvironmentVariableCredentialsProvider>(); OssClient client(Endpoint, credentialsProvider, conf); /* 释放网络等资源。*/ ShutdownSdk(); return 0; }
C
#include "oss_api.h" #include "aos_http_io.h" /* 填写自定义域名。*/ const char *endpoint = "yourCustomEndpoint"; void init_options(oss_request_options_t *options) { options->config = oss_config_create(options->pool); /* 用char*类型的字符串初始化aos_string_t类型。*/ aos_str_set(&options->config->endpoint, endpoint); /* 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。*/ aos_str_set(&options->config->access_key_id, getenv("OSS_ACCESS_KEY_ID")); aos_str_set(&options->config->access_key_secret, getenv("OSS_ACCESS_KEY_SECRET")); /* 开启CNAME,将自定义域名绑定到存储空间上。*/ options->config->is_cname = 1; options->ctl = aos_http_controller_create(options->pool, 0); } int main() { aos_pool_t *p; oss_request_options_t *options; /* 初始化全局变量,在程序生命周期内只需要调用一次。*/ if (aos_http_io_initialize(NULL, 0) != AOSE_OK) { return -1; } /* 初始化内存池和options。*/ aos_pool_create(&p, NULL); options = oss_request_options_create(p); init_options(options); /* 逻辑代码,此处省略。*/ /* 释放内存池,相当于释放了请求过程中各资源分配的内存。*/ aos_pool_destroy(p); /* 释放之前分配的全局资源,在程序生命周期内只需要调用一次。*/ aos_http_io_deinitialize(); return 0; }
Ruby
require 'aliyun/oss' client = Aliyun::OSS::Client.new( # 使用自定义域名作为Endpoint。 endpoint: 'http://example.com', # 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。 access_key_id: ENV['OSS_ACCESS_KEY_ID'], access_key_secret: ENV['OSS_ACCESS_KEY_SECRET'] cname: true) )
使用命令行工具ossutil
通过配置文件设置Bucket和自定义域名的映射关系。详情请参见配置ossutil。
通过sign生成经过签名的文件URL。详情请参见sign(生成签名URL)。
长期文件URL
警告如需获取长期有效的文件URL,即不存在过期时间。您需要将读文件读写权限ACL设置为公共读。设置为公共读后,文件的互联网上任何用户都可以对该Object进行访问,这有可能造成您数据的外泄以及费用激增,建议您使用临时文件URL。
获取长期有效的文件URL的操作步骤如下:
设置文件读写权限ACL为公共读。
具体操作,请参见设置Object ACL。
拼接文件URL。
绑定自定义域名后,如果文件读写权限ACL为公共读,则无需进行签名操作。公共读文件URL的格式为
http://YourDomainName/ObjectName
。例如,您为华东1(杭州)地域的examplebucket绑定了自定义域名static.example.com,且该Bucket下包含example.jpg的文件,则该文件URL为
http://static.example.com/example.jpg
。
在浏览器中,访问生成的文件URL。
后续操作
使用HTTPS协议
HTTPS协议在HTTP的基础上整合了SSL/TLS安全协议层,从而为数据传输提供了强大的加密保护。使用HTTPS协议访问之前,您需要购买相应的数字证书并完成证书托管。具体步骤,请参见绑定自定义域名的证书托管。
使用CDN加速
如果您希望提升静态资源访问的速度和稳定性,您可以为OSS开启CDN加速,然后将自定义域名绑定到CDN加速域名上。具体操作,请参见绑定CDN加速域名。
避免盗刷
如果您希望避免Bucket内的资源被其他人盗用,您可以通过设置Referer列表(包括白名单Referer和黑名单Referer)以及是否允许空Referer的方式,限制您Bucket内资源的访问来源。具体步骤,请参见防盗链。
加速跨境传输
如果您希望提升跨境访问的速度和稳定性,您可以将自定义域名绑定到OSS传输加速域名上。具体操作,请参见绑定CDN加速域名。
托管静态网站
如果您希望将您的静态网站托管到OSS,并使用自定义域名访问,您需要为存储空间设置静态网站托管。具体步骤,请参见静态网站托管概述。
常见问题
已有主机记录与当前添加CNAME记录生成的主机记录相同,暂时无法自动添加CNAME记录
域名绑定在自己的其他Bucket上
NeedVerifyDomainOwnership
绑定自定义域名后,还是无法预览文件?
已经正常解析到WAF且有内容的域名可以绑定至Bucket吗?
绑定自定义域名后,之前的文件URL是否可以继续使用?
使用自定义域名就是公网访问吗?
如何使用自定义域名访问OSS文件时是下载行为?
如何解除自定义域名绑定?
相关API
关于创建域名所有权验证所需的CnameToken的接口,请参见CreateCnameToken。
关于获取已创建的CnameToken的接口,请参见GetCnameToken。
关于为某个Bucket绑定自定义域名的接口,请参见PutCname。
关于查询某个Bucket下绑定的所有自定义域名的接口,请参见ListCname。
关于删除某个Bucket已绑定的自定义域名的接口,请参见DeleteCname。
关于使用阿里云解析DNS添加TXT解析记录或CNAME解析记录的接口,请参见AddDomainRecord - 根据传入参数添加解析记录。