VoxelFlow 基础镜像文档

概述和主要用途

VoxelFlow是一个Python框架，设计用于MRI数据集的大规模和小规模分析。它支持分析pipeline的实验与定义，并可进行规模化部署。本镜像作为VoxelFlow的基础运行环境，提供了框架运行所需的依赖、配置基础及部署支持。

核心功能和特性

• 多规模分析支持：适用于大小规模MRI数据集分析，支持科研与临床研究场景
• 分布式计算：支持分布式模式，可将任务分配到多节点集群，无需依赖HPC环境
• 灵活数据存储：集成MongoDB数据库，支持GridFS、S3、GCS等多种存储后端
• 快照与备份：支持数据快照功能，可增量备份至S3存储桶，实现高效数据保护
• 系统监控：内置/api/health-check健康检查端点，支持系统状态与资源监控
• 安全特性：支持双因素认证、审计日志、登录失败锁定等安全功能
• 开发工具链：包含前端开发环境、测试框架、文档构建工具等完整开发支持

使用场景和适用范围

• 医学影像分析：处理MRI数据集，支持影像预处理、量化分析等科研工作
• 分布式部署：在多台普通计算机组成的集群中部署，加速大规模数据处理
• 开发与测试：作为框架开发基础，支持本地开发、单元测试、CI流程验证
• 生产环境：配置MongoDB与分布式模式后，可稳定运行于生产环境，提供可靠服务

安装与使用方法

从源码安装VoxelFlow

1. 克隆代码仓库：

   bash
   git clone [***]
   cd voxelflow
   

2. 安装系统依赖：

   • macOS：

     bash
     brew install eigen tmux ceres-solver glog
     

   • Linux：通过系统包管理器安装（如apt、yum等）

3. 配置虚拟环境：

   bash
   python3 -m venv venv
   source venv/bin/activate  # 激活虚拟环境
   

4. 安装依赖并部署：

   bash
   pip install -r requirements.txt
   pip install -e .  # 以开发模式安装
   

数据库配置

VoxelFlow依赖MongoDB，推荐通过Docker部署：

1. 拉取MongoDB镜像：

   bash
   docker pull mongo:5.0
   

2. 启动MongoDB容器：

   bash
   docker run -p 27017:27017 --restart=always --name voxelflow-db -d mongo:5.0
   

3. 配置数据库连接：

   • 本地数据库（默认）：

     bash
     export VOXELFLOW_USE_LOCAL_DB=true
     

   • 远程数据库：

     bash
     export VOXELFLOW_PRODUCTION=false
     export VOXELFLOW_DB_HOST=192.168.50.201
     export VOXELFLOW_DB_PORT=27017
     export VOXELFLOW_DB_PASSWORD=mytopsecretpassword
     

运行VoxelFlow

1. 开发模式：

   bash
   voxelflow --dev
   

   访问地址：http://localhost:4975
   默认管理员账号：administrator，密码：rutherford!2009（可通过VOXELFLOW_DEFAULT_ADMINISTRATOR_PASSWORD修改）

2. 分布式模式：

   bash
   export VOXELFLOW_DISTRIBUTED_MODE=true
   voxelflow --dev  # 本地机器作为worker节点
   

配置参数（环境变量）

开发相关操作

前端开发

1. 安装依赖：

   bash
   cd web/frontend
   npm install --save --legacy-peer-deps
   

2. 启动开发服务器：

   bash
   npm start  # 访问 http://localhost:3000
   

   需同时运行后端服务：voxelflow --dev

运行测试

• 单元测试：

  bash
  pytest --cov voxelflow tests/unit
  

• 集成测试：

  bash
  pytest tests/integration
  

• 本地CI测试：

  bash
  ./gh.sh  # 模拟GitHub Actions检查
  

构建文档

bash
voxelflow --build-docs  # 生成文档
xdg-open documentation/index.html  # Linux系统查看文档

高级功能配置

快照功能

启用快照需配置：

bash
export VOXELFLOW_DISTRIBUTED_MODE=true
export VOXELFLOW_SNAPSHOT_ENABLE=true
export VOXELFLOW_SNAPSHOT_ENDPOINT_URL=<S3端点URL>
export VOXELFLOW_SNAPSHOT_ACCESS_KEY=<访问密钥>
export VOXELFLOW_SNAPSHOT_SECRET_KEY=<密钥>
export VOXELFLOW_SNAPSHOT_BUCKET=<桶名称>

通过管理员账户在Web界面管理快照，配置VOXELFLOW_SCHEDULE_BACKUP=true可启用每日自动备份。

S3 Blob存储

配置S3作为blob存储后端：

bash
export VOXELFLOW_USE_S3_AS_BLOB_STORE=true
export VOXELFLOW_S3_BLOB_STORE_ACCESS_KEY=<访问密钥>
export VOXELFLOW_S3_BLOB_STORE_SECRET_KEY=<密钥>
export VOXELFLOW_S3_BLOB_STORE_ENDPOINT_URL=<S3端点URL>
export VOXELFLOW_S3_BLOB_STORE_BUCKET=<桶名称>

数据库集合说明

VoxelFlow在MongoDB中使用的主要集合包括：

• docs：存储所有项目文档数据
• projects：项目元数据（ID、名称等）
• experiments：实验元数据（配置、状态等）
• users：用户信息（账号、权限等）
• jobs：任务记录（通常任务完成后删除）
• audit_logs：审计日志（需VOXELFLOW_AUDIT_LOGS_ENABLE=true）
• GridFS集合：voxelflow.jobs_results.files等用于存储大文件数据