SuperDoc安全集成完全指南:文档访问控制、遥测配置与AGPL授权差异
SuperDoc安全集成完全指南:文档访问控制、遥测配置与AGPL授权差异
SuperDoc 是一个在浏览器中渲染和编辑 DOCX 文件的文档引擎,本文面向新手完整讲解它的三大安全主题:文档访问控制、遥测(Telemetry)配置,以及 AGPL 开源授权与商业授权的差异,帮助你在把 SuperDoc 集成到产品中时守住数据边界、做出正确的授权选择。
先认识 SuperDoc:浏览器里的 DOCX 编辑器
SuperDoc 直接把 OOXML 格式的 DOCX 文件在浏览器里排版、编辑,修改内容会写回 XML,而不需要经过 HTML 转换。下面是它在 IDE 中打开 DOCX 文档的实际演示:
因为文档编辑发生在浏览器端,数据本地性天然更好——但官方安全文档明确指出:编辑发生在浏览器里,并不意味着所有集成都是私有的,也不意味着客户端代码就是可信的授权边界。这是理解后面所有内容的前提。
📌 相关文档:secure-integration.mdx、README.md
文档访问控制第一步:识别所有数据边界
在部署 SuperDoc 之前,先回答一个问题:你的文档数据会流经哪些地方? 官方安全集成文档列出了 5 类边界:
| 边界 | 说明 |
|---|---|
| URL 文档 | 由浏览器从其源(origin)拉取 |
本地 File / Blob |
停留在浏览器内存中,直到你的应用代码发送或持久化它 |
| 导出的字节 | 默认留在本地,除非被下载、上传、缓存或传给其他 API |
| 协作 Provider | 会传输文档更新与 awareness(在线状态)数据 |
| 网络校对、AI、遥测、日志、上传处理 | 都可能传输文档内容或元数据 |
官方给出的两条铁律值得抄在团队备忘录里:
- 最小化数据、保留期和日志;
- 默认绝不记录文档正文、条款内容、评论文本、凭证、签名 URL 或变更负载(mutation payloads)。
访问控制第二步:可信决策放在可信服务上
很多新手会以为"在编辑器里把按钮禁用掉、把模式设为只读"就等于做了权限控制。官方文档明确提醒:这些只是引导普通浏览器交互的界面手段,对能控制自己浏览器的用户不构成强制访问控制。
真正安全的做法是:
- 在可信服务端对文档请求做身份认证;
- 在服务端强制执行读、写、导出、协作、AI Agent 审批等策略;
- 传给
user的姓名和邮箱,除非来自已认证的应用会话,否则只能当作展示身份,不能当作凭据; - 校验用户上传的 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 不授予任何针对引擎的逆向或复刻权利。
安全实践与漏洞披露:生产部署清单
最后给一份面向生产的检查清单:
- ✅ 保持版本在支持线内: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 集成。
