Z-FSS 开发文档

1. 概述

Z-FSS（Zhuolu File Storage Service）是一套基于 Laravel 11 + LayUI + MySQL 的轻量文件存储系统，类似阿里云 OSS / MinIO 的精简版。

支持多类型文件上传（参考阿里云 OSS 常见对象类型，详见第 2 节）
文件物理保存在 Laravel 项目根目录的 zfss/ 下，并同步到 public/zfss/ 供 HTTP 访问
返回完整 URL，例如：https://z-fss.ridacab.com/zfss/2026/10/22/xxx.pdf
开放 API，使用 AccessKey + SecretKey 鉴权
单文件上限：100 MB

2. 支持的文件类型

以下类型参考阿里云 OSS 常见对象格式。上传时以文件扩展名为主校验；MIME 类型也会辅助校验（允许 application/octet-stream）。

分类	支持的扩展名
图片	jpg, jpeg, png, gif, bmp, webp, svg, ico, tif, tiff, heic, heif, psd, ai, eps
文档 / 办公	pdf, doc, docx, xls, xlsx, ppt, pptx, txt, rtf, csv, md, odt, ods, odp, pages, numbers, key
压缩包	zip, rar, 7z, tar, gz, tgz, bz2, xz
音频	mp3, wav, aac, flac, ogg, m4a, wma, amr, ape
视频	mp4, avi, mov, wmv, flv, mkv, webm, m3u8, ts, 3gp, mpg, mpeg, rm, rmvb, m4v
网页 / 开发资源	html, htm, css, js, json, xml, yaml, yml, map, wasm
字体	ttf, otf, woff, woff2, eot
安装包 / 其他	apk, ipa, dmg, iso, img, bin, dat, log, sql, conf, ini, pem, crt, cer, p12

合计：共支持 94 种扩展名。

禁止上传的扩展名（安全黑名单）

即使未在白名单中，以下类型也会被拒绝（防止可执行脚本通过 Web 目录被访问）：

php, phtml, php3, php4, php5, php7, php8, phar, asp, aspx, asa, asax, ascx, ashx, asmx, jsp, jspx, cgi, htaccess, htpasswd, shtml, exe, bat, cmd, com, msi, scr, vbs, ps1, sh

如需增减类型，请修改服务器上的 config/zfss.php，并执行 php artisan config:clear。

3. 快速开始

3.1 获取密钥

登录管理后台 → API 密钥 → 创建密钥，获得 AccessKey 与 SecretKey。

3.2 Base URL

https://z-fss.ridacab.com/api/v1

3.3 鉴权方式（任选其一）

方式 A：请求头（推荐）

X-Access-Key: 你的AccessKey
X-Secret-Key: 你的SecretKey

方式 B：Authorization Bearer

Authorization: Bearer {AccessKey}:{SecretKey}

方式 C：Query / 表单参数

access_key=你的AccessKey&secret_key=你的SecretKey

4. 统一响应格式

{
  "code": 0,
  "message": "success",
  "data": { ... }
}

字段	说明
code	0 表示成功，非 0 为错误码（与 HTTP 状态码接近）
message	提示信息
data	业务数据，失败时为 null

5. 接口列表

POST 上传文件

POST https://z-fss.ridacab.com/api/v1/upload
Content-Type: multipart/form-data

参数	位置	必填	说明
file	form-data	是	文件字段名必须为 file，类型见第 2 节
X-Access-Key	Header	是	AccessKey
X-Secret-Key	Header	是	SecretKey

成功响应示例：

{
  "code": 0,
  "message": "上传成功",
  "data": {
    "uuid": "a1b2c3d4-....",
    "url": "https://z-fss.ridacab.com/zfss/2026/10/22/20261022153000_abcdef.pdf",
    "original_name": "contract.pdf",
    "size": 204800,
    "mime_type": "application/pdf",
    "extension": "pdf",
    "created_at": "2026-10-22 15:30:00"
  }
}

GET 文件列表

GET https://z-fss.ridacab.com/api/v1/files?page=1&limit=20&keyword=

GET 文件详情

GET https://z-fss.ridacab.com/api/v1/files/{uuid}

DELETE 删除文件

DELETE https://z-fss.ridacab.com/api/v1/files/{uuid}

6. 调用示例

cURL

curl -X POST "https://z-fss.ridacab.com/api/v1/upload" \
  -H "X-Access-Key: ZFDEMOACCESSKEY01" \
  -H "X-Secret-Key: zfss_demo_secret_key_please_change" \
  -F "file=@/path/to/document.pdf"

PHP (Guzzle / Laravel Http)

use Illuminate\Support\Facades\Http;

$response = Http::withHeaders([
    'X-Access-Key' => '你的AccessKey',
    'X-Secret-Key' => '你的SecretKey',
])->attach('file', file_get_contents('/path/to/document.pdf'), 'document.pdf')
  ->post('https://z-fss.ridacab.com/api/v1/upload');

$data = $response->json();
$url = $data['data']['url'] ?? null;

JavaScript (fetch)

const form = new FormData();
form.append('file', fileInput.files[0]);

const res = await fetch('https://z-fss.ridacab.com/api/v1/upload', {
  method: 'POST',
  headers: {
    'X-Access-Key': '你的AccessKey',
    'X-Secret-Key': '你的SecretKey'
  },
  body: form
});
const json = await res.json();
console.log(json.data.url);

Python (requests)

import requests

files = {'file': open('document.pdf', 'rb')}
headers = {
    'X-Access-Key': '你的AccessKey',
    'X-Secret-Key': '你的SecretKey',
}
r = requests.post('https://z-fss.ridacab.com/api/v1/upload', headers=headers, files=files)
print(r.json()['data']['url'])

7. 部署说明（自有域名）

将代码部署到服务器，Nginx/Apache 将域名（如 z-fss.zhuoluyunkeji.com）指向 public/ 目录
配置 .env 中的 APP_URL=https://z-fss.zhuoluyunkeji.com 与 MySQL 连接
执行 php artisan migrate --seed 初始化数据库
确保项目根目录 zfss/ 与 public/zfss/ 可写
生产环境请修改默认管理员密码并重新创建 API 密钥

默认管理员：admin@zfss.local / admin123

更多细节见项目根目录 README.md。