rohit124551/ghost-vault

# 👻 GhostVault — 粘贴。分享。阅后即焚。 GhostVault 是一个高端、安全且短暂的文件共享生态系统，旨在实现极致的速度与隐私保护。无论您是粘贴一张快速截图与客户分享，还是为敏感文档创建一个临时的“死信箱”房间，GhostVault 都能以优雅的姿态和实时的精确度为您妥善处理。    ## ✨ 核心功能 - **🚀 即时粘贴分享**：在仪表盘任意位置按下 `Ctrl+V` 即可立即上传截图。URL 会自动复制到剪贴板。 - **🔒 安全临时房间**：为访客生成 4 字符令牌房间 (`/r/xxxx`)。链接可设置为在几分钟、几小时或几天后过期。 - **⚡ 实时协作**：通过 Socket.io 进行全双工聊天和文件共享。无需刷新即可实时看到访客的上传和消息。 - **🌗 双主题引擎**：在 **Cyber Midnight**（时尚的暗黑模式）和 **Safe White**（高对比度的明亮模式）之间自由切换。 - **📱 支持 PWA**：支持独立显示，可将 GhostVault 作为原生应用安装在您的 iPhone 或 Android 设备上。 - **📂 通用文件支持**：通过智能的 `auto-detect` Cloudinary 存储，分享 Excel 电子表格、Word 文档、PowerPoint 等。 - **👁️ 阅后即焚模式**：专门设置的房间，在接收到第一个文件后会自动撤销。 - **🚨 紧急模式**：快速连按两次 `Esc` 键可立即隐藏您的文件库。通过一个隐藏的触发器即可恢复。 ## 🛠️ 技术栈 | 层级 | 技术 | 职责 | | :--- | :--- | :--- | | **Frontend** | React (Vite) | 具有现代美感的高性能 SPA | | **Backend** | Node.js (Express) | API 层与实时 Socket 协调 | | **Real-time** | Socket.IO | 用于实时更新的双向通信 | | **Database** | Supabase | 用于存储房间和消息历史的 PostgreSQL 存储 | | **Auth** | Supabase Auth | 安全的 Email 和 Password 身份验证 | | **File Storage** | Cloudinary | 用于图片和原始文档的全球 CDN 存储 | | **Styling** | Vanilla CSS | 具有动态 CSS 变量的自定义设计系统 | ## 📂 项目结构 ``` ghost-vault/ ├── client/ # React + Vite Frontend │ ├── public/ # Static assets (Manifest, Icons, Service Worker) │ └── src/ │ ├── components/ # Reusable UI (ChatWindow, ServerWakeUp, ThemeToggle) │ ├── contexts/ # State providers (Auth, Socket, Theme) │ ├── hooks/ # Custom logic (useServerHealth, useTheme) │ ├── lib/ # Utilities (api, supabase) │ └── pages/ # Full-page components │ ├── LoginPage # Secure entry for Vault Owner │ ├── DashboardPage # Real-time control center & file uploader │ ├── VaultPage # Managed archive of all shared assets │ ├── RoomsPage # Detailed list & management of active/revoked rooms │ ├── GuestRoomPage # Public interface for ephemeral link guests (/r/:token) │ └── NotFoundPage # Friendly 404 feedback for invalid/expired links │ ├── server/ # Node.js + Express + Socket.io Backend │ └── src/ │ ├── lib/ # Integrations │ │ ├── cloudinary.js # Multi-format storage & transformations │ │ ├── supabase.js # DB client & real-time subscriptions │ │ └── token.js # 4-character secure token generator │ ├── middleware/ # Security │ │ └── auth.js # JWT validation & Room-token authorization │ ├── routes/ # API Layer │ │ ├── rooms.js # Room lifecycle (CRUD + Validation) │ │ ├── roomMessages.js # Real-time chat & ephemeral file exchange │ │ ├── upload.js # Screenshot processing & metadata storage │ │ └── uploads.js # Vault management & bulk deletion │ ├── socket/ # Event management │ │ └── index.js # Real-time message broadcasting & revocation │ └── index.js # Server entry point & Middleware config │ ├── supabase-schema.sql # PostgreSQL database structure └── package.json # Workspace & dependency management ``` ## 🚀 设置与部署 ### 1. 数据库与身份验证 (Supabase) - 在 Supabase SQL 编辑器中运行 `supabase-schema.sql`。 - 在 Supabase Dashboard 中启用 **Email & Password** 身份验证。 - 如果您希望即时创建账号/登录，请禁用 **Confirm Email**。 ### 2. 环境配置 **服务器 (`server/.env`)** ``` SUPABASE_URL=your_project_url SUPABASE_SERVICE_ROLE_KEY=your_secret_service_key CLOUDINARY_CLOUD_NAME=your_name CLOUDINARY_API_KEY=your_key CLOUDINARY_API_SECRET=your_secret PORT=4000 FRONTEND_URL=https://your-app.vercel.app ``` **客户端 (`client/.env`)** ``` VITE_SUPABASE_URL=your_project_url VITE_SUPABASE_ANON_KEY=your_public_anon_key VITE_API_URL=https://your-api.onrender.com VITE_SOCKET_URL=https://your-api.onrender.com ``` ### 3. 本地开发 ``` # 安装 root、client 和 server 依赖 npm install # 并发运行所有内容 npm run dev # 或者分别运行 cd server && npm run dev # port 4000 cd client && npm run dev # port 5173 ``` ## 📸 使用与工作流 ### 所有者流程 1. **登录**：输入您授权的 **Email 和 Password**。无需魔术链接。 2. **存入文件库**：直接拖放或使用 `Ctrl+V` **粘贴截图**。如有需要，可设置过期时间。 3. **分享**：点击任意链接上的 QR 图标以显示可扫描的分享弹窗，或复制直接 URL。 4. **监控**：打开任何活动链接的聊天窗口，实时查看访客的互动情况。 ### 访客体验 1. **无需登录**：访客只需打开您分享的 `/r/:token` 链接。 2. **上传与聊天**：他们可以立即拖放文件或发送消息。 3. **自动清理**：一旦链接过期或您将其撤销，访客将立即被重定向至安全的 404 页面。 ### 🚨 紧急模式 - 快速连按两次 `Esc` 键 → 整个 UI 将瞬间消失。 - 点击右下角隐藏的灰色小圆点 → 恢复 UI。 ## 🔒 安全与隐私 - **直接身份验证**：为所有者提供安全的 Email 和 Password 登录。 - **令牌化访问**：访客只能通过唯一的 4 字符令牌访问特定房间。 - **自动清理**：过期数据将从 Supabase 和 Cloudinary 中自动清除。 - **重定向**：无效、已撤销或已过期的链接会立即将访客重定向至安全的 404 页面。 *GhostVault — 用 ❤️ 构建，只为速度与隐私。* ## 📱 PWA 测试清单 要验证 PWA 是否正常工作： 1. **打开 Chrome DevTools → Application → Manifest** - 应显示所有图标和 manifest 详情，且无错误。 2. **Application → Service Workers** - 应显示 `sw.js` 已激活并正在运行。 3. **Lighthouse audit → PWA category** - 应在所有 PWA 检查中获得高分。 4. **在 Android Chrome 上 → 三个点菜单 → "添加到主屏幕"** - 应显示 GhostVault 的名称和图标，而不是通用的。 5. **在 iOS Safari 上 → 分享按钮 → "添加到主屏幕"** - 应显示 GhostVault 的名称和图标。 6. **安装后 → 从主屏幕打开** - 应以独立模式 打开，不带任何浏览器 UI。 - URL 栏应被隐藏。 - 状态栏应与应用主题匹配并呈深色。 - 安全区域 (刘海/主页指示器) 应得到适当的 padding 尊重。

标签：Cloudinary, DNS解析, Express, GNU通用公共许可证, MITM代理, Node.js, PWA, React, Socket.io, Supabase, Syscalls, Vite, 临时聊天室, 全栈应用, 匿名分享, 双因素主题, 后端开发, 实时聊天, 实时通信, 开源项目, 截屏分享, 数据泄露, 文件共享, 文件管理, 暗黑模式, 测试用例, 私密传书, 移动端支持, 网络信息收集, 网络安全, 自动过期, 阅后即焚, 限时分享, 隐私保护