KVideo 日常运维手册

目标：给出 KVideo 4.9.20 稳定运行期的完整运维闭环——日常巡检项与命令、备份策略（与其特殊的数据模型匹配）、监控探活、升级回滚、以及一套经真实故障演练验证的排查手册。全部命令与回显实测于 Ubuntu 22.04 + KVideo 4.9.20（Docker Compose 单实例，端口 8131）。

一、环境信息

本手册实测环境（与部署篇一致，运维动作可直接复现）：

• 操作系统：Ubuntu 22.04（x86_64）
• KVideo 版本：4.9.20（官方镜像 kuekhaoyang/kvideo:4.9.20）
• 部署形态：Docker Compose 项目 kvideo-4.9.20-stack，单实例，宿主端口 8131 → 应用 3000
• 部署目录：/opt/kvideo/（compose 文件所在）
• 资源基线（实测）：空载内存约 50 MiB（docker stats 实测 mem=49.93MiB、CPU 0.01%），镜像磁盘占用约 339 MB
• 演示管理账号：admin / q1w2e3r4
• 运维前提：理解 KVideo「服务端无状态 + 用户数据在浏览器 + 可选 Upstash 同步」的数据模型（详见《KVideo 4.9.20 配置参数详解》），这决定了本手册备份与扩容的形态。

二、日常巡检

KVideo 是轻量无状态服务，巡检项比数据库类应用少得多，核心是「进程活着、接口答话、版本对号、日志干净」四件事，建议每日或每周跑一轮。

2.1 进程状态巡检

cd /opt/kvideo && docker compose ps --format 'table {{.Name}}\t{{.Status}}'

实测回显：

NAME                STATUS
kvideo-4.9.20-web   Up 2 minutes

STATUS 应为 Up；若显示 Restarting 或 Exited，直接跳到第七节故障排查。

2.2 HTTP 探活巡检

curl -s -o /dev/null -w 'code=%{http_code} time=%{time_total}s\n' http://127.0.0.1:8131/

实测回显：

code=200 time=0.021112s

健康基线：状态码 200，响应时间在百毫秒内。首页带 Next.js 预渲染缓存（x-nextjs-cache: HIT），探活开销极低，可放心高频执行。

2.3 版本一致性巡检

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

实测回显：

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

核对 currentVersion 与 compose 中镜像 tag 一致；该接口同时返回上游最新版本与 Release Notes，是升级决策的官方数据源。

2.4 日志巡检

docker compose -f /opt/kvideo/docker-compose.yml logs --since 24h kvideo | grep -ci 'error\|warn' || echo "no errors"

实测回显：

0
no errors

稳定运行期日志应基本静默（Next.js 只在启动时输出横幅）；出现连续 error 再看上下文定位。

2.5 资源占用巡检

docker stats kvideo-4.9.20-web --no-stream --format '{{.Name}} mem={{.MemUsage}} cpu={{.CPUPerc}}'

实测回显：

kvideo-4.9.20-web mem=49.93MiB / 23.42GiB cpu=0.01%

内存基线约 50 MiB 级；若长时间数倍于此值，通常是某个源接口响应异常导致聚合搜索缓冲堆积，观察日志并测试各源延迟。

三、备份与恢复

KVideo 的备份策略与其数据模型强相关——服务端本身几乎无数据可备，备份对象按「三层」分别处理：

实操：部署配置备份（服务器上执行）：

tar czf /root/backup/kvideo-compose-$(date +%F).tar.gz -C /opt/kvideo docker-compose.yml

实测回显：无输出（打包成功），确认产物：

ls -lh /root/backup/ | grep kvideo

实测回显：

-rw-r--r-- 1 root root 465 Oct 25 11:35 kvideo-compose-2026-10-25.tar.gz

恢复演练：配置文件损坏/丢失时，解包回 /opt/kvideo/ 后重建：

tar xzf /root/backup/kvideo-compose-2026-10-25.tar.gz -C /opt/kvideo/
cd /opt/kvideo && docker compose up -d

实测回显：

[+] Running 1/1
 ✔ Container kvideo-4.9.20-web  Started

⚠️ 注意：因为用户数据不在服务器上，误删服务器目录不会丢用户数据；反过来，用户清浏览器数据会丢个人配置——家庭站建议至少为管理员账号配置 Upstash 同步，成员账号引导开启「界面导出」习惯。

四、监控告警

家庭/小团队规模不必上重型监控栈，一个探活脚本 + 日志关键字即可覆盖 KVideo 的核心风险面。以下巡检脚本可直接放入 cron（每 5 分钟）：

#!/bin/bash
# /opt/kvideo/healthcheck.sh —— KVideo 探活告警
CODE=$(curl -s -o /dev/null -w '%{http_code}' --max-time 5 http://127.0.0.1:8131/)
if [ "$CODE" != "200" ]; then
  logger -t kvideo-health "KVideo DOWN http_code=$CODE"
  # 告警通道按需接入（邮件/webhook/短信网关），此处以 syslog 留痕示例
  docker compose -f /opt/kvideo/docker-compose.yml restart kvideo
fi

脚本逻辑说明：5 秒超时探测首页，非 200 即记入 syslog 并自动重启服务（KVideo 无状态，自动重启无数据风险）；logger 写入的系统日志可用 grep kvideo-health /var/log/syslog 追溯历史故障时间线。告警通道接入属通用设施，按既有告警体系（邮件/webhook）替换 logger 行即可。

cron 安装（每 5 分钟执行一次）：

chmod +x /opt/kvideo/healthcheck.sh
(crontab -l 2>/dev/null; echo '*/5 * * * * /opt/kvideo/healthcheck.sh') | crontab -

实测回显：无输出（crontab 写入成功），用 crontab -l | grep kvideo 可见：

*/5 * * * * /opt/kvideo/healthcheck.sh

容量告警线建议：磁盘（镜像层 + 日志）超过 2 GB、内存持续超过 512 MiB、探活失败连续 2 个周期——满足任一即介入排查。家庭站实测资源远低于这些阈值。

五、扩容缩容

5.1 纵向扩缩容（资源上下限）

KVideo 空载 50 MiB 内存，家庭规模无需扩容；若接入大量用户或源质量差（慢源多、缓冲多），用 compose 限定资源上限防失控：

    deploy:
      resources:
        limits:
          memory: 512m

改后 docker compose up -d 生效；缩容则调小该值。无状态应用缩容没有数据迁移问题。

5.2 横向扩容（多实例）

需要高可用或多副本负载均衡时，注意三个前提：

1. 所有实例共用同一 AUTH_SECRET，否则 Cookie 签名跨实例不通；
2. 多实例共享 Upstash Redis（配置同步层的唯一共享点），否则各实例用户数据割裂；
3. 前面挂 Nginx/Caddy 等反代做负载均衡，KVideo 本身无会话粘滞要求（会话是签名 Cookie，不依赖内存 session）。

单实例到多实例的切换成本极低——这正是无状态架构的红利；反之家庭规模建议保持单实例，复杂度不值得。

5.3 缩容与下线

cd /opt/kvideo && docker compose down

实测回显：

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

彻底下线再删除镜像与部署目录即可；用户数据在各自浏览器与 Upstash，服务端无残留。

六、升级与回滚

6.1 升级流程（固定 tag 策略）

KVideo 4.9.x 小版本节奏快（2026 年 7-8 月两个月内 7 个 tag），升级按固定 tag 滚动：

# 1. 查看上游最新版本与 Release Notes（官方接口，无需去 GitHub 翻）
curl -s http://127.0.0.1:8131/api/app-update

实测回显（输出节选）：

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

# 2. 修改 /opt/kvideo/docker-compose.yml 中 image 为新版本 tag（如 kuekhaoyang/kvideo:4.9.21）
# 3. 拉取并滚动重建
cd /opt/kvideo && docker compose pull && docker compose up -d

# 4. 升级后验证：版本号 + 登录链路
curl -s http://127.0.0.1:8131/api/app-update | head -c 90

实测回显（版本随镜像更新后形态）：

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

⚠️ 注意两点：①升级会重启服务，所有用户登录态失效需重新登录（实测确认，即使固定了 AUTH_SECRET）；②用户数据在浏览器端，升级不丢任何用户配置，无需数据迁移脚本。

6.2 回滚流程

新版本异常时，把 image 行改回上一个版本 tag 后重建：

# docker-compose.yml: image: kuekhaoyang/kvideo:4.9.19
cd /opt/kvideo && docker compose up -d

KVideo 无服务端数据结构，跨版本回滚零兼容负担；仅需留意客户端缓存的 PWA 资源，用户侧强制刷新一次浏览器即可。

七、故障排查手册

以下三条均为实测演练沉淀的完整排障路径（故障注入 → 现象 → 定位 → 恢复）。

7.1 故障一：站点完全无法访问（服务停机）

现象（实测注入：停止服务后探活）：

curl -s -o /dev/null -w 'code=%{http_code}\n' --max-time 3 http://127.0.0.1:8131/

实测回显：

code=000

curl 退出码 7（连接被拒），浏览器显示「无法访问此网站」。

定位三步：

# 1. 容器是否活着
docker compose -f /opt/kvideo/docker-compose.yml ps

实测回显（停机态）：

NAME                STATUS
kvideo-4.9.20-web   Exited (0) 30 seconds ago

# 2. 为什么退出——看日志尾部
docker logs kvideo-4.9.20-web --tail 20
# 3. 是否端口冲突/系统重启后未拉起——看 compose 事件与 restart 策略

恢复与验证（实测）：

docker compose -f /opt/kvideo/docker-compose.yml start kvideo

实测回显：

 Container kvideo-4.9.20-web Started

curl -s -o /dev/null -w 'code=%{http_code} time=%{time_total}s\n' http://127.0.0.1:8131/

实测回显：

code=200 time=0.023185s

根因预防：本次演练为手动 stop；生产中同类故障多为宿主重启后未自愈，确认 compose 中 restart: unless-stopped 在位即可自动拉起。

7.2 故障二：登录一直失败

现象：输入正确密码提示无效（接口返回 {"valid":false}）。

定位路径（按命中率排序）：

1. 环境变量没应用——改过 compose 的 environment 后只执行了 restart：

docker inspect kvideo-4.9.20-web --format '{{range .Config.Env}}{{println .}}{{end}}' | grep -E 'ADMIN_PASSWORD|ACCESS_PASSWORD'

实测回显：

ADMIN_PASSWORD=q1w2e3r4
ACCESS_PASSWORD=q1w2e3r4view

核对运行中实例的真实环境变量与 compose 文件是否一致；不一致则 docker compose up -d 重建。

2. 混淆了两个密码的语义——ACCESS_PASSWORD 在 ADMIN_PASSWORD 非空时不参与登录（实测：用 ACCESS_PASSWORD 的值做仅密码登录返回 {"valid":false}），登录只认 ADMIN_PASSWORD；
3. 用户名写错——管理员用户名固定为 admin，不存在自定义超管用户名；
4. 账号体系模式变化——开启 MANAGED_AUTH_ENABLED 后走托管账号体系，引导密码与界面建号并存，用 curl -s http://127.0.0.1:8131/api/auth 看 loginMode 当前值。

7.3 故障三：同步接口 503

现象：部分用户配置「保存不上」（若配置了依赖同步的用法），或日志出现同步错误。

定位：

curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8131/api/user/config

实测回显（未配置 Redis 的部署）：

503

curl -s http://127.0.0.1:8131/api/user/config

实测回显：

{"error":"Server-side sync is not configured on this deployment"}

处置：503 + 该报错是「部署未配置 Upstash」的预期行为而非故障；确需同步能力时补配 UPSTASH_REDIS_REST_URL 与 UPSTASH_REDIS_REST_TOKEN（必须是 Upstash REST 凭据，不能填自建 redis:// 地址），docker compose up -d 重建后重测，预期返回 {"success":true,"data":null} 类正常响应。

7.4 其他高频问题速查

八、常见问题

Q1：KVideo 需要像数据库那样做备份策略吗？ 不需要等价物。服务端唯一值得备份的是 compose 文件（含密码与源下发配置）；用户数据在浏览器与 Upstash。把「服务器目录误删」和「用户丢配置」分开对待（见第三节三层模型）。

Q2：探活频率多高合适？ 首页有预渲染缓存，单次探活开销微乎其微，每 1-5 分钟均可；配合第三节脚本建议 5 分钟。

Q3：升级要停机窗口吗？ 滚动重建秒级完成，家庭规模无感；唯一影响是登录态失效需重登（实测确认）。选深夜升级即可。

Q4：容器重启循环怎么排查？ docker logs --tail 50 看崩溃点；常见根因是 compose 里 environment 格式错误（缺 - 前缀、冒号未加引号）导致启动即退出，docker compose config 可先静态校验语法。

Q5：能不能多个 KVideo 版本并存灰度？ 可以，再起一套 compose（不同项目名、不同宿主端口），验证通过后切反代指向即可——无状态应用灰度成本极低。

九、参考链接

• 官方 GitHub 仓库：https://github.com/KuekHaoYang/KVideo
• Docker Hub 镜像页：https://hub.docker.com/r/kuekhaoyang/kvideo
• 本专栏相关篇目：
  • 《KVideo 介绍与选型指南》
  • 《KVideo Docker Compose 部署指南》
  • 《KVideo 4.9.20 配置参数详解》