第41章 文件上传
文件上传 本文档描述 Cloudreve 中的文件上传流程。上传流程因存储策略类型而异，但通常遵循以下三个步骤：
概述 完整的文件上传包含三个步骤： 1. 创建上传会话：向 Cloudreve 服务器请求上传会话。 2. 上传分片：将文件数据以分块形式上传至存储提供商。 3. 完成上传：最终确认上传（部分存储策略需要此步骤）。
对于小文件，建议直接调用“更新文件内容” API，以简化为单次请求的上传流程。
步骤 1：创建上传会话 调用“创建上传会话” API 以启动上传。响应中包括： * session_id：此次上传会话的唯一标识符 * chunk_size：每个分片的大小（字节） * upload_urls：用于上传分块的预签名 URL（因存储策略而异） * credential：分块上传的认证凭据 * expires：会话过期时间戳 * storage_policy：存储策略配置，包含： * policy_type：存储提供商类型 * chunk_concurrency：允许的最大并发分片上传数 * streaming_encryption：是否支持流式加密 * encrypt_metadata：加密参数（若启用了客户端加密）
步骤 2：上传分片 分片上传方法取决于存储策略类型：
本地/远程存储策略 针对本地存储，或 storage_policy.relay 设为 true 的任意存储策略，请使用“上传文件分片” API。 对于远程（从节点）存储，请将分片发送至 upload_urls 中的 URL（单一元素）。请求格式与本地分片上传相似，区别如下： * 分片索引通过查询参数 chunk 传递，例如：http://slave.example.com/api/v4/slave/upload/{session_id}?chunk=2 * Authorization 头使用上传会话中返回的 credential 值，例如：Bearer Cr sBnnQ3rZ-UBr7d8ohKpUFtsQc8OMLuWwn1VhuJtdc5k=:1749623351
S3 兼容存储策略 对于 S3、OSS、COS、OBS 和 KS3 存储策略，请使用 upload_urls 中的预签名 URL（每个分片对应一个 URL）。请查阅相应云提供商的多部分上传文档： * S3: UploadPart * OSS: UploadPart * COS: UploadPart * OBS: Uploading Parts * KS3: 使用与 S3 相同的 API
OneDrive 对于 OneDrive 存储策略，请使用 upload_urls 中的上传 URL 并附带字节范围头。请参阅 Microsoft 的“上传字节到上传会话”文档。
七牛 对于七牛存储策略，请参阅其“上传分片”文档。
又拍云 对于又拍云存储策略，请参阅其“大文件上传”文档。
步骤 3：完成上传 完成步骤因存储策略而异：
| 存储策略 | 完成方式 | | :--- | :--- | | 本地 / 远程 / 又拍云 | 自动完成 - 最后一个分片上传后无需额外操作 | | OneDrive | 调用 OneDrive 上传完成接口 | | S3 / KS3 | 调用 CompleteMultipartUpload，然后调用 S3 上传完成回调 | | OSS | 调用 CompleteMultipartUpload（回调由系统自动处理） | | COS | 调用 Complete Multipart Upload，然后调用 COS 上传完成回调 | | OBS | 调用 Completing a Multipart Upload，然后调用 OBS 上传完成回调 | | 七牛 | 调用 Complete Multipart Upload |
分片上传 文件根据上传会话返回的 chunk_size 拆分为多个分片。存储策略中的 chunk_concurrency 字段指定了可同时上传的分片数量。
客户端加密 当服务器启用文件加密时，上传会话响应中将包含 encrypt_metadata，其字段如下： * cipher：加密算法（例如 aes-256-ctr） * key_plain_text：Base64 编码的加密密钥 * iv：Base64 编码的初始化向量
客户端应在上传前使用 AES-256-CTR 模式对文件数据进行加密。在使用流式加密时，分片边界无需与 AES 块边界对齐——请根据每个分片在文件中的字节位置计算正确的计数器偏移量。
参考实现 如需完整的实现参考，请参阅： * Web: frontend/src/component/Uploader/core/uploader * Desktop: desktop/crates/cloudreve-sync/src/uploader
