Invidious升级指南：版本迁移与数据库变更处理

Invidious升级指南：版本迁移与数据库变更处理

【免费下载链接】invidious Invidious is an alternative front-end to YouTube 项目地址: https://gitcode.com/GitHub_Trending/in/invidious

概述

Invidious作为YouTube的开源替代前端，在版本迭代过程中经常涉及数据库结构的变更。本文详细解析Invidious的数据库迁移机制，提供从版本升级到数据迁移的完整解决方案，帮助管理员顺利完成实例升级。

数据库迁移架构解析

迁移系统核心组件

Invidious采用模块化的数据库迁移系统，主要由以下组件构成：

迁移版本管理表结构

CREATE TABLE IF NOT EXISTS public.invidious_migrations (
    id bigserial PRIMARY KEY,
    version bigint NOT NULL
);

现有迁移脚本分析

迁移脚本类型

根据项目结构，Invidious包含两种迁移方式：

1. SQL脚本迁移 (config/migrate-scripts/)
2. Crystal代码迁移 (src/invidious/database/migrations/)

关键迁移示例

示例1：添加订阅状态字段

#!/bin/sh
[ -z "$POSTGRES_USER" ] && POSTGRES_USER=kemal
[ -z "$POSTGRES_DB" ] && POSTGRES_DB=invidious

psql "$POSTGRES_DB" "$POSTGRES_USER" -c "ALTER TABLE channels ADD COLUMN subscribed bool;"
psql "$POSTGRES_DB" "$POSTGRES_USER" -c "UPDATE channels SET subscribed = false;"

示例2：创建频道表（Crystal迁移）

module Invidious::Database::Migrations
  class CreateChannelsTable < Migration
    version 1

    def up(conn : DB::Connection)
      conn.exec <<-SQL
      CREATE TABLE IF NOT EXISTS public.channels
      (
        id text NOT NULL,
        author text,
        updated timestamp with time zone,
        deleted boolean,
        subscribed timestamp with time zone,
        CONSTRAINT channels_id_key UNIQUE (id)
      );
      SQL
      # ... 索引和权限设置
    end
  end
end

升级流程详解

前置检查清单

在开始升级前，请完成以下检查：

检查项	说明	重要性
数据库备份	确保有完整的数据备份	⭐⭐⭐⭐⭐
当前版本确认	记录当前Invidious版本号	⭐⭐⭐⭐
配置文件备份	备份config.yml文件	⭐⭐⭐⭐
服务状态检查	确认当前实例运行状态	⭐⭐⭐

升级操作步骤

步骤1：服务停止与备份

# 停止Invidious服务
sudo systemctl stop invidious

# 数据库备份
pg_dump -U kemal -d invidious > invidious_backup_$(date +%Y%m%d).sql

# 配置文件备份
cp config/config.yml config/config.yml.backup

步骤2：代码更新

# 拉取最新代码
git pull origin master

# 安装依赖
shards install

# 编译项目
make

步骤3：数据库迁移执行

# 自动运行所有待处理迁移
./invidious --migrate

# 或手动检查待处理迁移
./invidious --pending-migrations

步骤4：服务重启与验证

# 启动服务
sudo systemctl start invidious

# 检查服务状态
sudo systemctl status invidious

# 验证数据库变更
psql -U kemal -d invidious -c "\d"

常见问题与解决方案

问题1：迁移冲突处理

症状：迁移脚本执行失败，出现版本冲突错误

解决方案：

# 查看已应用的迁移版本
psql -U kemal -d invidious -c "SELECT version FROM invidious_migrations ORDER BY version;"

# 手动修复迁移状态（谨慎操作）
psql -U kemal -d invidious -c "INSERT INTO invidious_migrations (version) VALUES (冲突版本号);"

问题2：数据类型不兼容

症状：ALTER TABLE语句因数据类型冲突失败

解决方案：

-- 示例：处理布尔字段迁移
ALTER TABLE channels 
ALTER COLUMN subscribed TYPE boolean 
USING CASE WHEN subscribed = 'true' THEN true ELSE false END;

问题3：外键约束冲突

症状：迁移因外键约束失败

解决方案：

-- 临时禁用外键约束
ALTER TABLE table_name DISABLE TRIGGER ALL;

-- 执行迁移操作
-- ...

-- 重新启用外键约束
ALTER TABLE table_name ENABLE TRIGGER ALL;

迁移脚本开发指南

创建新的迁移脚本

方法1：SQL脚本迁移

#!/bin/sh
# migrate-db-xxx.sh
[ -z "$POSTGRES_USER" ] && POSTGRES_USER=kemal
[ -z "$POSTGRES_DB" ] && POSTGRES_DB=invidious

# 添加新字段示例
psql "$POSTGRES_DB" "$POSTGRES_USER" -c "ALTER TABLE videos ADD COLUMN duration interval;"

方法2：Crystal代码迁移

module Invidious::Database::Migrations
  class AddVideoDuration < Migration
    version 11  # 确保版本号唯一且递增

    def up(conn : DB::Connection)
      conn.exec <<-SQL
      ALTER TABLE videos 
      ADD COLUMN duration interval,
      ADD COLUMN is_live boolean DEFAULT false;
      SQL
      
      conn.exec "CREATE INDEX IF NOT EXISTS videos_duration_idx ON videos (duration);"
    end
  end
end

迁移脚本最佳实践

1. 原子性操作：每个迁移脚本应该是原子的，要么全部成功，要么全部失败
2. 幂等性设计：使用IF NOT EXISTS和IF EXISTS确保脚本可重复执行
3. 版本控制：严格遵循版本号递增原则
4. 回滚考虑：为复杂迁移提供回滚方案
5. 性能优化：大数据量表迁移时考虑分批次处理

监控与维护

迁移状态监控

-- 查看迁移历史
SELECT version, inserted_at 
FROM invidious_migrations 
ORDER BY version DESC 
LIMIT 10;

-- 检查未应用的迁移
SELECT * FROM (
  VALUES (1), (2), (3), (4), (5), (6), (7), (8), (9), (10)
) AS expected_versions(version)
WHERE version NOT IN (
  SELECT version FROM invidious_migrations
);

自动化升级脚本示例

#!/bin/bash
# auto-upgrade-invidious.sh

set -e

echo "开始Invidious自动升级流程..."
echo "当前时间: $(date)"

# 停止服务
echo "停止Invidious服务..."
sudo systemctl stop invidious

# 备份数据库
BACKUP_FILE="invidious_backup_$(date +%Y%m%d_%H%M%S).sql"
echo "创建数据库备份: $BACKUP_FILE"
pg_dump -U kemal -d invidious > "/backups/$BACKUP_FILE"

# 更新代码
echo "更新代码库..."
git pull origin master

# 安装依赖和编译
echo "安装依赖..."
shards install
echo "编译项目..."
make

# 运行迁移
echo "执行数据库迁移..."
./invidious --migrate

# 启动服务
echo "启动服务..."
sudo systemctl start invidious

echo "升级完成！"

总结

Invidious的数据库迁移系统提供了灵活可靠的版本升级机制。通过理解其迁移架构、掌握升级流程、熟悉常见问题处理方法，管理员可以确保实例升级过程平稳顺利。关键要点包括：

1. 始终备份：升级前务必完成数据和配置文件的完整备份
2. 测试验证：在测试环境中验证迁移脚本后再应用到生产环境
3. 监控追踪：密切监控迁移过程，及时处理可能出现的问题
4. 文档记录：详细记录每次升级的变更内容和处理过程

遵循本文指南，您将能够高效管理Invidious实例的版本升级，确保服务的持续稳定运行。

---

提示：升级完成后，建议在低峰期进行全面的功能测试，确保所有特性正常工作。如遇复杂迁移场景，可参考项目GitHub仓库的Issues和Discussion板块寻求社区支持。

【免费下载链接】invidious Invidious is an alternative front-end to YouTube 项目地址: https://gitcode.com/GitHub_Trending/in/invidious