shield_lock
金大哥
← 返回 MCP 目录
public公开dns本地运行

blankfiles-website

Laravel驱动的空白文件网站，提供按类型和分类浏览下载最小化有效空白文件的功能，文件数据通过CDN从外部仓库获取。

article

README

🚀 空白文件网站

这是一个基于 Laravel 的应用程序，为 blankfiles.com 提供支持。用户可以按类型和类别浏览并下载最小有效空白文件。文件数据和资源通过可配置的 CDN 从 filearchitect/blank-files 仓库提供。

🚀 快速开始

本项目是一个基于 Laravel 的应用程序，用于搭建空白文件网站。用户可通过该网站按类型和类别浏览并下载最小有效空白文件。

✨ 主要特性

  • 支持按文件类型和类别浏览与下载空白文件。
  • 文件数据和资源通过可配置的 CDN 从指定仓库获取。
  • 提供 Web 界面和 API 接口，方便不同方式的访问。
  • 支持缓存配置，可减少 CDN 请求。
  • 具备 API 速率限制和使用分析日志。

📦 安装指南

环境要求

  • PHP 8.2 及以上版本
  • Composer
  • Node.js 18 及以上版本（用于 Vite 前端构建）

安装步骤

git clone https://github.com/filearchitect/blankfiles-website.git
cd blankfiles-website
composer install
cp .env.example .env
php artisan key:generate

在 .env 文件中设置 CDN_URL（详见 配置说明）。然后构建前端并运行应用：

npm install && npm run build
php artisan serve

或者使用 Laravel Herd 并配置 .test 域名。

📚 详细文档

配置说明

| 变量 | 描述 | | ---- | ---- | | CDN_URL | 必需。用于构建可下载文件 URL 的基础 URL，格式为 {CDN_URL}/files/{filename}。默认值：https://raw.githubusercontent.com/filearchitect/blank-files/main（在 config/app.php 中设置）。 | | CATALOG_URL | 可选。目录 JSON 文件（files/files.json）的直接 URL。默认值为 https://raw.githubusercontent.com/filearchitect/blank-files/main/files/files.json，以确保数据的实时性。 | | CACHE_ENABLED | 可选。当设置为 true 时，将缓存从 CDN 获取的文件列表。缓存的 TTL 由 CATALOG_TTL_MINUTES 控制（默认值为 10）。详见 config/cache.php 和 app/Services/FileService.php。 | | CATALOG_TTL_MINUTES | 可选。当 CACHE_ENABLED=true 时，远程目录的缓存 TTL（分钟）。值越小，新格式的更新越及时；值越大，CDN 请求越少。 | | API_KEYS | 可选。用于高频率 API 客户端的逗号分隔的 API 密钥（通过 X-API-Key 或 Authorization: Bearer ... 使用）。 | | API_PUBLIC_RATE_LIMIT | 可选。公共 API 的每分钟请求限制（默认值为 30）。 | | API_KEY_RATE_LIMIT | 可选。使用 API 密钥的每分钟请求限制（默认值为 300）。 | | API_USAGE_LOG_CHANNEL | 可选。API 使用分析的日志通道（默认值为 api_usage）。 | | OPENPANEL_CLIENT_ID | 可选。设置后启用 OpenPanel 网页分析脚本。 | | OPENPANEL_CLIENT_SECRET | 可选。保留用于服务器端 OpenPanel 事件（不暴露给浏览器脚本）。 |

项目结构

| 路径 | 用途 | | ---- | ---- | | app/Http/Controllers/FileController.php | Web 端：主页、文件详情页、下载代理。 | | app/Http/Controllers/Api/FileController.php | API 端：列出所有文件、按类型列出文件。 | | app/Services/FileService.php | 获取目录 JSON 文件（CATALOG_URL）并根据 CDN_URL 格式化文件 URL。 | | routes/web.php | Web 路由（主页、文件展示、下载）。 | | routes/api.php | API v1 路由。 | | resources/views/files/ | 用于文件列表和文件详情的 Blade 视图。 |

部署说明

当推送到 main 分支时，GitHub Actions 会执行以下操作：

  1. 使用 npm ci 和 npm run build 构建前端（Vite）。
  2. 使用 SCP 将 public/build/ 目录复制到 Forge 服务器。
  3. 触发 Laravel Forge 部署。
  4. 在服务器上运行 php artisan optimize:clear。

所需的仓库密钥：

  • FORGE_SSH_HOST — 服务器的 SSH 主机。
  • FORGE_SSH_USER — SSH 用户（例如 forge）。
  • SSH_PRIVATE_KEY — 用于 SCP/SSH 的私钥。
  • FORGE_SERVER_ID — Forge 服务器 ID。
  • FORGE_SITE_ID — Forge 站点 ID。
  • FORGE_API_KEY — Forge 部署令牌。

详见 .github/workflows/deploy.yml。

开发者和机器人相关

基础 URL

生产环境：https://blankfiles.com。支持 HTML 和 JSON 格式；在适用的情况下使用 Accept: application/json。

Web 路由

| 方法 | 路径 | 描述 | | ---- | ---- | ---- | | GET | / | 主页：按类别列出文件。当 Accept: application/json 时返回 JSON 格式。限流：30 次/分钟。 | | GET | /upload-testing | 专注于二进制文件的上传测试着陆页，链接到高需求的文件格式和类别。 | | GET | /files/{category}/{type} | 对 SEO 友好的文件详情页（例如 /files/document-spreadsheet/xlsx）。约束条件：category、type = [A-Za-z0-9\-]+。 | | GET | /files/download/{category}/{type} | 下载代理：以 Content-Disposition: attachment 方式流式传输文件（文件名 blank.{type} 或 blank.{type}.zip）。限流：60 次/分钟。 |

API 路由（前缀 api/v1）

| 方法 | 路径 | 响应 | | ---- | ---- | ---- | | GET | /api/v1/files | { "files": [ ... ], "meta": { "version", "generated_at", "count" } }。 | | GET | /api/v1/files/{type} | 相同的架构，按文件扩展名过滤。 | | GET | /api/v1/files/{category}/{type} | 找到匹配项时返回包含一个条目的相同架构；未找到时返回 404。 | | GET | /api/v1/status | API 健康状态 + 聚合目录指标（file_count、type_count、category_count）和上游源信息。 |

机器友好说明

  • 规范的文件目录架构定义在 blank-files 仓库中：files/files.json（键 files，数组元素为 { type, url, category, package? }）。
  • 下载 URL：可使用 API 的 url 字段直接访问 CDN，或使用 GET /files/download/{category}/{type} 进行同源下载并获得可预测的文件名。
  • API 响应和站点地图支持条件请求（ETag、Last-Modified）。
  • 速率限制：基于公共 IP 的限制和可选的 API 密钥限制（X-API-Key）。
  • API 使用分析日志记录到 storage/logs/api-usage-*.log（可配置通道）。
  • 兼容性策略：API 策略。
  • 增长页面的 Web 着陆分析日志记录到 storage/logs/web-traffic-*.log。

客户端代码片段

curl -sS "https://blankfiles.com/api/v1/files/document-spreadsheet/xlsx" \
  -H "Accept: application/json" \
  -H "X-API-Key: $BLANKFILES_API_KEY"

const res = await fetch("https://blankfiles.com/api/v1/files", {
  headers: { "Accept": "application/json", "If-None-Match": etag }
});
if (res.status === 304) {
  // 未更改
}

import requests
r = requests.get("https://blankfiles.com/api/v1/status", timeout=20)
r.raise_for_status()
print(r.json())

兼容性策略

  • /api/v1/* 下的 URL 版本稳定。
  • 重大变更需要新的主要 API 路径版本。
  • 弃用的端点在移除前至少保留 90 天。
  • 可以添加新字段；客户端应忽略未知字段。

相关项目

MCP 服务器（适用于代理市场/注册表）

本仓库现在包含一个最小的 MCP 服务器，将空白文件作为工具调用公开。

  • 脚本：scripts/mcp/blankfiles-mcp.mjs
  • 运行：npm run mcp:server
  • 可选环境变量：BLANKFILES_BASE_URL（默认值：https://blankfiles.com）

可用的 MCP 工具：

  • list_blank_files — 列出文件，可选过滤器（category、type、limit）
  • files_by_type — 按文件扩展名列出条目
  • file_by_category_type — 通过类别 + 扩展名进行确定性单查找

本地 MCP 客户端配置示例：

{
  "mcpServers": {
    "blankfiles": {
      "command": "node",
      "args": ["/absolute/path/to/blankfiles-website/scripts/mcp/blankfiles-mcp.mjs"],
      "env": {
        "BLANKFILES_BASE_URL": "https://blankfiles.com"
      }
    }
  }
}

注册表提交辅助工具：

  • 模板元数据：scripts/mcp/registry/server.json.template
  • 发布清单：scripts/mcp/registry/PUBLISHING.md

已发布的包工作区：

  • packages/blankfiles-mcp（发布为 @filearchitect/blankfiles-mcp）

OpenClaw 技能（ClawHub 可发现性）

本仓库包含一个适用于 OpenClaw 的技能包：

  • 技能路径：skills/blankfiles
  • 技能入口：skills/blankfiles/SKILL.md
  • 发布指南：skills/blankfiles/references/publish.md

典型的发布流程：

npm i -g clawhub
clawhub login
clawhub publish ./skills/blankfiles \
  --slug blankfiles \
  --name "Blank Files Gateway" \
  --version 1.0.0 \
  --changelog "Initial release" \
  --tags latest

📄 许可证

本项目采用 MIT 许可证。

help

运行方式说明

cloud

托管运行

托管运行通常表示这个 MCP Server 由服务方环境承载，用户一般按页面提供的连接方式或授权流程接入，不需要在本地长期启动一个 MCP 进程

  1. 打开服务方连接页
  2. 完成授权或复制端点
  3. 在 MCP 客户端中连接
terminal

本地运行 / 其它方式

本地运行通常需要用户在自己的电脑或服务器上安装依赖，把 server_config 复制到 MCP 客户端，并按 env_schema 补齐环境变量、密钥或其它配置

  1. 复制 server_config
  2. 安装所需依赖
  3. 补齐环境变量后重启客户端