hypothesis/lms Docker 镜像 - 轩辕镜像

Hypothesis LTI app 镜像文档

镜像概述

Hypothesis LTI app 是 Hypothesis 官方提供的 LTI（Learning Tools Interoperability）应用镜像，用于将 Hypothesis 的协作注释功能无缝集成到支持 LTI 标准的学习管理系统（LMS）中。通过该镜像部署的应用，教育机构可在 Canvas、Blackboard、Moodle 等主流 LMS 平台中嵌入 Hypothesis 的注释工具，实现课程材料、文档、网页内容的实时协作注释，促进师生互动与深度学习。

核心功能与特性

1. LTI 标准兼容

• 支持 LTI 1.1 和 LTI 1.3 协议，适配不同版本 LMS 的集成需求，确保跨平台兼容性。
• 符合 IMS Global 标准，通过 LTI 安全机制（如 OAuth 签名、OIDC 认证）保障数据传输安全。

2. 深度 LMS 集成

• 自动同步 LMS 用户身份（姓名、***、角色），无需额外账号体系。
• 与 LMS 课程结构联动，支持按课程、章节组织注释内容，保持学习场景连贯性。

3. 协作注释功能

• 实时多人注释：支持学生、教师对同一内容进行高亮、评论和回复，形成讨论线程。
• 注释权限管理：基于 LMS 角色（教师/学生/管理员）控制注释可见范围（公开/小组/私有）。
• 内容类型适配：支持 PDF、网页、HTML 文档等常见课程材料格式的注释。

4. 数据可靠性与扩展性

• 支持 PostgreSQL、MySQL 等主流数据库存储注释数据，确保持久化与可扩展性。
• 提供 REST API 接口，便于与第三方系统（如 analytics 工具）集成，实现学习数据追踪。

使用场景与适用范围

Hypothesis LTI app 主要面向教育领域，适用于需要在学习管理系统中增强协作互动的场景：

• 高等教育：大学课程中，教师可将阅读材料通过 LMS 分发，学生通过 Hypothesis 进行协作注释，深化阅读理解并形成讨论社区。
• K12 教育：中学课堂中，教师引导学生对课文、文献进行注释，支持小组合作学习和课堂互动。
• 职业培训：企业或培训机构可将技术文档、操作手册集成到 LMS，学员通过注释功能标记疑问、分享见解，提升培训效果。
• 教育技术服务商：LMS 平台提供商可将其作为推荐工具集成到生态中，丰富教学功能选项。

使用方法与配置说明

前置条件

• 运行环境：Docker Engine 20.10+ 或 Docker Desktop。
• LMS 要求：支持 LTI 1.1 或 LTI 1.3 的学习管理系统（如 Canvas、Blackboard、Moodle 3.9+）。
• 基础设施：具备公网可访问的服务器（用于 LMS 回调）、数据库服务（推荐 PostgreSQL 12+）。
• 权限要求：LMS 管理员权限（用于添加外部 LTI 工具）。

核心配置参数

应用通过环境变量配置，关键参数如下表：

Docker 部署示例

1. 单容器部署（测试环境）

使用 SQLite 数据库（仅推荐测试），通过以下命令启动：

bash
docker run -d \
  --name hypothesis-lti \
  -p 8000:8000 \
  -e LTI_VERSION="1.1" \
  -e LTI_11_KEY="your_lms_key" \
  -e LTI_11_SECRET="your_lms_secret" \
  -e SECRET_KEY="your_secure_secret" \
  -e DEBUG="false" \
  hypothesis/lti-app:latest

2. Docker Compose 部署（生产环境）

创建 docker-compose.yml，集成 PostgreSQL 数据库：

yaml
version: '3.8'

services:
  lti-app:
    image: hypothesis/lti-app:latest
    ports:
      - "8000:8000"
    environment:
      - LTI_VERSION=1.3
      - LTI_13_CLIENT_ID=your_lms_client_id
      - LTI_13_OIDC_AUTH_URL=[***]
      - DATABASE_URL=postgresql://postgres:postgres@db:5432/hypothesis_lti
      - SECRET_KEY=your-32-char-secure-secret-here
      - ALLOWED_HOSTS=lti.your-institution.edu
      - DEBUG=false
    depends_on:
      - db
    restart: unless-stopped

  db:
    image: postgres:14-alpine
    volumes:
      - postgres_data:/var/lib/postgresql/data
    environment:
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=postgres
      - POSTGRES_DB=hypothesis_lti
    restart: unless-stopped

volumes:
  postgres_data:

启动服务：

bash
docker-compose up -d

LMS 集成步骤

以 Canvas LMS 为例（LTI 1.3）：

1. 获取应用元数据
   部署后访问 [***] 获取 LTI 1.3 配置 JSON（包含 client_id、oidc_initiation_url 等）。

2. 在 Canvas 中添加工具

   • 进入 Canvas 管理员后台 → 设置 → 应用 → 查看应用配置 → 添加 LTI 1.3 工具。
   • 输入名称（如 "Hypothesis"），上传步骤 1 获取的配置 JSON，或手动填写 Client ID、OIDC 发起 URL。

3. 配置部署

   • 创建部署 ID，启用 "信任此工具"，设置权限（如访问用户信息、课程信息）。
   • 复制 Canvas 生成的 部署 ID 并更新应用环境变量 LTI_13_DEPLOYMENT_ID。

4. 测试访问
   在 Canvas 课程中添加 "Hypothesis" 工具，验证是否能正常加载并进行注释操作。

注意事项

• 生产环境安全：必须通过 HTTPS 访问（建议配置 Nginx 反向代理 + Let's Encrypt SSL），禁用 DEBUG 模式。
• 数据备份：定期备份数据库（如通过 pg_dump 备份 PostgreSQL 数据），防止注释内容丢失。
• 性能优化：高并发场景（如数百用户同时注释）需配置数据库连接池（通过 DB_POOL_SIZE 环境变量）。
• 版本兼容性：镜像标签建议使用具体版本（如 hypothesis/lti-app:1.2.0）而非 latest，确保部署稳定性。