★ FEATURED ARTICLE 后端【免费下载链接】Tachidesk-ServerA rewrite of Tachiyomi for the Desktop项目地址https://gitcode.com/gh_mirrors/ta/Tachidesk-Server点击查看免费下载本篇技术指南以 Tachidesk-ServerSuwayomi-ServerTachiyomi 的桌面端重写版官方 Troubleshooting.md 为主线系统梳理服务器运行中最常见的五类故障——数据库损坏、HTTP 429 限流、扩展加载超时、Cloudflare 人机验证拦截与 Flaresolverr 连接失败并给出从对症下药到数据目录整体重置的完整修复路径。读完本文你将能根据具体报错信息快速定位故障根因、正确操作 Flaresolverr 相关配置项并在万不得已时安全执行备份-重置-恢复的完整流程。排查前置准备先停服再动手官方文档开篇就强调了一条铁律以下所有步骤都假定你已经停止了 Suwayomi/Tachidesk-Server 服务。无论是删除数据文件、重建数据库还是清理缓存目录在进程运行状态下操作都会导致文件占用、写入冲突甚至引入新的损坏。如果排查过程中需要向社区求助官方建议提前准备好日志文件。日志位于 The Data Directory 下的logs目录中附带完整错误堆栈的日志是他人帮你定位问题的最快途径。此外理解数据目录在哪是一切排查的基础。根据 The Data Directory默认数据目录因操作系统而异将Account替换为你的用户名Windows 7 及以后C:\Users\Account\AppData\Local\TachideskWindows XPC:\Documents and Settings\Account\Application Data\Local Settings\TachideskmacOS/Users/Account/Library/Application Support/TachideskUnix/Linux/home/account/.local/share/Tachidesk如果你希望把数据目录放到自定义位置可以通过 JVM 启动参数指定例如java -Dsuwayomi.tachidesk.config.server.rootDirD:\Tachidesk Data -jar Tachidesk-vX.Y.Z-rxxxx.jar该参数对应的配置声明位于源码 ServerConfig.kt 中server.rootDir设置项。下文所有涉及删除数据文件的操作都是针对这个目录进行的。数据库损坏Broken database典型报错特征当你看到以下任一错误文本时基本可以判定数据库已损坏或不兼容failed due to org.jetbrains.exposed.exceptions.ExposedSQLException: org.h2.jdbc.JdbcSQLSyntaxErrorException: Column CATEGORY.SORT_ORDER not foundorg.h2.jdbc.JdbcSQLSyntaxErrorException: Column CHAPTER.KOREADER_HASH not foundjava.lang.IllegalStateException: Unable to read the page at position 96170708817765466任何包含SQL Statement字样的其他错误文本根因分析从报错内容可以反推两类成因数据库与程序版本不匹配例如Column CATEGORY.SORT_ORDER not found和Column CHAPTER.KOREADER_HASH not found表明当前程序版本期望的数据库表结构中存在sort_order、koreader_hash等列但磁盘上的旧数据库缺少这些列。这两列在源码中确实存在CategoryTable.ktserver/src/main/kotlin/suwayomi/tachidesk/manga/model/table/CategoryTable.kt定义了val order integer(sort_order).default(0)ChapterTable.ktserver/src/main/kotlin/suwayomi/tachidesk/manga/model/table/ChapterTable.kt定义了val koreaderHash varchar(koreader_hash, 32).nullable()。此类报错的典型触发场景是你曾运行预览版preview随后降级回稳定版stable旧程序写入的数据库结构无法被当前版本识别。数据库文件物理损坏Unable to read the page at position ...这类错误通常来自 H2 数据库引擎无法读取数据页常见诱因是未正常关闭 Suwayomi如直接杀进程或程序意外崩溃。解决方案如果是预览版降级到稳定版导致的不兼容直接重新升级回预览版即可恢复。其余情况损坏或无法确定的兼容性问题需要重置数据并从备份恢复具体操作见下文通用故障排除章节。官方明确警告此类问题没有更温和的修复手段切勿试图手动修补 H2 数据库文件。HTTP error 429请求过于频繁被限流报错含义HTTP error 429Too Many Requests意味着数据源source已把你屏蔽——你在短时间内向对方服务器发送了太多请求。如果你启用了追踪Tracker功能追踪服务同样可能对你限流。官方文档特别指出一个高频误伤场景批量迁移Mass-Migration会在短时间内对数据源和所有已配置的追踪服务产生意想不到的高并发请求量极易触发 429。解决方案更换或增加数据源分散请求压力减少并发下载任务在进行批量操作如迁移、全量更新之间留出足够的等待时间让请求间隔趋于合理。从源码层面看限流拦截器 RateLimitInterceptor.kt 实现了扩展库的rateLimit(permits, period)机制如permits 5, period 1.seconds表示每秒最多 5 个请求它通过请求时间戳队列与Semaphore公平锁控制同一域名下的请求节奏。需要理解的是这是 Suwayomi 客户端侧对源站请求节奏的自我约束而 429 是源站服务器侧的回应——两者并不冲突出现 429 说明源站仍认为你的请求过快正确的做法是进一步放慢节奏。扩展超时Extension times out典型报错特征Timed out waiting for 20000 ms…Timed out waiting for page list第一步判断问题归属看到这类超时错误时先判断是扩展自身的问题还是 Suwayomi 的问题在出问题条目的漫画详情页点击Open in WebView在 WebView 中打开观察页面加载情况。WebView 能正常加载说明网络、服务器、渲染链路都正常问题出在扩展本身。此时应去官方仓库的 issues 区与 Discord 社区检索该扩展是否有已知问题例如网站改版导致扩展失效。WebView 加载出错问题出在 Suwayomi 本地环境。按下一步处理。第二步清理本地渲染缓存WebView 报错时进入 The Data Directory删除其中的bin和cache两个文件夹然后重启 Suwayomi。如果重启后 WebView 依然无法工作说明你的安装不完整。在 Linux 上请对照项目 README 中 WebView support (GNU/Linux) 一节的说明补齐依赖例如 KCEF/CEF 浏览器内核相关组件。从源码看WebView 功能由 WebViewController.kt 与 KcefWebView.kt 等模块提供bin/cache目录正是这些浏览器内核组件运行时生成/缓存的产物删除后重启会触发重新初始化。相关报错的语义补充Timed out waiting for 20000 ms中的 20000ms 是扩展发起网络请求时的默认超时上限从架构上看扩展的超时请求经由 NetworkHelper.kt 构建的 OkHttp 客户端发出。若源站本身响应极慢或处于半故障状态也会表现为同样的超时错误——这也是为什么要先通过 WebView 手动验证源站可达性。Flaresolverr 相关故障Cloudflare 的人机验证bot protection是漫画源站最常用的反爬手段。Suwayomi 通过 Flaresolverr 服务来绕过此类挑战相关配置项全部集中在源码 ServerConfig.kt 的CLOUDFLARE设置分组对应 SettingGroup.kt 中的CLOUDFLARE(Cloudflare)下具体包括配置项默认值类型说明server.flareSolverrEnabledfalse布尔是否启用 Flaresolverr 集成server.flareSolverrUrlhttp://localhost:8191字符串Flaresolverr 服务地址server.flareSolverrTimeout60秒整数等待 Flaresolverr 解题的超时时间server.flareSolverrSessionNamesuwayomi字符串会话名用于复用解题 Cookieserver.flareSolverrSessionTtl15分钟整数会话存活时长server.flareSolverrAsResponseFallbackfalse布尔未检测到 Cloudflare 时是否直接回退使用 Flaresolverr 返回的响应体Flaresolverr requiredjava.io.IOException: Cloudflare bypass currently disabled此报错表示你访问的数据源已启用 Cloudflare 的机器人防护——用浏览器打开该源站首页应当能看到Confirm Im human确认我是人类的验证页。从源码 CloudflareInterceptor.kt 可以看清触发链路拦截器首先检查响应状态码是否为403/503ERROR_CODES且响应头Server为cloudflare-nginx或cloudflareSERVER_CHECK满足条件即判定Cloudflare 反机器人已开启随后读取server.flareSolverrEnabled配置若为false则直接抛出IOException(Cloudflare bypass currently disabled)——这正是你看到的报错文本。解决方案下载并部署 Flaresolverr 或 Byparr然后在 Suwayomi 设置中启用 Flaresolverr。请注意每次使用这类源站时都必须保持 Flaresolverr/Byparr 处于运行状态否则绕行机制无法生效。启用后拦截器会向server.flareSolverrUrl默认http://localhost:8191的/v1端点发送request.get/request.post指令见CFClearance.resolveWithFlareSolver携带会话名、session_ttl_minutes、returnOnlyCookies等参数成功后会将 Flaresolverr 返回的cf_clearanceCookie 与 User-Agent 写入本地 Cookie 存储再用带 Cookie 的请求重放原始请求。Flaresolverr not runningjava.io.IOException: Failed to connect to localhost/[0:0:0:0:0:0:0:1]:8191此报错意味着你已经在设置中开启了server.flareSolverrEnabled但 Flaresolverr没有安装或没有在运行8191端口无服务在监听[0:0:0:0:0:0:0:1]即 IPv6 形式的 localhost。按顺序排查确认 Flaresolverr 已安装并正在运行。尤其注意在 Windows 上不要关闭运行它的控制台窗口否则服务随之退出。确认server.flareSolverrUrl配置正确。默认值http://localhost:8191通常无需修改除非你将服务部署在了其他主机或端口。检查防火墙设置。若服务在运行且地址正确你的系统防火墙可能拦截了到 Flaresolverr 的连接。通用故障排除General Troubleshooting核弹级方案如果以上针对性方案均无效官方文档提供了最终手段将 Suwayomi 重置为干净的安装状态。[!WARNING] 此操作将删除全部数据包括整个书架library 操作前务必确认你已经按上文所述备份了所有数据完整步骤如下备份确保手头有一份较新的书架备份——如果应用还能启动就在应用内创建一份备份Settings Backup。停止服务确认 Suwayomi 完全退出右键托盘图标退出或用操作系统提供的方式结束进程。清理浏览器数据如果你通过浏览器访问 Suwayomi WebUI清空浏览器的全部站点数据避免旧缓存/旧登录态干扰。删除数据目录找到 The Data Directory 中的数据目录并整体删除然后重新启动应用。如果你希望保留已下载的漫画文件可以尝试外科手术式地只删除以下部分注意只删其中一部分可能无法解决问题database.mv.dbH2 主数据库文件database.trace.dbH2 跟踪文件bin浏览器内核组件cache缓存extensions扩展安装目录settings设置webUIWeb 界面资源恢复备份启动 Suwayomi进入Settings Backup Restore Backup选择最新备份进行恢复。注意从备份恢复不会恢复已下载的漫画。如果你在第 4 步保留了下载文件此时需要重新下载所有漫画——好在 Suwayomi 会识别磁盘上已存在的文件不会真的重复下载未变化的内容只是补齐元数据与索引。若问题反复出现如果你需要周期性执行此操作、或上述步骤未能解决问题请在官方仓库提交 issue或加入官方 Discord 服务器附上logs目录中的日志寻求社区帮助。排查路径速查表报错/症状判定方向首选动作Column CATEGORY.SORT_ORDER not found等 SQL 语句错误数据库不兼容/损坏预览版降级则升回预览版否则重置恢复备份Unable to read the page at position ...数据库物理损坏重置恢复备份HTTP error 429源站限流减少请求频率、分散数据源、错开批量操作Timed out waiting for 20000 ms…扩展或本地渲染问题用 WebView 判别归属删除bin、cache后重启Cloudflare bypass currently disabled源站开启 CF 验证且未启用 Flaresolverr部署并保持 Flaresolverr 运行Failed to connect to localhost/...:8191Flaresolverr 未运行/地址错误/被防火墙拦截按顺序检查运行状态→URL→防火墙本文所有配置项、报错文本与文件路径均以当前仓库docs/Troubleshooting.md、server/server-config/src/main/kotlin/suwayomi/tachidesk/server/ServerConfig.kt、server/src/main/kotlin/eu/kanade/tachiyomi/network/interceptor/CloudflareInterceptor.kt为准。需要深入研究的读者可以继续阅读 The-Data-Directory.md 了解数据目录细节或在 server/src/main/kotlin/suwayomi/tachidesk/server/database/migration 中查看数据库表结构的演进历史从而理解版本不兼容报错背后的迁移机制。赞分享后端【免费下载链接】Tachidesk-ServerA rewrite of Tachiyomi for the Desktop项目地址https://gitcode.com/gh_mirrors/ta/Tachidesk-Server点击查看免费下载相关推荐如何用开源项目解放小爱音箱打造你的专属智能音乐系统如何用开源项目解放小爱音箱打造你的专属智能音乐系统 你是否曾为小爱音箱无法播放本地音乐而烦恼是否希望用语音就能控制播放自己的音乐收藏XiaoMusic开源后端智能硬件音视频实战解析GGCNN实时生成式机器人抓取网络的深度应用实战解析GGCNN实时生成式机器人抓取网络的深度应用 GGCNNGenerative Grasping CNN是一个基于深度学习的实时机器人抓取合成框架人工智能深度学习计算机视觉机器人Ceph Monitor 故障排查完全指南从 Quorum 状态判断到存储损坏恢复Ceph Monitor 故障排查完全指南从 Quorum 状态判断到存储损坏恢复 导读 本文以 Ceph 官方运维文档《Troubleshooting M存储分布式文件系统对象存储后端高可用上一篇GetQzonehistory如何一次扫码把QQ空间所有说说备份到Excel下一篇Rivet Actors 仓库 OpenSpec 工作流实践用 /opsx-verify 在归档前验证实现与变更工件的一致性创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
