【原创项目】FormHub – 通用表单收集系统

一个轻量、美观、易部署的 PHP 表单收集系统。支持自定义表单字段、文件上传、审核流程、查询码追踪、操作日志等功能。

AI 辅助生成项目提醒

• 本项目部分内容由 AI 辅助生成。
• 使用前请自行审查安全性、正确性及合规性。
• 项目提供者不作任何担保，使用者承担全部责任。
• 如有bug请各位AI修一下，哈哈
  

功能特性

• 表单管理：可视化创建和编辑表单，支持多种字段类型
• 字段类型：文本、多行文本、数字、邮箱、电话、日期、选择、多选、图片上传、文件上传等
• 文件上传：支持图片和文件上传，可配置文件类型、大小、数量限制，安全防护完善
• 审核流程：管理员可对提交进行通过、驳回、备注操作
• 查询码追踪：提交成功后生成唯一查询码，用户可随时查询审核状态
• 密码保护：表单可设置访问密码
• 重复提交：支持允许/禁止重复提交
• 数据导出：原生 XLSX 导出，附件以超链接形式嵌入，点击可直接下载
• 提交管理：管理员全局查看所有提交，支持查询码搜索、状态筛选
• 操作日志：全面记录所有用户操作，支持筛选、详情查看和导出
• 安全加固：HMAC 签名文件链接、安全响应头、Session 防护、防枚举爆破
• 现代 UI：渐变色、圆角卡片、柔和阴影、动画过渡
• 响应式设计：完美适配手机和桌面端
• 零配置部署：无需伪静态，支持查询参数模式直接运行
  

技术栈

• 后端：PHP 8.1+（原生，无框架依赖，无需 Composer）
• 前端：Bootstrap 5 + Bootstrap Icons
• 数据库：SQLite / MySQL / PostgreSQL / 达梦 / OceanBase / TiDB / 人大金仓 / openGauss
• 导出：原生 PHP ZipArchive 生成 XLSX（无需第三方库）
  

环境要求

• PHP >= 8.1
• 必需扩展：openssl、mbstring、json、fileinfo、zip
• 数据库扩展（根据选择）：pdo_sqlite / pdo_mysql / pdo_pgsql / pdo_dm
• Web 服务器：Apache / Nginx / Laragon / 任意支持 PHP 的服务器
  

快速部署
方式一：宝塔面板部署（推荐）
1. 添加网站

• 登录宝塔面板，点击「网站」→「添加站点」
• 填写域名，如 form.example.com
• 选择 PHP 版本 8.1 或更高
• 点击「提交」
  

2. 上传代码

使用管理员或维护人员提供的正式发布 ZIP 包，在宝塔「文件」界面上传 ZIP 包并解压。

3. 检查 PHP 扩展

确认以下扩展已安装：fileinfo、openssl、mbstring、zip

4. 设置目录权限

设置 uploads/ 和 cache/ 目录权限为 755

5. 访问安装

打开浏览器访问域名，系统会自动进入安装向导

方式二：手动部署

• 下载代码到 Web 服务器目录
• 设置 uploads/ 和 cache/ 目录权限为 755
• 访问域名，系统自动进入安装向导
  

无需伪静态：系统自动支持 ?route=/admin 查询参数模式。

目录结构

1. 1 FormHub/
   
2. 2 ├── index.php                 # 入口文件
   
3. 3 ├── assets/                   # 静态资源
   
4. 4 ├── src/                      # 源码目录
   
5. 5 │   ├── handlers/             # 业务处理器
   
6. 6 │   ├── models/               # 数据模型
   
7. 7 │   ├── views/                # 视图模板
   
8. 8 │   └── setup-wizard.php      # 安装向导
   
9. 9 ├── uploads/                  # 上传文件目录
   
10. 10 ├── cache/                    # 缓存目录
    
11. 11 └── tools/                    # 工具脚本

复制代码

数据库配置

系统支持多种数据库，安装时会自动配置。也可手动编辑 config.json：

SQLite（默认，零配置）

1. {
   
2.   "db": {
   
3.     "driver": "sqlite",
   
4.     "path": "database.sqlite"
   
5.   }
   
6. }

复制代码

MySQL / OceanBase / TiDB

1. {
   
2.   "db": {
   
3.     "driver": "mysql",
   
4.     "host": "localhost",
   
5.     "port": 3306,
   
6.     "database": "formhub",
   
7.     "username": "root",
   
8.     "password": "your_password",
   
9.     "charset": "utf8mb4"
   
10.   }
    
11. }

复制代码

系统使用手册
一、系统概述

FormHub 是一款通用的文件上传收集与表单管理系统。管理员可以创建自定义表单，用于收集用户提交的数据和文件，例如图片、文档、联系方式、报名信息等，并在后台统一审核管理。用户端无需登录，通过表单链接即可填写和提交。

系统适合用于资料收集、报名登记、证件上传、活动申请、审批收集、内部信息采集等场景。

二、快速开始

• 将项目文件部署到 PHP 8.1+ 的 Web 服务器。
• 访问系统域名，首次使用会进入安装/初始化流程。
• 按提示配置数据库并创建管理员账号。
• 使用管理员账号登录后台。
• 创建表单模板，配置字段、上传限制、访问密码等选项。
• 发布表单，并将表单链接分享给用户填写。
• 用户提交后获得查询码，可凭查询码查询审核状态。
• 管理员在审核中心处理提交记录，并可导出数据。
  

三、用户端使用说明
1. 系统首页

用户访问系统根路径后，可以看到已发布的表单列表。每个表单以卡片形式展示，用户点击表单卡片即可进入填写页面。首页也提供“查询提交状态”入口，便于用户通过查询码查看处理进度。

2. 填写表单

表单页面会展示表单标题、说明和各个字段。系统支持以下常见字段类型：

字段类型	说明
文本	单行文本输入，适合姓名、单位、标题等内容
多行文本	大段文字输入，适合备注、说明、申请理由等内容
数字	仅允许输入数字
邮箱	用于收集邮箱地址
手机号	用于收集手机号，自动校验中国大陆手机号格式
身份证号	用于收集身份证号，自动校验 18 位二代身份证格式与校验码
日期	用于选择日期
单选	从多个选项中选择一个
多选	从多个选项中选择多个
图片上传	上传图片文件，适合证件照、截图、资料照片等
文件上传	上传文档或其他附件

带有必填标记的字段必须填写。文件上传字段会根据管理员配置限制文件类型、大小和数量。

3. 提交表单

用户填写完成后点击提交按钮，系统会自动校验必填项、字段格式（手机号、身份证号、邮箱等）和文件上传限制。提交成功后会生成唯一查询码。

查询码是用户后续查询审核状态的重要凭证，建议用户提交后立即复制或截图保存。

4. 查询提交状态

用户可以进入“查询提交状态”页面，输入查询码查看提交记录的处理进度。常见状态包括：

• 待审核：管理员尚未处理。
• 已通过：提交内容已审核通过。
• 已驳回：提交内容未通过审核，页面会显示驳回原因。
• 已备注：管理员已添加处理备注。
  

四、管理端使用说明
1. 管理员登录

访问 /admin/login 进入管理员登录页面。输入管理员账号和密码后即可进入后台。首次部署且未创建管理员时，系统会引导完成初始化。

2. 表单管理

登录后台后默认进入表单管理页面。管理员可以在这里统一管理所有表单模板，包括：

• 新建表单：创建新的收集表单。
• 编辑表单：修改表单名称、描述、字段和访问控制。
• 发布/下线：控制表单是否在用户端显示。
• 复制表单：快速复制已有表单配置。
• 删除表单：删除后进入回收站，可按系统规则恢复或清理。
• 拖拽排序：调整表单在用户端首页的显示顺序。
• 回收站：查看和恢复已删除表单。
  

3. 创建和编辑表单

表单编辑器主要包含以下配置：

• 基本信息：设置表单标题、描述、截止时间、最大提交数等。
• 字段配置：添加文本、多行文本、数字、邮箱、手机号、身份证号、日期、图片、文件、单选、多选等字段。
• 字段规则：设置字段标签、提示文字、是否必填、选项内容、上传限制等。
• 访问控制：可设置表单访问密码，开启后用户需要输入密码才能填写。
• 发布状态：保存后根据需要发布表单。
  

建议发布前先预览表单，确认字段顺序、必填项、文件限制和提示文案符合预期。

4. 审核中心

审核中心是管理员处理用户提交数据的核心页面。页面支持按状态、表单和关键字筛选提交记录，并集中展示查询码、表单名称、提交内容、附件和审核操作。

常用操作包括：

• 通过：将提交记录标记为审核通过。
• 驳回：填写驳回原因后将记录标记为已驳回。
• 详情：进入提交详情页查看完整字段、附件和审核信息。
• 图片预览：图片字段显示缩略图，点击缩略图可在本页弹窗放大预览，支持缩放、拖拽、旋转和下载原图。
  

5. 提交详情

提交详情页会完整展示一次提交的所有字段数据、上传文件、审核状态、审核意见和提交时间。管理员可在详情页查看附件并进行审核处理。

6. 数据导出

管理员可以将提交数据导出为 XLSX 文件。导出内容包含字段数据和附件链接，附件以超链接形式嵌入，便于后续整理和归档。

7. 操作日志

操作日志记录管理员的重要操作，包括登录、登出、创建表单、编辑表单、删除表单、审核提交、导出数据、修改系统设置、系统升级等。日志包含操作人、操作类型、目标对象、操作时间和 IP 地址，可用于审计和问题追溯。

8. 系统设置

系统设置页面可配置以下内容：

设置项	说明
系统名称	显示在首页和浏览器标题等位置
副标题	显示在首页 Header 下方
Logo	可上传系统 Logo，用于首页和后台展示
升级设置	查看当前版本，并通过本地上传升级包完成系统升级

9. 系统升级

系统升级采用本地上传升级包的方式。管理员或维护人员先准备好正式发布的升级 ZIP 包，然后在后台升级页面上传。系统会校验升级包内容，执行升级流程，并尽量保留现有配置、数据库和上传文件。

升级前建议先备份数据库、uploads/ 目录和 config.json，并确认当前环境具备文件写入权限。升级包应来自可信维护渠道，不建议上传来源不明的压缩包。

10. 修改密码

管理员可在后台侧边栏底部进入修改密码页面，输入旧密码和新密码后完成修改。修改后建议重新登录确认新密码可用。

五、常见问题

问题	处理建议
图片缩略图无法显示或返回 404	检查数据库 files 表是否存在对应记录，确认 uploads 目录中文件真实存在，并检查目录权限
图片缩略图返回处理失败	检查 PHP GD 扩展是否启用，或确认图片格式是否受当前服务器支持
文件上传失败	检查 upload_max_filesize、post_max_size、目录权限和表单字段上传限制
用户无法访问表单	检查表单是否已发布、是否过期、是否达到最大提交数、是否设置访问密码
查询码查不到结果	确认查询码输入无误，并检查提交记录是否存在
管理员无法登录	检查账号密码、Session 配置、浏览器 Cookie，以及服务器时间是否正常
数据库连接失败	检查 config.json 中的数据库类型、地址、端口、账号密码和扩展是否正确
伪静态不生效	可使用查询参数模式访问，例如 ?route=/admin
本地上传升级失败	检查升级 ZIP 包是否完整、文件类型是否在升级白名单内，以及目录写入权限是否正常

使用建议

• 大文件上传：如需上传大文件，请在 ini中调整 upload_max_filesize 和 post_max_size 配置
• 高并发场景：如果预期有高并发提交，建议生产环境使用 MySQL 而非 SQLite，可获得更好的并发性能
  

源码分享：Formhub-v1.6.1.zip

原贴：【原创项目】FormHub – 通用表单收集系统-蓝小白的知识笔记

练练手  哈哈
开发时间   15天
token使用大概200元

基本能跑

蓝小白酱的开发日记