Jirafeau 介绍与选型指南

Jirafeau（PHP 一次性临时文件托管）认知篇：项目沿革与定位、无数据库存储架构、功能特性清单、适用场景限制与同类工具量化选型对比，基于官方仓库与生态实查（查询日期 2026-10-30）。

JirafeauJirafeau文件分享PHP2026/10/30

Jirafeau 介绍与选型指南

目标：说清 Jirafeau 这一 PHP 一次性临时文件托管工具的定位、架构、功能边界与同类选型差异，帮助读者判断"什么时候该用它、什么时候不该用"。本文为认知篇，全部信息来源于官方仓库与官方生态站点联网溯源（查询日期 2026-10-30，标注于各节），未混入本地实测数据。

一、环境信息

  • 溯源方式：联网实查官方 GitLab 仓库、原仓库、Docker Hub、官方容器镜像仓库（API 响应原文留档，查询日期 2026-10-30）
  • 软件本体：Jirafeau（PHP 编写的 Web 临时文件托管 / "one-click filesharing"）
  • 许可证：AGPL-3.0（官方 README 徽章与 LICENSES 目录实查）
  • 官方仓库（社区续作版）：https://gitlab.com/jirafeau/Jirafeau（37 stars，最后活动 2026-10-29，实查）
  • 原始仓库（已停止维护）：https://gitlab.com/mojo42/Jirafeau（273 stars / 122 forks，最后活动 2025-01-09，实查）
  • 最新稳定版：4.7.2（GitLab tag 提交时间 2026-06-27，实查）
  • 官方演示站：https://jirafeau.net/（官方 README 指明）
  • 运行依赖：PHP（官方镜像基于 PHP 8.3 + lighttpd，官方 Dockerfile 实查）；无数据库

💡 说明：Jirafeau 名字来源于法语 "où est-ce qu'on la fate?" 的谐音梗——官方仓库描述为 "Jirafeau: a simple way to upload a file"。它不是下载工具，而是一个"上传一次、分享一条链接"的自托管临时文件托管服务。

二、软件概述

2.1 定位

Jirafeau 是一个"一键飞传"（one-click filesharing）自托管服务：选择文件 → 上传 → 得到一条下载链接，全部流程不需要注册账号。官方 README 对它的第一句描述是 "Jirafeau is a 'one-click-filesharing': Select your file, upload, share a link. That's it."（来源：官方 README，查询日期 2026-10-30）。

它的设计哲学是 KISS（Keep It Simple, Stupid）——官方明确声明 "Jirafeau project won't evolve to a file manager and will focus to keep a very few dependencies"，即不打算做成文件管理器，而是把依赖压到最少：无数据库、纯 PHP + 文件系统即可运行。

2.2 项目沿革（重要）

Jirafeau 的"官方仓库"需要特别注意，这里存在一次接力（以下时间线均实查于 2026-10-30）：

阶段仓库状态
前身Jyraphe（gna.org）Jirafeau 基于 Jyraphe 0.5 稳定版 fork 而来，官方 README 注明，原站已存档（web.archive.org 快照可查）
原项目gitlab.com/mojo42/Jirafeau（作者 Jérôme Jutteau）已停止维护：fork README 明确写有 "This project is a fork of the discontinued project"，原仓库最后活动 2025-01-09（GitLab API 实查，273 stars / 122 forks）
现官方gitlab.com/jirafeau/Jirafeau（社区续作）2024 年起接棒开发，README 声明 "In this repository we are aiming to continue development of the original Jirafeau project"；最后活动 2026-10-29（GitLab API 实查，37 stars）

因此 2024 年之后查到的 4.6.x / 4.7.x 版本均出自社区续作仓库。本文（及本专栏全部 4 篇）基于续作官方的最新稳定版 4.7.2。

💡 技术拓展：自托管临时文件托管（one-time file sharing）与网盘（file manager）是两类产品形态。前者围绕"一条链接的生命周期"设计——限时、限次（一次性）、口令保护、到期自动删除，不提供用户体系与长期目录管理；后者围绕"人的文件资产"设计——目录树、配额、分享协作。Jirafeau 属于前者，与它同形态的还有 Uguu、goploader、transfer.sh、Plik 等（对比见第七节）。

三、核心架构

（来源：官方仓库源码结构与 docker/ 目录文件实读，查询日期 2026-10-30）

3.1 运行形态

Jirafeau 是典型的 PHP 经典架构：Web 服务器 + PHP-FPM + 文件系统，无数据库、无缓存服务、无消息队列。官方镜像内部由 lighttpd 承载 HTTP、php-fpm 执行 PHP（官方 Dockerfile：FROM php:8.3-fpm-alpine + apk add lighttpd）。官方 README 强调 "No database, only use basic PHP"。

3.2 入口文件分工

仓库根目录的 5 个 PHP 入口各司其职（源码树实查）：

入口职责
index.php上传主页（Web 界面，HTML5 分块异步上传）
f.php下载页：?h=<链接名> 取文件，&k=<口令> 带下载口令，&d=1 直接下载，&d=<删除码> 删除，&p=1 预览
script.php脚本接口（HTTP API）：POST 上传、GET 下载/删除、版本与容量查询，并可通过 ?lang=bash 自动生成 Bash 客户端脚本
admin.php管理界面：清理过期、清点存储、按名称/哈希/链接名检索、删除链接，兼带 PHP-CLI 两个维护子命令（clean_expired / clean_async）
tos.php可定制的服务条款页

3.3 数据存储模型

数据目录（默认 /data）下分三个子目录（源码 docker_config.php 与官方 docker/README.md 实查）：

  • files/：文件内容按哈希分片存放（如 files/fec2ab10/aea6b090/4ad54eb7/3e027314/<哈希>），同名哈希文件只存一份，旁边以 <哈希>_count 引用计数——这是文件级去重（deduplication）的基础；
  • links/：每个分享链接一个元数据文件，记录文件哈希、过期时间、口令哈希、一次性标记、上传者 IP、下载次数等；
  • async/：HTML5 异步分块上传的临时中转。

删除链接时引用计数递减，计数归零即物理删除文件内容；这一机制在官方仓库的 lib/functions.php 中实现（jirafeau_delete_link）。

3.4 配置模型

配置收敛在单一文件 lib/config.local.php（PHP 数组），模板为 lib/config.original.php（约 30 个配置项）。安装时向导或镜像首启脚本生成它；有效期的 9 个档位（minute/hour/day/week/fortnight/month/quarter/year/none）由 availabilities 数组控制。配置体系详见本专栏《Jirafeau 4.7.2 配置参数详解》。

四、功能特性

（来源：官方 README 功能清单 + CHANGELOG.md 实读，查询日期 2026-10-30）

特性说明
一次上传双链接每次上传生成一条下载链接 + 一条删除链接
大文件分块上传HTML5 File API 分块异步上传，规避 PHP post_max_size 限制，带进度/速率/剩余时间显示
有效期 9 档minute / hour / day / week / fortnight / month / quarter / year / none，可逐档开关（availabilities）
一次性链接下载一次后自动销毁（one_time_download，4.7.x 支持默认勾选）
下载口令上传方可设口令；download_password_requirement 支持 optional / required / generated（自动生成）三态，4.7.2 起口令以 SHA256 哈希存储
上传口令与 IP 白名单upload_password（多口令）、upload_ip / upload_ip_nopassword（CIDR，IPv4）
管理口令admin_password 以 SHA256 存储；亦支持 HTTP 认证托管（admin_http_auth_user）与管理端 IP 白名单（admin_ip）
文件级去重file_hash 设为 md5 时同内容文件只存一份（默认 random 不去重）；md5_outside 为低成本折中
服务端加密enable_crypt 开启后密钥不落库（返回给上传者），但与去重互斥
浏览器预览preview 开启后可预览可预览类型（4.7.x 连续修补了 SVG/MIME 嗅探类预览漏洞）
短链接4.7.0 新增 use_shortlinks，需要 Web 服务器 URL 重写支持
下载统计4.6.0 引入，记录下载次数与最后下载时间/来源
管理界面admin.php：清理过期、清点存储占用、按名称/哈希/链接检索、删除
脚本接口script.php HTTP API + 自动生成的 Bash 客户端（send/get/delete 三命令）
定时清理镜像内置 cleanup.sh 每日执行 admin.php clean_expired / clean_async；源码部署可用 cron 调用
多语言与主题语言包位于 lib/locales/（含中文），主题位于 media/，明暗两套（style / dark_style）
服务条款页tos.php 可定制，页脚自动带出组织名与联系人
X-Accel/X-Sendfile 卸载use_xsendfile 将文件下发交给 Web 服务器；另有 LiteSpeed 专用 workaround

五、快速开始

最小可用路径为官方镜像 + Docker Compose（来源：官方仓库 docker-compose.yaml 与 docker/README.md，查询日期 2026-10-30）。最小服务定义如下：

name: jirafeau-4.7.2-stack
services:
  web:
    image: registry.gitlab.com/jirafeau/jirafeau:4.7.2
    ports:
      - "8080:80"
    volumes:
      - ./jirafeau_data:/data
    environment:
      ADMIN_PASSWORD: q1w2e3r4   # 管理界面口令（示例值）
    restart: unless-stopped

启动后访问服务端口即进入上传主页；管理界面位于 /admin.php。首启时若不设 ADMIN_PASSWORD，镜像会自动生成一个 20 位随机口令并打印在启动日志中（官方 docker/README.md 声明）。完整的部署步骤、首启日志解读、上传/一次性链接/过期/管理端验证均在《Jirafeau Docker Compose 部署指南》中逐条实测给出。

六、适用场景与限制

6.1 适用场景

  • 临时文件分发：给同事/客户一个"看完即走"的下载链接，到期自动清理，不留存储尾巴；
  • 运维工件传递：日志包、抓包文件、构建产物的中转站——配合 Bash 客户端可完全脱离浏览器，一条命令上传并取回链接；
  • 敏感文件交接：一次性链接 + 下载口令 + 服务端加密组合，链接泄露后也不会二次下载；
  • 内网/家庭 NAS 轻量服务：无数据库、单容器、内存占用极小，适合常驻低配设备。

6.2 限制（官方声明 + 生态实查）

  • 无用户体系：没有账号、配额与目录管理，不适合作为团队长期文档库（官方明确不做文件管理器）；
  • 单机存储：数据落本地文件系统，无原生集群/分布式形态；
  • 热度体量中等：原项目 273 stars（GitLab 实查），社区续作 37 stars——是小众但持续维护的工具，选型时不应期待大型社区生态；
  • 无官方 Debian 包：Debian 官方源无 jirafeau 包（sources.debian.org API 实查，查询日期 2026-10-30），Linux 部署以容器或源码为主；
  • 预览安全边界：预览功能历史上多次出现 MIME 嗅探类 CVE（CVE-2022-30110 / CVE-2024-12326 / CVE-2025-7066 / CVE-2026-1466，CHANGELOG 实读），续作仓库已系统性修复，但生产环境建议关闭 preview 或保持版本跟进；
  • 镜像不含安装向导：官方容器镜像剥离了 install.php（本专栏部署篇实测），容器化路径完全依赖环境变量首启配置。

七、同类选型对比

同形态候选：Chibisafe（Node.js 网盘型，平台已交付）、goploader（Python）、transfer.sh（Go，已停维护）、Plik（Go）、Uguu（PHP）。对比维度与数据来源：Jirafeau 侧为本节实查数据；Chibisafe 侧引用本站已发布评测（见文末链接）；其余项目为公开资料的一般性描述（未逐项实测，选型时请以各自官方文档为准）。

维度Jirafeau 4.7.2Chibisafe 6.xgoploadertransfer.shPlik
技术栈PHP + lighttpdNode.js + React（前后端分离）PythonGoGo
依赖无数据库，纯文件系统需数据库（如 PostgreSQL）+ 对象存储可选单二进制 + SQLite单二进制单二进制
一次性链接✅ 内置✅ 支持❌（永久链接为主）❌（限时）✅ 支持
有效期控制9 档可配置有过期策略弱有有
下载口令✅（optional/required/generated）✅❌❌✅
文件级去重✅（md5 模式）❌❌❌❌
服务端加密✅（与去重互斥）✅❌❌✅
管理界面✅（清理/检索/删除/清点）✅（完整管理后台）❌❌✅
CLI/APIBash 客户端 + HTTP APIOpenAPI 77 路径（实测）HTTP APIHTTP APIHTTP API + CLI
部署体量单容器，极轻三容器编排（前端/后端/网关）极轻极轻极轻
维护状态活跃（2026-10-29 有活动）活跃缓慢已停维护活跃
镜像热度取证社区镜像聚合 pulls ≈ 3.7M（Docker Hub 实查）见本站评测———

选型建议：

  • 只想要"限时/限次/口令"的纯临时链接服务、且希望单容器极轻部署 → Jirafeau；
  • 需要完整网盘体验（账号、目录、配额、大文件管理后台）→ Chibisafe（见本站评测）；
  • 只需要一条命令在服务器间传文件、不需要 Web 界面 → transfer.sh / Plik 类单二进制更顺手（但 transfer.sh 已停维护，慎选）。

八、参考链接