教程：使用 React 安全嵌入 Doconut 查看器 – 全面指南
将文档查看器安全嵌入不仅仅是把中间件代码片段复制到 ASP.NET Core 应用中。集成必须为身份验证、文档访问、会话管理、渲染、批注、搜索、打印和审计日志等方面划定清晰的边界。
企业构建以文档为中心的门户——如 DMS、CRM、法律审查或工程图纸应用——同样需要将原始文件保留在应用边界之后。Doconut 支持 PDF、Office、CAD 和图像文档的服务器端查看模型，而 React 前端可以提供用户界面。
本教程侧重于可靠的架构，刻意回避可能因 SDK 版本而异的包名、选项属性、方法签名和端点路径。请使用与您授权版本匹配的官方文档，以获取准确的注册和 API 细节。
1️⃣ 步骤 1 – 准备 ASP.NET Core 和 React 项目
在编写任何代码之前，确保您的开发环境满足以下基线要求：
| 要求 | 推荐版本 |
|---|---|
| .NET 运行时 | .NET 6 或更高 |
| ASP.NET Core | 6.0+ |
| 集成开发环境 | 支持的 .NET 开发环境 |
| 前端（可选） | 与项目兼容的 React 应用 |
- 创建一个新的 ASP.NET Core Web API 项目
dotnet new webapi -n DocPortal
cd DocPortal
-
添加授权的 Doconut 依赖 – 从官方文档获取确切的包名、版本、原生依赖以及许可证加载说明。不要假设与您版本无关的教程中出现的包或包装器适用于当前项目。
-
准备 React 应用 – 如果查看器将通过 React 展示，请使用团队已批准的前端设置。让 React 应用依赖您自己的已认证 API，而不是未记录的第三方包装器。
-
提交初始状态 – 大多数企业团队会强制执行 Git 策略，要求对涉及许可证或安全设置的任何更改进行签名提交。
现在，您已经拥有一个干净的解决方案，可用于文档化的 Doconut 服务器集成。
2️⃣ 步骤 2 – 安全配置服务器集成
使用项目中确切 Doconut 版本提供的说明注册查看器。中间件顺序、服务注册、许可证初始化以及配置属性名称都是版本特定的细节，切勿从未经验证的示例中复制。
无论 SDK 版本如何，外围的 ASP.NET Core 应用都应强制执行以下控制：
- 在打开文档前进行身份验证 – 查看器会话绝不能绕过应用的身份层。
- 在服务器端解析文档标识符 – 接受应用级别的文档 ID，而不是浏览器提供的任意物理文件路径。
- 对每个操作进行授权 – 查看、批注、搜索、下载和打印可能需要不同的权限。
- 将机密信息置于源代码管理之外 – 将许可证、连接字符串和加密材料存放在批准的密钥管理机制中。
- 应用请求限制 – 为查看器工作流设置合适的上传、文档大小、超时和速率限制。
- 记录安全事件 – 记录访问决策和文档操作，但不要将文档内容或敏感令牌写入日志。
将所有 SDK 设置视为版本化配置。在生产环境启用前，请先在官方参考中确认其含义。
3️⃣ 步骤 3 – 将文档会话隔离在应用服务后
将 Doconut 相关交互封装在专用的应用服务中。Viewer 类的引用在架构层面有用，但构造函数签名、文档打开方法、缓存需求以及许可证发现行为必须依据您已安装版本的文档。
安全的服务边界应：
- 接收已认证的用户和应用级别的文档标识符。
- 检查用户对请求操作的权限。
- 从批准的服务器端存储中解析文档。
- 调用文档化的查看器 API 建立文档会话。
- 仅返回客户端所需的最小不透明会话信息。
- 根据保留和缓存策略释放或过期会话。
浏览器绝不能收到物理存储路径、许可证数据、内部缓存键或对原始文档的无限制引用。
4️⃣ 步骤 4 – 启用批注、搜索和受控打印
仅当您的授权 Doconut 配置以及已安装版本支持时，才启用批注、搜索、OCR 和受控打印。避免假设方法名称、持久化格式或选项类。
- 批注 – 确定哪些角色可以创建、编辑、查看或删除标记。根据 SDK 版本的持久化指南以及您自己的审计要求存储批注状态。
- 搜索和 OCR – 确定哪些文档类型需要 OCR，提取的文本保存位置以及索引保留时长。将搜索结果视为文档数据并相应授权。
- 受控打印 – 在应用层面定义页数限制、水印策略、审批规则和审计事件，然后映射到文档化的打印功能。
将这些操作与用于文档会话的同一应用服务保持一致，以便控制器保持轻量，业务规则易于测试。
5️⃣ 步骤 5 – 连接 React 前端
React 应用应调用您已认证的 ASP.NET Core API，而不是接受存储路径或直接连接内部文档服务。围绕业务操作定义自己的面向资源的 API 合约，避免将 SDK 特定的端点名称公开为客户端合约的一部分。
典型的交互顺序如下：
- 用户在应用中选择已可见的文档。
- React 使用文档的应用 ID 请求查看会话。
- ASP.NET Core 对请求进行身份验证、授权文档并协调查看器会话。
- React 仅收到用于显示查看器的必要信息。
- 批注、搜索和打印请求通过已认证的应用 API 返回。
- 服务器记录审计事件，并在适当时机使会话过期。
在 React UI 中，保持会话状态短暂，显式处理授权失败，避免将敏感值存放在持久化浏览器存储中，并提供不泄露内部路径或异常细节的加载与错误状态。
这种分离使渲染和文档控制留在服务器端，而 React 只负责呈现和交互。
结论
通过将 Doconut 集成置于安全的 ASP.NET Core 应用服务之后，您可以构建支持 PDF、Office、CAD 和图像工作流的文档门户，而无需将 React 界面耦合到未记录的 SDK 细节。身份验证、授权、会话生命周期、搜索、批注、打印和审计策略仍然是您应用设计的显式组成部分。
准备在您的 .NET 项目中评估 Doconut 吗？使用官方包、许可证和 API 文档对应您选择的版本，然后将上述架构与安全检查清单应用到您的实现中。