flywheel/deid-log

flywheel/deid-log

该deid-log服务已归档，不再用于生产环境。

去标识日志API（De-Identification Logging API）允许客户端在将去标识数据集上传到Flywheel前，将原始DICOM标签持久化到数据库中。随后可基于一组索引标签通过SQL查询deid-log记录，或通过deid-log ID与上传到Flywheel的文件进行交叉引用。入站请求通过配置的Flywheel Core实例进行认证。

mermaid
sequenceDiagram
    CLIENT  ->>+ DEIDLOG : POST /logs {deid_tags: {...}}
    DEIDLOG ->>+ CORE    : 授权请求
    CORE    ->>- DEIDLOG : 请求认证通过
    DEIDLOG ->>- CLIENT  : {id: d34db33f}
    CLIENT  ->>  CORE    : POST /upload {deid_log_id: d34db33f, data: ...}

镜像概述与主要用途

deid-log服务提供DICOM标签去标识日志记录功能，核心用途是在***数据去标识处理流程中，留存原始DICOM标签信息并支持后续查询与追溯。通过该服务，客户端可在数据去标识后、上传至Flywheel平台前，将关键原始标签存储到数据库，为数据审计、回溯及关联分析提供支持。

核心功能与特性

• DICOM标签持久化：支持将原始DICOM标签（如患者ID、检查UID等）存储到数据库
• 多数据库支持：已测试并支持SQLite、PostgreSQL和MySQL作为后端数据库
• 认证集成：通过Flywheel Core实例对请求进行身份验证
• 索引查询：基于预设索引标签（如StudyInstanceUID、PatientID等）支持SQL查询
• ID交叉引用：通过deid-log ID与Flywheel平台上传的文件建立关联
• 自动表结构创建：服务启动时自动创建数据库表结构

使用场景与适用范围

适用于***影像数据处理场景，特别是需要对DICOM文件进行去标识处理并保留原始标签记录的流程，例如：

• ***数据合规存档与审计
• 去标识数据与原始数据的追溯关联
• 多系统间数据流转的标签一致性校验
• 科研数据管理中原始信息的安全留存

使用方法与配置说明

支持的数据库后端

deid-log支持并测试以下数据库后端：

• SQLite（默认）
• PostgreSQL
• MySQL/MariaDB

使用SQLite运行

默认数据库后端为SQLite，HTTP API运行在容器内8000端口。如需在主机相同端口暴露服务：

bash
docker run --name deid-log -d -p 8000:8000 \
    -e FW_DEID_LOG_CORE_URL=https://local.flywheel.io \
    flywheel/deid-log

默认SQLite数据库文件存储在容器内/data目录下的Docker卷中。建议按上述示例让Docker管理存储。如需将SQLite数据库存储在主机指定目录，可通过-v /host/data/dir:/data进行绑定挂载。

使用PostgreSQL运行

bash
# 创建网络
docker network create deid-net

# 启动PostgreSQL容器
docker run --network deid-net --name postgres -d \
    -e POSTGRES_DB=db \
    -e POSTGRES_USER=user \
    -e POSTGRES_PASSWORD=pass \
    postgres:12-alpine

# 启动deid-log容器
docker run --network deid-net --name deid-log -d -p 8000:8000 \
    -e FW_DEID_LOG_DB_URL=postgresql://user:pass@postgres:5432/db \
    -e FW_DEID_LOG_CORE_URL=https://local.flywheel.io \
    flywheel/deid-log

使用MySQL/MariaDB运行

bash
# 创建网络
docker network create deid-net

# 启动MySQL容器（或使用mariadb:10）
docker run --network deid-net --name mysql -d \
    -e MYSQL_DATABASE=db \
    -e MYSQL_USER=user \
    -e MYSQL_PASSWORD=pass \
    -e MYSQL_ROOT_PASSWORD=root \
    mysql:5  # 或 mariadb:10

# 启动deid-log容器
docker run --network deid-net --name deid-log -d -p 8000:8000 \
    -e FW_DEID_LOG_DB_URL=mysql://user:pass@mysql:3306/db \
    -e FW_DEID_LOG_CORE_URL=https://local.flywheel.io \
    flywheel/deid-log

使用Helm部署

查看helm文档了解如何通过Chart部署。

环境变量配置

查询deid-log数据库

数据库表结构

deid-log会自动创建并使用单个数据库表deid_log：

plaintext
sqlite> .schema deid_log
CREATE TABLE deid_log (
    id BINARY(16) NOT NULL,
    created DATETIME,
    timestamp DATETIME,
    "AccessionNumber" VARCHAR(16),
    "PatientBirthDate" VARCHAR(8),
    "PatientID" VARCHAR(64),
    "PatientName" VARCHAR(512),
    "StudyInstanceUID" VARCHAR(64),
    "StudyID" VARCHAR(16),
    "StudyDate" VARCHAR(8),
    "StudyTime" VARCHAR(16),
    "StudyDateTime" VARCHAR(26),
    "StudyDescription" VARCHAR(64),
    "SeriesInstanceUID" VARCHAR(64),
    "SeriesDate" VARCHAR(8),
    "SeriesTime" VARCHAR(16),
    "SeriesDateTime" VARCHAR(26),
    "SeriesDescription" VARCHAR(64),
    "TimezoneOffsetFromUTC" VARCHAR(16),
    "DeidentifiedTags" JSON NOT NULL,
    PRIMARY KEY (id)
);

按deid-log ID查询

plaintext
sqlite> SELECT PatientName FROM deid_log WHERE id = X'65774D086757457C9DCF96E762803606';
Doe^John

按索引字段过滤查询

plaintext
sqlite> SELECT SeriesInstanceUID FROM deid_log WHERE timestamp < '2006-08-31';
1.2.840.113619.2.62.994044785528.20060823223142485052

开发指南

环境准备

使用poetry安装项目依赖，并启用pre-commit：

bash
poetry install
pre-commit install

本地运行

启用调试和代码热重载功能本地运行：

bash
FW_DEID_LOG_CORE_URL=https://local.flywheel.io \
FW_DEID_LOG_DB_URL=sqlite:///deid-log.sqlite3 \
gunicorn -c deid_log/config.py -w 1 --reload "deid_log.app:create_app()"

API文档

访问http://localhost:8000/docs可浏览OpenAPI文档。

API请求示例

集成上传服务需使用POST /logs接口，发送包含索引字段和去标识DICOM JSON标签的 payload：

json
{
  "indexed_fields": {
    "AccessionNumber": "10523475",
    "PatientID": "0000680029",
    "PatientName": "Doe^John"
  },
  "deidentified_tags": {
    "00100010": {"vr": "PN", "Value": [{"Alphabetic": "QA_1TX"}]},
    "00080012": {"vr": "DA", "Value": ["20200505"]},
    "00291020": {"vr": "OB", "InlineBinary": "YQ=="}
  }
}

许可证

代码仓库

flywheel-io/tools/app/deid-log