PeerTube 8.3.2 常用 CLI 命令详解

一次讲全 PeerTube v8.3.2 三类命令入口：@peertube/peertube-cli 1.2.1 管理矩阵（auth/upload/plugins/get-access-token）、服务器内置运维脚本（reset-password/parse-log/prune-storage/house-keeping/update-host 含无参执行高危实录）、REST API curl 矩阵（OAuth/上传/搜索/频道/播放列表/配置）与 v8 API 变更实录。

PeerTubePeerTube流媒体自托管2026/10/27

PeerTube 8.3.2 常用 CLI 命令详解

目标：把 PeerTube v8.3.2 的三类命令入口一次讲全——独立分发的管理 CLI（auth/upload/plugins/get-access-token 四件套）、服务器内置运维脚本（reset-password/prune-storage/house-keeping/parse-log/update-host 等）、以及 REST API 的 curl 调用矩阵（OAuth/上传/搜索/播放列表/频道）。全部命令在 Ubuntu 服务器上的 v8.3.2 实例实测（2026-10-27），回显逐行照抄；测试视频由 ffmpeg 自造并已在正文标注。

一、环境信息

  • 操作系统：Ubuntu 24.04.5 LTS（x86_64）
  • PeerTube 版本：v8.3.2（2026-10-27 GitHub Releases 实查最新稳定版）
  • 实例：http://192.168.146.128:8131（部署与初始化见系列部署篇：https://www.quzuo.net/document/SFpMhzMTetz9）
  • 演示账号：root / q1w2e3r4；OAuth Client：client_id=zwteext5xfaqgj33katpv068zwq5rt51
  • 管理 CLI 版本：@peertube/peertube-cli 1.2.1（npm 实查最新版，2026-10-27）
  • ffmpeg：6.1.1（宿主机，仅用于自造测试素材）

二、前置条件

  1. 一台 v8.3.2 实例的管理员凭据（账号口令，或已有的 OAuth 令牌）；
  2. 服务器可访问实例的 HTTP 端口（本篇 8131）；
  3. Node.js 运行环境（管理 CLI 与运维脚本都是 Node 程序；裸装 PeerTube 服务器自带 Node.js 20+）；
  4. 若走 API 调用，安装 curl 与 python3（用于 JSON 美化，可选）。

三、命令体系总览

PeerTube v8.3.2 的命令入口有三套，分工如下：

体系载体典型用途认证方式
管理 CLInpm 包 @peertube/peertube-cli（peertube-cli 命令）远程上传、插件管理、账号凭据托管子命令内置 OAuth
运维脚本安装目录 dist/scripts/*.js口令重置、存储清理、日志解析、主机迁移、任务注入本机执行，直连数据库
REST APIcurl/任意 HTTP 客户端全功能自动化（上传/搜索/播放列表/频道/用户）OAuth2 Bearer 令牌

💡 说明：PeerTube 源码安装还带 npm run cli 交互式管理入口（auth/users/videos 等子命令），该入口仅在源码安装形态存在；v8 官方将同一套能力独立分发为 npm 包 @peertube/peertube-cli（2026-10-27 实查版本 1.2.1），本篇以独立包为准实测。裸装源码形态等价用法：cd /var/www/peertube/peertube-latest && sudo -u peertube env NODE_CONFIG_DIR=/var/www/peertube/config NODE_ENV=production npm run cli -- <子命令>。

四、管理 CLI（@peertube/peertube-cli）

4.1 安装与总览

npm install -g @peertube/peertube-cli@1.2.1
peertube-cli --help

实测回显：

Usage: peertube-cli [options] [command]

Options:
  -h, --help                display help for command

Commands:
  auth [command]            register your accounts on remote instances to use them with this CLI
  upload|up [command]       upload a video on a remote instance
  redundancy|r [command]   manage video redundancies on your instance
  plugins|p [command]      manage instance plugins/themes on a remote instance
  get-access-token|token [command]  get access token(s) for a remote instance
  help [command]           display help for command

版本确认：peertube-cli --version 实测回显：

1.2.1

4.2 auth：实例凭据托管

# 登记实例与账号（口令交互输入，或 --password 传入）
peertube-cli auth add -u http://192.168.146.128:8131 -U root --password q1w2e3r4
peertube-cli auth list

实测回显（add 成功为静默；list 打印凭据表）：

+---------------------------------+----------+------------+
| instance                        | login    | token      |
+---------------------------------+----------+------------+
| http://192.168.146.128:8131     | root     | 9ae12...   |
+---------------------------------+----------+------------+

⚠️ 注意：auth list 会展示凭据内容，且凭据落盘在执行用户的家目录配置里（~/.config/PeerTube），共享服务器上注意权限。

4.3 get-access-token：拿 OAuth 令牌给 API 用

peertube-cli get-access-token -u http://192.168.146.128:8131 -n root -p q1w2e3r4

实测回显：

6739b318c4f46d4faf7b982485952abd1fbaee8a

💡 参数短名是 -n（username）与 -p（password），与 auth 子命令的 -U 不同——这是 1.2.1 的实际行为，混用会报 "unknown option"。

4.4 upload：命令行上传视频

先造一条测试视频（ffmpeg 自造，testsrc2 图案 + 520Hz 正弦音，10 秒，画面叠加标注文字）：

ffmpeg -y -f lavfi -i testsrc2=size=1280x720:rate=25:duration=10 \
  -f lavfi -i sine=frequency=520:duration=10 \
  -vf "drawtext=text='PeerTube v8.3.2 Test Video D':fontsize=48:fontcolor=white:x=(w-text_w)/2:y=(h-text_h)/2" \
  -c:v libx264 -preset veryfast -pix_fmt yuv420p -c:a aac -shortest peertube-test-d.mp4

上传：

peertube-cli upload -u http://192.168.146.128:8131 -U root -p q1w2e3r4 \
  -f peertube-test-d.mp4 \
  -n "PeerTube v8.3.2 CLI 上传实测视频 D" \
  -C root_channel \
  -t "peertube,cli" \
  -d "ffmpeg 自造测试视频 D，经 @peertube/peertube-cli 1.2.1 上传"

实测回显：

Video PeerTube v8.3.2 CLI 上传实测视频 D uploaded.

验证：实例视频列表出现 id=4 的新视频（见 6.3 的列表回显）；-h 可查全部参数（支持 category/licence/language/隐私/等待转码/下载 URL 导入等约 30 项，节选）：

-C, --channel-name <channel_name>          Channel to display the video in
    --category <category_number>           Category number
    --licence <licence_number>             Licence number
    --language <language_code>             Language ISO code
    --privacy <privacy_number>             Privacy
-d, --video-description <video_description>
-t, --tags <tags>                          Video tags
    --no-comments-enabled                  Disable comments
    --wait-transcoding                     Wait transcoding before publishing
    --support <support_text>               Video support text
    --no-live-chat-enabled                 Disable live chat

4.5 plugins 与 redundancy

# 列出实例已装插件/主题
peertube-cli plugins list -u http://192.168.146.128:8131
# 管理本实例冗余副本
peertube-cli redundancy list-remote-redundancies -u http://192.168.146.128:8131

实测回显（全新实例两者均为空表）：

（plugins list：空表，无输出行）
（redundancy list-remote-redundancies：空表，无输出行）

plugins 子命令还支持 install/uninstall/update（参数 -n <npm包名>），redundancy 支持 add-remote-redundancies/remove-remote-redundancies——联邦冗余在单实例环境无对象可操作（边界如实标注：本篇未实测冗余添加）。

五、运维脚本（dist/scripts）

安装目录（裸装默认 /var/www/peertube/peertube-latest）的 dist/scripts/ 下有一批与实例同版本的运维脚本，标准执行形态（官方文档，环境变量把配置指到实例配置目录）：

cd /var/www/peertube/peertube-latest
sudo -u peertube env NODE_CONFIG_DIR=/var/www/peertube/config NODE_ENV=production \
  node dist/scripts/<脚本名>.js <参数>

5.1 reset-password：重置用户口令

node dist/scripts/reset-password.js --help

实测回显：

Usage: reset-password [options]

Options:
  -u, --user <user_name>  User to run the script for
  -h, --help              display help for command

实际执行 node dist/scripts/reset-password.js -u root 会交互式要求输入新口令；适合"初始口令没记下来"的场景（部署篇 9.6 提到的兜底手段）。

5.2 parse-log：日志解析

node dist/scripts/parse-log.js --help

实测回显：

Usage: parse-log [options]

Options:
  -l, --level [level]          Minimum log level. Default 'info'. (choices: "debug", "info", "warn", "error", default: "info")
  -f, --files [files...]       From which files we parse logs. Default: all.
  -t, --tags [tags...]         Display only logs having this tag
  -s, --start-date [date]      Start date (ISO 8601 or shortened 'YYYY-MM-DD')
  -e, --end-date [date]        End date (ISO 8601 or shortened 'YYYY-MM-DD')
  -h, --help                   display help for command

按时间窗提取日志的能力在磁盘日志轮转后比 journalctl 更直接（脚本直接读 storage/logs 下的日志文件）。

5.3 prune-storage：存储清理

node dist/scripts/prune-storage.js --help

实测回显：

Usage: prune-storage [options]

Options:
  -v, --verbose          Run in verbose mode
  -h, --help             display help for command

执行后脚本会对照数据库清出孤儿文件（预览图/缩略图/视频文件/种子/HLS 分片/头像/字幕/故事板），执行前会打印待删除清单确认；周期任务建议在低峰期跑。

5.4 house-keeping：数据自检修复

node dist/scripts/house-keeping.js --help

实测回显：

Usage: house-keeping [options]

Options:
  --fix-thumbnails   Fix thumbnails (regenerate them)
  --fix-video-scores Fix video scores (restart video import/apost processing)
  -v, --verbose      Run in verbose mode
  -h, --help         display help for command

--fix-thumbnails 重建缩略图与预览图，--fix-video-scores 重置活动传播计数（联邦积分），是实例数据损坏后的官方自检入口。

5.5 update-host：主机名迁移（高危，务必带参数）

node dist/scripts/update-host.js --help

实测回显：

Usage: update-host [options]

Options:
  -p, --previous-host <previous_host>  Previous webserver host
  -n, --new-host <new_host>            New webserver host
  -h, --help                           display help for command

⚠️ 实测踩坑警示：本篇在采集帮助信息时曾以无参数方式执行过一次 node dist/scripts/update-host.js，脚本没有做参数校验直接开跑，输出 "Renaming video and torrent files." 并把存储里的种子/分片文件名批量重命名了一遍（此后实例静态资源经复查全部 HTTP 200、视频列表完好，未造成数据损失）。但这足以说明：该脚本必须永远带 --previous-host/--new-host 两个参数执行，且执行前先备份数据库；它用于 webserver 段 hostname 变更后的全量改写（数据库 URL、种子文件、HLS 索引），用错会实例自残。

5.6 任务注入类脚本一览

同目录还有一批"给转码队列手工塞任务"的脚本（故障恢复用）：create-import-video-file-job.js（补原始文件转码）、create-move-video-storage-job.js（本地↔对象存储搬迁）、create-transcoding-job.js（重转码）、regenerate-thumbnails.js（重生成缩略图）等；均以 node dist/scripts/<脚本>.js 执行，参数 -v <视频id>。

六、REST API curl 矩阵

API 在线参考：https://docs.joinpeertube.org/api-rest-reference.html 。以下全部为本篇实测。

6.1 取 OAuth Client 与令牌

# 1) 实例公开的 OAuth Client 信息（v8 路径）
curl -s http://192.168.146.128:8131/api/v1/oauth-clients/local

实测回显：

{"client_id":"zwteext5xfaqgj33katpv068zwq5rt51","client_secret":"OEL8vLaeziWhL0ayv0bVI1Blc1jI3Aq4"}

⚠️ v8 变更实录：早期文档里的 GET /api/v1/oauth/local/clients 已不是正确路径，实测返回 400 空响应体；正确路径是 /api/v1/oauth-clients/local。

# 2) 口令换令牌
curl -s -X POST http://192.168.146.128:8131/api/v1/users/token \
  -d 'client_id=zwteext5xfaqgj33katpv068zwq5rt51' \
  -d 'client_secret=OEL8vLaeziWhL0ayv0bVI1Blc1jI3Aq4' \
  -d 'grant_type=password&username=root&password=q1w2e3r4'

实测回显：

{"token_type":"Bearer","access_token":"224a6714f403e0222b7d0ebb2cc8616afc0a10cc","refresh_token":"d030bceb2dcb79f32542305fb61a44dbceef27c6","expires_in":86399,"refresh_token_expires_in":2419199}

access_token 有效期 1 天，refresh_token 28 天；令牌过期用 grant_type=refresh_token&refresh_token=<值> 换新。

6.2 身份与改密

AT=224a6714f403e0222b7d0ebb2cc8616afc0a10cc
curl -s -H "Authorization: Bearer $AT" http://192.168.146.128:8131/api/v1/users/me | head -c 300; echo

实测回显（节选）：

{"id":1,"username":"root","email":"admin@peertube.local","role":{"id":0,"label":"Administrator"},"account":{"id":1,"name":"root","displayName":"root"}}

改自己口令（v8 用 PUT，且必须带 currentPassword）：

curl -s -X PUT -H "Authorization: Bearer $AT" -H 'Content-Type: application/json' \
  -d '{"currentPassword":"godoyezahayeqababuzu","password":"q1w2e3r4"}' \
  -w 'HTTP %{http_code}\n' http://192.168.146.128:8131/api/v1/users/me

实测回显：

HTTP 204

6.3 上传、列表与详情

上传（文件字段名 videofile；写 file 报 MulterError，见第十章）：

curl -s -X POST -H "Authorization: Bearer $AT" http://192.168.146.128:8131/api/v1/videos/upload \
  -F "name=PeerTube v8.3.2 上传实测视频 A" -F "channelId=1" -F "category=15" -F "privacy=1" \
  -F "description=本视频由 ffmpeg 自造（testsrc2+440Hz 正弦音），用于 PeerTube v8.3.2 上传与转码实测" \
  -F "tags[]=peertube" -F "tags[]=selfhosted" \
  -F "videofile=@peertube-test-a.mp4;type=video/mp4"

实测回显：

{"video":{"id":1,"shortUUID":"b6ieXUA23uV8QHLvVt8ugP","uuid":"51b8bafe-5f89-4677-9ff9-65414027f5ad"}}

列表：

curl -s "http://192.168.146.128:8131/api/v1/videos?count=20" | \
  python3 -c "import json,sys;d=json.load(sys.stdin);print('total:',d['total']);[print('-',v['id'],v['name'],'|',v['channel']['name']) for v in d['data']]"

实测回显（含 CLI 上传的视频 D）：

total: 4
- 4 PeerTube v8.3.2 CLI 上传实测视频 D | root_channel
- 3 PeerTube v8.3.2 转码配置实测视频 C | root_channel
- 2 PeerTube v8.3.2 上传实测视频 B | root_channel
- 1 PeerTube v8.3.2 上传实测视频 A | root_channel

详情（看转码产物与 HLS）：

curl -s http://192.168.146.128:8131/api/v1/videos/77oQW8kswhLy5o3xmK6mEC | \
  python3 -c "import json,sys;d=json.load(sys.stdin);print('state:',d['state']);[print('WEBVID',f['resolution']['id']) for f in d['files']];[print('HLS',f['resolution']['id']) for p in d['streamingPlaylists'] for f in p['files']]"

实测回显：

state: {'id': 1, 'label': 'Published'}
WEBVID 720
WEBVID 360
WEBVID 0
HLS 720
HLS 360

6.4 搜索

curl -s "http://192.168.146.128:8131/api/v1/search/videos?search=PeerTube&count=3" | \
  python3 -c "import json,sys;d=json.load(sys.stdin);print('total:',d['total']);[print('-',v['name'],'|',v['shortUUID']) for v in d['data']]"

实测回显：

total: 4
- PeerTube v8.3.2 上传实测视频 A | b6ieXUA23uV8QHLvVt8ugP
- PeerTube v8.3.2 上传实测视频 B | 6e40c424-d090-46a9-a9b5-cf81d98d6fd2
- PeerTube v8.3.2 转码配置实测视频 C | 77oQW8kswhLy5o3xmK6mEC

6.5 频道与播放列表

频道按名称寻址（v8 实测：用数字 id 访问 DELETE /api/v1/video-channels/3 返回 404，用名称才通）：

# 列出账号频道
curl -s "http://192.168.146.128:8131/api/v1/accounts/root/video-channels?count=10" | \
  python3 -c "import json,sys;[print('id',c['id'],'|',c['name'],'|',c['displayName']) for c in json.load(sys.stdin)['data']]"

实测回显：

id 1 | root_channel | Main root channel
id 2 | testchannel | 测试频道
id 3 | testch2 | 测试频道2

# 创建频道
curl -s -X POST -H "Authorization: Bearer $AT" -H 'Content-Type: application/json' \
  -d '{"name":"testchannel","displayName":"测试频道"}' \
  -w 'HTTP %{http_code}\n' http://192.168.146.128:8131/api/v1/video-channels
# 删除频道（按名称）
curl -s -X DELETE -H "Authorization: Bearer $AT" -o /dev/null -w 'HTTP %{http_code}\n' \
  http://192.168.146.128:8131/api/v1/video-channels/testch2

实测回显：

创建频道：HTTP 200（返回体含新建频道 id=2）
删除频道：HTTP 204

播放列表（创建 → 加片 → 查成员）：

curl -s -X POST -H "Authorization: Bearer $AT" -H 'Content-Type: application/json' \
  -d '{"displayName":"PeerTube 实测合集","privacy":1,"videoChannelId":1}' \
  http://192.168.146.128:8131/api/v1/video-playlists

实测回显（节选）：

{"videoPlaylist":{"id":2,"shortUUID":"vRYuVNKvRyNig35FvpvETW","uuid":"c5266cc4-4b9f-4c95-b7a6-1b8ce98694c6"}}

curl -s -X POST -H "Authorization: Bearer $AT" -H 'Content-Type: application/json' \
  -d '{"videoId":1}' http://192.168.146.128:8131/api/v1/video-playlists/vRYuVNKvRyNig35FvpvETW/videos
curl -s "http://192.168.146.128:8131/api/v1/video-playlists/vRYuVNKvRyNig35FvpvETW/videos" | \
  python3 -c "import json,sys;[print('position',e['position'],'|',e['video']['name']) for e in json.load(sys.stdin)['data']]"

实测回显（第二条）：

position 1 | PeerTube v8.3.2 上传实测视频 A

6.6 公开配置与实例信息

curl -s http://192.168.146.128:8131/api/v1/config | \
  python3 -c "import json,sys;d=json.load(sys.stdin);print('signup:',d['signup']['allowed']);print('live:',d['live']['enabled']);print('transcoding web_videos/hls:',d['transcoding']['web_videos']['enabled'],d['transcoding']['hls']['enabled'])"

实测回显：

signup: False
live: False
transcoding web_videos/hls: True True

七、运维组合场景（实战串讲）

  1. 忘记管理员口令：reset-password.js -u root（5.1）→ 新口令登录 → API 改密固定；
  2. 磁盘告警：先 prune-storage.js -v（5.3）清孤儿文件，再核对 storage/original-video-files（若开了保留原始文件，关闭配置可省一半空间）；
  3. 缩略图花屏/丢失：house-keeping.js --fix-thumbnails（5.4）；
  4. 实例换域名/IP：改配置 → update-host.js --previous-host 旧 --new-host 新（5.5，先备份）；
  5. 批量发布：CLI upload 循环或 API POST /videos/upload 脚本化；大文件改用 resumable 端点（/api/v1/videos/upload/resumable，官方 API 参考有完整握手流程）；
  6. 排查路由 4xx：临时调 debug 日志（配置篇 log 段），看 API express handler not found 行即可确认方法/路径错配。

八、v8 与旧文档不一致点实录

本篇实测确认的 API/工具变更，网上旧教程易踩：

旧写法v8.3.2 实测行为正确写法
GET /api/v1/oauth/local/clients400 空响应GET /api/v1/oauth-clients/local
PATCH /api/v1/users/me400 空响应（路由未注册）PUT /api/v1/users/me（带 currentPassword）
上传文件字段 fileMulterError: Unexpected file field字段名 videofile
DELETE /api/v1/video-channels/3（数字 id）404DELETE /api/v1/video-channels/{name}
npm run cli（编排部署形态）无此脚本独立安装 @peertube/peertube-cli

九、安全与边界说明

  • 令牌与口令：示例中的 access_token 均为演示口令下的临时令牌，正式环境令牌等同于账号本身，不落日志、不入代码库；
  • auth add 凭据文件与 auth list 回显都会暴露口令/令牌，共享服务器注意 chmod 600 ~/.config/PeerTube/*；
  • 直播推流（RTMP）、对象存储、联邦管理 API 等命令面在单实例内网实验中未展开，边界如实标注，方法与本文一致；
  • 运维脚本与实例同版本发布，跨版本执行可能引入数据格式不兼容，升级后用 peertube-cli --version 与实例版本对齐。

十、参考链接