Misery-photo

Appearance

版本迁移指南 ​

本页用于记录重要版本变更、兼容性影响与升级步骤。

适用范围 ​

  • 从旧版本升级到当前 main。
  • 从单桶配置迁移到多桶 KV 持久化配置。
  • 从图片-only 流程迁移到图片+视频混合流程。

近期关键变更 ​

0) v1.0.3 大文件分片上传上线 ​

影响：

  • 上传链路新增 multipart 分片模式，适配大文件与弱网场景。
  • 默认策略：单文件 >= 64MB 走分片（32MB 分片、分片并发 3、大文件场景文件并发 1）。
  • 每片失败支持最多 3 次指数退避重试。
  • 当仍有失败分片时，支持继续失败分片、保存会话稍后继续、放弃并 abort 清理。
  • 新增服务端分片控制接口：/api/upload/multipart。

升级动作：

  1. 校验对象存储 CORS 是否暴露 ETag。
  2. 校验大文件上传失败后的三种动作：继续、保存、放弃清理。
  3. 校验 abort 后未完成分片不再保留。
  4. 若有反向代理/CDN，校验其请求体限制与超时策略。

1) v1.0.2 类型治理与加载优化 ​

影响：

  • 核心页面与关键 API 路由清理 any，统一改为显式类型和 unknown 错误收敛。
  • 新增统一错误工具，减少不同模块的错误处理分叉。
  • JSZip 改为按需动态加载，非 ZIP 场景不再承担对应首屏负担。
  • 构建与静态检查基线收敛为：npm run build 通过、eslint src 无报错。

升级动作：

  1. 回归验证上传 ZIP 解析流程（首次触发会动态加载 JSZip）。
  2. 回归验证下载打包流程（确保动态加载后可正常导出）。
  3. 回归验证登录、桶切换、批量操作与删除接口错误提示行为。
  4. 确认 CI 或部署流程继续执行 npm run build 作为发布前门禁。

2) v1.0.1 传输中心体验升级 ​

影响：

  • 上传与下载统一为可收起的传输中心交互。
  • 支持圆形悬浮窗收起/展开与玻璃态动画。
  • 新增总体进度、当前处理文件、单文件进度、实时速度展示。
  • 传输速度单位自动切换：默认 MB/s，低于 1 MB/s 显示 KB/s。

升级动作：

  1. 验证上传任务可收起到悬浮窗后继续进行。
  2. 验证下载任务可收起到悬浮窗后继续进行。
  3. 验证上传/下载任务面板中的单文件进度与速度显示是否正常。
  4. 验证取消下载后面板状态可正确清理。

3) 多桶配置迁移到服务端 KV ​

影响：

  • 桶配置不再只依赖本地或单环境变量。
  • 需要正确配置 BUCKET_STORE_PROVIDER 与对应 KV 变量。

升级动作：

  1. 在目标环境配置 KV 连接变量。
  2. 设置 BUCKET_ENCRYPTION_KEY。
  3. 登录后台重新校验并保存桶配置。

4) 默认桶策略调整 ​

影响：

  • 默认桶可作为兜底可见入口。
  • 默认桶通常不可删除。

升级动作：

  1. 确认默认桶是否符合当前业务预期。
  2. 在设置中切换激活桶并验证列表数据。

5) 视频能力接入 ​

影响：

  • 列表支持视频类型。
  • 上传与 ZIP 导入支持视频媒体。

升级动作：

  1. 验证视频上传、播放、删除流程。
  2. 如使用 m3u8，确保分片文件可访问。

升级前检查清单 ​

  • 备份当前环境变量。
  • 记录当前可用桶配置。
  • 准备回滚版本号。

升级后回归清单 ​

  1. 登录与登出。
  2. 桶列表读取、保存、切换。
  3. 图片上传、视频上传、ZIP 导入。
  4. 批量复制/移动/删除。
  5. 下载与代理访问。

常见迁移问题 ​

升级后桶读取失败 ​

  • 多数是 BUCKET_ENCRYPTION_KEY 变更导致旧密文不可读。

升级后某些接口 401 ​

  • 检查 AUTH_SECRET 是否丢失或被替换。

升级后部署通过但行为异常 ​

  • 优先核对 Preview/Production 环境变量是否一致。

回滚建议 ​

  • 使用上一个稳定提交重新部署。
  • 回滚后不要立即覆盖当前 KV 数据，先确认兼容性。
  • 回滚成功后再制定下一次迁移计划。