构建无运行时、无存储、无共享 JS 上下文的插件系统

背景

Tolgee 的核心平台基于 Spring Boot 和 TypeScript/React 构建，拥有完善的集成测试和极高的稳定性，单次发布周期仅需约一小时。这种稳定性对客户而言是巨大的优势，但对于内部的产品迭代和实验性功能的开发却构成了阻碍。

在传统的发布流程中，任何新功能的上线都需要经历完整的测试、边缘情况处理及全员推送流程。这导致两个主要问题：

1. 迭代滞后：当功能最终上线时，客户可能已经找到了替代方案，或者由于缺乏与真实用户的早期迭代，导致功能采纳率低。
2. 创新受阻：开发者难以快速针对单一客户定制功能并进行微调，因为任何改动都涉及核心代码库的重构和重新发布。

为了解决这一矛盾，Tolgee 团队希望建立一种机制，能够以极快的速度交付实验性功能，允许直接与客户测试并根据反馈调整，同时不触碰核心代码库。此外，他们还希望作为目标受众的开发者能够自行扩展 Tolgee 工具。

基于此需求，Tolgee Apps 应运而生。创始人 Jan Cizmar 利用 AI 编程工具（Claude Code）在约 3 个人天内完成了概念验证（PoC）引擎的“vibecoding”（一种结合直觉与 AI 辅助的快速编码方式），并在内部黑客松中进行了测试。目前，该 PoC 旨在快速学习并指导后续正式实现，正式版本将经过完整的测试覆盖和代码审查后重新编写。

核心内容

Tolgee Apps 的定义与架构

Tolgee Apps 是一种通过 iframe、API 访问、Webhook 和 UI 装饰器来扩展 Tolgee 平台的插件系统。每个应用由一个 JSON 清单（Manifest）描述，其中声明了元数据、命名位置的 UI 模块、所需权限范围、Webhook 订阅以及可选的装饰器端点。

工作流程如下：

• 渲染：Tolgee 将每个 UI 模块渲染在沙盒化的 iframe 中。
• 通信：通过 postMessage 传递受限的上下文（Scoped Context）。
• 权限：应用通过短期有效的 JWT 令牌调用 Tolgee REST API。

实际应用场景： 应用可以在项目中添加新的仪表盘页面、在翻译编辑器旁增加面板、在特定键值上显示图标和徽章、打开模态框，或在翻译变更时响应 Webhook。所有这些操作均无需修改核心平台的一行代码。

清单示例解析： 一个真实的清单（如回译示例应用）会明确告知 Tolgee：

• 需要 translations.view 和 keys.view 权限。
• 订阅 SET_TRANSLATIONS Webhook 事件。
• 将 /tools-panel 路由渲染在翻译工具面板中。
• 通过装饰器端点动态显示警告图标。

行业定位：嵌入式 iframe 应用模型

这种模式在行业内被称为“嵌入式 iframe 应用模型”。其核心要素包括：

1. 声明模块和权限范围的 JSON 清单。
2. 由宿主在指定位置渲染的沙盒 iframe。
3. 用于上下文传递和握手的 postMessage 桥接。
4. 权限不超过安装用户的 OAuth/JWT 令牌。
5. 用于服务端事件的签名 Webhook。

竞品对比：

• 典型代表：Atlassian Connect 是该模式的原型。类似模式也见于 Contentful App Framework、Shopify 嵌入式应用、Zendesk Apps Framework、Salesforce Canvas、monday.com 和 Miro。
• 本地化领域：Crowdin Apps 是与 Tolgee 最直接的竞争对手，采用几乎相同的模型。而 Lokalise、Phrase 和 Smartling 则更倾向于 API 集成，而非产品内的 iframe 插件。
• 其他方案：虽然存在沙盒 JS 和无服务器方案（如 Atlassian Forge、Shopify Functions），但 Tolgee 选择 iframe 路线是因为其语言无关性、部署灵活性以及通过隧道和热更新清单 URL 实现的本地开发便利性。

三大核心架构决策

在设计 Tolgee Apps 时，团队做出了三个根本性的架构决策，旨在避免技术陷阱并降低风险：

决策 1：Tolgee 平台侧无存储

Tolgee 不在其数据库中存储任何插件数据。如果插件需要持久化状态（如回译判定结果或术语表建议），插件作者必须自行托管存储后端。

• 优势：避免了处理数据结构迁移、数据量限制、跨插件搜索以及插件卸载后数据清理等复杂问题。
• 劣势：平台无法控制数据，也无法在插件作者停止服务时保留旧版本。这与 GitHub Apps、Slack Apps 等云应用平台面临的挑战一致。
• 未来考量：虽然考虑过添加基于 JSONB 的每键或每翻译存储，但鉴于其引发的复杂性，目前仍坚持外部存储策略。

决策 2：Tolgee 运行时中无插件代码执行

在 NetSuite 工作时，SuiteScript 允许插件在前后端运行代码，但这需要庞大的团队来隔离运行时、管理 API 表面并处理安全问题。

• 策略：Tolgee 决定让开发者自行托管后端（即使是免费的 Heroku 实例或无服务器函数）。
• 权衡：应用作者需自行负责后端可用性，平台无法保证应用持续在线。
• 收益：平台无需承担计算成本、内存限制，也无需在运行时隔离不受信任的代码。对于 Tolgee 自家的应用，可能会使用共享数据库系统，但这属于部署决策，而非对第三方开发者的约束。

决策 3：UI 中无代码执行（仅限 iframe）

与 Figma 插件在沙盒 JS VM 中运行不同，Tolgee 拒绝在 UI 运行时中执行第三方 JavaScript。

• 风险：如果在共享的 JavaScript 上下文中运行插件代码，插件可能修改原型、拦截网络请求或访问主应用的 DOM，导致 XSS（跨站脚本攻击）风险。Shadow DOM 和 Web Components 无法完全隔离 JS 执行上下文，微前端（Module Federation）也存在同样的运行时共享问题。
• 解决方案：Iframe 提供了真正的来源隔离（Origin Isolation）。插件的 JavaScript 在完全独立的浏览上下文中运行，无法直接访问宿主应用的核心逻辑。

关键要点

• 稳定性与灵活性的平衡：Tolgee 通过插件系统解决了核心平台稳定但迭代缓慢的问题，允许快速实验而不影响核心代码。
• 嵌入式 iframe 模型：采用行业标准的嵌入式 iframe 架构，通过 JSON 清单、postMessage 通信和 JWT 令牌实现安全交互。
• 零存储策略：插件数据完全由作者自行托管，平台不存储任何插件数据，从而规避了数据迁移、搜索和清理的复杂性。
• 零运行时执行：插件代码不在 Tolgee 服务器或客户端运行时中执行，开发者需自行托管后端，平台无需处理沙箱隔离和资源限制。
• 严格的安全隔离：通过 iframe 实现真正的来源隔离，防止第三方代码通过 XSS 攻击宿主应用，优于共享 JS 上下文或微前端方案。
• AI 辅助开发：PoC 阶段利用 AI 工具（Claude Code）大幅缩短了开发时间（从 20 天缩短至 3 天），加速了概念验证过程。

意义与影响

Tolgee 的架构决策为 SaaS 平台的插件系统设计提供了一个极具参考价值的案例，特别是在安全性和维护成本之间寻求平衡方面。

1. 降低平台维护负担：通过拒绝存储和运行时执行，Tolgee 将插件生态的复杂性转移给了插件开发者。这使得平台团队能够专注于核心产品的稳定性和性能，而无需组建庞大的安全团队来监控和隔离第三方代码。
2. 安全优先的设计哲学：在 Web 应用日益复杂的今天，XSS 攻击是主要威胁之一。Tolgee 选择 iframe 而非共享 JS 上下文，体现了对安全边界的严格坚守。虽然牺牲了部分性能（如 Figma 插件所追求的原生交互速度），但对于以翻译和管理为核心的工具而言，这种安全隔离是必要且合理的。