你的应用如何设计应用（app）模型？

应用是什么？

应用（app）是接入方系统在石墨文档中台中的“接入身份”和“配置载体”。可以把它理解成“你的业务系统在石墨里的注册记录”。

当业务系统调用石墨后端 API、前端打开编辑器/预览页、或者石墨回调业务系统接口时，石墨都会基于这个 app 来判断：

这次请求属于哪个接入方。

允许使用哪些能力和文件类型。

应该回调到哪个业务系统地址。

当前 license、席位和有效期是否允许继续服务。

一个 app 通常会绑定以下核心配置：

鉴权配置

appId：公开标识，用于指向具体哪个应用。

appSecret：指定应用的私有密钥，只能放在你的业务系统后端。

这部分决定“你是否能以这个 app 的身份调用石墨接口”。这两个配置在你的系统接入石墨文档中台前，由石墨侧提前申请好后提供给你。

回调配置

endpointUrl: 石墨回调接入方的统一入口地址。

这个 endpointUrl 是你系统实现的所有回调接口的 BaseURL，所有的回调接口需要使用 endpointUrl 这个公共前缀。

回调接口实现：包括当前用户、指定用户、文件元信息、权限、搜索、事件等能力接口。

回调地址的可达性和稳定性：石墨服务端必须能访问，且升级或迁移时要保证兼容。

这部分决定“石墨在运行时如何反向读取你的业务上下文”。这个配置是你来决定，你定义好具体的回调地址 endpointUrl 后，通过 更新App回调地址 这个接口通知到石墨文档中台。

应用（app）和“租户”有什么区别？

在接入石墨文档中台的系统设计中，最容易混淆的是把 app、租户、用户、文件混成同一层概念。它们其实分别解决不同问题：

应用（app）：接入方系统在石墨中的身份，用于鉴权、能力控制和回调路由。

租户：接入方业务系统中的数据隔离单元，例如一个企业客户、一个学校、一个组织。

用户：租户下的业务账号，石墨通过回调读取其展示信息和权限。

文件：由接入方定义和维护的业务对象，石墨只根据 fileId 回调查询，不替接入方维护业务“租户”数据。

一个常见模型是：

一个应用（app）服务多个租户。

每个租户下有自己的用户、文件、权限和组织架构。

石墨通过 app 找到接入方，再通过 token、fileId 和回调接口进入某个具体租户上下文。

如果你的业务要求“不同客户完全独立，连配置、回调地址、席位也要分别管理”，也可以考虑为不同环境或不同业务线拆分多个 app。但在多数 SaaS 场景里，更常见的是“一个 app + 多租户业务数据隔离”。

应用（app）和租户如何配合？

可以把职责分工理解成下面两层：

应用（app）层负责“接到石墨这边来的是谁”。

租户层负责“这个请求在你自己的业务系统里属于谁、能看什么、能做什么”。

实际请求链路里通常是这样协作的：

业务后端以某个 app 的身份生成 signature，并把 appId、signature、token、fileId 交给前端或用于服务端调用。

石墨收到请求后，知道这是哪个 app 发起的请求，并按该 app 的配置决定可用能力和回调目标。

石墨回调接入方接口时，会带回 X-WebOffice-Token 或其他上下文。

接入方后端再根据 X-WebOffice-Token 识别当前用户、租户和权限，并返回该租户下的文件、用户、组织等信息。

这里要特别注意：token 不是 app 的静态配置，而是某次具体访问的业务凭证。它负责把“应用身份”进一步定位到“当前租户 + 当前用户 + 当前会话”。

常见误区

把 app 当成租户。app 解决的是“接入身份”，不是“业务数据隔离”。

把 token 当成 app 配置。token 更适合表达一次访问的业务上下文，而不是应用静态信息。

只校验 fileId，不校验租户和用户。这样最容易造成跨租户读到错误文件。

前端直接持有 appSecret。appSecret 只能保存在服务端。

只关注接口是否能调通，不关注回调返回的数据是否来自同一租户、同一组织和同一权限模型。

应用是什么？#

鉴权配置#

回调配置#

应用（app）和“租户”有什么区别？#