Python Synapse Client 镜像文档

镜像概述和主要用途

Python Synapse Client Docker镜像封装了Sage Bionetworks的Synapse平台Python客户端，提供与Synapse协作研究平台的交互能力。该平台支持团队共享数据、跟踪分析流程和协作开发，镜像可直接作为命令行工具使用，或作为Python库集成到数据科学工作流中，简化跨环境部署和依赖管理。

核心功能和特性

• 多版本支持：基于Python 3.9-3.13构建，兼容主流Python环境
• 双模式操作：支持命令行直接调用和Python库两种使用方式
• 完整数据交互：实现文件上传/下载、项目管理、数据矩阵处理等核心功能
• 目录同步工具：通过synapseutils支持本地目录与Synapse项目的递归同步
• 性能监控集成：内置OpenTelemetry支持，可跟踪API调用性能和数据传输指标
• 安全认证：支持Synapse个人访问令牌(auth token)认证，保障数据访问安全

使用场景和适用范围

• 学术研究协作：研究团队共享实验数据、分析代码和结果报告
• 自动化数据管理：集成到ETL流程，自动上传测序数据、分析结果到Synapse
• 跨平台开发：在Docker环境中统一开发、测试和生产环境的依赖配置
• 大型项目同步：通过清单文件批量管理成百上千个文件的上传与更新
• 性能优化：利用OpenTelemetry分析数据传输瓶颈，优化API调用效率

详细的使用方法和配置说明

镜像获取

假设镜像托管在Docker Hub，可通过以下命令拉取最新版本：

bash
docker pull synapseclient:latest

命令行工具基础使用

查看帮助信息

bash
docker run -it --rm synapseclient:latest synapse -h

下载Synapse数据

bash
# 使用auth token下载指定ID的数据到当前目录
docker run -it --rm -v $(pwd):/data synapseclient:latest \
  synapse -p your_auth_token get syn*** -o /data

Python库使用示例

基本登录与项目创建

1. 创建本地Python脚本（create_project.py）：

python
import synapseclient
from synapseclient.models import Project
import os

# 初始化客户端
syn = synapseclient.Synapse()
# 使用环境变量传入的认证令牌登录
syn.login(authToken=os.environ.get('SYNAPSE_AUTH_TOKEN'))

# 创建新项目
project = Project('Docker测试项目')
project.store()
print(f"项目创建成功，ID: {project.id}")

2. 运行容器执行脚本：

bash
docker run -it --rm \
  -v $(pwd):/app \
  -e SYNAPSE_AUTH_TOKEN=your_auth_token \
  synapseclient:latest \
  python /app/create_project.py

本地目录同步到Synapse

使用synapseutils同步整个目录结构：

1. 创建同步脚本（sync_directory.py）：

python
import synapseclient
import synapseutils
import os

syn = synapseclient.Synapse()
syn.login(authToken=os.environ.get('SYNAPSE_AUTH_TOKEN'))

# 配置路径（容器内路径，通过-v挂载本地目录）
local_dir = "/data/synapse_project"
project_id = "syn1234"  # 目标Synapse项目ID
manifest_path = f"{local_dir}/sync_manifest.tsv"

# 生成同步清单
synapseutils.generate_sync_manifest(
    syn,
    directory_path=local_dir,
    parent_id=project_id,
    manifest_path=manifest_path
)

# 执行同步
synapseutils.syncToSynapse(
    syn,
    manifestFile=manifest_path,
    sendMessages=False
)
print(f"同步完成，清单文件路径: {manifest_path}")

2. 运行同步命令：

bash
docker run -it --rm \
  -v $(pwd)/synapse_project:/data/synapse_project \
  -e SYNAPSE_AUTH_TOKEN=your_auth_token \
  synapseclient:latest \
  python /data/synapse_project/sync_directory.py

认证配置

环境变量传递认证令牌（推荐）

通过SYNAPSE_AUTH_TOKEN环境变量传入令牌，避免明文暴露：

bash
docker run -e SYNAPSE_AUTH_TOKEN=your_auth_token synapseclient:latest ...

持久化认证状态

挂载Synapse配置目录（默认~/.synapse）以保留登录状态：

bash
# 首次登录并保存认证信息
docker run -it --rm \
  -v ~/.synapse:/root/.synapse \
  synapseclient:latest \
  synapse login --auth-token your_auth_token

# 后续使用无需重复登录
docker run -it --rm \
  -v ~/.synapse:/root/.synapse \
  -v $(pwd):/data \
  synapseclient:latest \
  synapse get syn*** -o /data

OpenTelemetry性能监控配置

启动Jaeger跟踪后端

bash
docker run --name jaeger \
  -e COLLECTOR_OTLP_ENABLED=true \
  -p ***:*** \  # Jaeger UI
  -p 4318:4318 \      # OTLP HTTP收集端点
  jaegertracing/all-in-one:latest

运行客户端并启用跟踪

bash
docker run -it --rm \
  -e SYNAPSE_AUTH_TOKEN=your_auth_token \
  -e OTEL_SERVICE_NAME=synapse-data-sync \
  -e OTEL_EXPORTER_OTLP_ENDPOINT=[***] \
  synapseclient:latest \
  python -c "import synapseclient; synapseclient.Synapse.enable_open_telemetry(); syn = synapseclient.Synapse(); syn.login(authToken=os.environ['SYNAPSE_AUTH_TOKEN']); syn.get('syn***')"

访问Jaeger UI（http://localhost:***），在"Service"下拉框选择`synapse-data-sync`查看跟踪数据。

高级配置：自定义OpenTelemetry资源属性

在Python代码中配置自定义跟踪属性：

python
import synapseclient

# 启用OpenTelemetry并添加自定义资源属性
synapseclient.Synapse.enable_open_telemetry(
    resource_attributes={
        "deployment.environment": "production",
        "service.version": "3.1.0",
        "experiment.id": "EXP-2024-001"
    }
)

# 后续正常使用客户端
syn = synapseclient.Synapse()
syn.login(authToken=os.environ.get('SYNAPSE_AUTH_TOKEN'))

许可证信息

本镜像包含的Python Synapse Client软件版权归2013-2025 Sage Bionetworks所有，采用Apache License, Version 2.0许可协议。