文件存储与 Vault 复制

Aras Innovator 将业务对象与文件内容分开管理：Document、Part 等对象保存在数据库中， File Item 保存文件元数据，实际字节由 Vault 保存。理解这三层关系，是排查上传、下载和异地复制问题的起点。

适用版本

本文以 Release 30～37 的官方 File Handling、Vault OData 和 Vault Replication 文档为基线。 Release 39 项目应先在该版本文档库中复核菜单名称、部署方式与已知问题，再照本文实施。 旧版 11/12 的接口与当前版本可能不同，不要跨版本复制上传代码。

---

1. 先分清三个对象

对象	保存什么	不保存什么
业务容器	文档编号、版本、状态、责任人等业务信息	文件字节
File Item	文件名、大小、校验信息、所在 Vault 等元数据	业务审批语义
Vault	文件的物理内容	文档生命周期和业务关系

一个业务容器可以通过关系保存多个 File，也可以通过 Item 类型属性引用单个 File。 选择哪种方式取决于业务基数，而不是平台强制要求。

• 多附件、需要顺序或附件角色：使用关系 ItemType。
• 单一主文件、缩略图等固定槽位：使用指向 File 的 Item 属性。
• 需要版本、签审和发布：把这些规则放在业务容器上，不要把 File 当成完整文档模型。

不要绕过文件 API

不要直接写 Vault 目录、直接改 File 表，或手工拼接物理路径。 文件提交涉及权限、事务、校验和 Vault 选择，应使用目标版本支持的客户端文件 API、IOM 文件处理类或 Vault OData 接口。

---

2. 文件请求的职责边界

上图只表达职责，不是可直接实现的 HTTP 协议。 具体请求顺序、端点、分块方式和 token 结构必须以目标 Release 的 File Handling 或 Vault OData 文档为准。

下载时也不能只验证“知道 File ID”。Innovator 与 Vault 会结合当前会话、权限和授权信息决定能否取得内容。

---

3. Vault 选择与读取优先级

多 Vault 环境通常为不同地点或身份配置读取优先级。它解决的是：同一文件存在多个副本时，当前用户优先从哪个 Vault 获取。

配置时记录以下信息：

1. 用户所属 Identity。
2. 每个 Identity 的 Read Priority 顺序。
3. 文件当前实际存在的 Vault。
4. Vault 之间是否可连通。
5. 复制所需的 Agent Service 是否正常。

两个概念不要混用

Read Priority 决定“优先读哪里”；Replication Rule 决定“何时以及怎样产生副本”。 提高读取优先级不会自动把已有文件搬到该 Vault。

---

4. 三种复制触发器

复制规则的触发器有三种，名字相近但行为完全不同。

Trigger	触发时机	适合场景	关键限制
onDemand	用户请求获取文件，而优先 Vault 尚无副本时	节省异地存储，只缓存实际访问的文件	目标由最高读取优先级决定；规则中的 Target Vault 关系不用于该触发器
onChange	文件被上传、新增或内容发生变化时	希望文件变更后主动分发	需要明确目标 Vault，并评估上传后的复制负载
onEvent	Method 显式调用 File 的 replicate action 时	在审批、发布等业务事件中由代码控制复制	它不会因生命周期变化而自动触发

4.1 onEvent 的正确调用

服务器 Method 在业务条件满足后，可提交如下 AML：

<AML>
  <Item type="File"
        action="replicate"
        id="FILE_ID" />
</AML>

这段 AML 只是触发复制；实际目标、复制类型和执行模式仍由匹配的 Replication Rule 决定。

事务与外部副作用

不要把 OnAfterUpdate 描述成“数据库已经提交”。Server Event 的 OnAfter 仍处在服务器事务流程中，返回错误可导致回滚。 若复制触发必须与发布状态严格一致，应验证失败补偿、重试与幂等行为。

---

5. Trigger、Mode 与 Type 是三条轴

不要把触发器和执行模式写成同一个枚举。复制配置至少要分别回答以下问题：

• Trigger：onDemand、onChange 还是 onEvent？
• Mode：Immediate、Delayed、Scheduled 还是 Manual？
• Type：复制后保留源文件的 Copy，还是移动语义的 Move？
• Target：哪些 Vault 是目标？onDemand 的目标选择规则例外。

Immediate 会把等待时间放在当前操作路径上；Delayed 与 Scheduled 依赖后台执行能力；Manual 需要明确运维动作。 生产环境选型应同时测量文件大小、链路带宽、失败重试和用户可接受等待时间。

---

6. 配置前检查清单

6.1 基础设施

• 每个 Vault URL 可从对应网络区域访问。
• 服务账号对物理存储路径有正确权限。
• TLS 证书、主机名和代理配置一致。
• 需要后台复制时，Agent Service 已安装并正常运行。
• 时间同步正常，避免授权与日志时间难以关联。

6.2 元数据

• Vault 定义指向正确的服务与路径。
• Read Priority 针对测试 Identity 配置完成。
• Replication Rule 的 Trigger、Mode、Type 与目标均有评审记录。
• 文件类型或其他条件不会意外排除测试文件。
• 测试用户对业务容器与 File 都有必要权限。

---

7. 可复现实验：验证三种触发器

请在隔离环境使用一个小文本文件和两个 Vault，不要用生产 CAD 数据。

7.1 建立基线

1. 使用测试 Identity 登录。
2. 上传文件并记录 File ID、源 Vault、文件大小和时间。
3. 在两个 Vault 的受支持管理界面或日志中确认副本位置。
4. 保留 Replication Transaction 与 Agent 日志。

7.2 验证 onDemand

1. 仅让源 Vault 保存文件。
2. 为测试 Identity 把另一个 Vault 设为最高 Read Priority。
3. 下载该文件。
4. 验证下载成功，并确认目标 Vault 在请求后产生副本。
5. 再次下载，比较日志与响应时间。

7.3 验证 onChange

1. 建立只匹配测试文件的 onChange 规则。
2. 上传新版本或更改文件内容。
3. 按配置的 Mode 等待或启动后台任务。
4. 验证指定 Target Vault 的副本和事务状态。

7.4 验证 onEvent

1. 建立 onEvent 规则，但先不要调用 replicate。
2. 仅推进业务对象生命周期，确认不会凭空复制。
3. 用受控 Method 对测试 File 执行 action="replicate"。
4. 验证目标副本、重复调用结果与失败重试行为。

实验通过标准应写成证据：File ID、规则 ID、事务 ID、时间、源/目标 Vault 和最终状态。

---

8. 常见错误

把 onEvent 写成“上传或发布时自动触发”

上传或更改对应 onChange；onEvent 需要 Method 显式调用 replicate。

先创建 File，再用自制 HTTP POST 上传

这忽略了文件事务和目标版本协议。应使用官方支持的文件处理 API。

认为所有文件必须挂在 Document 下

Document 是常见业务容器，不是 File 的唯一合法关系。应按业务模型选择关系或属性引用。

认为读优先级会自动同步文件

读取顺序与复制规则相互配合，但不是同一配置。

直接比较 Vault 磁盘文件名

物理组织属于实现细节。诊断应以 File ID、官方日志和受支持接口为准。

---

9. 官方依据

• Adding a Replication Rule — Release 37
• Installing the Agent Service — Release 37
• Vault OData Interface — Release 28
• Aras Innovator Platform Documentation Library

文档最后核验：2026-08-13。升级后应重新执行第 7 节实验。