OHIF DICOMweb Proxy 数据源基于 JSON 配置的动态 DICOMweb 代理接入指南【免费下载链接】ViewersOHIF zero-footprint DICOM viewer and oncology specific Lesion Tracker, plus shared extension packages项目地址: https://gitcode.com/GitHub_Trending/vi/Viewers在 OHIF Viewer 中DICOMweb Proxy 是一种特殊的动态数据源只需提供一个返回 JSON 配置文件的外部 URLOHIF 便会读取其中的 DICOMweb 服务配置动态构造一个完整的 DICOMweb 数据源并把后续的元数据查询、影像检索与存储请求全部委托给该服务。本文以仓库中的配置文档为主线结合extensions/default扩展的源码实现讲解其工作原理、JSON 配置结构、URL 调用方式与安全边界帮助你在不修改前端代码的前提下将 OHIF Viewer 动态接入任意 DICOMweb 服务。什么是 DICOMweb ProxyDICOMweb Proxy 是ohif/extension-default扩展注册的webApi类型数据源其核心思路是配置不写死在应用里而是通过 URL 动态下发。你可以用一个带有dicomwebproxy路径的 URL 启动 OHIF Viewer该 URL 的查询参数指向一份返回 JSON 的远程地址JSON 中含有一个 DICOMweb 配置。OHIF 解析该配置后构造 DICOMweb 数据源并委托后续的元数据与影像请求到配置中指定的服务器https://viewer.ohif.org/viewer/dicomwebproxy?urlhttps://ohif-dicom-json-example.s3.amazonaws.com/dicomweb.json其中url查询参数的值即 JSON 文件所在位置例如上例中的https://ohif-dicom-json-example.s3.amazonaws.com/dicomweb.json该文件在编写本文档时并不存在仅作示例。文档中特别指出DICOMweb Proxy 的使用方式与 DICOM JSON 数据源 十分相似——两者都是通过?url动态加载配置区别在于 DICOM JSON 加载的是静态 JSON 元数据而 DICOMweb Proxy 加载的是 DICOMweb 服务配置随后与真实服务器进行 DICOMweb 协议交互。JSON 配置结构servers.dicomWeb 数组url参数返回的 JSON 中必须包含一个servers对象其下有一个名为dicomWeb的配置数组。DICOMweb Proxy 只取数组的第一项来构造数据源多出的项会被忽略。下面是最小可用的示例配置完整来自 关联文档{ servers: { dicomWeb: [ { name: DCM4CHEE, wadoUriRoot: https://server.dcmjs.org/dcm4chee-arc/aets/DCM4CHEE/wado, qidoRoot: https://server.dcmjs.org/dcm4chee-arc/aets/DCM4CHEE/rs, wadoRoot: https://server.dcmjs.org/dcm4chee-arc/aets/DCM4CHEE/rs, qidoSupportsIncludeField: true, supportsReject: true, imageRendering: wadors, thumbnailRendering: wadors, enableStudyLazyLoad: true, supportsFuzzyMatching: true, supportsWildcard: true } ] } }各字段含义与作用字段说明name数据源展示名称例如DCM4CHEE用于标识后端归档wadoUriRootWADO-URI 请求的根地址对应/wado端点qidoRootQIDO-RS 查询服务的根地址对应/rs端点wadoRootWADO-RS 检索服务的根地址对应/rs端点qidoSupportsIncludeField服务端 QIDO 是否支持includefield查询参数supportsReject服务端是否支持 reject 操作imageRendering影像渲染方式常用wadorsthumbnailRendering缩略图渲染方式常用wadorsenableStudyLazyLoad是否启用 study 级懒加载supportsFuzzyMatching是否支持模糊匹配查询supportsWildcard是否支持通配符查询提示qidoRoot、wadoRoot与可选的stowRoot是相互独立的绝对 URL不必共享同一主机或路径前缀——QIDO、WADO、STOW 三类服务可分别路由到各自的根地址。此外由于 DICOMweb Proxy 最终把配置委托给 DICOMweb 数据源处理DICOMweb 数据源 文档中介绍的全部配置选项如singlepart、thumbnailRendering、thumbnailRequestStrategy、queryLimit、bulkDataURI、dicomUploadEnabled等同样适用于 JSON 中的服务器配置可在远程 JSON 中直接使用。例如{ servers: { dicomWeb: [ { name: Orthanc, qidoRoot: https://pacs.example.org/dicom-web, wadoRoot: https://pacs.example.org/dicom-web, imageRendering: wadors, thumbnailRendering: rendered, thumbnailRequestStrategy: fetch, queryLimit: 101, bulkDataURI: { enabled: true, relativeResolution: series } } ] } }源码实现如何动态构造 DICOMweb 数据源DICOMweb Proxy 的核心实现位于 extensions/default/src/DicomWebProxyDataSource/index.ts它在数据源注册模块 getDataSourcesModule.js 中以dicomwebproxy名称注册type为webApi。初始化流程initialize是动态代理的关键入口其工作流程为读取 URL从查询参数中读取url若缺失则抛出No url for name错误安全校验调用resolveConfigFetchPolicy(url, ...)校验目标 URL 的协议、同源关系与来源白名单详见下文“安全边界”拉取 JSON通过fetchConfigJson以 CORS 方式 GET 远程 JSON结构校验若返回的数据中缺少data.servers?.dicomWeb?.[0]抛出Invalid configuration returned by url委托构造以data.servers.dicomWeb[0].configuration || data.servers.dicomWeb[0]为配置调用 DICOMweb 数据源的createDicomWebApi构造委托数据源随后调用其initialize。注意第 5 步的兼容逻辑如果数组第一项内部存在configuration子对象则以子对象为准否则直接使用该项本身——这允许远程 JSON 在服务信息外层再包一层configuration。委托的接口面构造完成后代理对象把 DICOMweb 数据源的接口逐项转发形成完整的IWebApiDataSource实现query.studies.search/query.series.search/query.instances.search研究、序列、实例三级查询retrieve.getGetThumbnailSrc/retrieve.directURL/retrieve.renderedURL缩略图与影像直链/渲染 URLretrieve.series.metadata序列元数据检索store.dicomDICOM 存储STOW-RSreject.series、deleteStudyMetadataPromise、getImageIdsForDisplaySet、getImageIdsForInstance、getConfig其余委托能力。getConfig在委托尚未建立时返回{ dicomUploadEnabled: false }作为安全默认值。另外getStudyInstanceUIDs直接从查询参数读取studyInstanceUIDs兼容studyInstanceUids的大小写变体以分号;分隔解析为数组——这一逻辑与模式路由中按数据源路径进入工作区的机制配合用于指定要加载的研究列表。URL 查询参数读取从源码可见初始化时通过query.get(url)读取配置地址。也就是说完整的调用形态为在/viewer/dicomwebproxy路径后携带?urljson地址查询参数如文档开头的示例所示。在应用配置中启用 dicomwebproxyDICOMweb Proxy 需要在应用的dataSources数组中注册才会生效。参考开发环境配置 platform/app/public/config/dev.js{ namespace: ohif/extension-default.dataSourcesModule.dicomwebproxy, sourceName: dicomwebproxy, configuration: { friendlyName: dicomweb delegating proxy, name: dicomwebproxy, }, },namespace指向扩展注册的数据源模块标识sourceName为数据源名称模式路由通过/mode/dicomwebproxy这类路径定位到该数据源configuration.name用于初始化错误信息中的数据源标识configuration.friendlyName为界面展示名称。值得注意的是默认生产配置 platform/app/public/config/default.js 中刻意不启用dicomwebproxy以及dicomlocal、dicomjson等动态源并注释说明?url类运行时源会扩大默认部署的攻击面应在受控的部署环境中按需开启。KHEOPS 等特定部署也会在自己的配置如 kheops.js中注册该数据源并通过 OHIF 路径对接/viewer/dicomwebproxy。安全边界authenticated 环境下的来源白名单DICOMweb Proxy 通过 secureConfigFetch.js 中的resolveConfigFetchPolicy实施严格的 URL 校验协议限制仅允许http:与https:其他协议直接拒绝禁止片段与用户信息URL 中不得包含#片段也不得携带username:password用户信息同源放行若配置 URL 与应用同源直接放行已认证环境的白名单当存在已登录的userAuthenticationService即携带 Authorization 头且配置 URL 非同源时必须命中dangerouslyAllowedOriginsForAuthenticatedEnvironments配置的白名单裸源格式scheme host 可选端口不允许带路径、查询、hash 或用户信息否则抛出Blocked remote configuration origin ...错误。fetchConfigJson以mode: cors、credentials: same-origin、redirect: error、referrerPolicy: no-referrer发起 GET 请求响应非 2xx 时抛出带状态码的错误。该安全策略在 secureConfigFetch.test.js 中有对应测试覆盖。在 DICOMweb Proxy 数据源中白名单通过数据源配置的dangerouslyAllowedOriginsForAuthenticatedEnvironments传入{ namespace: ohif/extension-default.dataSourcesModule.dicomwebproxy, sourceName: dicomwebproxy, configuration: { name: dicomwebproxy, friendlyName: dicomweb delegating proxy, dangerouslyAllowedOriginsForAuthenticatedEnvironments: [ https://config.example.org, ], }, },从字段名中的dangerously可以推断这是为受信任环境准备的配置用于在已认证携带凭证的前提下允许跨源加载动态数据源配置需要部署者仔细权衡安全影响。典型使用场景与注意事项适用场景多租户 / 多归档接入同一套 OHIF 前端根据 URL 参数动态切换不同的 DICOMweb 后端如 DCM4CHEE、Orthanc 等无需重新构建应用配置下发与运维解耦服务端可随时更新 JSON 配置如切换服务器地址、调整supportsWildcard等能力开关前端无需发版托管平台集成外部平台如 KHEOPS在自己的服务端维护配置通过/viewer/dicomwebproxy?url...将患者数据路由到对应归档。注意事项JSON 配置必须包含servers.dicomWeb数组且非空否则数据源初始化会直接报错只使用数组第一项多余配置不会生效代理委托的是 DICOMweb 数据源因此 DICOMweb 配置文档 中关于服务端能力supportsReject、supportsFuzzyMatching、supportsWildcard、qidoSupportsIncludeField、bulkDataURI相对路径解析relativeResolution: studies | series等的说明同样适用生产环境默认不启用该数据源需在受控部署中显式注册并结合dangerouslyAllowedOriginsForAuthenticatedEnvironments白名单约束跨源加载。总结DICOMweb Proxy 为 OHIF Viewer 提供了一种“配置即 URL”的动态接入能力前端通过?url参数获取远端 JSON动态构造 DICOMweb 数据源并委托全部后续请求。其实现集中在 DicomWebProxyDataSource/index.ts配合 secureConfigFetch.js 的协议校验与认证环境白名单机制兼顾了灵活性与安全性。对于需要多归档接入、配置热更新或平台托管集成的场景DICOMweb Proxy 是与 DICOM JSON 数据源互补的重要方案。【免费下载链接】ViewersOHIF zero-footprint DICOM viewer and oncology specific Lesion Tracker, plus shared extension packages项目地址: https://gitcode.com/GitHub_Trending/vi/Viewers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考