cgvalle/freesurfer_vnc

FreeSurfer VNC Docker镜像文档

1. 镜像概述与主要用途

本镜像为流行的神经影像分析软件FreeSurfer提供Docker容器化部署方案，兼容Windows、macOS及Linux系统。通过集成VNC桌面环境，用户可通过浏览器或VNC客户端访问FreeSurfer图形界面，无需复杂的本地安装配置。

2. 核心功能与特性

• 跨平台兼容：支持Windows（需WSL 2）、macOS及Linux系统。
• 多方式访问：提供浏览器（无需VNC客户端）和VNC远程连接两种访问方式。
• 配置灵活：可自定义VNC登录密码、FreeSurfer主题目录（SUBJECTS_DIR）路径。
• 数据持久化：支持挂载本地目录作为持久化存储，确保分析数据不丢失。
• 简化部署：通过Docker容器化，规避本地依赖冲突，一键启动FreeSurfer环境。

3. 使用场景与适用范围

• 神经影像分析：适用于需要使用FreeSurfer进行脑结构影像处理（如皮层重建、脑区分割等）的研究人员、学生及临床工作者。
• 跨平台协作：在不同操作系统环境下保持一致的分析流程，便于团队协作。
• 临时环境部署：快速搭建FreeSurfer运行环境，无需长期占用本地系统资源。
• 教学与演示：在教学场景中快速部署标准化FreeSurfer环境，降低学员配置门槛。

4. 使用方法与配置说明

4.1 基本使用（Docker CLI）

通用命令（Linux/macOS）

bash
docker run -d \
    --name freesurfer_vnc \
    -e VNC_PASSWORD=mypassword \
    -e SUBJECTS_DIR=/root/persistent/subjects \  
    -v $HOME/docker/freesurfer_VNC:/root/persistent \  # 推荐：持久化存储
    -p 6080:80 -p 5900:5900 \
    cgvalle/freesurfer_vnc:latest

4.2 参数说明

容器通过运行时参数配置，格式通常为<外部>:<内部>（如端口映射）。以下为核心参数说明：

4.3 Windows系统设置

前置要求

Windows需安装Windows Subsystem for Linux (WSL) 2。推荐通过Docker Desktop自动配置WSL 2环境，简化部署流程。

Windows专用命令

bash
docker run -d \
    --name freesurfer_vnc \
    -e VNC_PASSWORD=mypassword \
    -e SUBJECTS_DIR=/root/persistent/subjects \  
    -v //c/Users/<user_name>/Documents:/root/persistent \  # Windows路径格式
    -p 6080:80 -p 5900:5900 \
    cgvalle/freesurfer_vnc:latest

注意事项

• Windows路径需使用双斜杠（//）表示目录，如//c/Users/<user_name>/Documents。
• 需将<user_name>替换为实际Windows用户名。
• 成功启动后，通过浏览器访问http://127.0.0.1:6080进入FreeSurfer桌面。

4.4 注意事项

• 首次运行目录创建：若将卷挂载至/root/persistent，需在首次运行时手动创建subjects文件夹，否则可能导致路径错误。
• 端口冲突：若本地6080或5900端口已被占用，需修改端口映射（如-p 6081:80）。
• VNC客户端访问：使用VNC客户端连接时，地址为127.0.0.1:5900，密码为VNC_PASSWORD指定值（若无密码则直接连接）。

5. FreeSurfer许可证

FreeSurfer需要免费许可证，可通过其官方网站申请。获取许可证文件后，需将其放置于容器内的/home/ubuntu/freesurfer目录（默认$FREESURFER_HOME路径）。

6. 致谢

本镜像基于https://github.com/vemonet/docker-ubuntu-vnc-desktop%E7%9A%84VNC%E6%A1%8C%E9%9D%A2%E5%AE%B9%E5%99%A8%E6%9E%84%E5%BB%BA%E3%80%82