Kavita 服务器迁移指南：硬件更换与环境重建步骤
Kavita 服务器迁移指南：硬件更换与环境重建步骤
【免费下载链接】Kavita Kavita is a fast, feature rich, cross platform reading server. Built with a focus for manga and the goal of being a full solution for all your reading needs. Setup your own server and share your reading collection with your friends and family. 
项目地址: https://gitcode.com/gh_mirrors/ka/Kavita
迁移前准备工作
Kavita 服务器迁移需重点保护用户数据与配置，避免因硬件更换导致阅读进度丢失或服务中断。迁移前需确认源服务器运行状态，备份核心数据文件与配置项。
核心文件定位
- 配置文件：API/config/appsettings.json 存储服务器端口（默认5000）、缓存策略等关键配置
- 用户数据：通过 API/Data/DataContext.cs 与 API/Data/UnitOfWork.cs 实现的数据访问层管理所有用户数据
- 邮件模板：API/config/templates/ 目录下存储邮件通知模板，迁移时需完整保留
必备工具
- 文件传输工具（如
scp或图形化工具） - 文本编辑器（用于核对配置文件）
- 备份存储介质（容量建议 ≥ 源数据目录2倍）
数据备份流程
关键目录备份
- 配置目录：
cp -r API/config/ /backup/kavita-config/
- 用户数据：需备份整个数据库文件（默认存储路径需通过 API/Data/Repositories/ 实现的仓储层确认）
- 媒体文件：漫画/图书源文件目录（通过 API/DTOs/LibraryDto.cs 中定义的
Path字段获取实际路径）
验证备份完整性
检查备份文件大小与源文件是否一致：
du -sh /backup/kavita-config/
du -sh /path/to/original/config/
新服务器环境部署
基础环境配置
- 安装与源服务器相同版本的依赖（参考 INSTALL.txt）：
# Linux系统权限配置
chmod +x Kavita
chown -R user:user /opt/kavita/
- 启动基础服务：
./Kavita & # 后台运行服务
配置文件迁移
- 将备份的配置文件复制到新服务器对应目录：
cp -r /backup/kavita-config/ API/config/
- 验证配置参数：
- 端口号：API/config/appsettings.json 中
Port字段 - 缓存设置：确认
Cache数值与源服务器一致（默认75）
数据恢复与验证
数据库恢复
- 复制备份的数据库文件到新服务器数据目录
- 通过仓储层接口验证数据完整性：
// 示例代码来自 [API.Tests/Extensions/SeriesFilterTests.cs](https://link.gitcode.com/i/ca9bbfdbe1018901dcd8946e758f89c9)
var series = await unitOfWork.SeriesRepository.GetSeriesByIdAsync(1);
Assert.NotNull(series); // 验证核心数据是否恢复成功
服务验证流程
- 访问新服务器地址
http://new-server-ip:5000 - 登录管理员账户，检查：
- 库列表完整性（通过 API/Services/LibraryService.cs 实现）
- 用户阅读进度（通过 API/Entities/AppUserProgress.cs 实体验证）
- 邮件通知功能（测试发送 API/config/templates/EmailTest.html）
迁移后优化
性能调优
- 调整缓存大小：根据新服务器内存配置修改 API/config/appsettings.json 中
Cache字段 - 设置开机自启：
# 示例：systemd服务配置
cat > /etc/systemd/system/kavita.service << EOF
[Unit]
Description=Kavita Reading Server
[Service]
ExecStart=/opt/kavita/Kavita
WorkingDirectory=/opt/kavita/
User=user
[Install]
WantedBy=multi-user.target
EOF
systemctl enable kavita
监控与维护
- 日志监控：定期检查服务日志（默认存储在应用根目录
logs/下） - 定期备份：配置定时任务自动备份数据库文件
常见问题处理
服务启动失败
- 端口冲突：修改 API/config/appsettings.json 中
Port字段 - 权限问题：参考 INSTALL.txt 第2步重新配置文件权限
数据不一致
- 通过 API/Services/MetadataService.cs 提供的元数据修复功能重建索引
- 执行数据库一致性检查（通过 API/Data/DataContext.cs 实现的上下文对象）
迁移 checklist
| 检查项 | 状态 | 参考文档 |
|---|---|---|
| 配置文件完整性 | □ | API/config/appsettings.json |
| 用户数据恢复 | □ | API/Data/UnitOfWork.cs |
| 媒体文件访问权限 | □ | INSTALL.txt |
| 服务端口可达性 | □ | API/config/appsettings.json |
| 邮件功能测试 | □ | API/config/templates/EmailTest.html |
完成迁移后，建议观察服务运行至少24小时，确认无数据丢失或功能异常后再下线源服务器。定期备份策略可参考 API/Services/HostedServices/ 中提供的定时任务框架实现自动化。
【免费下载链接】Kavita Kavita is a fast, feature rich, cross platform reading server. Built with a focus for manga and the goal of being a full solution for all your reading needs. Setup your own server and share your reading collection with your friends and family. 项目地址: https://gitcode.com/gh_mirrors/ka/Kavita
