链接健康检测：自动发现失效书签

书签的价值在于它指向的内容。然而互联网是一个不断变化的世界，网站关闭、页面迁移、域名过期每天都在发生。一个收藏了半年的技术文章链接，很可能已经返回 404 了。如果你的书签库中充斥着大量失效链接，它不仅无法帮你找到有用的信息，反而会浪费你的时间。MarkStackAI 的链接健康检测功能可以自动扫描你的书签库，精准定位每一个失效链接。

健康检测的工作原理

链接健康检测的核心逻辑是：对书签中的每一个 URL 发起 HTTP 请求，根据响应的状态码和连接结果判断链接是否有效。

后端使用 Python 的 httpx 异步 HTTP 客户端来执行检测请求。每次检测会先尝试发送 HEAD 请求（只获取响应头，不下载内容），如果目标服务器不支持 HEAD 方法，再降级为 GET 请求。这种策略既保证了检测的准确性，又尽可能减少了对目标网站的负载。

检测过程中，系统会手动跟随 HTTP 重定向（而不是让 HTTP 客户端自动跟随），每一跳都会验证目标 URL 的安全性，防止 SSRF（服务端请求伪造）攻击。最多允许 5 次重定向跳转。

检测结果类型

每个书签检测完成后，会被标记为以下四种健康状态之一：

• 有效（Valid）：HTTP 状态码为 2xx，表示链接正常可访问。在书签卡片上显示为绿色圆形标志。
• 无效（Broken）：HTTP 状态码为 4xx 或 5xx，或者连接被拒绝。常见原因包括页面被删除（404）、服务器错误（500）、权限拒绝（403）等。在书签卡片上显示为红色圆形标志。
• 重定向（Redirect）：HTTP 状态码为 3xx，表示链接被重定向到了另一个地址。虽然链接仍然可以访问，但可能需要更新为最终的目标 URL。在书签卡片上显示为黄色标志。
• 超时（Timeout）：请求在规定时间内没有收到响应。默认超时时间为 10 秒。超时可能是网站暂时不可用，也可能是网站设置了严格的访问限制。

对于标记为「待检测」的书签（尚未执行过健康检测），在书签卡片右下角会显示一个灰色的问号标志。

异步并发检测

如果你的书签库有几百甚至上千个书签，逐个检测将耗费大量时间。MarkStackAI 使用 Python 的 asyncio 异步框架来并发执行检测任务，大幅提升检测速度。

并发检测的关键设计：

• 并发限制：使用信号量（Semaphore）控制同时进行的 HTTP 请求数量，避免对目标网站造成过大压力，同时防止后端服务器资源耗尽。
• 请求间延迟：对同一域名的请求之间设置短暂延迟，避免被目标网站的速率限制拦截。
• 超时保护：整个检测任务设置总体超时时间（12 秒），单个 HTTP 请求超时设置为 8 秒。即使某个网站响应异常缓慢，也不会阻塞整个检测流程。
• 异常隔离：使用 return_exceptions=True 确保单个请求的异常不会导致整批检测任务失败。某个链接检测出错，其他链接的检测不受影响。

实际测试中，300 个书签的全量检测通常可以在 30 秒到 1 分钟内完成，具体耗时取决于目标网站的响应速度。

使用健康检测页面

在侧栏点击「链接检测」进入健康检测页面。页面顶部是统计卡片区域，展示四项关键数据：

• 总书签数：当前书签库中的书签总数。
• 有效链接：检测结果为有效的书签数量。
• 无效链接：检测结果为无效（包括超时）的书签数量。
• 待检测：尚未执行过健康检测的书签数量。

统计卡片下方是操作按钮区域。点击「开始检测」按钮即可启动全量健康检测。检测过程中，页面会实时更新进度和结果。检测完成后，下方的结果列表会展示所有书签的健康状态。

你可以通过筛选器只显示特定状态的书签，比如只查看无效链接，方便集中处理问题书签。

文件夹级别检测

除了全量检测，MarkStackAI 还支持针对特定文件夹的局部检测。在书签管理页面，每个文件夹的工具栏上有一个检测按钮，点击后只会检测该文件夹及其子文件夹中的书签。

文件夹级别检测的应用场景包括：

• 刚导入了一批新书签，想快速验证它们是否都有效。
• 某个分类下的书签比较老旧，想重点检测一下存活率。
• 全量检测耗时太长，想分批次逐个文件夹检测。

后端的 health_service.py 通过 folder_id 参数来支持局部检测，只查询指定文件夹下的书签 URL 进行检测。

批量选择检测

在书签管理页面，你还可以通过复选框多选特定的书签，然后点击批量操作栏的「检测」按钮，只对选中的书签执行健康检测。这种精准检测方式特别适合以下场景：

• 你怀疑某几个特定网站最近出了问题，想单独验证。
• 之前检测结果为超时的书签，想重新检测看是否恢复。
• 新添加的几个书签，想立即确认链接是否有效。

批量选择检测调用的是后端的 POST /health/check-batch API，传入选中书签的 ID 列表，后端只对这些特定书签执行检测，响应更快，服务器负载更小。

批量删除无效书签

检测出无效链接后，下一步自然是清理它们。健康检测页面的结果列表支持复选框多选，配合批量操作栏可以一键删除所有选中的无效书签。

批量删除的操作流程：

1. 在健康检测页面，使用筛选器只显示「无效」状态的书签。
2. 勾选需要删除的书签，或点击全选复选框选中所有无效书签。
3. 点击批量操作栏的「删除」按钮。
4. 在确认对话框中确认操作。
5. 被删除的书签进入回收站，如果误删可以恢复。

批量删除调用 POST /bookmarks/batch-delete API，单次最多支持删除 500 个书签。删除是软删除，数据不会立即消失，在回收站中仍然可以恢复。

书签卡片上的健康状态指示器

健康检测的结果不仅在检测页面展示，也会反馈到书签管理页面的每一个书签卡片上。在网格视图的大卡片模式下，每个书签的右下角会显示一个小圆形标志：

• 绿色圆形 + 勾号：链接有效
• 红色圆形 + 叉号：链接无效
• 灰色圆形 + 问号：尚未检测

这些标志采用单字符设计，体积小巧不会遮挡书签的标题和其他信息，但又足够醒目让你一眼就能识别出问题链接。在列表视图中，健康状态也以类似的方式展示在每一行的末尾。

健康检测的安全考量

健康检测涉及服务端向外部 URL 发起 HTTP 请求，这在安全上需要特别注意。MarkStackAI 采取了以下安全措施：

• SSRF 防护：每次请求前验证目标 URL 是否为安全地址，禁止访问内网 IP 地址（如 127.0.0.1、10.x.x.x、192.168.x.x 等）和特殊协议。
• 重定向验证：手动跟随重定向时，每一跳都会重新验证目标 URL 的安全性，防止通过重定向绕过 SSRF 防护。
• 最大重定向次数：限制最多 5 次重定向，防止无限重定向循环。
• 请求超时：严格的超时设置防止被恶意服务器慢速响应拖住。
• User-Agent 标识：使用标准的 User-Agent 字符串，部分网站会根据 User-Agent 决定是否响应。

检测频率建议

链接健康检测不需要每天运行。根据书签库的规模和更新频率，建议以下检测策略：

• 书签量较少（100 个以内）：每周执行一次全量检测即可。
• 书签量中等（100-500 个）：每两周执行一次全量检测，新添加的书签可以单独即时检测。
• 书签量较大（500 个以上）：每月执行一次全量检测，平时按文件夹分批检测。

检测结果会持久保存在数据库中，不会因为页面刷新或重新登录而丢失。下次检测时，之前的结果会被新结果覆盖。

小结

链接健康检测是书签管理中容易被忽视但极其重要的环节。大量失效链接不仅浪费存储空间，更会在你需要某个链接时带来挫败感。MarkStackAI 通过异步并发检测引擎、多级检测粒度（全量、文件夹级、精准选择）、直观的状态标识和便捷的批量删除功能，让书签库的维护变得轻松高效。定期运行一次健康检测，就能确保你的书签库始终整洁有效，每一个链接都指向真正有价值的内容。