SuperDoc安全集成完全指南:文档访问控制、遥测配置与AGPL授权差异

原创2026-10-15 15:59:211,673 阅读

SuperDoc安全集成完全指南:文档访问控制、遥测配置与AGPL授权差异

SuperDoc 是一个在浏览器中渲染和编辑 DOCX 文件的文档引擎,本文面向新手完整讲解它的三大安全主题:文档访问控制、遥测(Telemetry)配置,以及 AGPL 开源授权与商业授权的差异,帮助你在把 SuperDoc 集成到产品中时守住数据边界、做出正确的授权选择。

先认识 SuperDoc:浏览器里的 DOCX 编辑器

SuperDoc 直接把 OOXML 格式的 DOCX 文件在浏览器里排版、编辑,修改内容会写回 XML,而不需要经过 HTML 转换。下面是它在 IDE 中打开 DOCX 文档的实际演示:

SuperDoc DOCX 文档编辑器在 VSCode 中的演示动图

因为文档编辑发生在浏览器端,数据本地性天然更好——但官方安全文档明确指出:编辑发生在浏览器里,并不意味着所有集成都是私有的,也不意味着客户端代码就是可信的授权边界。这是理解后面所有内容的前提。

📌 相关文档:secure-integration.mdx、README.md

文档访问控制第一步:识别所有数据边界

在部署 SuperDoc 之前,先回答一个问题:你的文档数据会流经哪些地方? 官方安全集成文档列出了 5 类边界:

边界 说明
URL 文档 由浏览器从其源(origin)拉取
本地 File / Blob 停留在浏览器内存中,直到你的应用代码发送或持久化它
导出的字节 默认留在本地,除非被下载、上传、缓存或传给其他 API
协作 Provider 会传输文档更新与 awareness(在线状态)数据
网络校对、AI、遥测、日志、上传处理 都可能传输文档内容或元数据

官方给出的两条铁律值得抄在团队备忘录里:

  • 最小化数据、保留期和日志;
  • 默认绝不记录文档正文、条款内容、评论文本、凭证、签名 URL 或变更负载(mutation payloads)。

访问控制第二步:可信决策放在可信服务上

很多新手会以为"在编辑器里把按钮禁用掉、把模式设为只读"就等于做了权限控制。官方文档明确提醒:这些只是引导普通浏览器交互的界面手段,对能控制自己浏览器的用户不构成强制访问控制。

真正安全的做法是:

  1. 在可信服务端对文档请求做身份认证;
  2. 在服务端强制执行读、写、导出、协作、AI Agent 审批等策略;
  3. 传给 user 的姓名和邮箱,除非来自已认证的应用会话,否则只能当作展示身份,不能当作凭据;
  4. 校验用户上传的 DOCX 文件,设置大小与超时限制,必要时隔离敏感处理。

一句话总结:编辑器管"体验",服务端管"授权"。

配置浏览器安全边界:HTTPS、CSP 与 cspNonce

生产环境建议按以下清单配置浏览器边界:

  • ✅ 全站使用 HTTPS;
  • ✅ 采用严格的 CORS 策略;
  • ✅ 配置 Content Security Policy(CSP),只放行你部署所需的脚本、Worker、连接、图片和字体;
  • ✅ 避免无版本号的第三方运行时依赖,上线前决定 Editor 静态资源是否自托管。

为运行时样式传递 cspNonce

SuperDoc 会在运行时创建布局和光标样式。如果你的页面 CSP 要求 <style> 元素带 nonce,就要把服务端每次 HTML 响应生成的 nonce 传给每一个挂载的 SuperDoc 实例:

function createEditor(file: File, responseNonce: string) {
  return new SuperDoc({
    selector: '#editor',
    document: file,
    cspNonce: responseNonce,
  });
}

对应页面的 CSP 指令大致是:

Content-Security-Policy: style-src-elem 'self' 'nonce-{response-nonce}'; style-src-attr 'unsafe-inline'

⚠️ 注意:cspNonce 只作用于 SuperDoc 的运行时 <style> 元素,它不配置 CSP 本身,也不授权脚本或 Worker。验证方式是部署后检查浏览器没有报 style-src 违规。

遥测配置:默认开启,但可以随时关闭

这是安全集成中最容易被忽略的一点:SuperDoc 的遥测默认是开启的。浏览器 Editor 在每份 DOCX 就绪后会发送一个"文档打开"事件。

遥测数据里到底有什么?

官方明确界定了上报结构,请求体只包含:

  • superdocVersion:SuperDoc 版本;
  • browserInfo:UA、页面 origin(只有 hostname,不含路径、查询串、片段)、屏幕尺寸;
  • metadata:你自己附加的应用上下文;
  • events:仅含 timestamp、documentId、documentCreatedAt。

不会包含文档内容。但官方同时强调:metadata 由你自己填写,所以不要把文档文本、评论、个人数据、凭证、签名 URL 塞进去。

关闭或改指遥测端点

完全禁用遥测:

const superdoc = new SuperDoc({
  selector: '#editor',
  document: '/contract.docx',
  telemetry: { enabled: false },
});

保留遥测但指向自己的端点并附加环境标识:

telemetry: {
  enabled: true,
  endpoint: 'https://telemetry.example.com/v1/events',
  metadata: { application: 'contract-review', environment: 'production' },
}

CLI 的遥测开关

命令行工具 superdoc 默认不上报用量,但你可以显式声明,让保证"写在命令里":

superdoc get-text contract.docx --no-telemetry

或者用环境变量让整个 CI 环境、容器都关闭遥测:

export SUPERDOC_TELEMETRY=0
superdoc get-text contract.docx

🛡️ 一个值得点赞的设计:SUPERDOC_TELEMETRY 只接受 0/false/off/no/disabled(关闭)或 1/true/on/yes/enabled(保持开启)这组白名单值,其他拼写会让命令直接失败,而不是悄悄回退到上报——CI 配置里手滑打错一个字母不会导致遥测"复活"。

📌 相关文档:telemetry.mdx;遥测请求结构参考 Telemetry.ts

License Key 详解:它是身份标识,不是访问凭证

很多集成者会把 licenseKey 当成"门禁钥匙",这里需要纠正一下:

const superdoc = new SuperDoc({
  selector: '#editor',
  document: '/contract.docx',
  licenseKey: import.meta.env.VITE_SUPERDOC_LICENSE_KEY,
});

官方对 license 的定位非常清楚:

  • 它是客户端可见的身份标识(client-visible identity),不是密钥、不是访问凭证;
  • 遥测开启时,它会随"文档打开"事件一起发送;
  • 省略它时,事件使用"社区/评估"身份,功能不受限;
  • 浏览器构建变量对运行应用的人可见,所以请把文档访问、协作凭据、服务端授权与 license 身份彻底分开。

📌 相关文档:license.mdx

AGPLv3 与商业授权:两条路怎么选

SuperDoc 采用双重授权(dual licensing),选哪条取决于你如何分发和运营应用:

维度 开源版(AGPLv3) 商业版(Commercial License)
适用场景 你的应用能满足 AGPLv3 要求 专有软件、商业部署
核心义务 网络交互的修改版必须向用户提供对应源码 以商业协议约定为准
代码位置 本仓库全部开源代码 见 LICENSE 与官方商业条款
联系 — 邮件 q@superdoc.dev

AGPLv3 对新手意味着什么?

AGPL 比普通 GPL 多了一条"网络条款"(第 13 条):如果你的修改版通过网络与用户交互,就必须让所有远程用户有机会免费获取你的修改版源码。也就是说,你在自己的服务器上跑一个改造过的 SuperDoc,哪怕不分发二进制文件,开源义务也可能被触发。

所以决策很简单:

  • 你的产品本身就是开源的,或愿意公开改动 → 选 AGPLv3,零成本;
  • 你的产品是闭源商业软件 → 直接走商业授权,避免为开源义务做额外架构妥协。

容易被忽视的第三方:DOCX Engine 专有许可证

这里有一个重要的隐藏细节:SuperDoc 生态里还有一个 @superdoc/docx-engine 包,它是专有软件,不属于开源部分,受独立的《SuperDoc DOCX Engine 专有许可证》(2026-07-14 版)约束。关键条款包括:

  • 📦 仅限作为 SuperDoc 的依赖使用,不可单独分发、转售、镜像;
  • 🔒 禁止逆向工程、反混淆、重建源码,包括借助 LLM/AI 手段;
  • 🤖 禁止 AI 用途:不得将引擎材料或其派生信息用于训练、克隆、行为复刻等构建"竞品产品"(但用它给你的应用赋能是允许的);
  • 🏠 自托管:官方不托管你的生产环境,也不访问你的文档内容。

也就是说,开源版编辑器 + 专有引擎是两套独立许可证的组件,AGPLv3 不授予任何针对引擎的逆向或复刻权利。

📌 相关文档:license.mdx、docx-engine-license.mdx、LICENSE、NOTICE

安全实践与漏洞披露:生产部署清单

最后给一份面向生产的检查清单:

  • ✅ 保持版本在支持线内:2.x(latest)和 1.x(legacy)都受支持,安全修复随各线最新补丁发布,主版本内升级即可拿到;
  • ✅ 私有披露漏洞:发现安全问题不要开公开 issue,通过官方安全通告渠道或邮件 q@superdoc.dev 提交,官方承诺 2 个工作日内确认、7 天内给出进展;
  • ✅ 参考合规基线:SuperDoc 通过 SOC 2 Type II 认证,数据传输用 TLS 加密、静态存储用 AES-256,API 不持久化文档数据;
  • ✅ 验证遥测行为:在部署环境的浏览器网络面板里确认——禁用后无遥测请求,或启用后只打到批准的端点、携带批准的元数据;
  • ✅ 发布隐私说明:用产品化的隐私语言公开数据边界、保留期与日志策略。

📌 相关文档:security.mdx、SECURITY.md

总结

主题 一句话要点
文档访问控制 识别数据边界;授权决策放在可信服务端,而不是靠浏览器界面
浏览器策略 HTTPS + 严格 CORS + CSP;需要时给 cspNonce 传响应级 nonce
遥测 默认开启、只报 origin 级元数据;enabled: false 或 --no-telemetry 显式关闭
License Key 身份标识而非凭证,缺失时使用社区/评估身份
授权选择 闭源商业产品选商业授权;开源场景用 AGPLv3;注意 DOCX Engine 是独立专有组件

把这三块(访问控制、遥测、授权)配置好,你就拥有了一个数据边界清晰、合规路径明确的 SuperDoc 集成。

登录后查看全文
docx-editor