Folo 故障排除完全指南：从问题诊断到系统恢复

环境兼容性检查清单

在进行故障排除前，请确认您的系统环境满足以下要求：

环境要求	最低配置	推荐配置
操作系统	Windows 10 1809+ / macOS 10.15+ / Linux Kernel 4.19+	Windows 11 / macOS 12+ / Linux Kernel 5.4+
硬件资源	4GB RAM, 500MB 存储空间	8GB RAM, SSD 存储
Node.js 版本	v14.17.0	v16.14.0+
网络环境	基本网络连接	稳定宽带连接

环境检查工具：scripts/check-env.ts

启动时出现签名验证错误

问题场景

Windows 系统安装 Folo 时出现"无法验证发布者"或"应用已损坏"的错误提示，安装进程中断。

原因分析

Windows 系统的用户账户控制(UAC)和数字签名验证机制阻止了未经过微软认证的应用程序运行。Folo 作为开源软件使用自签名证书，可能被部分系统安全设置识别为潜在风险。

解决方案

方案 A：通过属性设置解除锁定（基础）

1. 右键点击安装文件，选择"属性"
2. 在"常规"选项卡中，勾选"解除锁定"选项
3. 点击"应用"保存设置
4. 双击安装文件重新尝试安装

⚠️ 注意：此方法适用于大多数个人用户环境，无需管理员权限。

方案 B：命令行强制安装（进阶）

1. 打开命令提示符（Win+R → cmd → 回车）
2. 导航至安装文件所在目录：

   cd C:\path\to\installer
   

3. 执行强制安装命令：

   Folo-Setup.exe --install --force --skip-signature-check
   

相关文档：docs/installation/windows.md

预防措施

1. 加入 Folo 测试版计划，提前获取数字签名的预览版本
2. 在企业环境中，可将 Folo 证书添加至系统信任根证书库
3. 定期通过官方渠道获取最新版本，减少兼容性问题

应用启动后立即崩溃

问题场景

macOS 系统中，Folo 图标短暂出现在 Dock 栏后立即消失，无任何错误提示。

原因分析

此问题通常与以下因素相关：

• 系统版本不兼容（低于 macOS 10.15）
• 应用权限不足，无法访问必要系统资源
• 应用缓存损坏或配置文件错误
• 与其他系统扩展或安全软件冲突

解决方案

方案 A：权限修复（基础）

1. 打开"系统设置 > 隐私与安全性"
2. 选择"文件和文件夹"选项
3. 确保 Folo 已获得"文档文件夹"和"下载"访问权限
4. 重启应用尝试启动

方案 B：缓存清理与安全模式启动（进阶）

1. 打开终端应用
2. 执行缓存清理命令：

   rm -rf ~/Library/Caches/is.follow
   rm -rf ~/Library/Application\ Support/is.follow
   

3. 尝试安全模式启动：

   open -a Folo --args --safe-mode
   

方案 C：深度日志分析（专家）

1. 启用详细日志记录：

   defaults write is.follow logging.level debug
   

2. 启动应用并收集崩溃日志：

   tail -f ~/Library/Logs/is.follow/main.log
   

3. 分析日志中的错误信息，定位问题根源

日志分析工具：tools/log-analyzer.ts

预防措施

1. 定期清理应用缓存（建议每月一次）
2. 在系统更新前备份 Folo 配置文件
3. 避免安装来源不明的系统扩展

订阅源添加失败

问题场景

尝试添加 RSS 或 Atom 订阅源时，界面提示"无效 URL"或"连接失败"，但该 URL 在浏览器中可正常访问。

原因分析

订阅源添加失败可能涉及多方面技术因素：

• URL 格式错误或缺少协议前缀（http:///https://）
• 网络代理配置不当或防火墙限制
• 源服务器实施了反爬虫机制或用户认证
• 订阅源格式不符合 RSS/Atom 规范
• 应用内部解析器异常

解决方案

方案 A：基础 URL 检查与修复（基础）

1. 确认 URL 以 http:// 或 https:// 开头
2. 移除 URL 末尾可能存在的多余字符（如空格、引号）
3. 在浏览器中验证 URL 可访问性
4. 尝试使用简化版 URL（如去除查询参数）

方案 B：网络环境配置（进阶）

1. 检查系统代理设置：
   • Windows：设置 > 网络和 Internet > 代理
   • macOS：系统设置 > 网络 > 高级 > 代理
2. 在 Folo 中配置网络代理：
   • 打开"设置 > 网络 > 代理设置"
   • 选择"使用系统代理"或手动配置代理服务器
3. 测试网络连接：

   curl -I https://example.com/feed
   

方案 C：高级源验证与手动添加（专家）

1. 使用在线 RSS 验证工具检查源格式
2. 手动下载 feed XML 文件：

   curl https://example.com/feed > feed.xml
   

3. 通过"导入文件"功能添加本地 feed.xml
4. 分析错误日志定位解析问题：

   grep "feed-parser" ~/Library/Logs/is.follow/main.log
   

订阅功能实现：packages/internal/database/src/services/subscription.ts

预防措施

1. 优先使用 HTTPS 协议的订阅源
2. 定期检查订阅源健康状态
3. 对于频繁失效的源，考虑使用 RSS 代理服务

内容同步停滞

问题场景

Folo 显示同步进度卡在特定百分比（如 33% 或 75%），长时间无变化，新内容无法加载。

原因分析

内容同步过程涉及多个环节，任何一环出现问题都可能导致同步停滞：

• 网络连接不稳定或带宽限制
• 大型媒体文件下载超时
• 数据库事务死锁
• 同步服务进程异常终止
• 服务器 API 速率限制

解决方案

方案 A：基础同步重置（基础）

1. 点击界面顶部的"同步"按钮强制刷新
2. 检查网络连接状态，确保稳定联网
3. 关闭并重新启动 Folo 应用
4. 前往"设置 > 内容 > 同步设置"，点击"立即同步"

方案 B：高级同步管理（进阶）

1. 访问"设置 > 高级 > 同步管理"
2. 点击"清除同步队列"按钮
3. 选择性禁用大型媒体文件同步
4. 调整同步参数：
   • 降低同步并发数（默认 5，建议改为 2）
   • 增加超时时间（默认 30 秒，建议改为 60 秒）

方案 C：数据库维护（专家）

1. 关闭 Folo 应用
2. 执行数据库修复命令：

   folo-cli database repair
   

3. 检查数据库文件完整性：

   sqlite3 ~/Library/Application\ Support/is.follow/data.db "PRAGMA integrity_check"
   

4. 手动删除损坏的缓存文件：

   rm -rf ~/Library/Caches/is.follow/sync/*
   

同步服务代码：packages/internal/services/sync.ts

预防措施

1. 配置合理的同步计划（建议非高峰时段）
2. 定期执行数据库维护（每月一次）
3. 对包含大量媒体的订阅源单独设置同步策略

界面渲染异常

问题场景

应用界面出现文字重叠、布局错乱、图标显示异常或颜色失真等视觉问题。

原因分析

界面渲染问题通常与以下因素相关：

• 显卡驱动不兼容或过时
• 系统字体缺失或损坏
• 应用主题缓存损坏
• 高 DPI 显示设置冲突
• CSS 渲染引擎异常

解决方案

方案 A：基础显示设置重置（基础）

1. 前往"设置 > 外观 > 主题"，切换至不同主题
2. 调整界面缩放比例："设置 > 显示 > 缩放"
3. 重置字体设置："设置 > 外观 > 字体 > 恢复默认"
4. 重启应用使设置生效

方案 B：高级渲染修复（进阶）

1. 启用硬件加速兼容模式：
   • 右键点击 Folo 快捷方式
   • 选择"属性 > 目标"
   • 在末尾添加： --disable-gpu --force-cpu-draw
   • 应用更改并重启应用
2. 清除字体缓存：

   # Windows
   del %LOCALAPPDATA%\Folo\font-cache.dat
   
   # macOS
   rm ~/Library/Caches/is.follow/font-cache.dat
   

方案 C：自定义 CSS 修复（专家）

1. 创建自定义 CSS 文件：

   /* 修复特定元素显示问题 */
   .article-content {
     line-height: 1.5 !important;
     font-size: 14px !important;
   }
   

2. 在"设置 > 高级 > 自定义 CSS"中导入该文件
3. 使用开发者工具调试界面元素：
   • 按下 Ctrl+Shift+I (Windows) 或 Cmd+Opt+I (macOS)
   • 使用元素选择工具定位问题组件
   • 实时调整样式并测试效果

界面组件代码：packages/internal/components/

预防措施

1. 保持显卡驱动程序更新
2. 安装系统推荐的字体包
3. 避免在高 DPI 屏幕上使用极端缩放比例
4. 定期清理应用缓存

AI 功能无响应

问题场景

点击"AI 摘要"或"翻译"按钮后，功能无响应或提示"无法连接到 AI 服务"。

原因分析

AI 功能依赖多个组件协同工作，包括：

• 网络连接到 AI 服务 API
• API 密钥配置与验证
• 本地模型加载与运行环境
• 请求速率限制与配额管理
• 防火墙或安全软件拦截

解决方案

方案 A：基础连接检查（基础）

1. 验证网络连接：打开浏览器访问 status.follow.is
2. 检查 API 密钥状态："设置 > AI 功能 > API 密钥"
3. 确保 AI 功能已启用："设置 > AI 功能 > 启用 AI 服务"
4. 尝试切换 AI 服务提供商："设置 > AI 功能 > 服务提供商"

方案 B：高级网络排查（进阶）

1. 测试 API 连接性：

   # 替换 YOUR_API_KEY 为实际密钥
   curl -X POST https://api.follow.is/ai/summary \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"text":"test"}'
   

2. 检查防火墙设置，确保允许 Folo 访问以下域名：
   • api.follow.is
   • *.openai.com (如使用 OpenAI 服务)
   • *.anthropic.com (如使用 Anthropic 服务)
3. 查看 AI 服务日志：

   tail -f ~/Library/Logs/is.follow/ai-service.log
   

方案 C：本地模型配置（专家）

1. 安装本地 AI 模型支持：

   folo-cli ai install-model --model tiny-llama
   

2. 配置本地模型路径：

   folo-cli config set ai.model_path ~/models/tiny-llama
   

3. 验证本地模型运行状态：

   folo-cli ai test-model
   

AI 功能源码：packages/internal/services/ai/

预防措施

1. 定期检查 API 密钥有效期
2. 为 AI 功能配置专用网络连接
3. 对于频繁使用场景，考虑配置本地模型作为备份
4. 监控 AI 服务状态页面获取服务中断通知

数据迁移与恢复

问题场景

需要将 Folo 数据从旧设备迁移到新设备，或在应用崩溃后恢复数据。

原因分析

数据迁移过程涉及多个关键组件：

• 数据库文件完整性
• 配置文件兼容性
• 媒体缓存文件迁移
• 跨平台数据格式差异
• 权限与文件所有权

解决方案

方案 A：标准备份与恢复（基础）

1. 在源设备上创建备份：
   • 打开"设置 > 高级 > 数据管理"
   • 点击"创建备份"，选择保存位置
   • 等待备份完成（通常需要 1-5 分钟）
2. 在目标设备上恢复备份：
   • 复制备份文件到目标设备
   • 打开"设置 > 高级 > 数据管理"
   • 点击"恢复备份"，选择备份文件
   • 重启应用完成恢复

方案 B：手动文件迁移（进阶）

1. 定位数据目录：

   # Windows
   %APPDATA%\is.follow
   
   # macOS
   ~/Library/Application Support/is.follow
   
   # Linux
   ~/.config/is.follow
   

2. 复制核心数据文件：
   • data.db (主数据库)
   • config.json (配置文件)
   • subscriptions.json (订阅列表)
   • cache/ (媒体缓存目录，可选)
3. 在新设备上放置文件到对应目录
4. 修复文件权限（仅 Linux/macOS）：

   chmod -R 700 ~/Library/Application\ Support/is.follow
   

方案 C：命令行迁移工具（专家）

1. 使用 Folo CLI 导出数据：

   folo-cli export --path ~/folo-backup.zip --include-media
   

2. 传输备份文件到新设备
3. 在新设备导入数据：

   folo-cli import --path ~/folo-backup.zip --overwrite
   

4. 验证数据完整性：

   folo-cli database verify
   

数据管理工具：packages/cli/src/commands/backup.ts

预防措施

1. 定期自动备份（建议每周一次）
2. 启用云同步功能（"设置 > 同步 > 云同步"）
3. 导出重要订阅列表为 OPML 文件
4. 保持应用版本一致再进行迁移

总结与支持资源

本文档涵盖了 Folo 应用的常见故障场景及解决方案，从基础操作到高级诊断工具。如果您遇到本文未涵盖的问题，可通过以下渠道获取支持：

• 官方文档：docs/troubleshooting.md
• 社区论坛：forum.follow.is
• 问题跟踪：issues.follow.is
• 技术支持：[e-mail]

提交问题报告时，请包含：

• 应用版本号（"设置 > 关于"）
• 操作系统及版本
• 问题重现步骤
• 相关日志文件

Folo 作为开源项目，欢迎您通过 GitHub 贡献代码或改进文档，共同提升应用稳定性和用户体验。