# backend **Repository Path**: zesso/backend ## Basic Information - **Project Name**: backend - **Description**: 企业级智能短链 + 二维码 + 落地页 + 渠道统计 + SaaS 多租户 + 私域引流平台 - **Primary Language**: PHP - **License**: Not specified - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-08-26 - **Last Updated**: 2026-08-26 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 虎王云智慧引流短链系统（HWCloud Link） > 企业级智能短链 + 二维码 + 落地页 + 渠道统计 + SaaS 多租户 + 私域引流平台 基于 ThinkPHP 8 + Vue 3 + Element Plus 构建，前后端统一站点部署，开箱即用。 --- ## ✨ 功能特性 ### 核心功能 | 模块 | 说明 | |------|------| | 🔗 **短链管理** | 自定义短码 / 随机生成、过期时间、访问密码、跳转类型（301/302/JS跳转）、批量操作 | | 📱 **二维码管理** | 在线生成 PNG/SVG 二维码、自定义尺寸与颜色、批量下载 | | 📄 **落地页管理** | 6 套内置模板（推广页/下载页/表单页/促销页/品牌页/电商页）、自定义 HTML、在线编辑 | | 📢 **渠道管理** | 渠道分组、渠道码追踪、独立统计 | | 🌐 **域名管理** | 多域名绑定、跳转域名轮询、过期提醒 | | 📊 **数据统计** | 访问概览、趋势图表、设备分析、渠道分析、地区分析（ECharts 可视化） | | 📋 **访问日志** | 详细访问记录、Excel 导出、多维筛选 | | 👥 **商户管理** | SaaS 多租户、租户隔离、套餐绑定、状态控制 | | 🛡️ **角色权限** | RBAC 细粒度权限控制、4 角色 20 权限、自定义角色与权限分配 | | ⚙️ **系统设置** | 全局配置、分组管理、实时保存 | | 🔑 **认证中心** | JWT 鉴权、账号/手机号登录、找回密码、验证码 | | 📦 **套餐管理** | 短链额度、有效期、功能权限配置 | ### 技术亮点 - **统一站点部署**：前端构建产物集成到后端 `/web/` 路径，单域名单 Nginx 即可运行 - **多租户隔离**：基于 tenant_id 的数据隔离，管理员可查看全平台数据 - **RBAC 权限**：细粒度接口权限控制，权限码注入 JWT - **API 限流**：基于 Redis 的滑动窗口限流（60 次/分钟） - **IP 地区解析**：内置 IpRegionService，支持 ip2region 离线数据库 - **短信服务**：双渠道支持（阿里云/腾讯云），验证码场景全覆盖 - **到期提醒**：Console 命令 `tenant:expire-remind`，可接入定时任务 - **访问日志导出**：PhpSpreadsheet 生成 Excel，联表查询，上限 5000 条 --- ## 🛠️ 技术栈 ### 后端 - **PHP** ≥ 8.0（推荐 8.2+） - **ThinkPHP** 8.x（多应用模式：admin / api / index） - **MySQL** 5.7+ / 8.0 - **Redis**（predis 客户端，非 PHP 扩展） - **predis/predis** 2.x — Redis 客户端 - **firebase/php-jwt** 6.x — JWT 鉴权 - **chillerlan/php-qrcode** 5.x — 二维码生成 - **phpoffice/phpspreadsheet** 3.x — Excel 导出 ### 前端 - **Vue** 3.5+（Composition API） - **Element Plus** 2.14+ - **Vue Router** 4.x（History 模式） - **Pinia** 4.x（状态管理） - **ECharts** 6.x（数据可视化） - **Axios** 1.x（HTTP 请求） - **Vite** 8.x（构建工具） --- ## 📁 项目结构 ``` hwcloud-link/ ├── backend/ # 后端项目（ThinkPHP 8） │ ├── app/ │ │ ├── admin/ # 管理后台应用 │ │ │ ├── controller/ # 14 个控制器 │ │ │ │ ├── Auth.php # 认证（登录/登出/改密/找回密码） │ │ │ │ ├── TenantController.php # 商户管理 │ │ │ │ ├── UserController.php # 用户管理 │ │ │ │ ├── ShortLinkController.php # 短链管理 │ │ │ │ ├── ChannelController.php # 渠道管理 │ │ │ │ ├── LandingPageController.php # 落地页管理 │ │ │ │ ├── QrcodeController.php # 二维码管理 │ │ │ │ ├── DomainController.php # 域名管理 │ │ │ │ ├── PackageController.php # 套餐管理 │ │ │ │ ├── StatsController.php # 数据统计 │ │ │ │ ├── VisitLogController.php # 访问日志 + Excel导出 │ │ │ │ ├── RoleController.php # 角色权限 │ │ │ │ ├── SystemSettingController.php # 系统设置 │ │ │ │ └── BaseController.php # 基类控制器 │ │ │ └── route/app.php # Admin 路由（含 JWT 中间件） │ │ ├── api/ # 短链跳转 API 应用 │ │ │ ├── controller/ │ │ │ │ ├── Redirect.php # 短链跳转核心 │ │ │ │ ├── Link.php # 开放 API │ │ │ │ └── BaseController.php │ │ │ └── route/app.php │ │ ├── index/ # SPA 入口应用 │ │ │ ├── controller/Index.php # 返回前端 index.html │ │ │ └── route/app.php │ │ └── common/ # 公共代码 │ │ ├── model/ # 21 个数据模型 │ │ ├── service/ # 6 个服务层 │ │ │ ├── AuthService.php # 认证服务 │ │ │ ├── ShortLinkService.php # 短链服务 │ │ │ ├── StatsService.php # 统计服务 │ │ │ ├── RbacService.php # RBAC 权限服务 │ │ │ ├── SmsService.php # 短信服务 │ │ │ └── IpRegionService.php # IP 地区解析 │ │ ├── middleware/ # 4 个中间件 │ │ │ ├── JwtAuth.php # JWT 鉴权 │ │ │ ├── Cors.php # 跨域处理 │ │ │ ├── RateLimit.php # API 限流 │ │ │ └── NormalizeUrl.php # URL 规范化 │ │ └── command/ │ │ └── TenantExpireRemind.php # 租户到期提醒命令 │ ├── config/ # ThinkPHP 配置 │ ├── frontend-src/ # 前端源码（Vue 3） │ │ ├── src/ │ │ │ ├── views/ # 15 个页面组件 │ │ │ ├── api/ # 13 个 API 模块 │ │ │ ├── router/ # Vue Router │ │ │ ├── store/ # Pinia 状态管理 │ │ │ └── utils/request.js # Axios 封装 │ │ ├── vite.config.js # Vite 配置 │ │ └── package.json │ ├── public/ # ThinkPHP 公共目录 │ ├── route/ # 全局路由 │ ├── .env.example # 环境配置示例 │ ├── composer.json │ └── nginx-vhost.conf # Nginx 配置参考 ├── database/ # 数据库 SQL 文件 │ └── huwang_link.sql # 完整建表 + 种子数据 ├── DEPLOY.md # 部署文档 └── README.md ``` --- ## 🚀 快速开始 ### 环境要求 | 组件 | 版本 | 说明 | |------|------|------| | PHP | ≥ 8.0 | 需启用：pdo_mysql、openssl、curl、mbstring、fileinfo、gd | | MySQL | 5.7+ / 8.0 | 字符集 utf8mb4 | | Redis | 5.0+ | 用于限流/缓存/验证码 | | Nginx | 1.15+ | 或 Apache | | Node.js | 18+ | 仅构建前端需要 | ### 1. 克隆项目 ```bash git clone https://github.com/your-username/hwcloud-link.git cd hwcloud-link ``` ### 2. 导入数据库 ```sql CREATE DATABASE huwang_link DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; USE huwang_link; SOURCE database/huwang_link.sql; ``` SQL 文件包含 23 张表 + 种子数据（管理员账号、4 角色 20 权限 44 关联、6 落地页模板、5 套餐）。 ### 3. 安装后端依赖 ```bash cd backend composer install ``` ### 4. 配置环境 ```bash cp .env.example .env ``` 编辑 `.env`，修改数据库 / Redis / JWT 配置： ```ini [DATABASE] TYPE = mysql HOSTNAME = 127.0.0.1 DATABASE = huwang_link USERNAME = root PASSWORD = your_password HOSTPORT = 3306 CHARSET = utf8mb4 [REDIS] HOST = 127.0.0.1 PORT = 6379 PASSWORD = SELECT = 0 [JWT] SECRET = your-random-secret-key-at-least-32-chars-long EXPIRE = 86400 [RATE_LIMIT] ENABLE = true MAX_REQUESTS = 60 WINDOW = 60 ``` ### 5. 构建前端 ```bash cd frontend-src npm install npm run build # 产物自动输出到 ../web/ ``` ### 6. 配置 Nginx 参考 `backend/nginx-vhost.conf`，核心配置： ```nginx server { listen 80; server_name your-domain.com; root /path/to/backend; index index.php; # 前端静态资源缓存 location /web/assets/ { expires 30d; add_header Cache-Control "public, immutable"; } # 所有非文件请求转发到 ThinkPHP location / { if (!-e $request_filename) { rewrite ^(.*)$ /index.php?s=/$1 last; } } # PHP-FPM location ~ \.php$ { fastcgi_pass 127.0.0.1:9000; fastcgi_index index.php; fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; include fastcgi_params; } # 禁止访问敏感目录 location ~ /(runtime|vendor|frontend-src)/ { deny all; } } ``` ### 7. 访问系统 | 地址 | 说明 | |------|------| | `http://your-domain.com/admin` | 管理后台 | | `http://your-domain.com/s/{code}` | 短链跳转 | **默认账号**：`admin` / `admin123` > ⚠️ **首次登录后请立即修改密码** --- ## 📡 API 概览 ### Admin API（需 JWT 鉴权） #### 认证相关 | 方法 | 路径 | 说明 | |------|------|------| | POST | `/admin/auth/login` | 账号密码登录 | | POST | `/admin/auth/login/phone` | 手机号验证码登录 | | POST | `/admin/auth/send-code` | 发送短信验证码 | | GET | `/admin/auth/info` | 获取当前用户信息 | | PUT | `/admin/auth/change-password` | 修改密码 | | POST | `/admin/auth/logout` | 退出登录 | | POST | `/admin/auth/forgot-password` | 忘记密码 | | POST | `/admin/auth/verify-reset-token` | 验证重置令牌 | | POST | `/admin/auth/reset-password` | 重置密码 | #### 业务管理 | 方法 | 路径 | 说明 | |------|------|------| | GET / POST | `/admin/tenant` | 租户列表 / 创建 | | GET / PUT / DELETE | `/admin/tenant/:id` | 租户详情 / 更新 / 删除 | | PUT | `/admin/tenant/:id/toggle-status` | 切换租户状态 | | POST | `/admin/tenant/:id/reset-password` | 重置租户密码 | | GET / POST | `/admin/user` | 用户列表 / 创建 | | GET / PUT / DELETE | `/admin/user/:id` | 用户 CRUD | | GET / POST | `/admin/link` | 短链列表 / 创建 | | GET / PUT / DELETE | `/admin/link/:id` | 短链 CRUD | | PUT | `/admin/link/:id/toggle-status` | 切换短链状态 | | GET | `/admin/link/:id/stats` | 短链统计 | | POST | `/admin/link/batch` | 批量操作 | | GET / POST | `/admin/channel` | 渠道列表 / 创建 | | GET | `/admin/channel/all` | 全部渠道（下拉选择用） | | GET / POST | `/admin/landing-page` | 落地页列表 / 创建 | | GET | `/admin/landing-page/templates` | 落地页模板列表 | | GET / POST | `/admin/qrcode` | 二维码列表 | | POST | `/admin/qrcode/generate` | 生成二维码 | | GET | `/admin/qrcode/:id/download` | 下载二维码 | | GET / POST | `/admin/domain` | 域名列表 / 创建 | | GET / POST | `/admin/package` | 套餐列表 / 创建 | | GET | `/admin/stats/overview` | 统计概览 | | GET | `/admin/stats/trend` | 趋势统计（近 N 天） | | GET | `/admin/stats/device` | 设备分布统计 | | GET | `/admin/stats/channel` | 渠道分布统计 | | GET | `/admin/stats/region` | 地区分布统计 | | GET | `/admin/visit-log` | 访问日志列表 | | GET | `/admin/visit-log/export` | 导出访问日志（Excel） | | GET / POST | `/admin/role` | 角色列表 / 创建 | | GET | `/admin/role/permissions` | 权限树 | | GET / PUT / DELETE | `/admin/role/:id` | 角色 CRUD | | GET / POST | `/admin/setting` | 系统设置读取 / 保存 | ### 公开 API | 方法 | 路径 | 说明 | |------|------|------| | GET | `/s/:code` | 短链跳转（302 重定向） | | GET | `/api/landing/:id` | 落地页展示 | | POST | `/api/landing/:id/click` | 落地页点击追踪 | --- ## 🗄️ 数据库表结构 共 23 张表： | 表名 | 说明 | 种子数据 | |------|------|----------| | `users` | 系统用户 | 3 条 | | `tenants` | 租户（商户） | 4 条 | | `short_links` | 短链 | — | | `link_rules` | 短链跳转规则 | — | | `link_domains` | 跳转域名 | — | | `channels` | 渠道 | 2 条 | | `landing_pages` | 落地页 | — | | `landing_templates` | 落地页模板 | 6 套 | | `qrcodes` | 二维码 | — | | `visits` | 访问记录 | — | | `clicks` | 点击记录 | — | | `packages` | 套餐 | 5 条 | | `tenant_packages` | 租户-套餐关联 | — | | `orders` | 订单 | — | | `agents` | 代理商 | — | | `agent_commissions` | 代理佣金 | — | | `roles` | 角色 | 4 个 | | `permissions` | 权限 | 20 个 | | `role_permissions` | 角色-权限关联 | 44 条 | | `user_roles` | 用户-角色关联 | 1 条 | | `operation_logs` | 操作日志 | — | | `system_settings` | 系统设置 | 7 条 | | `ip_blacklist` | IP 黑名单 | — | | `password_resets` | 密码重置令牌 | — | --- ## 🔧 进阶配置 ### Redis 使用 `predis/predis` 纯 PHP 客户端，**无需安装 PHP Redis 扩展**。用于： - API 限流计数器（滑动窗口） - 短链缓存（含负缓存机制） - 验证码存储 ### 短信服务 支持阿里云和腾讯云双渠道，在 `.env` 中配置： ```ini [SMS] PROVIDER = aliyun # aliyun / tencent ACCESS_KEY = your-access-key SECRET_KEY = your-secret-key SIGN_NAME = 你的签名 TEMPLATE_LOGIN = SMS_VERIFY_CODE ``` > 未配置时自动降级为模拟发送（返回成功但不实际发送） ### IP 地区解析 `IpRegionService` 支持 [ip2region](https://github.com/lionsoul2014/ip2region) 离线数据库。将 `ip2region.xdb` 放入 `extend/` 目录即可启用。未配置时返回 "未知"。 ### 租户到期提醒 ```bash # 手动执行 php think tenant:expire-remind # 推荐：加入 crontab 每日上午 9 点执行 # 0 9 * * * cd /path/to/backend && php think tenant:expire-remind ``` ### RBAC 权限种子 系统预置 4 个角色： | 角色 | code | 权限数 | |------|------|--------| | 超级管理员 | super_admin | 20（全部） | | SaaS 商户 | tenant_admin | 自定义 | | 商户员工 | tenant_staff | 自定义 | | 代理商 | agent | 自定义 | --- ## 🐛 常见问题 ### 前端页面白屏 - 检查 `backend/web/` 目录是否存在构建产物（`npm run build`） - Nginx `root` 是否指向 `backend/` 目录 - 浏览器 Console 是否有 JS 加载 404 错误 ### API 返回 500 - 检查 `.env` 数据库配置是否正确 - 检查 PHP 版本 ≥ 8.0 且已启用所需扩展 - 查看 `runtime/admin/log/` 下的错误日志 ### 列表 API 带尾部斜杠返回 500 ThinkPHP 路由组内 `Route::get('/')` 与带斜杠的 URL 不兼容。前端 API 路径已统一为**不带尾部斜杠**（如 `/admin/tenant` 而非 `/admin/tenant/`）。 ### Composer 安装失败 确保 PHP 版本 ≥ 8.0。如遇 PhpSpreadsheet 依赖冲突： ```bash composer require phpoffice/phpspreadsheet:^3.0 --with-all-dependencies ``` ### Redis 连接失败 确认 Redis 服务已启动：`redis-cli ping` 返回 `PONG`。如不需要 Redis，限流和缓存功能将自动降级。 --- ## 📷 系统截图 > 可在此添加管理后台各页面截图 --- ## 📄 License Apache-2.0 --- ## 🙏 致谢 - [ThinkPHP](https://www.thinkphp.cn/) — 高性能 PHP 框架 - [Vue.js](https://vuejs.org/) — 渐进式 JavaScript 框架 - [Element Plus](https://element-plus.org/) — Vue 3 UI 组件库 - [ECharts](https://echarts.apache.org/) — 数据可视化库 - [ip2region](https://github.com/lionsoul2014/ip2region) — 离线 IP 地址定位库