KVideo Docker Compose 部署指南

目标：在一台 Ubuntu 22.04 服务器上，用 Docker Compose 从零部署 KVideo 4.9.20 视频聚合平台，完成端口映射、管理员账号初始化、启动验证与日常启停，全部命令与回显均已在 Ubuntu 22.04 + Docker 29.9.2 环境实测通过。

一、环境信息

本文实测环境与关键版本如下，读者在相近环境可直接复现：

• 操作系统：Ubuntu 22.04（内核 7.0.0-38-generic，x86_64）
• Docker：Client/Server 29.9.2（API 1.56）
• Docker Compose：v5.6.1（docker compose 插件形态）
• KVideo 版本：4.9.20（官方镜像 kuekhaoyang/kvideo:4.9.20，2026-08-16 发布的最新稳定版）
• 镜像架构：linux/amd64（另有 arm64 多架构 tag 可用于 ARM 设备/NAS）
• 镜像体积：约 339 MB（解压后），压缩层约 83 MB
• 服务端口：宿主 8131 → 应用 3000（应用在镜像内固定监听 3000）
• 部署目录：/opt/kvideo/（本文示例目录，可自行调整）
• 演示管理账号：admin / q1w2e3r4

二、镜像选型说明

KVideo 官方发布渠道有两个，选型前先分清：

版本 tag 选择建议：

• 固定版本 tag（如 4.9.20）：推荐。KVideo 小版本迭代快（4.9.x 两个月内推送了 7 个 tag），固定 tag 保证升级动作可控、回滚有据；
• latest：省心但不可控，docker compose pull 时行为会随上游变化，家庭自用可接受，长期运维不推荐；
• 应用自身内置版本自检接口（/api/app-update 返回当前版本与最新版 Release Notes），升级前后均可据此核对版本一致性，见「九、常用运维命令」。

三、前置条件

1. 服务器已安装 Docker 与 docker compose 插件。未安装的执行：

# 安装 Docker 官方仓库版（Ubuntu 22.04）
curl -fsSL https://get.docker.com | sh

实测回显（输出节选，实测首尾）：

# Executing docker install script, commit: ...
...（中间为 apt 拉包与安装过程，略）...
Client: Docker Engine - Community
 Version:    29.9.2
...
Server: Docker Engine - Community
 Engine:
  Version:  29.9.2

2. 验证 compose 插件可用：

docker compose version

实测回显：

Docker Compose version v5.6.1

3. 端口规划：确认宿主上目标端口未被占用（本文用 8131）：

ss -ltn | grep 8131 || echo "port 8131 free"

实测回显：

port 8131 free

4. 网络可达性：拉取镜像需要访问 Docker Hub；国内网络环境慢或超时时，为 Docker daemon 配置镜像加速器或代理后重试（Docker 层面的拉取代理在 /etc/docker/daemon.json 或 systemd 环境中配置，属宿主 Docker 服务配置，与 KVideo 应用本身无关）。

四、部署步骤

4.1 创建部署目录

mkdir -p /opt/kvideo && cd /opt/kvideo

实测回显：无输出（目录创建成功）。

4.2 编写 docker-compose.yml

在 /opt/kvideo/docker-compose.yml 写入以下内容（本文件为实测部署所用版本）：

name: kvideo-4.9.20-stack

services:
  kvideo:
    image: kuekhaoyang/kvideo:4.9.20
    container_name: kvideo-4.9.20-web
    restart: unless-stopped
    ports:
      - "8131:3000"
    environment:
      - NODE_ENV=production
      - ADMIN_PASSWORD=q1w2e3r4
      - AUTH_SECRET=kvideo-demo-auth-secret-2026
      - NEXT_PUBLIC_SITE_NAME=KVideo Demo
      - PERSIST_SESSION=true

networks:
  default:
    name: kvideo-net

逐项说明：

• name: kvideo-4.9.20-stack：compose 项目名，显式指定可避免多套部署同名互相覆盖；
• image：固定版本 tag，升级时只改这一行；
• container_name: kvideo-4.9.20-web：固定容器名，便于 docker logs/docker inspect 定位；
• ports: "8131:3000"：宿主 8131 映射到应用固定监听的 3000；
• ADMIN_PASSWORD：管理员账号 admin 的密码（登录用户名固定为 admin），KVideo 以此引导出 super_admin 角色；界面「仅输入密码」登录同样比对该值；
• AUTH_SECRET：会话 Cookie 的签名密钥，多实例部署或换密码后想踢掉旧会话时改它；
• PERSIST_SESSION：会话持久开关，默认 true（30 天有效期）。

4.3 拉取镜像并启动

cd /opt/kvideo && docker compose up -d

实测回显：

[+] Running 2/2
 ✔ Network kvideo-net  Created
 ✔ Container kvideo-4.9.20-web  Started

⚠️ 注意：若该步拉取镜像超时，通常是服务器到 Docker Hub 的网络问题，配置镜像加速或代理后重试 docker compose pull && docker compose up -d 即可。

4.4 查看启动日志

docker logs kvideo-4.9.20-web

实测回显：

▲ Next.js 16.2.12
- Local:         http://localhost:3000
- Network:       http://0.0.0.0:3000
✓ Ready in 0ms

✓ Ready 出现即应用已就绪（Next.js standalone 模式启动极快，正常情况下秒级完成）。

4.5 验证部署结果

第一步：HTTP 探活。

curl -sI http://127.0.0.1:8131/ | head -5

实测回显：

HTTP/1.1 200 OK
Vary: rsc, next-router-state-tree, next-router-prefetch, next-router-segment-prefetch, Accept-Encoding
x-nextjs-cache: HIT
x-nextjs-prerender: 1
x-nextjs-stale-time: 300

第二步：公开认证配置接口（确认环境变量已生效）。

curl -s http://127.0.0.1:8131/api/auth

实测回显：

{"hasAuth":true,"hasPremiumAuth":false,"loginMode":"legacy_password","persistSession":true,"subscriptionSources":"","iptvSources":"","mergeSources":"","danmakuApiUrl":""}

hasAuth:true + loginMode:legacy_password 说明密码门禁已启用、模式为「管理员密码引导」。

第三步：版本自检接口（确认部署的确是 4.9.20）。

curl -s http://127.0.0.1:8131/api/app-update | head -c 200

实测回显（输出节选）：

{"currentVersion":"4.9.20","currentRelease":{"version":"4.9.20","publishedAt":"2026-08-16","title":"修复搜索更新标识、简介实体和占位图深色模式","notes":[...

currentVersion 与镜像 tag 一致即部署无误。

第四步：管理员登录接口实测（用户名固定 admin）。

curl -s -X POST http://127.0.0.1:8131/api/auth \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"q1w2e3r4"}' | head -c 300

实测回显（输出节选）：

{"valid":true,"session":{"accountId":"legacy-admin","profileId":"81ee72e5f0e797a4","username":"admin","name":"超级管理员","role":"super_admin","mode":"legacy"},"hasAuth":true,...

role:super_admin 即管理员身份验证通过。

第五步：浏览器访问 http://<服务器IP>:8131，输入 admin / q1w2e3r4 登录，进入「导入设置」添加自有视频源后即可搜索播放。

五、数据持久化说明

KVideo 的持久化模型与大多数自托管应用不同，部署前务必理解：

结论：KVideo 默认零本地状态，compose 文件无需配置 volume 即可长期运行——升级镜像不丢任何数据（数据本来就在用户浏览器里）。这个设计的另一面是：用户清理浏览器数据会丢失个人配置，家庭多人使用时建议配置 Upstash Redis 同步（见《KVideo 4.9.20 配置参数详解》）或在站内引导用户使用同一浏览器。

六、环境变量表

以下为部署常用环境变量全表（依据 4.9.20 源码 lib/server/auth.ts、lib/config/site-config.ts 及 README 整理，核心项均经实测验证）：

关键差异与选型：单密码家庭自用只需 ADMIN_PASSWORD；需要区分「能管理的家人」和「只能看的客人」时用 ACCOUNTS 引导多账号或开启 MANAGED_AUTH_ENABLED 走界面建账号。

七、配置文件挂载

KVideo 本身无必须挂载的配置文件，但两类场景会用到挂载：

1. 自定义站点图标（SITE_ICON_FILE 方式）：

    volumes:
      - /opt/kvideo/icon.png:/app/public/icon.png:ro

2. 广告关键词文件（AD_KEYWORDS_FILE 方式）：

    volumes:
      - /opt/kvideo/ad-keywords.txt:/app/ad-keywords.txt:ro

挂载后在 environment 中加 - SITE_ICON_FILE=/app/public/icon.png 或 - AD_KEYWORDS_FILE=/app/ad-keywords.txt，docker compose up -d 重建生效。

八、等价 docker run 命令

不使用 compose 时，以下单命令与本文 compose 完全等价：

docker run -d \
  --name kvideo-4.9.20-web \
  --restart unless-stopped \
  -p 8131:3000 \
  -e NODE_ENV=production \
  -e ADMIN_PASSWORD=q1w2e3r4 \
  -e AUTH_SECRET=kvideo-demo-auth-secret-2026 \
  -e NEXT_PUBLIC_SITE_NAME="KVideo Demo" \
  -e PERSIST_SESSION=true \
  kuekhaoyang/kvideo:4.9.20

两者差异仅在网络编排：compose 会创建独立网络并便于服务扩展（如未来加 Redis），单机自用 docker run 足够。

九、常用运维命令

以下命令均在实测环境验证（在 /opt/kvideo/ 目录下执行）。

查看运行状态：

docker compose ps

实测回显：

NAME                IMAGE                       SERVICE   CREATED         STATUS         PORTS
kvideo-4.9.20-web   kuekhaoyang/kvideo:4.9.20   kvideo    6 minutes ago   Up 6 minutes   0.0.0.0:8131->3000/tcp, [::]:8131->3000/tcp

实时日志：

docker compose logs -f kvideo

实测回显（日志尾部）：

▲ Next.js 16.2.12
- Local:         http://localhost:3000
- Network:       http://0.0.0.0:3000
✓ Ready in 0ms

重启与停止：

docker compose restart kvideo   # 重启
docker compose stop             # 停止（保留容器）
docker compose down             # 停止并删除容器与网络（数据在浏览器端，无本地数据丢失风险）

版本升级（固定 tag 策略）：

# 1. 修改 docker-compose.yml 中 image 为新版本 tag（如 4.9.21）
# 2. 拉新镜像并滚动重建
docker compose pull && docker compose up -d
# 3. 核对版本
curl -s http://127.0.0.1:8131/api/app-update | head -c 120

实测回显（升级动作后的版本核对形态）：

{"currentVersion":"4.9.20","currentRelease":{"version":"4.9.20","publishedAt":"2026-08-16",...

回滚：把 image 行改回旧版本 tag，重复 docker compose up -d 即可——KVideo 无服务端数据结构，回滚没有兼容性负担。

十、常见问题

Q1：浏览器访问一直转圈或 502？ 先 docker compose ps 确认容器 Up，再 docker logs kvideo-4.9.20-web 看 ✓ Ready 是否出现；若端口被占用，docker compose up -d 阶段就会报 port is already allocated，换 ports 左侧宿主端口即可。

Q2：登录提示密码错误？ 登录用户名固定为 admin，密码取 ADMIN_PASSWORD 的值；若两个变量都为空，站点处于无门禁模式（不会弹登录框）。改完环境变量必须 docker compose up -d 重建（restart 不会应用 environment 变更）。

Q3：换浏览器/换设备后源和播放记录全没了？ 这是预期行为——数据在浏览器 localStorage。需要跨设备同步时配置 Upstash Redis（REST 协议）环境变量，配置后同账号登录自动拉取云端配置；未配置时同步接口返回 503，属正常。

Q4：站内搜索无结果？ KVideo 不内置任何源。进入「导入设置」添加自有授权源（苹果 CMS V10 JSON 协议接口）或订阅源后再搜索；源不可达时可用界面自带的延迟检测排查。

Q5：镜像拉取很慢或超时？ Docker Hub 直连慢属网络问题，为 Docker daemon 配置国内镜像加速器或代理后 docker compose pull 重试；或改用源码本地构建（仓库自带 Dockerfile，构建过程约需数分钟，依赖 npm 源可达性）。

十一、参考链接

• 官方 GitHub 仓库：https://github.com/KuekHaoYang/KVideo
• Docker Hub 镜像页：https://hub.docker.com/r/kuekhaoyang/kvideo
• 在线体验站：https://kvideo.pages.dev/
• 本专栏相关篇目：
  • 《KVideo 介绍与选型指南》
  • 《KVideo 4.9.20 配置参数详解》
  • 《KVideo 日常运维手册》