rainblogweb/README.md

# 🌧️ RainWeb - 个人云管理平台

[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)

一体化个人云平台，集成博客、论坛、密码管理器、管理后台聚合等功能，Material Design 3 风格，支持深色/浅色切换。

## 功能概览

| 功能 | 说明 |
|------|------|
| 📝 **博客** | 瀑布流布局，支持 Markdown 渲染，响应式设计 |
| 💬 **论坛** | 多分类，发帖/回复，用户权限管理 |
| 🔒 **密码管理器** | AES-256-GCM 加密存储，PIN 码解锁，密码生成/复制 |
| 📋 **管理面板聚合** | 在 iframe 中嵌入多个管理后台，统一入口 |
| 🌓 **深浅色主题** | Material Design 3 色彩系统，一键切换 |
| 🖼️ **壁纸背景** | 上传自定义壁纸，多种缩放方式，自动半透叠加提升可读性 |
| 🧊 **磨砂玻璃效果** | 导航栏/卡片磨砂玻璃样式，可调模糊强度和透明度 |
| 📧 **邮箱验证注册** | SMTP 邮件发送，Material 风格邮件模板 |
| 🔐 **验证码系统** | 内置扭曲文字验证码 / Google reCAPTCHA V2，支持登录/注册/发帖场景 |
| 🛠️ **CLI 工具** | 命令行管理：修改密码、端口、验证码规则、一键升级 |
| 🔑 **首次初始化向导** | 首次启动自动引导设置管理员密码和站点信息 |

## 快速开始

### 环境要求

- **Node.js** 22 或更高版本（推荐 22 LTS）
- **npm** 随 Node.js 安装

### 下载安装

| 方式 | 文件 | 说明 |
|------|------|------|
| 🪟 Windows 开箱即用 | `rainweb-win.zip` | 含 node_modules，解压双击 `start.bat` 即可 |
| 📦 源码版 | `rainweb-source.zip` | 需 `npm install` 安装依赖，适用于宝塔/Linux |

**Windows：**
```bash
解压 rainweb-win.zip → 双击 start.bat → 访问 http://localhost:3001
```

**Linux / 宝塔面板：**
```bash
unzip rainweb-source.zip -d rainweb
cd rainweb
npm install
npm run build
npm start
```

首次访问会自动跳转 `http://localhost:3001/setup.html` 完成初始化。

### 宝塔面板部署

1. 上传 `rainweb-baota.zip` 到服务器并解压
2. 宝塔面板 → 网站 → Node项目 → 添加Node项目
   - **启动文件**: `server.js`
   - **端口**: `3001`
3. 提交后宝塔自动 `npm install` 并启动
4. 若未自动构建，手动执行 `npm run build`（构建 React 前端到 `public/dist/`）
5. 如需域名访问，配置 Nginx 反向代理：

```nginx
server {
    listen 80;
    server_name 你的域名.com;

    location / {
        proxy_pass http://127.0.0.1:3001;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
    }
}
```

### Docker 部署（可选）

```bash
# 使用 Node.js 官方镜像
docker run -d -p 3001:3001 -v $(pwd)/data:/app/data node:22 bash -c "
  cd /app && npm install && node server.js
"
```

## 默认账号

| 用户名 | 密码 | 角色 |
|--------|------|------|
| `admin` | `admin123` | 管理员 |

**首次启动后请及时修改密码。**

## CLI 命令

```bash
node cli.js <command>
# 或
npm run cli -- <command>
```

| 命令 | 说明 |
|------|------|
| `status [--json]` | 查看版本、服务、数据库和备份状态 |
| `health [--json]` | HTTP 健康检查和 SQLite 完整性检查；不健康时返回非 0 |
| `db-check [--json]` | 只读检查数据库完整性和关键表 |
| `start` | 校验 PID 后启动服务器，已运行时不会重复启动 |
| `stop` | 只停止确认属于本项目的 `server.js`，优雅等待退出 |
| `restart` | 优雅停止并等待后启动服务器 |
| `port [number]` | 查看/修改端口 |
| `password` | 交互式修改管理员密码（兼容旧的末尾参数写法） |
| `captcha` | 交互式配置验证码；也支持 `--type`、`--login`、`--register`、`--forum`、`--failed`、`--threshold` |
| `config [--json]` | 查看配置，敏感值统一脱敏 |
| `backup` | 创建数据库备份并立即做完整性检查 |
| `backup list [--json]` | 列出备份并检查 SQLite 完整性 |
| `backup prune --keep N [--yes]` | 预览清理旧备份；只有显式 `--yes` 才删除 |
| `backup restore <file> --yes` | 服务停止后恢复指定备份；显式确认才覆盖，旧库会保留 |
| `upgrade` | 升级前备份，检查干净工作区，`git pull --ff-only`、安装、构建并在服务原本运行时重启验活 |

通用选项：`--yes` 跳过确认，`--json` 输出 JSON，HTTP 检查可用 `--timeout 100-60000` 设置毫秒超时。密码默认交互输入，不建议在命令行中传递明文密码。

## 技术栈

- **后端**: Node.js + Express
- **数据库**: SQLite (better-sqlite3)
- **前端**: React + Vite + React Router（前台原生样式 / 后台 MUI）
- **加密**: AES-256-GCM, PBKDF2, bcrypt
- **验证码**: SVG 扭曲文字 / Google reCAPTCHA V2
- **文件上传**: multer
- **邮件**: nodemailer
- **Markdown**: marked

## 项目结构

```
rainweb/
├── server.js              # 主入口
├── vite.config.js         # Vite 构建配置
├── cli.js                 # CLI 工具
├── db.js                  # 数据库层
├── middleware/
│   └── auth.js            # JWT 认证中间件
├── routes/                # API 路由
│   ├── auth.js            # 登录/注册/用户管理
│   ├── blog.js            # 博客 CRUD
│   ├── forum.js           # 论坛/帖子/回复
│   ├── passwords.js       # 密码管理器
│   ├── admin-links.js     # 管理面板链接
│   ├── captcha.js         # 验证码生成/验证
│   ├── settings.js        # 站点设置
│   ├── email.js           # SMTP 邮件
│   ├── upload.js          # 壁纸上传
│   ├── setup.js           # 初始化向导
│   ├── announcements.js   # 公告
│   └── profile.js         # 个人资料
├── frontend/              # React 前端源码（Vite 根目录）
│   ├── index.html         # 前台入口（含 ${site_name} 占位符）
│   ├── admin.html         # 后台入口
│   └── src/
│       ├── main.jsx       # 前台入口
│       ├── App.jsx        # 前台布局 + 路由表
│       ├── admin/         # 后台入口（MUI）
│       ├── api/           # fetch 封装
│       ├── lib/           # 工具函数
│       ├── theme.jsx      # 主题切换（data-theme）
│       └── pages/         # 前台页面
├── public/
│   ├── dist/              # Vite 构建产物（npm run build 生成，serveIndex 读取）
│   ├── css/style.css      # 全局样式 + 主题
│   └── wallpaper/         # 上传的壁纸
└── package.json
```

## 站点设置

管理后台提供以下配置项：

### 基本设置
- 网站名称、描述
- 主题色
- reCAPTCHA V2 (Site Key / Secret Key)

### 验证码设置
- 类型：关闭 / 内置验证码 / Google reCAPTCHA
- 应用范围：登录、注册、发帖、失败次数过多

### 主题设置
- 主题色
- 壁纸上传 / URL / 缩放方式
- 导航栏样式：默认 / 磨砂玻璃 / 胶囊
- 卡片样式：实色 / 磨砂玻璃
- 玻璃效果：模糊强度、透明度

### SMTP 邮件
- 主机、端口、用户名、密码
- 发件人邮箱、名称
- 支持测试发送

## 开发

```bash
# 开发模式（Vite dev server，端口 5173，/api 与 /uploads 代理到本地后端 3101）
npm run dev

# 构建生产产物到 public/dist/
npm run build

# 预览构建产物
npm run preview

# 生产运行（Express 服务 public/ 与构建产物）
npm start
```

前端为 React + Vite，开发时前端改动由 Vite 热更新，无需刷新；生产部署必须先在服务器执行 `npm run build` 生成 `public/dist/`。

## 升级

```bash
# 方法1：一键升级（推荐；仅限自托管机器本地执行）
node cli.js upgrade

# 方法2：手动
git pull --ff-only
npm install
npm run build
node cli.js restart
```

`upgrade` 要求 git 工作区干净，只执行 fast-forward 更新；失败会返回非 0，不会假报成功。`backup prune` 默认只预览不删除，`backup restore` 必须同时满足服务已停止和 `--yes`。

## 版本

当前版本记录在项目根目录的 `VERSION` 文件中，导航栏标题右侧会显示当前版本号。

## Releases

| 文件 | 说明 |
|------|------|
| `rainweb-win.zip` | Windows 开箱即用版，包含 node_modules，解压即运行 |
| `rainweb-source.zip` | 源码版，需 `npm install`，适用于 Linux / 宝塔面板 |

## License

MIT