https://github.com/woodgear/refresh

Refresh

Refresh 是一个自托管的个人账号 feed API：用你自己的浏览器登录态，把 X/Twitter 、知乎、B 站推给你的内容采集成结构化资源，再通过网页、RSS 和 JSON API 消费。

它不是多用户托管服务，也不内置第三方账号凭据。登录态、抓取到的内容、媒体缓存和日志都属于本机运行态数据，不提交到仓库。

它做什么

• 通过 Chrome DevTools Protocol 操控一个独立的 Chrome profile 。


• 
  使用你自己的登录态抓取平台推荐流：
  
  
  • X/Twitter home timeline GraphQL 响应
  
  
  • 知乎 topstory / moments API
  
  
  • B 站动态流 / 热门 API
  
  
  
  


• 每次抓取保存为不可变的 RefreshWindow 档案。


• 将内容归一化为 Message / Author / Account 等 k8s 风格资源。


• 提供 React 阅读界面：按源过滤、未读追踪、登录恢复、手动刷新。


• 提供 RSS：/rss/<source>.xml 和 /rss/all.xml。


• 图片会本地化到 data/media，方便 RSS 阅读器稳定回源。

隐私边界

仓库只放应用代码。以下运行态路径已被 git 忽略：

• profiles/：Chrome profile 、cookies 、登录态


• data/：抓取内容、媒体、overlay 、调度器状态、日志


• .env / .env.*：本地部署配置

公开仓库前不要把运行态目录、截图、导出的 cookie 、本地环境变量文件或真实数据样例提交进来。

本地运行

依赖：

• Bun


• pnpm


• Chrome / Chromium


• jq、xmllint（用于 verify.sh）

启动：

pnpm install

pnpm start

默认地址：

• 后端 API：http://localhost:3001


• 前端网页：http://localhost:5173

首次使用时打开 http://localhost:5173。如果账号未登录，页面会提示登录；登录过程发生在受管 Chrome profile （默认 profiles/main）里。

Chrome 启动与登录态

Refresh 不依赖外部浏览器自动化服务。后端需要访问平台时，会先检查本机 CDP：

http://127.0.0.1:${RADAR_CDP_PORT}/json/version

如果 CDP 不可用，后端会自动拉起一个有窗口的 Chrome / Chromium：

• CDP 只监听本机 127.0.0.1。


• 默认 CDP 端口是 19223，可用 RADAR_CDP_PORT 修改。


• 默认 profile 是 profiles/main，可用 RADAR_PROFILE_DIR 修改。


• Chrome 路径会自动探测；找不到时用 RADAR_CHROME_BIN 指定。


• 启动参数包含 --remote-debugging-port 和 --user-data-dir，因此登录态会持久化在 profile 目录里。

登录、扫码和抓取都使用这个同一个 profile 。不要把 profiles/ 提交到仓库。

Linux 服务器部署时需要有可用的图形桌面会话，因为平台登录通常需要可见窗口。scripts/start-k2-tmux.sh 会在 tmux 进程里补齐常见桌面环境变量：

• XDG_RUNTIME_DIR


• WAYLAND_DISPLAY


• DISPLAY


• DBUS_SESSION_BUS_ADDRESS

如果检测到 WAYLAND_DISPLAY，后端启动 Chrome 时会默认追加 --ozone-platform=wayland。需要强制指定时可以设置：

export RADAR_CHROME_OZONE_PLATFORM=wayland

验证

bunx tsc --noEmit

./verify.sh

verify.sh 使用隔离的 mock 数据，不依赖真实平台登录态。

部署

Refresh 运行两个进程：

• 后端：bun server/index.ts


• 前端/Vite 反代：bunx vite

公网部署时，把公网地址放进环境变量，然后用反向代理或 tunnel 暴露 Vite 端口。

示例：

export REFRESH_PUBLIC_URL="https://refresh.example.com"

export SERVER_PORT=13001

export WEB_PORT=13002



scripts/start-k2-tmux.sh

scripts/start-k2-tmux.sh 会：

• 在 tmux session 中启动后端和前端；


• 用 REFRESH_PUBLIC_URL 设置 RADAR_BASE_URL，保证 RSS 里的媒体地址能回源；


• 从 REFRESH_PUBLIC_URL 推导 Vite allowed host ；


• 将进程日志写入 data/logs/。

公网代理或 tunnel 指向：

http://127.0.0.1:${WEB_PORT}

后端通过 Vite proxy 访问，因此通常只需要暴露 Web 端口。

常用环境变量

文档