PeerTube 8.3.2 配置参数详解

目标：逐段吃透 PeerTube v8.3.2 的配置体系——配置文件加载层级、production.yaml 各段参数含义、环境变量覆盖机制，并给出可复现的"修改→重启→验证"闭环实例（转码分辨率与 WebTorrent-P2P 实测闭环）。基于 Ubuntu 服务器上的 v8.3.2 实测（2026-10-27），验证素材由 ffmpeg 自造并在正文标注；涉及未实测的段落均如实标注边界。

一、环境信息

• 操作系统：Ubuntu 24.04.5 LTS（x86_64）
• PeerTube 版本：v8.3.2（2026-10-27 GitHub Releases 实查之最新稳定版）
• 部署形态：Compose 编排部署（部署细节见《PeerTube 8.3.2 Docker Compose 部署指南》）；本篇只谈配置，命令均为服务器视角
• 配置验证实例：http://192.168.146.128:8131，管理员 root / q1w2e3r4（演示口令）
• 配置文件层级实测载体：自定义配置目录（服务器裸装形态对应 /var/www/peertube/config/，编排形态对应配置挂载目录 /config），二者在加载层级中位置相同，参数语义完全一致

说明：v8.3.2 镜像内置的默认配置文件为 /app/config/default.yaml（870 行，全部配置项的出厂默认值）；本篇引用的"默认值"均摘自该文件原文（2026-10-27 从运行实例导出核对）。

二、前置条件

1. 一台可访问的 PeerTube v8.3.2 实例（部署见系列部署篇）；
2. 管理员具备修改配置目录的权限（裸装形态：sudo -u peertube vim /var/www/peertube/config/production.yaml）；
3. 熟悉 YAML 缩进与字符串引号规则（PeerTube 配置含数组与布尔量，格式错误会导致服务拒绝启动，见第十章 FAQ）；
4. 重启手段：sudo systemctl restart peertube（裸装 systemd 服务，官方安装文档注册的标准服务名）。

三、配置的加载层级与两种修改方式

v8.3.2 服务启动时第一行日志就打印配置加载层级（实测回显，逐行照抄）：

[192.168.146.128:8131] 2026-10-27 02:48:02.183 info: Using following configuration file hierarchy: /app/config/default.yaml -> /app/support/docker/production/config/production.yaml -> /app/support/docker/production/config/custom-environment-variables.yaml.

写入自定义 production.yaml 后层级变为四段（实测回显）：

[192.168.146.128:8131] 2026-10-27 02:48:02.183 info: Using following configuration file hierarchy: /app/config/default.yaml -> /app/support/docker/production/config/production.yaml -> /config/production.yaml -> /app/support/docker/production/config/custom-environment-variables.yaml.

规则总结（node-config 机制，官方镜像内置路径如实呈现）：

两种修改方式按场景选择：

1. 临时/环境相关项（主机名、端口、数据库密码）：用环境变量（部署篇 .env 方式），不落文件；
2. 业务策略项（转码、注册、配额、联邦）：写自定义 production.yaml，改动可控、可版本化。

裸装形态的标准路径（官方源码安装文档）：配置目录为 /var/www/peertube/config/，其中 production.yaml 从仓库模板复制而来；服务以 NODE_CONFIG_DIR=/var/www/peertube/config NODE_ENV=production 运行。

四、环境变量覆盖机制

官方文件 custom-environment-variables.yaml（v8.3.2 版 137 行）定义了"环境变量 → 配置项"的映射，常用的映射关系（摘自该文件原文）：

实测确认过的行为：.env 中 PEERTUBE_LOG_LEVEL=info 时日志为 info 级；改为 debug 并重建服务后，日志立刻出现大量 debug: 行（例如每个请求的 body 与校验细节），验证了环境变量对 log.level 的覆盖生效。改回 info 后 debug 行消失——环境变量优先于文件，排查配置"不生效"时先查环境变量是否同名覆盖。

五、参数总览

default.yaml（v8.3.2）顶层配置段全集（含行号定位，便于对照源文件）：

下文挑选影响面最大的段落详解并给出验证闭环；其余段落以默认值表形式列出。

六、核心参数详解与验证闭环

6.1 webserver 段——实例对外身份

default.yaml 出厂值：

webserver:
  https: false
  hostname: 'localhost'
  port: 9000

本篇实测值（写入自定义 production.yaml，等价于部署篇 .env 环境变量方式）：

webserver:
  hostname: 192.168.146.128
  port: 8131
  https: false

这三个值会写进所有对外 URL：视频播放地址、HLS 分片地址、ActivityPub actor id、分享链接与嵌入代码。验证：上传视频后从 API 返回中核对 URL 域名端口（实测回显，视频 A 的 HLS 播放列表地址）：

playlistUrl: http://192.168.146.128:8131/static/streaming-playlists/hls/51b8bafe-5f89-4677-9ff9-65414027f5ad

⚠️ 修改代价：hostname/https 属于"实例级身份"，变更后旧 URL 全部失效，官方提供 update-host.js 迁移脚本重写数据库与种子文件（用法见系列命令篇）。上线前一次定准，之后不要再改。

6.2 database 段——连接与连接池

default.yaml 出厂值（原文）：

database:
  hostname: '127.0.0.1'
  port: 5432
  ssl: false
  suffix: '_dev'
  username: 'peertube'
  password: 'peertube'
  pool:
    max: 5

要点：

• 裸装生产环境应把 hostname 指向数据库地址、password 换强口令；编排形态常用环境变量（PEERTUBE_DB_*）注入，本篇部署即用 .env（实测连接成功，启动日志 Database peertube is ready.）；
• suffix: '_dev' 是给开发模式加库名后缀用的，生产配置必须显式置空或保持无后缀意识，否则连的库名会带 _dev；
• pool.max 默认 5，大流量实例可随内存调大（PeerTube 主要瓶颈通常在转码而非连接池）。

6.3 redis 段——队列与缓存

出厂默认 hostname: '127.0.0.1'、port: 6379，可选 auth、db（编号）、pool。编排形态用环境变量 PEERTUBE_REDIS_HOSTNAME=redis 指向服务名（本篇实测通过，转码队列正常出队——视频上传后 30 秒内完成 HLS 生成）。Redis 故障时的典型表象是：上传成功但转码队列不再推进、登录限流失效。

6.4 storage 段——数据目录规划

default.yaml 出厂值（裸装默认相对路径，基于 PeerTube 安装目录；原文全列）：

storage:
  tmp: 'storage/tmp/'
  tmp_persistent: 'storage/tmp-persistent/'
  bin: 'storage/bin/'
  avatars: 'storage/avatars/'
  web_videos: 'storage/web-videos/'
  streaming_playlists: 'storage/streaming-playlists/'
  original_video_files: 'storage/original-video-files/'
  redundancy: 'storage/redundancy/'
  logs: 'storage/logs/'
  previews: 'storage/previews/'
  thumbnails: 'storage/thumbnails/'
  storyboards: 'storage/storyboards/'
  torrents: 'storage/torrents/'
  captions: 'storage/captions/'
  cache: 'storage/cache/'
  plugins: 'storage/plugins/'
  well_known: 'storage/well-known/'
  uploads: 'storage/uploads/'
  client_overrides: 'storage/client-overrides/'

裸装生产路径即 /var/www/peertube/storage/...。本篇实测实例落盘后目录树（实测回显，find <数据目录> -maxdepth 1 -type d | sort）：

/data
/data/streaming-playlists
/data/client-overrides
/data/original-video-files
/data/plugins
/data/uploads
/data/bin
/data/previews
/data/captions
/data/avatars
/data/storyboards
/data/tmp
/data/thumbnails
/data/cache

容量规划提示：streaming-playlists（HLS 分片）通常是大头；original-video-files 只有开启"保留原始文件"（transcoding.original_file.keep）才会增长；cache 与 tmp 可随清理脚本释放（见系列命令篇 prune-storage 一节）。

6.5 log 段——日志级别

出厂值 log.level: 'info'，可选 debug/info/warn/error。本篇实测调试经历：排查 API 异常时把 PEERTUBE_LOG_LEVEL 置 debug，日志随即输出请求级细节（含"API express handler not found"这类路由未命中提示，正是靠它定位到 v8 的 PATCH→PUT 变更）；恢复 info 后 debug 行消失。生产建议保持 info，仅在排障时临时调级并记得改回。

6.6 transcoding 段——转码策略（含实测闭环）

default.yaml 出厂值（v8.3.2 原文，重点行）：

transcoding:
  enabled: true
  original_file:
    keep: false
  remote_runners:
    enabled: false
  threads: 1
  concurrency: 1
  profile: 'default'
  available_profiles: []
  resolutions:
    0p: false
    144p: false
    240p: false
    360p: false
    480p: false
    720p: false
    1080p: false
    1440p: false
    2160p: false
  always_transcode_original_resolution: true
  always_transcode_podcast_optimized_audio: true
  fps:
    max: 60
  web_videos:
    enabled: false
  hls:
    enabled: true

三个出厂行为的实测印证（视频 A/B 为 720p 源）：

1. resolutions 全 false + always_transcode_original_resolution: true → 只生成与源同分辨率的 HLS（视频 A 详情 API 实测：HLS 仅 720p 一档）；
2. web_videos.enabled: false → 不生成 WebTorrent 用的 mp4（web-videos 目录只出现播客音频优化产物 -0.mp4，源自 always_transcode_podcast_optimized_audio: true）；
3. hls.enabled: true → HLS 必开。

修改→重启→验证闭环（本篇核心实验）：在自定义 production.yaml 中开启 360p 档与 WebTorrent 产物：

# <自定义配置目录>/production.yaml
transcoding:
  web_videos:
    enabled: true
  resolutions:
    360p: true

重启服务（裸装：sudo systemctl restart peertube；编排形态重启主服务），再上传 720p 测试视频 C（ffmpeg 自造，testsrc2 图案 + 660Hz 正弦音，12 秒）：

ffmpeg -y -f lavfi -i testsrc2=size=1280x720:rate=25:duration=12 \
  -f lavfi -i sine=frequency=660:duration=12 \
  -vf "drawtext=text='PeerTube v8.3.2 Test Video C':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-c.mp4

AT=<管理员令牌>
curl -s -X POST -H "Authorization: Bearer $AT" http://192.168.146.128:8131/api/v1/videos/upload \
  -F "name=PeerTube v8.3.2 转码配置实测视频 C" -F "channelId=1" -F "privacy=1" \
  -F "description=ffmpeg 自造测试视频 C，用于验证开启 360p 与 web_videos 后的转码产物" \
  -F "videofile=@peertube-test-c.mp4;type=video/mp4"

约 35 秒转码完成后查询详情（实测回显）：

state: {'id': 1, 'label': 'Published'}
WEBVID res 720 | 3477.4 KB
WEBVID res 360 | 1849.8 KB
WEBVID res 0 | 91.6 KB      ← 播客音频优化产物
HLS res 720 | 3461.9 KB
HLS res 360 | 1842.9 KB

同时公开配置 API 确认新策略已生效（实测回显）：

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

True True

闭环结论：resolutions 按需开启（每档都增加转码时长约 30%~40% 与对应存储），web_videos 决定 P2P 分发产物是否存在——两个开关独立、可组合。

6.7 live 段——直播

出厂默认即关闭（公开配置 API 实测回显：live.enabled: False | allowReplay: True | rtmpPort: 1935）。开启直播需要三件事：配置 live.enabled: true、放行 RTMP 端口（默认 1935）、评估 CPU（live.transcoding 可设 enabled: false 让推流端承担编码）。官方文档明确直播是资源大户，小实例建议按需开启并限制并发路数（live.max_instance_lives / max_user_lives）。

6.8 signup 与 user 段——注册与配额

出厂值 signup.enabled: false（公开配置 API 实测：signup.allowed: False）。开启注册时配套项：

公开 API 中的用户配额字段实测回显（/api/v1/config 的 user 段键）：['videoQuota', 'videoQuotaDaily']。面向公众开注册的实例，官方推荐组合：requiresEmailVerification: true + requiresApproval: true + 显式配额。

6.9 object_storage 段——对象存储（边界标注）

出厂 enabled: false。开启后支持 S3 兼容存储承接视频/分片上传（endpoint/region/bucket/密钥/ACL 等参数齐全，官方另有 PEERTUBE_OBJECT_STORAGE_UPLOAD_ACL_* 环境变量映射）。本篇未实测对象存储（实验环境无 S3 服务），如实标注：参数语义以官方 custom-environment-variables.yaml 与 default.yaml 注释为准，验证方法与本文闭环一致（开启后 storage.streaming_playlists 等路径行为切换为远端）。

6.10 federation / followers / blocklist 段——联邦边界

出厂即联邦就绪但实例自由：federation.enabled: true、federation.videos.federate_unlisted: false；followers.instance.enabled（允许被别人关注）与 followings.instance.autoFollowIndex（自动跟随官方索引实例）都可按实例策略收紧/放开。本篇实验为单实例环境，联邦握手未实测（需第二个公网可达实例），如实标注边界；本地已验证的是联邦元数据的对外暴露：频道页 ActivityPub URL 正常返回（频道 URL 实测回显 http://192.168.146.128:8131/video-channels/testchannel）。

6.11 import 段——远程导入

出厂 import.videos.http.enabled: false、import.videos.torrent.enabled: false（公开配置 API 实测回显确认）。允许用户从任意 URL/种子导入视频前，官方建议显式开启并配置 import.videos.http.proxy 走代理出口，避免 SSRF 风险；面向公众的实例谨慎放开。

七、生产配置模板（精选覆盖层）

以下模板只包含"建议覆盖出厂值的项"，可直接作为自定义 production.yaml 起点（其余全部继承 default.yaml）：

webserver:
  hostname: video.example.com   # 改成你的域名/IP
  port: 443
  https: true

listen:
  port: 9000

database:
  hostname: <数据库地址>
  port: 5432
  ssl: false
  suffix: ''
  username: peertube
  password: <数据库强口令>
  pool:
    max: 10

redis:
  hostname: <Redis地址>
  port: 6379
  auth: <Redis口令或置空>

smtp:
  hostname: <SMTP服务器>
  port: 587
  username: <账号>
  password: <口令>
  from_address: peertube@example.com
  tls: true
  disable_starttls: false

admin:
  email: admin@example.com

log:
  level: 'info'

transcoding:
  enabled: true
  threads: 2                    # 建议留 1-2 核给 Web/数据库
  concurrency: 2                # 并行转码任务数，按核数调整
  resolutions:
    360p: true
    720p: true
  web_videos:
    enabled: true               # 需要 P2P 分发才开
  hls:
    enabled: true

live:
  enabled: false                # 资源评估后再开

signup:
  enabled: false                # 面向公众时再开并配审批/邮箱验证

八、验证方法总集

配置修改后的验证手段（本篇全部实测过）：

1. 看启动日志第一行：配置层级是否出现你的文件（见第三章回显）；
2. 公开配置 API：GET /api/v1/config 返回 transcoding/live/signup/import 等生效值；
3. 行为验证：如转码档位用"上传自造视频→查详情 files/streamingPlaylists"闭环；
4. URL 检查：webserver 段改动后看新视频的 fileUrl/playlistUrl 域名端口。

九、修改不生效排查清单

1. 环境变量同名覆盖：PEERTUBE_* 变量优先于文件（第四章实测），先查部署环境变量；
2. 改完没重启：production.yaml 只在启动时读取一次，sudo systemctl restart peertube 后再看（编排形态需重建服务而非 reload）；
3. 层级放错：自定义文件必须在 NODE_CONFIG_DIR 指向的目录（裸装 /var/www/peertube/config/），且文件名必须是 production.yaml；
4. YAML 语法错误：服务会拒绝启动，journalctl -u peertube -n 50 看解析报错行号（典型：布尔值写成字符串、冒号后缺空格）；
5. 值域不对：分辨率键只认 0p/144p/240p/360p/480p/720p/1080p/1440p/2160p，写 4k 无效。

十、参考链接

• 官方配置文档：https://docs.joinpeertube.org/install/any-source （production.yaml 说明）
• 出厂默认值全集（v8.3.2）：https://github.com/Chocobozzz/PeerTube/blob/v8.3.2/config/default.yaml
• 环境变量映射全集：https://github.com/Chocobozzz/PeerTube/blob/master/support/docker/production/config/custom-environment-variables.yaml
• 管理面板配置（与文件配置的关系）：https://docs.joinpeertube.org/admin/configuration
• 站内系列：《PeerTube 介绍与选型指南》、《PeerTube 8.3.2 Docker Compose 部署指南》、《PeerTube 8.3.2 常用 CLI 命令详解》