## 📖 关于 **CMNW** 是一个基于 NestJS 的复杂微服务平台，专注于《魔兽世界》的 **开源情报 (OSINT)** 和 **数据市场分析 (DMA)**。该平台建立在由 13 个微服务和 7 个共享库组成的分布式架构之上，CMNW 利用基于 XVA 的定价模型提供全面的情报收集、实时市场分析和高级金融估值。 ### 🎯 关键特性 - 🕵️ **高级 OSINT 能力**: 通过 Battle.net API 集成，全面的角色和公会情报收集 - 📊 **实时市场分析**: 拍卖行监控，包含历史价格追踪和趋势检测 - 💰 **XVA 金融估值**: 具有风险评估和投资组合分析的复杂定价引擎 - 🔄 **分布式任务处理**: 基于 BullMQ 的消息队列，支持 Redis、优先级队列和重试机制 - 🐳 **云原生架构**: 完整的 Docker 容器化，支持多平台 (ARM64 & x64) - 🔒 **企业级认证**: 通过 Passport 集成 Battle.net OAuth 和 Discord OAuth - 📈 **监控与可观测性**: Prometheus 指标、Loki 日志和 Bull Board 队列监控 - 🧪 **全面测试**: Jest 单元测试、Playwright E2E 测试和丰富的模拟数据 ## 🏗️ 架构 ### 🧩 微服务 CMNW 作为 **pnpm monorepo** 运行，包含 13 个专门的微服务： | Service | Port | Description | Key Features | | -------------------- | ---- | -------------------------- | --------------------------------------------------------------- | | 🎯 **Core** | 3000 | 中央管理服务 | Realms & Keys 管理, 身份验证, 系统配置 | | 🌐 **API Gateway** | 8080 | REST API 网关 | 请求路由, Swagger 文档位于 `/api/docs`, 速率限制 | | 🕵️ **OSINT** | 3000 | 情报收集 | 3 个 workers (characters, guilds, profile), Battle.net 集成 | | 📊 **DMA** | 3004 | 数据市场分析 | 2 个 workers (auctions, items), 实时 AH 监控 | | 💰 **Market** | 3002 | 市场操作 | XVA 计算, 合约, 金币追踪, 估值 | | 👤 **Characters** | - | 角色管理 | 玩家档案, 统计追踪, 实体索引 | | 🏰 **Guilds** | - | 公会分析 | 成员追踪, 名册管理, 活动日志 | | 📈 **Analytics** | - | 指标聚合 | 角色/公会/市场/合约指标服务 | | 🏆 **Ladder** | - | 排名系统 | 竞争排名, 排行榜 | | 🧪 **Tests** | - | 测试基础设施 | E2E 测试, 模拟数据, 基准测试 | | 📊 **Warcraft Logs** | - | 团队副本分析 | 战斗日志解析, 性能指标 | | 🌍 **WoW Progress** | - | 进度追踪 | 公会进程, 团队副本完成追踪 | | 💎 **Valuations** | - | 财务建模 | XVA 计算, 风险评估, 投资组合分析 | ### 📚 共享库 7 个共享库为微服务提供通用功能： - **[@app/configuration](libs/configuration)** - 集中配置管理 - **[@app/logger](libs/logger)** - 集成 Loki 的结构化日志 - **[@app/pg](libs/pg)** - PostgreSQL 连接和 TypeORM 工具 - **[@app/mongo](libs/mongo)** - MongoDB 连接和 Mongoose 模式 - **[@app/resources](libs/resources)** - 共享资源和常量 - **[@app/bullmq](libs/bullmq)** - 基于 Redis 的 BullMQ 任务队列模式 - **[@app/s3](libs/s3)** - AWS S3 存储集成 ## 🛠️ 技术栈 ### 🎯 后端框架 - **[NestJS](https://nestjs.com)** 11.1.9 - 渐进式 Node.js 框架 - **TypeScript** 5.9.3 - 类型安全的 JavaScript 开发 - **Node.js** >=24.0.0 - JavaScript 运行时 - **RxJS** 7.8.2 - 响应式编程与 observables ### 🗄️ 数据层 - **PostgreSQL** 17.4 - 主关系数据库，使用 SnakeNamingStrategy - **MongoDB** - 文档存储，使用 Mongoose 9.0.1 - **Redis** 7.4.3 - 内存缓存和会话存储 - **TypeORM** 0.3.28 - 支持迁移的数据库 ORM ### 🔄 消息队列 - **BullMQ** 5.66.0 - 基于 Redis 的任务队列，支持优先级和重试机制 - **Bull Board** 6.15.0 - 队列监控仪表板 ### 🔌 外部集成 - **[@alexzedim/blizzapi](https://www.npmjs.com/package/@alexzedim/blizzapi)** 2.7.0 - Battle.net API 客户端 - **Warcraft Logs API** - 战斗日志分析 - **Raider.IO API** - 大秘境和团队副本进度 - **AWS S3** - 对象存储，使用 @aws-sdk/client-s3@3.948.0 ### 🔐 认证与安全 - **Passport** 0.7.0 - 认证中间件 - **Battle.net OAuth** - 暴雪认证 - **Discord OAuth** - 通过 passport-discord@0.1.4 集成 Discord ### 🐳 DevOps 与部署 - **Docker** - 支持多平台构建的容器化 - **GitHub Actions** - 使用自托管 runners 的 CI/CD 流水线 - **pnpm** 10.28.1 - 快速、节省磁盘空间的包管理器 ### 🔧 开发工具 - **Jest** 30.2.0 - 具有全面覆盖率的测试框架 - **Playwright** 1.57.0 - 端到端测试自动化 - **ESLint & Prettier** - 代码质量和格式化 - **Swagger/OpenAPI** - API 文档，使用 @nestjs/swagger@11.2.3 ### 📊 监控与可观测性 - **Prometheus** - 指标收集，使用 @willsoto/nestjs-prometheus@6.0.2 - **Loki** - 日志聚合 - **Bull Board** - 队列监控和管理 ## 🚀 快速开始 ### 前置条件 - **Node.js** >=24.0.0 - **pnpm** >=10.0.0 (通过 corepack 管理) - **Docker** & **Docker Compose** - **PostgreSQL** 17+ - **MongoDB** (最新版) - **Redis** 7.4+ ### 🔧 安装 ``` # 克隆仓库 git clone https://github.com/alexzedim/cmnw.git cd cmnw # 启用 corepack 进行 pnpm 版本管理 corepack enable # 安装依赖 pnpm install # 复制环境配置 cp .env.example .env cp .env.docker.example .env.docker ``` ### 🐳 Docker 开发环境设置 使用 Docker Compose 启动基础设施服务和微服务： ``` # 启动数据库服务 (PostgreSQL, MongoDB, Redis) docker-compose -f docker-compose.db.yml up -d # 启动核心服务 docker-compose -f docker-compose.core.yml up -d # 启动 OSINT 服务 docker-compose -f docker-compose.osint.yml up -d # 启动 DMA 服务 docker-compose -f docker-compose.dma.yml up -d # 启动分析服务 docker-compose -f docker-compose.analytics.yml up -d # 或者启动所有开发服务 docker-compose -f docker-compose.dev.yml up -d ``` ### 🛠️ 本地开发 ``` # 构建所有微服务 pnpm build:all # 启动开发服务器 (watch 模式) pnpm start:dev # 运行特定微服务 nest start core --watch nest start api --watch nest start osint --watch nest start dma --watch nest start market --watch # 以 debug 模式启动 pnpm start:debug ``` ### 🌐 访问点 启动服务后： - **API Gateway**: http://localhost:8080 - **Swagger 文档**: http://localhost:8080/api/docs - **Bull Board**: http://localhost:8080/queues - **Core Service**: http://localhost:3000 - **Market Service**: http://localhost:3002 - **DMA Service**: http://localhost:3004 ## 💼 核心模块 ### 🕵️ OSINT (开源情报) 通过 Battle.net API 集成，全面收集角色和公会情报： **架构：** - **3 个专用 Workers**: [`characters.worker.ts`](apps/osint/src/workers/characters.worker.ts), [`guilds.worker.ts`](apps/osint/src/workers/guilds.worker.ts), [`profile.worker.ts`](apps/osint/src/workers/profile.worker.ts) - **BullMQ 集成**: 带 Redis 和重试机制的优先级队列 - **实时更新**: 角色生命周期追踪和实体索引 **关键特性：** - **角色分析**: 玩家档案、装备、成就、专业 - **公会监控**: 通过 [`guild-member.service.ts`](apps/osint/src/services/guild-member.service.ts) 进行成员追踪、名册管理、活动日志 - **副本进度**: Warcraft Logs 和 Raider.IO 集成 - **收藏系统**: 通过 [`character-collection.service.ts`](apps/osint/src/services/character-collection.service.ts) 管理角色收藏 **服务：** - [`character.service.ts`](apps/osint/src/services/character.service.ts) - 角色数据处理 - [`guild.service.ts`](apps/osint/src/services/guild.service.ts) - 公会数据聚合 - [`character-lifecycle.service.ts`](apps/osint/src/services/character-lifecycle.service.ts) - 生命周期管理 - [`guild-roster.service.ts`](apps/osint/src/services/guild-roster.service.ts) - 名册同步 ### 📊 DMA (数据市场分析) 实时拍卖行监控和市场情报： **架构：** - **2 个专用 Workers**: [`auctions.worker.ts`](apps/dma/src/workers/auctions.worker.ts), [`items.worker.ts`](apps/dma/src/workers/items.worker.ts) - **高频更新**: 实时拍卖行快照 - **历史分析**: 价格趋势检测和预测 **关键特性：** - **价格追踪**: 带技术指标的历史价格分析 - **市场图表**: 交互式价格可视化 - **跨服分析**: 服务器人口和定价比较 - **商品监控**: 服务器范围的商品价格追踪 - **物品情报**: 物品元数据和定价计算 ### 💰 市场与估值引擎 使用 XVA (X-Value Adjustments) 计算的高级财务建模： **服务：** - [`xva.service.ts`](apps/market/src/services/xva.service.ts) - XVA 计算引擎 - [`contracts.service.ts`](apps/market/src/services/contracts.service.ts) - 合约管理 - [`gold.service.ts`](apps/market/src/services/gold.service.ts) - 金币价格追踪 - [`evaluation.service.ts`](apps/market/src/services/evaluation.service.ts) - 资产评估 - [`auctions.service.ts`](apps/market/src/services/auctions.service.ts) - 拍卖处理 - [`items.service.ts`](apps/market/src/services/items.service.ts) - 物品估值 **关键特性：** - **风险评估**: 信用、资金和资本价值调整 - **价格发现**: 基于市场状况的动态定价 - **投资组合分析**: 多资产风险和回报分析 - **制造业经济**: 通过 [`disenchanting.libs.ts`](apps/market/src/libs/disenchanting.libs.ts), [`milling.libs.ts`](apps/market/src/libs/milling.libs.ts), [`prospecting.libs.ts`](apps/market/src/libs/prospecting.libs.ts) 计算分解、研磨、选矿 ### 📈 分析与监控 综合指标聚合和监控： **服务：** - [`character-metrics.service.ts`](apps/analytics/src/services/character-metrics.service.ts) - 角色分析 - [`guild-metrics.service.ts`](apps/analytics/src/services/guild-metrics.service.ts) - 公会分析 - [`market-metrics.service.ts`](apps/analytics/src/services/market-metrics.service.ts) - 市场分析 - [`contract-metrics.service.ts`](apps/analytics/src/services/contract-metrics.service.ts) - 合约分析 **监控：** - **Prometheus 指标**: 自定义指标收集 - **队列监控**: 位于 `/queues` 的 Bull Board 仪表板 - **Worker 统计**: 通过 [`worker-stats.listener.ts`](apps/osint/src/listeners/worker-stats.listener.ts) 进行实时 Worker 性能追踪 ## 🧪 测试 ### 🎯 测试套件 使用 **[Jest](https://jestjs.io)** 30.2.0 和 **[Playwright](https://playwright.dev)** 1.57.0 的全面测试基础设施： ``` # 运行所有测试 pnpm test # 运行测试并生成覆盖率 pnpm test:cov # 在 watch 模式下运行测试 pnpm test:watch # 运行测试并进行调试 pnpm test:debug ``` ### 📋 测试覆盖 包含模拟数据的广泛测试套件： - 🕵️ 带有 **[模拟数据](apps/tests/mocks/osint.mock.ts)** 的 **[OSINT 测试](apps/tests/test/tests.osint.spec.ts)** - 📊 带有 **[模拟数据](apps/tests/mocks/dma.mock.ts)** 的 **[DMA 测试](apps/tests/test/tests.dma.spec.ts)** - 🎯 核心服务的 **[Core 测试](apps/tests/test/tests.core.spec.ts)** - 🌐 社交功能的 **[Community 测试](apps/tests/test/tests.community.spec.ts)** - 🔄 带有 **[模拟数据](apps/tests/mocks/worker.mock.ts)** 的 **[Worker 测试](apps/tests/test/tests.worker.spec.ts)** ### 🧪 测试服务 专用的测试微服务包含： - **[基准测试套件](apps/tests/src/tests.bench.ts)** - 性能基准测试 - **[队列测试](apps/tests/src/tests.characters.queue.service.ts)** - BullMQ 队列测试 - **Worker 测试](apps/tests/src/tests.worker.ts)** - Worker 性能测试 ## 🚀 部署 ### 🔄 CI/CD 流水线 通过带有自托管 runners 的 **GitHub Actions** 进行自动部署： **工作流：** - ✅ Docker 镜像构建 (ARM64 & x64) - ✅ 自动化测试 (Jest + Playwright) - ✅ 安全扫描 - ✅ 多环境部署 - ✅ 容器镜像仓库发布 ### 🐳 生产环境部署 **1. 环境设置：** ``` # 配置生产环境 cp .env.production .env # 设置部署 secrets export ENC_PASSWORD="your_encryption_key" export BNET_CLIENT_ID="your_client_id" export BNET_CLIENT_SECRET="your_client_secret" ``` **2. 容器镜像仓库：** ``` # 构建多平台镜像 docker buildx build --platform linux/amd64,linux/arm64 \ -t ghcr.io/alexzedim/cmnw:6.10.9 \ -t ghcr.io/alexzedim/cmnw:latest \ --push . # 在生产服务器上拉取镜像 docker pull ghcr.io/alexzedim/cmnw:latest ``` **3. 服务编排：** ``` # 部署基础设施 docker-compose -f docker-compose.db.yml up -d # 部署核心服务 docker-compose -f docker-compose.core.yml up -d # 部署 OSINT 服务 docker-compose -f docker-compose.osint.yml up -d # 部署 DMA 服务 docker-compose -f docker-compose.dma.yml up -d # 部署分析服务 docker-compose -f docker-compose.analytics.yml up -d ``` **4. 健康检查：** ``` # 验证服务健康状态 curl http://localhost:8080/health curl http://localhost:3000/health curl http://localhost:3002/health curl http://localhost:3004/health ``` ## 📚 API 文档 ### 🌐 REST API 端点 **API Gateway** (端口 8080) 提供全面的 REST API 访问： **OSINT 端点：** - `GET /osint/character/:realm/:name` - 角色情报 - `GET /osint/guild/:realm/:name` - 公会情报 - `GET /osint/realm/:slug` - 服务器信息 **DMA 端点：** - `GET /dma/auctions/:connectedRealmId` - 拍卖行数据 - `GET /dma/items/:itemId` - 物品市场数据 - `GET /dma/commodities` - 商品价格 **市场端点：** - `GET /market/contracts` - 活跃合约 - `GET /market/gold/:region` - 金币价格 - `GET /market/evaluation/:itemId` - 物品评估 **队列监控：** - `GET /queues` - Bull Board 仪表板 - `GET /queue/metrics` - 队列指标 - `GET /queue/workers` - Worker 状态 ### 📖 交互式文档 **Swagger/OpenAPI** 文档位于： - **开发环境**: http://localhost:8080/api/docs - **生产环境**: https://api.cmnw.me/docs API 文档由 NestJS 装饰器自动生成，包含： - 📝 请求/响应模式 - 🔐 认证要求 - 🧪 交互式 API 测试 - 📊 模型定义 ## 🔧 开发工作流 ### 📦 包管理 ``` # 安装依赖 pnpm install # 向特定 workspace 添加依赖 pnpm add --filter @app/osint # 更新依赖 pnpm update # 清理安装 pnpm clean-install ``` ### 🏗️ 构建 ``` # 构建所有微服务 pnpm build:all # 构建特定服务 nest build core nest build api nest build osint nest build dma nest build market ``` ### 🔍 代码质量 ``` # Lint 并修复代码 pnpm lint # 格式化代码 pnpm format # Type checking tsc --noEmit ``` ### 🐛 调试 ``` # 启动并附带 debugger pnpm start:debug # 调试特定服务 nest start osint --debug --watch # 调试测试 pnpm test:debug ``` ## 📊 监控与可观测性 ### 📈 指标收集 **Prometheus 集成：** - 通过 [@willsoto/nestjs-prometheus](https://www.npmjs.com/package/@willsoto/nestjs-prometheus)@6.0.2 获取自定义指标 - 服务健康指标 - 队列性能指标 - 数据库连接池指标 **指标端点：** - `GET /metrics` - Prometheus 指标 - `GET /health` - 健康检查端点 ### 📝 日志记录 **结构化日志：** - 通过 [@app/logger](libs/logger) 进行集中日志记录 - 集成 Loki 进行日志聚合 - 带请求追踪的上下文日志 - 日志级别：error, warn, info, debug, verbose ### 🔍 队列监控 **Bull Board 仪表板：** - 位于 `/queues` 的实时队列监控 - 任务状态追踪 - 失败任务检查 - 队列指标和统计 - Worker 性能监控 ### 🎯 Worker 统计 实时 Worker 性能追踪： - 任务处理速率 - 成功/失败比率 - 平均处理时间 - 队列深度监控 ## 🤝 贡献 我们欢迎具备以下经验的开发者贡献： - 🎯 **微服务架构** - NestJS, 分布式系统 - 🕵️ **情报收集系统** - OSINT, 数据聚合 - 📊 **金融数据分析** - XVA 计算, 风险建模 - 🎮 **游戏 API 集成** - Battle.net, Warcraft Logs, Raider.IO - 🔒 **安全与认证** - OAuth, JWT, API 安全 - 🐳 **DevOps 与基础设施** - Docker, Kubernetes, CI/CD ### 📋 如何贡献 1. **Fork** 仓库 2. **创建** 特性分支 (`git checkout -b feature/amazing-feature`) 3. **提交** 更改 (`git commit -m 'Add amazing feature'`) 4. **推送** 到分支 (`git push origin feature/amazing-feature`) 5. **开启** Pull Request ### 🐛 问题与功能请求 - 🐛 **Bug 报告**: [创建 Issue](https://github.com/alexzedim/cmnw/issues) - 💡 **功能请求**: [发起讨论](https://github.com/alexzedim/cmnw/discussions) - 📖 **文档**: 帮助改进我们的文档 - 🧪 **测试**: 扩大测试覆盖率 ### 📝 开发准则 - 遵循 TypeScript 最佳实践 - 为新功能编写全面的测试 - 更新 API 更改的文档 - 使用约定式提交信息 - 提交 PR 前确保所有测试通过 ## 📄 许可证 本项目采用 **Mozilla Public License 2.0** 授权 - 详情请参阅 [LICENSE](LICENSE) 文件。

🌟 由 @alexzedim 用 ❤️ 构建

🌐 网站 • 🐛 问题 • 💬 讨论 • 🐦 Twitter

"智慧总能致胜" 🎯

标签：BullMQ, Docker, ESC4, GitHub, MongoDB, NestJS, OSINT, PostgreSQL, Redis, REST API, TypeScript, World of Warcraft, 代码示例, 分布式系统, 命令控制, 响应大小分析, 安全插件, 安全防御评估, 密码管理, 市场分析, 微服务架构, 情报平台, 搜索引擎查询, 数据分析, 数据采集, 测试用例, 游戏经济, 特征检测, 自动化攻击, 自定义请求头, 请求拦截, 金融估值, 魔兽世界