# 简易下载站点

## 项目简介
这是一个基于 PHP 的轻量级文件下载/管理站点，支持用户分级（admin/editor/viewer）、文件上传、下载、删除与操作日志。适合小型内部文件共享或个人私有文件库。

## 特性
- 用户角色：`admin`（管理员）、`editor`（编辑）、`viewer`（只读）
- 文件浏览与目录支持（`files/` 目录）
- 多文件上传、支持新建子目录
- 下载速率限速配置（每秒字节数）
- 登录防爆破：5 分钟内连续失败 3 次拉黑 IP
- 管理后台可视化管理黑名单 IP（查询/新增/删除）
- 管理后台可修改防爆破阈值（窗口秒数与最大失败次数）
- 操作日志记录（`logs/actions.log`）

## 目录结构（重要文件）
- `config.php`：全局配置与公共函数（用户管理、日志、权限、速率限速、路径安全）
- `bootstrap.php`：统一引导文件（会话启动 + 配置加载）
- `index.php`：主页，目录浏览与下载入口
- `upload.php`：上传页与上传处理逻辑
- `download.php`：安全下载（realpath 校验、速率限速）
- `login.php` / `logout.php`：登录与登出
- `users.php`：用户管理（仅管理员）
- `viewlog.php`：查看与清空操作日志（仅管理员）
- `settings.php`：站点设置（仅管理员，可修改站点标题与主题色）
- `security.php`：安全设置（仅管理员，可修改防爆破阈值并管理黑名单 IP）
- `navbar.php`：顶部导航与主题变量
- `lib/`：模块化函数目录（站点设置、认证与权限、文件操作、浏览器拦截）
- `style.css`：样式表
- `assets/`：静态资源（如背景图片）
- `files/`：存放用户上传或可下载文件
- `logs/`：日志与登录防护记录（`actions.log`, `failed_logins.json`, `ip_blacklist.json`, `security_settings.json`）
- `site_settings.json`：站点外观配置（`site_name`, `theme_color`）

## 快速部署
1. 环境要求：PHP 7.4+，Web 服务器（Apache/Nginx），可写的文件系统权限。
2. 将项目放到 Web 根目录或虚拟主机目录。
3. 确保 `files/` 与 `logs/` 目录可写：

```bash
# Windows（示例）
# 在 PowerShell 中为运行 Web 服务器的用户授予写权限，或在资源管理器中调整权限。
```

4. 访问 `login.php`：首次若 `users.json` 为空，会提示创建第一个管理员账户。
5. 登录后根据角色访问 `upload.php`、`delete.php`（管理员）与 `users.php`（管理员）。

## 配置要点
在 `config.php` 中可调整：
- `$default_site_name`：默认站点名称
- `$default_theme_color`：默认主题色
- `$file_dir`：文件存放目录（默认为 `files/`）
- `$download_rate_limit`：下载速率限制（字节/秒），0 表示不限制
- `$max_login_failures_per_window` 与 `$login_fail_window_seconds`：登录失败窗口与拉黑阈值

也可在 `security.php`（管理员）中在线调整：
- 登录失败窗口秒数
- 窗口内最大失败次数
- 黑名单 IP 的查询、手动拉黑和解除拉黑

管理员可在 `settings.php` 页面在线修改站点标题与主题色，配置将持久化到 `site_settings.json`。

用户数据保存在 `users.json`（位于项目根），密码使用 `password_hash()` 存储（代码兼容旧明文但建议迁移所有账户为哈希）。

## 架构与命名约定（建议）
- 页面入口统一通过 `bootstrap.php` 加载环境，避免在各文件重复 `session_start()` 与 `include("config.php")`。
- `config.php` 仅负责初始化与装配，具体业务函数拆分到 `lib/` 子模块中。
- 页面文件建议使用 `kebab-case` 命名（如 `view-log.php`），函数命名使用 `snake_case`，常量使用 `UPPER_SNAKE_CASE`。
- 保留旧文件名作为兼容入口时，可在旧文件中仅保留一层重定向/代理逻辑，逐步迁移到新命名。
- 与安全相关的逻辑（权限、路径校验、日志）尽量集中在公共层，页面只保留参数解析与渲染。
- 当前公共层已统一提供：AJAX 错误响应、登录跳转、CSRF token 生成/校验、Flash 消息读写，可在管理页面复用以减少重复代码。

## 安全建议（强烈建议实施）
- 部署 HTTPS（TLS）以保护会话与凭证传输。
- 限制上传文件类型与大小，在前端/后端同时验证 MIME 与扩展名。
- 为表单添加 CSRF token，以防止跨站请求伪造。
- 确保 `files/`、`logs/`、`users.json` 权限最小化，仅 Web 服务账号可写。
- 关闭目录列表（web server 配置），避免直接泄露文件结构。
- 将 `users.json` 中的明文密码一并迁移为哈希并移除明文兼容代码路径。
- 对日志文件做轮转与权限控制，避免单文件无限增长。

## 备份与维护
- 定期备份 `files/` 与 `logs/` 以及 `users.json`。
- 若为生产环境，考虑将文件存储迁移到对象存储（如 S3）并使用外部数据库保存用户与日志。

## 常见问题排查
- 无法上传/写入：检查 `files/` 与 `logs/` 目录写权限。
- 登录失败触发拉黑：失败窗口记录在 `logs/failed_logins.json`，黑名单在 `logs/ip_blacklist.json`，可手动清理。
- 下载异常或速度慢：检查 `$download_rate_limit` 配置与服务器带宽。

## 已限制的浏览器

- 本站对部分嵌入式或国产内置浏览器做了访问限制，以避免兼容性或安全问题：
	- QQ 浏览器（UA 中含 `MQQBrowser` / `QQBrowser` 等）
	- 微信内置浏览器（UA 中含 `MicroMessenger`）
	- 360 浏览器（常见 UA 包含 `360SE`/`360EE`/`QIHU` 等）

- 实现位置：在 `config.php` 中有 `is_disallowed_browser()` 检测逻辑，匹配上述 User-Agent 并返回 HTTP 403 提示页面。
- 管理员例外：若管理员已登录（session 中 `role === 'admin'`），默认允许访问（便于维护）；该例外可在 `config.php` 中调整或移除。

- 注意：User-Agent 可被伪造，若需更严格限制建议结合其他手段（例如在受限页面加入跳转说明、使用验证码或服务端指纹策略）。

## 后续改进建议
- 添加 CSRF、严格的文件类型/大小验证
- 将公共函数拆分到 `lib/` 以便单元测试
- 支持分页的文件列表、搜索与标签

---
如需我把 README 调整为更精简或更详细版本（例如加入部署脚本、示例 nginx 配置、Windows 权限命令），告诉我想要的方向。