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_DIRWAYLAND_DISPLAYDISPLAYDBUS_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 端口。
常用环境变量
| 变量 | 用途 | 默认 |
|---|---|---|
PORT |
后端端口 | 3001 |
RADAR_DATA_DIR |
数据根目录 | ./data |
RADAR_BASE_URL |
RSS 媒体绝对地址 | http://localhost:$PORT |
RADAR_CDP_PORT |
受管 Chrome CDP 端口 | 19223 |
RADAR_PROFILE_DIR |
受管 Chrome profile 目录 | ./profiles/main |
RADAR_CHROME_BIN |
Chrome 可执行文件 | 自动探测 |
RADAR_CHROME_OZONE_PLATFORM |
Chrome Ozone 平台，例如 wayland |
检测到 WAYLAND_DISPLAY 时为 wayland |
RADAR_PROXY |
媒体下载代理 | http://127.0.0.1:7890 |
REFRESH_API_TARGET |
Vite 反代的后端地址 | http://localhost:3001 |
REFRESH_ALLOWED_HOSTS |
Vite 允许访问的 host ，逗号分隔 | 未设置 |
REFRESH_PUBLIC_URL |
公网部署 URL ，供 scripts/start-k2-tmux.sh 使用 |
脚本必填 |
文档
| 文件 | 内容 |
|---|---|
| AGENTS.md | 当前架构、约定、API 速查、常见任务操作手册 |
| docs/design.md | 原始设计蓝图和设计取舍 |
| docs/progress.md | 实施日志、踩坑记录和后续候选项 |
Select Language