气象MCP分析服务器

Weather MCP项目的隐私优先分析收集服务器。

概述

此服务器从Weather MCP服务器实例收集匿名使用分析，以帮助改进产品，同时严格保护用户隐私。它包括：

API服务：基于Fastify的REST API，用于接收分析事件和提供统计信息
工作进程：用于数据库写入和聚合的后台作业处理器
数据库：PostgreSQL和TimescaleDB用于高效的时间序列存储
队列：Redis用于缓冲和异步处理
监控：普罗米修斯指标+Grafana仪表板，用于操作可观察性

注：面向公众的分析仪表板单独托管在网站项目。此服务器提供网站使用的后端API。

建筑

MCP Servers → API Service → Redis Queue → Worker → PostgreSQL/TimescaleDB
       |          ↓                |                        ↓
       |    Prometheus ←───────────┘              Public Stats API
       |          ↓                                        ↓
       |      Grafana                              Website Dashboard
       |    (ops monitoring)                     (public analytics)
       └──────────────────────────────────────────────────┘

隐私原则

无个人身份信息收集：没有坐标、位置名称或用户标识符
无IP日志记录：应用程序配置为从不记录IP地址
仅匿名：所有数据都是真正匿名的，不能链接到用户
加入：MCP服务器中默认禁用分析
透明：所有集合代码都是开源的，可审计的

特性

API终点

POST /v1/events -事件摄入（速率限制：60/min）
GET /v1/health -健康检查
GET /v1/status -详细的系统状态
GET /v1/stats/overview -汇总统计
GET /v1/stats/tools -工具使用统计
GET /v1/stats/tool/:toolName -特定工具统计数据
GET /v1/stats/errors -错误统计
GET /v1/stats/performance -性能指标
GET /metrics -普罗米修斯指标

运行监测

普罗米修斯 用于指标收集（保留30天）
格拉法纳 对于操作仪表板（包括3个仪表板）：

- API运行状况（请求率、错误、响应时间） - Worker&Queue（队列深度、处理统计数据、错误） - 数据库和基础架构（查询性能、连接、资源）

警报管理器 用于通知（电子邮件、Slack）
15+警报规则 跨越6个组（API、队列、工作者、数据库、资源、数据新鲜度）
自动刷新仪表板（间隔10秒）

技术栈

运行时：Node.js 20 LTS
框架：禁食
数据库：PostgreSQL 16+时间尺度数据库2.x
队列：Redis 7
监控：普罗米修斯+格拉法纳+警报经理
容器：Docker+Docker组合
反向代理：Nginx（生产）
日志记录：Pino（结构化JSON日志）

Docker快速入门

1.克隆和配置

# Clone the repository
git clone https://github.com/weather-mcp/analytics-server.git
cd analytics-server

# Create environment file
cp .env.example .env
nano .env  # Edit configuration

2.启动所有服务

# Build and start all services
docker-compose up -d

# Check logs
docker-compose logs -f

# Verify health
curl http://localhost:3000/v1/health

3.接入服务

API: http://localhost:3000
API健康: http://localhost:3000/v1/health
普罗米修斯: http://localhost:9090
格拉法纳: http://localhost:3001（管理员/管理员）
警报管理器: http://localhost:9093

开发设置

先决条件

Node.js 20+
Docker和Docker Compose
PostgreSQL 16与TimescaleDB（或使用Docker）
Redis 7（或使用Docker）

1.安装依赖项

# Install API server dependencies
npm install

# Install dashboard dependencies
cd dashboard
npm install
cd ..

2.启动基础设施

# Start PostgreSQL and Redis only
docker-compose up -d postgres redis

# Wait for services to be ready
./scripts/start-dev.sh

3.初始化数据库

# Run database initialization
./scripts/init-db.sh

# Or manually:
npm run build
node dist/database/migrations.js

4.启动开发服务器

# Terminal 1: API Server (with hot reload)
npm run dev

# Terminal 2: Worker Process (with hot reload)
npm run dev:worker

# Terminal 3: Dashboard (with hot reload)
cd dashboard
npm run dev

5.运行测试

# Run all tests
npm test

# Run specific test suites
npm run test:unit
npm run test:integration

# Generate coverage report
npm run test:coverage

配置

所有配置都是通过环境变量完成的。看 .env.example 所有可用选项。

关键配置选项

# Server
NODE_ENV=production
PORT=3000
LOG_LEVEL=info

# Database
DB_HOST=localhost
DB_PORT=5432
DB_NAME=analytics
DB_USER=analytics
DB_PASSWORD=your-secure-password

# Redis
REDIS_HOST=localhost
REDIS_PORT=6379

# API
RATE_LIMIT_PER_MINUTE=60
MAX_BATCH_SIZE=100
API_BODY_LIMIT_KB=100

# Security
TRUST_PROXY=true
CORS_ORIGIN=*

API使用

事件摄入

curl -X POST http://localhost:3000/v1/events \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "version": "1.0.0",
        "tool": "get_forecast",
        "status": "success",
        "timestamp_hour": "2025-11-12T20:00:00Z",
        "analytics_level": "standard",
        "response_time_ms": 150,
        "service": "noaa",
        "cache_hit": true,
        "country": "US"
      }
    ]
  }'

获取统计信息

# Overview
curl http://localhost:3000/v1/stats/overview?period=30d

# Tool stats
curl http://localhost:3000/v1/stats/tools?period=7d

# Performance
curl http://localhost:3000/v1/stats/performance?period=90d

项目结构

analytics-server/
├── src/
│   ├── api/              # Fastify API server
│   │   ├── index.ts      # Main server with routes
│   │   ├── stats.ts      # Stats query functions
│   │   └── validation.ts # Event validation
│   ├── worker/           # Event processing worker
│   │   └── index.ts      # Worker main loop
│   ├── database/         # PostgreSQL interactions
│   │   ├── index.ts      # Connection pool & queries
│   │   └── migrations.ts # Database migrations
│   ├── queue/            # Redis queue management
│   │   └── index.ts      # Queue operations
│   ├── monitoring/       # Prometheus metrics
│   │   └── metrics.ts    # Metrics definitions
│   ├── utils/            # Utilities
│   │   └── logger.ts     # Structured logging (Pino)
│   ├── types/            # TypeScript types
│   │   └── events.ts     # Event type definitions
│   └── config.ts         # Configuration loader
├── dashboard/            # React dashboard
│   ├── src/
│   │   ├── components/   # React components
│   │   ├── api.ts        # API client
│   │   ├── types.ts      # TypeScript types
│   │   └── App.tsx       # Main app
│   └── dist/             # Production build
├── tests/
│   ├── unit/             # Unit tests
│   └── integration/      # Integration tests
├── scripts/              # Utility scripts
│   ├── init-db.sh        # Database initialization
│   └── start-dev.sh      # Development startup
├── docker-compose.yml    # Docker Compose config
├── Dockerfile            # Container image (API/Worker)
└── init.sql              # Database schema

测试

# Run all tests (76 tests total)
npm test

# Run with coverage
npm run test:coverage

# Run specific test files
npm test -- tests/integration/api.test.ts
npm test -- tests/integration/database.test.ts
npm test -- tests/integration/stats-api.test.ts

测试覆盖率

数据库测试：32个测试（插入、聚合、迁移）
API测试：18项测试（验证、限速、健康检查）
统计API测试：19个测试（端点、缓存、过滤）
单元测试：7项测试（验证逻辑、实用程序）

监控

分析服务器包括对基础设施健康和性能的全面运营监控。

普罗米修斯指标

这 /metrics endpoint公开了以下指标：

http_requests_total -按路由和状态列出的HTTP请求总数
http_request_duration_seconds -请求持续时间直方图
events_received_total -按分析级别和工具接收的事件
events_processed_total -处理的事件（成功/错误）
queue_depth -当前队列深度测量仪
database_connection_pool -连接池统计数据（总数、空闲、等待）
database_query_duration_seconds -查询性能直方图
cache_operations_total -缓存命中/未命中
worker_batch_size -工人批量分布
worker_errors_total -按类型划分的工人错误
加上Node.js默认指标（CPU、内存、GC、事件循环等）

Grafana仪表板

包括三个预配置的操作仪表板：

API运行状况仪表板：请求率、错误率、响应时间（p50/p95/p99）、正常运行时间
工作人员和队列仪表板：队列深度、处理速率、批大小、工作人员错误
数据库和基础架构仪表板：查询性能、连接池、缓存命中率、内存/CPU

所有仪表板每10秒自动刷新一次，并包括颜色编码的警报。

请参阅： 监控\_ GIDE.md 获取完整的监控文档。

数据保留

通过TimescaleDB保留策略配置：

原始事件：90天（自动删除）
每日聚合：2年
每小时聚合：30天
错误摘要：90天

生产部署

分析服务器已做好生产准备，并包括全面的部署基础设施。

快速生产部署

# 1. Clone and configure
git clone https://github.com/weather-mcp/analytics-server.git
cd analytics-server
cp .env.example .env
nano .env  # Update with production values

# 2. Start with production configuration
docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d

# 3. Verify deployment
./scripts/health-check.sh

生产特点

Docker Compose 具有生产覆盖（资源限制、安全强化）
Nginx反向代理 使用SSL/TLS、速率限制、隐私优先日志记录
自动数据库备份 （7天保留、压缩、验证）
健康监控脚本 （API、数据库、Redis、磁盘空间）
Cron作业设置 （自动备份和维护）
资源限制 适用于所有服务（CPU、内存）
日志轮转 配置
安全加固 （仅限内部端口，TLS 1.2+，HSTS）

综合文档

部署\_ GIDE.md -完整的VPS部署演练（5500+字）
PRE_DEPLOYMENT_CHECKLIST.md -80+验证项目
操作指南.md -日常操作和维护（4000+字）
监控\_ GIDE.md -监控和可观察性（7000+字）

快速安全检查表

\[\]在中更改默认数据库密码 .env
\[\]配置防火墙（UFW）
\[\]设置SSL/TLS证书（建议使用Let's Encrypt）
\[\]更新grafana管理员密码
\[\]配置Alertmanager电子邮件通知
\[\]设置自动备份（运行 ./scripts/setup-cron.sh)
\[\]验证速率限制是否有效
\[\]审查和更新CORS来源

请参阅中的完整安全检查表 PRE_DEPLOYMENT_CHECKLIST.md

使用Cloudflare隧道进行安全部署

为了增强安全性，您可以使用以下命令部署分析服务器 Cloudflare隧道，它提供安全访问，而不会将任何端口暴露到互联网。

证券收益

✅ 无开放端口 服务器上的（80/443）-除SSH之外的所有端口均已关闭 ✅ DDOS防护 Cloudflare的边缘网络 ✅ 自动SSL/TLS 证书管理 ✅ 无直接IP暴露 -攻击者无法发现您的服务器 ✅ 仅限出站连接 -服务器启动与Cloudflare的连接 ✅ 免费无限带宽

建筑

User → Cloudflare Edge → Cloudflare Tunnel → Analytics API (localhost only)

您的服务器没有可公开访问的端口。Cloudflare Tunnel创建一个加密的边界外连接到Cloudflare的边缘网络，然后将HTTPS流量路由到本地API服务器。

快速设置

我们提供自动化脚本，便于Cloudflare Tunnel部署：

# 1. Configure firewall (blocks all ports except SSH)
sudo ./scripts/setup-firewall.sh YOUR_IP_ADDRESS

# 2. Install and configure Cloudflare Tunnel
sudo ./scripts/setup-cloudflare-tunnel.sh

# 3. Start your API server (listens on localhost only)
npm run build
node dist/api/index.js

部署选项

选项A：直接Cloudflare隧道 （最简单）

Cloudflare → Tunnel → API (localhost:3000)

选项B：Cloudflare隧道+Nginx （高级）

Cloudflare → Tunnel → Nginx (localhost:8080) → API (localhost:3000)

添加速率限制、缓存和其他安全标头。

完整的文件

有关完整的部署说明，请参阅：

CLOUDFLARE_TUNNEL_DEPLOYMENT.md -完整的分步指南
环境配置.md -环境变量引用

Cloudflare隧道与传统部署

功能	Cloudflare隧道	传统Nginx
开放端口	仅限SSH（22）	SSH（23）、HTTP（80）、HTTPS（443）
SSL证书	自动	手动（让我们加密）
DDoS保护	包括在内	需要单独的服务
IP暴露	隐藏	公共IP可见
设置复杂性	自动脚本	手动nginx+certbot
防火墙规则	最小	广泛
成本	免费	免费（但更复杂）

先决条件

Cloudflare帐户（免费版有效）
由Cloudflare DNS管理的域
数字海洋液滴或任何VPS
Ubuntu 22.04 LTS或更高版本

配置文件

Cloudflare隧道部署包括：

scripts/setup-cloudflare-tunnel.sh -自动隧道安装
scripts/setup-firewall.sh -UFW防火墙配置
nginx/cloudflare-tunnel.conf -隧道可选nginx配置
cloudflared-config.template.yml -隧道配置模板
docs/CLOUDFLARE_TUNNEL_DEPLOYMENT.md -完整的部署指南

监控隧道健康状况

# Check tunnel status
sudo systemctl status cloudflared

# View tunnel logs
sudo journalctl -u cloudflared -f

# Test external access
curl https://analytics.weather-mcp.dev/health

您还可以在Cloudflare Zero Trust仪表板中监控隧道健康状况。

故障排除

数据库连接问题

# Check PostgreSQL is running
docker-compose ps postgres

# Check logs
docker-compose logs postgres

# Test connection
PGPASSWORD=$DB_PASSWORD psql -h localhost -U analytics -d analytics

队列问题

# Check Redis
docker-compose ps redis

# Check queue depth
docker-compose exec redis redis-cli LLEN analytics:events

# Clear queue (development only!)
docker-compose exec redis redis-cli DEL analytics:events

工作人员未处理事件

# Check worker logs
docker-compose logs worker

# Restart worker
docker-compose restart worker

# Check for errors in database
docker-compose logs postgres | grep ERROR

贡献

分叉存储库
创建要素分支(git checkout -b feature/amazing-feature)
进行更改
运行测试(npm test)
提交您的更改(git commit -m 'Add amazing feature')
推送到分支(git push origin feature/amazing-feature)
打开拉取请求

开发指南

为所有新功能编写测试
遵循现有的代码风格（ESLint+Prettier）
更新文档
确保所有测试通过
为所有函数添加TypeScript类型

许可证

MIT许可证-请参阅许可证详细信息文件

文档

包括全面的文件：

用户文档

README.md -此文件（项目概述和快速入门）
API毫米 -完整的API参考资料和示例
隐私政策.md -隐私政策和数据处理

部署文档

部署\_ GIDE.md -VPS部署演练（5500+字）
CLOUDFLARE_TUNNEL_DEPLOYMENT.md -Cloudflare隧道安全部署指南
环境配置.md -完整的环境变量引用
PRE_DEPLOYMENT_CHECKLIST.md -80+个发射前验证项目
操作指南.md -日常操作和维护（4000+字）

监控文件

监控\_ GIDE.md -完整的监控指南（7000+字）
发射后监测.md -发射后监测计划

技术文档

测试指南.md -测试策略和执行
测试验证报告.md -完整的覆盖范围分析
API_INTEGRACTION_GUIDE.md语言 -网站开发人员集成指南
类型脚本_类型.md -TypeScript类型定义指南
实施_计划.md -详细的实施路线图

阶段完成报告

第6阶段_完成_报告.md -部署和基础设施
第7阶段_完成_报告.md -监测和可观察性
第9阶段_完成_报告.md -发射准备

链接

GitHub组织: https://github.com/weather-mcp
气象MCP服务器: https://github.com/weather-mcp/mcp-server
分析服务器: https://github.com/weather-mcp/analytics-server
网站: https://github.com/weather-mcp/website
公共仪表板: https://weather-mcp.dev/dashboard *（即将推出）*

支持

对于问题和疑问：

分析服务器问题: https://github.com/weather-mcp/analytics-server/issues
MCP服务器问题: https://github.com/weather-mcp/mcp-server/issues
常见问题: https://github.com/weather-mcp/.github/discussions

______________________________________________________________________

状态: ✅ 生产准备就绪（第9阶段完成）

最后更新: 2025-01-13 版本: 1.0.0 测试覆盖率：关键模块86-100%（266项测试通过）

Analytics Server

快速接入

详细介绍

气象MCP分析服务器

概述

建筑

隐私原则

特性

API终点

运行监测

技术栈

Docker快速入门

1.克隆和配置

2.启动所有服务

3.接入服务

开发设置

先决条件

1.安装依赖项

2.启动基础设施

3.初始化数据库

4.启动开发服务器

5.运行测试

配置

关键配置选项

API使用

事件摄入

获取统计信息

项目结构

测试

测试覆盖率

监控

普罗米修斯指标

Grafana仪表板

数据保留

生产部署

快速生产部署

生产特点

综合文档

快速安全检查表

使用Cloudflare隧道进行安全部署

证券收益

建筑

快速设置

部署选项

完整的文件

Cloudflare隧道与传统部署

先决条件

配置文件

监控隧道健康状况

故障排除

数据库连接问题

队列问题

工作人员未处理事件

贡献

开发指南

许可证

文档

用户文档

部署文档

监控文件

技术文档

阶段完成报告

链接

支持

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP