不用再手动导出Siftly实时同步X书签的OAuth原理与定时任务配置指南【免费下载链接】SiftlyLocal Twitter/X bookmark organizer with AI categorization and mindmap visualization项目地址: https://gitcode.com/gh_mirrors/si/Siftly还在一次次把 XTwitter书签导出成 JSON 再拖进 Siftly 吗Siftly 是一款自托管的 Twitter/X 书签管理工具用本地 SQLite 存数据、AI 自动分类、脑图可视化。过去你只能靠书签小工具bookmarklet或控制台脚本手动导出而 Siftly 新增了两条免手动通道官方 OAuth 2.0 授权直连与Cookie 实时同步 定时任务。这篇指南帮你彻底搞懂它的同步原理并一步步配好自动定时任务。为什么还要手动导出先看清老痛点 ⚠️Siftly 最早提供的导入方式是书签小工具和浏览器控制台脚本登录 X 的书签页 → 自动滚动抓取 → 下载bookmarks.json→ 上传。它可靠但每次都是手动触发。书签是活的今天收藏 20 条、下周又加了 50 条你就得重复整个流程。对重度收藏党来说这才是真正的负担。核心诉求只有一个让 Siftly 自己定期去 X 上拉取增量书签。下面两种方式都能做到。Siftly 的两种免导出同步方式 方式认证来源数据来源是否官方自动续期OAuth 授权直连X 开发者 Client ID/Secret官方 REST APIapi.x.com/2/users/me/bookmarks✅ 官方✅ Token 自动刷新Cookie 实时同步浏览器里的auth_tokenct0X 网页内部 GraphQL 接口⚠️ 非官方⏰ 需配定时任务两者都落在同一个数据库里、共用同一套按tweetId去重的导入逻辑所以随便用哪种、甚至混用都不会产生重复书签。OAuth 原理拆解一次授权长期自动续期 OAuth 这条路径走的是 X 官方 OAuth 2.0 PKCES256流程整个链路被拆成 4 个 API 路由全部在 app/api/import/x-oauth/ 目录下。第 1 步生成 PKCE 并跳转授权前端请求 authorize/route.ts 时服务端会用crypto.randomBytes(32)生成code_verifier再做 SHA-256 得到code_challengeS256生成随机state防 CSRF连同 origin 一起存进本地Setting表返回一个https://x.com/i/oauth2/authorize?…链接请求里带的授权范围scope是bookmark.read tweet.read users.read offline.access——只读书签且offline.access是关键它让 X 返回refresh_token从而支持长期免登录。第 2 步回调换 Token用户授权后回到 callback/route.ts它做三件安全且重要的事校验state和库里存的值比对不一致立刻报错杜绝 CSRF。用授权码换 Token带code_verifier去https://api.x.com/2/oauth2/token拿到access_token、refresh_token、expires_in全部落库。拉取用户信息调api.x.com/2/users/me记录昵称/用户名便于界面展示最后清理掉临时的 PKCE 字段。第 3 步自动刷新过期 Token真正取书签在 fetch/route.ts。它的getValidToken()会先比对x_oauth_token_expiry未过期 → 直接用缓存的access_token已过期 → 用refresh_token静默换新 Token再重新存库也就是说你几乎永远不用再重新授权同步可以常年自动跑下去。Cookie 实时同步 定时任务配置 ⏰如果你没有 X 开发者账号官方 API 需要申请可以用 Cookie 方式把浏览器里的auth_token和ct0粘进 Siftly它模仿网页客户端直接调 X 的内部 GraphQL 书签接口。核心逻辑分两块取数与入库x-sync.ts 的syncBookmarks()配合 twitter-api.ts分页拉取单次上限 50 页、解析时间线、按tweetId去重后写入数据库并自动抓取图片/视频/GIF 媒体。定时调度同一文件的startScheduler()读取x_sync_interval配置用setInterval周期性触发runScheduledSync()。定时任务的四个档位在 live/route.ts 中syncInterval只接受以下取值off 1h 4h 8h 24hoff停止调度器不再自动同步1h / 4h / 8h / 24h分别对应每 1 / 4 / 8 / 24 小时同步一次配置、查询、删除凭证都通过POST / GET / DELETE三个方法统一走这个路由手动触发一次同步则由 live/sync/route.ts 的POST负责。内置的自我保护机制Siftly 不是傻等它在 x-sync.ts 里写好了容错防并发syncing标志位保证同一时刻只有一个同步任务在跑重复请求返回 409。缺凭证就跳过定时任务触发时若库里没有auth_token/ct0直接静默跳过不会刷错误。授权失效自动停摆一旦接口返回401 / 403凭证失效或封禁调度器会stopScheduler()自动停掉避免无效轮询。结构变更告警若 X 改了返回结构导致首页解析为空会明确抛出提示提醒你更新解析逻辑。快速上手步骤 OAuth 路径推荐长期省心在 X 开发者平台创建应用拿到Client ID可选Client Secret在 Siftly 设置页填入到 app/import/ 页面点Connect X Account跳转 X 授权并同意授权成功自动回跳点拉取书签即可之后 Token 自动续期Cookie 定时任务路径无需开发者账号登录 X 书签页从浏览器请求头里复制auth_token和ct0填进 Siftly 的实时同步配置app/api/import/live/选择同步间隔如4h保存后调度器立即启动想看进度随时点手动同步一次或改回off关闭 两种方式可共存先用 OAuth 做长期主干Cookie 作为无开发者账号时的兜底。两种方式怎么选一张表看懂 你的情况推荐方案理由有 X 开发者账号、追求长期稳定OAuth 授权直连官方 API Token 自动刷新最省心没有开发者账号、想立刻用起来Cookie 实时同步零门槛配个4h就能自动跑书签更新极频繁每天几十条OAuth 短间隔 / 手动同步官方接口更稳分页更可靠只是偶尔补几条继续用 bookmarklet 手动导出没必要常驻凭证常见问题 FAQ ❓Q定时任务重启服务后会丢吗syncInterval存在本地Setting表里配置是持久的调度器本身是进程内setInterval应用启动时会依据配置重新拉起。Q同步会不会把书签存到云端的 X 服务器上不会。所有书签、媒体、分类都存在你本机的 SQLite 文件里Siftly 只向你配置的 AI 端点和你授权的 X 接口发请求无遥测、无追踪。Q401/403频繁出现怎么办说明 Cookie 凭证失效或被风控。重新复制最新的auth_token/ct0即可OAuth 路径则重新走一次授权。小结 Siftly 让你从手动导出 JSON彻底解放出来OAuth 2.0 PKCE提供长期免登录的官方直连Cookie 实时同步 1h/4h/8h/24h 定时任务提供零门槛的自动兜底两者共用同一套去重入库逻辑并内置防并发、自动停摆等容错。配上之后你的 X 书签知识库会自动、安静地保持最新——把时间留给真正想研究的内容吧。【免费下载链接】SiftlyLocal Twitter/X bookmark organizer with AI categorization and mindmap visualization项目地址: https://gitcode.com/gh_mirrors/si/Siftly创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考