华为云OSS从0开始对接：Java、PHP、Python三语言实战指南

apphuang2026年07月02日 18:37:503

1. 华为云OSS概述与开通准备

对象存储服务（Object Storage Service，OBS）是华为云提供的一种稳定、安全、高效、易用的云存储服务，具备标准Restful API接口，可存储任意数量和形式的非结构化数据。OSS的核心概念是桶（Bucket）和对象（Object）——桶是存储对象的容器，对象则是存储的具体文件。无论是网站图片、视频文件、备份归档数据，还是大数据分析的海量日志，都可以通过OSS进行可靠存储。

对于开发者而言，华为云OSS提供了丰富的接入方式：管理控制台、API、SDK（Java/PHP/Python/Node.js等）、图形化工具OBS Browser+以及命令行工具obsutil。本文将从零开始，手把手带你完成华为云OSS的对接全流程，重点覆盖Java、PHP、Python三种主流开发语言的SDK实战。

需要先登录华为云控制台，点击：华为云控制台，还没有账号，点击：注册并关联，已有账号点击：登录后关联

1.1 注册账号与实名认证

使用华为云OSS的第一步是拥有一个华为账号并完成实名认证。如果你还没有华为账号，访问华为云官网点击注册，按提示填写手机号、邮箱等信息完成注册。注册成功后，建议立即完成实名认证——个人实名认证通常需要提供身份证信息，企业实名认证则需要营业执照等资料。实名认证是使用华为云所有付费服务的前提。

1.2 开通OSS服务

登录华为云控制台后，在服务列表中找到"对象存储服务 OBS"，点击进入服务页面。首次使用时，页面会提示开通服务，确认后即可完成开通。开通OSS服务本身不产生费用，费用仅在实际使用存储空间、流量和API请求时产生。新用户通常可以享受一定额度的免费试用资源，具体以华为云官网活动为准。

1.3 获取访问密钥（AK/SK）

访问密钥（Access Key ID和Secret Access Key）是调用OSS API的身份凭证，相当于云服务的"用户名和密码"。获取AK/SK的具体步骤如下：

登录华为云控制台，点击页面右上角的用户名，在下拉菜单中选择"我的凭证"
在左侧导航栏中单击"访问密钥"
单击"新增访问密钥"，完成身份验证（手机验证或邮箱验证）
验证通过后，系统会生成并下载一个名为credentials.csv的文件
打开该文件即可获取Access Key ID和Secret Access Key

安全提示：Secret Access Key仅在下载时可见，请务必妥善保管，切勿在代码中硬编码AK/SK。推荐使用环境变量或密钥管理服务来存储敏感凭证。

1.4 确定Endpoint（终端节点）

Endpoint是OSS服务的访问地址，格式通常为obs.区域代码.myhuaweicloud.com。例如，华北-北京四区域的Endpoint为obs.cn-north-4.myhuaweicloud.com。你可以在华为云官网的"地区和终端节点"页面查询各区域对应的Endpoint。选择Endpoint时需要注意：

Endpoint必须与Bucket所在区域一致，否则无法正常访问
如果使用同区域的ECS服务器访问OSS，建议使用内网Endpoint（如obs.cn-north-4.myhuaweicloud.com），可免流量费用

2. 创建Bucket（存储桶）

Bucket是OSS中存储对象的容器，所有文件都必须存放在某个Bucket中。创建Bucket时需要了解以下核心规则与最佳实践。

2.1 桶命名规则

桶名需要全局唯一，不能与已有任何桶名称重复（包括其他用户创建的桶）。具体命名约束如下：

长度范围为3到63个字符
仅支持小写字母、数字、中划线（-）和英文句号（.）
必须以小写字母或数字开头和结尾
禁止两个英文句号相邻（如"my..bucket"）
禁止英文句号和中划线相邻（如"my-.bucket"）
禁止使用IP地址格式

最佳实践：建议避免在桶名中包含英文句号（.），因为桶名会作为访问域名的一部分，包含句号可能导致HTTPS访问时证书校验失败。推荐使用纯小写字母和数字的组合，如myapp-images。

2.2 桶的存储类别

华为云OSS支持四种存储类别，不同类别在性能、成本和适用场景上各有差异：

标准存储：访问时延低、吞吐量高，适用于频繁访问的热点数据（如大数据、移动应用、热点视频、社交图片等）
低频访问存储：适用于不频繁访问（平均一年少于12次）但需要快速访问的数据（如文件同步、企业备份等）
归档存储：适用于很少访问（平均一年访问一次）的长期备份数据，成本极低但数据恢复需要数分钟到数小时
深度归档存储：适用于几年访问一次的超长期归档数据，成本最低但恢复时间最长

创建Bucket时可以指定默认的存储类别，上传对象时也可以单独指定。

2.3 桶的访问权限

创建Bucket时建议将权限设置为"私有"，即只有经过身份认证的请求才能访问桶内对象。后续如果需要公开某些文件，可以通过生成签名URL或配置桶策略来实现精细化权限控制，而不是直接将整个桶设置为公共读。

2.4 创建Bucket的方式

华为云OSS支持多种方式创建Bucket：

管理控制台：登录OBS控制台，点击"创建桶"，按向导填写桶名、区域、存储类别、权限等参数即可完成创建
OBS Browser+：图形化桌面工具，操作直观
obsutil命令行工具：适合批量操作和自动化脚本
SDK：通过代码调用API创建（后续章节详述）

注意事项：桶创建成功后，名称和所属区域不可修改。删除桶后，桶名需要约30分钟才能被释放并重新使用。一个账号及账号下所有IAM用户一共可创建100个桶。

3. 文件上传的四种方式

文件上传到OSS是最基础也是最高频的操作。华为云OSS提供了四种主流上传方式，开发者可以根据实际场景灵活选择。

3.1 管理控制台上传

适合临时上传或少量文件测试。操作步骤：进入OBS控制台 → 点击目标桶名称进入对象列表 → 点击"上传对象" → 选择本地文件或拖拽文件到上传区域 → 确认上传。控制台上传支持单文件和批量文件上传，也支持创建文件夹来组织文件结构。需要注意的是，OSS本身没有文件夹的概念，所谓"文件夹"实际是一个大小为0且对象名以"/"结尾的对象。

3.2 OBS Browser+图形化工具

OBS Browser+是华为云官方提供的图形化桌面工具，支持Windows、macOS和Linux系统。它的优势在于操作直观、功能全面，支持桶管理、对象管理、批量上传下载、断点续传等高级功能。使用前需要下载安装OBS Browser+，然后使用AK/SK登录即可连接OSS服务。

3.3 obsutil命令行工具

obsutil是华为云OSS的命令行工具，适合熟悉命令行的开发者，尤其在批量处理、自动化脚本和CI/CD集成场景中非常高效。安装和使用步骤：

访问华为云官网下载对应操作系统的obsutil压缩包
解压后配置AK/SK和Endpoint（可通过obsutil config命令配置）
创建桶：obsutil mb obs://桶名
上传文件：obsutil cp 本地文件路径 obs://桶名/对象名

obsutil支持Windows、Linux和macOS等操作系统，可根据实际情况选择合适版本。

3.4 SDK代码上传

对于需要集成到应用程序中的场景，使用SDK是最佳选择。下面将分别介绍Java、PHP、Python三种语言的SDK配置与文件上传实现。

4. Java SDK对接实战

4.1 引入SDK依赖

在Maven项目的pom.xml中添加华为云OBS Java SDK依赖：

<dependency>
    <groupId>com.huaweicloud</groupId>
    <artifactId>esdk-obs-java</artifactId>
    <version>3.21.10</version>
</dependency>

如果是Gradle项目，可以在build.gradle中添加：

implementation 'com.huaweicloud:esdk-obs-java:3.21.10'

4.2 初始化ObsClient

ObsClient是Java SDK的核心客户端类，所有OSS操作都需要通过它来完成。初始化时需要传入AK、SK和Endpoint：

import com.obs.services.ObsClient;

String ak = System.getenv("ACCESS_KEY_ID");
String sk = System.getenv("SECRET_ACCESS_KEY");
String endpoint = "obs.cn-north-4.myhuaweicloud.com";

ObsClient obsClient = new ObsClient(ak, sk, endpoint);

安全建议：AK和SK应从环境变量读取，禁止在代码中硬编码。

4.3 创建Bucket（Java）

使用Java SDK创建Bucket的示例代码：

import com.obs.services.model.CreateBucketRequest;
import com.obs.services.model.StorageClassEnum;

CreateBucketRequest request = new CreateBucketRequest("myapp-images");
request.setLocation("cn-north-4");
request.setStorageClass(StorageClassEnum.STANDARD);
obsClient.createBucket(request);

创建Bucket时需要拥有obs:bucket:CreateBucket权限。同一用户在同一区域多次创建同名桶不会报错，桶属性以第一次请求为准。

4.4 上传文件（Java）

使用putObject方法上传本地文件到OSS：

import com.obs.services.model.PutObjectRequest;
import com.obs.services.model.PutObjectResult;
import java.io.File;

String bucketName = "myapp-images";
String objectKey = "photos/2026/photo01.jpg";
String localFilePath = "/path/to/local/photo.jpg";

PutObjectRequest request = new PutObjectRequest(bucketName, objectKey, new File(localFilePath));
PutObjectResult result = obsClient.putObject(request);
System.out.println("上传成功，ETag: " + result.getEtag());

putObject方法支持多种输入源：本地文件、输入流、字节数组等。上传大文件（超过5GB）时需要使用分段上传（Multipart Upload）。

4.5 下载文件（Java）

import com.obs.services.model.GetObjectRequest;
import java.io.File;

String bucketName = "myapp-images";
String objectKey = "photos/2026/photo01.jpg";
String downloadPath = "/path/to/download/photo.jpg";

GetObjectRequest request = new GetObjectRequest(bucketName, objectKey);
obsClient.getObject(request, new File(downloadPath));
System.out.println("下载成功");

4.6 生成签名URL（Java）

对于私有Bucket中的文件，外部访问需要生成带签名的临时URL：

import com.obs.services.model.TemporarySignatureRequest;
import com.obs.services.model.TemporarySignatureResponse;
import java.util.HashMap;

TemporarySignatureRequest request = new TemporarySignatureRequest();
request.setMethod(HttpMethodEnum.GET);
request.setBucketName("myapp-images");
request.setObjectKey("photos/2026/photo01.jpg");
request.setExpires(3600); // 有效期1小时

TemporarySignatureResponse response = obsClient.createTemporarySignature(request);
String signedUrl = response.getSignedUrl();
System.out.println("临时访问URL: " + signedUrl);

5. PHP SDK对接实战

5.1 安装SDK

华为云OBS PHP SDK推荐通过Composer安装：

composer require huaweicloud/huaweicloud-sdk-php-obs

或者下载SDK源码包后手动引入。

5.2 初始化ObsClient

<?php
require 'vendor/autoload.php';
use Obs\ObsClient;

$obsClient = new ObsClient([
    'key' => getenv('ACCESS_KEY_ID'),
    'secret' => getenv('SECRET_ACCESS_KEY'),
    'endpoint' => 'https://obs.cn-north-4.myhuaweicloud.com',
    'signature' => 'obs'
]);
?>

同样建议通过环境变量获取AK/SK，避免硬编码。

5.3 创建Bucket（PHP）

<?php
$resp = $obsClient->createBucket([
    'Bucket' => 'myapp-images',
    'Location' => 'cn-north-4',
    'StorageClass' => ObsClient::StorageClassStandard
]);
print_r($resp);
?>

PHP SDK的createBucket方法同样支持设置存储类别和访问权限。

5.4 上传文件（PHP）

<?php
$bucketName = 'myapp-images';
$objectKey = 'photos/2026/photo01.jpg';
$localFile = '/path/to/local/photo.jpg';

$resp = $obsClient->putObject([
    'Bucket' => $bucketName,
    'Key' => $objectKey,
    'SourceFile' => $localFile
]);
echo '上传成功，ETag: ' . $resp['ETag'] . "\n";
?>

5.5 下载文件（PHP）

<?php
$resp = $obsClient->getObject([
    'Bucket' => 'myapp-images',
    'Key' => 'photos/2026/photo01.jpg',
    'SaveAsFile' => '/path/to/download/photo.jpg'
]);
echo "下载成功\n";
?>

5.6 生成签名URL（PHP）

<?php
$resp = $obsClient->createSignedUrl([
    'Method' => 'GET',
    'Bucket' => 'myapp-images',
    'Key' => 'photos/2026/photo01.jpg',
    'Expires' => 3600
]);
echo '临时URL: ' . $resp['SignedUrl'] . "\n";
?>

PHP SDK生成的签名URL可用于临时授权访问私有文件。

5.7 表单上传（PHP）

PHP SDK还支持基于HTML表单的上传方式，适用于浏览器直接上传场景：

<?php
$resp = $obsClient->createPostSignature([
    'Expires' => 3600,
    'FormParams' => [
        'x-obs-acl' => ObsClient::AclPublicRead,
        'content-type' => 'text/plain'
    ]
]);
echo 'Policy: ' . $resp['Policy'] . "\n";
echo 'Signature: ' . $resp['Signature'] . "\n";
?>

生成的Policy和Signature需要填入HTML表单的隐藏字段中，表单的action指向OSS的Endpoint。

6. Python SDK对接实战

6.1 安装SDK

使用pip安装华为云OBS Python SDK：

pip install esdk-obs-python --upgrade

国内网络环境下建议使用华为云镜像源加速：

pip install esdk-obs-python -i https://repo.huaweicloud.com/repository/pypi/simple

目前华为云OBS Python SDK最新稳定版本为3.x系列，与Python 3.6+完全兼容。

6.2 初始化ObsClient

import os
from obs import ObsClient

ak = os.getenv('HUAWEI_OBS_AK')
sk = os.getenv('HUAWEI_OBS_SK')
server = 'obs.cn-north-4.myhuaweicloud.com'

obsClient = ObsClient(access_key_id=ak, secret_access_key=sk, server=server)

同样强烈建议从环境变量读取AK/SK，不要在代码中硬编码。

6.3 创建Bucket（Python）

bucketName = 'myapp-images'
obsClient.createBucket(bucketName, location='cn-north-4')
print(f'Bucket {bucketName} 创建成功')

6.4 上传文件（Python）

使用putFile方法上传本地文件：

bucketName = 'myapp-images'
objectKey = 'photos/2026/photo01.jpg'
localFilePath = '/path/to/local/photo.jpg'

resp = obsClient.putFile(bucketName, objectKey, localFilePath)
if resp.status < 300:
    print('上传成功，ETag:', resp.body.etag)
else:
    print('上传失败:', resp.errorCode)

单次上传对象大小范围为[0, 5GB]，超过5GB的大文件需要通过多段上传。Python SDK还支持流式上传，使用包含read属性的可读对象作为数据源。

6.5 下载文件（Python）

resp = obsClient.getObject(bucketName, objectKey, downloadPath='/path/to/download/photo.jpg')
if resp.status < 300:
    print('下载成功')
else:
    print('下载失败:', resp.errorCode)

6.6 生成签名URL（Python）

from obs import HttpMethod

resp = obsClient.createSignedUrl(method=HttpMethod.GET, bucketName=bucketName, objectKey=objectKey, expires=3600)
if resp.status < 300:
    print('临时URL:', resp.body.signUrl)
else:
    print('生成失败:', resp.errorCode)

7. 访问控制与安全配置

7.1 签名URL临时访问

对于私有Bucket中的文件，外部用户无法直接通过URL访问。最常用的解决方案是生成带签名的临时URL。签名URL的核心原理是：将访问凭证（AK/SK）和访问参数（如对象路径、过期时间）组合后进行签名，生成的URL在有效期内可以绕过权限校验直接访问对象。上述Java、PHP、Python的示例中均已包含生成签名URL的代码实现。

7.2 绑定自定义域名

使用OSS默认的桶域名（如myapp-images.obs.cn-north-4.myhuaweicloud.com）在业务推广中不够友好。华为云OSS支持为Bucket绑定自定义域名：

在OBS控制台进入目标桶的"域名管理"页面
点击"绑定用户域名"，输入你的自定义域名（如images.yourdomain.com）
在域名DNS服务商处添加CNAME记录，将自定义域名指向桶的默认域名

配置自定义域名时需要注意：OBS自定义域名配置暂不支持HTTPS访问，如需HTTPS协议访问，需要配合CDN服务进行HTTPS证书管理。

7.3 CDN加速配置

为已配置的自定义域名开启CDN加速后，即使OSS桶中的对象权限为私有，通过CDN也可以提供公共读访问。开启CDN加速的步骤：

在CDN控制台添加加速域名，源站类型选择"OSS域名"
CDN会自动将OSS作为回源站
开启CDN后，用户请求被调度至最近的边缘节点，大幅提升访问速度
CDN通常支持更高的并发带宽，适合大流量业务场景

7.4 IAM权限控制

默认情况下，新建的IAM用户没有任何权限。推荐使用IAM进行权限管理，配置方式如下：

创建用户组，为用户组设定IAM权限集
创建IAM用户，将用户加入用户组以获取相关权限
为不同部门或不同业务创建独立的IAM用户，实现权限隔离

IAM权限是作用于云资源的，定义了允许和拒绝的访问操作。通过IAM策略可以实现精细化权限控制，例如只允许某个子账号上传文件到指定Bucket的特定目录，而不能执行删除操作。

7.5 CORS配置与防盗链

如果OSS中的资源需要被Web前端直接访问（如通过Ajax上传图片），需要配置CORS（跨域资源共享）规则，允许来自特定域名的跨域请求。同时，为了防止其他网站盗用你的OSS资源，可以配置防盗链（Referer白名单），只允许来自你备案域名的请求访问资源。

8. 生命周期管理与成本优化

8.1 存储类别自动转换

通过OSS提供的生命周期功能，可以实现存储类别的自动转换，从而有效降低存储成本。标准存储的对象可以自动转换为低频访问存储、归档存储或深度归档存储。

配置生命周期规则时需要注意：

低频访问存储的最低存储时间为30天——如果对象在30天内转换为归档存储，需要补足剩余天数的低频存储费用
归档存储的最低存储时间为90天——如果对象在90天内转换为深度归档存储，需要补足剩余天数的归档存储费用
深度归档存储的最低存储时间为180天

生命周期规则的典型配置策略：

热数据（频繁访问）：标准存储，上传后30天内保持
温数据（偶尔访问）：连续45天无访问则自动转为低频访问存储，成本降低约65%
冷数据（几乎不访问）：90天无访问且容量大于1GB则转为深度归档存储，成本降低约85%

8.2 同区域ECS内网访问免流量

如果应用程序部署在华为云ECS上，且ECS与OSS位于同一区域，使用内网Endpoint访问OSS可以免去外网下行流量费用。例如，北京四的ECS访问北京四的OSS时，使用obs.cn-north-4.myhuaweicloud.com（内网地址）而不是公网地址，流量费用将为零。这是最直接有效的成本优化手段。

8.3 按量计费核心费用构成

华为云OSS默认为按需计费模式，按实际使用时长收费，以小时为单位结算，不设最低消费标准。核心费用由以下几部分构成：

存储费用：按不同存储类型和实际存储量及时间计算。标准存储约0.099元/月/GB起，低频访问存储约0.08元/月/GB起
请求费用：按所有类型的API请求次数计费，包括PUT/POST/COPY/LIST/GET/HEAD等
流量费用：通过互联网从OSS下载数据所产生的公网流出流量。内网流量和流入流量免费
数据恢复费用：恢复低频访问、归档或深度归档存储类别的对象时，按实际恢复数据量收费

成本优化建议：合理利用生命周期规则将冷数据自动转换为低频或归档存储，配合同区域ECS内网访问免流量策略，可以有效控制月度账单。

9. 常见问题解答

问1：AK/SK丢失了怎么办？

登录华为云控制台，进入"我的凭证" → "访问密钥"，可以禁用已泄露的密钥并重新生成新的访问密钥。Secret Access Key仅在生成时可见，请务必及时保存。

问2：上传文件时提示"桶不存在"怎么办？

检查桶名是否正确（注意大小写和特殊字符），确认桶所在的区域与Endpoint配置的区域一致。如果桶刚创建，可能需要等待几秒让配置生效。

问3：私有桶中的文件如何分享给他人？

使用签名URL（临时URL）是最安全的方式。可以设置URL的有效期（如1小时或24小时），将生成的URL分享给他人，过期后自动失效。

问4：如何监控OSS的使用量和费用？

在华为云控制台的"费用中心"可以查看详细的账单和用量统计。也可以开通云监控服务，设置告警规则，当存储量或流量超过阈值时及时收到通知。

问5：上传大文件（超过5GB）应该用什么方式？

需要使用分段上传（Multipart Upload）。将大文件分割成多个部分分别上传，全部上传完成后再合并。三种语言的SDK均支持分段上传接口。

问6：低频访问存储和归档存储的数据取回需要多久？

低频访问存储的数据取回通常实时（毫秒级）。归档存储的数据取回需要数分钟到数小时不等，具体取决于选择的恢复方式（加急或标准）。深度归档存储的恢复时间更长，一般为数小时。