# PrerenderShield

**Repository Path**: xhpmayun/prerender-shield

## Basic Information

- **Project Name**: PrerenderShield
- **Description**: PrerenderShield 是一款集防火墙安全防护与预渲染功能于一体的企业级 Web 应用中间件，专为解决前后端分离架构下网站发布的痛点而设计。现有防火墙产品（如雷池）无法支持预渲染，而预渲染产品（如 Rendertron）缺乏防火墙能力，PrerenderShield 填补了这一市场空白，为用户提供一站式的安全防护与 SEO 优化解决方案。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2025-12-29
- **Last Updated**: 2026-01-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Prerender Shield

## 0. 前后端分离下的 SEO 痛点

在现代化的 Web 开发中，前后端分离架构（SPA - 单页应用）已成为主流，React、Vue、Angular 等框架带来了极佳的开发体验。然而，这种架构也带来了显著的 SEO 挑战：

### 🔍 **爬虫兼容性问题**
- **搜索引擎爬虫无法执行 JavaScript**：传统搜索引擎爬虫难以解析动态生成的内容
- **首屏加载延迟**：SPA 应用需要先加载 JavaScript 再渲染内容，影响爬虫抓取效率
- **内容索引不完整**：动态路由和异步加载的内容可能无法被完整索引

### 🛡️ **安全防护缺失**
- **API 暴露风险**：前后端分离架构使得 API 接口直接暴露在外网
- **OWASP Top 10 威胁**：XSS、CSRF、SQL 注入等攻击面扩大
- **缺乏统一防护**：需要在多个层面配置安全策略，管理复杂

### 🔄 **技术栈碎片化**
- **需要多个组件组合**：WAF 防火墙 + 渲染预热服务 + 反向代理
- **配置复杂分散**：不同系统有不同的配置方式和监控界面
- **运维成本高昂**：需要维护多个服务的部署、监控和更新

### 💰 **成本与效率问题**
- **商业服务费用高昂**：Cloudflare WAF + Prerender.io 等组合年费可达数千美元
- **资源利用不充分**：单独部署的渲染服务可能对所有请求进行渲染，浪费计算资源
- **响应延迟增加**：多个中间件串联增加请求延迟

## 1. 项目介绍

**Prerender Shield** 是一款创新的企业级 Web 应用中间件，将 **OWASP Top 10 安全防护** 与 **智能渲染预热** 功能深度集成，专为解决前后端分离架构下的 SEO 优化和安全防护痛点而设计。

### 🎯 **核心价值主张**
- **一体化解决方案**：安全防护 + SEO 优化，一套系统解决两个核心问题
- **智能流量路由**：自动识别爬虫请求，按需渲染，避免资源浪费
- **开源自托管**：完全开源，支持私有化部署，数据完全自主可控

### 🏗️ **技术架构**
- **后端**：Go 1.20+（高性能、高并发、内存安全）
- **前端**：React 18 + TypeScript + Ant Design（现代化管理界面）
- **渲染引擎**：Headless Chromium + Puppeteer（标准浏览器渲染）
- **缓存系统**：Redis（高性能内存数据库）
- **部署方式**：原生部署（一键脚本安装）

## 2. 核心功能介绍

### 🔒 **企业级安全防护**

#### OWASP Top 10 全面防护
| 威胁类型 | 防护能力 | 检测方式 |
|---------|---------|---------|
| **注入攻击** | SQL 注入、NoSQL 注入、命令注入 | 正则匹配、语法分析 |
| **跨站脚本** | 存储型 XSS、反射型 XSS、DOM XSS | 输入过滤、输出编码 |
| **跨站请求伪造** | CSRF 令牌验证、Origin 检查 | 令牌验证、来源验证 |
| **不安全反序列化** | 类型安全检查、序列化白名单 | 格式验证、类型检查 |
| **敏感数据泄露** | 数据加密、安全头配置 | 数据掩码、头检测 |
| **XML 外部实体** | XXE 攻击检测与拦截 | XML 解析限制 |
| **组件安全漏洞** | 已知漏洞检测、依赖扫描 | CVE 匹配、版本检查 |

#### 高级安全特性
- **实时威胁检测**：毫秒级响应，自动拦截恶意请求
- **自定义规则引擎**：支持基于正则表达式的自定义防护规则
- **详细审计日志**：完整记录所有安全事件，支持溯源分析
- **GeoIP 过滤**：基于地理位置的黑白名单控制

### 🚀 **智能渲染预热**

#### 爬虫智能识别
- **User-Agent 分析**：自动识别搜索引擎爬虫（Googlebot、Bingbot 等）
- **行为模式检测**：基于请求频率、路径模式的智能识别
- **可配置策略**：支持自定义爬虫识别规则

#### 高性能渲染引擎
- **Headless Chromium**：使用标准浏览器引擎，确保渲染兼容性
- **资源池管理**：Chromium 实例复用，降低内存消耗
- **并发控制**：智能并发限制，防止资源耗尽
- **超时机制**：可配置渲染超时，避免长时间阻塞

#### 缓存优化策略
- **多级缓存**：内存缓存 + Redis 缓存，支持分布式部署
- **智能过期**：基于内容哈希的缓存失效策略
- **条件更新**：支持 If-Modified-Since、ETag 等 HTTP 缓存头
- **预热机制**：支持 sitemap 解析和定时批量预热

### 🔄 **智能流量路由**

#### 请求自动分类
- **爬虫请求** → 渲染预热 → 返回静态 HTML
- **普通用户请求** → 直接转发 → 原样响应
- **API 请求** → 安全检查 → 转发或拦截

#### 动态路由规则
- **基于路径的路由**：不同路径可配置不同处理策略
- **基于域名的路由**：支持多站点独立配置
- **基于条件的路由**：支持复杂的条件判断逻辑

### 📊 **现代化管理界面**

#### 实时监控仪表板
- **安全事件监控**：实时显示拦截的威胁类型和数量
- **渲染状态监控**：显示渲染成功率、平均耗时等指标
- **流量分析**：请求量、响应时间、缓存命中率统计
- **系统健康检查**：服务状态、资源使用情况监控

#### 配置管理中心
- **站点管理**：多站点独立配置，支持批量操作
- **规则管理**：安全规则、渲染规则的可视化管理
- **证书管理**：SSL/TLS 证书的申请和续期
- **用户管理**：基于角色的权限控制系统

### 🔐 **SSL/TLS 支持**
- **Let's Encrypt 集成**：自动申请和续期免费 SSL 证书
- **TLS 1.2/1.3 支持**：最新加密协议，确保传输安全
- **证书自动管理**：零运维成本，自动处理证书过期

## 3. 产品优势对比

### 🏆 **与竞品对比分析**

Prerender Shield 在市场上具有独特的定位，填补了现有产品的功能空白：

#### 市场定位矩阵
| 产品类型 | 代表产品 | 安全防护 | 渲染预热 | 综合网关 | 成本模式 |
|---------|---------|---------|---------|---------|---------|
| **Prerender Shield** | 本项目 | ✅ 完整OWASP防护 | ✅ 智能渲染预热 | ✅ 多站点代理 | 开源免费 |
| **纯WAF产品** | 雷池、Cloudflare WAF | ✅ 企业级防护 | ❌ 不支持 | ❌ 仅安全检测 | 商业付费 |
| **纯渲染产品** | Rendertron、Prerender.io | ❌ 无安全功能 | ✅ 专业渲染 | ❌ 仅渲染服务 | 开源/SAAS |
| **综合网关** | Nginx、Envoy、Traefik | ⚠️ 基础防护 | ❌ 不支持 | ✅ 完整网关功能 | 开源免费 |
| **商业云服务** | AWS WAF + CloudFront | ✅ 云端防护 | ⚠️ 有限支持 | ✅ 完整CDN | 按量付费 |

### 🎯 **核心竞争优势**

#### 1. 功能融合创新
- **一站式解决方案**：首次将企业级 WAF 与 SPA 渲染预热深度集成
- **技术协同优势**：安全检测 → 智能路由 → 按需渲染的完整闭环
- **统一管理体验**：单个界面管理安全和渲染配置，降低学习成本

#### 2. 成本效益显著
| 对比方案 | 年化成本 | 部署复杂度 | 运维成本 |
|---------|---------|-----------|---------|
| **Prerender Shield** | 0元（开源免费） | 低（一键部署） | 低（单系统运维） |
| **雷池WAF + Rendertron** | 2000元+ | 高（多系统集成） | 高（多系统运维） |
| **Cloudflare + Prerender.io** | 5000元+ | 中（云服务配置） | 中（云服务管理） |

#### 3. 技术优势突出
- **智能路由算法**：避免无效渲染，节省 30%+ 计算资源
- **资源优化设计**：Chromium 实例复用，降低内存消耗
- **实时配置更新**：Redis 驱动的动态配置，支持热重载
- **现代化技术栈**：Go + React Type +Script，易于二次开发

#### 4. 本地化优势
- **数据自主可控**：完全自托管，满足中国数据合规要求
- **网络优化**：本地部署，避免跨境网络延迟
- **中文友好**：完整中文文档和界面，降低使用门槛

### ⚡ **性能对比**
| 指标 | Prerender Shield | Rendertron | Prerender.io |
|------|-----------------|------------|--------------|
| **首次渲染延迟** | 300-500ms | 500-800ms | 200-400ms |
| **缓存命中率** | 95%+ | 85%+ | 90%+ |
| **内存消耗** | 中等（资源池优化） | 较高（每次新建实例） | 云服务托管 |
| **并发处理能力** | 50+ 请求/秒 | 20+ 请求/秒 | 按套餐限制 |

### 🛡️ **安全能力对比**
| 安全特性 | Prerender Shield | Cloudflare WAF | 雷池 WAF |
|---------|-----------------|---------------|---------|
| **OWASP 覆盖** | Top 10 完整覆盖 | Top 10 完整覆盖 | Top 10 完整覆盖 |
| **自定义规则** | ✅ 支持 | ✅ 支持 | ✅ 支持 |
| **实时更新** | 社区更新 | ✅ 云端实时更新 | ✅ 定期更新 |
| **审计日志** | ✅ 完整记录 | ✅ 企业版支持 | ✅ 支持 |
| **DDoS 防护** | 基础限流 | ✅ 专业防护 | ✅ 专业防护 |

## 4. 安装与部署

### 📋 **系统要求**

| 组件 | 最低要求 | 推荐配置 |
|------|---------|---------|
| **操作系统** | Linux (Ubuntu 20.04+, CentOS 8+, openSUSE, Alpine) / macOS 12+ | Linux (Ubuntu 22.04 LTS) |
| **CPU** | 2 核 | 4 核 |
| **内存** | 4 GB | 8 GB |
| **磁盘空间** | 10 GB | 20 GB (SSD) |
| **网络** | 可访问公网 | 稳定的网络连接 |
| **架构** | x86_64, arm64 | x86_64 |

### 📥 **部署方案**

Prerender Shield 采用三阶段部署模式：**开发者构建 → 用户安装 → 用户启动**，提供了完整的脚本支持。

#### 🚀 **开发者构建流程**

适合开发者和需要自定义编译的场景：

```bash
# 1. 克隆代码仓库
git clone https://github.com/yourusername/prerender-shield.git
cd prerender-shield

# 2. 给构建脚本添加执行权限
chmod +x build.sh

# 3. 执行构建脚本（自动构建前端和后端）
./build.sh
```

**build.sh 脚本功能说明**：
- ✅ 检查Go和Node.js环境
- ✅ 配置Go模块镜像加速
- ✅ 自动获取当前平台信息
- ✅ 构建前端（安装依赖、交互式设置API地址、构建）
- ✅ 安装Go依赖
- ✅ 构建当前平台的二进制文件（路径：bin/api）
- ✅ 将前端代码从web/dist拷贝到bin/web
- ✅ 构建产物验证和测试
- ✅ 输出构建结果和使用说明

#### 📦 **用户安装流程**

适合普通用户使用，基于预编译的二进制文件进行安装：

```bash
# 1. 确保已经完成构建（由开发者执行）
# ./build.sh

# 2. 给安装脚本添加执行权限
chmod +x install.sh

# 3. 执行安装脚本（自动检测环境）
./install.sh
```

**install.sh 脚本功能说明**：
- ✅ 检测操作系统和架构
- ✅ 检查并安装Redis（如未安装）
- ✅ 交互式配置Redis连接信息并保存到bin/config/config.yml
- ✅ 检查并安装谷歌无头浏览器（如未安装，安装路径：bin/google）
- ✅ 执行安装后的健康检查
- ✅ 输出启动命令和访问信息

#### 🎯 **用户启动流程**

适合普通用户使用，启动已安装的应用：

```bash
# 1. 确保已经完成安装
# ./install.sh

# 2. 启动应用
./bin/api start

# 3. 重启应用
./bin/api restart

# 4. 停止应用
./bin/api stop
```

**启动命令功能说明**：
- ✅ 使用bin/api二进制文件直接启动服务
- ✅ 支持start、restart、stop命令
- ✅ 自动使用bin/config/config.yml配置文件
- ✅ 数据目录：bin/data
- ✅ 日志文件：bin/data/prerender-shield.log
- ✅ 配置文件：bin/config/config.yml

> 注意：也可以继续使用start.sh脚本启动服务，脚本会自动适配新的二进制文件位置

```bash
# 兼容旧版本启动方式
chmod +x start.sh
./start.sh start
```
- ✅ 检测服务是否真正启动
- ✅ 执行服务健康检查
- ✅ 输出清晰的访问信息

### 📋 **脚本体系说明**

| 脚本名称 | 角色 | 主要功能 | 执行环境 |
|----------|------|----------|----------|
| **build.sh** | 开发者构建脚本 | 构建前端和后端，生成多平台二进制文件 | 开发环境 |
| **install.sh** | 用户安装脚本 | 依赖安装和配置，从预编译包安装应用 | 生产环境 |
| **start.sh** | 用户启动脚本 | 启动、停止、重启应用，执行健康检查 | 生产环境 |
| **test_script.sh** | 测试脚本 | 验证脚本体系在不同平台上的兼容性 | 测试环境 |

### 🔍 **验证安装**

安装完成后，请通过以下步骤验证服务是否正常运行：

1. **检查服务状态**
   ```bash
   ./start.sh status
   ```

2. **访问管理界面**
   - 打开浏览器访问：`http://你的服务器IP:9597`
   - 使用默认账号登录：**admin** / **123456**
   - 首次登录建议立即修改默认密码

3. **测试API接口**
   ```bash
   # 健康检查接口
   curl http://localhost:9598/api/v1/health
   # 预期返回：{"status":"ok","timestamp":"..."}
   
   # 版本信息接口
   curl http://localhost:9598/api/v1/version
   # 预期返回：{"version":"v1.0.1","build":"..."}
   ```

### 🚀 **服务管理**

####  **使用 start.sh 脚本管理**

```bash
# 启动服务（使用预编译的二进制文件）
./start.sh start

# 重启服务
./start.sh restart

# 停止服务
./start.sh stop

# 查看服务状态
./start.sh status
```

### 📊 **服务端口说明**

| 服务 | 端口 | 说明 |
|------|------|------|
| **管理界面** | 9597 | Web 管理控制台 |
| **API 服务** | 9598 | 后端 REST API |
| **Redis** | 6379 | 缓存数据库（本地服务） |
| **Prometheus** | 9090 | 监控指标暴露（可选） |

### 📁 **目录结构说明**

```
prerender-shield/                # 项目根目录/运行目录
├── bin/                        # 构建产物目录
│   ├── linux-amd64/            # Linux x86_64 平台
│   │   ├── api                 # 二进制文件
│   │   ├── static/             # 静态资源目录
│   │   └── config/             # 配置文件目录
│   └── ...                     # 其他平台
├── static/                     # 静态资源目录
├── config/                     # 配置文件目录
├── data/                       # 数据目录
│   ├── rules/                  # 防火墙规则目录
│   ├── certs/                  # 证书目录
│   └── logs/                   # 日志目录
└── web/                        # 前端目录
    └── dist/                   # 前端构建产物
```

**项目根目录结构**：

```
prerender-shield/               # 项目根目录
├── bin/                        # 构建产物目录（多平台二进制文件）
│   ├── linux-amd64/            # Linux x86_64 平台
│   │   └── api                 # 二进制文件
│   ├── linux-arm64/            # Linux ARM64 平台
│   ├── darwin-amd64/           # macOS x86_64 平台
│   ├── darwin-arm64/           # macOS ARM64 平台
│   ├── windows-amd64/          # Windows x86_64 平台
│   └── windows-arm64/          # Windows ARM64 平台
├── cmd/                        # Go 命令行入口目录
│   └── api/                    # API 服务入口
│       └── main.go             # 主程序入口
├── configs/                    # 配置文件模板目录
│   └── config.example.yml      # 配置文件模板
├── data/                       # 数据目录（运行时生成）
│   ├── prerender-shield.pid    # 进程PID文件
│   └── prerender-shield.log    # 日志文件
├── web/                        # 前端代码目录
│   ├── dist/                   # 构建后的前端文件（部署时使用）
│   ├── src/                    # 前端源代码
│   ├── package.json            # 前端依赖配置
│   └── vite.config.ts          # Vite配置文件
├── build.sh                    # 构建脚本（开发者使用）
├── install.sh                  # 安装脚本（用户使用）
├── start.sh                    # 启动脚本（用户使用）
├── go.mod                      # Go模块依赖配置
└── README.md                   # 项目说明文档
```

## 5. 配置管理

### 🎯 **主要配置文件**

| 配置文件 | 路径 | 说明 |
|---------|------|------|
| 主配置文件 | `./config/config.yml` | 包含所有核心配置 |
| 站点配置 | 存储在 Redis 中 | 动态站点配置，支持热更新 |
| 系统环境变量 | `/etc/default/prerender-shield` | 系统服务环境变量 |

### 🔧 **配置示例**

```yaml
# 服务器配置
server:
  address: 0.0.0.0
  api_port: 9598
  console_port: 9597

# 目录配置
dirs:
  data_dir: /var/lib/prerender-shield
  static_dir: ./static
  admin_static_dir: ./web/dist
  certs_dir: /var/lib/prerender-shield/certs

# 缓存配置
cache:
  type: redis
  redis_url: "localhost:6379"
  memory_size: 1000

# 监控配置
monitoring:
  enabled: true
  prometheus_address: ":9090"
```

### 🔄 **动态配置更新**

Prerender Shield 支持动态配置更新，无需重启服务即可生效：

1. **通过管理界面更新**：登录管理控制台，在系统配置页面进行修改
2. **通过API更新**：使用 `PUT /api/v1/system/config` 接口更新配置
3. **通过配置文件更新**：直接修改配置文件，系统会自动检测并加载

## 6. 开发与贡献

### 🌟 **完全开源，社区驱动**

Prerender Shield 采用 **MIT 许可证** 完全开源，我们相信：

- **透明可信**：所有代码公开，安全可审计
- **社区共建**：欢迎开发者贡献代码，共同完善功能
- **自由使用**：可自由使用、修改、分发，无任何限制

### 🤝 **如何参与贡献**

#### 代码贡献
1. **Fork 仓库**：创建自己的分支
2. **开发功能**：遵循项目代码规范
3. **提交 PR**：描述功能变更和测试结果
4. **代码审查**：项目维护者进行审查合并

#### 文档贡献
- **完善文档**：帮助改进使用指南、API 文档
- **翻译工作**：协助将文档翻译为其他语言
- **示例代码**：提供使用示例和最佳实践

#### 问题反馈
- **Bug 报告**：在 GitHub Issues 提交详细的问题描述
- **功能建议**：提出有价值的功能改进建议
- **使用反馈**：分享使用经验和改进建议

### 🏗️ **开发环境搭建**

```bash
# 1. 克隆项目
git clone https://gitee.com/xhpmayun/prerender-shield.git
cd prerender-shield

# 2. 启动后端服务（开发模式）
cd cmd/api
go run main.go

# 3. 启动前端开发服务
cd web
npm install
npm run dev

# 4. 访问开发环境
# 管理界面：http://localhost:5173
# API服务：http://localhost:9598
# 默认账号：admin / 123456
```

### 📚 **相关资源**

- **项目主页**：[Gitee](https://gitee.com/xhpmayun/prerender-shield) | [GitHub](https://github.com/xiaofang142/PrerenderShield)
- **在线文档**：[项目文档](https://prerender.websitetool.cn/)
- **问题追踪**：[GitHub Issues](https://github.com/xiaofang142/PrerenderShield/issues)

## 7. 常见问题与故障排除

### ❓ **为什么安装脚本无法安装 Chromium？**

**解决方案**：
1. 安装脚本会尝试多种浏览器安装方案：`chromium` → `chromium-browser` → `google-chrome-stable`
2. 如果所有方案都失败，会提示手动安装
3. 可以手动下载 Chromium 并添加到系统路径

### ❓ **管理控制台无法访问？**

**解决方案**：
1. 检查服务状态：`./start.sh status`
2. 检查端口是否被占用：`netstat -tuln | grep 9597`
3. 检查防火墙设置：`sudo ufw status`（Ubuntu）或 `sudo firewall-cmd --list-ports`（CentOS）
4. 检查日志：查看应用日志文件（默认在 ./logs/ 目录下）

### ❓ **Redis 连接失败？**

**解决方案**：
1. 检查 Redis 服务状态：`sudo systemctl status redis-server` 或 `redis-cli ping`
2. 检查 Redis 配置：`sudo cat /etc/redis/redis.conf | grep -i bind`
3. 确保 Redis 允许远程连接（如果需要）
4. 检查配置文件中的 Redis URL：`grep redis_url ./config/config.yml`

### ❓ **API 服务无法访问？**

**解决方案**：
1. 检查服务状态：`sudo systemctl status prerender-shield`
2. 检查端口是否被占用：`netstat -tuln | grep 9598`
3. 检查 API 日志：`tail -f /var/log/prerender-shield/app.log`

## 8. 联系我们

### 📞 **技术交流与支持**

我们提供多种渠道的技术交流和支持：

#### 即时通讯
- **微信**：xiao142000
- **QQ**：1036698712
- **QQ群**：973280483（技术交流、问题解答）

#### 邮件联系
- **技术支持**：myloveisphp@126.com
- **商务合作**：myloveisphp@126.com
- **安全反馈**：myloveisphp@126.com（请使用 PGP 加密）

#### 开源社区
- **GitHub Discussions**：[功能讨论](https://github.com/xiaofang142/PrerenderShield/discussions)
- **Gitee Issues**：[问题反馈](https://gitee.com/xhpmayun/prerender-shield/issues)

## 9. 项目状态

### 📊 **项目指标**

| 项目指标 | 状态 |
|---------|------|
| **核心功能** | ✅ 已完成 |
| **安全防护** | ✅ OWASP Top 10 覆盖 |
| **渲染预热** | ✅ 生产就绪 |
| **管理界面** | ✅ 现代化 UI |
| **部署方式** | ✅ 一键脚本部署 |
| **文档完整度** | 📝 持续完善中 |
| **社区活跃度** | 🌱 早期发展阶段 |

---

**Prerender Shield** - 让前后端分离网站既安全又 SEO 友好！

**最后更新**：2026年1月8日  
**版本**：v1.0.1  
**许可证**：MIT License  
**项目状态**：生产就绪，欢迎试用和贡献