ClipBucket Docker Compose 部署实战

目标：在一台服务器上用官方镜像与 Docker Compose 完成 ClipBucket V5（v5.5.3）的部署，跑通 Web 安装向导、初始化站点，并完成一次真实视频的上传→转码→播放闭环。本文为部署篇，全部命令与输出均来自 2026-10-28 的实测环境；配置项的完整解读见《ClipBucket 配置参数详解》，命令速查与排障手册见《ClipBucket 常用命令与运维实战》。

一、环境信息

本章实录本次部署的服务器与软件版本，后续所有章节的结论均基于此环境。

• 服务器系统：Linux（内核 6.1+，x86_64），宿主模拟真实服务器视角
• 编排工具：Docker 29.9.2（含 Docker Compose v2 插件）
• 应用版本：ClipBucket V5 v5.5.3-#221（官方镜像 oxygenz/clipbucket-v5:latest，1.86GB，2026-10-28 查询）
• 镜像内置栈：Nginx 1.26.3 + PHP-FPM 8.5.12 + MariaDB 11.8.6 + Redis + FFmpeg 7.1.5 + MediaInfo
• 实验网络：独立桥接网段 10.89.58.0/24
• 对外端口：宿主 8142 → Web 服务 80
• 部署目录规划：/opt/data/quzuo/tmp/clipbucket/compose（编排文件）、/opt/data/quzuo/tmp/clipbucket/data/{db,www}（持久化数据）
• 示例账号：admin / q1w2e3r4

💡 版本提醒：ClipBucket 原版（arslancb/clipbucket）已归档，现役主线是社区维护的 ClipBucket V5（MacWarrior/clipbucket-v5）。背景与选型对比见《ClipBucket 介绍与选型指南》。

二、镜像与部署形态

2.1 官方镜像的三个标签

V5 官方提供 oxygenz/clipbucket-v5 三个系列的标签（README 与 Registry tags 实查，2026-10-28）：

2.2 持久化路径

官方 latest 形态需要持久化两条路径（镜像内路径）：

• /var/lib/mysql：MariaDB 数据目录（镜像内已初始化好权限库，必须整目录持久化）；
• /srv/http/clipbucket：站点根目录（Web 根是其下的 upload/）。

⚠️ 坑点实录：如果用宿主目录（bind mount）而非命名卷挂载 /var/lib/mysql，首次启动会因空目录盖掉镜像内已初始化的数据库而报 [ERROR] Aborting（错误日志特征：Can't open and lock privilege tables / 连接报 Can't connect to local MySQL server through socket (111)）。bind mount 时必须先把镜像内的初始化数据拷出来再用（见 3.3 节第 3 步）；用命名卷则无此问题（首次使用会自动从镜像复制内容）。

三、部署实战

3.1 准备目录与编排文件

mkdir -p /opt/data/quzuo/tmp/clipbucket/compose
mkdir -p /opt/data/quzuo/tmp/clipbucket/data/db
mkdir -p /opt/data/quzuo/tmp/clipbucket/data/www

编写 docker-compose.yml（显式项目名与固定网段，便于与服务器上其他服务隔离）：

name: clipbucket-5.5.3-stack

services:
  clipbucket:
    image: oxygenz/clipbucket-v5:latest
    container_name: clipbucket-5.5.3-web
    restart: unless-stopped
    ports:
      - "8142:80"
    environment:
      DOMAIN_NAME: clipbucket.local
      MYSQL_PASSWORD: q1w2e3r4
      UID: 1000
      GID: 1000
    volumes:
      - /opt/data/quzuo/tmp/clipbucket/data/db:/var/lib/mysql
      - /opt/data/quzuo/tmp/clipbucket/data/www:/srv/http/clipbucket
    networks:
      - cbnet

networks:
  cbnet:
    driver: bridge
    ipam:
      config:
        - subnet: 10.89.58.0/24

环境变量说明（官方镜像 entrypoint 约定）：DOMAIN_NAME 为站点域名；MYSQL_PASSWORD 为内置 MariaDB 的初始化密码（首次建库时生效）；UID/GID 为站点文件属主。

3.2 拉取镜像并启动

cd /opt/data/quzuo/tmp/clipbucket/compose
docker compose pull
docker compose up -d

首启 docker compose up -d 会创建网络并拉起服务（Created/Started 两态）；后续变更后重复执行 docker compose up -d --force-recreate 的实测回显：

 Container clipbucket-5.5.3-web Recreate
 Container clipbucket-5.5.3-web Recreated
 Container clipbucket-5.5.3-web Starting
 Container clipbucket-5.5.3-web Started

重建后数据卷内容原样保留（实测：首页与观看页均恢复 200，视频与设置无丢失）。

docker compose ps 实测回显（Docker Compose version v5.6.1）：

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 logs clipbucket-5.5.3-web 实测节选）——逐个拉起内置组件：

=========================================
ClipBucket v5 Docker Container
PHP Version: 8.5
=========================================
Starting Redis Server...
Redis Server is ready!
Starting MariaDB...
2026-10-28  9:58:02 0 [Note] Starting MariaDB 11.8.6-MariaDB-0+deb13u1 from Debian source revision 9bfea48ce1214cc4470f6f6f8a4e30352cef84e7 server_uid 9nbvo6PW7oecNGF0v/x8sSbvLbs= as process 30
2026-10-28  9:58:02 0 [Warning] mariadbd: io_uring_queue_init() failed with EPERM: sysctl kernel.io_uring_disabled has the value 2, or 1 and the user of the process is not a member of sysctl kernel.io_uring_group. (see man 2 io_uring_setup).
create_uring failed: falling back to libaio

Sources already exist. No init required.
Starting Nginx...
=========================================
All services started successfully!
=========================================
Redis Server running on port 6379

（Sources already exist. No init required. 说明站点目录非空时跳过代码初始化；MariaDB 的 io_uring 告警会自动回退 libaio，不影响功能。）

3.3 bind mount 场景的数据准备（关键）

采用 bind mount 时，需在首次启动前把镜像内的初始化数据放到挂载目录（命名卷方案可跳过本步）：

# 从镜像中拷出已初始化的数据库目录（在宿主执行）
CID=$(docker create oxygenz/clipbucket-v5:latest true)
docker cp $CID:/var/lib/mysql/. /opt/data/quzuo/tmp/clipbucket/data/db/
docker rm $CID
# 按镜像 entrypoint 约定统一属主
chown -R 1000:1000 /opt/data/quzuo/tmp/clipbucket/data/db

站点目录两种做法：留空（容器首启自动拉取官方代码到 /srv/http/clipbucket），或预先放入从官方仓库取得的代码。本实验预先放入了 MacWarrior/clipbucket-v5 仓库内容（git clone --depth 1 https://github.com/MacWarrior/clipbucket-v5.git 后拷入 data/www/），行为与容器自动拉取一致。

3.4 Web 安装向导

浏览器打开 http://<服务器IP>:8142/cb_install/，进入安装向导（页面标题 ClipBucket v5.5.3 Installer）。向导共 9 个模式页：agreement → precheck → permission → database → dataimport → sitesettings → adminsettings → finish → lock。

第 1 步 协议页：勾选同意 Attribution Assurance License 后继续。

第 2 步 环境预检（precheck）：实测全部通过——PHP 版本、mysqli/curl/xml/mbstring/gd/openssl/fileinfo 模块、exec 函数、FFmpeg、MediaInfo、发送邮件组件均显示可用（镜像内置栈天生满足）。

第 3 步 目录权限（permission）：files/、includes/ 等写入检查全绿。

第 4 步 数据库（database）：按 entrypoint 初始化约定填写：

提交后显示 Successful connection，进入数据导入页。

第 5 步 数据导入（dataimport）：14 个 SQL 包（5.0.0 基础结构 + 各版本增量）依次导入，实测全部 Success（可点开每项查看行数）。

第 6~7 步 站点与管理员设置：填写站点标题/描述与管理员账号密码。

⚠️ 坑点实录（v5.5.3-#221 实测）：向导的 sitesettings/adminsettings 提交后未把设置完整落库（site_title 等仍为空、管理员密码哈希与登录校验算法不匹配）。部署后需进后台手动完成这两步（见 3.5 与《ClipBucket 配置参数详解》5.1），这是当前版本已知缺陷，属升级系统的范畴。

第 8~9 步 完成与上锁：finish 显示安装完成；最后执行 lock 删除 files/temp/install.me 安装锁（此后访问 /cb_install/ 会 302 回首页，防止重复安装）。

3.5 安装后必做的三件事

1. 补站点设置：后台 → Settings → Basic Configuration，填写 site_title/site_slogan 保存（实测保存后首页标题即生效：ClipBucket 实验站 - 自托管视频门户实验环境）。
2. 重置管理员密码：默认生成的哈希无法登录，需按 sha512(明文密码 + userid + password_salt) 算法重写（password_salt 在 cb_config 表），或直接后台 members 页重建管理员。实测修正后 admin/q1w2e3r4 登录后台 200。
3. 开启内容分区：Settings → Basic Configuration 把 videosSection（及频道/合集/播放列表）开关置为 yes。实测默认全为 no，不开会跳转所有 watch_video.php 请求到首页（排障实录见《ClipBucket 常用命令与运维实战》第 8 节）。

3.6 部署验证（上传→转码→播放闭环）

用 ffmpeg 造一个 15 秒测试视频后从网页端上传（登录 → Upload），上传接口返回：

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

此时 cb_video 表状态为 Waiting，文件落在 files/conversion_queue/2026/10/28/。执行官方 CLI 转码器（生产环境配 cron 定时执行）：

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

转码日志（files/logs/2026/10/28/179318291709958.log 实测节选）：

2026-10-28 10:22:27 => Video converted
Output file details :
- path : /srv/http/clipbucket/upload/files/videos/2026/10/28/179318291709958-360.mp4
- duration : 15   - video_codec : h264   - audio_codec : aac
- video_width : 640  - video_height : 360  - size : 517939
Conversion_status : completed   Time Took : 4.4126 seconds

验证结果（实测）：

闭环成立，部署完成。

四、常见部署问题实录

五、升级与回滚

• 代码升级：V5 采用持续部署模式（master 即最稳定版），站点目录为 Git 仓库时可 git pull；后台 Dashboard 内置自更新入口与数据库升级系统（admin_area/upgrade_db.php），升级前先做备份（命令见《ClipBucket 常用命令与运维实战》第 6 节）。
• 回滚：还原数据卷快照 + 回退 Git 版本即可；本文 6.2 的恢复演练验证了备份可导入性（新建临时库导入 SQL 后 cb_video=1、cb_users=2 行数一致）。

六、参考

• 官方 README（安装/镜像标签/环境变量）：https://github.com/MacWarrior/clipbucket-v5
• 官方镜像页：https://hub.docker.com/r/oxygenz/clipbucket-v5
• 本专栏姊妹篇：《ClipBucket 介绍与选型指南》《ClipBucket 配置参数详解》《ClipBucket 常用命令与运维实战》