# landing

**Repository Path**: xbkjlm/landing

## Basic Information

- **Project Name**: landing
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-26
- **Last Updated**: 2025-12-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Landing Admin Backend

## 项目简介

Landing Admin 是一个基于 Node.js 的落地页管理后台系统，提供短链管理、站点管理、访问控制等功能。该系统采用 Express.js 框架构建，使用 MySQL 数据库存储数据，Redis 作为缓存层，支持Prometheus 指标监控和完整的日志记录体系。

## 技术栈

- **运行时**: Node.js
- **框架**: Express.js
- **数据库**: MySQL + Sequelize ORM
- **缓存**: Redis
- **认证**: JWT (JSON Web Token)
- **日志**: Winston
- **监控**: Prometheus Client
- **工具库**: bcryptjs、axios、uuid、multer 等

## 项目结构

```
landing-admin/
├── .trae/                      # Trae IDE 配置目录
│   ├── documents/              # 开发文档
│   └── rules/                  # 项目规则
├── config/                     # 配置文件
│   ├── app.js                 # 应用配置
│   ├── database.js            # 数据库配置
│   ├── redis.js               # Redis 配置
│   └── countries.json         # 国家语言时区映射
├── controller/                 # 控制器层
│   ├── userController.js      # 用户认证控制器
│   ├── shortLinkController.js # 短链控制器
│   ├── siteController.js      # 站点控制器
│   ├── siteTemplateController.js # 站点模板控制器
│   ├── translationController.js # 翻译控制器
│   ├── supportLinkController.js # 客服链接控制器
│   ├── accessLogController.js # 访问日志控制器
│   ├── logController.js       # 系统日志控制器
│   ├── dashboardController.js # 仪表盘控制器
│   └── homeController.js      # 首页控制器
├── middleware/                 # 中间件
│   ├── authMiddleware.js      # 认证中间件
│   ├── accessControlMiddleware.js # 访问控制中间件
│   ├── errorMiddleware.js     # 错误处理中间件
│   ├── logMiddleware.js       # 日志中间件
│   ├── metricsMiddleware.js   # 指标监控中间件
│   └── smartRedirectMiddleware.js # 智能重定向中间件
├── models/                     # 数据模型
│   ├── User.js                # 用户模型
│   ├── ShortLink.js           # 短链模型
│   ├── Site.js                # 站点模型
│   ├── SiteTemplate.js        # 站点模板模型
│   ├── Translation.js         # 翻译模型
│   ├── SupportLink.js         # 客服链接模型
│   ├── AccessLog.js           # 访问日志模型
│   ├── SystemLog.js           # 系统日志模型
│   ├── DeviceEnvFull.js       # 设备环境模型
│   └── index.js               # 模型初始化
├── public/                     # 静态资源
│   ├── admin/                 # 管理后台前端
│   ├── landing/               # 落地页模板
│   ├── landing_module/        # 落地页模块
│   └── shortLink/             # 短链访问页面
├── routes/                     # 路由定义
├── schedule/                   # 定时任务
│   └── logCleanupTask.js      # 日志清理任务
├── script/                     # 脚本文件
│   ├── syncDB.js              # 数据库同步脚本
│   └── seedDB.js              # 数据库初始化脚本
├── services/                   # 业务逻辑层
├── utils/                      # 工具函数
│   ├── responseUtils.js       # 统一响应工具
│   ├── authUtils.js           # 认证工具
│   ├── deviceEnvUtils.js      # 设备环境工具
│   └── requestHeaderUtils.js  # 请求头工具
├── app.js                      # 应用入口文件
├── package.json               # 项目配置
└── ecosystem.config.js        # PM2 配置
```

## 功能模块

### 用户认证模块
- 用户登录
- Token 验证
- 单账号管理模式 (默认账号: admin, 密码: admin123)

### 短链管理模块
- 创建短链
- 获取短链列表
- 更新短链信息
- 删除短链
- 访问控制配置

### 站点管理模块
- 创建站点
- 获取站点列表
- 获取站点详情
- 更新站点信息
- 删除站点

### 站点模板管理模块
- 模板列表
- 模板详情
- 模板创建与更新
- 模板文件管理 (支持 ZIP 包上传)

### 翻译管理模块
- 翻译资源配置
- 多语言支持

### 客服链接管理模块
- 客服链接配置
- 关联短链管理

### 日志与监控模块
- 访问日志记录
- 系统日志记录
- Prometheus 指标监控
- 日志自动清理任务

## 安装与运行

### 环境要求
- Node.js >= 14
- MySQL >= 5.7
- Redis >= 6.0

### 安装依赖
```bash
npm install
```

### 环境配置
创建 `.env` 文件，配置以下环境变量:

```env
# 数据库配置
DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASSWORD=your_password
DB_NAME=landing_admin

# 生产环境数据库配置
DB_HOST_PROD=your_prod_host
DB_PORT_PROD=3306
DB_USER_PROD=your_prod_user
DB_PASSWORD_PROD=your_prod_password
DB_NAME_PROD=landing_admin_prod

# Redis 配置
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=your_redis_password

# 应用配置
NODE_ENV=development
PORT=3000

# JWT 配置
JWT_SECRET=your_jwt_secret_key
JWT_EXPIRES_IN=7d
```

### 数据库初始化
```bash
# 同步数据库模型
npm run syncdb

# 初始化数据
npm run seeddb
```

### 启动服务
```bash
# 开发模式
npm run dev

# 生产模式
npm start
```

### PM2 部署
```bash
pm2 start ecosystem.config.js
```

## API 响应规范

所有接口统一使用 `responseUtils.js` 中的方法返回响应，响应格式如下:

```json
{
  "code": 200,
  "message": "操作成功",
  "data": {}
}
```

分页接口响应格式:
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "list": [],
    "total": 0,
    "page": 1,
    "pageSize": 10
  }
}
```

错误响应格式:
```json
{
  "code": 400,
  "message": "错误信息"
}
```

## 访问控制说明

### 总体原则
- Redis 结果优先：命中 `blacklist`/`honey` 直接按记录处理，不再做检测。
- 只有 Redis 未命中或记录为 `real` 才会进入检测链路。
- 不设置过期或纠错策略，误判为蜜罐会一直保持蜜罐。

### 请求前置要求
- 路径参数必须完整：`accessType/shortCode/deviceHash`。
- 必须携带设备环境数据 `deviceEnvData`，为空直接拒绝。

### 参数说明
| 参数 | 作用 | 必要性 |
|------|------|--------|
| `accessType` | 访问类型，用于区分短链/子站 | 必填 |
| `shortCode` | 短链/子站编码 | 必填 |
| `deviceHash` | 设备环境数据哈希值，用于校验设备环境数据 | 必填 |
| `deviceEnvData` | 设备环境数据，用于校验设备环境数据，为以后可能的检测增加数据支持 | 必填 |

### 检测流程

1. 校验路径参数与设备环境数据
2. 查找短链/子站记录，不存在直接拒绝
3. 读取 Redis：
   - 命中 `blacklist`/`honey`：直接走对应链接
   - 命中 `real` 或未命中：进入后续检测
4. 若 `accessControl.enabled` 为 `true`，先执行三项"信息检测"：
   - `requiredHeadersCheck`：缺必需请求头 → 走蜜罐
   - `deviceEnvCheck`：设备环境与请求头不一致 → 走蜜罐
   - `countryLanguageTimezoneCheck`：国家/语言/时区不匹配 → 走蜜罐
5. 若仍为正常链接，执行白名单校验：
   - `allowedCountries/allowedLanguages/allowedTimezones/allowedDevices` 中任一"不为空且未命中" → 走黑名单
6. 计算最终跳转链接并写入 Redis
7. 写访问日志（AccessLog）

### accessControl 配置字段

| 字段 | 说明 |
|------|------|
| `enabled` | 是否启用访问控制。仅当为 `true` 时，才执行"信息检测 + 白名单校验" |
| `requiredHeadersCheck` | 为 `true` 时必须携带必需请求头，缺任意一项走蜜罐链接 |
| `deviceEnvCheck` | 为 `true` 时 `deviceEnvData` 与请求头一致性必须通过，不一致走蜜罐链接 |
| `countryLanguageTimezoneCheck` | 为 `true` 时要求国家/语言/时区匹配，不匹配走蜜罐链接 |
| `allowedCountries` | 不为空时，国家必须命中，否则走黑名单链接 |
| `allowedLanguages` | 不为空时，语言必须命中，否则走黑名单链接 |
| `allowedTimezones` | 不为空时，时区必须命中，否则走黑名单链接 |
| `allowedDevices` | 不为空时，设备类型必须命中，否则走黑名单链接 |
| `defaultAction` | 当前流程不再用于拦截，仅保留配置字段 |

### 必需请求头检测 (requiredHeadersCheck)

**目标**: 识别低质量自动化访问（如 curl/wget）和异常爬虫。

**检测规则**:
- 仅在 `enabled=true` 且 `requiredHeadersCheck=true` 时生效
- 需要携带完整的必需请求头：
  - `sec-ch-ua-platform`
  - `sec-ch-ua-full-version`
  - `referer`
  - `accept-language`
  - `cf-connecting-ip`
  - `cf-ipcountry`
  - `cf-timezone`
- 缺任意一项，直接判定为异常访问，走蜜罐链接

### 设备环境检测 (deviceEnvCheck)

**目标**: 识别设备信息与请求头不一致的可疑访问（含代理/脚本伪装）。

**检测规则**:
- 仅在 `enabled=true` 且 `deviceEnvCheck=true` 时生效
- 对比 `deviceEnvData` 与请求头的关键字段：
  - `user-agent`
  - `accept-language`（数组全量一致）
  - `cf-timezone`（或 `x-timezone`）
  - `sec-ch-ua-platform`
- 任一不一致，直接判定为异常访问，走蜜罐链接

### 国家语言时区检测 (countryLanguageTimezoneCheck)

**目标**: 识别国家/语言/时区组合异常的访问。

**检测规则**:
- 仅在 `enabled=true` 且 `countryLanguageTimezoneCheck=true` 时生效
- 使用 `countries.json` 的映射表进行匹配：
  - 国家必须匹配可用的语言与时区组合
- 不匹配时走蜜罐链接

### 结果判定

| 结果 | 触发条件 |
|------|----------|
| 拒绝 | 缺少必要参数或设备环境数据为空 |
| 蜜罐 | 任一"信息检测"不合格 |
| 黑名单 | 白名单任一未命中 |
| 正常 | 通过所有检测，返回真实链接 |

## 开发规范

1. **命名规范**: 所有变量、函数、文件夹采用驼峰命名法
2. **数据库操作**: 必须使用 Sequelize 方法，禁止使用原始 SQL
3. **接口响应**: 必须使用 `responseUtils.js` 中的方法返回统一响应
4. **HTTP 状态码**: 操作成功统一返回 200 状态码
5. **代码注释**: 每个函数需要 JSDoc 注释，包含函数作用、参数、返回值、异常等信息

## 可用脚本

| 命令 | 说明 |
|------|------|
| `npm start` | 生产模式启动 |
| `npm run dev` | 开发模式启动（使用 nodemon） |
| `npm run test` | 运行测试 |
| `npm run lint` | 代码检查 |
| `npm run syncdb` | 同步数据库模型 |
| `npm run seeddb` | 初始化数据库数据 |

## 许可证

ISC