English | 简体中文

nf-tencentcloud

简介

nf-tencentcloud 为 Nextflow 提供腾讯云 COS 对象存储和腾讯健康组学平台执行器支持，包括 cos:// 路径、通过平台 TES 接口提交任务，以及可选的工作流 metadata 输出。

目前仅在 master 维护 V3。 V1、V2 的历史 tag 和 Release 保留，不再提供后续更新。升级前请阅读 V3 迁移指南。

快速开始

环境要求

插件 manifest 声明最低 Nextflow 版本为 25.10.2。这表示最低版本要求，不代表保证兼容所有未来版本。
插件字节码要求 Java 17 或更高版本；构建和运行回归测试使用 JDK 21。
使用 COS 需要存储桶、对应地域和具备所需操作权限的凭据。
使用 tencentcloud-omics 执行器还需要已配置的腾讯健康组学平台环境及其 TES 接口访问权限。

从 GitHub Release 安装

3.0.5 Release 提供插件 ZIP 和 SHA256SUMS。GitHub 自动生成的源码归档不能作为插件包安装。

在 Linux 或 macOS 的 Bash 中运行以下命令。它会校验 SHA-256，将 ZIP 中的 classes/ 和 lib/ 安装到插件目录，并拒绝覆盖已有版本：

(
  set -eu
  plugin_version=3.0.5
  plugin_root="${NXF_PLUGINS_DIR:-${NXF_HOME:-$HOME/.nextflow}/plugins}"
  plugin_dir="$plugin_root/nf-tencentcloud-$plugin_version"
  release_url="https://github.com/Tencent/nf-tencentcloud/releases/download/$plugin_version"

  if [ -e "$plugin_dir" ] || [ -L "$plugin_dir" ]; then
    echo "Plugin directory already exists: $plugin_dir" >&2
    exit 1
  fi

  download_dir=$(mktemp -d)
  trap 'rm -rf "$download_dir"' EXIT
  curl --fail --location --silent --show-error \
    "$release_url/nf-tencentcloud-$plugin_version.zip" \
    --output "$download_dir/nf-tencentcloud-$plugin_version.zip"
  curl --fail --location --silent --show-error \
    "$release_url/SHA256SUMS" --output "$download_dir/SHA256SUMS"
  (cd "$download_dir" && shasum -a 256 -c SHA256SUMS)

  mkdir -p "$plugin_root"
  mkdir "$plugin_dir"
  unzip -q "$download_dir/nf-tencentcloud-$plugin_version.zip" -d "$plugin_dir"
  test -f "$plugin_dir/classes/META-INF/MANIFEST.MF"
)

运行 Nextflow 时使用相同的 NXF_PLUGINS_DIR 或 NXF_HOME。如果安装在创建版本目录后失败，请先检查该不完整目录；上述命令不会覆盖它。目录布局依据 Nextflow 25.10.2 的插件加载实现。

在 nextflow.config 中固定已安装版本：

plugins {
    id 'nf-tencentcloud@3.0.5'
}

也可以给 nextflow run 添加 -plugins nf-tencentcloud@3.0.5。工作流使用的其他插件仍需预先安装，或通过各自的分发渠道获取。

插件注册表状态

创建 GitHub Release 不等于向 Nextflow 插件注册表发布版本。上述安装方式使用 GitHub ZIP，不假定 nextflow plugin install 已能下载 3.0.5。注册表发布需要单独取得插件所有权及访问令牌，详见官方发布说明。本仓库的 make release 只检查并打包已提交源码；make publish-registry 才执行独立的注册表发布操作。

使用示例

配置 COS

通过运行环境或密钥管理服务提供凭据。下面的环境变量名是示例约定，由配置显式读取；不要把真实密钥提交到工作流或配置仓库。

tencentcloud {
    region = System.getenv('TENCENTCLOUD_REGION')
    secretId = System.getenv('TENCENTCLOUD_SECRET_ID')
    secretKey = System.getenv('TENCENTCLOUD_SECRET_KEY')
    sessionToken = System.getenv('TENCENTCLOUD_SESSION_TOKEN')
}

params.input = 'cos://your-bucket-1234567890/input/sample.txt'
workDir = 'cos://your-bucket-1234567890/nextflow/work'

region 必须与存储桶实际地域一致，例如 ap-guangzhou。临时凭据需要提供 sessionToken；使用长期凭据时可不设置对应环境变量。tencentcloud.accessToken 不是 COS 凭据配置项。

托管环境可通过 /config/rclone/rclone.conf 中对应 bucket 的配置节，或 /config/cos-secret/<bucket> 挂载凭据。这两种来源依次优先于工作流配置。所选挂载来源的有效更新会轮换凭据；无效更新保留上一次有效凭据。更改 region 需要重新打开 filesystem。

插件及凭据配置完成后，可以通过 Nextflow 文件操作读取 COS：

nextflow.enable.dsl = 2

workflow {
    channel.fromPath(params.input, checkIfExists: true)
        .view { path -> path.text }
}

配置腾讯健康组学平台

请向平台管理员获取 TES endpoint 及所需的 bearer token。仅拥有 COS 账号并不代表具有平台执行器权限。产品信息见腾讯健康组学平台。

使用平台时，在 COS 配置之外添加：

tencentcloud {
    omics {
        endpoint = System.getenv('OMICS_TES_ENDPOINT')
        accessToken = System.getenv('OMICS_TES_ACCESS_TOKEN')
    }
}

process.executor = 'tencentcloud-omics'

使用所属环境提供的 endpoint；执行器会在需要时添加 /v1。tencentcloud.omics.accessToken 用于 TES 请求认证，与 COS 的 sessionToken 分开配置。

文件系统行为

COS 是对象存储，NIO 接口不提供完整的 POSIX 文件系统语义：

随机访问和追加会把对象暂存到本地磁盘，在 close 时整体上传，因此需要足够的本地临时磁盘空间。
rename 通过复制后删除完成；独占创建和替换不保证跨客户端原子性。不支持文件锁、软链接、POSIX 权限、SYNC 和 DSYNC。
Files.copy 对目录只复制目录本身；显式目录上传、下载会递归处理。不支持移动非空目录。
精确对象 name 优先于 name/；最后一个子对象删除后，隐式目录可能消失。
遍历时拒绝无法无损映射为 Java Path 的对象 key；目录下载拒绝不安全的本地路径、软链接及已有目标文件。
Files.isWritable 保守返回 false；实际写权限由 COS 校验。
关闭 filesystem 会关闭关联句柄，正常关闭写句柄可能发布待写数据；上传或本地暂存失败会向调用者报告。
默认流式上传分片缓冲为 10 MiB，最多 10,000 片，未知总长度流的上限约为 97.7 GiB；反复 flush 可能降低该上限。

元数据权限、并发与故障边界、资源消耗和测试覆盖见文件系统审计。上游实现对照说明了回归用例与 AWS、Google Cloud Storage、Nextflow 和 Java NIO 行为的对应关系。

构建与测试

选择 JDK 21 后运行：

./gradlew test jacocoTestReport check packagePlugin

安装包输出为 build/distributions/nf-tencentcloud-3.0.5.zip。测试默认离线运行。真实 COS 测试必须显式开启，并使用可清理的测试 bucket；配置方法见文件系统审计。离线测试通过不代表已验证当前账号的 COS 权限或平台连接。

贡献

问题报告、Pull Request 和验证要求见 CONTRIBUTING.md。

许可证

采用 Apache License 2.0，详见 LICENSE。保留既有 Tencent 及第三方署名说明。

支持

本插件由腾讯健康组学平台团队维护。可复现的插件问题请提交至 GitHub Issues；平台产品咨询请联系 omics@tencent.com。