首页 / 二次开发

二次开发：主题、XBlock 与 API

Open edX 是 Django 单体 + 微服务的组合，绝大多数定制不需要动核心代码，通过主题、插件与 API 三个层面即可完成。

1. 主题定制

平台界面基于 Mako 模板 + Sass 样式，官方推荐的做法是制作独立主题包：

  1. Fork 官方主题仓库作为起点，修改品牌色、Logo、页头页脚模板；
  2. 在 Tutor 中启用：tutor config save --set ENABLE_THEMES=true 并挂载主题目录；
  3. 重新构建前端资源（打开 edX Platform 中的 Comprehensive Theming 文档对照调整）。
建议主题改动集中在品牌层（Logo / 配色 / 页脚 / 登录页），避免大面积改模板——大版本升级时模板差异越小，维护成本越低。

2. XBlock 插件开发

XBlock 是教学组件的插件标准，官方的习题、视频都是 XBlock。开发一个自己的交互组件：

# 用官方脚手架创建项目
pip install xblock-sdk
# XBlock 核心三件套：
#   XBlock 类：字段(field)、视图(view)、范围(scope)
#   student_view()：学员端渲染
#   studio_view()：教师端配置表单
  • 无状态内容用 Scope.content，学员作答数据用 Scope.user_state；
  • 通过 Tutor 的 MOUNT 机制挂载到平台，XBlock 配置中启用；
  • 发布到 PyPI 后即可在任意 Open edX 平台安装使用。

3. 平台 API

平台暴露完整的 REST API（/api/ 目录），配合 OAuth2 客户端凭证认证：

  • 课程：列表、详情、结构树；
  • 用户与选课：注册、选课状态、进度；
  • 成绩：成绩册、证书状态；
  • 常用对接场景：统一身份认证（SSO / CAS / OAuth）、企业微信与钉钉通知、教务系统成绩回传。
# 创建 OAuth2 客户端后调用示例
curl -H "Authorization: Bearer $TOKEN" \
     https://your-domain.com/api/courses/v1/courses/

4. 深度改造须知

  • 改核心代码请走 Fork + 补丁管理，并通过 Tutor 的 Mount 替换容器内代码，不要直接改容器；
  • 大版本升级前阅读官方 Release Notes，重点检查主题模板与 XBlock 兼容性；
  • 所有自定义内容纳入 Git 管理，形成「Tutor 配置 + 主题 + 插件 + 补丁」四件套的部署资产。