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

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

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

前言

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

v3版本的重大变更

v3版本带来了多项基础设施层面的重大改进：

1. 数据库变更：SQLite成为默认数据库
2. 依赖简化：移除了对Redis和Sidekiq的依赖
3. 部署简化：不再依赖Nginx和Docker Compose运行服务
4. 架构优化：整体架构更加轻量级

升级前的注意事项

重要警告：由于v3需要同时支持SQLite和PostgreSQL，而v2中的部分数据与SQLite不完全兼容，升级后将会丢失部分数据，包括所有设置项。

升级方案选择

根据数据库选择的不同，我们提供两种升级路径：

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

1. 准备工作

首先拉取v3版本的镜像：

docker pull blackcandy:3.0.0

停止并移除旧容器：

docker-compose down

2. 修改docker-compose配置

v3版本不再依赖redis、sidekiq和nginx，因此可以移除相关服务配置。同时需要注意：

• 保留production_uploads_data卷配置
• 更新后的配置示例：

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:

3. 启动新容器

docker-compose up -d

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

4. 清理旧数据

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

docker-compose down
rm -r media_cache_data
rm -r log
docker volume rm <redis_data_volume>
docker volume rm <uploads_data_volume>

5. 最终配置调整

移除production_uploads_data卷后的最终配置：

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:

方案二：迁移到SQLite数据库

1. 准备工作

停止并移除旧容器：

docker-compose down

2. 数据转换

由于PostgreSQL数据与SQLite不完全兼容，需要使用工具进行转换：

安装必要的Ruby环境：

gem install sequel

启动临时PostgreSQL容器：

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

使用sequel工具导出数据：

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

创建存储目录并复制数据库文件：

mkdir storage_data
cp production.sqlite3 storage_data/production.sqlite3

3. 启动新容器进行数据迁移

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

4. 清理旧数据

docker stop <container_id>
docker rm <container_id>
rm production.sqlite3
rm -r media_cache_data
rm -r log
docker volume rm <redis_data_volume>
docker volume rm <uploads_data_volume>
docker volume rm <db_data_volume>

5. 最终运行配置

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. 验证用户设置是否完整
3. 测试各项功能是否正常运行

常见问题解答

Q: 升级过程中遇到数据库连接错误怎么办？

A: 请检查数据库连接字符串是否正确，特别是用户名、密码和数据库名称。

Q: 媒体文件丢失如何处理？

A: 确保在升级过程中正确配置了MEDIA_PATH路径，并检查文件权限。

Q: 升级后性能下降怎么办？

A: 如果使用SQLite遇到性能问题，可以考虑切换回PostgreSQL方案。

结语

通过本文的详细指导，您应该能够顺利完成Black Candy从v2到v3的升级。v3版本带来了更简洁的架构和更低的资源消耗，建议所有用户尽快升级以获得更好的使用体验。如果在升级过程中遇到任何问题，可以参考项目文档或寻求社区支持。

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