• 音视频
• CMS
• 后端
• 前端

本篇以 lms-plugins/mediacms-moodle/README.md 为主体，完整讲清 MediaCMS 官方 Moodle 插件套件（filter_mediacms文本过滤器 +tiny_mediacmsTinyMCE 编辑器插件）的安装顺序、统一配置项与日常使用方法，并结合仓库中的插件源码剖析 URL 自动转嵌、LTI 1.3 OIDC 安全启动与"My Media"页面的实际实现链路，读完后可独立完成从打包安装到排障的全流程。

一、套件架构：两个插件，一份核心设置

MediaCMS 的 Moodle 集成由两个互相配合的插件组成，README 中定义的分工如下：

这种"设置集中在一处"的设计在源码中有明确体现。tiny_mediacms的version.php声明了对 filter 插件的硬依赖：

// lms-plugins/mediacms-moodle/tiny/mediacms/version.php $plugin->version = 2026051100; // 2026-05-11 $plugin->requires = 2024100700; // Requires Moodle 4.5+ $plugin->maturity = MATURITY_STABLE; $plugin->release = 'v1.0.0'; $plugin->dependencies = ['filter_mediacms' => 2026051100]; // Requires filter plugin for shared settings

即：套件版本为 v1.0.0，要求 Moodle 4.5 及以上（源码 tiny/mediacms/version.php 与 filter/mediacms/version.php），而 INSTALL.txt 注明支持 Moodle 4.x 与 5.x，README 声明在 Moodle 5 上测试过。

在编辑器插件读取"统一设置"这一点上，可以从源码结构看到其实现：tiny/mediacms/classes/plugininfo.php 的get_autoconvert_configuration()（L111-L134）与get_lti_configuration()（L142-L181）均通过get_config('filter_mediacms', 'mediacmsurl')/get_config('filter_mediacms', 'ltitoolid')从filter 插件的配置组中取值，而非自身配置组——这就是 README 所说"核心设置由 filter 插件提供、编辑器插件只读"的落地方式。

二、安装：两个独立 ZIP，顺序不可颠倒

套件以两个独立的 ZIP 包分发，README 给出的安装顺序表如下：

README 提到可用./build.sh构建出dist/filter_mediacms-v1.0.0.zip与dist/tiny_mediacms-v1.0.0.zip两个产物。注意：当前仓库的lms-plugins/mediacms-moodle/目录树中并未提交该脚本与dist/目录，dist/属于构建产物，需从发布渠道获取现成 ZIP 或自行打包。

方式 A —— 通过 Moodle 后台上传（推荐）

1. 以管理员身份登录 Moodle；
2. 进入Site administration > Plugins > Install plugins；
3. 上传filter_mediacms-v1.0.0.zip并完成安装；
4. 上传tiny_mediacms-v1.0.0.zip并完成安装。

方式 B —— 手动解压部署

将两个包上传到 Moodle 的 public 目录，分别解压到对应的插件类型目录：

cd /var/www/moodle/public unzip filter_mediacms-v1.0.0.zip -d filter/ unzip tiny_mediacms-v1.0.0.zip -d lib/editor/tiny/plugins/

确保 Web 服务器用户（通常是www-data）拥有新目录的属主权限：

# Example for Ubuntu/Debian systems chown -R www-data:www-data /var/www/moodle/public/filter/mediacms chown -R www-data:www-data /var/www/moodle/public/lib/editor/tiny/plugins/mediacms chmod -R 755 /var/www/moodle/public/filter/mediacms chmod -R 755 /var/www/moodle/public/lib/editor/tiny/plugins/mediacms

随后以管理员登录，进入Site administration > Notifications，按提示升级数据库以完成两个插件的安装。INSTALL.txt 补充了部署后的关键一步：必须确保 Filter 已启用并置于过滤器列表最顶部（"place it at the top of the filter. This is important, otherwise embeds won't load"）。

这一点在安装钩子中有自动化保障：filter/mediacms/db/install.php 在安装后自动执行filter_set_global_state('filter_mediacms', TEXTFILTER_ON)全局启用该过滤器，并把filter_active表中filter_mediacms记录的sortorder重写为 1（即最高优先级），其余过滤器顺延（L12-L44）。

三、配置：一次设置，两处生效

Step 1：核心设置（必填，只配一次）

路径：Site administration > Plugins > Filters > MediaCMS（Settings）。对照 filter/mediacms/settings.php，该页面实际注册了以下设置项：

关于 LTI Tool 的前置准备：需要先在Site administration > Plugins > Activity modules > External tool > Manage tools创建名为 MediaCMS 的 LTI 1.3 工具。仓库的 docs/moodle_plugin.md 给出了完整的外部工具参数清单（Tool URL 为 MediaCMS issuer URL +/lti/launch/、Keyset URL 为/lti/jwks/、Initiate login URL 为/lti/oidc/login/等），以及 MediaCMS 侧需要登记的 LTI Platform 端点：

• Auth login URL：https://YOUR_MOODLE/filter/mediacms/lti_auth.php（即本套件自定义的认证入口，见第五节）
• Auth token URL：https://YOUR_MOODLE/mod/lti/token.php
• Key set URL：https://YOUR_MOODLE/mod/lti/certs.php
• 同时启用 Deep Linking

此外，MediaCMS 一侧需在local_settings.py中开启USE_LTI = True（以及USE_IDENTITY_PROVIDERS、USE_RBAC）后重启服务。

Note（README 原文强调）：这些核心设置会被 filter 插件和 TinyMCE 编辑器插件同时使用。

Step 2：启用过滤器

1. 进入Site administration > Plugins > Filters > Manage filters；
2. 将MediaCMS设为 "On"，并保持在列表顶部（与 INSTALL.txt 的要求一致）。

Step 3：配置自动转换默认值（可选）

路径：Site administration > Plugins > Text editors > TinyMCE editor > MediaCMS settings，用于为自动转换的 URL 配置默认展示选项。对照 tiny/mediacms/settings.php（L39-L61），当前版本实际提供三个复选框，且默认均为开启：

需要注意：README 的此节还列有 "Show related videos"，但在当前仓库的tiny/mediacms/settings.php与 plugininfo.php 中均已不存在autoconvert_showrelated配置键（AUTOCONVERT.md 中残留的旧版说明可作参考）。以现有源码为准，自动转换的嵌入选项为showTitle、linkTitle、showUserAvatar三项。该页面顶部另有说明：核心设置（URL、LTI Tool）仍在 filter 插件处管理，此处不重复。

四、过滤器工作原理：URL 如何变成安全 iframe

filter 插件的核心是 filter/mediacms/classes/text_filter.php。其filter()方法（L26-L84）对课程富文本按顺序执行四类转换，这也是"学生无需任何操作、内容自动安全播放"的机制来源：

1. [mediacms:TOKEN]标签（L38-L40）：正则/\[mediacms:([a-zA-Z0-9]+)\]/匹配手写标签，直接生成指向launch.php的 iframe；
2. 已有 iframe 的 src 改写（L42-L49）：TinyMCE 插件保存的<iframe src="https://…/view?m=TOKEN…">会在输出阶段被只替换 src 值为launch.php?token=…URL，iframe 的其余属性（width、height、style 等）原样保留（callback_iframe_src，L97-L128）；源码注释特别说明此步骤必须先于第 3 步，否则 URL 模式会破坏src属性内的 HTML；
3. 纯文本 URL 自动转换（L51-L76）：先以占位符保护带data-mediacms-textlink="true"的纯文字链接（避免误转），再把匹配scheme://host/prefix/(view|embed)?m=TOKEN的裸 URL 替换为响应式 iframe。匹配规则基于filter_mediacms/mediacmsurl设置解析出的 host 与 scheme，因此只有配置了那个 MediaCMS 实例的 URL 才会被转换（若未配置mediacmsurl，filter()直接返回原文本，L31-L34）；
4. 文字链接还原为启动器（L78-L81）：被保护的 textlink 由transform_textlink()（L241-L277）改写成指向my_media.php?token=…&courseid=…的新标签页链接——即"链接形式"的媒体引用。

generate_iframe()（L181-L233）展示了最终产出的播放器结构：launch.php的查询参数为token（媒体 friendly_token）、courseid，外加从原 URL 中透传的showTitle、showUserAvatar、linkTitle、t（起始时间）、width、height（supported_params列表见 L167）。响应式尺寸策略为：未显式指定宽高时默认max-width: 640px且aspect-ratio: 16 / 9；指定了宽高则按比例锁定（L213-L218）。

编辑器侧的自动转换由 tiny/mediacms/amd/src/autoconvert.js 完成：监听 TinyMCE 的paste与input（insertFromPaste/insertText）事件，用正则^(https?:\/\/[^\/]+)\/view\?m=([a-zA-Z0-9_-]+)$（L37）识别 View URL，经域名白名单校验（空配置则允许全部）后，生成带showTitle/showUserAvatar/linkTitle参数的/embed?m=…iframe 插入编辑器。PHP 侧的plugininfo.php通过get_plugin_configuration_for_context()把权限、LTI 配置（toolId、courseId、contentItemUrl）与自动转换配置一并注入 JS。

五、LTI 1.3 安全播放链路：launch.php、lti_auth.php 与 My Media

5.1 单个视频的播放启动（launch.php）

当学生查看含嵌入视频的课程内容时，iframe 实际加载的是/filter/mediacms/launch.php?token=…&courseid=…。launch.php 的完整流程：

1. 读取mediacmsurl与ltitoolid配置，缺配置直接终止（"MediaCMS URL not configured" / "LTI tool not found"）；
2. 组装发给 MediaCMS 的 custom 参数（L58-L83）：media_friendly_token、embed_show_title、embed_show_user_avatar、embed_link_title、embed_start_time、show_media_page、embed_share_media（来自核心设置），以及parent_media_base——指回my_media.php的基址，用于点击嵌入播放器标题时导航回 Moodle 内的 My Media 页；
3. 关键防竞态设计（L116-L123）：调用lti_build_login_request()构造 OIDC 登录请求后，以launchid为键把 custom 参数存入 session（$SESSION->{'mediacms_cp_' . $launchid}）。源码注释解释了原因：避免共享单一 SESSION 键，否则"同页多个视频同时加载"时会互相覆盖；
4. 输出一张自动提交的 OIDC 登录表单（action 指向 MediaCMS 的lti_initiatelogin端点），另附media_token等隐藏字段作为二级兜底。

5.2 自定义 OIDC 认证端点（lti_auth.php）

MediaCMS 侧登记的 "Auth login URL" 指向 lti_auth.php，它是"功能上与/mod/lti/auth.php完全一致"的自定义端点，唯一差异：no-activity（id=0）分支只要求用户已登录，不再要求moodle/course:manageactivities能力——这样普通学生也能完成认证（文件头注释 L2-L11 与 L126-L130）。

该文件严格校验 OIDC 回调参数（scope=openid、response_type=id_token、login_hint必须等于当前$USER->id、client_id必须与工具配置一致、redirect_uri必须在工具登记的 Redirection URIs 白名单内），然后调用lti_get_launch_data()签发 JWT，最后输出自动 POST 回 MediaCMS 的表单。custom 参数从 session 取回：优先取mediacms_cp_<launchid>（按 launchid 键控，支持并发嵌入），否则回退到固定键mediacms_launch_customparams（单用途页面，L134-L142）。

5.3 My Media 页面与视频库选择（lti_launch.php / my_media.php / select_media_picker.php）

• my_media.php 用 Moodle 的mydashboard布局渲染一个占满视口的 iframe：不带 token 时 src 指向lti_launch.php（进入 MediaCMS 的 My Media）；带token参数时指向launch.php?...&show_media_page=true（直接打开对应媒体的完整页面）。该页面通过顶部导航或用户菜单的 "My Media" 链接进入（见下）；
• lti_launch.php 在进入 MediaCMS 前组装publishdata：查询用户所有已注册课程及其角色（默认student），base64 编码后以publishdata=…\nembed_share_media=…存入 session，由lti_auth.php在 OIDC 回调时随启动数据一并交给 MediaCMS——这就是 MediaCMS 侧"按课程分类（category）组织媒体"的数据来源；
• select_media_picker.php 是学生可访问的媒体选择器入口：把redirect_path=/lti/select-media/?mode=lms_embed_mode存入 session 后发起无 activity 的 OIDC 登录，MediaCMS 收到后路由到媒体选择界面；用户选片后由 MediaCMS 发出postMessage({type:'videoSelected',…})，编辑器插件的iframeembed.js处理。它替代了标准/mod/lti/contentitem.php（后者需要moodle/course:manageactivities，学生会被拒）；MediaCMS 侧对应视图是 lti/deep_linking.py 中的SelectMediaView（/lti/select-media/，见 lti/urls.py）。

5.4 "My Media" 导航入口是怎么挂上的

mymedia_nav_position设置由事件钩子消费：filter/mediacms/db/hooks.php 注册core\hook\after_config回调，classes/hooks.php 的append_my_media_link()（L20-L56）按配置值把My Media|/filter/mediacms/my_media.php追加进$CFG->custommenuitems（顶部导航）或$CFG->customusermenuitems（用户头像下拉菜单），值为 2 时不显示；常量MEDIACMS_NAV_PLACEMENT_TOP/PROFILE/NONE（0/1/2）定义在 filter/mediacms/lib.php。

六、日常使用

教师（编辑侧）

1. 在任意 TinyMCE 文本编辑器中点击MediaCMS图标（或 Insert 菜单中的 "Insert MediaCMS Media"）；
2. 两种插入方式：
   • 粘贴 URL：粘贴 View 或 Embed URL（自动转换为播放器，行为见第四节）；
   • Video Library：点击 "Video Library" 标签页浏览并选择视频（需完成 LTI Deep Linking 配置，走第五节的select_media_picker.php链路）；
3. 视频在编辑器中显示为占位符或 iframe；可调整尺寸、标题、头像、起始时间等嵌入选项。

学生（展示侧）

内容展示时，filter 已把嵌入内容替换为经launch.php的 LTI 1.3 安全 iframe：学生身份通过 OIDC 流程自动认证到 MediaCMS，无需登录 MediaCMS。"Share Embedded Media" 核心设置决定学生访问后是否在 "Shared with me" 中留下共享记录（开启时媒体 Publish State 变为 Private and Shared，即只能在 Moodle 内访问）。

七、构建与开发流程

README 的 "Build instructions" 一节的原始笔记较为简略，整理后的完整工作流如下（原文按此顺序）：

• 两类改动：PHP 改动无需构建；JS 改动需用npx grunt amd构建；
• 依赖：需要一个可用的 Moodle 实例（moodle/目录）与匹配的 npx 版本及依赖；

1. 在 lms-plugins/mediacms-moodle 中修改代码 2. 复制到 Moodle 目录 3. 在 moodle 中运行 npx grunt amd 构建 JS 文件 4. 从 moodle 复制回仓库 示例（README 原文）： sudo cp -r ~/mediacms/lms-plugins/mediacms-moodle/tiny/mediacms/ -r ~/mediacms/moodle/public/lib/editor/tiny/plugins/ cd ~/mediacms/moodle/public/lib/editor/tiny/plugins/mediacms/ && npx grunt amd sudo cp -r /home/user/mediacms/moodle/public/lib/editor/tiny/plugins/mediacms /home/user/mediacms/lms-plugins/mediacms-moodle/tiny/ 5. 最后清理 Moodle 缓存：php admin/cli/purge_caches.php

构建管线由 lms-plugins/mediacms-moodle/Gruntfile.js 定义：babel任务把tiny/mediacms/amd/src/*.js经@babel/preset-env+@babel/plugin-transform-modules-amd转译为 AMD 模块（模块 ID 重写为tiny_mediacms/<文件名>）输出到amd/build/，再由uglify生成.min.js。package.json 的 devDependencies 锁定了 Babel 7 系列工具链；编辑器插件的测试位于 tiny/mediacms/tests/behat/（image.feature、video.feature）。

八、排障与注意事项

README 的 Troubleshooting 一节给出的实用技巧：若 "My Media" 菜单位置不生效，可改走高级主题设置手动注入：在 Admin > Appearance > Themes > Advanced theme settings 中添加My Media|/filter/mediacms/my_media.php（对应$CFG->custommenuitems的手动等价物）。

结合源码可补充的排障清单：

适用前提：本套件要求 Moodle 4.5+ 且已按 docs/moodle_plugin.md 完成 MediaCMSlocal_settings.py（USE_LTI = True）与 LTI Platform 双向登记；文档还建议 MediaCMS 与 Moodle 使用同组织域名（如moodle.organisation.org对mediacms.organisation.org），以降低浏览器跨站跟踪防护对嵌入内容的影响。

小结

MediaCMS 的 Moodle 套件用"filter 提供统一设置 + tiny 提供编辑入口"的最小插件组合，把 LTI 1.3 OIDC 认证、Deep Linking 选片、URL 自动转嵌与课程级媒体共享整合进 Moodle 常规工作流：教师粘贴 URL 或点按钮插入视频，学生打开课程页即经launch.php → lti_auth.php完成静默认证并安全播放。核心源码入口集中在 filter/mediacms/classes/text_filter.php、launch.php、lti_auth.php 与 tiny/mediacms/amd/src/autoconvert.js，可作为进一步阅读与二次开发的起点。

• 音视频
• CMS
• 后端
• 前端