mythic3011/trustpilot-review-osint-pipeline

# trustpilot-review-osint-pipeline [](https://www.typescriptlang.org/) [](https://nodejs.org/) [](https://opensource.org/licenses/ISC) ## 功能 - **自动化提取** - 从 Trustpilot 公司页面抓取评论 - **CSV 导出** - UTF-8 编码输出，用于下游分析 - **分页处理** - 自动浏览多个评论页面 - **速率限制** - 可配置的延迟和指数退避 - **浏览器自动化** - 基于 Playwright 执行，适用于 JS 渲染的页面 - **日志和错误处理** - 进度记录和重试行为 - **基于属性的测试** - 对核心行为进行额外验证 - **手动登录支持** - 可选的有头模式用于身份验证 ## 目录 - [快速开始](#-quick-start) - [安装](#-installation) - [使用说明](#-usage) - [输出格式](#-output-format) - [速率限制](#-rate-limiting--ethical-scraping) - [测试](#-testing) - [故障排除](#-troubleshooting) - [项目结构](#-project-structure) - [贡献指南](#-contributing) ## 快速开始 ``` # 安装依赖 npm install # 安装 Playwright 浏览器 npx playwright install chromium # 运行 scraper npm start -- --url https://www.trustpilot.com/review/ouraring.com ``` ## 安装 ### 前置条件 - **Node.js** 18 或更高版本 - **npm** 或 **yarn** 包管理器 - 足够的磁盘空间用于 CSV 输出 ### 设置 1. **克隆仓库** ``` git clone https://github.com/mythic3011/trustpilot-review-osint-pipeline.git cd trustpilot-review-osint-pipeline ``` 2. **安装依赖** ``` npm install ``` 3. **安装 Playwright 浏览器** ``` npx playwright install chromium ``` 这将下载 headless 自动化所需的 Chromium 浏览器二进制文件（约 100MB）。 ## 使用说明 ### 基本用法 ``` npm start -- --url https://www.trustpilot.com/review/example.com ``` ### 开发模式 直接使用 TypeScript 运行（无需构建步骤）： ``` npm run dev -- --url https://www.trustpilot.com/review/example.com ``` ### 命令行选项 #### 必需项 | 选项 | 描述 | 示例 | | ------------- | ----------------------------- | ----------------------------------------------------- | | `--url ` | Trustpilot 公司评论 URL | `--url https://www.trustpilot.com/review/example.com` | #### 可选项 | 选项 | 描述 | 默认值 | 示例 | | ----------------------- | ------------------------------- | ------------- | ------------------------------- | | `--output ` | 输出的 CSV 文件名 | `reviews.csv` | `--output company-reviews.csv` | | `--max-pages ` | 要抓取的最大页数 | 无限制 | `--max-pages 10` | | `--delay ` | 请求之间的延迟（最小：1000ms） | `2000` | `--delay 5000` | | `--user-agent ` | 自定义 user agent | Chrome UA | `--user-agent "Mozilla/5.0..."` | | `--headed` | 显示浏览器窗口 | `false` | `--headed` | | `--wait-for-login` | 暂停以进行手动登录 | `false` | `--wait-for-login` | ### 使用示例 #### 抓取前 5 页 ``` npm start -- --url https://www.trustpilot.com/review/example.com --max-pages 5 ``` #### 慢速自定义输出 ``` npm start -- \ --url https://www.trustpilot.com/review/example.com \ --output example-reviews.csv \ --delay 5000 ``` #### 手动登录（有头模式） ``` npm start -- --url https://www.trustpilot.com/review/example.com --headed ``` 这将： 1. 打开一个可见的浏览器窗口 2. 导航到 URL 3. 暂停并等待您按回车键（ENTER） 4. 允许手动登录或交互 5. 在您按回车键后开始抓取 #### 完整示例 ``` npm start -- \ --url https://www.trustpilot.com/review/ouraring.com \ --output oura-reviews.csv \ --max-pages 100 \ --delay 3000 ``` ## 输出格式 ### CSV 结构 | 列名 | 类型 | 描述 | 示例 | | ------------- | ------- | -------------------- | -------------------------------------- | | `rating` | number | 星级评分 (1-5) | `5` | | `text` | string | 评论内容 | `"Great product! Highly recommend..."` | | `date` | string | 评论日期 (ISO 8601) | `2024-01-15` | | `reviewerName`| string | 评论者姓名 | `John Smith` | | `title` | string | 评论标题 | `"Excellent service"` | | `verified` | boolean | 是否验证购买 | `true` | ### 输出示例 ``` rating,text,date,reviewerName,title,verified 5,"Great product! Highly recommend to anyone.","2024-01-15","John Smith","Excellent service",true 4,"Good overall, shipping took longer.","2024-01-14","Jane Doe","Pretty good",false 5,"Amazing support. Quick resolution.","2024-01-13","Bob Johnson","Outstanding",true ``` ### 特殊字符处理 CSV 导出器负责处理： - 文本中的**逗号**（字段加引号） - 文本中的**引号**（使用双引号转义） - 评论中的**换行符**（保留在加引号的字段中） - **国际字符**（UTF-8 编码） - **表情符号**和特殊符号 ## 速率限制与道德抓取 ### 为什么这很重要 负责任的网络抓取可以防止： - 服务器过载 - IP 封禁 - 违反服务条款 - 降低其他用户的服务质量 ### 内置保护机制 1. **可配置的延迟** - 请求之间默认延迟 2 秒（最小 1 秒） 2. **指数退避** - 增加延迟自动重试（1秒 → 2秒 → 4秒） 3. **429 处理** - 遵守 `retry-after` 标头 4. **逼真的 User Agent** - 类似浏览器的身份标识 5. **请求日志** - 完整的审计追踪 ### 最佳实践 **建议：** - 使用合理的延迟（2-5 秒） - 使用 `--max-pages` 限制页数 - 在非高峰时段抓取 - 检查 `robots.txt` 政策 - 审查 Trustpilot 的服务条款 - 分散抓取会话 **不要：** - 同时运行多个实例 - 抓取频率过高 - 忽略速率限制响应 - 未经许可用于商业目的 ### 法律考量 - 本工具仅供**教育和研究目的** - 用户有责任遵守相关法律和服务条款（ToS） - 在可用时考虑使用官方 API - 尊重知识产权和隐私权 ## 测试 ### 运行测试 ``` # 所有测试 npm test # Watch 模式 npm run test:watch # 特定 suites npm run test:unit # Unit tests npm run test:property # Property-based tests npm run test:integration # Integration tests ``` ### 测试策略 **单元测试** - 验证特定示例和边缘情况 - 输入验证 - 错误处理 - 数据转换 - CSV 格式化 **基于属性的测试** - 验证普遍属性 - URL 验证正确性 - 所有输入的 CSV 转义 - 速率限制器时间保证 - 数据转换器一致性 **集成测试** - 端到端工作流 - 完整的抓取 pipeline - 模拟的 Trustpilot 页面 - 错误恢复场景 ### 测试覆盖率 该项目使用 **fast-check** 进行基于属性的测试： - 随机输入生成 - 自动发现边缘情况 - 广泛的输入空间覆盖 - 缩减至最小的失败示例 ## 故障排除 ### 找不到浏览器 **错误：** `browserType.launch: Executable doesn't exist` **解决方案：** ``` npx playwright install chromium ``` ### 验证码（CAPTCHA）检测 **症状：** 抓取工具因 CAPTCHA 提示终止 **解决方案：** - 增加延迟：`--delay 5000` - 避免频繁抓取 - 重试前等待一段时间 - 更换网络环境 ### 未提取到评论 **症状：** CSV 文件为空 **解决方案：** 1. 确认 URL 正确 2. 检查浏览器中该页面是否有评论 3. 尝试更长的延迟：`--delay 5000` 4. 检查 HTML 结构是否发生变化 ### 无效的 URL 错误 **错误：** `Invalid Trustpilot URL format` **有效格式：** - 有效：`https://www.trustpilot.com/review/example.com` - 有效：`https://www.trustpilot.com/review/my-company` - 无效：`https://trustpilot.com/review/example.com`（缺少 www） - 无效：`https://www.trustpilot.com/categories/electronics`（非评论页面） ### 网络超时 **错误：** `Navigation timeout exceeded` **解决方案：** - 检查网络连接 - 目标站点可能缓慢或不可用 - 稍后重试 - 使用稳定的网络 ### 权限被拒绝 **错误：** `EACCES: permission denied` **解决方案：** - 检查写入权限 - 指定不同的路径：`--output ~/Documents/reviews.csv` - 如果文件在 Excel 或其他程序中打开，请将其关闭 ### 速率限制 (429) **警告：** `Rate limit detected, waiting...` **行为：** 抓取工具会自动处理此问题： - 遵守 `retry-after` 标头 - 等待指定的时间 - 重试请求 **预防：** 增加 `--delay` 参数 ## 项目结构 ``` trustpilot-review-osint-pipeline/ ├── src/ # Source code │ ├── index.ts # Main entry point │ ├── cli.ts # CLI argument parsing │ ├── browser-controller.ts # Browser automation │ ├── page-navigator.ts # Pagination logic │ ├── content-extractor.ts # Review extraction │ ├── data-transformer.ts # Data normalization │ ├── csv-exporter.ts # CSV generation │ ├── rate-limiter.ts # Rate limiting │ ├── error-handler.ts # Error handling │ ├── logger.ts # Logging │ ├── url-validator.ts # URL validation │ └── config.ts # Configuration ├── tests/ │ ├── unit/ # Unit tests │ ├── property/ # Property-based tests │ └── integration/ # Integration tests ├── dist/ # Compiled output (generated) ├── tsconfig.json # TypeScript config ├── vitest.config.ts # Test config ├── package.json # Dependencies └── README.md # This file ``` ## 技术栈 - **[TypeScript](https://www.typescriptlang.org/)** - 类型安全和开发者体验 - **[Playwright](https://playwright.dev/)** - 浏览器自动化 - **[Vitest](https://vitest.dev/)** - 快速、现代的测试 - **[fast-check](https://fast-check.dev/)** - 基于属性的测试 - **[winston](https://github.com/winstonjs/winston)** - 日志框架 - **[commander](https://github.com/tj/commander.js)** - CLI 解析 - **[csv-writer](https://github.com/ryu1kn/csv-writer)** - CSV 生成 - **[date-fns](https://date-fns.org/)** - 日期实用工具 ## 架构 ### 设计原则 1. **关注点分离** - 每个模块都具有单一职责 2. **接口驱动** - 组件之间有明确的契约 3. **错误弹性** - 集中的错误处理和重试逻辑 4. **可测试性** - 模块化设计支持全面测试 5. **配置化** - 在启动时验证，在 runtime 不可变 ### 核心组件 - **浏览器控制器** - 管理 Playwright 浏览器生命周期 - **页面导航器** - 处理分页和页面加载 - **内容提取器** - 解析 HTML 并提取评论数据 - **数据转换器** - 规范化并验证提取的数据 - **CSV 导出器** - 生成格式正确的 CSV 文件 - **速率限制器** - 执行延迟并处理退避 - **错误处理器** - 分类错误并确定重试策略 ## 贡献指南 欢迎做出贡献！请遵循以下准则： ### 开发设置 ``` # Fork 并 clone 仓库 git clone https://github.com/mythic3011/trustpilot-review-osint-pipeline.git cd trustpilot-review-osint-pipeline # 安装依赖 npm install # 运行测试 npm test # Build 项目 npm run build ``` ### 贡献指南 1. **代码风格** - 遵循现有的 TypeScript 规范 2. **测试** - 为新功能添加单元测试和属性测试 3. **文档** - 针对面向用户的更改更新 README 4. **提交** - 使用清晰、具有描述性的提交信息 5. **道德** - 保持道德的抓取行为 ### Pull Request 流程 1. 创建功能分支：`git checkout -b feature/your-feature` 2. 连同测试一起进行更改 3. 确保所有测试通过：`npm test` 4. 根据需要更新文档 5. 提交具有清晰描述的 PR ## 许可证 ISC 许可证 - 有关详细信息，请参阅 [LICENSE](LICENSE) 文件 ## 免责声明 本工具仅供**教育和研究目的**提供。用户需全权负责确保其使用行为符合： - 适用的法律和法规 - Trustpilot 的服务条款 - 网站 robots.txt 政策 - 数据保护和隐私法 作者对滥用或因使用本软件而产生的任何后果**不承担任何责任**。 ## 致谢 - 使用 [Playwright](https://playwright.dev/) 构建，以实现可靠的浏览器自动化 - 基于属性的测试由 [fast-check](https://fast-check.dev/) 提供支持 - 灵感来源于道德的网络抓取最佳实践 ## 支持 - **问题**：[GitHub Issues](https://github.com/mythic3011/trustpilot-review-osint-pipeline/issues) - **文档**：查看 [USAGE_EXAMPLES.md](USAGE_EXAMPLES.md) 获取更多示例 - **仓库**：https://github.com/mythic3011/trustpilot-review-osint-pipeline

标签：ESC4, MITM代理, OSINT, Playwright, TypeScript, 命令控制, 安全插件, 数据采集, 特征检测, 网络调试, 自动化, 自动化攻击