https://github.com/nixliuxin/qzone-time-machine
QQ空间时光机 - 全量导出与本地浏览工具 | Archive your entire QZone and browse it offline
https://github.com/nixliuxin/qzone-time-machine
archive backup china data-export digital-archive electron nostalgia offline-viewer puppeteer qq qq-zone qzone qzone-backup qzone-export react self-hosted social-media-backup time-machine typescript
Last synced: 5 days ago
JSON representation
QQ空间时光机 - 全量导出与本地浏览工具 | Archive your entire QZone and browse it offline
- Host: GitHub
- URL: https://github.com/nixliuxin/qzone-time-machine
- Owner: nixliuxin
- License: mit
- Created: 2026-05-30T18:19:08.000Z (26 days ago)
- Default Branch: main
- Last Pushed: 2026-06-17T03:58:40.000Z (8 days ago)
- Last Synced: 2026-06-17T04:25:12.920Z (8 days ago)
- Topics: archive, backup, china, data-export, digital-archive, electron, nostalgia, offline-viewer, puppeteer, qq, qq-zone, qzone, qzone-backup, qzone-export, react, self-hosted, social-media-backup, time-machine, typescript
- Language: JavaScript
- Size: 438 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.en.md
- License: LICENSE
- Roadmap: ROADMAP.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
English ·
简体中文
QZone Time Machine
QZone-Time-Machine
Archive memories, preserve emotions
Back up your QQ Zone memories before they disappear.
QR code login, one-click backup, offline browsing — no server required.
---
## Features
- **Zero-Server Architecture** — Runs entirely on your machine, never uploads data anywhere
- **Local QR Code Login** — Authenticates via local Chromium with QQ's official login page; credentials stay on your device
- **Open Source & Transparent** — Fully auditable code, no telemetry or tracking
- **Complete Backup** — 10 modules fully collected
- **Original Quality** — Downloads images and videos at their highest available resolution
- **Resumable** — Interrupted backups continue where they left off
- **Smart Rate Limiting** — Automatic retry with exponential backoff
- **Offline Viewer** — Double-click `index.html` to browse locally, no internet or server required
- **Portable Output** — Standard JSON files with relative media paths
- **QQ Emoji Archival** — Automatically downloads all referenced QQ emojis locally for full offline access
---
## Supported Modules
| Module | Content | Additional Info |
|--------|---------|-----------------|
| **Messages** | Text, images, video, audio | Comments, geolocation, source device, forward count |
| **Blogs** | Full content (rich text/images) | Category tags, original/repost flag, comments |
| **Private Diaries** | Full content | Owner-only entries |
| **Albums** | Original resolution photos & video | Album description, EXIF, capture/upload time, POI, comments |
| **Videos** | Video files | Description, comments |
| **Message Board** | Full board messages | Replies, media attachments |
| **Friends** | Friend list | Groups, remarks, friendship date |
| **Favorites** | Favorited content | Source info |
| **Shares** | Shared content | Source, comments |
| **Visitors** | Visit records | Visitor info, visit content summary |
---
## Quick Start
```bash
# Install dependencies
pnpm install
# Build everything (CLI + viewer)
pnpm build
# Step 1: Log in (scan QR code with mobile QQ)
pnpm cli -- login
# Step 2: Back up a user
pnpm cli -- backup 123456789 -n "Nickname"
# Convert legacy backups (QZoneExport format)
pnpm cli -- convert ./old-backup ./output
```
### Sync scope (`--scope`)
`backup` / `backup-all` use `--scope` to control sync depth (both are always safe to re-run and resume automatically):
- `--scope full` (default) — rescan the lists (discover newly-added/missing **whole** items) and backfill details + media. Prioritizes completeness.
- `--scope topup` — trust the local lists as complete and **only backfill missing per-item data** (comments / likes / visitors / full content / media), skipping the list rescan (the step most likely to trip rate limits). Lowest API cost; only tops up accounts that already have a backup.
```bash
# Full sync (default)
pnpm cli -- backup 123456789 -n "Nickname"
# Light top-up: only fill gaps on an existing backup, no list rescan
pnpm cli -- backup 123456789 -n "Nickname" --scope topup
```
> The old `--fill-missing` flag is kept as a deprecated alias for `--scope topup`.
## Output Structure
Each backed-up user produces a self-contained directory:
```
{qq_number}_{name}/
├── index.html ← Double-click to browse offline
├── data/ JSON data files
│ ├── user.json
│ ├── messages.json
│ ├── blogs.json
│ ├── boards.json
│ ├── videos.json
│ ├── diaries.json
│ ├── friends.json
│ ├── favorites.json
│ ├── shares.json
│ ├── visitors.json
│ └── photos/
│ ├── albums.json Album index
│ └── {albumId}.json Photos for each album
└── media/ Downloaded images & videos
├── messages/images/
├── blogs/images/
├── albums/photos/{class}/{album}/
├── albums/covers/
├── emoji/ QQ emojis (localized)
└── videos/videos/
```
## Offline Viewer
After backup, a React SPA is automatically embedded into `index.html`:
- Light/dark mode toggle
- Click images to zoom, navigate with arrow keys
- Album EXIF info panel
- Inline video playback
- Full board/blog rendering with comments, avatars, and links
- Data completeness report
- Traditional pagination with keyboard shortcuts
## Architecture
```
QZone-Time-Machine (pnpm monorepo)
├── packages/cli TypeScript CLI + CommonJS engine
│ ├── src/index.ts Entry point (login / backup / convert)
│ ├── src/convert.ts Legacy data migration
│ └── engine/ Battle-tested JS collection engine (via createRequire)
└── packages/viewer React + Vite SPA
├── Single-file bundle (vite-plugin-singlefile)
└── Embedded in index.html for file:// protocol support
```
## Requirements
- Node.js 18+
- pnpm 9+
- Chromium / Chrome (for QR code login)
## Acknowledgements
This project was inspired by and built upon the work of:
- [QZoneExport](https://github.com/ShunCai/QZoneExport) — QQ Zone data export browser extension
- [QzonePhoto](https://github.com/11273/QzonePhoto) — QQ Zone photo downloader
## Disclaimer
### Security & Privacy
- This tool uses a **zero-server architecture** — runs entirely locally, never uploads any data
- Login uses QQ's official QR scan page via local Chromium; credentials are stored only in local `cookies.json`
- Intended for backing up **your own** QQ Zone data only; do not use to access others' data without authorization
### Copyright
- QQ Zone, QQ, and related trademarks belong to Tencent Holdings Ltd.
- QQ Zone logo copyright belongs to Tencent ([source](https://zh.wikipedia.org/wiki/File:Qzone-logo.png))
- This tool is not affiliated with Tencent
### Warranty
- Provided "as is" without warranty of any kind, express or implied
- Users assume all responsibility for consequences of using this tool
- QQ Zone APIs may change at any time; long-term availability is not guaranteed
## License
[MIT](LICENSE) (c) 2026 Nix Liu Xin