hsred/test

Public

WeChat Login

Code Issues Pull requests Events Packages Insights

main

test/README-cn.md

魂笙

feat: 增强后台管理功能并优化性能

2a750a60

PreviewCode viewBlame

Raw

URL 转换与 CDN 代理服务

一个功能强大的 URL 转换和 CDN 代理服务，支持将 GitHub、npm、cnb.cool 等源站的 URL 转换为自定义 CDN 地址，并提供灵活的黑名单和白名单管理功能。

功能特性
技术栈
项目结构
数据库模型
安装与部署
快速开始指南
常用命令参考
API 接口文档
黑名单规则说明
域名白名单规则说明
转换规则说明
高级配置
配置说明
常见问题
监控与日志
最佳实践
安全注意事项
贡献指南
更新日志
许可证
联系方式
致谢

功能特性

核心功能

URL 转换：支持将 GitHub、npm、jsDelivr、unpkg 等源站的 URL 转换为自定义 CDN 地址
CDN 代理：通过转换后的 URL 直接访问原始内容
黑名单规则：支持路径、正则表达式、域名三种黑名单匹配方式
域名白名单：支持仅域名、域名+路径、正则表达式三种匹配模式
灵活拦截：支持拦截、重定向、自定义响应三种拦截动作
管理后台：可视化的规则管理和统计信息查看

支持的源站

GitHub：github.com、raw.githubusercontent.com
npm：npmjs.com、unpkg.com、esm.run、jsdelivr.net
cnb.cool：GitLab 风格的代码托管平台
更多：可通过配置轻松扩展

技术栈

前端

Next.js 15：React 框架，支持 App Router
React 19：最新版本的 React
TypeScript：类型安全的 JavaScript 超集
Tailwind CSS：实用优先的 CSS 框架
shadcn/ui：基于 Radix UI 的组件库

后端

Next.js API Routes：服务端 API
Prisma ORM：数据库操作
SQLite：嵌入式数据库

开发工具

Bun：快速的 JavaScript 运行时
ESLint：代码质量检查
PostCSS：CSS 处理

项目结构


workspace/
├── .claude/                      # Claude AI 配置
│   └── settings.local.json        # AI 助手本地设置
├── .codebuddy/                   # CodeBuddy 配置
├── .next/                        # Next.js 构建输出
│   ├── app-build-manifest.json   # 应用构建清单
│   ├── build-manifest.json        # 构建清单
│   ├── cache/                    # 构建缓存
│   ├── server/                   # 服务端代码
│   ├── static/                   # 静态资源
│   ├── standalone/               # 独立部署文件
│   └── types/                    # TypeScript 类型
├── components.json               # shadcn/ui 组件配置
├── db/                          # 数据库文件
│   └── custom.db               # 自定义数据库
├── dev.log                     # 开发日志
├── eslint.config.mjs           # ESLint 配置
├── examples/                   # 示例代码
│   ├── websocket/              # WebSocket 示例
│   └── ...
├── image.png                   # 项目图片
├── mini-services/              # 微服务
├── next.config.ts             # Next.js 配置
├── next-env.d.ts             # Next.js TypeScript 类型声明
├── package.json              # 项目依赖和脚本
├── package-lock.json         # 依赖锁文件
├── postcss.config.mjs        # PostCSS 配置
├── prisma/                   # Prisma 数据库配置
│   ├── dev.db               # SQLite 开发数据库
│   ├── prisma/              # Prisma 迁移文件
│   └── schema.prisma        # 数据库模型定义
├── public/                   # 静态资源
│   ├── logo.svg             # Logo 文件
│   └── robots.txt           # 搜索引擎爬虫配置
├── scripts/                  # 工具脚本
│   └── init-db.ts          # 数据库初始化脚本
├── seed-logs.ts            # 日志种子数据
├── seed-test-data.ts       # 测试数据种子
├── skills/                 # AI 技能
├── src/                    # 源代码
│   ├── app/               # Next.js App Router
│   │   ├── [...catchall]/ # 通配符路由，处理 CDN 代理
│   │   │   └── route.ts  # CDN 代理路由处理
│   │   ├── admin/        # 管理后台
│   │   │   └── page.tsx  # 管理后台页面
│   │   ├── api/          # API 路由
│   │   │   ├── admin/    # 管理相关 API
│   │   │   │   ├── auth/               # 认证 API
│   │   │   │   │   └── route.ts       # 认证处理
│   │   │   │   ├── blacklist/          # 黑名单相关 API
│   │   │   │   │   ├── config/        # 黑名单配置
│   │   │   │   │   │   └── route.ts    # 黑名单配置管理
│   │   │   │   │   └── rules/         # 黑名单规则
│   │   │   │   │       └── route.ts    # 黑名单规则管理
│   │   │   │   ├── domains/           # 域名白名单 API
│   │   │   │   │   └── route.ts       # 域名白名单管理
│   │   │   │   ├── logs/              # 操作日志
│   │   │   │   │   └── route.ts       # 日志查询
│   │   │   │   ├── stats/             # 统计信息
│   │   │   │   │   └── route.ts       # 统计数据
│   │   │   │   └── route.ts           # 管理首页 API
│   │   │   ├── config/               # 配置 API
│   │   │   │   ├── reload/           # 配置重载
│   │   │   │   │   └── route.ts      # 配置重载接口
│   │   │   │   └── route.ts          # 系统配置
│   │   │   ├── convert/             # URL 转换 API
│   │   │   │   └── route.ts          # URL 转换处理
│   │   │   ├── proxy/               # 代理 API
│   │   │   │   └── route.ts          # 内容代理
│   │   │   ├── status/              # 服务状态
│   │   │   │   └── route.ts          # 状态检查
│   │   │   └── route.ts             # API 路由
│   │   ├── globals.css            # 全局样式
│   │   ├── layout.tsx             # 根布局
│   │   └── page.tsx              # 首页
│   ├── components/              # React 组件
│   │   └── ui/                 # shadcn/ui 组件
│   │       ├── accordion.tsx   # 手风琴
│   │       ├── alert-dialog.tsx # 警告对话框
│   │       ├── alert.tsx       # 警告提示
│   │       ├── aspect-ratio.tsx # 宽高比
│   │       ├── avatar.tsx      # 头像
│   │       ├── badge.tsx       # 标签
│   │       ├── breadcrumb.tsx  # 面包屑导航
│   │       ├── button.tsx      # 按钮
│   │       ├── calendar.tsx     # 日历
│   │       ├── card.tsx        # 卡片
│   │       ├── carousel.tsx    # 轮播图
│   │       ├── chart.tsx       # 图表
│   │       ├── checkbox.tsx    # 复选框
│   │       ├── collapsible.tsx # 可折叠
│   │       ├── command.tsx     # 命令面板
│   │       ├── context-menu.tsx # 右键菜单
│   │       ├── dialog.tsx      # 对话框
│   │       ├── drawer.tsx      # 抽屉
│   │       ├── dropdown-menu.tsx # 下拉菜单
│   │       ├── form.tsx        # 表单
│   │       ├── hover-card.tsx  # 悬停卡片
│   │       ├── input-otp.tsx   # OTP 输入
│   │       ├── input.tsx       # 输入框
│   │       ├── label.tsx       # 标签
│   │       ├── menubar.tsx     # 菜单栏
│   │       ├── navigation-menu.tsx # 导航菜单
│   │       ├── pagination.tsx  # 分页
│   │       ├── popover.tsx     # 弹出框
│   │       ├── progress.tsx    # 进度条
│   │       ├── radio-group.tsx # 单选组
│   │       ├── resizable.tsx   # 可调整大小
│   │       ├── scroll-area.tsx # 滚动区域
│   │       ├── select.tsx      # 选择器
│   │       ├── separator.tsx   # 分隔符
│   │       ├── sheet.tsx       # 侧边栏
│   │       ├── sidebar.tsx     # 侧边栏组件
│   │       ├── skeleton.tsx    # 骨架屏
│   │       ├── slider.tsx      # 滑块
│   │       ├── sonner.tsx      # Toast 通知
│   │       ├── switch.tsx      # 开关
│   │       ├── table.tsx       # 表格
│   │       ├── tabs.tsx        # 标签页
│   │       ├── textarea.tsx    # 文本域
│   │       ├── toast.tsx       # Toast 组件
│   │       ├── toaster.tsx     # Toast 容器
│   │       ├── toggle-group.tsx # 切换组
│   │       ├── toggle.tsx      # 切换按钮
│   │       └── tooltip.tsx     # 工具提示
│   ├── hooks/                 # React Hooks
│   │   ├── use-mobile.ts      # 移动端检测
│   │   └── use-toast.ts       # Toast 通知
│   └── lib/                  # 工具库
│       ├── converter.ts       # URL 转换核心逻辑
│       ├── db-manager.ts      # 数据库管理
│       ├── db.ts             # 数据库连接
│       └── utils.ts          # 工具函数
├── tailwind.config.ts        # Tailwind CSS 配置
├── tsconfig.json            # TypeScript 配置
├── start.bat                # Windows 启动脚本
└── start.sh                 # Linux/Mac 启动脚本

数据库模型

SystemConfig（系统配置）

存储系统的全局配置项，支持分类管理。


model SystemConfig {
  id          String   @id @default(cuid())
  key         String   @unique
  value       String
  description String?
  category    String   @default("general")
  updatedAt   DateTime @updatedAt
  updatedBy   String?
}

BlacklistRule（黑名单规则）

定义 URL 拦截规则，支持多种匹配方式和拦截动作。


model BlacklistRule {
  id             String   @id @default(cuid())
  type           String   // 'path', 'regex', 'domain'
  pattern        String
  description    String?
  enabled        Boolean  @default(true)
  priority       Int      @default(0)
  actionOnMatch  String?  // 'block', 'redirect', 'custom'
  redirectUrl    String?
  customResponse String?
  createdAt      DateTime @default(now())
  updatedAt      DateTime @updatedAt
  createdBy      String?
}

BlacklistConfig（黑名单配置）

黑名单的全局配置，控制黑名单的整体行为。


model BlacklistConfig {
  id             String   @id @default(cuid())
  enabled        Boolean  @default(true)
  globalMode     String   @default("block")
  actionOnMatch  String   @default("block")
  redirectUrl    String?
  customResponse String?
  logMatches     Boolean  @default(true)
  updatedAt      DateTime @updatedAt
  updatedBy      String?
}

DomainRule（域名白名单）

定义允许访问的域名规则，支持多种匹配模式。


model DomainRule {
  id          String   @id @default(cuid())
  domain      String
  matchType   String   @default("domain") // 'domain', 'domain_path', 'regex'
  pathPattern String?
  description String?
  enabled     Boolean  @default(true)
  priority    Int      @default(0)
  createdAt   DateTime @default(now())
  updatedAt   DateTime @updatedAt
  createdBy   String?
}

ConversionRecord（转换记录）

记录所有的 URL 转换操作，用于统计分析。


model ConversionRecord {
  id            String   @id @default(cuid())
  sourceDomain  String
  targetUrl     String
  sourceUrl     String
  status        String   // 'success', 'failed', 'blocked'
  blockedReason String?
  ipAddress     String?
  userAgent     String?
  referer       String?
  responseTime  Int
  createdAt     DateTime @default(now())
}

ConversionStats（转换统计）

按天聚合的转换统计信息，用于分析和报表。


model ConversionStats {
  id              String   @id @default(cuid())
  date            String   // YYYY-MM-DD
  totalConversions Int     @default(0)
  successCount    Int      @default(0)
  failedCount     Int      @default(0)
  blockedCount    Int      @default(0)
  avgResponseTime Float?   // 平均响应时间
  totalFileSize   BigInt?  @default(0)
  topDomains      String?  // JSON 格式存储热门域名
  createdAt       DateTime @default(now())
  updatedAt       DateTime @updatedAt

  @@unique([date])
  @@index([date])
}

OperationLog（操作日志）

记录系统的重要操作，用于审计和追踪。


model OperationLog {
  id          String   @id @default(cuid())
  action      String   // 'CREATE', 'UPDATE', 'DELETE', 'SWITCH_DB', etc.
  module      String   // 'BlacklistRule', 'DomainRule', 'SystemConfig', etc.
  entityId    String?
  details     String?
  ipAddress   String?
  userAgent   String?
  userId      String?
  createdAt   DateTime @default(now())

  @@index([createdAt])
  @@index([module])
  @@index([action])
}

ComplianceConfig（合规日志配置）

日志合规性管理配置。


model ComplianceConfig {
  id                  String   @id @default(cuid())
  retentionDays       Int      @default(90) // 日志保留天数
  enabled             Boolean  @default(true)
  auditMode           Boolean  @default(false)
  sensitiveDataMask   Boolean  @default(true)
  alertThreshold      Int?     // 告警阈值
  createdAt           DateTime @default(now())
  updatedAt           DateTime @updatedAt
}

User（用户认证）

管理员用户账户（预留）。


model User {
  id        String   @id @default(cuid())
  username  String   @unique
  password  String   // 哈希后的密码
  role      String   @default("admin")
  enabled   Boolean  @default(true)
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
  lastLoginAt DateTime?
}

安装与部署

环境要求

Node.js >= 18.17.0 或 Bun >= 1.0.0
Git（可选，用于克隆项目）

快速开始

1. 克隆项目


git clone <repository-url>
cd workspace

2. 安装依赖

使用 Bun（推荐）：


bun install

或使用 npm：


npm install

3. 初始化数据库


bun run db:push

4. 启动开发服务器


bun run dev

服务器将在 http://localhost:3000 启动。

生产部署

1. 构建项目


DATABASE_URL="file:./prisma/dev.db" bun run build

2. 启动生产服务器


bun run start

或使用启动脚本：

Linux/Mac:


./start.sh

Windows:


start.bat

Docker 部署（可选）

创建 Dockerfile：


FROM node:18-alpine AS builder

WORKDIR /app

COPY package*.json ./
RUN npm install

COPY . .
RUN DATABASE_URL="file:./prisma/dev.db" npm run build

FROM node:18-alpine

WORKDIR /app

ENV NODE_ENV=production
ENV DATABASE_URL="file:./prisma/dev.db"

COPY --from=builder /app/.next/standalone ./
COPY --from=builder /app/.next/static ./.next/static
COPY --from=builder /app/public ./public
COPY --from=builder /app/prisma ./prisma

EXPOSE 3000

CMD ["node", "server.js"]

构建和运行：


docker build -t url-converter .
docker run -p 3000:3000 url-converter

快速开始指南

5 分钟快速体验

1. 安装并启动


# 克隆项目
git clone <repository-url>
cd workspace

# 安装依赖（使用 Bun 更快）
bun install
# 或使用 npm
# npm install

# 初始化数据库
DATABASE_URL="file:./prisma/dev.db" bun run db:push

# 启动开发服务器
bun run dev

服务将在 http://localhost:3000 启动。

2. 转换 URL

使用 curl 测试 URL 转换：


# 转换 GitHub URL
curl -X POST http://localhost:3000/api/convert \
  -H "Content-Type: application/json" \
  -d '{"url": "https://github.com/user/repo/blob/main/file.js"}'

# 响应示例
# {
#   "originalUrl": "https://github.com/user/repo/blob/main/file.js",
#   "convertedUrl": "https://your-cdn.com/gh/user/repo@main/file.js",
#   "cached": false
# }

3. 访问 CDN 资源

使用转换后的 URL 直接访问内容：


# 访问转换后的 CDN 资源
curl http://localhost:3000/cnb/hsred/test@main/README.md

4. 管理后台

访问 http://localhost:3000/admin 进入管理后台：

查看统计信息
管理黑名单规则
管理域名白名单
查看操作日志

常见使用场景

场景 1：加速 GitHub 资源访问


# 原始 URL
https://github.com/user/repo/blob/main/README.md

# 转换后
https://your-cdn.com/gh/user/repo@main/README.md

场景 2：转换 npm 包


# 原始 URL
https://unpkg.com/react@18.2.0/umd/react.production.min.js

# 转换后
https://your-cdn.com/npm/react@18.2.0/umd/react.production.min.js

场景 3：保护敏感路径

在管理后台添加黑名单规则：

类型：path
模式：/api/internal
拦截动作：block

所有匹配 /api/internal 的请求将被拦截。

常用命令参考

开发命令


# 启动开发服务器
bun run dev
# 或
npm run dev

# 构建项目
DATABASE_URL="file:./prisma/dev.db" bun run build

# 启动生产服务器
bun run start

# 代码检查
bun run lint

数据库命令


# 推送 schema 到数据库
DATABASE_URL="file:./prisma/dev.db" bun run db:push

# 生成 Prisma Client
bun run db:generate

# 创建数据库迁移
DATABASE_URL="file:./prisma/dev.db" bun run db:migrate

# 重置数据库
DATABASE_URL="file:./prisma/dev.db" bun run db:reset

# 打开 Prisma Studio
npx prisma studio

部署命令


# 构建并启动（Linux/Mac）
DATABASE_URL="file:./prisma/dev.db" bun run build
bun run start

# 使用启动脚本
./start.sh          # Linux/Mac
start.bat           # Windows

# 部署到 Cloud Studio（需要先登录）
# 点击 CloudStudio 集成按钮

实用工具


# 查看实时日志
tail -f dev.log

# 搜索日志中的错误
grep "ERROR" dev.log

# 查看最近的转换记录
grep "CONVERT" dev.log | tail -20

# 数据库备份
cp prisma/dev.db prisma/dev.db.backup.$(date +%Y%m%d)

# 数据库恢复
cp prisma/dev.db.backup.20260110 prisma/dev.db

5 分钟快速体验

1. 安装并启动


# 克隆项目
git clone <repository-url>
cd workspace

# 安装依赖（使用 Bun 更快）
bun install
# 或使用 npm
# npm install

# 初始化数据库
DATABASE_URL="file:./prisma/dev.db" bun run db:push

# 启动开发服务器
bun run dev

服务将在 http://localhost:3000 启动。

2. 转换 URL

使用 curl 测试 URL 转换：


# 转换 GitHub URL
curl -X POST http://localhost:3000/api/convert \
  -H "Content-Type: application/json" \
  -d '{"url": "https://github.com/user/repo/blob/main/file.js"}'

# 响应示例
# {
#   "originalUrl": "https://github.com/user/repo/blob/main/file.js",
#   "convertedUrl": "https://hpyvnhay55-3000.cnb.run/gh/user/repo@main/file.js",
#   "cached": false
# }

3. 访问 CDN 资源

使用转换后的 URL 直接访问内容：


# 访问转换后的 CDN 资源
curl http://localhost:3000/cnb/hsred/test@main/README.md

4. 管理后台

访问 http://localhost:3000/admin 进入管理后台：

查看统计信息
管理黑名单规则
管理域名白名单
查看操作日志

常见使用场景

场景 1：加速 GitHub 资源访问


# 原始 URL
https://github.com/user/repo/blob/main/README.md

# 转换后
https://your-cdn.com/gh/user/repo@main/README.md

场景 2：转换 npm 包


# 原始 URL
https://unpkg.com/react@18.2.0/umd/react.production.min.js

# 转换后
https://your-cdn.com/npm/react@18.2.0/umd/react.production.min.js

场景 3：保护敏感路径

在管理后台添加黑名单规则：

类型：path
模式：/api/internal
拦截动作：block

所有匹配 /api/internal 的请求将被拦截。

API 接口文档

URL 转换

POST /api/convert

转换原始 URL 为 CDN URL。

请求体：


{
  "url": "https://github.com/user/repo/blob/main/file.js"
}

响应：


{
  "originalUrl": "https://github.com/user/repo/blob/main/file.js",
  "convertedUrl": "https://cdn.example.com/gh/user/repo@main/file.js",
  "cached": false
}

内容代理

GET /api/proxy?url=<encoded-url>

通过代理获取原始 URL 的内容。

示例：


GET /api/proxy?url=https%3A%2F%2Fcnb.cool%2Fhsred%2Ftest%2F-%2Fgit%2Fraw%2Fmain%2FREADME.md

CDN 直接访问

GET /<converted-path>

直接访问转换后的路径获取内容。

示例：


GET /cnb/hsred/test@main/README.md

服务状态

GET /api/status

获取服务健康状态和统计信息。

响应：


{
  "healthy": true,
  "totalConversions": 1000,
  "avgResponseTime": 45,
  "timestamp": "2026-01-10T08:00:00.000Z"
}

管理后台 API

认证

POST /api/admin/auth

管理员登录认证。

请求体：


{
  "username": "admin",
  "password": "password"
}

黑名单规则

GET /api/admin/blacklist/rules - 获取黑名单规则列表
POST /api/admin/blacklist/rules - 创建黑名单规则
PUT /api/admin/blacklist/rules - 更新黑名单规则
DELETE /api/admin/blacklist/rules?id=<id> - 删除黑名单规则

域名白名单

GET /api/admin/domains - 获取域名白名单列表
POST /api/admin/domains - 创建域名白名单
PUT /api/admin/domains - 更新域名白名单
DELETE /api/admin/domains?id=<id> - 删除域名白名单

黑名单配置

GET /api/admin/blacklist/config - 获取黑名单配置
POST /api/admin/blacklist/config - 更新黑名单配置

统计信息

GET /api/admin/stats?period=7d

获取转换统计信息。

参数：

period: 时间周期（1d, 7d, 30d, 90d, all）

响应：


{
  "chartData": [...],
  "topDomains": [...],
  "totalStats": {
    "total": 1000,
    "success": 950,
    "failed": 30,
    "blocked": 20,
    "avgResponseTime": 45
  },
  "ruleStats": {
    "blacklistRules": 5,
    "domainWhitelist": 3
  }
}

操作日志

GET /api/admin/logs?page=1&limit=20

获取操作日志列表。

黑名单规则说明

规则类型

1. 路径匹配（path）

检查 URL 路径是否包含指定字符串。

示例：

模式：/README.md
匹配：https://example.com/README.md ✅
匹配：https://example.com/docs/README.md ✅
不匹配：https://example.com/readme.txt ❌

2. 正则表达式（regex）

使用正则表达式进行高级匹配。

示例：

模式：^/api/.*\.json$
匹配：https://example.com/api/v1/users.json ✅
匹配：https://example.com/api/data.json ✅
不匹配：https://example.com/api/v1/users ❌

3. 域名匹配（domain）

检查 URL 的域名是否匹配。

示例：

模式：example.com
匹配：https://example.com/path ✅
匹配：https://api.example.com/path ✅
不匹配：https://other.com/path ❌

拦截动作

1. 拦截（block）

直接返回 403 错误，拒绝访问。

2. 重定向（redirect）

重定向到指定 URL。

配置：

重定向 URL：https://example.com/blocked

3. 自定义响应（custom）

返回自定义的响应内容。

配置：

自定义响应文本：访问被拒绝，请联系管理员

域名白名单规则说明

匹配类型

1. 仅域名（domain）

匹配指定域名下的所有路径。

示例：

域名：github.com
放行：https://github.com/user/repo ✅
放行：https://github.com/user/repo/blob/main/file.js ✅
不放行：https://gitlab.com/user/repo ❌

2. 域名+路径（domain_path）

匹配指定域名下的特定路径前缀。

示例：

域名：github.com
路径模式：/user/repo
放行：https://github.com/user/repo ✅
放行：https://github.com/user/repo/blob/main/file.js ✅
不放行：https://github.com/other/repo ❌

3. 正则表达式（regex）

使用正则表达式进行高级匹配。

示例：

域名：example.com
路径模式：^/api/v\d+/
放行：https://example.com/api/v1/users ✅
放行：https://example.com/api/v2/data ✅
不放行：https://example.com/api/users ❌

优先级说明

数字越大，优先级越高
多个规则同时匹配时，使用优先级最高的规则
默认优先级为 0

转换规则说明

GitHub

原始 URL:


https://github.com/user/repo/blob/main/file.js

转换后:


https://cdn.example.com/gh/user/repo@main/file.js

npm

原始 URL:


https://unpkg.com/package@1.0.0/file.js

转换后:


https://cdn.example.com/npm/package@1.0.0/file.js

cnb.cool

原始 URL:


https://cnb.cool/group/subgroup/project/-/git/raw/main/file.js

转换后:


https://cdn.example.com/cnb/group/subgroup/project@main/file.js

高级配置

系统配置项

在管理后台的"系统配置"中可以配置以下参数：

配置项	说明	默认值
`ACCELERATOR_DOMAIN`	CDN 加速域名	`localhost:3000`
`ENABLE_CACHE`	是否启用缓存	`true`
`CACHE_TTL`	缓存有效期（秒）	`3600`
`REQUEST_TIMEOUT`	请求超时时间（毫秒）	`30000`
`MAX_REDIRECTS`	最大重定向次数	`5`

黑名单高级配置

全局拦截模式


{
  "enabled": true,
  "globalMode": "block",
  "actionOnMatch": "block",
  "redirectUrl": "https://example.com/blocked",
  "customResponse": "访问被拒绝",
  "logMatches": true
}

规则优先级示例


// 高优先级规则（100）
{
  "type": "regex",
  "pattern": "^/api/v\\d+/admin",
  "priority": 100,
  "actionOnMatch": "block"
}

// 中等优先级规则（50）
{
  "type": "path",
  "pattern": "/api",
  "priority": 50,
  "actionOnMatch": "monitor"
}

// 默认优先级规则（0）
{
  "type": "domain",
  "pattern": "blocked.com",
  "priority": 0,
  "actionOnMatch": "redirect",
  "redirectUrl": "https://safe.example.com"
}

性能优化配置

1. 启用响应缓存


// 在 next.config.ts 中配置
const nextConfig: NextConfig = {
  async headers() {
    return [
      {
        source: '/:path*',
        headers: [
          {
            key: 'Cache-Control',
            value: 'public, max-age=3600, s-maxage=3600',
          },
        ],
      },
    ]
  }
}

2. 配置 CDN 回源


# Caddyfile 示例
https://your-cdn.com {
    reverse_proxy localhost:3000
    header / Cache-Control "public, max-age=3600"
}

配置说明

环境变量

创建 .env.local 文件配置环境变量：


# 数据库 URL
DATABASE_URL="file:./prisma/dev.db"

# 管理员密码（可选）
ADMIN_PASSWORD="your_secure_password"

Next.js 配置

主要配置在 next.config.ts：


const nextConfig: NextConfig = {
  output: "standalone",  // 独立部署模式
  typescript: {
    ignoreBuildErrors: true,
  },
  reactStrictMode: false,
  eslint: {
    ignoreDuringBuilds: true,
  },
  // ... 其他配置
}

Tailwind CSS 配置

配置文件在 tailwind.config.ts，支持自定义主题和样式。

常见问题

1. 构建失败

问题： 构建时提示 DATABASE_URL is not set

解决：


DATABASE_URL="file:./prisma/dev.db" bun run build

2. 数据库迁移失败

问题： Prisma 迁移失败

解决：


# 重置数据库
bun run db:reset

# 或手动推送 schema
bun run db:push

3. 端口被占用

问题： 端口 3000 已被使用

解决：


# 修改端口
bun run dev -p 3001

4. 黑名单规则不生效

问题： 配置了黑名单规则但没有拦截请求

检查：

规则是否已启用（enabled = true）
规则优先级是否正确
URL 是否匹配规则模式
查看日志确认规则是否被触发

5. 代理请求超时

问题： 访问某些资源时提示超时

解决：

检查源站是否正常
增加 REQUEST_TIMEOUT 配置
检查网络连接
查看日志获取更多信息

6. 缓存未生效

问题： 每次请求都访问源站，没有使用缓存

检查：

确认 ENABLE_CACHE 配置为 true
检查缓存有效期 CACHE_TTL 设置
查看响应头是否包含缓存标记
清除缓存后重试

监控与日志

查看转换统计

通过 API 获取统计信息：


# 获取最近 7 天的统计
curl http://localhost:3000/api/admin/stats?period=7d

# 响应示例
# {
#   "chartData": [
#     { "date": "2026-01-04", "success": 120, "failed": 5, "blocked": 3 },
#     { "date": "2026-01-05", "success": 150, "failed": 8, "blocked": 2 }
#   ],
#   "topDomains": [
#     { "domain": "github.com", "count": 500 },
#     { "domain": "unpkg.com", "count": 300 }
#   ],
#   "totalStats": {
#     "total": 1000,
#     "success": 950,
#     "failed": 30,
#     "blocked": 20,
#     "avgResponseTime": 45
#   }
# }

查看操作日志


# 获取操作日志
curl http://localhost:3000/api/admin/logs?page=1&limit=20

# 响应示例
# {
#   "logs": [
#     {
#       "id": "xxx",
#       "action": "CREATE",
#       "module": "BlacklistRule",
#       "details": "Created blacklist rule: path - /api/test",
#       "createdAt": "2026-01-10T08:00:00.000Z"
#     }
#   ],
#   "total": 100,
#   "page": 1,
#   "limit": 20
# }

日志文件位置

开发日志：/workspace/dev.log
服务器日志：/workspace/server.log
构建日志：构建过程中输出到终端

数据库日志查询

使用 Prisma Studio 查看数据库：


npx prisma studio

这将启动一个可视化的数据库管理界面，默认在 http://localhost:5555。

最佳实践

1. 规则管理

优先使用明确的路径匹配，正则表达式可能影响性能
为规则设置合理的优先级，避免冲突
定期审查和清理不再使用的规则
使用描述性的规则名称和说明

2. 安全建议

不要在配置中暴露敏感信息
定期备份数据库文件（prisma/dev.db）
在生产环境使用强密码管理后台
启用日志记录并定期审查

3. 性能优化

合理设置缓存时间
使用 CDN 加速静态资源
监控平均响应时间
定期清理过期的转换记录

4. 运维建议

定期备份数据库
监控磁盘空间使用
配置日志轮转
设置告警阈值

安全注意事项

敏感信息保护

不要提交敏感配置：
- .env 文件
- 数据库文件（*.db）
- 包含密码的配置
使用环境变量：


# .env.local
DATABASE_URL="file:./prisma/dev.db"
ADMIN_PASSWORD="your_secure_password"

数据库安全：
- 定期备份数据库
- 使用强密码（如果使用外部数据库）
- 限制数据库访问权限

访问控制

管理后台保护：
- 设置强密码
- 使用 HTTPS
- 限制访问 IP（如需要）
API 限流：
- 实现请求频率限制
- 防止 DDoS 攻击
- 监控异常访问

贡献指南

欢迎贡献代码！请遵循以下步骤：

Fork 本仓库
创建特性分支：git checkout -b feature/amazing-feature
提交更改：git commit -m 'Add amazing feature'
推送到分支：git push origin feature/amazing-feature
提交 Pull Request

代码规范

使用 TypeScript 编写代码
遵循 ESLint 规则
添加必要的注释和文档
编写测试用例

提交信息格式


<type>: <subject>

<body>

<footer>

类型：

feat: 新功能
fix: 修复
docs: 文档
style: 格式
refactor: 重构
test: 测试
chore: 构建/工具

更新日志

Version 0.1.0 (2026-01-10)

✨ 初始版本发布
✨ 支持 GitHub、npm、cnb.cool URL 转换
✨ 黑名单和白名单管理
✨ 转换统计和日志记录
✨ 可视化管理后台
📝 完整的文档

许可证

本项目采用 MIT 许可证。

联系方式

如有问题或建议，请通过以下方式联系：

提交 Issue
发起 Pull Request
查看项目文档

致谢

感谢以下开源项目的支持：

如有问题或建议，请提交 Issue 或 Pull Request。

35/F,Tencent Building,Kejizhongyi Avenue,Nanshan District,Shenzhen

京ICP备11018762号-111

URL 转换与 CDN 代理服务

目录

功能特性

核心功能

支持的源站

技术栈

前端

后端

开发工具

项目结构

数据库模型

SystemConfig（系统配置）

BlacklistRule（黑名单规则）

BlacklistConfig（黑名单配置）

DomainRule（域名白名单）

ConversionRecord（转换记录）

ConversionStats（转换统计）

OperationLog（操作日志）

ComplianceConfig（合规日志配置）

User（用户认证）

安装与部署

环境要求

快速开始

1. 克隆项目

2. 安装依赖

3. 初始化数据库

4. 启动开发服务器

生产部署

1. 构建项目

2. 启动生产服务器

Docker 部署（可选）

快速开始指南

5 分钟快速体验

1. 安装并启动

2. 转换 URL

3. 访问 CDN 资源

4. 管理后台

常见使用场景

场景 1：加速 GitHub 资源访问

场景 2：转换 npm 包

场景 3：保护敏感路径

常用命令参考

开发命令

数据库命令

部署命令

实用工具

5 分钟快速体验

1. 安装并启动

2. 转换 URL

3. 访问 CDN 资源

4. 管理后台

常见使用场景

场景 1：加速 GitHub 资源访问

场景 2：转换 npm 包

场景 3：保护敏感路径

API 接口文档

URL 转换

内容代理

CDN 直接访问

服务状态

管理后台 API

认证

黑名单规则

域名白名单

黑名单配置

统计信息

操作日志

黑名单规则说明

规则类型

1. 路径匹配（path）

2. 正则表达式（regex）

3. 域名匹配（domain）

拦截动作

1. 拦截（block）

2. 重定向（redirect）

3. 自定义响应（custom）

域名白名单规则说明

匹配类型

1. 仅域名（domain）

2. 域名+路径（domain_path）