---

每日一句正能量

今夜我们不谈跨过山海，只谈米香、灯火与团圆。

---

一、前言：为什么云存储是鸿蒙应用的"必选项"

在万物智联时代，用户的照片、视频、文档不再局限于单一设备。手机拍摄、平板修图、智慧屏展示——这种跨设备的无缝体验，背后依赖的核心能力正是云存储服务。传统自建存储方案需要开发者独立搭建对象存储、CDN加速、权限管控、数据备份等基础设施，开发和运维成本极高。而 HarmonyOS 通过 AppGallery Connect（AGC）云存储服务，将这一切能力打包为开箱即用的 SDK，让开发者可以像操作本地文件一样管理云端资源。

本文将从架构设计、核心 API 实战、断点续传、冲突解决、安全加固到性能调优，全面拆解鸿蒙云存储服务的企业级落地方案。无论你是刚接触端云一体化的初学者，还是希望优化现有方案的资深开发者，都能从中获得可落地的技术参考。

---

二、云存储服务架构全景

鸿蒙云存储服务采用端云一体化架构，通过 Cloud Foundation Kit 将端侧 ArkTS 代码与云侧 AGC 服务深度打通。整个技术栈可分为四层：端侧应用层、SDK 抽象层、云侧服务层和基础设施层。

图1：端云一体化云存储架构全景图

端侧层负责 UI 交互、本地缓存、离线队列和状态管理。当用户选择文件后，端侧通过 photoPicker 获取文件 URI，经业务逻辑层处理后交由数据访问层（DAO）执行上传或下载操作。SDK 层是开发者直接交互的核心，通过 cloudStorage.bucket() 获取存储桶实例，所有上传、下载、删除、元数据操作均围绕 StorageBucket 展开。云侧层提供对象存储、Serverless 云函数、文档数据库和统一认证服务，并通过声明式安全访问规则（Security Rules）实现细粒度权限控制。基础设施层则依托华为云全球 CDN、多副本冗余存储、弹性伸缩和 DDoS 防护，保障服务的高可用与低延迟。

与传统自建方案相比，AGC 云存储将开发效率提升约 80%，运维成本趋近于零，且支持按量付费的弹性计费模式，特别适合中小团队快速构建生产级应用。

---

三、环境配置与 SDK 初始化

3.1 开通服务与工程配置

在 AGC 控制台创建项目后，需完成以下配置：

1. 开通云存储服务：进入"我的项目 → 构建 → 云存储"，创建存储桶（Bucket）并选择区域（建议中国大陆选择 CHINA 节点）。
2. 配置安全规则：默认规则禁止所有访问，需根据业务场景配置读写权限（详见第六节）。
3. 下载配置文件：将 agconnect-services.json 放入端侧工程的 entry/src/main/resources/rawfile 目录。
4. 添加网络权限：在 module.json5 中声明：

"requestPermissions": [
  { "name": "ohos.permission.INTERNET" }
]

3.2 SDK 初始化与存储桶获取

云存储的核心入口是 StorageBucket，初始化流程如下：

// CloudStorageManager.ets
import { cloudCommon, cloudStorage } from '@kit.CloudFoundationKit';
import { request } from '@kit.BasicServicesKit';

export class CloudStorageManager {
  private static instance: CloudStorageManager;
  private bucketInstance: cloudStorage.StorageBucket | null = null;
  private readonly BUCKET_NAME = 'my-app-bucket';

  static getInstance(): CloudStorageManager {
    if (!CloudStorageManager.instance) {
      CloudStorageManager.instance = new CloudStorageManager();
    }
    return CloudStorageManager.instance;
  }

  private constructor() {
    this.initCloud();
  }

  private initCloud(): void {
    // 全局初始化：配置区域、超时、认证提供者
    cloudCommon.init({
      region: cloudCommon.CloudRegion.CHINA,
      functionOptions: {
        timeout: 10 * 1000  // 云函数超时 10 秒
      },
      authProvider: new HuaweiAuthProvider(), // 自定义认证提供者
      storageOptions: {
        mode: request.agent.Mode.FOREGROUND,  // 前台模式
        network: request.agent.Network.ANY     // 任意网络
      }
    });

    // 获取指定存储桶实例
    this.bucketInstance = cloudStorage.bucket(this.BUCKET_NAME);
  }

  getBucket(): cloudStorage.StorageBucket {
    if (!this.bucketInstance) {
      throw new Error('StorageBucket 未初始化');
    }
    return this.bucketInstance;
  }
}

// 自定义认证提供者（基于华为账号）
class HuaweiAuthProvider implements cloudCommon.AuthProvider {
  async getAccessToken(): Promise<string> {
    // 实际项目中通过 AccountKit 获取 AccessToken
    return 'Bearer ' + await AuthService.getToken();
  }
}

关键要点：

• CloudRegion.CHINA 指定中国大陆节点，可降低跨境延迟；
• storageOptions.mode 设为 FOREGROUND 表示前台上传/下载，若需后台传输可改为 BACKGROUND；
• 认证提供者（AuthProvider）负责 AccessToken 的获取与刷新，是安全访问的第一道闸门。

---

四、核心 API 实战：上传、下载、删除与元数据

图2：云存储核心API调用流程与生命周期管理

4.1 文件上传：从本地到云端

上传是云存储最高频的操作。以下示例展示了从文件选择到上传完成的完整流程，包含路径生成、元数据封装和进度监听：

// UploadService.ets
import { photoAccessHelper } from '@kit.MediaLibraryKit';
import { fileIo } from '@kit.CoreFileKit';
import { BusinessError } from '@kit.BasicServicesKit';

export class UploadService {
  private bucket = CloudStorageManager.getInstance().getBucket();

  /**
   * 选择图片并上传
   */
  async uploadImageFromPicker(): Promise<string> {
    // 1. 调用系统图库选择器
    const photoHelper = photoAccessHelper.getPhotoAccessHelper(getContext());
    const selection = await photoHelper.select({
      MIMEType: photoAccessHelper.PhotoViewMIMETypes.IMAGE_TYPE,
      maxSelectNumber: 1
    });

    if (selection.length === 0) {
      throw new Error('用户取消选择');
    }

    const uri = selection[0].uri;
    return this.uploadFile(uri, 'images/');
  }

  /**
   * 通用文件上传
   * @param localUri 本地文件 URI
   * @param cloudDir 云端目录前缀
   */
  async uploadFile(localUri: string, cloudDir: string = ''): Promise<string> {
    try {
      // 2. 读取本地文件信息
      const file = fileIo.openSync(localUri, fileIo.OpenMode.READ_ONLY);
      const stat = fileIo.statSync(file.fd);
      const fileName = localUri.substring(localUri.lastIndexOf('/') + 1);
      
      // 3. 生成云端唯一路径：目录 + UUID + 原始文件名
      const uniqueId = generateUUID();
      const cloudPath = `${cloudDir}${uniqueId}_${fileName}`;

      // 4. 封装元数据
      const metadata: cloudStorage.Metadata = {
        contentType: this.getMimeType(fileName),
        contentLength: stat.size,
        customMetadata: {
          'uploadTime': new Date().toISOString(),
          'deviceModel': deviceInfo.model,
          'appVersion': '1.0.0'
        }
      };

      // 5. 执行上传并监听进度
      const uploadTask = this.bucket.uploadFile(cloudPath, localUri, metadata);
      
      uploadTask.on('progress', (uploaded: number, total: number) => {
        const percent = Math.round((uploaded / total) * 100);
        AppStorage.setOrCreate('uploadProgress', percent);
        console.info(`上传进度: ${percent}%`);
      });

      uploadTask.on('complete', () => {
        console.info(`上传完成: ${cloudPath}`);
      });

      await uploadTask;
      fileIo.closeSync(file);
      
      return cloudPath;
    } catch (err) {
      const error = err as BusinessError;
      console.error(`上传失败: ${error.code} - ${error.message}`);
      throw error;
    }
  }

  private getMimeType(fileName: string): string {
    const ext = fileName.split('.').pop()?.toLowerCase();
    const mimeMap: Record<string, string> = {
      'jpg': 'image/jpeg', 'jpeg': 'image/jpeg', 'png': 'image/png',
      'gif': 'image/gif', 'mp4': 'video/mp4', 'pdf': 'application/pdf'
    };
    return mimeMap[ext || ''] || 'application/octet-stream';
  }
}

4.2 文件下载：预签名 URL 与本地写入

下载文件时，建议通过预签名 URL（Signed URL）实现临时访问，避免长期暴露存储桶权限：

// DownloadService.ets
export class DownloadService {
  private bucket = CloudStorageManager.getInstance().getBucket();

  /**
   * 下载文件到本地缓存目录
   */
  async downloadFile(cloudPath: string, localName?: string): Promise<string> {
    // 1. 生成本地保存路径
    const context = getContext();
    const cacheDir = context.cacheDir;
    const saveName = localName || cloudPath.split('/').pop() || 'download.tmp';
    const localPath = `${cacheDir}/${saveName}`;

    // 2. 执行下载并监听进度
    const downloadTask = this.bucket.downloadFile(cloudPath, localPath);
    
    downloadTask.on('progress', (downloaded: number, total: number) => {
      const percent = Math.round((downloaded / total) * 100);
      AppStorage.setOrCreate('downloadProgress', percent);
    });

    await downloadTask;
    return localPath;
  }

  /**
   * 获取文件的预签名访问 URL（有效期 1 小时）
   */
  async getSignedUrl(cloudPath: string, expireSeconds: number = 3600): Promise<string> {
    const url = await this.bucket.getDownloadURL(cloudPath, expireSeconds);
    return url;
  }
}

4.3 文件删除与级联清理

删除文件时，建议同步清理关联的元数据记录，可通过云函数实现级联删除：

// DeleteService.ets
export class DeleteService {
  private bucket = CloudStorageManager.getInstance().getBucket();

  async deleteFile(cloudPath: string): Promise<void> {
    // 1. 删除云端文件
    await this.bucket.deleteFile(cloudPath);
    
    // 2. 触发云函数清理关联数据（如数据库中的文件记录）
    await this.triggerCleanupCloudFunction(cloudPath);
    
    console.info(`文件已删除: ${cloudPath}`);
  }

  private async triggerCleanupCloudFunction(cloudPath: string): Promise<void> {
    // 通过 Cloud Function Kit 调用云函数
    const functionResult = await cloudFunction.call({
      name: 'cleanupFileMetadata',
      data: { filePath: cloudPath }
    });
    console.info('级联清理完成:', functionResult);
  }
}

---

五、断点续传与多设备冲突解决

图3：断点续传机制与多设备同步冲突解决方案

5.1 断点续传实现

在弱网环境或大文件传输场景下，断点续传是保障用户体验的关键。鸿蒙云存储 SDK 底层已支持分片上传（Multipart Upload），开发者只需合理配置分片大小和并发数：

// ResumeUploadService.ets
export class ResumeUploadService {
  private bucket = CloudStorageManager.getInstance().getBucket();
  private readonly CHUNK_SIZE = 2 * 1024 * 1024; // 2MB 分片

  async uploadWithResume(localUri: string, cloudPath: string): Promise<void> {
    const file = fileIo.openSync(localUri, fileIo.OpenMode.READ_ONLY);
    const stat = fileIo.statSync(file.fd);
    const totalSize = stat.size;
    
    // 查询已上传的分片列表（ETag + PartNumber）
    const uploadedParts = await this.bucket.listMultipartUploads(cloudPath);
    const uploadedSet = new Set(uploadedParts.map(p => p.partNumber));

    const totalChunks = Math.ceil(totalSize / this.CHUNK_SIZE);
    
    for (let i = 0; i < totalChunks; i++) {
      if (uploadedSet.has(i + 1)) {
        console.info(`分片 ${i + 1}/${totalChunks} 已上传，跳过`);
        continue;
      }

      const offset = i * this.CHUNK_SIZE;
      const length = Math.min(this.CHUNK_SIZE, totalSize - offset);
      
      // 读取分片数据
      const buffer = new ArrayBuffer(length);
      fileIo.readSync(file.fd, buffer, { offset, length });

      // 上传单个分片（带重试机制）
      await this.uploadPartWithRetry(cloudPath, i + 1, buffer);
      
      console.info(`分片 ${i + 1}/${totalChunks} 上传成功`);
    }

    // 合并分片并完成上传
    await this.bucket.completeMultipartUpload(cloudPath);
    fileIo.closeSync(file);
  }

  private async uploadPartWithRetry(
    cloudPath: string, 
    partNumber: number, 
    data: ArrayBuffer,
    maxRetry: number = 3
  ): Promise<void> {
    for (let attempt = 1; attempt <= maxRetry; attempt++) {
      try {
        await this.bucket.uploadPart(cloudPath, partNumber, data);
        return;
      } catch (err) {
        if (attempt === maxRetry) throw err;
        // 指数退避：1s, 2s, 4s
        await new Promise(r => setTimeout(r, Math.pow(2, attempt - 1) * 1000));
        console.warn(`分片 ${partNumber} 第 ${attempt} 次重试...`);
      }
    }
  }
}

5.2 多设备冲突解决

当用户在手机和平板上同时修改同一文件时，需通过版本向量时钟（Vector Clock）检测冲突并采取合并策略：

// ConflictResolver.ets
interface FileVersion {
  cloudPath: string;
  version: number;
  timestamp: number;
  deviceId: string;
  checksum: string;
}

export class ConflictResolver {
  /**
   * 冲突检测与解决
   */
  async resolveConflict(
    localVersion: FileVersion,
    remoteVersion: FileVersion
  ): Promise<'local' | 'remote' | 'merge' | 'user'> {
    // 策略1：时间戳优先（Last-Write-Wins）
    if (localVersion.timestamp !== remoteVersion.timestamp) {
      return localVersion.timestamp > remoteVersion.timestamp ? 'local' : 'remote';
    }

    // 策略2：版本号优先
    if (localVersion.version !== remoteVersion.version) {
      return localVersion.version > remoteVersion.version ? 'local' : 'remote';
    }

    // 策略3：校验和不同但时间戳相同，保留多版本供用户选择
    if (localVersion.checksum !== remoteVersion.checksum) {
      return 'user';
    }

    return 'local'; // 无实质冲突
  }

  /**
   * 保留多版本文件
   */
  async preserveBothVersions(
    cloudPath: string,
    localUri: string
  ): Promise<void> {
    const bucket = CloudStorageManager.getInstance().getBucket();
    
    // 将本地版本重命名后上传
    const versionedPath = cloudPath.replace(
      /(\.[^.]+)$/,
      `_conflict_${Date.now()}$1`
    );
    
    await bucket.uploadFile(versionedPath, localUri);
    console.info(`冲突版本已保留: ${versionedPath}`);
  }
}

---

六、安全访问规则与数据生命周期

图4：安全访问规则配置与数据全生命周期管理

6.1 声明式安全规则

AGC 云存储采用声明式安全规则（Security Rules），通过路径匹配和条件表达式控制访问权限。以下是一个典型的多场景规则配置：

// security-rules.json（AGC 控制台配置）
{
  "rules": {
    // 用户私有空间：仅认证用户可读写自己的目录
    "match": "/users/${auth.uid}/**",
    "allow": ["read", "write", "delete"],
    "condition": "auth != null && auth.uid == request.auth.uid"
  },
  {
    // 公共资源：任何人可读，仅管理员可写
    "match": "/public/**",
    "allow": ["read"],
    "condition": "true"
  },
  {
    // 共享文件：通过令牌临时访问
    "match": "/shared/${token}",
    "allow": ["read"],
    "condition": "request.time < resource.metadata.expireTime"
  },
  {
    // 管理员目录：仅管理员角色可访问
    "match": "/admin/**",
    "allow": ["read", "write", "delete"],
    "condition": "auth != null && auth.token.admin == true"
  }
}

规则设计原则：

1. 最小权限原则：默认拒绝所有访问，按需开放；
2. 动态变量绑定：利用 ${auth.uid} 实现用户隔离；
3. 时间窗口控制：共享链接通过 expireTime 限制有效期；
4. 元数据校验：结合 resource.metadata 实现更细粒度的条件判断。

6.2 数据全生命周期管理

云存储中的数据从上传到销毁，需经历完整的生命周期管理：

阶段	关键操作	技术要点
上传	文件校验、加密传输	客户端 MD5 校验 + HTTPS TLS 1.3
存储	多副本冗余、跨 AZ 容灾	3 副本存储 + 跨可用区部署
访问	CDN 加速、预签名 URL	边缘节点缓存 + 临时令牌
分享	令牌生成、有效期控制	共享令牌 + 过期自动失效
归档	低频存储、成本优化	自动生命周期策略转换存储类别
销毁	安全擦除、元数据清理	云函数级联删除 + 审计日志

---

七、性能优化与最佳实践

7.1 上传性能优化

1. 分片大小调优：2MB 是兼顾内存占用和并发效率的推荐值，大文件场景可适当增大至 5MB；
2. 并发控制：同时上传 3-5 个分片，避免过多线程导致网络拥塞；
3. 压缩预处理：图片上传前使用 ImageKit 进行质量压缩（建议 80%），视频使用分段转码；
4. 本地缓存索引：维护已上传文件的 cloudPath ↔ localUri 映射表，避免重复上传。

7.2 下载性能优化

1. CDN 预热：对于热点资源（如应用启动图、公共素材），通过 AGC 控制台预热 CDN 节点；
2. 本地缓存策略：使用 LRU 缓存管理下载文件，设置最大缓存容量（如 500MB）；
3. 懒加载与占位图：列表场景优先加载缩略图，点击后再下载原图。

7.3 成本控制

1. 存储类别转换：30 天未访问的文件自动转为低频存储，降低 40% 存储成本；
2. 生命周期规则：设置自动删除过期临时文件（如缓存目录 /temp/** 7 天自动清理）；
3. 流量监控：通过 AGC 监控面板实时跟踪上传/下载流量，设置用量告警阈值。

---

八、完整实战：相册云备份组件

以下是一个完整的相册云备份组件，集成上传、下载、删除和进度展示：

// CloudAlbum.ets
@Component
export struct CloudAlbum {
  @State uploadProgress: number = 0;
  @State downloadProgress: number = 0;
  @State fileList: string[] = [];

  private uploadService = new UploadService();
  private downloadService = new DownloadService();
  private deleteService = new DeleteService();

  build() {
    Column({ space: 16 }) {
      Text('云端相册').fontSize(24).fontWeight(FontWeight.Bold)

      Button('选择并上传')
        .onClick(async () => {
          try {
            const cloudPath = await this.uploadService.uploadImageFromPicker();
            this.fileList.push(cloudPath);
          } catch (e) {
            promptAction.showToast({ message: '上传失败: ' + e.message });
          }
        })

      if (this.uploadProgress > 0 && this.uploadProgress < 100) {
        Progress({ value: this.uploadProgress, total: 100, type: ProgressType.Ring })
          .width(80)
        Text(`上传中 ${this.uploadProgress}%`).fontSize(12).fontColor('#666')
      }

      List() {
        ForEach(this.fileList, (path: string) => {
          ListItem() {
            Row() {
              Text(path.split('/').pop()).layoutWeight(1)
              Button('下载')
                .onClick(async () => {
                  const localPath = await this.downloadService.downloadFile(path);
                  promptAction.showToast({ message: '已保存至: ' + localPath });
                })
              Button('删除')
                .fontColor(Color.Red)
                .onClick(async () => {
                  await this.deleteService.deleteFile(path);
                  this.fileList = this.fileList.filter(p => p !== path);
                })
            }
            .width('100%')
            .padding(12)
          }
        })
      }
      .width('100%')
      .height(300)
    }
    .padding(16)
    .width('100%')
  }
}

---

九、总结

鸿蒙云存储服务通过端云一体化架构，将对象存储、CDN 加速、安全管控和 Serverless 计算整合为统一的开发体验。本文从 SDK 初始化、核心 API 实战、断点续传、冲突解决、安全规则到性能优化，构建了一套完整的企业级文件管理方案。

核心要点回顾：

• 使用 cloudCommon.init() 完成全局配置，cloudStorage.bucket() 获取存储桶实例；
• 上传时封装 Metadata 并监听 progress 事件实现进度反馈；
• 下载时优先使用 getDownloadURL() 生成预签名 URL，避免长期暴露权限；
• 大文件采用分片上传 + 断点续传，配合指数退避重试机制提升成功率；
• 多设备冲突通过向量时钟检测，支持自动合并和用户仲裁两种策略；
• 安全规则遵循最小权限原则，利用 ${auth.uid} 实现用户目录隔离。

随着 HarmonyOS 生态的持续演进，云存储服务将进一步与分布式数据管理、AI 智能分类等能力深度融合。期待开发者们基于本文方案，构建出更多创新的全场景应用。

---

转载自：https://blog.csdn.net/u014727709/article/details/163832419
欢迎 👍点赞✍评论⭐收藏，欢迎指正