ubcctlt/compair-app

ComPAIR 镜像文档

镜像概述和主要用途

ComPAIR是一个基于自适应比较判断（ACJ）方法的教育应用。ACJ源于Thurstone 1927年提出的比较判断法则，最初用于心理测量，现作为评分的替代方案，特别适用于难以用评分标准描述的表现性评估，以及评分者间信度问题突出的场景。该应用允许学生回答教师或其他学生提出的问题，然后比较和判断给定答案，系统根据ACJ方法计算每个答案的分数。

核心功能和特性

核心功能

• 支持学生回答问题及对答案进行比较判断
• 基于ACJ方法自动计算答案分数
• 多用户角色管理（学生、教师、系统管理员）
• 课程和作业管理
• 学习分析数据收集（支持xAPI和Caliper）
• 多种用户认证方式（APP登录、CAS、SAML 2.0、LTI）

技术框架

• 前端：Javascript，使用AngularJS作为MVC框架，Bootstrap用于UI设计
• 后端：Python，基于Flask Web框架，使用Flask SQLAlchemy进行数据库持久化
• 数据库迁移：Alembic
• 任务队列：Celery（支持后台任务）

使用场景和适用范围

• 教育机构的教学评估
• 学生作业质量评价
• 表现性任务评分（如论文、项目报告等）
• 需要提高评分者间一致性的评估场景
• 教学数据分析与学习行为追踪

使用方法和配置说明

开发环境安装

开发环境依赖

• Docker Engine
• Docker Compose
• npm
• 运行单元测试需额外安装：lapack 和 atlas（用于scipy和numpy）

  bash
  # CentOS/RHEL
  yum install lapack-devel atlas-devel
  # Debian/Ubuntu
  apt-get install libatlas-base-dev liblapack-dev
  

克隆仓库并启动服务器

bash
git clone git@github.com:ubc/compair.git compair
cd compair
npm install
node_modules/gulp/bin/gulp.js
node_modules/gulp/bin/gulp.js prod
docker-compose up -d

初始化数据库（首次运行）

bash
# 创建空数据库
docker exec -it compair_app_1 python manage.py database create

# 或创建包含演示数据的数据库
docker exec -it compair_app_1 python manage.py database create -s

应用访问地址：http://localhost:8080/

常用操作

• 查看日志

  bash
  # 应用日志
  docker logs -f compair_app_1
  # Nginx日志
  docker logs -f compair_web_1
  # 数据库日志
  docker logs -f compair_db_1
  

• 停止服务器

  bash
  docker-compose stop
  

• 停止并清理

  bash
  docker-compose down
  rm -rf .data
  

• 访问数据库

  bash
  docker exec -it compair_app_1 mysql
  

• 升级数据库

  bash
  docker exec -it compair_app_1 alembic upgrade head
  

• 运行管理命令

  bash
  docker exec -it compair_app_1 python manage.py COMMAND
  

• 本地构建镜像

  bash
  docker build -t ubcctlt/compair-app .
  

• 升级应用

  bash
  docker-compose down
  docker pull ubcctlt/compair-app  # 拉取最新镜像
  docker-compose up
  docker exec -it compair_app_1 alembic upgrade head  # 升级数据库
  

测试

测试环境依赖

使用python3-saml需额外安装系统依赖：

bash
# macOS
brew install libxmlsec1
# Debian/Ubuntu
apt-get install libxmlsec1-dev
# CentOS/RHEL
yum install xmlsec1-devel

运行测试

• Python单元测试

  bash
  make testb
  

• AngularJS规范测试

  bash
  make testf
  

• AngularJS验收测试

  bash
  make testa
  

生成生产环境资源

运行gulp prod生成生产环境资源，包括：

1. 合并所有Bower管理的JavaScript库为单个压缩文件
2. 编译并压缩LESS文件为单个CSS文件
3. 编译并压缩邮件用LESS文件为静态文件夹中的单个CSS文件
4. 复制所有Bower管理的图片和字体到静态文件夹
5. 复制PDF查看器及其资源到静态文件夹

配置说明

学习分析设置

ComPAIR使用Experience API (xAPI)和/或Caliper收集学习分析数据，需配置学习记录存储(LRS)。

通用设置

• LRS_APP_BASE_URL：可选，设置所有语句的基础URL，用于保持URL一致性
• LRS_USER_INPUT_FIELD_SIZE_LIMIT：用户输入字段的字节限制，默认***（1MB）
• LRS_SIS_COURSE_ID_URI_TEMPLATE：SIS课程ID URI模板，默认'{base_url}/course/{sis_course_id}'
• LRS_SIS_SECTION_ID_URI_TEMPLATE：SIS章节ID URI模板，默认'{base_url}/course/{sis_course_id}/section/{sis_section_id}'

Actor账户设置

• LRS_ACTOR_ACCOUNT_USE_GLOBAL_UNIQUE_IDENTIFIER：是否使用全局唯一标识符作为actor标识
• LRS_ACTOR_ACCOUNT_GLOBAL_UNIQUE_IDENTIFIER_HOMEPAGE：使用全局唯一标识符时的actor主页

XAPI设置

• XAPI_ENABLED：是否启用xAPI，默认0（禁用）
• LRS_XAPI_STATEMENT_ENDPOINT：LRS URL，默认'local'（日志到xapi_log表）
• LRS_XAPI_USERNAME：OAuth1账户用户名
• LRS_XAPI_PASSWORD：OAuth1账户密码
• LRS_XAPI_AUTH：Basic认证字符串（base64编码的"用户名:密码"）

Caliper设置

• CALIPER_ENABLED：是否启用Caliper，默认0（禁用）
• LRS_CALIPER_HOST：LRS URL，默认'local'（日志到xapi_log表）
• LRS_CALIPER_API_KEY：发送Caliper语句的API密钥

后台任务设置

ComPAIR使用Celery处理后台任务，包括数据库重置、LTI课程成员更新、成绩更新、邮件发送等。

启用后台任务

1. 设置Celery broker（如Redis、RabbitMQ）
2. 启动Celery worker：celery worker --app=celery_worker.celery
3. 配置相关环境变量

任务设置

• CELERY_ALWAYS_EAGER：是否立即执行任务（阻塞模式），默认1（启用）；设为0启用后台任务
• CELERY_BROKER_URL：broker URL（如redis://localhost:6379/0）
• CELERY_RESULT_BACKEND：结果存储后端，默认禁用
• CELERY_TIMEZONE：时区，默认'America/Vancouver'

用户认证设置

ComPAIR支持多种认证方式，至少需启用一种。

APP登录设置

• APP_LOGIN_ENABLED：是否启用用户名密码登录，默认True

CAS登录设置

• CAS_LOGIN_ENABLED：是否启用CAS登录，默认False
• CAS_SERVER：CAS服务器URL（不含尾随斜杠）
• CAS_AUTH_PREFIX：CAS动作前缀，默认'/cas'
• CAS_USE_SAML：是否使用SAML验证端点，默认False（使用/serviceValidate）
• CAS_ATTRIBUTE_USER_ROLE：用于确定用户默认角色的CAS属性
• CAS_INSTRUCTOR_ROLE_VALUES：指示教师角色的CAS属性值列表（空格分隔）
• CAS_ATTRIBUTE_FIRST_NAME/LAST_NAME/STUDENT_NUMBER/EMAIL：用于同步用户信息的CAS属性

SAML 2.0登录设置

• SAML_LOGIN_ENABLED：是否启用SAML登录，默认False
• SAML_SETTINGS：python3-saml的JSON设置
• SAML_SETTINGS_FILE：JSON设置文件路径（如未设置SAML_SETTINGS）
• SAML_UNIQUE_IDENTIFIER：用户唯一标识属性，默认'uid'
• SAML_METADATA_URL：IDP元数据URL
• SAML_METADATA_ENTITY_ID：IDP元数据实体ID
• SAML_EXPOSE_METADATA_ENDPOINT：是否暴露元数据端点，默认禁用
• SAML_ATTRIBUTE_USER_ROLE/INSTRUCTOR_ROLE_VALUES/FIRST_NAME等：类似CAS的用户属性设置

LTI设置

• LTI_LOGIN_ENABLED：是否启用LTI登录，默认True
• 需通过系统管理员界面创建LTI消费者密钥/密钥对

其他关键设置

• 登录页面自定义：LOGIN_ADDITIONAL_INSTRUCTIONS_HTML、CAS_LOGIN_HTML、SAML_LOGIN_HTML（支持HTML内容，会被AngularJS sanitize处理）
• 邮件通知：MAIL_NOTIFICATION_ENABLED（默认False），需配置Flask-Mail相关参数
• HTTPS设置：ENFORCE_SSL（默认True），控制是否强制HTTPS
• 演示环境：DEMO_INSTALLATION（默认False），启用后提供默认数据并每日重置
• 附件设置：ATTACHMENT_UPLOAD_LIMIT（默认250MB）、ATTACHMENT_ALLOWED_EXTENSIONS（默认pdf, mp3, mp4等）
• Kaltura媒体附件：KALTURA_ENABLED（默认0），支持视频/音频上传到Kaltura，需配置Kaltura账户信息
• 学生数据隐私：EXPOSE_EMAIL_TO_INSTRUCTOR、EXPOSE_THIRD_PARTY_USERNAMES_TO_INSTRUCTOR等控制数据可见性

Docker Compose配置示例

yaml
version: '3'
services:
  app:
    image: ubcctlt/compair-app
    depends_on:
      - db
    environment:
      - DATABASE_URL=mysql+pymysql://user:password@db:3306/compair
      - SECRET_KEY=your_secret_key
      - APP_LOGIN_ENABLED=True
      - CELERY_ALWAYS_EAGER=1
    volumes:
      - ./data:/app/.data
    ports:
      - "8080:8000"
  db:
    image: mysql:5.7
    environment:
      - MYSQL_ROOT_PASSWORD=root_password
      - MYSQL_DATABASE=compair
      - MYSQL_USER=user
      - MYSQL_PASSWORD=password
    volumes:
      - mysql_data:/var/lib/mysql
volumes:
  mysql_data:

注意事项

• 修改配置后需重启服务器
• 生产环境中应禁用DEMO_INSTALLATION
• 使用SAML或CAS时需确保相关依赖已安装
• 后台任务需正确配置Celery broker和worker以确保性能