# 盛月堂公共资源托管平台基于 PHP + Nginx 的零依赖公共文件下载与分享平台，提供目录浏览、实时搜索、SHA-512 哈希校验与供平台内嵌调用的 JSON API。 ## 功能特性 | 特性 | 说明 | |---|---| | 目录浏览 | 文件夹树侧栏 + 面包屑导航，SPA 无刷新切换 | | 搜索 | 当前目录实时过滤；可选递归全站搜索（返回前 100 条） | | 哈希校验 | SHA-512；≤50MB 实时计算，>50MB 后台队列预计算，前端自动轮询 | | 下载 | Nginx 静态直发，PHP 不参与文件 IO，支持超大文件 | | 在线预览 | GitHub 风格预览页：图片 / PDF 页内渲染，Word(.docx) 与 Excel(.xls/.xlsx) 浏览器本地渲染（vendor 库自托管，无外部服务依赖），Markdown 沙箱渲染，文本转义输出（≤2MB），支持上一份/下一份切换与键盘 ←/→ 导航 | | JSON API | list / tree / info / search / health，供第三方平台识别文件 | | 响应式 | 移动端自适应布局 | | 无障碍 | ARIA 表格语义、键盘可达（Enter 复制哈希、焦点环） | ## 文件结构 | 文件 | 说明 | |---|---| | index.php | Web 入口：页面渲染、搜索与哈希状态轮询接口 | | preview.php | 文件预览页（GitHub 风格：信息头 + 工具栏 + 上一份/下一份；图片/PDF 页内渲染，docx/xlsx 本地渲染，Markdown 沙箱） | | api.php | JSON API v1 入口 | | functions.php | 共享函数库（安全、哈希、索引、渲染辅助） | | hashWorker.php | 哈希后台计算 Worker（仅 CLI） | | apiKeyGen.php | API 密钥管理工具（仅 CLI：生成 / 查询 / 删除 / 重置） | | corsGen.php | API CORS 白名单管理工具（仅 CLI：添加 / 查询 / 删除 / 清空） | | assets/css | 样式（按层拆分）：base 基础 / layout 布局 / fileList 文件列表 / error 错误页 / preview 预览页 / markdown 渲染 | | assets/js | 脚本（按模块拆分）：util 工具 / search 搜索 / hash 哈希 / main SPA 入口 / preview 预览页 / markdown 渲染器；vendor/ 本地第三方库（jszip、docx-preview、xlsx/SheetJS，Office 浏览器本地渲染用） | | 403.html / 404.html | 错误页 | | robots.txt | 爬虫规则 | | tests/functionsTest.php | 单元测试（58 项断言）+ 全项目语法检查 | | downloads/ | 托管文件根目录（数据目录） | `downloads/` 内部数据文件： | 文件 | 说明 | |---|---| | .hashes.json | 哈希结果持久缓存（mtime + size + sha512） | | .hash_queue.json | 待计算任务队列 | | 使用说明.md | 本文档 | 配置文件（默认在项目根，可经环境变量移出，见部署第 5 步）： | 文件 | 说明 | |---|---| | .apikey | API 密钥（每行一个，支持多平台各自持有） | | .api_cors | CORS 允许的 Origin 白名单（每行一个完整 Origin） | ## 核心机制 ### 请求流程 ``` 浏览器 → Nginx ├─ /downloads/* → 静态文件直发（不经过 PHP） ├─ /d/xxx → 重写为 /index.php?dir=xxx（页面） ├─ /api/v1/xxx → 重写为 /api.php?action=xxx（JSON API） └─ 其他路径 → try_files 回退 index.php ``` ### 哈希计算（异步队列） 1. Web 请求读取 `downloads/.hashes.json`，`mtime + size` 均一致则直接命中 2. 未命中且 ≤50MB：同步计算并写回存储 3. 未命中且 >50MB：加入 `downloads/.hash_queue.json`，页面显示"计算中"并每 5 秒轮询 4. 后台 Worker（计划任务每 5 分钟）消费队列，流式分块计算（1MB/块，内存恒定） 5. `php hashWorker.php --scan` 全量扫描，将新增/变更文件补入队列 **缓存失效规则**：文件 mtime 或 size 变化即失效重算，无时间上限。删除 `.hashes.json` 可强制全量重算。 ### 缓存 | 缓存 | TTL | 位置 | |---|---|---| | 文件索引（搜索用） | 60 秒 | 系统临时目录（原子写入） | | 目录树 | 60 秒 | 系统临时目录（原子写入） | | 哈希结果 | 永久（随文件失效） | downloads/.hashes.json | ### 安全设计 - 路径遍历防护：`realpath` 前缀校验 + 路径逐段隐藏检查 - 隐藏文件/目录全部过滤（点开头 + Thumbs.db、desktop.ini 等） - API 密钥认证：`hash_equals` 防时序攻击，支持多密钥 - CORS 白名单：仅 `.api_cors` 中列出的 Origin 放行 - 响应头：CSP（无 unsafe-inline）/ nosniff / X-Frame-Options / Referrer-Policy - CLI 脚本双重保护：Nginx deny + `PHP_SAPI` 运行环境守卫 ## API v1 Base URL：`https://<域名>/api/v1` 认证：请求头 `X-API-Key: <密钥>`（推荐）或查询参数 `?key=<密钥>`；`/health` 免认证。 | 端点 | 参数 | 说明 | |---|---|---| | GET /health | - | 健康检查（公开，供平台探活） | | GET /list | dir（目录，默认根）；page / per_page（可选分页，默认 100、上限 500） | 目录内容：folders + files（含字节大小 / 类型 / mtime / SHA-512 / 下载直链 / 预览链接 previewUrl / hashStatus） | | GET /tree | - | 全量目录树 | | GET /info | path（文件相对路径） | 单文件详情，hashStatus 为 ready / pending，含 previewUrl | | GET /search | keyword（≤100 字符） | 按名称搜索，返回前 100 条 + total | 统一响应格式： ```json { "code": 0, "message": "ok", "data": { } } ``` 调用示例： ```bash # 健康检查（免认证） curl https://<域名>/api/v1/health # 列目录（分页） curl -H "X-API-Key: <密钥>" "https://<域名>/api/v1/list?dir=tools&page=1&per_page=50" # 文件详情 curl -H "X-API-Key: <密钥>" "https://<域名>/api/v1/info?path=tools/setup.exe" ``` 错误码：`400` 参数无效 · `401` 密钥缺失或错误 · `404` 资源不存在 · `405` 方法不允许 · `503` 服务未就绪（目录缺失 / 未配置密钥） ## API 密钥管理密钥通过 CLI 工具 `apiKeyGen.php` 管理（仅命令行可执行，Web 访问返回 403），支持多密钥并存，供不同平台各自持有。 ```bash # 生成密钥（追加到 .apikey，旧密钥保留有效） php apiKeyGen.php # 查询密钥（显示序号、完整密钥与前 8 位标识） php apiKeyGen.php --list # 删除密钥（按序号，对应 --list 显示的 [N]） php apiKeyGen.php --del=2 # 删除密钥（按前缀，唯一匹配才执行，多个匹配时拒绝并提示加长前缀） php apiKeyGen.php --del=1a2b3c4d # 重置密钥（清空后重新生成一个，旧密钥全部立即失效） php apiKeyGen.php --regen ``` 说明： - 密钥为 64 位十六进制（32 字节强随机），文件写入为原子操作，权限 600 - 多平台调用建议各自生成独立密钥，泄露或下线时按序号/前缀单独删除，不影响其他平台 - `--regen` 会使所有旧密钥失效，仅在全球泄露等极端情况使用，执行后需逐一通知调用方更新 - 密钥文件默认位于项目根 `.apikey`（受 Nginx 点文件规则保护）；如已按部署第 5 步移出 webroot，CLI 需带 `SYTCRAFT_CONFIG_DIR=<配置目录>` 运行 ## CORS 跨域配置浏览器跨域调用 API（如平台页面内嵌 fetch）需将平台 Origin 加入白名单，否则浏览器会拦截响应；服务端直连（curl / 后端请求）不受 CORS 限制。白名单通过 CLI 工具 `corsGen.php` 管理（仅命令行可执行，Web 访问返回 403）。 ```bash # 添加来源（格式：http(s)://域名或IP[:端口]，自动去重，容错结尾斜杠） php corsGen.php --add=https://panel.example.com # 查询白名单（显示序号与来源，* 标注风险提示） php corsGen.php --list # 删除来源（按序号，对应 --list 显示的 [N]） php corsGen.php --del=2 # 删除来源（按前缀，唯一匹配才执行，多个匹配时拒绝并提示加长前缀） php corsGen.php --del=panel.example.com # 清空白名单（跨域调用全部被拒，API 直连不受影响） php corsGen.php --clear # 允许任意来源（设为 *，任何网站均可在用户浏览器中调用本 API，不推荐） php corsGen.php --allow-all ``` 说明： - 匹配规则为**完整 Origin 精确匹配**（协议 + 域名 + 端口全一致才放行），不支持通配子域名；多环境（生产 / 测试 / 本地 `http://localhost:3000`）可各加一条 - 白名单文件默认位于项目根 `.api_cors`（受 Nginx 点文件规则保护），原子写入，权限 600 - 预检请求（OPTIONS）与正式响应使用同一白名单；未配置白名单时 API 仍可正常服务，仅浏览器跨域读取被拦截 - 如已按部署第 5 步将配置移出 webroot，CLI 需带 `SYTCRAFT_CONFIG_DIR=<配置目录>` 运行 ## 部署指南 ### 1. 环境要求 PHP ≥ 7.2（CLI + FPM）、Nginx、宝塔面板（可选，用于计划任务管理） ### 2. 初始化 ```bash cd <项目根目录> # 生成 API 密钥（写入 .apikey，权限 600） php apiKeyGen.php # （平台浏览器内嵌调用时）添加 CORS 白名单 php corsGen.php --add=https://<平台域名> # 首次全量计算哈希 php hashWorker.php --scan ``` ### 3. Nginx 伪静态规则 ```nginx # 点文件全部禁止（覆盖 .apikey / .api_cors / .hashes.json 等） location ~ /\. { deny all; } # CLI 脚本禁止 Web 访问 location ~ ^/(functions\.php|hashWorker\.php|apiKeyGen\.php|corsGen\.php)$ { deny all; } # API 路由 rewrite ^/api/v1/(list|tree|info|search|health)$ /api.php?action=$1 last; # 目录浏览路由（/d/xxx 必须重写，否则回退渲染首页导致 SPA 导航失效） rewrite ^/d/(.+)$ /index.php?dir=$1 last; # 兜底路由 location / { try_files $uri /index.php?$query_string; } # 错误页 error_page 403 /403.html; error_page 404 /404.html; location = /403.html { internal; } location = /404.html { internal; } ``` HTTPS server 块追加 HSTS： ```nginx add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always; ``` ### API 限流（可选） `limit_req_zone` 只能定义在 Nginx **http 块**，而宝塔伪静态属于 server 块——直接在伪静态里写 `limit_req` 会报 `zero size shared memory zone "apiLimit"`。正确开启方式： 1. 宝塔 → 软件商店 → Nginx → 设置 → 配置修改，在 `http { }` 内添加： ```nginx limit_req_zone $binary_remote_addr zone=apiLimit:10m rate=10r/s; ``` 2. 保存后再在伪静态中追加： ```nginx location /api/ { limit_req zone=apiLimit burst=20 nodelay; } ``` ### 4. 计划任务（宝塔面板）每 5 分钟执行一次： ```bash cd <项目根目录> && php hashWorker.php ``` ### 5. （可选）配置移出 webroot 默认 `.apikey` / `.api_cors` 位于项目根，已受 Nginx 点文件规则保护。如需移出 webroot： ```bash mkdir <配置目录> mv .apikey .api_cors <配置目录>/ ``` 在 Nginx 的 PHP fastcgi 参数区传递环境变量： ```nginx fastcgi_param SYTCRAFT_CONFIG_DIR <配置目录>; ``` 此后 CLI 工具需带环境变量运行： ```bash SYTCRAFT_CONFIG_DIR=<配置目录> php apiKeyGen.php ``` ## 运维手册 ### Worker 三种模式 ```bash php hashWorker.php # 处理队列后退出（计划任务用） php hashWorker.php --scan # 全量扫描补队列后处理（批量新增文件后用） php hashWorker.php --daemon # 常驻进程，每 10 秒检查队列 ``` 单文件计算超 5 分钟自动放回队列下次继续；多 Worker 由单例锁互斥，不会重复计算。 ### 测试 ```bash php tests/functionsTest.php # 58 项断言 + 全项目 php -l 语法检查 ``` ### 常见问题 | 现象 | 原因与处理 | |---|---| | SPA 切目录页面不动 | SPA 请求已直连 `/index.php?dir=` 并带时间戳，不依赖伪静态与 CDN；若仍异常多为浏览器缓存旧 JS，Ctrl+F5 强刷或 CDN 控制台刷新。直开 `/d/` 链接（新标签/无 JS）仍需伪静态含该重写规则 | | 哈希一直"计算中" | Worker 未运行；检查计划任务，或手动执行 php hashWorker.php | | 大文件哈希迟迟不出 | >50MB 依赖 Worker；100GB 文件需多个任务周期，属正常 | | API 返回 503 | .apikey 未生成，或 downloads 目录缺失 | | 跨域调用被拦截 | 调用方 Origin 未加入白名单：php corsGen.php --add=https://<平台域名> 后重试 | | 需要强制重算哈希 | 删除 downloads/.hashes.json 后执行 php hashWorker.php --scan |