# 通用表单系统公开版

**Repository Path**: jimhuhu/formhub-open

## Basic Information

- **Project Name**: 通用表单系统公开版
- **Description**: 一个轻量、美观、易部署的 PHP 表单收集系统。支持自定义表单字段、文件上传、审核流程、查询码追踪等功能。
- **Primary Language**: PHP
- **License**: MIT
- **Default Branch**: master
- **Homepage**: https://zsbj.top/
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-06-10
- **Last Updated**: 2026-06-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: PHP, Tailwind, CSS, MySQL, Sqlite

## README

# FormHub

FormHub 是一个轻量、易部署的通用表单收集系统，适合用于活动报名、资料收集、问卷提交、附件上传、审批流转和后台数据管理。项目使用原生 PHP 构建，不依赖后端框架；前端基于 Tailwind CSS，提供响应式布局、深色模式和 Apple 风格毛玻璃界面。

当前版本：`v3.3.0`

## 功能特性

- 表单管理：可视化创建、编辑、发布和停用表单
- 字段类型：文本、多行文本、数字、邮箱、电话、日期、单选、多选、图片上传、文件上传等
- 附件能力：支持文件类型、大小、数量限制，图片可在线预览
- 审核流程：可开启提交审批，支持待审、通过、驳回和批量处理
- 查询码追踪：开启审批后，用户可使用查询码查看处理状态
- 访问控制：支持表单访问密码，留空即公开访问
- 重复提交控制：可按表单配置是否允许重复提交
- 数据导出：支持导出表单提交数据和附件归档包
- 后台管理：统一管理表单、提交、文件、管理员和操作日志
- 安全加固：CSRF 防护、Session 防护、HMAC 文件链接、敏感字段加密、安全响应头和防枚举策略
- 多端适配：桌面端和移动端均可使用，支持手动或跟随系统深色模式

## 技术栈

- 后端：PHP 8.1+，原生 PHP，无需 Composer
- 前端：Tailwind CSS，原生 JavaScript
- 数据库：SQLite、MySQL、PostgreSQL、达梦、OceanBase、TiDB、人大金仓、openGauss
- 容器：Docker、Docker Compose、Nginx、PHP-FPM、Supervisor
- 导出：PHP ZipArchive 生成 XLSX 和附件压缩包

## 快速开始

### 使用离线 Docker 镜像

开源仓库的 `docker/` 目录包含已导出的离线镜像包和部署用 Compose 文件：

```text
docker/
├── docker-compose.yaml
├── formhub_3.3.0_amd64.tar
└── formhub_3.3.0_arm64.tar
```

进入部署目录：

```bash
cd docker
```

导入镜像：

```bash
# AMD64 服务器
docker load -i formhub_3.3.0_amd64.tar

# ARM64 服务器
docker load -i formhub_3.3.0_arm64.tar
```

推荐先生成随机密码配置，再启动服务。

Windows PowerShell：

```powershell
.\scripts\generate-env.ps1
docker compose up -d
```

Linux / macOS：

```bash
bash scripts/generate-env.sh
docker compose up -d
```

启动后访问：

```text
http://localhost:51125
```

常用命令：

```bash
docker compose ps
docker compose logs -f
docker compose down
```

Docker 部署细节见 [docker/部署说明.md](docker/部署说明.md)。

### 二次构建镜像

开源发布仓库默认提供离线镜像包，不包含镜像构建所需的完整 Dockerfile 上下文。开发或二次打包时，请使用完整源码仓库构建：

```bash
docker compose up -d --build
```

### 手动部署

1. 准备 PHP 8.1 或更高版本。
2. 将 `formhub/` 目录部署到 Web 站点根目录。
3. 确保以下目录可写：
   - `formhub/uploads/`
   - `formhub/cache/`
   - `formhub/logs/`
   - `formhub/storage/sessions/`
4. 确保配置文件目录可写，默认配置文件位于 `formhub/storage/config.json`。
5. 访问站点首页，按安装向导完成数据库和管理员配置。

系统支持查询参数路由，无需强制配置伪静态；例如后台入口可通过 `?route=/admin` 访问。

## 环境要求

必需 PHP 扩展：

- `pdo`
- `openssl`
- `mbstring`
- `json`
- `fileinfo`
- `zip`
- `gd`

按数据库选择安装对应扩展：

- SQLite：`pdo_sqlite`
- MySQL / OceanBase / TiDB：`pdo_mysql`
- PostgreSQL / openGauss：`pdo_pgsql`
- 达梦：`pdo_dm`

## 项目结构

```text
.
├── formhub/                 # 应用源码和 Web 根目录
│   ├── assets/              # 前端资源
│   ├── routes/              # 路由定义
│   ├── sql/                 # 数据库初始化 SQL
│   ├── src/                 # 核心 PHP 代码和视图
│   ├── storage/             # 配置和会话等运行数据
│   ├── uploads/             # 上传文件
│   └── index.php            # 应用入口
├── package.json             # Tailwind CSS 构建脚本
├── package-lock.json        # 前端构建依赖锁定文件
├── tailwind.config.js       # Tailwind CSS 配置
├── postcss.config.js        # PostCSS 配置
├── .npmrc                   # npm 镜像源配置
└── docker/                  # 离线 Docker 镜像和部署文件
    ├── docker-compose.yaml  # 离线镜像部署用 Compose 文件
    ├── 部署说明.md
    ├── formhub_*.tar        # AMD64 / ARM64 离线镜像包
    └── scripts/             # 环境变量生成脚本
```

## 本地开发

安装前端构建依赖：

```bash
npm install
```

编译 Tailwind CSS：

```bash
npm run build:css
```

监听 CSS 变更：

```bash
npm run watch:css
```

如果修改了 UI 或布局样式，请重新运行：

```bash
npm run build:css
```

## 配置说明

Docker 部署使用根目录 `.env` 配置端口和 MySQL 账号密码。请不要直接使用 `.env.example` 中的占位密码，建议通过脚本生成：

```powershell
.\scripts\generate-env.ps1
```

主要环境变量：

| 变量 | 说明 | 默认值 |
| --- | --- | --- |
| `FORMHUB_PORT` | FormHub 对外端口 | `51125` |
| `MYSQL_PORT` | MySQL 对外端口 | `13306` |
| `MYSQL_DATABASE` | MySQL 数据库名 | `formhub` |
| `MYSQL_USER` | MySQL 用户名 | `formhub` |
| `MYSQL_PASSWORD` | MySQL 用户密码 | 脚本生成 |
| `MYSQL_ROOT_PASSWORD` | MySQL root 密码 | 脚本生成 |

应用运行配置默认保存在 `formhub/storage/config.json`。容器部署时会通过 `FORMHUB_CONFIG_PATH` 指向持久化路径。

## 安全建议

- 生产环境务必使用强密码和 HTTPS。
- 不要提交 `.env`、数据库文件、运行日志和上传附件。
- Docker 部署前请运行环境生成脚本，避免使用默认密码。
- 对外暴露 MySQL 端口仅建议用于调试，生产环境可关闭或通过防火墙限制访问。
- 定期备份 `storage/`、`uploads/`、`cache/`、`logs/` 和数据库数据。

## 贡献

欢迎提交 Issue 和 Pull Request。建议在提交前完成以下检查：

```bash
npm run build:css
```

如涉及后端逻辑，请同时验证安装向导、表单提交、后台登录、附件上传和数据导出等关键流程。

## 许可证

本项目使用 MIT 许可证，详见 [LICENSE](LICENSE)。

## 免责声明

FormHub 按“现状”提供，不提供任何明示或暗示担保，包括但不限于适销性、特定用途适用性、安全性、稳定性、数据完整性和非侵权担保。

使用者应自行评估、部署、维护和备份系统，并自行承担因安装、部署、配置、升级、二次开发、数据迁移、文件上传、数据库使用、第三方环境、网络攻击、安全事件、数据丢失、业务中断或其他使用行为产生的风险和责任。

在适用法律允许的最大范围内，项目作者、维护者和贡献者不对任何直接、间接、偶然、特殊、惩罚性或后果性损失承担责任，即使已被告知可能发生此类损失。

本免责声明是对 [LICENSE](LICENSE) 中 MIT 许可证无担保和责任限制条款的中文说明。若本说明与 LICENSE 正文存在差异，以 LICENSE 英文正文为准。