CannaMuffinMan/FCGBDS
GitHub: CannaMuffinMan/FCGBDS
FCGBDS 是一个基于 TypeScript 和 Redis 的生产级 bot 防御中间件，通过多维信号评分在边缘或 API 层对自动化流量进行检测、质询和阻断。
Stars: 0 | Forks: 0
# FCGBDS (Forever Couch Gang Bot Defense System)
FCGBDS 是一个可以在您自己的系统中运行的生产级 bot 防御技术栈。
本仓库现在包含完整的客户运行时模块、middleware 逻辑以及带有安全占位符默认值的 Cloudflare Worker 测试客户端。
License: MIT。
Price: 免费。
## 从这里开始
1. 系统深度解析: `explanative`
2. MSCB bridge 深度解析: `MSCB_EXPLANATIVE.md`
3. 贡献指南: `CONTRIBUTING.md`
4. 推广代码片段: `PROMOTION_KIT.md`
5. 基准测试文档: `scripts/benchmark/README.md`
6. 只读 demo: `demo/read-only-dashboard.html`
## 来自作者的自愿请求
如果 FCGBDS 对您的平台有所帮助，我们请求您能做到以下其中一点：
这仅仅是一个请求，而不是法律要求。法律条款遵循 MIT 协议。
## 包含内容
1. 位于 `src/` 中的完整 TypeScript 运行时模块：
- `botDefense.ts`
- `index.ts`
- `telemetryManager.ts`
- `updateManager.ts`
- `dashboard.ts`
- `licenseManager.ts`（开源兼容垫片，无付费 license）
2. 位于 `botDefenseRedis.ts` 的 Redis 状态管理器参考。
3. 位于 `cloudflare-workers/` 的 Cloudflare Worker 示例。
4. Docker、部署脚本以及用于快速推出的 `.env.example`。
## 高层架构
FCGBDS 使用分层评分和阈值来决定是允许、质询还是阻止传入的流量。
主要信号族：
1. IP 命中窗口。
2. 设备指纹命中窗口。
3. Payload 重复窗口。
4. Header 和浏览器一致性检查。
5. Host 不匹配检查。
6. Honeypot 字段检测。
状态可以在内存中运行，也可以由 Redis 支持以实现水平扩展。
```
flowchart LR
U[Client Request] --> E[Edge/API Entry]
E --> M[FCGBDS Middleware]
M --> S1[IP Window Signal]
M --> S2[Device Fingerprint Signal]
M --> S3[Payload Repetition Signal]
M --> S4[Header and Browser Trust Signal]
M --> S5[Host Mismatch Signal]
M --> S6[Honeypot Signal]
S1 --> R[Risk Score Aggregation]
S2 --> R
S3 --> R
S4 --> R
S5 --> R
S6 --> R
R --> D{Decision Thresholds}
D -->|Allow| A[Route Handler]
D -->|Challenge| C[429 Challenge Response]
D -->|Block| B[403 Block Response]
M <-->|Shared Counters| X[(Redis)]
M -.fallback.-> L[(Local Memory)]
M --> T[Telemetry and Dashboard]
```
## 快速开始
### 1) 安装依赖
```
npm install
```
### 2) 配置环境
```
cp .env.example .env
```
在 `.env` 中设置占位符的值：
- `FCG_API_BASE_URL=https://PLACEHOLDER_API_BASE_URL`
- `BOT_DEFENSE_EXPECTED_HOSTNAME=api.yourdomain.com`
- `REDIS_URL=redis://localhost:6379`（可选，但推荐）
### 3) 在开发环境中运行
```
npm run dev
```
### 4) 构建并在生产环境中运行
```
npm run build
npm start
```
### 5) Docker 选项
```
docker-compose up -d
```
## 如何将 FCGBDS 集成到您现有的 API 中
### 选项 A：将 FCGBDS 作为您的主要边缘 API middleware 运行
1. 使用 `src/index.ts` 作为您的入口点。
2. 将 `BOT_DEFENSE_PATHS` 设置为您想要保护的路由。
3. 在业务逻辑之前，让受保护的流量通过 FCGBDS middleware。
### 选项 B：将 middleware 嵌入到现有的 Express API 中
1. 从 `src/botDefense.ts` 导入 `createBotDefenseMiddleware`。
2. 使用您的阈值进行初始化。
3. 在敏感路由之前使用 `app.use(botDefense.middleware)`。
### 选项 C：跨多个 API pod 共享防御状态
1. 使用 Redis (`REDIS_URL`) 以便共享计数器。
2. 保持您的 pod 为无状态。
3. 根据路由配置调整窗口和阈值。
## 用于测试和模拟的 Cloudflare Workers
`cloudflare-workers/` 目录包含您可以快速部署的 worker 副本。
所有特定于环境的 hostname 都已替换为占位符。
每个 worker 的典型设置：
1. 进入 worker 文件夹。
2. 更新 `wrangler.toml` 中的占位符。
3. 使用 Wrangler 进行部署。
占位符示例：
- `TARGET_API = "https://PLACEHOLDER_API_BASE_URL"`
- `ALLOWED_TARGET_HOSTS = "PLACEHOLDER_API_HOST,PLACEHOLDER_SECONDARY_API_HOST"`
## 平台集成示例
1. Express 示例: `examples/express-integration.md`
2. Fastify 示例: `examples/fastify-integration.md`
3. Twitch webhook 集成说明: `examples/platforms/twitch-webhook-integration.md`
4. Kick 集成说明: `examples/platforms/kick-webhook-integration.md`
5. MSCB 后端插件快速入门: `examples/mscb-backend-plug-in.md`
## 基准测试和性能报告
使用内置的基准测试脚本来生成数据，以便您可以在可重现的测试条件下发布这些数据。
1. 快速运行：
```
npm run benchmark:quick
```
2. 自定义运行：
```
npm run benchmark -- --url http://127.0.0.1:3001/api/auth/login --connections 50 --duration 30 --method POST
```
3. 完整基准测试指南：
- `scripts/benchmark/README.md`
本仓库中没有硬编码任何静态的 RPS 或延迟声明。请在发布您自己测量的结果时附上命令 + 环境详情。
## 前/后对比展示工作流
为了确保直播的可信度和可审计性，请发布匿名化的前/后指标快照：
1. 使用您的数据更新 `demo/sample-metrics.json`。
2. 打开 `demo/read-only-dashboard.html` 以可视化对比结果。
3. 在您的发布说明中分享截图 + 基准测试命令。
## 占位符安全
本仓库有意使用占位符替换内部基础设施值：
1. `PLACEHOLDER_API_BASE_URL`
2. `PLACEHOLDER_API_HOST`
3. `PLACEHOLDER_APP_HOST`
4. `PLACEHOLDER_WEB_HOST`
5. `PLACEHOLDER_SECONDARY_API_HOST`
6. `PLACEHOLDER_TERTIARY_API_HOST`
在部署之前，请将这些内容替换为您自己的值。
## 可见性检查清单
1. 将 GitHub topics 添加到此仓库：
- bot-detection
- rate-limiting
- anti-cheat
- cloudflare
- redis
- typescript
2. 使用 `PROMOTION_KIT.md` 制作直播覆盖层和社交帖子。
3. 将来自 `demo/read-only-dashboard.html` 的只读指标截图添加到您的仓库主页或帖子中。
## 安全和运营说明
1. 不要记录原始的用户机密。
2. 尽量减少对请求体（request body）的记录，并将其涂黑隐藏。
3. 仅使用 HTTPS。
4. 定期轮换 token 和共享机密。
5. 从保守的阈值开始，然后根据实时指标进行调整。
## 仓库结构
```
.
├─ src/
├─ cloudflare-workers/
├─ examples/
├─ scripts/benchmark/
├─ demo/
├─ botDefenseRedis.ts
├─ .env.example
├─ docker-compose.yml
├─ Dockerfile
├─ CONTRIBUTING.md
├─ PROMOTION_KIT.md
├─ deploy.sh
├─ deploy.bat
└─ explanative
```
标签：Redis, TypeScript, 反爬虫, 威胁情报, 安全插件, 开发者工具, 搜索引擎查询, 机器人拦截, 程序员工具, 自定义脚本, 请求拦截, 防御系统, 高对比度