Link Forge

LinkForge-URL缩短器

🚧 进行中 -该项目目前正在开发中，可能包含不完整的功能或错误。

一个现代的、功能丰富的URL缩短应用程序，具有分析功能，使用React、TypeScript、Node.js和MongoDB构建。包括用于AI驱动的URL管理的模型上下文协议（MCP）服务器集成。

______________________________________________________________________

🚀 特性

• URL缩短：使用自定义别名创建短URL
• 分析：全面的点击跟踪和分析
• 用户认证：基于JWT的安全身份验证
• 仪表盘：带有图表和见解的漂亮仪表板
• MCP集成：用于AI工具集成的模型上下文协议服务器
• 响应式设计：支持暗模式的移动优先设计
• Docker支持：使用Docker Compose实现完全容器化
• Redis支持的后台作业：BullMQ用于URL过期和分析聚合，具有 本地 setInterval 后备方案 启动时或共享Redis客户端断开连接后无法访问Redis时；当Redis再次准备就绪时，工作将转移回BullMQ
• Redis关闭时缓存降级：重定向查找缓存在Redis不可用时跳过Redis。这 短URL计数器 现在使用MongoDB，因此只要MongoDB可用，短URL创建就可以工作。
• 可观测性堆栈：Prometheus指标收集、Grafana仪表板和Redis/MongoDB导出器的全面监控
• API密钥缓存：用于API密钥验证的基于Redis的缓存，以提高身份验证性能
• 增强指标：HTTP请求、队列性能、Redis操作和URL操作的自定义指标

______________________________________________________________________

🏗️ 建筑

技术栈

项目结构

url-shortener/
├── client/                 # React frontend application
│   ├── src/
│   │   ├── components/     # Reusable UI components
│   │   ├── services/       # API services and MCP client
│   │   ├── pages/          # Page components
│   │   ├── store/          # State management
│   │   └── hooks/          # Custom React hooks
│   └── Dockerfile
├── server/                 # Node.js backend API
│   ├── src/
│   │   ├── controllers/    # Route controllers
│   │   ├── routes/         # API routes
│   │   ├── config/         # Configuration files
│   │   ├── utils/          # Utility functions
│   │   ├── queues/         # Queue systems
│   │   ├── workers/        # Background job workers
│   │   ├── producers/      # Queue producers
│   │   ├── models/         # Data models
│   │   ├── services/       # Business logic
│   │   ├── repositories/   # Data access layer
│   │   ├── middlewares/    # Express middlewares
│   │   ├── server.ts       # Main server entry point
│   │   └── mcp.server.ts   # MCP server implementation
│   └── Dockerfile
├── compose.yaml            # Docker Compose configuration
└── README.md              # This file

系统运行时流程

客户： React应用程序通过HTTP调用API(/trpc).公共短链接使用 GET /fwd/:shortUrl 在Express主应用程序上。 主控程序 是一个单独的过程（默认 MCP_SERVER_PORT 4200，SSE）在引导中启用时--请参阅 server/src/mcp.server.ts.

创建短URL（tRPC）： 分配新链接现在使用 基于MongoDB的计数器 (getNextId). 创建短URL不再需要Redis读取、重定向和计数器分配都使用MongoDB。

重定向并点击分析（Redis向上）： 每个成功的重定向都会构建一个有效载荷 addAnalyticsJob 将工作推到 BullMQ分析 队列（由Redis支持）。这 分析工作者 在内存中缓冲作业 散装嵌件 当以下任一情况发生时：

• 批次达到 20 工作，或
• 一 5秒 定时器会触发（定期刷新——所以你也会在时间窗口上刷新，而不仅仅是当大小达到20时）。

插入到MongoDB。 死信队列： 在批量插入过程中失败的行，或者在刷新抛出的情况下在整个批次中失败的行将是 添加到分析死信队列 以便稍后检查/回放。

Redis关闭时重定向： 用户仍然使用MongoDB重定向（并且缓存行为降级）。 BullMQ在没有Redis的情况下无法运行，所以 点击分析不会通过队列记录 在那个州--这里的改进正在进行中。

计划作业： Redis启动后， URL过期 在BullMQ上运行 ~16分钟 节奏和 分析聚合 在一个 约60分钟 节奏。如果Redis不可用， 本地 setInterval 调度器 大致相同的工作（没有BullMQ）。

查看图表： 内置Markdown预览(Ctrl+Shift+V)在VS代码和游标中 不 渲染美人鱼。选项：安装 Markdown预览美人鱼支持 并从该扩展打开预览，或在GitHub上查看此文件（那里支持Mermaid）。下面的文本图适用于任何预览。

文本图（适用于所有地方）：

                        +------------------+
                        |   User Browser   |
                        +--------+---------+
                                 |
           +---------------------+----------------------+
           |                     |                      |
           v                     v                      v
    +-------------+      +---------------+       +---------------+
    | React Client|      | GET /fwd/...  |       | MCP clients   |
    |  /trpc      |      | (redirect)    |       | SSE :4200     |
    +------+------+      +-------+-------+       +-------+-------+
           |                      |                      |
           v                      v                      v
    Express + tRPC          same Express app           MCP server
           \                      |                     /
            +----------+----------+--------------------+
                                  |
    +------------------------------------------------------------------+
    |                                                                  |
   |  CREATE SHORT URL (uses MongoDB counter)                         |
    |  Redis UP  --> counter OK --> persist URL in MongoDB             |
   |  MongoDB DOWN -> creation fails (no new short URL)               |
    |                                                                  |
    |  REDIRECT                                                         |
    |  --> resolve target from MongoDB (Redis cache if available)       |
    |  Redis UP  --> enqueue 1 analytics job per redirect --> BullMQ   |
    |  Redis DOWN -> redirect OK, queue offline (analytics gap/WIP)    |
    |                                                                  |
    v                                                                  v
  MongoDB                                                           Redis
 (URLs, analytics                                                  (counter,
  aggregates)                                                       BullMQ)

    Analytics worker (Redis UP only):
      redirect jobs -> in-memory batch -> flush if |batch|>=20 OR every 5s
                    -> bulk insert MongoDB
                    -> failures -> Dead letter queue

    Schedulers:
      Redis UP   -> BullMQ: URL expiry ~16 min, aggregation ~60 min
      Redis DOWN -> Local timers: same two jobs without BullMQ

Mermaid version (GitHub / Mermaid-enabled preview)

flowchart TB
  subgraph clients [Clients]
    browser[User Browser]
    mcpClients[MCP clients]
  end
  subgraph mainApi [Main API Express]
    trpc[tRPC]
    redirect[GET /fwd redirect]
  end
  mcpServer[MCP server SSE port 4200]
  mongo[(MongoDB)]
  redis[(Redis)]
  q[Analytics BullMQ queue]
  worker[Analytics worker]
  batch[Batch max 20 or flush every 5s]
  dlq[Analytics dead letter queue]
  bullSched[BullMQ schedulers URL expiry 16m aggregation 60m]
  localSched[Local schedulers when Redis down]

  browser --> trpc
  browser --> redirect
  mcpClients --> mcpServer
   trpc -->|new short URL ID| mongo
  trpc --> mongo
  redirect --> mongo
  redirect --> redis
  redirect -->|one job per redirect| q
  mcpServer --> mongo
  q --> redis
  q --> worker
  worker --> redis
  worker --> batch
  batch --> mongo
  batch -->|failed rows or flush error| dlq
  bullSched --> redis
  bullSched --> mongo
  localSched --> mongo

Redis和后台作业

Redis用于：

• 重定向缓存 （热路径 /fwd/:shortUrl)
• 单调的短URL ID （基于MongoDB的计数器）
• BullMQ：URL过期计划程序(~16分钟 在cron中）和分析聚合(约60分钟 /代码中的小时窗口）
• 队列监视 通过Bull Board /ui （发展）

启动行为

• initRedis() 等待成功 PING 或者在大约之后超时 3秒，因此当Redis变慢或变慢时，服务引导不会无限期阻塞。
• A共享 isRedisAvailable flag跟踪主Redis客户端(ready, error, close, end).

BullMQ与本地调度器

• 当Redis可用时：URL过期和分析聚合在 BullMQ （队列+可重复作业+工人）。

• 当Redis在启动时停机，或者共享客户端看到与BullMQ设置断开连接后：这些工作负载会回退到 本地计时器 （16分钟URL到期作业，60分钟聚合间隔）。

• 新的短网址 现在使用基于MongoDB的单调ID计数器： 只要MongoDB可用，创建就可以工作此路径不需要Redis。

• 对于 满的 行为——创建链接、缓存、队列和Bull Board--保持Redis运行Docker Compose启动 redis 通过健康检查，服务器在容器中启动之前等待健康的Redis。

分析提交队列

• 点击事件包括 每次重定向时排队 当Redis和BullMQ健康时；工人 批次 写入（刷新 20 工作或 5秒 定时器）并发送 批量插入失败/刷新错误 到 死信队列 （参见 analytics.worker.ts).
• 如果Redis宕机， 分析队列不工作，所以 不记录实时点击分析 通过这条路；到期/聚合仍然可以使用 本地调度器. 强化这条道路是一项正在进行的工作。
• 队列客户端创建于 模块导入 时间；一个宕机的Redis可能会产生连接噪音，直到它回来。

文本图（Redis模式）：

                    Shared Redis client (app singleton)
                                        |
              +-------------------------+-------------------------+
              |                                                   |
      Redis UP (connected)                                 Redis DOWN / close
              |                                                   |
      +-------+-------+                                   +-------+-------+
      |               |                                   |               |
      v               v                                   v               v
 BullMQ +         Redirect                           setInterval      Cache: no-op
 cache hit        cache OK                           local jobs      or cache miss
 (expiry,         (hot path)                         (expiry,          (degraded)
  aggregation)                                        aggregation)

Mermaid version (GitHub / Mermaid-enabled preview)

flowchart LR
  subgraph redisUp [Redis up]
    BullMQ[BullMQ schedulers]
    Cache[Redirect cache]
  end
  subgraph redisDown [Redis down or disconnected]
    Local[Local setInterval jobs]
    CacheDegraded[Cache no-op or miss]
  end
  SharedClient[Shared redis client]
  SharedClient --> BullMQ
  SharedClient --> Cache
  SharedClient --> Local
  SharedClient --> CacheDegraded

______________________________________________________________________

环境变量引用

配置在启动时由以下人员验证 server/src/config/env.ts.复制 server/.env.example 到 server/.env 并进行调整。 必需 （无默认值）： DB_URL, REDIS_URL, BASE_URL, JWT_ACCESS_SECRET （最少10个字符）， JWT_REFRESH_SECRET （最少10个字符）。如果省略，所有其他键都有默认值。

Docker与本地URL：关于Docker内部网络的使用 DB_URL=mongodb://mongo:27017/url_shortener 和 REDIS_URL=redis://redis:6379.在你的主机与 npm run dev，使用 localhost 两者（参见 .env.example).

______________________________________________________________________

🐳 Docker设置

先决条件

• Docker和Docker Compose已安装在您的系统上
• Git用于克隆存储库

快速开始

1. 克隆仓库

   git clone https://github.com/Abhi-wolf/LinkForge.git
   cd LinkForge

1. 启动应用程序 （编写文件为 compose.yaml)

   docker compose -f compose.yaml up -d

Docker Compose V1用户可以运行 docker-compose -f compose.yaml up -d 相反。

1. 访问应用程序

- 前端: http://localhost:3000 - 后端API: http://localhost:4000 - MCP服务器: http://localhost:4200 - 牛板（队列UI）: http://localhost:4000/ui - 普罗米修斯: http://localhost:9090 - 格拉法纳: http://localhost:3001（管理员/管理员） - Redis导出器: http://localhost:9121/metrics - MongoDB导出器: http://localhost:9216/metrics

服务

Docker Compose设置包括：

• 芒果 （端口27017）：URL数据的主数据库
• 瑞迪斯 （端口6379）：缓存、ID计数器和BullMQ作业后端
• 服务器 （端口40004200）：后端API和MCP服务器
• 客户 （端口3000）：React前端应用程序
• 普罗米修斯 （端口9090）：指标收集和监控
• 格拉法纳 （端口3001）：可视化仪表板
• Redis导出器 （端口9121）：普罗米修斯的Redis指标
• MongoDB导出器 （端口9216）：普罗米修斯的MongoDB指标

环境变量（Docker）

对于 完整变量列表和默认值，请参阅 环境变量引用 上面。

跑步时 里面 compose.yaml，至少设置 DB_URL 和 REDIS_URL 使用撰写服务主机名(mongo, redis).捆绑 server.environment 块可以是最小的；扩展或安装 .env 文件要求保密(JWT_ACCESS_SECRET, JWT_REFRESH_SECRET等等）和可选密钥匹配生产需求。将名称与对齐 server/src/config/env.ts （例如使用 JWT_ACCESS_SECRET，不 JWT_SECRET).

⚠️ 安全：在制作中使用强大的JWT秘密；永远不要承诺真实 .env 文件夹。

______________________________________________________________________

🔧 MCP服务器集成

概述

模型上下文协议（MCP）服务器允许AI助手通过标准化的接口与URL缩短器进行交互。

MCP服务器详细信息

• 统一资源定位符: http://localhost:4200
• 运输：服务器发送事件（SSE）
• 认证：API关键中间件

可用工具

MCP服务器公开了以下工具：

1. create_short_url

- 从原始URL创建短URL - 输入： { originalUrl: string, tags?: [string],expirationDate?: Date }

1. get_original_url

- 从短URL ID检索原始URL - 输入： { shortUrl: string }

1. 获取分析信息关于url

- 检索特定URL的分析 - 输入： { shortUrl: string, startDate: Date, endDate: Date }

1. get_all_user_urls

- 检索由经过身份验证的用户创建的所有URL - 输入：无需参数

连接到MCP服务器

API密钥验证

MCP服务器需要API密钥进行身份验证。要生成API密钥，请执行以下操作：

1. 生成API密钥 （通过您的应用程序设置或API）
2. 使用API密钥 在 x-api-key 所有MCP请求的标头

使用MCP检查器

1. 安装MCP检查器：

   npx @modelcontextprotocol/inspector

1. 打开浏览器并导航到：

   http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=

1. 检查器UI将允许您测试所有可用工具。

______________________________________________________________________

📱 应用程序功能

前端功能

• 着陆页：无身份验证的公共URL缩短
• 用户认证：使用JWT代币登录和注册
• 仪表盘：KPI卡和图表概述
• 链路管理：创建、查看、编辑和删除短网址
• 分析：使用图表进行详细的点击分析
• 设置：配置文件管理和密码更改
• 深色模式：系统、浅色和深色主题支持

后端功能

• RESTful API：URL的完整CRUD操作
• 认证：基于JWT的身份验证，带有刷新令牌
• 分析：点击跟踪设备和推荐人数据
• 缓存和计数器：Redis不可用时，Redis支持的重定向缓存会优雅降级； 基于MongoDB的单调ID计数器 用于创建短URL
• 后台作业：BullMQ用于URL过期和分析聚合，在Redis不可用时使用本地调度器（请参阅 Redis和后台作业)
• 速率限制：API速率限制和安全
• 健康检查：对所有服务进行Docker健康检查
• 指标收集：HTTP、队列、Redis和URL操作的全面Prometheus指标
• API密钥管理：安全的API密钥生成和缓存，用于MCP身份验证

______________________________________________________________________

API终点

健康检查

• GET /health-check -服务健康状态

指标端点

• GET /metrics -Prometheus指标端点（HTTP、队列、Redis、URL指标）

队列监控（开发）

• GET /ui -BullBoard UI用于配置BullMQ队列

MCP服务器

• GET /sse -SSE连接端点（需要 x-api-key 头球
• POST /messages -消息处理端点（需要 x-api-key 头球

______________________________________________________________________

🛠️ 发展

地方发展设置

1. 安装依赖项

   # Frontend
   cd client
   npm install

   # Backend
   cd server
   npm install

1. 设置环境变量

   # In server directory
   cp .env.example .env
   # Edit .env with your configuration

1. 启动数据库

   docker compose -f compose.yaml up mongo redis -d

1. 运行开发服务器

   # Backend (in server directory)
   npm run dev

   # Frontend (in client directory)
   npm run dev

生产环境构建

# Build frontend
cd client
npm run build

# Build backend
cd server
npm run build

______________________________________________________________________

📊 监测和可观察性

指标收集

该应用程序在以下位置公开了全面的Prometheus指标 /metrics:

• HTTP指标：请求计数、持续时间、错误、速率限制
• 队列指标：BullMQ队列大小、处理时间、故障率
• Redis指标：连接状态、缓存命中/未命中率、操作计数
• URL指标：短URL创建率、重定向计数、分析处理

监控堆栈

• 普罗米修斯 (http://localhost:9090)：收集和存储指标
• 格拉法纳 (http://localhost:3001)：使用仪表板可视化指标
• Redis导出器 (http://localhost:9121/metrics)：Redis特定指标
• MongoDB导出器 (http://localhost:9216/metrics)：MongoDB特定指标

健康检查

Docker Compose设置包括对所有服务的健康检查：

• MongoDB：数据库连接检查
• 瑞迪斯：Redis ping检查
• 服务器：HTTP健康检查端点(/live)
• 出口商：度量端点可用性

健康状况可以通过以下方式检查：

docker compose -f compose.yaml ps

API密钥缓存

API密钥缓存在Redis中，以提高身份验证性能：

• 缓存TTL：API密钥缓存项的可配置过期时间
• 缓存失效：密钥更新/删除时自动缓存失效
• 后备方案：缓存不可用时直接查找数据库

______________________________________________________________________

🔒 安全考虑

• JWT机密应在生产中更改
• API密钥应保持安全并定期轮换
• 永远不要在客户端代码或公共存储库中公开API密钥
• 数据库凭据应使用环境变量
• 应在生产环境中启用HTTPS
• 对API端点实施速率限制
• MCP服务器连接需要有效的API密钥，通过 x-api-key 头球

______________________________________________________________________

📝 许可证

该项目根据MIT许可证获得许可。

______________________________________________________________________

🤝 贡献

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 如果适用，添加测试
5. 提交拉取请求

______________________________________________________________________

建于❤️ 使用现代网络技术