ClipBucket 配置参数详解

目标：讲清 ClipBucket V5（v5.5.3-#221）的完整配置体系——文件层（config.php / Nginx / PHP）、数据库层（cb_config 表）、后台面板三层的字段含义、默认值、实测修改方法与踩坑记录。所有默认值与修改结果均来自 2026-10-28 实测环境（部署过程见《ClipBucket Docker Compose 部署实战》），版本背景见《ClipBucket 介绍与选型指南》。

一、环境信息

• 应用版本：ClipBucket V5 v5.5.3-#221（cb_version 表实测记录：version=5.5.3, revision=221）
• 内置栈：Nginx 1.26.3 / PHP-FPM 8.5.12 / MariaDB 11.8.6 / FFmpeg 7.1.5 / ffprobe / MediaInfo
• 后台路径：/admin_area/（示例账号 admin / q1w2e3r4）
• 配置取证方式：后台设置页源码解析 + cb_config 表直查 + 修改后落库复核

二、配置体系总览

V5 的配置分三层，修改优先级与作用域各不相同：

加载顺序（includes/common.php 实测代码）：config.php 存在则加载（新体系），否则回退 dbconnect.php（旧体系，v5.5.3 镜像内不存在该文件）。

三、文件层配置

3.1 includes/config.php（安装器生成，553 字节）

实测生成内容（脱敏结构）：

<?php
//Database Host
$DBHOST = '127.0.0.1';
//Database Name
$DBNAME = 'clipbucket';
//Database Username
$DBUSER = 'clipbucket';
//Database Password
$DBPASS = 'q1w2e3r4';
//Database Port
$DBPORT = '3306';
//Setting Table Prefix
define('TABLE_PREFIX', 'cb_');

/*
 * Enable this array to overwrite configurations over DB values
 * This is usefull when you have multiple server working on a single DB with different server configurations
 *
 * $config_overwrite = [
 *    'config_name' => 'config_value'
 * ];
 */

要点：$config_overwrite 是官方提供的"文件级覆盖"机制——同一数据库支撑多台 Web 时，把机器差异（如 ffmpeg 路径）写进该数组即可，优先级高于 cb_config 表值。

3.2 Nginx 站点配置（官方镜像内置）

官方配置（镜像内 nginx-clipbucket.conf，/srv/http/clipbucket/upload 为站点根）关键项实测摘录：

client_max_body_size 2M;

location ~ ^/(includes|changelog|files/temp|cb_install)/ {
    return 302 https://$host/403.php;
}

解读：上传体量被 Nginx 层硬限在 2MB（生产按需调大并同步 PHP 两项，见 3.3）；includes/（源码）、changelog/、files/temp/（上传临时区）、cb_install/（安装器）禁止外部直访。实际验证：includes/config.php 无法从 Web 读取。

3.3 PHP 运行时限制（镜像实测 php -i）

⚠️ 三道闸协同：Nginx client_max_body_size → PHP post_max_size/upload_max_filesize → 业务参数 max_upload_size（cb_config，MB）。生产调大上传限额需三层同时改，取最小值生效。

四、数据库层：cb_config 与相关表

4.1 cb_config 表

结构极简：config_id / name / value。后台所有保存动作最终落到这张表；$config_overwrite 在运行期覆盖其值。

4.2 高频配置行清单（实测默认值）

站点与分区（setting_basic.php）

上传（setting_advanced.php）

转码（setting_advanced.php + cb_video_resolution 表）

💡 实测规律：转码只输出 不超过源片分辨率 的档位。实测 640×360 源片只产出 240p 与 360p 两个文件，虽然 480p/720p/1080p 都处于启用状态。

邮件（setting_advanced.php）

代理（setting_advanced.php，官方功能）

实测该代理配置注入两条链路：版本检查用 file_get_contents 的 stream context（update.class.php:104），其余远程请求走 cURL——代理开启后安装期"打开 /cb_install/ 报 500"的问题即从根上解决（见第七节实录）。

五、后台面板操作要点

5.1 保存机制（实测）

后台两页（Basic / Advanced Configuration）的表单提交是全量字段保存：处理代码按固定字段清单遍历 $_POST（setting_advanced.php:183），因此不能只 POST 想改的几项——漏带的字段会被当空值处理。实测两次全量 POST（共 102 字段）保存后 cb_config 落库值逐项核对一致。

两类自动修正逻辑（源码口径）：布尔型字段非 yes 一律归一为 no；数值型字段 ≤0 一律归 1。分辨率勾选（gen_240p ~ gen_2160p 七个复选框）走独立保存函数（saveVideoResolutions），落 cb_video_resolution 表。

5.2 实测修改演练

通过后台 Advanced Configuration 修改 5 项并保存，复核结果（cb_config 实测回显）：

name                value
max_upload_size     2000
max_video_duration  600
proxy_enable        yes
proxy_port          7897
proxy_url           192.168.1.62

同一演练中把分区开关全部打开（Basic 页），保存后前台观看页立即从"跳转首页"恢复为 200 正常播放——分区开关的生效无需重启服务（PHP-FPM 不缓存配置表值）。

六、敏感与运维相关配置

七、配置排障实录

1. watch 页跳首页：videosSection=no 所致。所有分区开关默认关闭，首次部署后必须先开视频分区（实测开启前 302，开启后 200）。
2. 上传视频标题只有一个字：max_video_title=1（默认）。上传接口用文件名去扩展名后按该上限截断（mb_substr），改成实际需要值（如 100）即可。
3. 安装器/后台间歇 500：版本检查需出网（update.class.php 经 file_get_contents+stream context 拉取 latest/changelog JSON）。无外网环境临时关 allow_url_fopen；有代理则把 proxy_enable/proxy_url/proxy_port 配好（官方代理功能实测可用）。
4. get_video 查视频返回空：cb_version 标称 5.5.3-221 但库中缺 tags 系列表（安装器导入链曾中断且不校验单条 SQL 失败）。用 cb_install/sql/structure.sql（全表 IF NOT EXISTS，幂等）重导补齐 122 张表后恢复。教训：版本行只表明"应达到"的结构，断链导入不回滚版本号。
5. 表单保存后部分配置丢失：后台设置页必须整页提交（全字段遍历保存机制），用脚本/代理只回传部分字段会清掉其余项（见 5.1）。

八、参考

• 本专栏姊妹篇：《ClipBucket 介绍与选型指南》《ClipBucket Docker Compose 部署实战》《ClipBucket 常用命令与运维实战》
• 官方仓库与文档：https://github.com/MacWarrior/clipbucket-v5 、https://docs.clipbucket.com