Uguu 1.9.9 介绍与选型指南

目标：介绍 Uguu——PHP 编写的极简临时文件托管/分享平台（Pomf 的直系分支），覆盖项目定位、核心架构、功能特性、最小可用示例、适用场景限制，以及与 Plik、PicoShare、goploader、PsiTransfer、transfer.sh 等同类自托管文件分享组件的量化选型对比。本文为认知与选型篇，全部版本号、星数、特性清单均联网溯源并标注来源与查询日期（2026-11-01），不含本地实测；部署、配置与命令的实测细节见系列后续各篇。

一、环境信息（溯源说明）

本文是认知与选型篇，不含本地实测，以下为溯源对象与信息渠道：

• 溯源对象：Uguu（GitHub 仓库 nokonoko/Uguu），作者 Go Johansson（nekunekus/nokonoko，Pomf AB，瑞典），官网示例站 uguu.se
• 溯源日期：2026-11-01（本文全部版本号、星数、维护状态、特性清单均在该日联网实查）
• 信息渠道：GitHub 仓库 README（raw 源文件）、仓库 package.json 与 src/config.json（版本号双渠道）、RELEASE_NOTE.md（版本沿革）、官方 Wiki《Uguu Configuration & Installation》（部署形态与配置项）、shields.io 徽章 JSON（星数）、awesome-selfhosted 收录页（社区收录与最近活动时间）
• 星数取证方式：shields.io stars 徽章 JSON（https://img.shields.io/github/stars/nokonoko/Uguu.json）返回 {"label":"stars","message":"1.2k"}，查询日期 2026-11-01
• 系列后续篇章：部署细节见《Uguu 1.9.9 Docker Compose 部署指南》，配置项逐项实测见《Uguu 1.9.9 配置参数详解》，上传 API 与过期清理命令见《Uguu 1.9.9 常用命令详解》

二、软件概述

2.1 项目定位

Uguu 自我描述为「a simple lightweight temporary file hosting and sharing platform, but can also be used as a permanent file host」（来源：仓库 README，查询日期 2026-11-01）。它解决的是一类非常具体的需求：给陌生访客一个无需注册的上传页面，文件存进来之后给一条随机文件名的短链，到期自动物理删除。Uguu 是 Pomf 的直系分支（README Credits：「Uguu is based on Pomf which was written by Emma Lejack & Go Johansson」），而 Pomf 的作者之一正是 Uguu 的维护者本人，公共实例 uguu.se 也由其长期运营（首页标注「Max upload size is 128 MiB & files expire after 3 hours」，查询日期 2026-11-01）。

与同类组件相比，Uguu 的差异化定位有三点：

1. 技术栈为 PHP：在本批次同域组件（Plik/PicoShare/goploader/transfer.sh 均为 Go、PsiTransfer 为 Node.js）中，Uguu 是唯一 PHP 实现。对已有 Nginx + PHP-FPM 运维经验（尤其同时托管 WordPress 等 PHP 站点）的团队，运维心智成本最低；
2. 链接即文件名：不像多数组件返回带独立短码的分享页，Uguu 的下载 URL 就是 https://文件域名/随机文件名，浏览器直开即下载/直显，无中间跳转页；
3. 内容安全管控内建：扩展名/MIME 黑白名单、文件哈希（xxh3）黑名单库、上传速率限制三件套是默认功能，面向「对公网开放上传」的场景做了更多防御性设计。

2.2 项目活跃度与可信度

2.3 版本沿革要点

Uguu 的版本节奏是「长期小步维护」，无固定发布周期。1.9.9 的发行注记（源码包内 RELEASE_NOTE.md，查询日期 2026-11-01）包含两条关键内容：

• 修复「通过 API 一次上传多个文件时只有第一个文件被上传」的缺陷——多文件 API 是本版本明确修复点（本文系列部署篇实测确认多文件响应正常）；
• 新增 Docker 开发环境支持（仓库自带 Dockerfile：Alpine 3.20 底座 + Nginx + PHP-FPM 8.3 + Bun 构建，详见部署篇）。

另有一条对选型决策重要的历史沿革：2015-2022 年代码以 MIT 许可发行，2022 年起改为 GPL-3.0（源码文件头注释原文「Note that this was previously distributed under the MIT license 2015-2022」）。若公司商用，作者在源码中明确建议直接联系其解决许可事宜，而非使用 2022 年前的旧代码——把 GPL-3.0 视为当前唯一合规基线即可。

三、核心架构

Uguu 是一个典型的「Nginx + PHP-FPM + 关系库」三层极简结构，全部组件可在单机上运行：

• Web 层（Nginx）：托管编译产物 dist/public/（HTML/CSS/JS/图片），并以 FastCGI 方式把 *.php 请求转给 PHP-FPM。生产推荐用独立子域名（如 files.example.com）直接服务上传文件目录，官方 Wiki 给出主域/子域/单域三种 Nginx 配置模板（来源：官方 Wiki，查询日期 2026-11-01）；
• 应用层（PHP 8.3 + PHP-FPM）：核心逻辑在 src/Classes/ 下五个类——Upload（上传编排：重命名、哈希、过滤、落盘）、Response（JSON/HTML/Text/CSV 四种响应格式与错误码）、Database（PDO 数据访问：files/ratelimit/blacklist 表读写）、Connector（配置加载与错误处理）、expireChecker（过期扫描与物理删除）。配置经 APCu 缓存（键名 UC），修改 config.json 后需重载 PHP-FPM 才生效；
• 存储层：上传文件直接落 FILES_ROOT 目录（默认 /var/www/files/），随机文件名由 ID_CHARSET 字符表生成（默认 8 位、可暴力枚举性低）；元数据存数据库，默认 SQLite（单文件 /var/www/db/uguu.sq3），可切 MySQL/PostgreSQL（DB_MODE 一键切换）；
• 构建层（Bun）：源码仓库不是可直接部署的 PHP 站点——模板（EJS）、JS、CSS 需经 bun install && make && make install 编译进 dist/，页面文案（站点名、副标题、上传上限提示等）在编译期烧录进静态 HTML；
• 清理层（cron）：过期删除不依赖上传请求触发，而是独立脚本 dist/checkExpire.php 由 cron 周期执行（官方推荐每分钟），扫描 files 表中 date 字段早于 expireTime + expireTimeUnit 的记录并 unlink 物理文件，同时顺带清理 24 小时前的速率限制记录。

💡 技术拓展：文件托管类组件的「到期删除」有两种主流实现——请求惰性删除（下载时判断过期再清理，省 cron 但磁盘峰值高）与定时扫描删除（独立 cron/守护进程，磁盘占用可预期）。Uguu 与 Pomf 系采用后者（checkExpire.php 每分钟扫描），Jirafeau 同为定时扫描，而 PicoShare 通过数据表查询在下载路径上做惰性判断。定时扫描方案要求部署方必须配好 cron，否则过期文件会一直占盘——这是 Uguu 部署时最容易被遗漏的一步。

四、功能特性

以下特性均见官方 README 功能清单（查询日期 2026-11-01），并经本文系列后续篇章在 1.9.9 上逐项实测：

• 免注册一键上传：Web 页面支持点击选择、拖拽（Drag & Drop）与剪贴板粘贴（Paste）三种方式，无任何账号体系；
• 上传 API 多格式响应：POST /upload.php（表单字段 files[]），?output= 参数支持 JSON（默认）/HTML/Text/CSV 四种格式；实测 JSON 响应含 hash（xxh3 内容哈希）、filename、url、size、dupe 五字段；
• ShareX 等截图工具对接：API 兼容 ShareX 自定义上传器配置（Windows 生态常用的截图直传链路）；
• 扩展名与 MIME 黑/白名单：FILTER_EXTENSIONS/FILTER_MIME 两张列表 + FILTER_MODE 开关（true=黑名单模式，false=白名单模式），默认黑名单拦截 exe/bat/jar/svg 等 13 类扩展名与 8 类 MIME；DOUBLE_DOTS_EXTENSIONS 处理 tar.gz 等双扩展名；
• 文件哈希黑名单库：BLACKLIST_DB 开启后按 xxh3 哈希比对 blacklist 表，命中即拒收（配合管理面板可沉淀恶意样本）；
• 上传速率限制：RATE_LIMIT 开启后按「IP+UA 指纹」在 ratelimit 表记账，RATE_LIMIT_FILES 份/RATE_LIMIT_TIMEOUT 秒，超限返回明确错误文案；指纹仅在 LOG_IP=false（默认）时也不落明文 IP——隐私优先设计；
• 防重复（ANTI_DUPE）：开启后相同内容哈希的文件只存一份，重复上传直接返回既有 URL（响应中 dupe: true）；
• 可配置过期：expireTime + expireTimeUnit（秒/分/时/天/周/月/年七档），由 cron 脚本物理删除，也可把过期调大近似「永久托管」。

五、快速开始（最小可用示例）

完整的镜像构建与 Compose 编排见《Uguu 1.9.9 Docker Compose 部署指南》，这里只给出「服务已就绪」前提下的一条最小可用链路（以下命令与回显摘自本系列部署篇的实测记录，Ubuntu 24.04 + Uguu 1.9.9，Web 端口 8134）：

# 上传一个文本文件（files[] 为固定字段名，JSON 为默认响应格式）
curl -s -F "files[]=@hello.txt" http://127.0.0.1:8134/upload.php

实测回显：

{
    "success": true,
    "files": [
        {
            "hash": "47272535fb3d837e",
            "filename": "wnBwPUJr.txt",
            "url": "https:\/\/127.0.0.1:8134\/files\/wnBwPUJr.txt",
            "size": 22,
            "dupe": false
        }
    ]
}

拿到 url 后浏览器直开即下载（本地 HTTP 实测时注意把响应里的 https:// 换成 http://，这是 Uguu 硬编码 URL 协议的已知行为，生产环境配 TLS 后无此问题）。更多 API 形态（多文件、text/csv 输出、过滤与限速触发）见《Uguu 1.9.9 常用命令详解》。

六、适用场景与限制

6.1 适用场景

• 运维侧临时传文件：替代 FTP/网盘中转，curl 一条命令从任意服务器把日志、配置、安装包丢到内网共享点，链接直接贴给同事；
• 对外提供匿名上传入口：客服/活动收集大文件，免注册 + 黑白名单 + 限速 + 哈希黑名单的组合比裸奔的网盘目录可控得多；
• 已有 PHP 运维体系的团队：与既有 Nginx/PHP-FPM 栈共用监控、备份、日志体系，SQLite 单文件库的备份就是一个 cp；
• 截图/剪贴板直传：ShareX 用户可把 Uguu 配成私有图床式临时托管。

6.2 限制与不适用

• 无账号、无权限体系：没有用户/分组/配额概念，谁拿到链接谁能下——需要私有空间、访问控制的场景请看 PicoShare（单用户口令）或 Plik（多认证）；
• 无分片/断点续传：大文件受 PHP upload_max_filesize/Nginx client_max_body_size 硬顶，GB 级传输不是它的设计目标；
• 前端文案编译期烧录：站点名、上限提示等页面文案改 config.json 不生效，需重新编译模板（详见配置篇排障实录）；
• 1.9.9 的 CSV 输出有缺陷：?output=csv 实测必返回 500（上游缺陷，详见命令篇排障实录），需要机器可读输出时用 JSON 或 text；
• 到期删除依赖 cron：忘配 cron 则文件只逻辑过期、永不物理删除。

七、同类选型对比

与 Uguu 同域的自托管文件分享组件，本批次已交付多篇实测的对比对象如下（星数与版本均为各组件交付时的实查数据，查询日期随行标注；六者的技术栈恰好覆盖 Go/Node.js/PHP 三条路线）：

选型建议（按场景对号入座）：

• 要匿名 + 内容安全管控：Uguu 是六者中唯一把扩展名/MIME 黑白名单、哈希黑名单、限速做成一等公民的，公网开放上传首选；
• 要权限与认证：Plik 的五类认证提供方（含 OIDC）最完整，企业内网分发优先；
• 要个人私有网盘式分享：PicoShare 的单用户口令 + 每文件自定义到期日最省心；
• 要阅后即焚：goploader 默认一次性视图，语义最贴合；
• 要给客户发一批文件的收取页：PsiTransfer 的分享桶（对方可整包下载）独一档；
• 要纯命令行管道式（cat foo | curl ...）：transfer.sh 体验最佳但已停维护，生产慎用，可评估其维护中的替代品后再定；
• PHP 团队统一技术栈：Uguu 几乎没有对手——同域其余五者没有 PHP 实现。

八、参考链接

• GitHub 仓库：https://github.com/nokonoko/Uguu
• 官方配置与安装 Wiki：https://github.com/nokonoko/Uguu/wiki/Uguu-Configuration-%26-Installation
• 官方示例站：https://uguu.se
• 上游 Pomf 项目：https://github.com/pomf/pomf
• 配套管理面板 Moe Panel：https://github.com/Pomf/MoePanel
• 本系列部署篇：《Uguu 1.9.9 Docker Compose 部署指南》
• 本系列配置篇：《Uguu 1.9.9 配置参数详解》
• 本系列命令篇：《Uguu 1.9.9 常用命令详解》