OpenList-Strm

Appearance

常见问题 ​

本文档收集了用户在使用 OpenList to Stream 过程中遇到的常见问题和解决方案。

🚀 版本升级问题 ​

Q: V1 升级到 V2 版本后无法启动？ ​

A: V2.0.0 是重大架构更新，不支持直接升级，需要手动迁移数据。

问题症状：

  • 容器启动后立即退出
  • 数据库连接失败
  • 配置文件无法读取
  • 日志显示路径错误

解决方法：

📋 迁移步骤 ​

  1. 停止旧版本容器
bash
docker-compose down

  1. 挂载目录调整 按照以下步骤复制数据到新的挂载目录：

  2. 迁移数据库文件

bash
# 原 /app/data/config/db 目录下的所有 db 文件复制到新的挂载目录下的 /maindata/db 下
cp ./data/config/db/* ./data/db/
  1. 迁移日志文件
bash
# 原 /app/data/log 目录下的 log 文件复制到新的挂载目录下的 /maindata/log
cp ./data/log/* ./logs/
  1. 迁移配置文件
bash
# 原 /app/data/config 目录下的所有 json 文件复制到新的挂载目录下的 /maindata/config 下
cp ./data/config/*.json ./data/config/
  1. 启动容器
bash
docker-compose up -d

🔍 关键路径变更对比 ​

文件类型旧路径 (V1)新路径 (V2)
数据库文件/app/data/config/db//maindata/db/
配置文件/app/data/config//maindata/config/
日志文件/app/data/log//maindata/log/
STRM 文件/app/backend/strm//app/backend/strm/ (不变)

⚠️ 重要注意事项 ​

  • 手动迁移: 必须手动复制数据文件，不能自动升级
  • 路径变更: 容器内路径结构完全重新设计
  • 配置更新: 使用新的环境变量配置方式

🔧 故障排除 ​

如果迁移后仍有问题：

  1. 检查容器日志
bash
docker logs ostrm
  1. 验证数据完整性
bash
# 检查文件是否正确迁移
ls -la ./data/db/
ls -la ./data/config/
ls -la ./logs/
  1. 确认目录权限
bash
chmod -R 755 ./data ./logs ./strm

💡 为什么需要手动迁移？ ​

V2.0.0 版本进行了以下重大改进：

  • 🏗️ 架构重构: 大量代码重构，提升系统稳定性
  • 🐳 容器优化: 改进 Docker 构建，使用 Ubuntu 22.04 基础镜像
  • 📁 路径标准化: 统一容器内路径管理，增强跨平台兼容性
  • 🔧 依赖更新: 升级到 Java 21 运行时环境

这些改进虽然带来了更好的性能和兼容性，但也导致了数据结构的重大变化，因此需要手动迁移以确保数据安全。

📄 字幕文件问题 ​

Q: 字幕文件没有下载？ ​

A: 字幕文件下载失败可能有以下原因：

  1. 未开启配置

    • 确认已开启「保留字幕文件」选项
    • 在系统设置或任务配置中检查此选项

  2. OpenList 中不存在字幕文件

    • 确认 OpenList 目录中确实存在字幕文件
    • 检查字幕文件格式是否支持

  3. 字幕格式不支持

    • 系统支持以下格式：.srt、.ass、.vtt、.ssa、.sub、.idx
    • 其他格式不会被识别和下载

  4. 网络问题

    • 检查与 OpenList 服务器的网络连接
    • 查看执行日志中的具体错误信息

  5. 权限问题

    • 确认输出目录有写入权限
    • 确认 OpenList 访问令牌有读取权限

Q: 字幕文件重复下载？ ​

A: 系统默认会过滤已下载的字幕文件。如果出现重复：

  1. 检查是否有多个相同名称的字幕文件
  2. 查看日志确认是否真的重复下载
  3. 手动清理后重新执行任务

Q: 字幕文件下载后找不到？ ​

A: 字幕文件默认保存在与 STRM 文件相同的目录下：

  1. 检查 STRM 文件同级目录
  2. 确认字幕文件名与视频文件名匹配
  3. 查看任务执行日志确认下载路径

Q: 包含中文的字幕文件名无法下载？ ​

A: 系统已内置 URL 编码支持：

  1. 确认使用的是最新版本
  2. 在系统设置中开启「URL 编码」选项
  3. 查看日志确认编码是否正确处理

🖼️ 图片文件问题 ​

Q: 图片文件没有下载？ ​

A: 图片文件下载失败可能有以下原因：

  1. 未开启配置

    • 确认已开启相关刮削选项
    • 检查「使用已有刮削信息」设置

  2. 图片下载优先级问题 系统支持三级下载优先级：

    • 第一级：本地是否存在
    • 第二级：OpenList 下载
    • 第三级：TMDB 刮削

    如果前两级找到文件，就不会进行第三级刮削。

  3. OpenList 中不存在图片文件

    • 确认 OpenList 目录中确实存在图片文件
    • 检查图片格式是否支持：.jpg、.jpeg、.png、.webp、.bmp

  4. 图片命名不符合规范

    • 标准命名：{baseFileName}-poster.jpg、{baseFileName}-fanart.jpg、{baseFileName}-thumb.jpg
    • 系统也支持任意命名图片的降级策略

  5. TMDB API 问题

    • 确认 TMDB API 密钥已配置
    • 检查网络连接是否正常
    • 确认 API 配额是否用完

Q: 海报图片和背景图有什么区别？ ​

A: 不同类型的图片用途不同：

  • 海报图片 (-poster.jpg)：用于媒体库的封面展示
  • 背景图 (-fanart.jpg)：用于媒体库的背景展示
  • 缩略图 (-thumb.jpg)：用于剧集的缩略图展示

Q: 不想使用 OpenList 中的图片，直接刮削怎么办？ ​

A: 可以通过以下方式：

  1. 不开启「使用已有刮削信息」选项
  2. 或者删除 OpenList 中已有的图片文件
  3. 系统会自动降级到 TMDB 刮削

Q: 图片文件下载后文件名为乱码？ ​

A: 这是 URL 编码导致的问题：

  1. 确认使用的是最新版本
  2. 系统会自动处理 URL 编码
  3. 如果仍有问题，查看日志并提交 Issue

🔧 任务执行问题 ​

Q: 任务执行很慢怎么办？ ​

A: 可以尝试以下优化：

  1. 启用增量更新模式

    • 只处理新增或修改的文件
    • 避免重复刮削

  2. 减少并发任务数

    • 在系统设置中调整并发数量

  3. 开启本地优先模式

    • 开启「使用已有刮削信息」
    • 开启「保留字幕文件」

  4. 检查网络连接

    • 确保网络连接稳定
    • 考虑配置代理

  5. 分批处理

    • 将大量文件分成多个任务

Q: 任务执行失败怎么办？ ​

A: 按以下步骤排查：

  1. 查看执行日志

    • 定位具体的错误信息
    • 记录错误发生的文件

  2. 检查文件权限

    • 确认输出目录可写
    • 确认 OpenList 可访问

  3. 检查网络连接

    • 测试 OpenList 连接
    • 测试 TMDB API 连接

  4. 检查文件格式

    • 确认视频格式支持
    • 确认文件名没有特殊字符

  5. 重试任务

    • 修正问题后重新执行
    • 开启「失败重试」选项

Q: 如何查看详细的执行日志？ ​

A: 有多种方式查看日志：

  1. Web 界面查看

    • 访问「日志」页面
    • 按任务、级别、时间筛选

  2. 容器日志

bash
docker logs ostrm
  1. 本地日志文件
    • 查看 ./logs/ 目录下的日志文件

📊 刮削问题 ​

Q: 刮削功能不工作？ ​

A: 检查以下几点：

  1. TMDB API 配置

    • 确认 API 密钥已配置
    • 验证 API 密钥是否有效

  2. 网络连接

    • 测试是否能够访问 TMDB
    • 考虑配置代理

  3. 刮削开关

    • 确认已开启刮削功能
    • 确认相关选项已配置

  4. 文件命名

    • 确保文件名规范
    • 尝试使用 AI 识别辅助

Q: 刮削结果不准确？ ​

A: 可以尝试以下方法：

  1. 改进文件名

    • 使用规范的文件命名
    • 包含年份、季集等信息

  2. 使用 AI 识别

    • 开启 AI 识别功能
    • 提供更准确的匹配

  3. 手动刮削

    • 对于重要文件，可以手动刮削
    • 系统会保存手动刮削结果

  4. 检查语言设置

    • 确认刮削语言设置正确
    • 尝试切换语言重新刮削

💾 存储问题 ​

Q: 存储空间不足怎么办？ ​

A: 可以尝试以下方法：

  1. 清理孤立文件

    • 系统会自动清理
    • 也可以手动执行清理

  2. 减少刮削内容

    • 只刮削必要的文件
    • 关闭不需要的刮削选项

  3. 使用增量更新

    • 避免重复处理

  4. 外接存储

    • 将 STRM 文件存储到外接存储

Q: 如何备份数据？ ​

A: 有多种备份方式：

  1. 使用备份脚本
bash
./dev-docker.sh backup
  1. 手动备份
bash
# 备份数据库
cp ./data/db/openlist2strm.db ./backup/

# 备份配置
cp ./data/config/*.json ./backup/

# 备份 STRM 文件
cp -r ./strm ./backup/
  1. Docker 卷备份
bash
docker run --rm -v ostrm_data:/data -v $(pwd)/backup:/backup alpine tar czf /backup/ostrm-data.tar.gz -C /data .

🌐 网络问题 ​

Q: 无法连接 OpenList 服务器？ ​

A: 检查以下几点：

  1. 服务器地址

    • 确认地址正确
    • 包含正确的端口号

  2. 网络连接

    • 测试网络连通性
    • 检查防火墙设置

  3. Token 有效性

    • 确认 Token 未过期
    • 确认 Token 权限足够

  4. SSL 证书

    • 如果使用 HTTPS，确认证书有效
    • 考虑添加信任证书

Q: TMDB API 无法访问？ ​

A: 可以尝试以下方法：

  1. 检查 API 密钥

    • 确认密钥正确
    • 确认密钥未过期

  2. 网络代理

    • 配置 HTTP 代理
    • 在系统设置中填入代理地址

  3. 网络环境

    • 检查网络是否能够访问 TMDB
    • 考虑使用 VPN

📞 获取帮助 ​

问题未解决？ ​

如果按照迁移指南操作后仍有问题：

  1. 收集信息

    • 记录具体的错误信息
    • 提供完整的操作步骤
    • 包含容器启动日志

  2. 寻求帮助

  3. 参考文档

重要提醒: 升级前请务必备份数据，严格按照迁移指南操作，避免数据丢失。