SumatraPDF 受限模式Restricted Use配置指南用 sumatrapdfrestrict.ini 构建 Kiosk / 内嵌查看器【免费下载链接】sumatrapdfSumatraPDF reader项目地址: https://gitcode.com/gh_mirrors/su/sumatrapdfSumatraPDF 内置了一套受限使用restricted use策略机制通过放置sumatrapdfrestrict.ini配置文件或传入-restrict命令行参数可以批量禁用打开新文件、打印、选择复制、外链跳转、联网更新、保存偏好等不适合自助终端与捆绑分发场景的功能。本文以官方配置文档为主体结合仓库内 docs/sumatrapdfrestrict.ini 与 src/SumatraPDF.cpp 的权限实现完整讲解受限模式的启用方式、全部策略开关、白名单语义与底层工作原理读完后你可以为任意部署环境定制一套最小权限的 PDF 阅读器。受限模式是什么适用于哪些场景SumatraPDF 默认是一个功能完整的 PDF/电子书阅读器可以打开新文件、打印、选择并复制内容、跟随文档内链接、自动检查更新、把自身注册为系统默认 PDF 查看器等。但在把 SumatraPDF 作为你软件文档的内嵌查看器或Kiosk 自助终端如查询机、电子屏导览这类场景中这些能力反而是风险面终端用户不应能随意打开任意文件、不应能跳到外部网页、不应能把界面改得面目全非。受限模式正是为这类场景设计的它是基于白名单的策略系统——配置文件中没有显式开启的功能一律默认禁用只放行你明确允许的权限。其官方文档位于 docs/md/Configure-for-restricted-use.md。启用方式一放置 sumatrapdfrestrict.ini 配置文件启用受限模式最直接的方式是把配置文件sumatrapdfrestrict.ini放到与SumatraPDF.exe同级的目录中。程序启动时会在可执行文件所在目录查找该文件源码中的文件名为常量kRestrictionsFileName sumatrapdfrestrict.ini见 src/SumatraPDF.cpp找到即进入受限模式。仓库根目录下就提供了一份完整可用的示例配置docs/sumatrapdfrestrict.ini。将它复制到SumatraPDF.exe旁边并按其注释修改即可生效。配置文件的解析与语义如下所有布尔型开关的值只能是0禁用或1启用文件中未写出的开关默认视为0禁用——这正是白名单设计的体现配置写在[Policies]小节内如果文件损坏、无法解析出[Policies]小节程序会按最严格处理即全部功能禁用源码注释err on the side of full restriction见 src/SumatraPDF.cpp不会出现解析失败反而放开权限的危险行为。启用方式二-restrict 命令行参数除了配置文件还可以用-restrict命令行参数进入受限模式。在 src/Flags.cpp 中解析到Arg::Restrict时会设置i.restrictedUse true随后启动流程在 src/SumatraPDF.cpp 调用InitializePolicies(flags.restrictedUse)。需要特别注意源码中的一条注释与逻辑src/SumatraPDF.cpp-restrict命令行参数优先于sumatrapdfrestrict.ini配置文件——一旦传入-restrict程序直接进入全受限状态仅保留Perm::RestrictedUse标记本身配置文件不再参与放行。换句话说只放sumatrapdfrestrict.ini按文件内容放行指定权限只传-restrict全部权限禁用无法再放行两者都没有一切权限放开正常运行模式。[Policies] 小节全部开关详解以下 7 个开关对应 docs/sumatrapdfrestrict.ini 中[Policies]小节的全部布尔项每一个都映射到源码 src/SumatraPDF.h 中enum class Perm的一个位标记配置项默认值含义对应的 Perm 位InternetAccess1允许访问互联网用于检查更新、发送崩溃报告Perm::InternetAccessDiskAccess1允许访问文件系统打开/保存文件、跟随超链接打开浏览器、启动外部 PDF 查看器 / LaTeX 源码编辑器 / 媒体播放器、显示经常阅读页、重开最近文件Perm::DiskAccessSavePreferences1退出时保存用户偏好修改设置、收藏夹菜单、记住最近打开的文件Perm::SavePreferencesRegistryAccess1允许写注册表用于把 SumatraPDF 注册为默认 PDF 查看器Perm::RegistryAccessPrinterAccess1允许打印文档Perm::PrinterAccessCopySelection1允许选择并复制内容鼠标选择、全选、复制选区Perm::CopySelectionFullscreenAccess1允许全屏与演示Presentation模式Perm::FullscreenAccess示例一个只允许阅读、打印但禁止联网、禁止选择复制、禁止全屏、禁止写注册表与保存偏好的最小配置如下[Policies] InternetAccess 0 DiskAccess 1 SavePreferences 0 RegistryAccess 0 PrinterAccess 1 CopySelection 0 FullscreenAccess 0注意示例文件中各项默认值为1但那只代表示例文件放行这些功能。实际部署时把不需要的项删掉即可——未出现的项按0处理从而被禁用。两个白名单参数LinkProtocols 与 SafeFileTypes除了 7 个布尔开关[Policies]小节还有两个逗号分隔的白名单参数它们只在DiskAccess 1时才会被读取源码 src/SumatraPDF.cppLinkProtocols——文档内链接允许传递给操作系统如交给浏览器打开的协议白名单。示例默认值http,https,mailto网页链接与电子邮件地址源码中当配置文件不存在时的内置默认值更宽一些kDefaultLinkProtocols http,https,mailto,filesrc/SumatraPDF.cpp解析时会做小写化并把空格、冒号、分号统一替换为逗号后切分所以写http, https; mailto也能被正确解析。SafeFileTypes——被PDF 等文档链接、且 SumatraPDF 自身无法打开、需要交给外部应用处理的文件类型白名单按注册表中的PerceivedType判定。常见取值audio、video、image、document、text、system示例默认值audio,video,webpage源码内置默认值kDefaultFilePerceivedTypes audio,video,webpagesrc/SumatraPDF.cpp特殊值*表示放行所有文件类型源码注释明确标注不推荐.htm、.html、.xhtml会强制按webpage类型处理以便文档超链接可以打开本地网页src/SumatraPDF.cpp。这两个白名单的实际生效逻辑在 src/SumatraPDF.cppSumatraLaunchBrowser()先检查DiskAccess再校验 URL 的 scheme 是否命中gAllowedLinkProtocolsOpenFileExternally()则先检查DiskAccess再查扩展名对应的 PerceivedType 是否命中gAllowedFileTypes。也就是说即使DiskAccess 1文档里的file://或tel:等协议、以及不在白名单内的附件类型依旧会被拦下。源码级实现位掩码策略与检查点受限模式的实现并不依赖分散的if分支而是一套集中的位掩码权限系统权限定义enum class Perm用位标记定义 7 项权限Perm::All 0x0FFFFFF表示全部放行Perm::RestrictedUse 0x1000000是一个独立标记位只要配置文件存在或传了-restrict就会置位src/SumatraPDF.h。初始化InitializePolicies(restrict)在启动早期执行src/SumatraPDF.cpp——先处理-restrict再尝试读取 exe 同目录的sumatrapdfrestrict.ini文件不存在则全部放行文件存在则先置Perm::RestrictedUse再逐个把配置值为非 0 的权限位合并进gPolicyRestrictions。查询全局变量gPolicyRestrictions初始为Perm::All之后只做收窄HasPermission(Perm p)用(p gPolicyRestrictions) p判断某权限是否放行CanAccessDisk()则是DiskAccess的便捷封装src/SumatraPDF.cpp。检查点CanAccessDisk()/HasPermission(...)分布在命令处理、菜单项生成、更新检查等大量调用点中。例如 src/UpdateCheck.cpp 在受限/插件/压测环境下跳过更新检查src/SumatraPDF.cpp 在受限使用时不弹崩溃报告对话框崩溃报告的上报也依赖InternetAccess权限src/SumatraPDF.cpp。关联推断从 src/SumatraPDF.cpp 的AnnotationsAreDisabled()可以看出磁盘访问被禁时注解编辑也会被禁用注解需要写回原文件即无磁盘访问 ⇒ 无注解编辑这是权限之间的隐含联动属于从源码结构可以推断的结论。一个值得注意的细节Perm的位定义注释明确写着权限可通过 sumatrapdfrestrict.ini 或 -restrict 命令行标志撤销src/SumatraPDF.h说明这套机制面向的是部署级策略而非用户级偏好——它不依赖当前用户的设置而是由分发方决定。受限模式实际禁用的功能对照官方文档列出的禁用清单与上述权限位存在如下对应关系多数能力由DiskAccess、SavePreferences等底层权限间接关停打开新文件 → 依赖DiskAccess从 PDF 内启动 URL →SumatraLaunchBrowser()检查DiskAccessLinkProtocols白名单文本与图像选择 → 由CopySelection控制打印 → 由PrinterAccess控制受限时打印返回NoPermission见 src/Print.h修改默认设置 / 保存到磁盘 / 最近打开文件历史 / 收藏夹 / 经常阅读页 → 依赖SavePreferences文件历史菜单还会额外检查CanAccessDisk()见 src/SumatraPDF.cpp自动与手动更新检查 → 依赖InternetAccessTeX 预览SyncTeX支持 → 属于偏好项随SavePreferences受限注册为默认 PDF 查看器 → 由RegistryAccess控制用 Adobe Acrobat 打开、邮件发送 PDF → 依赖DiskAccess/InternetAccess提供的相应动作路径因此实际部署时一个典型的 Kiosk 配置通常是DiskAccess 0或仅保留阅读必需的项、其余全部关闭让用户只能浏览由命令行或参数指定的文档。区别补充受限模式 vs DisableAutoLinks 高级设置受限模式解决的是整体禁用某项能力的部署问题如果你只想针对单个行为做限制可以使用高级设置文件Settings菜单 →Advanced options...或命令面板CtrlK输入adv详见 docs/md/Advanced-options-settings.md。典型例子是DisableAutoLinks高级设置默认false见 docs/md/Advanced-options-settings.md它只禁用 PDF 文本中自动识别出来的 URL、邮箱与纯文本 DOI 链接即非嵌入式的、由 SumatraPDF 根据文本内容推断出来的链接不会禁用 PDF 中显式嵌入的超链接annotations / link annotations它通过普通高级设置持久化随SavePreferences生效适用于想关掉自动链接但不进入整体受限模式的场景。与之相对受限模式下的DiskAccess 0会拦截所有类型链接的跳转动作包括嵌入超链接因为启动浏览器这一动作本身就被禁止了。两种手段的差异可进一步参考 docs/md/Hyperlinks.md。部署与验证建议文件位置sumatrapdfrestrict.ini必须与SumatraPDF.exe同目录路径不允许被普通用户篡改否则受限形同虚设若用安装包分发建议放在程序目录并由安装器写入。行为验证仓库为受限模式提供了自动化测试钩子——src/SumatraControl.cpp 的TestGetPolicies控制命令会把InitializePolicies()实际授予的各项权限以restricted、internet、disk、prefs、registry、printer、copy、fullscreen的形式输出供 GHSA 安全测试断言配置是否按预期生效。你在自建部署验证脚本时也可以借助类似手段确认最终生效的权限集合。边界情况文件损坏时按全受限处理-restrict会覆盖配置文件全部禁用LinkProtocols/SafeFileTypes仅在DiskAccess 1时读取.htm/.html/.xhtml一律视为webpage。小结SumatraPDF 的受限模式是一套设计简洁、边界清晰的部署级权限系统一个文件或一个命令行参数即可把功能丰富的阅读器收敛为只能看、不能动的专用查看器且遵循默认全部禁用、显式白名单放行的安全原则。理解Perm位掩码、InitializePolicies()的启动时序以及DiskAccess/LinkProtocols/SafeFileTypes三层校验磁盘访问 → 协议 → 文件类型的调用链你就能根据 Kiosk、内嵌文档、受控查阅等具体场景精确地裁剪出最小可用的配置。【免费下载链接】sumatrapdfSumatraPDF reader项目地址: https://gitcode.com/gh_mirrors/su/sumatrapdf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 SumatraPDF 受限模式（Restricted Use）配置指南：用 sumatrapdfrestrict.ini 构建 Kiosk / 内嵌查看器
SumatraPDF 受限模式Restricted Use配置指南用 sumatrapdfrestrict.ini 构建 Kiosk / 内嵌查看器【免费下载链接】sumatrapdfSumatraPDF reader项目地址: https://gitcode.com/gh_mirrors/su/sumatrapdfSumatraPDF 内置了一套受限使用restricted use策略机制通过放置sumatrapdfrestrict.ini配置文件或传入-restrict命令行参数可以批量禁用打开新文件、打印、选择复制、外链跳转、联网更新、保存偏好等不适合自助终端与捆绑分发场景的功能。本文以官方配置文档为主体结合仓库内 docs/sumatrapdfrestrict.ini 与 src/SumatraPDF.cpp 的权限实现完整讲解受限模式的启用方式、全部策略开关、白名单语义与底层工作原理读完后你可以为任意部署环境定制一套最小权限的 PDF 阅读器。受限模式是什么适用于哪些场景SumatraPDF 默认是一个功能完整的 PDF/电子书阅读器可以打开新文件、打印、选择并复制内容、跟随文档内链接、自动检查更新、把自身注册为系统默认 PDF 查看器等。但在把 SumatraPDF 作为你软件文档的内嵌查看器或Kiosk 自助终端如查询机、电子屏导览这类场景中这些能力反而是风险面终端用户不应能随意打开任意文件、不应能跳到外部网页、不应能把界面改得面目全非。受限模式正是为这类场景设计的它是基于白名单的策略系统——配置文件中没有显式开启的功能一律默认禁用只放行你明确允许的权限。其官方文档位于 docs/md/Configure-for-restricted-use.md。启用方式一放置 sumatrapdfrestrict.ini 配置文件启用受限模式最直接的方式是把配置文件sumatrapdfrestrict.ini放到与SumatraPDF.exe同级的目录中。程序启动时会在可执行文件所在目录查找该文件源码中的文件名为常量kRestrictionsFileName sumatrapdfrestrict.ini见 src/SumatraPDF.cpp找到即进入受限模式。仓库根目录下就提供了一份完整可用的示例配置docs/sumatrapdfrestrict.ini。将它复制到SumatraPDF.exe旁边并按其注释修改即可生效。配置文件的解析与语义如下所有布尔型开关的值只能是0禁用或1启用文件中未写出的开关默认视为0禁用——这正是白名单设计的体现配置写在[Policies]小节内如果文件损坏、无法解析出[Policies]小节程序会按最严格处理即全部功能禁用源码注释err on the side of full restriction见 src/SumatraPDF.cpp不会出现解析失败反而放开权限的危险行为。启用方式二-restrict 命令行参数除了配置文件还可以用-restrict命令行参数进入受限模式。在 src/Flags.cpp 中解析到Arg::Restrict时会设置i.restrictedUse true随后启动流程在 src/SumatraPDF.cpp 调用InitializePolicies(flags.restrictedUse)。需要特别注意源码中的一条注释与逻辑src/SumatraPDF.cpp-restrict命令行参数优先于sumatrapdfrestrict.ini配置文件——一旦传入-restrict程序直接进入全受限状态仅保留Perm::RestrictedUse标记本身配置文件不再参与放行。换句话说只放sumatrapdfrestrict.ini按文件内容放行指定权限只传-restrict全部权限禁用无法再放行两者都没有一切权限放开正常运行模式。[Policies] 小节全部开关详解以下 7 个开关对应 docs/sumatrapdfrestrict.ini 中[Policies]小节的全部布尔项每一个都映射到源码 src/SumatraPDF.h 中enum class Perm的一个位标记配置项默认值含义对应的 Perm 位InternetAccess1允许访问互联网用于检查更新、发送崩溃报告Perm::InternetAccessDiskAccess1允许访问文件系统打开/保存文件、跟随超链接打开浏览器、启动外部 PDF 查看器 / LaTeX 源码编辑器 / 媒体播放器、显示经常阅读页、重开最近文件Perm::DiskAccessSavePreferences1退出时保存用户偏好修改设置、收藏夹菜单、记住最近打开的文件Perm::SavePreferencesRegistryAccess1允许写注册表用于把 SumatraPDF 注册为默认 PDF 查看器Perm::RegistryAccessPrinterAccess1允许打印文档Perm::PrinterAccessCopySelection1允许选择并复制内容鼠标选择、全选、复制选区Perm::CopySelectionFullscreenAccess1允许全屏与演示Presentation模式Perm::FullscreenAccess示例一个只允许阅读、打印但禁止联网、禁止选择复制、禁止全屏、禁止写注册表与保存偏好的最小配置如下[Policies] InternetAccess 0 DiskAccess 1 SavePreferences 0 RegistryAccess 0 PrinterAccess 1 CopySelection 0 FullscreenAccess 0注意示例文件中各项默认值为1但那只代表示例文件放行这些功能。实际部署时把不需要的项删掉即可——未出现的项按0处理从而被禁用。两个白名单参数LinkProtocols 与 SafeFileTypes除了 7 个布尔开关[Policies]小节还有两个逗号分隔的白名单参数它们只在DiskAccess 1时才会被读取源码 src/SumatraPDF.cppLinkProtocols——文档内链接允许传递给操作系统如交给浏览器打开的协议白名单。示例默认值http,https,mailto网页链接与电子邮件地址源码中当配置文件不存在时的内置默认值更宽一些kDefaultLinkProtocols http,https,mailto,filesrc/SumatraPDF.cpp解析时会做小写化并把空格、冒号、分号统一替换为逗号后切分所以写http, https; mailto也能被正确解析。SafeFileTypes——被PDF 等文档链接、且 SumatraPDF 自身无法打开、需要交给外部应用处理的文件类型白名单按注册表中的PerceivedType判定。常见取值audio、video、image、document、text、system示例默认值audio,video,webpage源码内置默认值kDefaultFilePerceivedTypes audio,video,webpagesrc/SumatraPDF.cpp特殊值*表示放行所有文件类型源码注释明确标注不推荐.htm、.html、.xhtml会强制按webpage类型处理以便文档超链接可以打开本地网页src/SumatraPDF.cpp。这两个白名单的实际生效逻辑在 src/SumatraPDF.cppSumatraLaunchBrowser()先检查DiskAccess再校验 URL 的 scheme 是否命中gAllowedLinkProtocolsOpenFileExternally()则先检查DiskAccess再查扩展名对应的 PerceivedType 是否命中gAllowedFileTypes。也就是说即使DiskAccess 1文档里的file://或tel:等协议、以及不在白名单内的附件类型依旧会被拦下。源码级实现位掩码策略与检查点受限模式的实现并不依赖分散的if分支而是一套集中的位掩码权限系统权限定义enum class Perm用位标记定义 7 项权限Perm::All 0x0FFFFFF表示全部放行Perm::RestrictedUse 0x1000000是一个独立标记位只要配置文件存在或传了-restrict就会置位src/SumatraPDF.h。初始化InitializePolicies(restrict)在启动早期执行src/SumatraPDF.cpp——先处理-restrict再尝试读取 exe 同目录的sumatrapdfrestrict.ini文件不存在则全部放行文件存在则先置Perm::RestrictedUse再逐个把配置值为非 0 的权限位合并进gPolicyRestrictions。查询全局变量gPolicyRestrictions初始为Perm::All之后只做收窄HasPermission(Perm p)用(p gPolicyRestrictions) p判断某权限是否放行CanAccessDisk()则是DiskAccess的便捷封装src/SumatraPDF.cpp。检查点CanAccessDisk()/HasPermission(...)分布在命令处理、菜单项生成、更新检查等大量调用点中。例如 src/UpdateCheck.cpp 在受限/插件/压测环境下跳过更新检查src/SumatraPDF.cpp 在受限使用时不弹崩溃报告对话框崩溃报告的上报也依赖InternetAccess权限src/SumatraPDF.cpp。关联推断从 src/SumatraPDF.cpp 的AnnotationsAreDisabled()可以看出磁盘访问被禁时注解编辑也会被禁用注解需要写回原文件即无磁盘访问 ⇒ 无注解编辑这是权限之间的隐含联动属于从源码结构可以推断的结论。一个值得注意的细节Perm的位定义注释明确写着权限可通过 sumatrapdfrestrict.ini 或 -restrict 命令行标志撤销src/SumatraPDF.h说明这套机制面向的是部署级策略而非用户级偏好——它不依赖当前用户的设置而是由分发方决定。受限模式实际禁用的功能对照官方文档列出的禁用清单与上述权限位存在如下对应关系多数能力由DiskAccess、SavePreferences等底层权限间接关停打开新文件 → 依赖DiskAccess从 PDF 内启动 URL →SumatraLaunchBrowser()检查DiskAccessLinkProtocols白名单文本与图像选择 → 由CopySelection控制打印 → 由PrinterAccess控制受限时打印返回NoPermission见 src/Print.h修改默认设置 / 保存到磁盘 / 最近打开文件历史 / 收藏夹 / 经常阅读页 → 依赖SavePreferences文件历史菜单还会额外检查CanAccessDisk()见 src/SumatraPDF.cpp自动与手动更新检查 → 依赖InternetAccessTeX 预览SyncTeX支持 → 属于偏好项随SavePreferences受限注册为默认 PDF 查看器 → 由RegistryAccess控制用 Adobe Acrobat 打开、邮件发送 PDF → 依赖DiskAccess/InternetAccess提供的相应动作路径因此实际部署时一个典型的 Kiosk 配置通常是DiskAccess 0或仅保留阅读必需的项、其余全部关闭让用户只能浏览由命令行或参数指定的文档。区别补充受限模式 vs DisableAutoLinks 高级设置受限模式解决的是整体禁用某项能力的部署问题如果你只想针对单个行为做限制可以使用高级设置文件Settings菜单 →Advanced options...或命令面板CtrlK输入adv详见 docs/md/Advanced-options-settings.md。典型例子是DisableAutoLinks高级设置默认false见 docs/md/Advanced-options-settings.md它只禁用 PDF 文本中自动识别出来的 URL、邮箱与纯文本 DOI 链接即非嵌入式的、由 SumatraPDF 根据文本内容推断出来的链接不会禁用 PDF 中显式嵌入的超链接annotations / link annotations它通过普通高级设置持久化随SavePreferences生效适用于想关掉自动链接但不进入整体受限模式的场景。与之相对受限模式下的DiskAccess 0会拦截所有类型链接的跳转动作包括嵌入超链接因为启动浏览器这一动作本身就被禁止了。两种手段的差异可进一步参考 docs/md/Hyperlinks.md。部署与验证建议文件位置sumatrapdfrestrict.ini必须与SumatraPDF.exe同目录路径不允许被普通用户篡改否则受限形同虚设若用安装包分发建议放在程序目录并由安装器写入。行为验证仓库为受限模式提供了自动化测试钩子——src/SumatraControl.cpp 的TestGetPolicies控制命令会把InitializePolicies()实际授予的各项权限以restricted、internet、disk、prefs、registry、printer、copy、fullscreen的形式输出供 GHSA 安全测试断言配置是否按预期生效。你在自建部署验证脚本时也可以借助类似手段确认最终生效的权限集合。边界情况文件损坏时按全受限处理-restrict会覆盖配置文件全部禁用LinkProtocols/SafeFileTypes仅在DiskAccess 1时读取.htm/.html/.xhtml一律视为webpage。小结SumatraPDF 的受限模式是一套设计简洁、边界清晰的部署级权限系统一个文件或一个命令行参数即可把功能丰富的阅读器收敛为只能看、不能动的专用查看器且遵循默认全部禁用、显式白名单放行的安全原则。理解Perm位掩码、InitializePolicies()的启动时序以及DiskAccess/LinkProtocols/SafeFileTypes三层校验磁盘访问 → 协议 → 文件类型的调用链你就能根据 Kiosk、内嵌文档、受控查阅等具体场景精确地裁剪出最小可用的配置。【免费下载链接】sumatrapdfSumatraPDF reader项目地址: https://gitcode.com/gh_mirrors/su/sumatrapdf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考