openai的业务架构 openapi开放平台架构

目录

背景和价值

开发架构介绍

开放架构图

OpenAPI

应用账号体系

OAuth 2.0认证

RESTful API

AsyncAPI 2.0

插件系统

服务端插件原理和应用

认证同步插件

 消息插件

 Web插件原理和应用

Web客户端插件

 Web组件

内容处理框架

杀毒原理和应用

加解密原理和应用

---

---

背景和价值

为何要做开放性架构，因为AnyShare Family 7 定位于非结构化数据中台，势必需要强大的平台能力，通过这个平台为上层业务系统，提供强大的内容处理、内容统一存储等能力。

开发架构介绍

开放架构图

OpenAPI

OpenAPI 规范（OAS），是定义一个标准的、与具体编程语言无关的RESTful API的规范。OpenAPI 规范使得人类和计算机都能在“不接触任何程序源代码和文档、不监控网络通信”的情况下理解一个服务的作用。如果您在定义您的 API 时做的很好，那么使用 API 的人就能非常轻松地理解您提供的 API 并与之交互了。

如果您遵循 OpenAPI 规范来定义您的 API，那么您就可以用文档生成工具来展示您的 API，用代码生成工具来自动生成各种编程语言的服务器端和客户端的代码，用自动测试工具进行测试等等。

OpenAPI 3.0.0 是 OpenAPI 规范的第一个正式版本，因为它是由 SmartBear Software 捐赠给 OpenAPI Initiative，并在2015年从 Swagger 规范重命名为 OpenAPI 规范。

应用账号体系

OAuth 2.0认证

提到OAuth ，就需要了解互联网的鉴权体系。为了防止张三访问李四的资源，我们需要认证（authentication），即鉴定谁在访问；为了防止资源被没有权限的人访问，我们需要授权（authorization），即确定访问者能否访问当前资源。需要注意的是，为了保护访问者信息，授权协议可以在传递信息时隐藏访问者。

OAuth是鉴权协议的一种，有OAuth 1.0和OAuth 2.0两个版本，1.0版本因设计过于复杂很少使用，我们提到OAuth一般指OAuth 2.0。

OAuth 2.0得到广泛应用主要得益于三个特点：

• 简单：不管是Oauth服务提供者还是应用开发者，都很易于理解与使用；
• 安全：没有涉及到用户密钥等信息，更安全更灵活；
• 开放：任何服务提供商都可以实现Oauth，任何软件开发商都可以使用Oauth；

OAuth 2.0的核心：访问令牌

在现实生活中，我们通常会通过委托书委托他人帮助我们做一些事。在计算机世界中，访问受OAuth2.0 授权协议保护的 API，也是类似的场景：用户通过访问令牌授权客户端软件访问自己的资源（API）。访问令牌即类似现实生活中的委托书，包含 3 要素：谁（资源拥有者）委托（授权）谁（客户端）做什么事情（scope）。常用的访问令牌获取流程如下：

 

• 客户端首先将资源拥有者引导至授权服务器，请求资源拥有者为其授权。
• 授权服务器先对资源拥有者进行身份认证，此时资源拥有者的凭据不会暴露给客户端。
• 然后资源拥有者选择是否对客户端授权，客户端可以请求授权范围（scope）的子集，该子集可能会被资源拥有者进一步缩小。
• 授权请求被许可后，客户端向授权服务器请求访问令牌（具有受限访问权限的凭据）。
• 最后，客户端使用访问令牌代表资源拥有者以有限的权限对受保护资源上的 API 进行访问。

RESTful API

表征状态传输 (REST) 是一种软件架构，决定了 API 的工作条件。REST 最初作为管理复杂网络（例如互联网）上的通信的指南而建立。您可以使用基于 REST 的架构为高性能和可靠的大规模通信提供支持。您可以轻松应用和修改此种架构，为任何 API 系统带来可见性和跨平台可能性。

API 开发人员可以使用多种不同的架构设计 API。遵循 REST 架构风格的 API 称为 REST API。实施 REST 架构的 Web 服务称为 RESTful Web 服务。术语 RESTful API 通常指 RESTful Web API。但是，术语 REST API 和 RESTful API 可以互换使用。

以下是 REST 架构风格的一些原则：

统一接口

统一接口是一切 RESTful Web 服务设计的基础。其表示服务器以标准格式传输信息。格式化的资源在 REST 中称为表征。此格式可以与服务器应用程序上资源的内部表征不同。例如，服务器可以将数据存储为文本，但以 HTML 表征格式发送该数据。

统一接口强制实施四个架构约束：

1. 请求应确定资源。它们通过使用统一的资源标识符实现此功能。
2. 客户端包含资源表征中的足够信息以修改或删除资源（如需要）。服务器通过发送进一步描述资源的元数据以符合这一条件。
3. 客户端接收有关如何进一步处理表征的信息。服务器通过发送自描述信息实现此功能，该信息包含了有关客户端如何以最佳方式使用这些信息的元数据。
4. 客户端接收有关其完成任务需要的所有其他相关资源的信息。服务器通过在表征中发送超链接实现此功能，以便客户端可以动态发现更多资源。

无状态

在 REST 架构中，无状态指一种服务器独立于所有之前的请求完成每个客户端请求的通信方法。客户端可以以任意顺序请求资源，每个请求为无状态或与独立于其他请求。此 REST API 设计约束意味着服务器每次可以完全识别和满足请求。

层次化系统

在层次化系统架构中，客户端可以连接到客户端和服务器之间的其他授权中间方，其仍将接收来自服务器的响应。服务器也可以将请求传递到其他服务器。您可以将 RESTful Web 服务设计为在包含多个层级（例如安全、应用程序和业务逻辑）的数个服务器上运行，从而共同满足客户端请求。这些层级对客户端仍不可见。

高速缓存能力

RESTful Web 服务支持缓存，缓存是指将一些响应存储在客户端或中间方上以提高服务器响应时间的流程。例如，假设您访问某个网站，该网站的每个页面都包含通用的页眉和页脚图像。每次您访问新的网站页面时，服务器必须重新发送相同的图像。为了避免出现这种情况，客户端在首次响应后会缓存或存储这些图像，之后直接使用缓存中的图像。RESTful Web 服务通过使用自行定义为可缓存或不可缓存的 API 响应来控制缓存。

按需编码

在 REST 架构风格中，服务器可以通过将软件编程代码传输到客户端暂时扩展或自定义客户端功能。例如，当您在任何网站上填写注册表单时，浏览器会立即高亮您填写内容的任何错误，例如不正确的电话号码。正是由于服务器发送的代码，浏览器才可以实现这个功能。

RESTful API 有以下优势：

可扩展性

采用了 REST API 的系统可以高效扩展，因为 REST 优化了客户端-服务器交互。无状态可减轻服务器负载，因为服务器不必保留过去的客户端请求信息。管理良好的缓存可部分或完全消除某些客户端-服务器交互。所有这些功能都支持可扩展性，并且不会导致通信瓶颈进而降低性能。

灵活性

RESTful Web 服务支持客户端-服务器完全分离。该服务简化并分离了多种服务器组件，以便可以独立改进每个部分。平台或技术在服务器应用程序端更改，不会影响客户端应用程序。分层应用程序功能可进一步提升灵活性。例如，开发人员可以更改数据库层，而无需重新编写应用程序逻辑。

独立性

REST API 与所使用的技术相互独立。您可以在不影响 API 设计的情况下以多种编程语言编写客户端和服务器应用程序。您也可以在不影响通信的情况下更改任何一端的基础技术。

AsyncAPI 2.0

用于以机器可读的格式描述和记录消息驱动的 API。它与协议无关，因此您可以将其用于任何协议（例如，AMQP，MQTT，WebSockets，Kafka等）工作的API。它通常被称为OpenAPI的姊妹规范。

要深入理解AsyncAPI，我们需要了解消息驱动、事件驱动和流的概念：

消息驱动

在消息驱动通信中，一般链路就是消息生产者（Producer）向消息消费者（Consumer）发送消息。模型如下：

 消息驱动模式下通常会用到中间件，比较常见的中间组件有 RocketMQ，Kafka，RabbitMQ 等。这些中间件的目的是缓存生产者投递的消息直到消费者准备接收这些消息，以此将两端系统解耦。

在消息驱动架构中，消息的格式是基于消费者的需求制定的；消息传递可以是一对一，多对多，一对多或多对一。

消息驱动通讯比较常见的一个例子是商品订单推送，上游组件负责生成订单，下游组件负责接收订单并处理。通过这样的通讯方式上游生成组件其实无需关心整个订单的生命周期，更专注于如何快速生成订单，使单个组件的性能得以提升。

事件驱动

首先要申明一个观点：事件驱动其实是对消息驱动方法的改进，它对消息体大小，消息格式做了较为严格的限制，这层基于消息的限制封装其实就称为事件（Event）。

在事件驱动模式中，生产者发布事件来表示系统变更，任何感兴趣且有权限接入的服务都可以订阅这些事件，并将这些事件作为触发器来启动某些逻辑/存储/任务。

事件驱动的模式可以是一对一，多对一，一对多或多对多。通常情况下一般是多个目标根据过滤条件执行不同的事件。

在事件驱动架构中，事件的格式是由生产者根据事件标准协议制定的；由于更规范限制和封装，事件的生产者完全不需要关心有哪些系统正在消费它生成的事件。

事件不是命令，事件不会告诉消费者如何处理信息，他们的作用只是告诉消费者此时此刻有个事件发生了；事件是一份不可变的数据，重要的数据，它与消息的数据价值相同；通常情况下当某个事件发生并执行时，往往伴随着另一个事件的产生。

事件驱动提供了服务间的最小耦合，并允许生产服务和消费服务根据需求进行扩展；事件驱动可以在不影响现有服务的情况下添加各类新增组件。

事件驱动也可以举一个非常贴切的例子，我们以“客户购买完一款商品”为一个事件，举证在事件场景的应用：

• CRM（客户关系系统）系统接收到客户购买信息，可自行更新客户的购买记录；
• EMR（库存管理系统） 系统接收到客户购买信息，动态调整库存并及时补货；
• 快递服务接收到客户购买信息，自行打单并通知快递公司派送。

这么看，事件驱动模式可以应用并出现在任何地方！

在 EventBridge 产品化方向，也正是由于针对消息做了一些标准化封装，才有可能实现譬如针对事件本身的 filter（过滤） ，transform（转换），schema（事件结构），search（查询） 等能力。这些能力也拓展出更多针对事件驱动特有的场景功能及相关特性。

流（Streaming）

流是一组有序的无界事件或数据，执行操作通常是固定的某个事件段或一个相对事件。

通常情况下单个事件往往就是使用事件本身，但是对于流可能的操作大概率是过滤，组合，拆分，映射等等。

流的操作可以是无状态也可以是有状态的：

• 对于单个事件操作是无状态的，包括过滤和映射；
• 依赖消息在流的时间或位置是有状态的。有状态操作中，流处理逻辑必须保留一些已被消费消息的内存。有状态包括对数据做 Batch Size，Batch Window 等。

流这里也可以举一个比较简单的例子，比如我们的物流系统在物品通过一个物流节点时会生成一个事件，但是要查到这个物品完整的流转状态事件，则必须是各个物流节点单个事件的聚合，那这个聚合事件就是流事件。

Kafka 是最典型的流式中间件，在流式场景中，事件的位置信息至关重要。通常情况下位置信息是由消费者托管的。

插件系统

服务端插件原理和应用

认证同步插件

共享和协作是AnyShare Family 7的核心功能，权限管理又是它们的基础，而权限管理离不开人员和组织架构。同时人员和组织架构是企业管理的关键元素，整个企业的各个业务系统使用同一套人员和组织架构是非常必要的。为了完成人员、组织和认证的集成，AnyShare Family 7开放了认证同步插件。

认证和同步插件是包含了一个或多个 Python 代码文件的压缩包。这些 Python 代码文件按约定的方式进行命名和组织。不同名称的 Python 代码文件需要实现不同功能的类，这些功能包括：

• 将第三方用户系统中的组织架构导入到 AnyShare 用户系统中。
• 实现导入到 AnyShare 的第三方用户在外部认证系统中的鉴权。

认证插件支持账号密码认证、双因子认证、单点认证等，我们使用单点认证和账号密码认证来进一步熟悉AnyShare的认证。

单点登录指用户不通过 AnyShare 来进行账号密码的验证，而是在第三方用户系统中验证账号密码后，换取一次性令牌。再通过一次性令牌从 AnyShare 获取用户的详细信息。单点登录场景下，认证插件的主要作用是验证令牌在第三方用户系统中是否有效，从而决定是否可以返回令牌对应的用户信息。

单点登录的整体流程如下：

 账号密码登录分为三类：

• AnyShare本地用户的认证，直接使用AnyShare内部机制实现登录，不需要开发插件。
• 域用户的认证，大多数域认证可以通过AnyShare预装的域认证模块经过配置后完成，不需要开发插件。
• 外部用户的认证，外部用户的账户密码由客户的第三方系统管理，用户输入的用户名和密码由插件传递给第三方系统后，由第三发系统完成认证过程并返回认证结果，认证结果由插件处理并返回AnyShare，AnyShare根据结果判定登录成功或失败。

对于外部用户的账号密码认证，需要单独开发插件并配置，整体认证流程如下：

 同步插件的作用主要是将外部用户系统的组织架构数据，根据同步模块的要求转换成 AnyShare可以识别的数据结构。同步模块会解析该数据结构中的用户和部门信息，并在 AnyShare 中创建对应的组织、部门和用户数据。同步插件在配置后可以定期执行，保持AnyShare中的组织架构和用户与外部用户系统一致。

同步插件的同步逻辑如下：

 消息插件

AnyShare在使用过程中会产生一些消息，如共享通知、审核消息、知识中心推送等。如果能把这些消息推送到聊天软件、OA系统或代办系统中，可以进一步提升知识传播效率和办公效率。因此，AnyShare提供了消息插件机制，用于AnyShare内部消息推送给客户的业务系统中。

通过消息插件发送消息的整体逻辑如下：

 Web插件原理和应用

Web技术经过三十余年的发展，凭借其分布式、平台无关、图形化交互等特性，当前应用范围已经涵盖各种终端、各类场景、各种行业。目前市面上多数应用系统同样通过Web技术实现，为了快速、低代码地整合AnyShare和这类Web应用的能力，AnyShare Family 7开放了两类Web能力。

Web客户端插件

Web客户端插件用于扩展AnyShare功能，目前开放的部分包括右键菜单、新建下拉框、工作中心和侧边栏，支持PC Web端和富客户端使用。通过该开放能力，可以把业务系统入口或功能集成AnyShare中，也可以给AnyShare添加诸如上传下载列表、目录创建模板、文件创建模板等个性化功能。集成于工作中心的客户端插件效果如下：

 Web客户端插件可以使用任意Web技术栈实现。对于已有系统，只需引入并实现特定的js生命周期函数即可，前后端系统可以独立部署或托管于AnyShare。对于全新开发的插件，可以使用AnyShare OpenAPI进行后端操作，也可以使用各类前端组件低代码实现移动复制、分享、跳转到其他插件、发送通知等各类功能。

Web客户端插件整体框架如下：

 Web组件

Web组件是一类静态资源集合（js、css、素材等），用于扩展业务系统功能，低代码实现AnyShare的上传、下载、预览、选择、共享、搜索等功能。目前支持的web组件类型如下：

• 预览组件
• 选择组件（文件夹/文件，单选/多选）
• 上传组件
• 下载组件
• 目录浏览组件
• 搜索组件
• 共享组件
• 复制组件
• 移动组件
• 打开文件位置组件

对于最常见的预览场景，目前支持办公文档（word、excel、powerpoint、pdf）、图片、音视频等格式。对于办公文档，还支持协作编辑等高级功能。

内容处理框架

为了应对数据不合规、数据泄漏和计算机病毒（如勒索病毒）等风险对企业数字资产的威胁，AnyShare实现了完备的内容处理框架。随着客户需求的不断挖掘，目前内容处理框架可用于内容识别、摘要提取、搜索等多种场景。完整的应用场景如下：

需求类型	业务功能	内容处理功能
安全管控	文档水印功能	文档水印
安全管控	文档脱敏功能	文档脱敏
安全管控	文档加密功能	文档加密
安全管控	文档外发包功能	文档外发包
安全管控	文档杀毒功能	文档杀毒
安全管控	敏感，非法内容识别功能	敏感词检测(FTA)，敏感非法图片，视频检测
多场景使用	图片缩略图功能	图片缩略图
多场景使用	视频缩略图功能	视频帧截图
多场景使用	多格式视频播放源功能	音视频转码
多场景使用	文档摘要功能	文档摘要生成（FTA）
搜索	文本文件全文搜索功能	文本提取（tika）
搜索	多媒体文本内容全文搜索	图片OCR(OCR)，音视频文本内容提取
搜索	文档标签搜索	文本标签提取(FTA)，图片对象识别(OD)，音视频结构化分析
搜索	图片搜索（近似图片，包含图片）功能	图片特征提取（OD）
搜索	相似文本搜索功能	文本特征提取(FTA)
内容识别	人脸识别功能	人脸检测，特征提取(FR)
内容识别	票据，表格，证件识别功能	图片OCR，结构化数据(OCR)
内容识别	文档信息获取功能	文档信息获取，图片，视频信息提取(IGI)

我们可以通过杀毒服务和加解密服务来了解内容处理框架是如何运作的。

杀毒原理和应用

AnyShare 杀毒服务，提供实时杀毒、选择文档范围主动发起杀毒的功能。通过启用杀毒服务，可以对文件进行安全管控，未经杀毒的文档不允许下载、预览；也可以对病毒文件采取修复或隔离操作。

杀毒服务的模块交互如下：

• efastdaemon（文档访问微服务）将文件上传、编辑等事件，发送到消息队列，entivirus监听事件，生成上传杀毒的任务。
• entivirus 调用 efastdaemon 的API，获取文档信息、文档下载地址，查杀病毒后，将文件标记未无毒，或者通过API将文件隔离。
• entivirus 访问 对象存储服务，下载待查杀的文件。
• sharemgnt_server 中包含查杀病毒管理和病毒库管理，提供了初始化主动杀毒任务、查询杀毒任务进度、更新病毒库等功能。
• sharesite_server 在分布式跨地域部署场景下，总站点病毒库更新后，会同步病毒库下载地址到分站点，分站点sharesite_server调用分站点 sharemgnt_server 的接口更新病毒库。
• 杀毒任务管理，病毒库管理，相关信息会持久化到MySQL中。

目前AnyShare内置了瑞星杀毒服务，如果要对接其他厂家的杀毒服务，可以通过实现特定的thrift协议来完成。

加解密原理和应用

加解密服务用于满足客户的数据安全需求，可以实现本地密文文件上传到AnyShare后解密并生成摘要标签等用于文档搜索和管理，下载文件时为密文文件；也可以实现本地为明文文件（可信环境）上传后存储为密文文件，防止数据泄漏。

文件的加解密处理流程如下：

• 文档集微服务生成任务（包含任务id，文件doc_id列表等信息）并推送到消息队列中
• 第三方应用微服务订阅相关消息进行任务处理
• 第三方应用微服务调用文件下载接口
• 第三方应用微服务获取文件下载地址
• 第三方应用微服务通过文件下载地址从对象存储获取文档
• 第三方应用微服务加解密处理
• 第三方应用微服务加解密或其他动作完成后，调用请求上传文件接口
• 第三方应用微服务获取文件上传地址
• 第三方应用微服务上传文件
• 第三方应用微服务回执加解密完成的nsq消息
• 文档集微服务获取回执的nsq消息

目前AnyShare已实现与华途、亿赛通、绿盾、前沿等加解密服务的集成，如果有其他厂商的加解密需求，可以通过实现特定的grpc协议接入。