141 lines
5.7 KiB
Markdown
141 lines
5.7 KiB
Markdown
# RSSPipe 🚀
|
|
|
|
> **Modern, High-Performance RSS Information Gateway & Distraction-Free Reader**
|
|
|
|
RSSPipe is a single-user, self-hosted RSS information gateway designed to replace traditional feeds readers with an elegant, ultra-fast, and distraction-free reading experience. Built with a robust Go backend and a modern React PWA interface.
|
|
|
|
---
|
|
|
|
## ✨ Key Features
|
|
|
|
- 🖥️ **Reeder 4 Minimal 3-Pane View**: Designed for desktop power users with collapsible navigation sidebar, dense article list, and distraction-free reading canvas.
|
|
- 📱 **Xiaohongshu-Style Masonry Waterfall**: Designed for mobile and media-rich browsing with adaptive masonry columns, category filter chips, and full-screen post reader.
|
|
- ⚡ **High-Speed Crawler & Engine**: Concurrent worker pool crawler in Go with per-feed polling intervals, custom timeouts, and HTTP conditional caching (ETag / Last-Modified 304).
|
|
- 🔒 **Single-User Security & Auth**: JWT-based session security and bcrypt hashing to secure access over the public internet.
|
|
- 📁 **OPML 2.0 Import & Export**: Effortless migration from Miniflux, Feedly, Inoreader, NetNewsWire, or Reeder.
|
|
- 🔗 **Standalone Article Sharing**: Instant public HTML snapshot sharing (`/share/{uuid}.html`) for individual articles.
|
|
- ⌨️ **Keyboard Navigation**: Complete single-key shortcut navigation (`j`/`k` next/previous, `m` mark read, `s` star, `e` archive, `v` view original, `[` sidebar toggle).
|
|
- 💾 **Local State & Reading Persistence**: Restores exact view modes, filter selections, active feeds, and reading positions upon page refresh.
|
|
|
|
---
|
|
|
|
## 🛠️ Architecture & Tech Stack
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────┐
|
|
│ React 18 PWA Frontend │
|
|
│ (Vite + TypeScript + Lucide + Modern CSS) │
|
|
└──────────────────────────┬──────────────────────────────┘
|
|
│ REST API + Static Asset Serving
|
|
┌──────────────────────────▼──────────────────────────────┐
|
|
│ Go 1.22 HTTP Server │
|
|
│ (Chi Router + JWT Auth) │
|
|
├──────────────────────────┬──────────────────────────────┤
|
|
│ Background Crawler │ SQLite Engine (WAL) │
|
|
│ (Worker Pool + Parser) │ (modernc.org/sqlite Driver) │
|
|
└──────────────────────────┴──────────────────────────────┘
|
|
```
|
|
|
|
- **Backend**: Go 1.22+, `go-chi/chi`, `gofeed` parser, `golang-jwt/jwt`.
|
|
- **Database**: Embedded SQLite with WAL mode (`modernc.org/sqlite` pure Go driver, no CGO required).
|
|
- **Frontend**: React 18, TypeScript, Vite, CSS custom properties.
|
|
|
|
---
|
|
|
|
## 🚀 Quickstart
|
|
|
|
### Option 1: Run with Docker Compose
|
|
|
|
```bash
|
|
# Clone the repository
|
|
git clone https://git.pengzhan.dev/haopengzhan/rsspipe.git
|
|
cd rsspipe
|
|
|
|
# Start RSSPipe
|
|
docker compose up -d
|
|
```
|
|
|
|
Visit **`http://localhost:8080`**.
|
|
Default credentials:
|
|
|
|
- **Username**: `admin`
|
|
- **Password**: `admin123456` *(configurable via environment variables)*
|
|
|
|
---
|
|
|
|
### Option 2: Local Development Setup
|
|
|
|
#### Prerequisites
|
|
|
|
- **Go 1.22+**
|
|
- **Node.js 18+ & npm**
|
|
|
|
```bash
|
|
# Clone the repository
|
|
git clone https://git.pengzhan.dev/haopengzhan/rsspipe.git
|
|
cd rsspipe
|
|
|
|
# Build and start server using Makefile
|
|
make dev
|
|
```
|
|
|
|
Or build separately:
|
|
```bash
|
|
make build # Compiles frontend bundle + backend binary into bin/rsspipe
|
|
./bin/rsspipe # Runs production binary
|
|
```
|
|
|
|
The server binds to `http://localhost:8080` and serves both the API endpoints and static frontend assets.
|
|
|
|
---
|
|
|
|
## ⚙️ Configuration & Environment Variables
|
|
|
|
| Variable | Default | Description |
|
|
| :--- | :--- | :--- |
|
|
| `PORT` | `8080` | Server HTTP port |
|
|
| `DB_PATH` | `./data/rsspipe.db` | Path to SQLite database file |
|
|
| `JWT_SECRET` | *(auto-generated)* | 32-byte secret key for signing JWT tokens |
|
|
| `ADMIN_USERNAME` | `admin` | Initial default administrator username |
|
|
| `ADMIN_PASSWORD` | `admin123456` | Initial default administrator password |
|
|
| `CRAWLER_WORKERS` | `10` | Number of concurrent fetch worker threads |
|
|
| `CRAWLER_INTERVAL` | `15` | Default background crawler interval (minutes) |
|
|
|
|
---
|
|
|
|
## ⌨️ Keyboard Shortcuts
|
|
|
|
| Shortcut | Action |
|
|
| :--- | :--- |
|
|
| `j` / `k` | Navigate to Next / Previous article |
|
|
| `m` | Toggle Read / Unread status |
|
|
| `s` | Toggle Starred status |
|
|
| `e` | Mark as read and advance to next |
|
|
| `v` | Open original article URL in new tab |
|
|
| `[` | Toggle left navigation sidebar |
|
|
| `r` | Trigger immediate refresh of feeds |
|
|
| `a` | Open "Add Subscription" modal |
|
|
| `1` | Switch to Desktop 3-Split View |
|
|
| `2` | Switch to Xiaohongshu Waterfall View |
|
|
| `3` | Switch to Settings & Management View |
|
|
| `Shift + A` | Mark all items in active view as read |
|
|
| `?` | Open keyboard shortcuts cheatsheet |
|
|
| `Esc` | Close any active modal dialog |
|
|
|
|
---
|
|
|
|
## 🧪 Testing & Quality Automation
|
|
|
|
```bash
|
|
make check # Run all quality checks (gofmt, go vet, tests, tsc, gitleaks)
|
|
make test # Run backend Go unit tests
|
|
make lint # Check formatting and run go vet
|
|
make format # Auto-format all Go files
|
|
```
|
|
|
|
---
|
|
|
|
## 📄 License
|
|
|
|
MIT License. Free for personal and commercial self-hosted use.
|