peertube

peertube — 在终端中浏览 PeerTube 联邦视频

在终端中浏览任意 PeerTube 实例——这是一个联邦部署，而非单一 API：查看实例统计信息、最新视频、完整视频详情、评论串、频道、账户和实例内搜索。仅在执行自己的账户命令时使用 OAuth2 进行身份验证。除 login/logout 外，所有命令均为只读操作。

设置

1. 选择要连接的实例。每条命令都针对单个实例；API 结构处处相同，但账户、令牌、规则和目录各不相同：

export PEERTUBE_SERVER="https://<INSTANCE_HOST>"   # e.g. https://tilvids.com

如要搜索整个联邦宇宙，而非单个实例，请将同一个变量指向公共搜索索引：PEERTUBE_SERVER=https://sepiasearch.org（API 结构相同——参见 references/search-and-discovery.md）。

2. 浏览无需其他设置：视频、搜索、频道、评论和实例信息均可匿名读取。

3. （可选）仅在执行自己的账户命令（me、my-videos）时登录：

scripts/peertube login --username <NAME> --prompt

身份验证的工作方式

PeerTube 使用标准 OAuth2，并为每个实例配置客户端凭据：CLI 会匿名从 GET /api/v1/oauth-clients/local（单数形式的 local）获取客户端凭据对，然后通过 POST /api/v1/users/token 将你的用户名和密码换成持有者令牌（grant_type=password，采用表单编码）。令牌通过 Authorization: Bearer <token> 传递，其有效期由实例配置决定（读取响应中的 expires_in——不要假定为固定时长），过期时会自动刷新。令牌文件会以仅所有者可访问的权限写入 ~/.config/peertube/token.json，并以服务器 URL 为键。 不要提交令牌——它们是账户凭据；使用完毕后，通过 scripts/peertube logout（POST /users/revoke-token）撤销。当前的生产实例会在 API 响应中隐藏 client_secret；CLI 会检测到此情况并说明解决方法。 详细说明和线级错误特征见： references/auth-and-tokens.md。

核心命令

server — 实例统计信息和身份信息（匿名）

scripts/peertube server              # name, description, user/video/view counters
scripts/peertube server --json

组合使用 GET /config/about 和 GET /server/stats（规范路径——不存在 /instance/stats）。

videos — 浏览实例上传的视频（匿名）

scripts/peertube videos                       # latest 15, offset pagination
scripts/peertube videos --limit 50 --offset 50
scripts/peertube videos --sort -views --json  # popular first

分页使用 start/count 偏移量（count 最大为 100）——API 没有 page 参数。

search — 在此实例上查找视频（匿名）

scripts/peertube search --query "linux"            # instance-local (searchTarget=local)
scripts/peertube search -q "docker" --limit 20 --json
PEERTUBE_SERVER="https://sepiasearch.org" scripts/peertube search -q "linux"   # fediverse-wide

捆绑的 CLI 仅执行实例内搜索（searchTarget=local）。如要搜索整个联邦宇宙，请将 PEERTUBE_SERVER 指向 SepiaSearch——命令相同，索引范围更广。搜索结果包含 channel.host/url，即联邦搜索结果来源实例的信息。

video — 查看单个视频的完整详情（匿名）

scripts/peertube video --id <UUID>          # numeric id, UUID, or shortUUID all work
scripts/peertube video --id <UUID> --json | jq '{name, description, views, url}'

comments — 顶级评论串（匿名）

scripts/peertube comments --id <UUID>                 # GET /videos/{id}/comment-threads
scripts/peertube comments --id <UUID> --limit 30 --json

channels / channel / account — 创作者（匿名）

scripts/peertube channels --limit 20 --json           # instance channel list
scripts/peertube channel --handle [email protected]   # name or name@host
scripts/peertube account --name [email protected]

channel 会显示元数据以及该频道上传的视频（按偏移量分页）。

me / my-videos — 你的账户（需要登录）

scripts/peertube me --json | jq '.role.label'
scripts/peertube my-videos --limit 50 --json

login / logout — OAuth2 会话管理

scripts/peertube login --username <NAME> --prompt        # hidden prompt
echo "<PASSWORD>" | scripts/peertube login --username <NAME> --password-stdin
scripts/peertube login --username <NAME> --otp <CODE>    # 2FA-enabled accounts
scripts/peertube logout                                   # revoke server-side + delete file

全局标志

scripts/peertube --json videos                     # flag before or after the subcommand
scripts/peertube videos --json
scripts/peertube --dry-run search --query test     # request plan, zero network
scripts/peertube --verbose videos --limit 2        # trace requests on stderr
scripts/peertube --server https://tilvids.com server   # per-invocation instance override

--dry-run 会输出 {"dry_run": true, "method", "path", "params"}（login 仅添加 form_fields 字段名，不包含值）——可用它在实际运行前验证 jq 命令链。--help 和 --dry-run 均无需凭据。

管道用法示例

搜索后查看排名第一的结果

scripts/peertube search --query "linux" --limit 5 --json | jq -r '.videos[0].uuid'
scripts/peertube video --id "$(scripts/peertube search -q linux --limit 1 --json | jq -r '.videos[0].uuid')" --json

翻页浏览频道上传的视频

scripts/peertube channel --handle [email protected] --limit 100 --offset 0 --json | jq -r '.videos[].name'
# loop: advance --offset by the returned count until you reach .total (no page param exists)

实例概况

scripts/peertube server --json | jq '{name: .instance.name, videos: .stats.totalLocalVideos, users: .stats.totalUsers, views: .stats.totalLocalVideoViews}'

登录、检查配额并退出登录

scripts/peertube login --username <NAME> --prompt
scripts/peertube me --json | jq '{username, role: .role.label, quota_bytes: .videoQuota}'
scripts/peertube logout

JSON 和 jq

--json 输出键是围绕原始 API 对象的稳定 snake_case 包装：videos （API 的 {total, data} 列表对象）、channels、threads（+ total_not_deleted）、 instance + stats、channel，以及计划中的 dry_run/method/path/params。视频 对象保留 PeerTube 自身的字段名称——uuid、shortUUID、name、duration （秒）、views、publishedAt、account{name,displayName,host}、 channel{name,displayName,host}——因此 jq 选择器可直接用于针对 /api/v1 的原始 curl。 示例：jq -r '.videos[] | [.name, .views, .channel.displayName] | @tsv'。

已知注意事项

• 各实例彼此独立（采用联邦机制，并非共用一个 API）——各实例的账户、令牌、规则、 已启用功能和目录各不相同。来自实例 A 的令牌在实例 B 上会返回 401；CLI 按服务器 URL 区分令牌文件。联邦到某个实例上的内容仍属于其来源（channel.host、视频 url）。
• 搜索范围有两种不同含义——searchTarget=local 搜索实例自己的目录；search-index （或 SepiaSearch 的基础 URL）通过外部索引搜索联邦网络。当前服务器上省略 searchTarget 会使用实例自身范围，而非联邦网络。除非将捆绑的 CLI 指向 sepiasearch.org，否则它只搜索 本地实例。
• 不存在 page 参数——集合使用 start/count 分页（最多 100）。 发送 page= 的客户端会静默地永远重复读取第一页。
• 评论路由是 /comment-threads（带连字符）——/comments 和 /commentthreads 都不是有效路由（当前服务器会对它们返回 400）。
• 实例元数据路径不统一——统计信息位于 /server/stats（操作标题为 “instance stats”），简介位于 /config/about，配置位于 /config。不存在 /instance/* 元数据路径。
• 生产环境会屏蔽 client_secret——当前生产实例上的 oauth-clients/local 会返回 "********************************"；使用被屏蔽的值请求令牌会返回 400。 CLI 会检测到这一情况，并说明前端资源变通方案。旧版快速入门中的 response_type=code 并不属于当前令牌架构——CLI 会省略它。
• 令牌有效期由实例配置——读取每次响应中的 expires_in；CLI 会保存绝对过期时间 expires_at，并自动刷新。令牌应仅允许所有者访问，切勿提交到版本库；注销时应撤销令牌 （仅删除文件不会让会话失效）。
• 双重验证需要 OTP 标头——在令牌请求中使用 x-peertube-otp；CLI 会将普通的 401 映射为“传入 --otp”。
• 速率限制——默认每个 IP 每 10 秒 50 次调用（令牌端点的限制更严格）；遇到 429 时读取 Retry-After 并退避。错误使用 RFC7807 application/problem+json 响应体；未知路由会返回 400（而非 404）——请读取响应体。
• duration 的单位是秒；ID 有三种（id、uuid、shortUUID，详情端点均接受）； role 是对象 {id, label}；videoQuota 的单位是字节。
• 匿名与已认证——浏览、搜索、评论和实例信息无需令牌； /users/me* 和所有变更操作始终需要令牌。

适用场景

当需要对 PeerTube 实例进行只读交互时，请使用此技能：浏览和筛选视频、搜索实例本地内容或 整个联邦网络（通过 SepiaSearch）、查看视频详情和评论、探索频道/账户、查看实例统计信息， 以及通过 OAuth2 管理自己的账户会话（登录、个人资料、我的视频、注销）。

不适用场景

请勿将此技能用于 YouTube、Vimeo 或其他平台的上传，也不要用于任何视频编辑/转码 （转交给这些平台各自的工具和 ffmpeg）；请勿用于安装、托管或管理 PeerTube 服务器 （实例管理不在范围内——捆绑的 CLI 仅支持只读操作以及登录/注销）；也不要用于一般的 ActivityPub/Mastodon 联邦问题（请使用 Mastodon 或 ActivityPub 技能）。

参考文件

文件	用途
references/auth-and-tokens.md	OAuth2 流程（oauth-clients/local、密码授权），密钥屏蔽、刷新/撤销、令牌文件管理、线路错误特征
references/search-and-discovery.md	searchTarget local 与 search-index 的区别、SepiaSearch 语义、搜索参数和排序
references/endpoint-catalog.md	每个读取端点的参数、响应结构、分页、速率限制
references/gotchas-field-guide.md	涵盖每种故障特征和版本差异的症状 → 原因 → 修复对照表
references/worked-recipes.md	多步骤 CLI/jq 工作流、原始 curl 身份验证链、jq 处理模式

可用脚本和先决条件

• scripts/peertube — 捆绑的 Python CLI（--json、--dry-run、--verbose、 --server 覆盖选项）。仅导入标准库和 requests。
• scripts/test_peertube.py — 离线测试套件（兼容 pytest 和 unittest）；所有 HTTP 请求均为模拟，不会产生任何网络流量。
• 需要 Python 3.8+ 和 requests。任何可访问的 PeerTube 实例（或 SepiaSearch） 均可使用；默认情况下不存在也不需要任何凭据。此技能不会启动任何服务。