在分布式服务器配置中使用 Doconut

当您需要从一组 ASP.NET Core 节点为 PDF、Office 文件、CAD 图纸或图像提供服务时，Doconut 的 分布式模式 让每个节点都可以从共享位置读取相同的页面工件。这样即可实现横向可伸缩、安全的查看器，并且在负载均衡器后无需粘性会话。

为什么分布式模式重要

• 可伸缩性 – 每个节点可以将页面发布到 UNC 或云共享；任何其他节点都能立即提供这些页面。
• 安全性 – 工件在共享文件夹中加密存储；查看器会根据 ASP.NET 会话令牌验证每个请求。
• 零 Office 依赖 – Converter 插件在服务器端运行，将 Word、Excel、PowerPoint、CAD 和图像转换为 PDF 或图像，无需安装 Microsoft Office。

这些特性使企业 DMS、CRM 或电子学习门户能够在 .NET 后端内部进行文档处理，同时扩展到数十个容器。

分布式模式的共享存储

在分布式模式下，Doconut 期望页面工件（PDF 页面、图像瓦片等）写入一个所有节点都能访问的存储位置——网络共享、Azure Blob 容器、S3 存储桶或任何其他由 Progressive Cloud Publishing 功能支持的共享存储。查看器会自动查找与每个文档安全令牌匹配的工件文件夹，因此除确保所有节点对所选存储具有相同的读写权限外，无需额外代码。

提示： 在每个实例的配置中使用相同的 UNC 路径（例如 \\fileserver\doconut）或云 URL，并保持文件夹权限一致。UsePerTokenSubfolders 行为默认已启用，可将每个文档的页面相互隔离。

注册 Doconut 和会话中间件

Doconut 依赖 ASP.NET Core 会话状态来实现每个文档的安全。仅在使用 minimal‑API 项目时才需要分布式缓存；MVC 或 Razor Pages 已经内置。

builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
});

builder.Services.AddDistributedMemoryCache(); // 会话需要缓存
builder.Services.AddSession();                 // Doconut 针对会话进行验证

app.UseSession();               // 必须在 UseDoconut() 之前运行
app.UseDoconutResources();      // 注册静态查看器资源
app.Map("/doconut", branch => branch.UseDoconut());

自定义路径（可选）

如果另一路由与 /doconut 冲突，请 一次性 更改路径并保持客户端 BasePath 同步：

builder.Services.AddDoconut(options =>
{
    options.MiddlewarePath = "/docs-engine";
    options.ResourcesPath  = "/docs-assets";
});
app.UseDoconutResources();
app.Map("/docs-engine", branch => branch.UseDoconut());

切勿在 MiddlewarePath 或 ResourcesPath 前添加前导斜杠；查看器会自动添加斜杠。

综合示例：Minimal‑API 示例

下面是一个紧凑、可投入生产的示例，结合了共享存储需求、会话处理以及 Doconut 注册。

var builder = WebApplication.CreateBuilder(args);

// 1️⃣ 核心 Doconut 注册
builder.Services.AddDoconut(options =>
{
    options.LicensePath = Path.Combine(
        AppContext.BaseDirectory, "wwwroot", "Doconut.Viewer.lic");
    options.MiddlewarePath = "/doconut";
    options.ResourcesPath  = "/doconut-res";
});

// 2️⃣ 会话和缓存（需要安全性）
builder.Services.AddDistributedMemoryCache();
builder.Services.AddSession();

var app = builder.Build();

app.UseRouting();
app.UseSession();
app.UseDoconutResources();                     // 静态查看器捆绑包
app.Map("/doconut", branch => branch.UseDoconut());

app.Run();

将此二进制文件部署到任意数量的 Docker 容器或 Windows 服务，并置于负载均衡器之后。只要每个实例能够访问您为页面工件配置的共享存储位置，查看器就会从任意节点获取页面，上传/转换也能在节点跳转间保持。

在负载均衡器后部署

1. 公开相同的基础 URL（例如 http://myapp.example.com，在每个节点上）。
2. 禁用粘性会话——Doconut 的分布式模式消除了会话亲和性的需求。
3. 确保健康监控 检查应用的基本端点（例如 /health），以便负载均衡器仅将流量路由到活跃节点。
4. 监控共享文件夹 的增长；默认的 30 分钟 TTL 可限制存储占用，但您可以根据合规需求进行调整。

通过这些步骤，您的文档密集型 .NET 应用程序可以服务数千个并发查看器，保持每页在静止时加密，并避免在每台服务器上安装 Office 的开销。

准备好尝试了吗？获取 Doconut 的 免费试用，启动几个容器，指向共享 UNC 路径，观察查看器在没有任何粘性会话 Cookie 的情况下实现弹性扩展。