fnndsc/cube

ChRIS_ultron_backEnd 技术文档

1. 镜像概述与主要用途

ChRIS_ultron_backEnd（简称CUBE）是ChRIS（容器化***计算开源平台）的核心后端组件，负责维护用户、文件、插件及管道的数据库。作为ChRIS系统的中枢，CUBE基于Django框架构建，集成PostgreSQL数据库和Celery任务队列，提供符合collection+json媒体类型的HTTP API，支撑整个平台的数据管理与工作流调度。

2. 核心功能与特性

2.1 核心功能

• 维护用户、文件、插件及管道的元数据与关系型数据库
• 提供符合collection+json规范的RESTful API接口
• 支持任务队列管理（基于Celery）
• 集成***计算工作流的核心业务逻辑

2.2 技术特性

• 框架与组件：Django Web框架、PostgreSQL数据库、Celery任务队列
• API协议：HTTP API支持collection+json内容类型
• 容器化部署：兼容Docker（27+）与Podman（5.2+）
• 开发工具链：通过just命令行工具简化开发与部署流程
• 跨平台支持：开发环境支持Linux、macOS及Windows WSL（依赖Docker Desktop Linux虚拟机）

3. 使用场景与适用范围

3.1 主要场景

• 作为ChRIS开源***计算平台的后端服务中枢
• ***数据管理（用户、文件元数据存储与检索）
• 插件与管道工作流的生命周期管理
• ***计算任务的队列调度与状态跟踪

3.2 适用范围

• ***科研机构的容器化计算平台搭建
• ***数据处理与分析工作流的后端支撑
• 开发环境中的ChRIS系统功能验证与测试
• 生产环境中***计算任务的稳定运行

4. 安装与部署

4.1 环境依赖

• 硬件要求：≥8GB RAM，≥20GB磁盘空间，稳定网络连接
• 软件依赖：
  • Docker（27.0.0+）或Podman（5.2.0+）
  • Docker Compose
  • just命令行工具（任务运行器）

4.2 快速部署（开发环境）

4.2.1 依赖安装

• Docker/Podman安装：

  • macOS/Windows：参考Docker官方文档
  • Linux：安装Docker Engine（注意：不要安装Docker Desktop），参考Docker Engine安装指南

• Podman配置（若使用Podman）：

  shell
  # 启动Podman用户服务
  systemctl --user start podman.service
  
  # 设置容器运行时偏好（二选一）
  just prefer podman  # 优先使用Podman
  just prefer docker  # 优先使用Docker
  

• just安装：参考just官方文档

4.2.2 启动服务

shell
# 克隆代码仓库
git clone https://github.com/FNNDSC/ChRIS_ultron_backEnd.git
cd ChRIS_ultron_backEnd

# 启动服务（首次运行需5-20分钟拉取/构建镜像）
just

服务启动后，CUBE将运行于http://localhost:8000/api/v1/，可通过浏览器访问或结合https://github.com/FNNDSC/ChRIS_ui%E5%89%8D%E7%AB%AF%E4%BD%BF%E7%94%A8%E3%80%82

5. 使用方法

5.1 核心just命令

5.2 测试与验证

shell
# 运行指定测试模块
just test feeds.tests.test_views  # 运行chris_backend/feeds/tests/test_views.py

# 验证API可用性（需安装xh与jnv/jq）
xh -a chris:chris1234 :8000/api/v1/ | jnv

5.3 服务停止与清理

shell
# 停止服务但保留数据
just down

# 完全清理（删除容器、镜像、数据卷）
just nuke

6. 配置参数与环境变量

6.1 环境变量

6.2 配置文件修改

• docker-compose.yml变更：修改后需执行just up重建服务
• 依赖变更（Dockerfile或requirements/*.txt）：需执行just build && just up重建镜像并重启

7. 开发指南

7.1 开发环境要求

• 系统：Linux（推荐）、macOS或Windows WSL
• 工具链：Git、Docker/Podman、Docker Compose、just
• IDE配置：VS Code或PyCharm可直接使用容器镜像localhost/fnndsc/cube:dev作为Python解释器

7.2 本地依赖安装（非容器化开发）

若需本地安装依赖（如LSP支持）：

shell
# 使用micromamba创建环境（推荐）
micromamba create -p ./.mambaenv -c conda-forge -y python=3.11 python-ldap=3.4
micromamba -p ./.mambaenv run pip install -r requirements/local.txt

# 激活环境
micromamba activate -p ./.mambaenv

7.3 OpenAPI兼容性

通过drf-spectacular生成OpenAPI schema，修改API后需验证：

shell
just openapi > /dev/null        # 验证OpenAPI注解
just openapi-split > /dev/null  # 拆分并验证schema

8. 生产部署

生产环境部署请参考官方Helm文档：[***]

9. GitHub Actions集成

可作为GitHub Actions步骤运行集成测试，示例配置：

yaml
jobs:
  test:
    runs-on: ubuntu-24.04
    steps:
      - name: Run ChRIS backend integration tests
        uses: FNNDSC/ChRIS_ultron_backEnd@master
        with:
          engine: docker  # 或podman
          command: test-integration  # 或test-unit、test-all等
        env:
          CUBE_IMAGE: localhost/fnndsc/cube:dev  # 自定义镜像（可选）
          PFCON_IMAGE: localhost/fnndsc/pfcon:dev

10. 架构参考

!ChRIS架构图
（注：支持系统深色模式自动切换，深色模式下显示深色架构图）

11. 文档资源

• REST API参考：https://fnndsc.github.io/ChRIS_ultron_backEnd
• API设计文档：https://github.com/FNNDSC/ChRIS_ultron_backEnd/wiki/ChRIS-REST-API-design
• 数据库设计：https://github.com/FNNDSC/ChRIS_ultron_backEnd/wiki/ChRIS-backend-database-design

注意：上述部分文档可能存在过时内容，请以最新代码实现为准。