8v4 短网址 · 产品与运维文档

版本：V3.9.1（2026-08-10）｜ 部署环境：phpstudy（PHP 8.2.9 + MySQL 5.7 / SQLite 双兼容）

一、项目概述

8v4 短网址是一个部署在自己服务器上的多用户短链接系统：生成短链、解短链、二维码生成/解析、积分经济、游客配额、短链与二维码过期时间、二维码生成统计管理，全套后台管理。

• 定位：自用 / 团队用的短链服务，替代第三方短链平台，数据自主可控
• 技术栈：PHP 8.2 原生（无框架）+ MySQL/SQLite 双兼容 + 原生 JS（qrcode.js / jsQR）
• 设计风格：扁平化 + 多彩配色 + 深色主题切换 + 响应式
• 入口：前台 index.php，后台 admin.php

目录结构

站点根目录/
├── index.php         # 前台入口（首页/登录注册/用户中心/解短链/建链API）
├── admin.php         # 后台入口（仪表盘/短链/用户/激活码/积分/权限/过期/二维码管理/快捷工具/设置/备份）
├── db.php            # 数据库封装、建表、全部业务函数（SQLite/MySQL 双兼容）
├── config.php        # 配置：数据库、短链域名、站点名、管理员密码
├── assets/
│   ├── style.css     # 全部样式（含深色主题变量）
│   ├── app.js        # 前台交互（建链/主题/二维码/复制）
│   ├── admin.js      # 后台交互
│   ├── qrcode.min.js # 二维码生成库
│   └── jsqr.min.js   # 二维码解析库
├── data/             # 数据目录（SQLite 模式放库文件，已加防下载保护）
├── nginx.conf.txt    # phpstudy Nginx 干净短链配置片段（示例）
└── favicon.ico

二、功能清单

前台（index.php）

| 功能 | 说明 | |---|---| | 生成短链 | 粘贴长链接生成短码；可选有效期；高级用户可自定义短码 | | 解短链 | 输入短码/短链/?u= 任意格式，显示原始地址+点击量，不跳转 | | 二维码生成 | 输入任意网址/文本生成本地二维码（工具 tab） | | 二维码解析 | 上传图片识别二维码内容（jsQR，本地处理） | | 游客配额 | 后台可设游客免费生成 N 条短链，Cookie 计数 | | 登录/注册 | 注册送积分；无邮箱验证（邮箱+密码） | | 使用帮助/权限对比 | 首页展示操作指引 + 各档位权限对比表 |

用户中心

• 我的短链：短码/目标/点击/状态/过期/时间，复制、二维码、删除
• 积分明细：每笔变动（加减、原因、时间）
• 激活高级：输入激活码升级高级用户
• 账号设置：改昵称、改密码

后台

| 菜单 | 功能 | |---|---| | 仪表盘 | 短链/启用中/点击/今日 统计 + 热门短链 + 用户统计 | | 短链管理 | 新建（含有效期）/搜索/按用户筛选/启停/编辑/删除 | | 用户管理 | 新增用户、启停、高级切换、+10/-10/自定义积分 | | 激活码 | 批量生成/导出 CSV/搜索/状态管理 | | 积分管理 | 总余额/今日发放/今日消耗 + 全用户流水（筛选/分页） | | 权限管理 | 5 项功能 × 游客/普通/高级 三档，即时生效 | | 过期时间 | 短链接默认有效期（三档）+ 二维码默认有效期（三档） | | 二维码管理 | 生成总次数/今日/独立/用户统计 + 记录列表（分类/来源/过期/删除/筛选） | | 快捷工具 | 二维码生成 + 解析（后台可用） | | 系统设置 | 站点名/描述/分页/短码长度/跳转类型/积分参数/游客次数/密码/备份 |

三、权限与积分体系

三档身份

| 身份 | 说明 | |---|---| | 游客 | 未登录；可解短链/二维码（按权限档位）；可生成短链（按 guest_limit 配额） | | 普通用户 | 注册即得；建链扣积分；不能自定义短码 | | 高级用户 | 激活码升级；自定义短码 + 免费建链 + 激活赠送积分 |

权限表

| 功能 | 默认档位 | |---|---| | 生成短链 | 登录用户（游客另由配额控制） | | 自定义短码 | 高级用户 | | 解短链 | 所有人 | | 二维码生成 | 所有人 | | 二维码解析 | 所有人 |

积分规则

• 注册赠送：credit_register（默认 20）
• 每链消耗：credit_per_link（默认 1，高级用户 0）
• 激活赠送：credit_activate（默认 100）
• 管理员可对任意用户 +10/-10 或自定义任意数值（正负均可），实时写流水

激活码

• 后台批量生成（可备注），支持导出 CSV
• 一码一用，用过即失效；激活后 activated_at 记录时间

四、过期时间机制

规则：建链时若用户没选「有效期」，按创建者身份的默认值过期；到期后访问短链返回 410「链接已过期」。

关键规则：

• 生成短链时附带的二维码 → 分类 short_link，跟随短链过期（不单独计算）
• 单独生成（工具 tab / 快捷工具）的二维码 → 分类 plain，按身份走 qrexpire* 默认值
• 后台/用户中心的短链列表显示过期时间列，过期标红

五、二维码体系

• 打点记录：前台四个入口（首页短链按钮/工具 tab/用户中心/解短链页）生成二维码自动记录到 qr_codes 表
• 分类：短链二维码（home/center/expand 来源） vs 纯二维码（tool 来源）
• 合并计数：同一用户 + 同一内容自动合并，count 累加
• 后台二维码管理：4 张统计卡 + 记录列表（内容/生成者/分类/来源/次数/过期/删除）+ 按用户/分类/内容筛选分页

六、部署指南（phpstudy）

1. 准备

• phpstudy 安装 PHP 8.2+（含 pdo_mysql/pdo_sqlite）、MySQL 5.7+
• 站点根目录指向项目文件夹

2. 配置 config.php

define('DB_DRIVER', 'mysql');          // mysql 或 sqlite
define('DB_HOST', '127.0.0.1');
define('DB_NAME', '8v4');              // MySQL 库名（sqlite 模式忽略）
define('DB_USER', 'root');
define('DB_PASS', 'root');
define('SHORT_DOMAIN', '8v4.com');     // 短链域名（不含协议）→ 换域名改这里
define('ADMIN_PASS', '8v4admin');      // 后台初始密码，上线务必修改

首次访问任意页面自动建表 + 写入默认配置，无需手动导 SQL。

3. Nginx 干净短链（可选）

短链想支持 域名/CODE 直接跳转，把 nginx.conf.txt 的 server 段合并进站点配置（改 server_name 与 root），重启 Nginx。不配置也不影响功能（可用 ?u=CODE 访问）。

4. 验证

• 前台 http://站点/index.php 正常显示
• 注册 → 建链 → 访问短码 → 跳转成功
• 后台 http://站点/admin.php → admin / 8v4admin 登录

七、换域名三步

1. config.php：SHORT_DOMAIN 改为新域名
2. Nginx：server_name 同步修改并重启
3. 后台系统设置：修改站点名称

   已生成的短链不受影响（数据库存短码不存域名，跳转时现拼）。

八、安全设计

已内置防护

• SQL 注入：全站 PDO 预处理参数化
• XSS：输出统一 h() 转义；短链 404 页不回显用户输入
• CSRF：所有 POST 均校验 token；session 无 token 一律拒绝（防"空==空"绕过）
• 协议白名单：建链仅允许 http/https
• 越权：删除/修改短链校验归属 user_id；游客无法访问后台（302）
• 数据目录：data/ 已加防下载（Apache .htaccess + Nginx deny）

运维注意事项

九、常见问题 FAQ

Q：改代码后页面没变化？

A：静态资源已带版本号会自动刷新；若 PHP 层没变，重启 phpstudy 的 PHP 服务（OPcache）。

Q：建链报 1292 Incorrect datetime value？

A：已修复（expire_at 空串转 NULL）。若再出现，确认部署目录的 db.php 已同步。

Q：游客生成了短链，后台"归属用户"显示什么？

A：显示"未归属"（user_id=0），可按用户筛选查看。

Q：二维码管理里为什么没记录？

A：需刷新页面加载新版 app.js（已带版本号）；确认生成二维码时弹窗正常打开。

Q：MySQL 和 SQLite 数据能互导吗？

A：后台"一键备份"导出 SQL；切换驱动需重建表并导入数据（同库结构）。

Q：过期时间到期的链接还能恢复吗？

A：后台编辑链接把过期时间改未来/永久即可（当前编辑表单未提供过期修改，可后续加）。

本文档随项目迭代更新，如有出入以代码为准。