H5页面导航系统· 完整使用说明

📌 项目概述

这是一个基于PHP的H5页面管理导航系统，用于管理和展示您部署在 /i/ 目录下的所有H5项目。系统支持项目上传、删除、自定义别名、图标设置等功能。

🚀 快速开始

1. 部署文件

将以下文件上传到 /www/wwwroot/qxgifts/i/ 目录：

/www/wwwroot/qxgifts/i/
├── index.php                    # 主程序文件
├── generate_hash.php            # 密码生成工具（使用后请删除）
├── .upload_config.json          # 密码配置文件（可选）
├── .folders.json                # 全局别名/图标配置（可选）
├── project1/                    # 您的H5项目文件夹
│   ├── index.html               # 项目首页
│   ├── .alias                   # 别名文件（可选）
│   ├── .icon                    # 图标文件（可选）
│   └── .delete_password         # 独立删除密码（可选）
└── project2/
    └── index.html

2. 设置权限

cd /www/wwwroot/qxgifts
chmod 755 i/
chown -R www:www i/

3. 配置密码

生成密码哈希

访问 https://qxgifts.com/i/generate_hash.php

1. 选择密码类型：

   • 📤 上传密码 - 用于上传项目
   • 🗑️ 删除密码 - 用于删除项目
2. 输入您的密码
3. 点击 "🔒 生成哈希"
4. 复制生成的哈希值

配置上传密码

方式一：修改 index.php

php

$UPLOAD_PASSWORD_HASH = '$2y$10$您的哈希值';

方式二：创建配置文件（推荐）
创建 .upload_config.json：

{
    "password_hash": "$2y$10$上传密码的哈希值",
    "delete_password_hash": "$2y$10$删除密码的哈希值"
}

📖 功能使用详解

1. 浏览项目

访问 https://qxgifts.com/i/ 即可看到所有项目卡片。

功能说明：

• 每个项目以卡片形式展示
• 点击卡片直接访问项目（如有 index.html）
• 支持搜索过滤
• 深色/浅色主题切换

2. 上传项目

步骤：

1. 点击 "📤 上传项目" 按钮
2. 输入上传密码
3. 选择 ZIP 或 RAR 文件（支持拖拽）
4. 点击 "上传并解压"

支持的格式：

• ZIP 格式（推荐）
• RAR 格式（需要 PHP RAR 扩展）

文件限制：

• 最大 100MB
• 支持中文文件名

上传后自动：

• 解压到新目录
• 查找 index.html/index.htm/index.php
• 自动跳转到项目首页

3. 删除项目

步骤：

1. 鼠标悬停在项目卡片上
2. 点击右上角的 🗑️ 按钮
3. 输入删除密码
4. 点击 "确认删除"

删除密码设置：

方式一：全局默认密码

$DEFAULT_DELETE_PASSWORD_HASH = '$2y$10$您的哈希值';

方式二：项目独立密码
在项目文件夹中创建 .delete_password 文件：

cd /www/wwwroot/qxgifts/i/project1
echo "$2y$10$生成的哈希值" > .delete_password
chmod 644 .delete_password

4. 自定义项目

设置别名

在项目文件夹中创建 .alias 文件：

cd /www/wwwroot/qxgifts/i/project1
echo "我的第一个项目" > .alias

设置图标

在项目文件夹中创建 .icon 文件：

# Emoji
echo "🚀" > .icon

# 图片路径
echo "/images/project-icon.png" > .icon

# SVG代码
echo '<svg>...</svg>' > .icon

全局配置（批量设置）

创建 .folders.json：

{
    "project1": {
        "alias": "我的项目",
        "icon": "🚀"
    },
    "project2": {
        "alias": "演示页面",
        "icon": "🎯"
    }
}

⚙️ 配置说明

核心配置参数（index.php）

// 上传密码
$UPLOAD_PASSWORD_HASH = '$2y$10$YOUR_HASH_HERE';

// 默认删除密码
$DEFAULT_DELETE_PASSWORD_HASH = '$2y$10$YOUR_DEFAULT_DELETE_HASH_HERE';

// 安全设置
$MAX_ATTEMPTS = 5;                    // 最大尝试次数
$LOCKOUT_TIME = 900;                  // 锁定时间（秒）
$MAX_FILE_SIZE = 100 * 1024 * 1024;  // 最大文件大小（100MB）
$ALLOWED_EXTENSIONS = ['zip', 'rar']; // 允许的文件格式

PHP 配置要求

upload_max_filesize = 100M
post_max_size = 100M
max_execution_time = 300
max_input_time = 300
memory_limit = 256M

需要的 PHP 扩展

🎨 主题切换

系统支持深色/浅色两种主题：

• 默认深色：与主站 qxgifts.com 风格一致
• 浅色模式：适合白天使用
• 自动记忆：主题偏好保存在浏览器中
• 系统同步：可自动跟随系统主题

点击页面右上角的 🌙/☀️ 按钮切换。

🔐 安全说明

1. 密码安全

• 所有密码使用 bcrypt 算法加密
• 建议使用强密码（至少8位，包含大小写字母、数字和特殊字符）
• 定期更换密码

2. 文件安全

• 路径遍历防护
• CSRF Token 保护
• 文件类型验证
• 上传频率限制（每小时20次）

3. 服务器安全

# 设置正确权限
chmod 755 /www/wwwroot/qxgifts/i/
chown -R www:www /www/wwwroot/qxgifts/i/

# 删除敏感文件
rm /www/wwwroot/qxgifts/i/generate_hash.php

🐛 常见问题

Q1: 上传失败 "文件超过服务器限制"

解决：修改 PHP 配置

upload_max_filesize = 100M
post_max_size = 100M

或在 index.php 开头添加：

ini_set('upload_max_filesize', '100M');
ini_set('post_max_size', '100M');

Q2: 解压失败 "PHP ZipArchive 扩展未启用"

解决：安装 ZipArchive 扩展

# Ubuntu/Debian
sudo apt-get install php8.2-zip

# CentOS/RHEL
sudo yum install php8.2-zip

# 重启 PHP
sudo systemctl restart php8.2-fpm

Q3: 密码错误被锁定

解决：等待15分钟自动解锁，或删除 Session 文件

# 清除 Session
rm -rf /tmp/sess_*

Q4: 页面显示 "目录不存在"

解决：检查路径是否正确，确保文件夹存在

ls -la /www/wwwroot/qxgifts/i/

Q5: 上传的 RAR 文件无法解压

解决：安装 RAR 扩展

# Ubuntu/Debian
sudo apt-get install php8.2-rar

# 或使用替代方案：将 RAR 转为 ZIP 格式再上传

📊 系统要求

🔄 更新日志

v2.0 (当前版本)

• ✅ 深色/浅色主题切换
• ✅ 密码哈希加密
• ✅ 上传进度显示
• ✅ 自动跳转项目首页
• ✅ 独立删除密码
• ✅ 防暴力破解
• ✅ CSRF 保护

v1.0

• 基础项目列表
• 上传和解压功能
• 别名和图标设置

📞 技术支持

如有问题，请检查：

1. PHP 错误日志：/var/log/php_errors.log
2. 服务器错误日志：/var/log/apache2/error.log 或 /var/log/nginx/error.log
3. 文件权限是否正确

📝 总结

这个系统让您能够：

1. 📁 统一管理所有 H5 项目
2. 📤 在线上传和部署新项目
3. 🗑️ 安全删除项目
4. 🎨 自定义项目别名和图标
5. 🔒 密码保护关键操作
6. 🌓 深色/浅色主题切换

快速命令参考：

# 查看项目列表
ls -la /www/wwwroot/qxgifts/i/

# 创建新项目文件夹
mkdir /www/wwwroot/qxgifts/i/new_project

# 设置别名
echo "新项目" > /www/wwwroot/qxgifts/i/new_project/.alias

# 设置图标
echo "🚀" > /www/wwwroot/qxgifts/i/new_project/.icon

# 设置删除密码
echo '$2y$10$哈希值' > /www/wwwroot/qxgifts/i/new_project/.delete_password