从 v2.3 到 v8.2PeerTube 变更日志全解读——安全修复、升级路径与关键功能演进【免费下载链接】PeerTubeActivityPub-federated video streaming platform using P2P directly in your web browser项目地址: https://gitcode.com/gh_mirrors/pe/PeerTubePeerTube 的 CHANGELOG.md 是一部跨越 v2.3 到 v8.2 的完整技术演进史它不仅逐版本记录了安全漏洞修复SECURITY、升级必读IMPORTANT NOTES、配置键变更Configuration和插件 API 演进Plugins/Themes/Embed API还承载了诸如直播、对象存储、HLS 分离音视频流、视频 Studio 剪辑、自动转录、频道协作等里程碑式功能的落地过程。本文以这份变更日志为主体骨架结合仓库中的 config/production.yaml.example、server/scripts/migrations/ 等实际文件系统梳理 PeerTube 版本迭代的技术脉络帮助你理解每个版本升级前必须做什么、安全修复集中在哪些攻击面、关键配置如何随版本迁移以及哪些功能能力在何时被引入或移除。一、变更日志的文档结构如何快速定位版本信息PeerTube 的 CHANGELOG 采用按版本号倒序排列的块状结构最新版本在最上方每个版本块内部又按固定分类组织SECURITY本版本修复的安全漏洞标注严重程度critical/high/medium与对应的 GitHub Security Advisory 编号GHSA-*IMPORTANT NOTES升级前的必读事项——手动迁移脚本、NodeJS 版本要求、配置键改名、nginx 配置更新、存储目录调整等NGINX / Docker / Sysadmin部署层面的专项变更Configuration新增/修改/删除的配置键部分版本标注This section is not exhaustivePlugins/Themes/Embed API插件钩子hooks、服务端助手helpers、客户端 API 与破坏性变更Features功能新增与改进重大功能用:tada:标注Bug fixes问题修复清单。从仓库根目录的版本块统计看PeerTube 以主版本 小版本 补丁版本三段式发布主版本如 v8.0、v7.0、v6.0承载架构级变更NodeJS 版本支持、包管理器切换、存储目录改名补丁版本如 v8.2.3、v8.1.8则密集承载安全修复与问题修复。例如 v8.2.x 系列在短短几个补丁版本内连续修复了多起中高危漏洞这正是阅读 CHANGELOG 时需要重点关注的信号补丁版本密度越高的时期往往意味着该版本线存在集中被披露的安全问题。二、安全修复主线从 XSS 到 SQL 注入的攻击面演化CHANGELOG 中 SECURITY 分类记录了 PeerTube 各阶段被披露与修复的主要漏洞类型从中可以清晰地看到一条攻击面演化主线早期集中在客户端 XSS 与 ActivityPub 对象校验后期则深入到了联邦协议签名校验、HLS 文件代理与数据库层。2.1 客户端与数据校验类早期版本线v3.0.1修复了用户名包含_时获取我的信息可能返回其他用户数据的问题——这是一起典型的参数解析边界漏洞。v4.1.1处理图片时剥离 EXIF 数据防止通过上传图片携带元数据的信息泄露。v4.3.1修复视频列表页排序下拉框中的 XSS由安全研究者报告。v6.0.4修复 embed 中的 XSS 注入。2.2 联邦协议ActivityPub与访问控制类v7–v8 主线进入 v7 后安全修复的重心明显转向 ActivityPub 联邦协议与文件代理层v7.1.1JFrog 安全团队报告修复 ActivityPub 播放列表创建时的 DoS 与盲 SSRFCVE-2025-32948、ActivityPub 数据爬取无限循环 DoSCVE-2025-32947、通过 ActivityPub/REST API 向他人频道添加播放列表CVE-2025-32945/32946、用户导入 ZIP 炸弹与非法文件名导致的资源耗尽/持久 DoSCVE-2025-32949/32944、私有 HLS 播放列表.m3u8泄露CVE-2025-32943。v7.2.2升级multer依赖防止畸形请求 DoS移除废弃的 Do Not Track 功能以堵住useragent包的 ReDoS。v8.1.6修复来自 actor inbox URL 的SQL 注入更新 actor 关注分数时、拒绝带特殊属性的 JSON-LD 对象、角色分配仅限管理员、阻止外部认证 token 重放、阻止导入与频道同步的 SSRF。v8.2.2修复critical级别漏洞——接收Update活动时校验签名活动的 actor 与视频必须位于同一主机GHSA-g9p4-f7h8-hc86修复对象存储 HLS 代理时的 HLS 文件名校验GHSA-93rr-g3x2-ffv4。v8.2.3修复 P2P segment 校验器未能正确拒绝非法 chunk 的问题对带嵌入限制的视频在无 Referer 头时禁止 embed在调试日志中脱敏 OAuth token为 ActivityPub 对象修复增加最大深度限制。v8.2.4修复high级别的未认证 ActivityPub Actor URL/key 重绑定导致的本地播放列表接管GHSA-37jf-59fg-9hpr以及medium级别的邮箱验证绕过客户端控制的isPendingEmail参数GHSA-wp9f-cmff-p8r2。2.3 真实攻击事件v8.1.8 的应急响应记录CHANGELOG 中极少见地完整记录了 v8.1.8 对一次真实在野攻击的响应过程v8.1.6 修复的 SQL 注入漏洞自 2026 年 5 月 18 日起已被大规模利用——攻击者利用该漏洞为root用户生成 token并安装了peertube-plugin-google-analytics-js恶意插件。v8.1.8 的应对措施包括自动移除该恶意插件使所有 OAuth token 失效全部用户需重新登录新增user.disable_root_auth配置键禁止 root token 使用该键在 config/production.yaml.example 中默认值为false从插件注册中心移除该插件。该版本同时给出了无法立即升级时的 SQL 排查 SQL按actorFollow.url中的恶意 IP、actor.inboxUrl中的字符定位记录、使 OAuth token 过期等以及关闭联邦federation.enabled: false的应急步骤。这段记录对 PeerTube 管理员而言是极具价值的应急手册。三、升级路径与运维关键点IMPORTANT NOTES 解读IMPORTANT NOTES 是 CHANGELOG 对运维最直接有用的部分。跨版本归纳升级主要涉及四类必修动作。3.1 运行环境版本要求NodeJS / 浏览器 / 数据库版本运行环境要求v3.1.0弃用 PostgreSQL 9.6支持 NodeJS 14/15v4.0.0兼容 ffmpeg 4.4.1不兼容 4.4.0v4.3.0Redis 5.x、FFmpeg 4.3 不再支持支持 NodeJS 18v5.2.0移除 NodeJS 14 支持Docker Compose 要求 v2v6.0.0移除 NodeJS 16 支持升级到 NodeJS 18v7.1.0移除 NodeJS 18 支持升级到 NodeJS 20 20.9v7.3.0最低 NodeJS 版本提升到 20.19v8.0.0支持 NodeJS 20.19 and 21或 22.12 and 23yarn移除改用pnpmv8.2.0移除 NodeJS 20 支持升级到 NodeJS 22 22.12浏览器支持线也在持续收紧v6.0.0 前移除了 ES5 模块支持v7.0.0 弃用 Safari desktop 13 与 iOS 14.5v7.1.0 弃用 Safari desktop 14v8.2.0 起 iOS 15.4 不再支持。v8.0.0 还提示 Node 18 下localhost可能优先解析为 IPv6要求production.yaml中listen.hostname、database.hostname、redis.hostname使用127.0.0.1。3.2 手动迁移脚本必须在数据库迁移完成后执行PeerTube 的多个主版本要求在数据库迁移完成启动日志出现Migrations finished. New migration version schema: xxx后手动执行一次性迁移脚本。仓库 server/scripts/migrations/ 目录下实际存放了peertube-4.0.ts至peertube-8.1.ts以及peertube-8.3.ts等脚本与 CHANGELOG 的指引一一对应。典型执行方式经典安装cd /var/www/peertube/peertube-latest sudo -u peertube NODE_CONFIG_DIR/var/www/peertube/config NODE_ENVproduction \ node dist/scripts/migrations/peertube-8.1.jsDocker 安装则为cd /var/www/peertube-docker docker compose exec -u peertube peertube node dist/scripts/migrations/peertube-8.1.js各版本脚本用途举例v6.3.0 的迁移更新视频文件元数据可安全重复执行v8.0.0 的迁移耗时可能长达 30 分钟实例用户/联邦 actor 多、磁盘慢时v8.1.0 的迁移完成后官方还强烈建议运行regenerate-thumbnails与prune-storage脚本。3.3 存储目录与配置键改名v6.0.0 典型案例v6.0.0 是配置迁移最重的一个版本核心是 WebTorrent 视频向 Web Video 的术语与存储重构storage.videos改名为storage.web_videos目录值从videos/改为web-videos/文件系统目录也必须同步改名经典安装sudo -u peertube mv /var/www/peertube/storage/videos/ /var/www/peertube/storage/web-videos/Docker 安装mv /path-to-docker-installation/docker-volume/data/videos/ /path-to-docker-installation/docker-volume/data/web-videos/transcoding.webtorrent改名为transcoding.web_videosobject_storage.videos改名为object_storage.web_videos新增storage.storyboardsDocker 环境变量同步改名如PEERTUBE_OBJECT_STORAGE_VIDEOS_BUCKET_NAME→PEERTUBE_OBJECT_STORAGE_WEB_VIDEOS_BUCKET_NAME。v5.0.0 则引入了secrets.peertube配置经典安装必须提前填写并将私有/内部视频文件迁移到videos/与streaming-playlists/下的private/子目录nginx 不再直接服务这些私有文件改由 PeerTube 校验认证后代理。3.4 nginx 配置随版本更新CHANGELOG 多次强调 nginx 配置必须随版本更新仓库中的 support/nginx/peertube 是官方模板v6.0.0移除location ~ ^/static/(thumbnails|avatars)/块upload-resumable端点更新为正则形式location ~ ^/api/v1/videos/(upload-resumable|([^/]/source/replace-resumable))$新增web-videos路径v6.0.3私有 HLS 静态文件 location 更新为^/static/(webseed|web-videos|streaming-playlists/hls)/private/v7.1.0因 Lets Encrypt 移除 OCSP 支持移除 nginx 配置中的 SSL staplingv8.0.1修复 HTTP3 兼容性v8.2.0修复用户下载视频时的重要 nginx I/O 问题官方要求升级 nginx 配置。四、配置项演进新增、改名与默认值变化CHANGELOG 的 Configuration 分类部分版本标注This section is not exhaustive记录了配置体系的演化。以下按版本归纳最有代表性的配置变更。4.1 v8.2.0视频下载限速v8.2.0 新增download.max_total_bytes_per_second与download.max_bytes_per_ip_per_second两个配置键用于限制视频下载带宽防止僵尸网络批量拉取整个实例的视频目录。仓库 config/production.yaml.example 中的默认值如下download: # Max cumulative download speed in bytes/s for all download requests, set to null for unlimited # Supports byte format (500KB, etc.) max_total_bytes_per_second: 5MB # Max cumulative download speed in bytes/s for a specific IP, set to null for unlimited # Supports byte format (500KB, etc.) max_bytes_per_ip_per_second: 2MB该功能在 packages/tests/src/api/videos/video-download-throttle.ts 中有对应测试与 v8.2.0 同时引入的全局下载并发限制download_generate_video.max_parallel_downloadsconfig/production.yaml.example默认 100共同构成下载侧的三重保护。同版本还调整了 OAuth2 刷新令牌默认有效期oauth2.token_lifetime.refresh_token从 2 周提高到 4 周。4.2 v8.1.x安全强化与对象存储细化v8.1.8新增user.disable_root_auth默认false禁用 root 用户 token 认证v8.1.0生成更多缩略图尺寸thumbnails.sizes对象存储默认配置改为不同对象类型web_videos、user_exports等共用同一bucket_name但使用不同prefix新增theme.customization.on_primary_color前景色配置import.videos.http.force_ipv4默认改为truev8.0.0移除无用的http_server配置段新增views.videos.local.max_age清理旧本地视频观看记录、video_transcription.timeout转录超时、client.new_features_infoconfig/production.yaml.example默认true可关闭新功能弹窗、user.password_constraints.min_length密码最小长度。4.3 v7.x直播存储与下载限流v7.2.0object_storage.streaming_playlists.store_live_streams默认改为false直播流默认不存对象存储见 config/production.yaml.exampletrending.videos.default默认改为hot算法新增全局下载限流download_generate_video.max_parallel_downloadsv7.1.0新增 captions 对象存储桶配置Docker 环境变量PEERTUBE_OBJECT_STORAGE_CAPTIONS_BUCKET_NAME等添加 SepiaSearch 作为默认搜索索引全局搜索默认仍关闭。4.4 配置键改名与移除清单迁移提醒版本旧键新键/替代v4.0.0log.rotation.maxFileSizelog.rotation.max_file_sizev4.0.0log.rotation.maxFileslog.rotation.max_filesv4.0.0log.anonymizeIPlog.anonymize_ipv4.0.0import.http.proxy改用HTTP_PROXY/HTTPS_PROXY环境变量v6.1.0views.videos.ip_view_expirationviews.videos.view_expirationv6.0.0storage.videos/transcoding.webtorrent/object_storage.videosstorage.web_videos/transcoding.web_videos/object_storage.web_videosv7.0.0client.videos.miniature.display_author_avatar移除作者头像始终显示v8.0.0http_server配置段移除此外 v8.2.0 起整个 PeerTube 配置都可以通过环境变量设置Docker 场景且环境变量配置会覆盖 Web 管理后台的配置。五、重大功能演进PeerTube 能力地图CHANGELOG 的 Features 部分勾勒出 PeerTube 的核心能力如何在多个版本中逐步成型。5.1 直播Livev3.0.0 → v8.2.0v3.0.0首次支持直播——通过 OBS、ffmpeg 等推流支持多分辨率直播转码、保存回放、每用户/实例直播数量与时长限制v4.2.0支持直播低延迟设置小延迟无 P2P / 大延迟提高 P2P 比例永久直播的每次直播会话可保存回放v6.0.0密码保护视频隐私直播与 VOD 通用可设置直播回放隐私v6.3.0直播默认启用分离音视频 HLS 流直播可输入/输出仅音频流v7.3.0用户可设置直播计划时间计划直播会出现在浏览视频列表中v8.2.0引入直播 DVR允许观众在直播中回看与暂停管理员可配置直播结束时自动发布回放选项的默认状态。5.2 存储与转码WebTorrent → Web Video HLS 对象存储v3.4.0Beta 支持视频文件存入对象存储S3 兼容v3.2.0HLS 转码默认开启、WebTorrent 默认关闭v5.0.0支持直播流对象存储支持 2FAOTPv6.0.0移除播放器 WebTorrent 支持——WebTorrent 视频改称 Web Video格式不变但不再使用 P2P播放器仍通过 HLS 使用 P2P新增 144p 转码、RTMPSv6.3.0HLS 音视频流分离VOD 可在管理后台开启直播自动开启仅存储一份音频流以节省磁盘下载弹窗支持选择分辨率支持最大 FPS 配置默认上限 60v7.1.0移除 WebTorrent 冗余支持HLS 冗余保留升级 p2p-media-loader 至 v2v8.1.0优化转码任务队列不必等待所有转码任务完成即可发布视频、低分辨率任务降优先级、并发转码增强视频缩略图支持 png/webp。5.3 创作与编辑工具Studio、字幕、转录v4.2.0Web 界面视频剪辑Studio——裁剪视频、添加片头片尾、右上角水印自动转码后替换原视频v6.0.0视频章节chapters支持视频文件替换视频 storyboard进度条悬停预览v6.2.0自动转录生成字幕基于 Whisper需pip3依赖可交由 PeerTube runners 执行v7.0.0字幕分段编辑弹窗v8.2.0Studio 支持移除视频片段。5.4 协作与治理频道协作、所有权转移、注册审批v5.1.0用户注册审批需填写注册理由版主审批后自动创建用户与频道v6.2.0评论审批策略与自动打标包含链接等规则与关注词表v8.0.0频道协作channel collaboration——频道所有者可邀请实例内用户成为编辑者编辑者可管理频道视频/播放列表/评论v8.2.0视频频道转移给同实例其他用户改进视频所有权转移 UX批量接受/拒绝、通知。5.5 客户端与播放器体验v6.3.0转录 widget与视频同步、可搜索、点击跳转章节标记更醒目v7.0.0客户端全面重设计——新 Light/Beige 主题与 Dark/Brown 主题、浏览视频页合并最近添加/热门/本地、My library 与 Administration 页面重组v8.0.0播放器重设计——新Lucide主题原主题改名Galaxy主题可由管理员/频道/单个视频三级控制v8.2.0播放器跨会话记忆播放速率与手动分辨率选择支持水平翻转视频新增g p等热键。六、插件 / 主题 / Embed API 演进CHANGELOG 持续记录了插件生态的扩展与破坏性变更这是第三方开发者必须跟踪的部分。6.1 服务端钩子hooks与助手helpersv4.1.0新增videos.getFiles(videoId)、videos.ffprobe(path)服务端助手发布peertube/peertube-typesNPM 包供 TypeScript 插件使用v5.1.0新增getServerListeningConfig助手与userUpdater外部认证钩子v7.2.0新增邮件钩子filter:email.subject.result、filter:email.template-path.resultv7.3.0 起邮件改用 Handlebars 模板引擎替代 Pugv8.1.0新增filter:feed.videos.list.resultv8.2.0新增filter:api.user.signup.requires-approval.result、filter:notifier.notification.enabled.result与storageManager.deleteData(key)助手。6.2 客户端钩子与嵌入 APIv2.4.0嵌入 API 新增playNextVideo/playPreviousVideo/getCurrentPositionembed 支持插件v4.2.0embed URL 支持controlBar0隐藏控制栏getSettings()、isLoggedIn()、getAuthHeader()客户端助手支持 embedv6.0.0嵌入 API 支持设置视频密码setVideoPasswordembed 页面不再禁止索引改用 canonical 标签指向观看页v8.1.0上传者可以限制视频可嵌入的域名白名单。6.3 主题相关的破坏性变更v7.2.0主题 CSS 必须为body声明--is-dark: 0/1v7.3.0插件/主题必须使用:root选择器而非body注入 CSS 变量v7.0.0所有 CSS 变量体系重构基于少量主色自动生成色板部分新变量回退到旧变量以减小破坏。七、给三类读者的升级与使用建议7.1 给实例管理员升级前先读对应版本块的 IMPORTANT NOTES重点核对 NodeJS 版本、迁移脚本、nginx 配置与存储目录改名四项v6.0.0 与 v8.0.0 的升级清单尤其长建议逐条对照。安全补丁优先v7.1.1、v8.1.6、v8.1.8、v8.2.2、v8.2.4 等版本包含在野利用或高危漏洞修复官方措辞如 v8.2.2 的强烈建议所有管理员立即升级、v8.1.8 的尽快升级需要严肃对待。善用辅助脚本server/scripts/migrations/ 的迁移脚本、regenerate-thumbnails与prune-storagev8.2.0 起后者无需停服即可运行、create-move-video-storage-job本地文件迁移到对象存储是升级后清理与迁移的主力工具。关注配置默认值变化如store_live_streams默认改为false、trending.videos.default默认改为hot、force_ipv4默认改为true这些会实际改变实例行为。7.2 给插件/主题开发者跟踪每版本的 Plugins/Themes/Embed API 小节特别注意标注Breaking change的项:root选择器、--is-dark变量、Handlebars 邮件模板新增钩子与助手可参考官方插件文档docs.joinpeertube.org 的 api/plugins 章节仓库 support/doc 与 packages/ 中有部分对应内容v8.x 起插件安装/更新基于 pnpm速度更快。7.3 给普通用户/内容创作者从 v8.0 开始体验 Lucide 播放器主题与频道协作v8.2 的直播 DVR、视频片段删除、频道转移直接改善日常创作流转录、章节、storyboard、密码保护视频、敏感内容分级v7.2 的 NSFW 系统改进等能力覆盖了从无障碍到内容治理的完整场景。八、结语把变更日志当作产品路线图PeerTube 的 CHANGELOG.md 远不止是一份修复清单——它同时是安全公告、升级手册、配置迁移指南与 API 演进记录。通过它可以看到一个去中心化视频平台如何在约两代主版本内完成从 WebTorrent 到 HLS P2P、从本地存储到对象存储、从纯 VOD 到直播 DVR、从手动治理到自动化协作治理的技术迁徙。无论你是实例管理员、插件开发者还是深度用户以版本块为索引、以 IMPORTANT NOTES 为行动清单、以 SECURITY 为优先级信号来阅读这份文档都能在每次升级中做到心中有数、有的放矢。【免费下载链接】PeerTubeActivityPub-federated video streaming platform using P2P directly in your web browser项目地址: https://gitcode.com/gh_mirrors/pe/PeerTube创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考