# Wallhaven 壁纸站点
一个基于 PHP 的 Wallhaven api壁纸浏览站点，支持搜索、详情查看、标签查看、收藏集查询、缓存与限流、管理员后台配置等能力。
## 1. 网站介绍
本项目用于快速搭建一个 Wallhaven 壁纸浏览站，核心特性：
– 支持关键词搜索与高级筛选（分类、纯净度、排序、分辨率、比例、颜色等）
– 支持壁纸详情页（元信息、标签、色板、下载）
– 支持收藏集与收藏详情浏览
– 支持标签详情页面
– 支持 API 缓存、请求限流、故障回退
– 支持管理员登录后统一配置 API 参数
– 支持图片域名重写（`path` / `thumbs`）以适配不同网络环境
– 支持非管理员禁用 API Key 调用（避免未授权使用）
## 2. 项目结构
“`text
wallhaven/
├─ index.php # 首页搜索与列表
├─ detail.php # 壁纸详情
├─ collections.php # 收藏集列表
├─ collection.php # 收藏详情
├─ tag.php # 标签详情
├─ settings.php # API 设置（管理员）
├─ clear_cache.php # 清理缓存接口（管理员）
├─ config.php # 核心配置与工具函数
├─ footer.php # 站点公共 footer
├─ style.css # 样式
├─ app.js # 前端交互
├─ data/
│ └─ config.json # 运行配置文件
└─ cache/ # API 缓存、限流数据
“`
## 3. 运行环境要求
– PHP 7.4+（推荐 PHP 8.0+）
– 必需扩展：`curl`、`json`
– 建议扩展：`openssl`（HTTPS）、`exif`（详情页 EXIF 功能）
– Web 服务器：Nginx / Apache / PHPStudy 均可
## 4. 安装与部署教程
### 4.1 下载并放置项目
将项目放到网站根目录，例如：
– Windows (PHPStudy): `c:\phpstudy_pro\WWW\wallhaven`
– Linux: `/www/wwwroot/your-domain`
### 4.2 配置站点
– 站点根目录指向本项目目录
– 确认 PHP 版本 >= 7.4
### 4.3 目录权限
确保以下目录可写（用于缓存和配置）：
– `data/`
– `cache/`
– `cache/rate_limit/`
Linux 示例：
“`bash
chown -R www:www /www/wwwroot/your-domainchmod -R 755 /www/wwwroot/your-domainchmod -R 775 /www/wwwroot/your-domain/data /www/wwwroot/your-domain/cache
“`
### 4.4 启动访问
浏览器打开站点首页：
– `http://你的域名/`
## 5. 首次配置教程
### 5.1 生成管理员密码哈希
执行：
“`bash
php -r “echo password_hash(‘你的管理员密码’, PASSWORD_DEFAULT), PHP_EOL;”
“`
复制输出哈希，写入 `data/config.json`：admin_password_hash参数
“`json
{“api_key”: “”,“api_base_url”: “https://wallhaven.cc/api/v1/”,“path_base_url”: “”,“thumbs_base_url”: “”,“admin_password_hash”: “$2y$10$……”}
“`
说明：
– 未配置管理员密码时，`settings.php` 不允许执行管理操作
### 5.2 登录 API 设置页面
– 访问：`/settings.php`
– 输入管理员密码登录，默认密码在项目的 README.md文件里
– 可配置：
– `api_key`
– `api_base_url`
– `path_base_url`
– `thumbs_base_url`
– 可执行：
– 清理缓存
– 恢复默认 API 地址
## 6. 配置项说明
`data/config.json` 字段：
– `api_key`: Wallhaven API Key（管理员维护）
– `api_base_url`: API 地址（默认 `https://wallhaven.cc/api/v1/`）（大陆无法访问wallhaven的官方api，你需要在api设置中换成你自己的api，具体方法下方有教程）
– `path_base_url`: 原图域名重写（重写 JSON `path`）
– `thumbs_base_url`: 缩略图域名重写（重写 JSON `thumbs`）
– `admin_password_hash`: 管理员密码哈希
## 7. 权限机制说明
– 管理配置仅管理员可用（`settings.php`）
– 非管理员状态下：
– 禁止使用已配置的 `api_key` 调用接口
– 页面会显示提示并提供“去 API 设置登录”入口
## 8. 缓存与限流
– API 响应会缓存到 `cache/*.json`
– 存在客户端维度的出站限流（默认每 60 秒最多 30 次）
– 可在设置页使用“清理缓存”按钮清空缓存文件
## 9. 常见问题（FAQ）
### 9.1 提示 429（请求过于频繁）
系统会提示用户刷新重试，并在可用时回退缓存数据。或者建议更换成你自己的api接口，默认的api接口是公开的，使用人数太多，会被提示频繁
### 9.2 图片无法打开（大陆网络场景）
请在 `settings.php` 设置：
– `path_base_url`
– `thumbs_base_url`
改为可访问的图片域名。
如果你的vps是境外服务器，可以使用nginx反代，https://wallhaven.cc/api，和 https://w.wallhaven.cc，https://th.wallhaven.cc 这三个域名制作自己的api，保证大陆用户可正常访问
具体反代教程：
### 9.3 open_basedir 报错
项目已做 open_basedir 安全判断。若仍报错，请检查：
– PHP `open_basedir` 配置
– 站点目录、`/tmp` 是否在允许范围
### 9.4 更换管理员密码
重新生成哈希并替换 `admin_password_hash`，重启 PHP 后生效。
index.php 将第三行的代码注释”//”去掉。填入你的新密码，然后访问首页，就能看到新的哈希值，填入 `data/config.json`：admin_password_hash参数即可。
## 10. 安全建议
– 不要把明文密码写入代码或版本库
– 生产环境优先使用环境变量管理管理员密码哈希
– 限制 `settings.php` 访问来源（如 Nginx 白名单）可进一步提升安全性
– 定期清理缓存与日志，避免磁盘占满
