trivadis/dataverse-previewers-provider

Dataverse Previewers

镜像概述和主要用途

Dataverse Previewers是符合Dataverse外部工具接口的数据文件预览器集合，最初由Qualitative Data Repository开发。v1.4版本包含17个预览器，支持34+种MIME类型。早期Dataverse版本（v4.11+）通过数据集页面的外部工具按钮提供预览功能，较新版本（v4.18+）支持在数据文件页面嵌入显示，最新版本（5.2+）可区分"预览"和"探索"工具并在不同位置展示。自Dataverse 6.1起，预览器可使用临时签名URL（signedUrls）访问受限制文件，替代长期API令牌（signedUrls在Dataverse 5.13引入，6.1版本起支持数据集PrivateUrl访问）。

!https://github.com/gdcc/dataverse-previewers/blob/master/examples/datasetdisplay.png?raw=true !https://github.com/gdcc/dataverse-previewers/blob/master/examples/previewInPage.PNG?raw=true

核心功能和特性

• 多格式支持：v1.4支持34+种MIME类型，涵盖文本、图像、音频、视频、PDF、电子表格等多种文件格式
• Dataverse版本兼容：适配Dataverse v4.11+，针对v4.18+、5.2+、6.1+等版本提供增强功能
• 安全访问：支持Dataverse 6.1+的signedUrls机制，限制预览器仅访问特定API调用，且URL具有有限生命周期（如1小时），替代长期API令牌提升安全性
• 本地化部署：可通过脚本下载外部依赖并本地化部署，避免外部网站依赖
• Docker支持：提供Docker容器化部署方式，简化本地运行和管理
• 自定义品牌：支持使用Dataverse实例的favicon和自定义logo（240px宽×140px高推荐尺寸）

使用场景和适用范围

• Dataverse实例管理员需要为用户提供文件预览功能
• 需要本地部署预览器以避免外部依赖或满足安全合规要求
• 希望通过Docker简化预览器的部署和版本管理
• Dataverse 6.1+用户希望使用更安全的signedUrls机制访问受限制文件

使用方法和配置说明

安装（通过注册到Dataverse）

无需下载预览器，直接运行以下curl命令将其注册到本地Dataverse实例（也可创建本地副本并注册）：

bash
# 示例：注册文本预览器（具体命令需根据Dataverse版本和需求选择，详见后续"示例Curl命令"部分）
curl -X POST http://localhost:8080/api/admin/externalTools \
  -H "Content-Type: application/json" \
  -d '{"displayName":"Text Previewer","description":"Preview text files","toolUrl":"https://gdcc.github.io/dataverse-previewers/previewers/v1.4/TextPreview.html","type":"preview","mimeType":"text/plain","toolParameters":{"queryParameters":{"fileid":"{fileId}","datasetid":"{datasetId}","signedUrl":"{signedUrl}"}}}'

注：如需启用国际化（要求Dataverse发送localeCode给预览器），需先删除现有预览器注册（使用Dataverse externalTools API），再用更新后的curl命令重新注册。

更新

API方法

1. 列出所有已注册预览器：

   bash
   curl http://localhost:8080/api/admin/externalTools
   

2. 根据ID删除每个旧版本：

   bash
   curl -X DELETE http://localhost:8080/api/admin/externalTools/<id>
   

3. 按照新安装说明重新注册

数据库方法

通过SQL更新externaltool表的toolurl列以更改仓库或版本：

sql
-- 示例：更新仓库和版本
update externaltool set toolurl=REPLACE(toolurl, 'globaldataversecommunityconsortium.github.io/dataverse-previewers/previewers', 'gdcc.github.io/dataverse-previewers/previewers/v1.1');

-- 仅更新版本
update externaltool set toolurl=REPLACE(toolurl, 'v1.2', 'v1.3');

完全本地安装

默认情况下，预览器引用外部JavaScript库和样式文件。如需本地安装（不依赖外部网站），可使用localinstall.sh脚本：

1. 下载仓库到本地
2. 进入脚本所在根目录
3. 运行：

   bash
   ./localinstall.sh previewers/v1.4 https://<your host>/<your base path to the previewers>
   

   脚本将下载指定版本所需的所有外部JavaScript和CSS文件，并更新6.1curlcommands.md、5.2curlcommands.md和pre5.2curlcommands.md中的示例配置命令，以引用本地URL。

Docker部署

支持通过Docker容器本地运行预览器：

docker run命令

bash
docker run --rm --name dataverse-previewers-provider \
  -e PREVIEWERS_PROVIDER_URL=http://localhost:8088 \
  -e VERSIONS="v1.4,betatest" \
  -p 8088:80 \
  trivadis/dataverse-previewers-provider:latest

• 环境变量说明：
  • PREVIEWERS_PROVIDER_URL：预览器暴露的基础URL（格式：http(s):///）
  • VERSIONS：要运行的预览器版本列表（逗号分隔）

访问预览器

启动后可通过以下URL访问预览器（以TextPreview为例）：

http://localhost:8088/previewers/v1.4/TextPreview.html

工作原理

预览器是基于标准HTML5功能（如audio、video）、第三方库（如PDF、电子表格处理库）或两者结合的轻量级包装器。例如：

• 标准图像显示结合第三方库实现缩放功能
• 简单文本/HTML显示结合第三方库进行内容 sanitize 以避免安全问题

自定义

• Favicon：如Dataverse默认位置存在favicon（<your site URL>/javax.faces.resource/images/favicondataverse.png.xhtml），预览器将自动使用
• Logo：在<your site URL>/logos/preview_logo.png添加logo（默认对应Payara/Glassfish的./docroot/logos目录下的同名文件），预览器将在左上角显示（推荐尺寸240px宽×140px高），默认显示空白白色图像

已知限制

• 权限要求：预览受限制内容需用户具有查看相关数据集版本和下载文件的权限；公开/已发布内容无需认证
• 认证机制：signedUrls（Dataverse 6.1+）推荐使用，限制API调用范围和生命周期；API令牌长期有效且权限范围广，需谨慎使用（如在公共电脑使用后建议重新生成）
• 文件创建日期：仅在Dataverse v4.12+中显示在标题中
• 视频Seek功能：部分浏览器和Dataverse实例不支持，因部分Dataverse存储IO驱动不支持部分文件下载（目前Chrome不支持，Firefox支持）
• TIFF图像预览：仅部分浏览器支持，因此相关MIME类型注册已从列表中移除

示例Curl命令

以下示例配置指向https://github.io/gdcc/%E6%8C%87%E5%AE%9A%E5%88%86%E6%94%AF%E7%9A%84%E9%A2%84%E8%A7%88%E5%99%A8%EF%BC%8C%E5%A6%82%E9%9C%80%E4%BD%BF%E7%94%A8%E6%97%A7%E7%89%88%E6%9C%AC%E6%88%96%E6%9C%AC%E5%9C%B0%E5%AE%89%E8%A3%85%E7%89%88%E6%9C%AC%EF%BC%8C%E5%8F%AF%E4%BF%AE%E6%94%B9%22toolUrl%22%EF%BC%9A

• Previewers v1.4（含测试版新预览器，如3D预览器）：
  • Dataverse 6.1+ - 使用SignedUrls
  • Dataverse 5.2+ - 使用API令牌（不推荐用于Dataverse 6.0+）
• Previewers v1.3（不含新预览器，适用于Dataverse < v5.2）：
  • Dataverse <= v5.1