ClipBucket 常用命令与运维实战

ClipBucket V5 运维手册：服务管理与五合一健康检查、常用 SQL、转码链路与 cron 批量转码实测、上传→转码→播放 E2E、备份恢复演练（mysqldump+tar，行数核验）与十条排障实录。

ClipBucketClipBucket流媒体视频转码备份恢复PHP2026/10/28

ClipBucket 常用命令与运维实战

目标：给 ClipBucket V5（v5.5.3-#221）管理员一份可照抄的运维手册——服务管理、数据库、日志、转码链路（含手动转码与定时任务）、上传→转码→播放全链实操、备份恢复，以及本专栏实测过程中沉淀的排障清单。全部命令与输出均来自 2026-10-28 实测；部署过程见《ClipBucket Docker Compose 部署实战》，参数含义见《ClipBucket 配置参数详解》。

一、环境信息

  • 应用版本：ClipBucket V5 v5.5.3-#221（官方镜像 oxygenz/clipbucket-v5:latest，内置栈 Nginx 1.26.3 / PHP-FPM 8.5.12 / MariaDB 11.8.6 / Redis / FFmpeg 7.1.5）
  • 服务编排：Docker Compose v5.6.1，项目 clipbucket-5.5.3-stack，服务名 clipbucket，服务实例名 clipbucket-5.5.3-web，对外端口 8142→80
  • 持久化：/var/lib/mysql（数据库）与 /srv/http/clipbucket（站点）均为宿主目录挂载
  • 示例账号：admin / q1w2e3r4
  • 站点内路径约定：站点根 = /srv/http/clipbucket，Web 根 = /srv/http/clipbucket/upload

二、服务管理命令

以下命令在宿主 /opt/data/quzuo/tmp/clipbucket/compose（编排文件所在目录）执行。

docker compose ps                      # 服务状态
docker compose restart clipbucket      # 重启服务
docker compose up -d --force-recreate  # 变更编排后重建（数据卷不受影响）
docker compose logs -f clipbucket      # 实时日志

docker compose ps 实测回显：

NAME                   IMAGE                          COMMAND           SERVICE      CREATED          STATUS          PORTS
clipbucket-5.5.3-web   oxygenz/clipbucket-v5:latest   "entrypoint.sh"   clipbucket   36 minutes ago   Up 36 minutes   0.0.0.0:8142->80/tcp, [::]:8142->80/tcp

服务内健康速查（一条命令验五个组件，实测回显注释）：

docker exec clipbucket-5.5.3-web bash -c \
  'curl -s -o /dev/null -w "web:%{http_code}\n" http://127.0.0.1/; \
   redis-cli ping; \
   mariadb -uroot -e "SELECT 1" | tail -1; \
   ffmpeg -version | head -1 | cut -d" " -f1-3; \
   php -v | head -1'

web:200
PONG
1
ffmpeg version 7.1.5-0+deb13u1
PHP 8.5.12 (cli)

三、数据库访问与常用 SQL

服务内置 MariaDB 客户端，root 免密走本地 socket：

docker exec -it clipbucket-5.5.3-web mariadb -uroot clipbucket

高频查询（实测可用）：

-- 视频状态总览
SELECT videoid, title, file_name, status, active, broadcast, views
FROM cb_video ORDER BY videoid DESC;

-- 转码队列（等待处理的记录）
SELECT Q.id, V.file_name, V.status, Q.date_added, Q.is_completed
FROM cb_video_conversion_queue Q JOIN cb_video V ON V.videoid=Q.videoid
ORDER BY Q.id DESC LIMIT 10;

-- 配置键值（改配置先看这里）
SELECT name, value FROM cb_config WHERE name LIKE 'max_%' OR name LIKE 'proxy_%';

-- 用户与站点信息
SELECT userid, username, email, level FROM cb_users;
SELECT * FROM cb_version;   -- 数据库结构版本（实测 5.5.3 / 221）

实测 cb_video 状态分布（本文写作时）：

videoid  title    status
1        c        Successful
2        second   Successful

💡 结构提示：库共 122 张表（实测 SHOW TABLES 计数）。若你的库缺表（如 tags 系列），见第 8.4 节断链导入修复。

四、日志体系

日志路径内容
转码日志（按天分目录）upload/files/logs/<Y/m/d>/<file_name>.log逐行转码过程 + 输出详情 JSON 摘要
服务启动日志docker compose logs clipbucketMariaDB/Redis/Nginx/PHP 启动横幅与告警
Nginx/PHP 运行日志服务内 /var/log/nginx/、/var/log/php8.5-fpm.log请求错误、PHP 致命错误

转码日志实测尾行（videoid=1，15 秒源片，耗时 4.4 秒）：

==========================================
Conversion completed
==========================================
2026-10-28 10:22:28- Time Took : 4.4126 seconds
Conversion_status : completed

五、转码链路实战

5.1 链路全景（代码实测口径）

Web 上传 → files/temp/<随机名>.mp4 →（file_uploader 入库 cb_video=Waiting，
        写 cb_video_conversion_queue 队列行，源文件落 files/conversion_queue/<Y/m/d>/）
        → 转码器（CLI：php actions/video_convert.php <file_name>）
        → FFmpeg 按启用档位输出 ≤ 源片分辨率的多码率 MP4（files/videos/<Y/m/d>/）
          + webp 缩略图（files/thumbs/video/<Y/m/d>/<file_name>/）
        → 队列行 is_completed=1，cb_video.status=Successful

分辨率档位来自 cb_video_resolution 表（实测 7 行：240p/360p/480p/720p/1080p 启用，1440p/2160p 默认停用，各含宽高与码率）。640×360 源片实测只产出 240p+360p——高于源片的档位自动跳过。

5.2 手动转码（单个视频）

docker exec clipbucket-5.5.3-web bash -c \
  'cd /srv/http/clipbucket/upload && php actions/video_convert.php 179318291709958'

CLI 静默运行（进度与结果全部写入第 4 节的转码日志）。两条实测行为：

  • 无参数直接执行：静默退出（$argv[1] 缺失即 die，退出码 0）——cron 配置必须传文件名；
  • 可选第二参数为音轨号（$argv[2]，多音轨视频选轨转码）。

5.3 定时转码（cron 实测可用的一行命令）

等待处理 = cb_video.status='Waiting' 且队列行未完成。实测通过的扫描+转码循环（服务内 crontab 示例，每分钟一次）：

* * * * * cd /srv/http/clipbucket/upload && for FN in $(mariadb -uroot clipbucket -N -e "SELECT V.file_name FROM cb_video V LEFT JOIN cb_video_conversion_queue Q ON Q.videoid=V.videoid WHERE V.status='Waiting' AND (Q.is_completed=0 OR Q.is_completed IS NULL);"); do php actions/video_convert.php "$FN"; done

实测执行结果（videoid=2 演示）：

videoid  title    status
1        c        Successful
2        second   Successful      ← Waiting → Successful，队列行 is_completed=1

配套的收尾动作 actions/verify_converted_videos.php（内部触发 verify_converted_videos_cron 钩子，用于核对转换产物与缩略图）同样适合放进 cron。

5.4 上传→转码→播放全链实操（E2E 复盘）

自造源片（容器内置 FFmpeg，640×360 + 440Hz 音轨，15 秒）：

docker exec clipbucket-5.5.3-web bash -c \
  'ffmpeg -f lavfi -i testsrc=size=640x360:rate=25 -f lavfi -i sine=frequency=440:sample_rate=44100 \
   -t 15 -c:v libx264 -preset ultrafast -pix_fmt yuv420p -c:a aac -shortest -y /tmp/cbdemo.mp4'

Web 上传（浏览器登录 admin → Upload；或等价的 HTTP 调用：登录 actions/login.php 后向 actions/file_uploader.php POST 分片四件套 chunk/chunks/name/unique_id + Filedata 文件）。实测响应：

{"success":"yes","file_name":"179318291709958","videoid":1}

转码完成后逐项验证（实测）：

验证项URL / 路径实测结果
多码率文件files/videos/2026/10/28/-240.mp4、-360.mp4（464KB 源 → 360p 输出 517939 字节）
缩略图files/thumbs/video/2026/10/28/179318291709958/5 帧 webp（512x320/768x480/original）
视频可播GET /files/videos/.../179318291709958-360.mp4200，字节数一致
观看页GET /watch_video.php?v=1200，播放器 video-js 标记，标题正常
播放计数cb_video.views0 → 2（访问即计）

六、备份与恢复

6.1 备份（实测命令）

# 数据库（一致性快照）
docker exec clipbucket-5.5.3-web bash -c \
  'mkdir -p /tmp/cb_backup && mariadb-dump -uroot --single-transaction --routines clipbucket \
   > /tmp/cb_backup/db-clipbucket-$(date +%F).sql'

# 视频产物 + 缩略图 + 站点配置文件
docker exec clipbucket-5.5.3-web bash -c \
  'cd /srv/http/clipbucket/upload && tar czf /tmp/cb_backup/files-$(date +%F).tar.gz \
   files/videos files/thumbs includes/config.php'

实测产出：

-rw-r--r-- 1 root root  571755 Oct 28 10:31 db-clipbucket-2026-10-28.sql
-rw-r--r-- 1 root root 2173603 Oct 28 10:31 files-2026-10-28.tar.gz

把 /tmp/cb_backup 拷回宿主（docker cp）即完成离线归档。规模化建议：把 mariadb-dump 与 tar 挂 cron 每日执行，输出落到挂载的数据盘。

6.2 恢复演练（实测）

新建临时库导入备份 SQL，核验行数后清理：

docker exec clipbucket-5.5.3-web bash -c \
  'mariadb -uroot -e "DROP DATABASE IF EXISTS cb_restore_test; CREATE DATABASE cb_restore_test;" && \
   mariadb -uroot cb_restore_test < /tmp/cb_backup/db-clipbucket-2026-10-28.sql && \
   mariadb -uroot cb_restore_test -N -e "SELECT COUNT(*) FROM cb_video; SELECT COUNT(*) FROM cb_users;"'

实测回显（与源库一致：视频 1 条、用户 2 条）：

1
2

⚠️ 恢复到真实站点时按镜像部署约定处理数据目录属主（本环境 UID/GID=1000），并保持 includes/config.php 与备份同源。

七、命令速查表

目的命令
服务状态/日志docker compose ps / docker compose logs -f clipbucket
组件健康第三节五合一命令
进站点 shelldocker exec -it clipbucket-5.5.3-web bash
进数据库docker exec -it clipbucket-5.5.3-web mariadb -uroot clipbucket
手动转码单个php actions/video_convert.php <file_name>
批量转码（cron）5.3 节扫描循环
收尾核验（cron）php actions/verify_converted_videos.php
看转码日志cat files/logs/<Y/m/d>/<file_name>.log
备份6.1 节两条
站点配置表SELECT name,value FROM cb_config WHERE ...

八、排障实录汇编（实测沉淀）

  1. 数据库起不来，连接报 socket 111：MariaDB 日志见 [ERROR] Aborting / 权限表打不开。根因：数据目录为空（bind mount 盖掉初始化数据）。处置：把镜像内 /var/lib/mysql 初始化内容拷入挂载目录并 chown -R 1000:1000（见部署篇 3.3），或改用命名卷。
  2. 打开安装器/后台 500：版本检查需出网（update.class.php:104 用 file_get_contents+stream context 拉 JSON）。无外网临时关 allow_url_fopen；有代理就在后台配 proxy_enable/proxy_url/proxy_port（实测该配置生效于 stream context 与 cURL 两条链路）。
  3. 向导过了数据库页但后续页 500：includes/config.php 未生成时框架回退加载不存在的 dbconnect.php。跑完向导配置生成步即可；手工补齐按 553 字节模板（$DBHOST/$DBNAME/$DBUSER/$DBPASS/$DBPORT+TABLE_PREFIX）。
  4. 安装器删不掉/重复可进：安装锁 files/temp/install.me。删除即锁（实测删除后访问 /cb_install/ 302 回首页）。
  5. 裸 POST 上传报 file_uploader : missing infos：enable_chunk_upload=yes 时必须带 chunk/chunks/name/unique_id。另有 Invalid Content : application（实测复现）= 上传内容损坏/为空，检查源文件本身。
  6. 观看页跳首页：videosSection=no（分区开关默认全关）。后台 Basic Configuration 打开即恢复（实测 302→200）。
  7. 上传标题只有一个字：max_video_title=1（默认）。上传接口按它 mb_substr 截断文件名；调大后新上传标题完整（实测第二条视频标题 second 正常落库）。该限制同时作用于各类写入口的标题校验。
  8. 查视频返回空（get_video 为 null）：cb_version 标称新版本但 tags 系列表缺失（安装器 SQL 导入断链且不回滚版本号）。用 cb_install/sql/structure.sql（幂等）重导补齐 122 张表。
  9. CLI 直插视频记录报 You are not logged in：submit_upload 依赖登录态，官方路径是 Web 上传入队 + cron 转码，不要用脚本伪造入库。
  10. MariaDB 启动日志 io_uring_queue_init() failed with EPERM：宿主内核禁用 io_uring 时 MariaDB 自动回退 libaio（实测回显 create_uring failed: falling back to libaio），无功能影响，可忽略。

九、参考