本章说明部署符合性如何证明“部署的是什么、如何构建、依赖是否就绪、业务是否可用以及失败如何回退”。OpenAgenet (OAN) 的节点服务、网站后端和前端静态资源应分别记录源码提交、构建产物、配置版本和验收证据；官方部署值用于说明一个可运行实例，协议要求则适用于所有声称符合规范的实现。

20.1 参考部署拓扑

参考拓扑由根平台、注册服务节点、发现服务节点、内容分发平台、链下信任索引器、数据库和官网组成。对外只暴露经过 TLS 和反向代理保护的必要入口，节点间使用配置的服务地址和授权材料通信；第三方节点可以独立部署，但必须通过节点身份、授权、接口和同步符合性检查。

flowchart LR
  A[资源提供方] --> B[注册服务节点]
  B --> C[根平台]
  C --> D[内容分发平台]
  D --> E[发现服务节点]
  C --> F[链下信任索引器]
  E --> G[官网或客户端]
  H[(数据库)] --- B
  H --- C
  H --- E

部署拓扑应把公网入口、内部服务、数据库和治理数据源分开标识；公开地址、端口和节点数量属于环境配置，不应被图示固化为协议必需项。

部署时可以按“公网入口、业务服务、状态存储、治理与同步”四个边界核对：官网和反向代理属于访问入口，节点服务承载注册、发布、分发或发现流程，数据库保存各自的运行状态，链下信任索引器读取治理事件并形成读模型。边界的具体主机和端口可以因环境变化，但每条跨边界连接都应能说明发起方、目标方、用途、认证材料和失败后的影响。

20.2 配置与秘密管理

配置按环境注入，代码包不携带生产私钥、数据库凭据或外部服务令牌。节点 DID 私钥、根平台授权材料、数据库连接信息、链上包或对象配置、发现和分发端点应限制文件权限并单独备份；启动前校验必填项，轮换时保留旧新配置的审计记录。启动前失败项应阻止服务进入就绪状态；配置轮换应记录旧配置失效时间、新配置生效时间和验证结果。

配置检查可用以下最小记录作为发布前证据；值只表示存在和是否通过校验，不把秘密写入报告：

profile=production
service=oan-homepage-backend
OAN_HOMEPAGE_LISTEN_ADDR=present:valid
OAN_OFFICIAL_ROOT_ENDPOINT=present:https
OAN_OFFICIAL_REGISTRAR_ENDPOINT=present:https
OAN_OFFICIAL_DISCOVERY_ENDPOINT=present:https
database=present:connected
node_identity=present:did-public-key-match
secrets=not-printed

若必填端点、数据库、节点身份或治理配置无法校验，应停留在配置阶段，不应继续通过启动成功或页面可访问来掩盖缺项。

20.3 构建与发布产物

发布记录至少包含源代码版本、锁文件、Rust 和前端构建环境、构建步骤、产物哈希、配置版本和发布时间。部署可采用版本化源码包或等效方式同步已确认版本，在目标构建环境中生成 Rust 后端和前端静态资源；源码包、二进制、静态资源和配置应能相互对应。发布前应形成“源代码版本 → 构建 → 产物 → 部署”的可追溯链；目标环境中的临时源码修改或未记录的构建目录不能作为正式来源。

发布记录可以用一个不含秘密的摘要描述产物之间的对应关系：

{
  "sourceCommit": "<git-commit>",
  "lockfile": "<lockfile-sha256>",
  "backendArtifact": "<backend-sha256>",
  "frontendArtifact": "<frontend-sha256>",
  "configFingerprint": "<config-fingerprint>",
  "builtAt": "<utc-time>",
  "environment": "<profile>"
}

尖括号中的内容是记录模板，不是 OAN 官方固定值。实际发布时应替换为真实摘要，并把源码归档、构建日志、产物哈希和服务器部署记录放在同一验收记录中。

20.4 数据库与存储要求

部署前确认数据库版本、连接、迁移和索引状态，迁移必须幂等、可记录并先备份。存储应覆盖资源登记、版本、凭证关联、发布任务、同步游标、治理事件和统计所需数据；恢复后检查关键记录、序列连续性、队列状态和索引一致性，不能只检查进程启动。

数据库验收应将“能连接”“迁移完成”“数据可用”和“恢复后仍一致”分别记录。重点核对资源 DID 与版本的唯一性、发布任务的幂等键、发现索引所需记录、治理事件与同步游标的连续性；迁移完成但关键索引缺失时，服务不应进入可写就绪状态。数据库检查不应通过官网公开接口返回内部表结构，报告中只保留必要的版本、计数、摘要和校验结果。

20.5 TLS、域名、反向代理与网络暴露

域名和 TLS 终止点应与实际服务入口一致，反向代理只转发必要路径并保留正确的 Host、协议和客户端关联信息。公开端口、跨域来源、防火墙和节点间访问规则应按环境配置；数据库、管理接口和内部队列不得因网站代理配置而暴露给普通互联网用户。验收时应分别从公网和内部网络检查允许路径、证书主机名、HTTP 到 HTTPS 跳转、CORS 范围和非公开路径的拒绝结果。

20.6 部署顺序与依赖检查

推荐顺序是记录基线、备份和同步代码，构建产物，准备数据库，启动根平台及依赖服务，再启动注册、分发、发现和索引器，最后部署官网并执行业务烟测。任一必需依赖、迁移、健康检查或关键烟测失败，都应停在当前步骤，保留证据并进入修复或回滚。每个步骤的通过条件应由下一步骤实际需要的依赖来定义，不能只以服务进程已启动作为放行条件。

20.6.1 代码同步与构建

以明确的源代码版本生成归档包或等效发布包，传送到目标构建环境后校验文件和版本信息。按项目锁定的 Rust 依赖编译节点服务，按前端构建脚本生成静态资源和后端产物；不从工作区临时文件或未记录的本地构建目录发布。

20.6.2 数据库准备

确认备份可恢复、数据库可连接、迁移版本和必需索引正确，再执行幂等迁移或启动校验。迁移失败不得启动会写入新数据的服务；需要人工处理时保存失败日志、数据库版本和恢复点。

20.6.3 节点启动顺序

先启动根平台及其数据库和发布依赖，再启动注册服务节点、内容分发平台、发现服务节点和链下信任索引器。实际顺序可按部署拓扑调整，但下游启动前必须确认上游地址、身份、授权和接口已就绪，避免以进程存在代替依赖可用。

20.6.4 服务健康检查

逐一检查进程存活、就绪接口、关键依赖和配置加载结果，并记录响应码、耗时、版本和时间。检查通过不代表业务路径通过，尤其要分别验证根平台发布、注册受理、发现查询、分发和索引同步。

20.6.5 部署后功能验证

部署后功能验证至少覆盖：

1. 健康和就绪接口。
2. 注册服务节点的合法请求与预期失败请求。
3. 根平台发布、内容分发和发现服务节点同步。
4. DID 精确查询和语义查询。
5. 数据库迁移状态、游标、日志和告警。

任一关键项失败时保留提交、产物、配置和响应证据，并停止发布完成确认。

接口验证应同时记录请求方法、实际 URL、HTTP 状态、响应类型、关键业务字段和关联标识。对于动态 JSON 接口，不能只检查响应为 2xx，还要检查注册响应是否包含资源 DID 和登记状态、根平台响应是否为 resource-verified-and-queued、内容分发响应是否包含发布游标、发现响应是否可反序列化为 ResourceDiscoveryResponse，以及索引器状态是否能说明当前同步位置。浏览器经官网代理访问时，还应额外验证代理路径与节点原始路径的映射没有改变请求体或错误语义。

20.7 注册节点功能烟测

使用隔离测试身份和受控资源验证表单或请求校验、控制签名、注册服务节点受理、重复提交和错误响应。若接口返回注册 VC，检查 VC 与资源 DID、版本或摘要的关联；测试资源的后续发布和清理不得污染正常资源统计。注册成功只证明注册服务节点完成受理，不自动证明根平台已经发布或发现服务节点已经索引。

20.8 发现节点功能烟测

对已发布的隔离测试资源执行 DID 精确查询和语义查询，核对 DID、资源类型、版本、状态、来源、根平台可信发布证明状态和索引时间。查询结果为空、返回旧版本或接口失败时，应结合游标和发布记录判断是传播延迟还是功能故障。语义查询的通过条件是返回可解释的候选和来源，不是要求某个固定排序或未经定义的相关性分数。

20.9 根平台、分发与索引器验证

分别检查根平台的发布状态、内容分发平台的资源或游标记录、链下信任索引器的同步状态和发现节点的索引结果。每一项检查都要给出来源、时间和正常判据；只看到根平台成功不能证明下游已经可发现。应使用同一个隔离资源版本贯穿核对，并记录根平台发布序列、分发摘要、索引版本和查询结果，避免以各接口的总数量相等替代内容一致性检查。

20.10 治理同步验证

选取可确认的治理事件，核对链上位置、事件类型、信任索引器游标、节点状态读模型和更新时间。连续两次或多次检查中游标和 latest_sequence 的关系应符合部署环境的同步状态；无新事件与同步停止必须区分。治理事件已被读取但投影未更新时，应判为同步链路未完成，而不是仅凭索引器接口响应成功放行。

20.11 升级、回滚与兼容性检查

升级前后检查数据库迁移、协议版本、资源模式、历史版本、节点互操作和回滚路径。升级只在兼容性和备份条件满足时继续；若新产物无法通过健康或业务验证，应按记录的版本和配置回退，并重新执行关键验收。升级验证应使用代表性的资源 DID、资源包、注册请求和发现查询，而不只验证服务能启动。

20.11.1 升级前检查

记录当前软件版本、二进制哈希、配置、数据库和游标状态，确认备份可读、目标版本可构建、迁移可回退或可恢复，并确认旧版本仍可取得。

20.11.2 数据和配置兼容

核对新增字段、资源包和凭证结构、协议路由、环境变量、节点授权材料及前端接口期望。兼容转换应可重复执行；不能兼容的历史数据必须在发布前停止，而不能在运行中静默丢弃。

20.11.3 回滚条件

出现数据库迁移失败、关键健康检查失败、注册或发现烟测失败、发布队列异常、索引持续停滞或安全配置错误时触发回滚评估。涉及不可逆数据迁移时先暂停写入并按恢复方案处理，不能只替换二进制。

20.11.4 回滚后验证

回滚后重新检查服务版本、配置、数据库记录、节点身份、发布序列和同步游标，再执行健康、注册、发现、根平台、分发和索引验证。只有旧版本恢复到可证明状态，才能结束回滚。

20.12 第三方节点接入与符合性测试

第三方节点应提交节点身份、授权材料、公开端点、支持的接口和环境信息，并通过签名验证、授权检查、协议响应、资源发布、同步、查询、安全边界和故障恢复测试。通过测试只授予明确范围内的接入资格，不替代后续运行监测和治理管理。准入报告应明确节点角色、授权域、接口版本、测试环境和有效期；未测试的角色、域或接口不能由其它通过项推定为合格。

第三方节点的最低验收证据可以按以下顺序组织：

node identity -> authorization -> protocol response
              -> controlled registration/publication
              -> synchronization/discovery
              -> failure recovery and evidence review

测试应优先在独立数据库和隔离端点中完成。节点能够调用接口不等于获得授权，能够同步数据也不等于可以发布资源；每一项结论都应绑定实际测试范围和证据。

20.13 构建可复现性与发布来源证明

构建记录应能从提交和锁文件追溯到产物，至少保存构建环境、命令、依赖版本、产物哈希和操作者。服务器上的运行二进制、前端静态资源和源码归档应能相互核验；配置和秘密不纳入公开产物哈希，但应记录其版本或指纹。对于 Rust 后端和官网前端，应分别保存构建结果，再在部署记录中说明二者如何组合为同一发布批次。

20.14 环境特定配置文件

开发、测试、预发布和生产环境使用独立 profile、端点、数据库和密钥，禁止把测试授权材料或生产私钥交叉复用。配置变更应有提交、审批或操作记录；同一代码在不同环境的差异应集中在配置，而不应通过未记录的手工改源码实现。验收时应核对当前 profile 与端点、数据库、节点身份和治理对象相互匹配，避免将测试环境的“通过”误写为生产环境通过。

20.15 部署后功能与安全验证

验收记录汇总版本、环境、配置、健康接口、业务烟测、数据库、治理同步、权限、TLS、公开端口和日志检查结果。还应确认私钥未进入日志或公开接口、管理数据未暴露给普通用户、错误响应未泄露秘密，并保留可复核的命令输出或接口响应摘要。最终结论应明确覆盖范围、证据时间、未覆盖项目和是否允许对外提供服务；任何关键项为 FAIL 或结果不确定时，不应写成整体通过。

参考来源