旧系统附件迁移到对象存储，先保持业务引用可追溯

不同附件需要不同的迁移与访问策略

适用边界：先确认为什么迁移，以及哪些文件不能动

这份方法适用于合同、图片、票据、导出报表等仍被业务记录引用的本地文件，目标是解除应用实例与磁盘目录的绑定。它不等同于数据库迁移，也不保证更换存储后自动提升上传速度、降低费用或满足合规要求。

先说明当前问题：多实例无法共享附件、服务器扩容困难、备份恢复不可验证，还是需要让小程序、APP 与 AI 智能体受控访问同一资料。不同目标决定是否需要 CDN、直传、内容扫描、归档层或跨区域复制。若文件受合同、隐私、行业留存或数据地域要求约束，应先由责任人确认存储区域、加密、日志与删除规则。

迁移前冻结随意改目录、改文件名和人工覆盖的操作。对正在处理中的临时文件、应用缓存、可再生成缩略图与正式原件分别标记；只有正式业务文件进入核心对账。无法确认归属的文件不能直接公开、删除或自动绑定给最近一条业务记录。

• 写清迁移目标、明确不在本次范围的缓存和临时文件。
• 记录存储、隐私、留存和删除要求的确认人。
• 先验证旧文件仍可备份和恢复，再开始批量复制。

用业务记录和文件系统双向盘点，建立迁移清单

只遍历目录会漏掉数据库中已经失联的附件记录，只查询数据库又会漏掉未登记文件。清单要从业务表到磁盘、再从磁盘反查业务表，区分已绑定、缺失、孤立、重复和损坏。

为每个候选文件记录稳定附件 ID、业务对象类型与主键、原路径、实际大小、最后修改时间、内容类型、可见范围和源端校验和。原始文件名用于展示，不直接作为对象键；重名、特殊字符、大小写与路径编码都可能在不同系统产生歧义。对象键可由环境、业务域、稳定 ID 和版本组成，但不要把姓名、手机号或合同标题等敏感信息放入键名。

盘点期间还要搜索代码、配置、模板、定时任务和数据库字段中的路径拼接逻辑。旧页面可能保存相对路径，APP 可能缓存完整域名，报表可能把服务器目录写入导出脚本。把每一种读写入口列入调用方清单，注明负责人和升级版本；目录复制完整，不代表这些调用方已经能够读取新位置。

• 对数据库记录与磁盘文件做双向差集并保留异常清单。
• 同名不同内容与同内容多副本分别识别，不按名称直接覆盖。
• 列全后台、小程序、APP、接口、任务和人工脚本中的文件入口。

让业务附件 ID 与实际存储位置解耦

业务表应引用稳定的附件标识，存储层再解析到桶、对象键、版本和状态。若页面永久保存带域名的完整 URL，后续换域名、换供应商或调整授权都会再次牵动业务数据。

可以建立附件元数据表或适配服务，至少保存附件 ID、所属业务记录、对象键、原始名称、大小、内容类型、校验算法和值、创建者、可见范围、迁移批次与验证状态。对于同一附件的原图、缩略图和转换版，明确派生关系，避免缩略图成功就把原件标为完成。对象键冲突时创建新版本或拒绝写入，不允许静默覆盖。

下载请求先使用附件 ID 查询元数据并校验当前业务权限，再由存储适配层读取本地文件或对象。这样双读期间能够保持上层接口稳定，也便于记录命中新存储、回退旧目录、文件缺失和授权拒绝等指标。对象存储产品的读取一致性与版本能力各不相同，应以所选产品和配置的官方说明及实测为准，不能把某一家服务的语义直接套到所有实现。

• 接口返回稳定附件 ID 或业务下载路由，不返回永久内部对象地址。
• 元数据显式记录存储状态、校验状态和迁移批次。
• 同一附件的原件与派生文件分别核验并保持关系。

迁移时重新验证上传、下载与公开边界

原来只有单台服务器能访问的目录，迁移后可能通过对象策略、CDN 或预签名地址触达。权限模型必须按业务重新验证，不能把“链接很难猜”当成访问控制。

公开素材与私有附件尽量分开存储和配置。私有下载先由应用核验登录状态、组织、角色及业务对象权限，再生成限定操作和有效期的访问入口；预签名地址在有效期内具有相应能力，应按临时凭证处理，避免进入分析参数、错误日志、聊天记录或长期数据库字段。若权限撤销需要立即生效，还要评估已经签发地址的剩余有效期与代理下载方案。

上传端限制允许的文件类型、大小、数量和业务归属，服务端重新识别内容并生成对象键。用户提供的名称只作为展示信息，不参与本地路径或对象策略计算。对需要恶意文件检测、图片解码或文档转换的场景，先进入隔离状态，扫描或转换完成后再标记可用；失败文件不能因为对象已经存在就出现在业务页面。

• 保持私有存储默认不公开，公开文件使用清晰分区与独立策略。
• 下载日志只记录附件 ID 和结果，不记录完整临时签名地址。
• 上传成功、内容可用和业务绑定采用不同状态，避免半成品被引用。

实施步骤：先接管新上传，再分批复制历史附件

先让所有新增与变更进入可追踪的新入口，才能得到稳定的历史迁移边界。批处理按可重入方式设计，同一文件重复执行不会生成不可解释的新对象，也不会覆盖已确认内容。

第一步，在非生产环境用脱敏样本验证上传、下载、权限、内容类型和异常处理。第二步，将生产新上传切换到对象存储，同时保存附件元数据；旧目录保持只读。第三步，按业务域、时间或租户生成历史清单，限速复制并记录每个对象的结果。第四步，对源端和目标端使用约定的完整内容校验算法，核对大小、校验和、对象状态与业务绑定，再将该附件标记为已验证。第五步，小比例启用新存储优先读取，观察后逐步扩大。

对象存储通常支持上传时或静态对象的校验能力，但实现和算法支持取决于产品、客户端与上传方式。以 Amazon S3 为例，官方说明可使用明确的校验算法验证上传与下载；分段上传后的 ETag 不应一概解释为整个文件的 MD5。项目应选定一致算法并把算法名称与值一同保存。抽样打开可以发现解析问题，但不能替代逐文件的机器校验和业务引用对账。

• 批处理支持断点续跑、限速、重试上限和逐文件结果导出。
• 复制失败不改源文件状态，重跑前能区分未处理与已验证。
• 每批先通过内容、元数据、业务引用和权限四类检查再放量。

验收与回滚：双读要可观察，旧目录要延迟退役

切换期由适配层优先读取已验证对象；对象未迁移、读取失败或校验状态不完整时，按规则回退旧目录并记录原因。回退次数必须可统计，否则表面可用会掩盖大量未完成迁移。

验收覆盖新上传、断点续传或大文件、同名文件、中文名称、历史下载、缩略图、权限撤销、过期临时地址、对象不可用和批处理重跑。按业务对象核对附件数量及关联，按文件核对大小和校验和，按角色核对允许与拒绝结果。再让小程序、APP、管理后台、导出任务和 AI 智能体使用同一批验收样例，证明各入口没有绕开权限或引用旧地址。

回滚方案应优先恢复旧读取和旧上传入口，而不是删除新对象。切换后的新增文件若只存在新存储，要有回写、批量导出或保持新读取能力的处置方式；否则所谓回滚会让新附件失联。观察期结束后仍要先生成最终差异报告，确认没有旧目录回退和未知写入，再按审批将旧目录转为归档或受控删除。备份、保留和删除分别验证，不把“对象复制成功”当成旧副本可以立即清理的依据。

• 监控新旧读取命中、回退原因、校验失败、拒绝访问与上传失败。
• 回滚演练覆盖切换后新增附件，而不只验证迁移前文件。
• 旧目录退役需要最终差异为零、恢复证据和明确批准。

需求讨论中的问题

关联服务与实施资料

下面的页面可继续核对相关技术边界、业务接入方式与项目交付条件。

• 旧系统历史数据迁移指南：将附件元数据与订单、客户等结构化数据纳入同一切换和对账计划。
• 旧接口版本兼容指南：让旧客户端继续使用稳定附件接口，逐步退出硬编码文件地址。
• AI Agent 智能体开发：为智能体读取合同和知识资料设置来源、权限、时效与审计边界。
• 小程序与 APP 一体化开发：统一多端上传下载、权限校验和失败提示，避免各端直连内部存储。
• 软件项目启动资料包：整理附件清单、接口责任、验收样例与交付边界。