Black Candy 从 v2 升级到 v3 的完整指南

Black Candy 从 v2 升级到 v3 的完整指南

blackcandy A self hosted music streaming server 项目地址: https://gitcode.com/gh_mirrors/bl/blackcandy

Black Candy 是一个优秀的音乐流媒体服务项目，在 v3 版本中进行了重大架构调整。本文将详细介绍从 v2 升级到 v3 的完整过程，帮助用户顺利完成迁移。

版本升级概述

Black Candy v3 版本带来了多项重大变更：

1. 数据库调整：默认使用 SQLite 作为数据库
2. 依赖简化：移除了对 Redis 和 Sidekiq 的依赖
3. 部署简化：不再依赖 Nginx 和 Docker Compose
4. 架构优化：服务启动更加轻量化

重要提示：由于 v3 需要同时支持 SQLite 和 PostgreSQL，且 v2 中的部分数据与 SQLite 不兼容，升级过程中会丢失一些设置数据。

升级前的准备工作

在开始升级前，请确保：

1. 备份当前 v2 版本的所有重要数据
2. 了解两种升级路径的区别
3. 预留足够的磁盘空间用于迁移过程

方案一：继续使用 PostgreSQL 数据库

1. 获取 v3 镜像

首先拉取最新的 v3 镜像：

docker pull blackcandy:3.0.0

2. 停止并移除旧容器

docker-compose down

3. 修改 docker-compose 文件

v3 版本不再需要 Redis、Sidekiq 和 Nginx 服务，可以简化配置文件。以下是推荐的配置示例：

version: '3'
services:
  app:
    container_name: 'blackcandy_app'
    image: blackcandy:v3.0.0 
    ports:
      - "80:3000"
    volumes:
      - ./storage_data:/app/storage
      - /media_data:/media_data
      - production_uploads_data:/app/public/uploads
    environment:
      DB_ADAPTER: postgresql
      DB_URL: postgresql://postgres@postgres/black_candy_production
      MEDIA_PATH: /media_data
    depends_on:
      - postgres
  postgres:
    container_name: 'blackcandy_postgres'
    image: postgres:11.1-alpine
    volumes:
      - production_db_data:/var/lib/postgresql/data
volumes:
  production_db_data:
  production_uploads_data:

4. 启动新容器

docker-compose up -d

系统会自动完成数据迁移。

5. 清理旧数据

迁移完成后，可以安全移除不再需要的旧数据：

docker-compose down
rm -r media_cache_data
rm -r log
docker volume rm <your_blackcandy_redis_data_volume>
docker volume rm <your_blackcandy_uploads_data_volume>

6. 最终配置调整

移除不再需要的 volumes 配置后，最终的 docker-compose 文件如下：

version: '3'
services:
  app:
    container_name: 'blackcandy_app'
    image: blackcandy:v3.0.0 
    ports:
      - "80:3000"
    volumes:
      - ./storage_data:/app/storage
      - /media_data:/media_data
    environment:
      DB_ADAPTER: postgresql
      DB_URL: postgresql://postgres@postgres/black_candy_production
      MEDIA_PATH: /media_data
    depends_on:
      - postgres
  postgres:
    container_name: 'blackcandy_postgres'
    image: postgres:11.1-alpine
    volumes:
      - production_db_data:/var/lib/postgresql/data
volumes:
  production_db_data:

7. 重启服务

docker-compose up -d

方案二：迁移到 SQLite 数据库

1. 停止并移除旧容器

docker-compose down

2. 数据转换准备

确保系统已安装 Ruby 环境：

gem install sequel

3. 启动临时 PostgreSQL 容器

docker run -p 5432:5432 -v <your_blackcandy_db_data_volume>:/var/lib/postgresql/data postgres:11.1-alpine

4. 使用 sequel 导出数据

sequel -C postgres://postgres@localhost:5432/black_candy_production sqlite://production.sqlite3

5. 准备存储目录

mkdir storage_data
cp production.sqlite3 storage_data/production.sqlite3

6. 启动新容器进行迁移

docker run -p 3000:3000 -v ./storage_data:/app/storage -v <your_blackcandy_uploads_data_volume>:/app/public/uploads blackcandy:v3.0.0 

7. 清理旧数据

docker stop <your_blackcandy_container>
docker rm <your_blackcandy_container>
rm production.sqlite3
rm -r media_cache_data
rm -r log
docker volume rm <your_blackcandy_redis_data_volume>
docker volume rm <your_blackcandy_uploads_data_volume>
docker volume rm <your_blackcandy_db_data_volume>

8. 最终运行配置

docker run -p 3000:3000 -v /media_data:/media_data -v ./storage_data:/app/storage -e MEDIA_PATH=/media_data blackcandy:v3.0.0

升级后注意事项

1. 首次访问：系统可能需要重新初始化部分设置
2. 性能监控：SQLite 版本在高并发下可能需要额外优化
3. 媒体文件：确保所有媒体文件路径正确配置
4. 定期备份：特别是使用 SQLite 时，建议定期备份数据库文件

常见问题解答

Q: 升级后为什么部分设置丢失了？ A: 这是预期行为，因为 v3 的配置结构与 v2 不完全兼容。

Q: 能否回滚到 v2 版本？ A: 可以，但需要恢复备份的 v2 数据和配置。

Q: 为什么移除 Redis 依赖？ A: v3 版本简化了架构，移除了对缓存和后台任务队列的需求。

通过本文的详细指导，您应该能够顺利完成 Black Candy 从 v2 到 v3 的升级。两种方案各有优势，建议根据实际需求选择最适合的升级路径。

blackcandy A self hosted music streaming server 项目地址: https://gitcode.com/gh_mirrors/bl/blackcandy