Intercom-service 集成架构

Intercom-service 是 openEDU 基础设施中一个小而关键的组成部分。它是一个运行在浏览器层面的代理与中介，用于实现跨应用的通信——文件选择器、视频会议房间创建、应用之间的静默单点登录以及门户导航。通过持有用户的 OpenID Connect 会话并将其经由可信中介暴露给套件中的其他部分，它使一批独立部署的服务像一个统一的协作工作空间那样协同工作。

Intercom-service 是什么

Intercom-service 是一个运行在用户浏览器上下文中的轻量级代理。每个参与的应用都将 intercom-service 嵌入为 iframe，并通过 postMessage 与之通信。由于该 iframe 位于 intercom-service 的源上，它能够持有各个应用彼此无法直接共享的凭据与会话状态——iframe 代表用户扮演可信中介的角色。

这种设计刻意保持 intercom-service 的轻量。它不存储应用数据；它只是在那些因浏览器同源策略而彼此隔离的应用之间中介导航、会话与跨应用意图。

它提供的能力

在整个套件中，应用依赖 intercom-service 来获得一组共享的浏览器层面能力：

• 静默登录——在应用之间传递 OpenID Connect 令牌，而无需用户看到重新认证步骤。
• 门户导航——获取中央导航结构，使每个应用都能呈现相同的门户菜单。
• 文件选择——在另一应用中打开套件文件存储服务中的文件。
• 视频会议房间——从协作应用中创建会议房间。
• 反向通道登出——协调所有应用的会话终止，使一次登出即可结束所有会话。

这些能力是让多服务平台看起来浑然一体、而非一堆互不相关的网站的粘合剂。

与身份层的集成

身份验证集中在 Keycloak 上，它作为套件的 OpenID Connect 提供者。intercom-service 通过自己的 OIDC 客户端参与该 realm，并按平台的声明命名约定（opendesk_username 声明）进行配置。由于 intercom-service 持有 OIDC 会话，它可以代表下层应用执行静默登录：应用重定向到 intercom-service，中介将已存储的会话兑换为令牌，应用继续运行而无需提示用户。

默认情况下，该 OIDC 客户端通过套件的 Keycloak 引导流程进行配置，因此其声明与平台其他部分保持一致地集中管理。反向通道登出也通过同一 OIDC 流程协调，因此在一个位置终止会话会传播到所有依赖该中介的应用。

Intercom-service 中介哪些服务

Intercom-service 以它要中介的一组可信应用进行配置，而套件会精确启用每个部署所需的具体集成。在 openEDU 平台中包括：

• 文件存储——Nextcloud 与 OpenCloud 文件服务，支持跨应用文件选择与静默访问。
• 群件——OX App Suite 群件后端，并在启用之处可选支持 Grommunio 群件栈。
• Wiki——XWiki 服务。
• 通信——Matrix (Synapse) 部署，用于消息与视频，intercom-service 针对 Matrix 服务器及其应用服务钩子进行配置。

平台将中介的后端列表视为可选启用（opt-in）：一个部署只启用它实际运行的那些集成，因此 intercom-service 始终反映实例具体选择的服务，而非固定的目录。这与平台模块化的设计一致，其中每个服务都可以独立启用或禁用。

应用如何使用中介

应用通过嵌入 intercom-service 的 iframe 并指向中介的端点来加入。实际中：

• 聊天（Element） 配置了 intercom-service 的导航与静默登录 URL，因此消息客户端会呈现共享门户，并与套件其他部分一起静默登录。
• Notes 使用中介的基础 URL 作为跨应用会话与导航行为的集成端点。

模式是一致的：应用声明一小组指向 intercom-service 的集成 URL，中介代表它处理共享的会话与导航问题。任何应用都无需自建联合或会话逻辑。

部署模式

intercom-service 作为 Kubernetes 工作负载运行，通过平台的 Helm/helmfile 配置管理，与套件的其他服务并列：

• 它以标准的轻量 Alpine 基础容器镜像打包，而不需要特定于服务的系统镜像，因此可以在任何 Kubernetes 集群上部署而不依赖平台特有组件。
• 它以加固方式运行——非 root、只读根文件系统、丢弃 Linux 能力以及受限的 seccomp 配置，与套件其他部分的安防态势保持一致。
• 它暴露一个健康端点，用于 Kubernetes 存活与就绪探针。
• 其会话状态保存在平台共享的、基于 Redis 的缓存层中。
• 它运行在平台 ingress 之后，受到与每个其他服务相同的 TLS 与 ingress 配置保护。

由于它持有会话状态并中转令牌，intercom-service 被视为安全敏感组件：它采用与套件中身份相关服务相同的加固与证书管理进行配置。

与上游的关系

intercom-service 由 openEDU CE 项目在上游维护，并为统一协作环境打包。openEDU 部署相同的 intercom-service，并针对教育平台的声明命名与后端选择进行配置。平台为教育栈扩展该中介——在社区版基础上增加文件存储支持，并为自身的部署配置群件、wiki 与通信后端——这一内容记录在社区文章《扩展 intercom-service》中，参见扩展 Intercom-Service。

延伸阅读

• 系统架构概览 —— 完整的平台架构
• 身份与认证架构 —— 如何处理 OIDC 与 SAML 联合
• 安全架构 —— 如何保护会话与身份数据
• 扩展 Intercom-Service —— 关于中介集成与治理的社区文章

---

Intercom-service 正是让一批独立部署的服务像一个统一的工作空间那样运作的关键——一个承载平台大部分集成负载的小小中介。