Uguu 1.9.9 配置参数详解

目标：逐项讲解 Uguu 1.9.9 的 config.json 全部 40 余个参数——位置、加载机制、分组语义、默认值与实测行为（含官方文档未写清的坑：max_upload_size 只管前端、站点文案编译期烧录、配置被 APCu 缓存需重启生效），并给出与 Nginx/PHP 三层上传限制的配合关系。本文所有实测均在 Ubuntu 24.04 LTS（x86_64）+ Nginx 1.26.3 + PHP 8.3.15 + SQLite 3.45.3 环境完成（2026-11-01，Uguu 1.9.9）。

一、环境信息

• 操作系统：Ubuntu 24.04 LTS（x86_64）
• 软件版本：Uguu 1.9.9（官方仓库 master；package.json 与 src/config.json 双渠道确认）
• 组件版本：Nginx 1.26.3、PHP-FPM 8.3.15、SQLite 3.45.3（nginx -v、php -v、sqlite3 --version 实测）
• 服务实例：Web 端口 8134（部署形态见《Uguu 1.9.9 Docker Compose 部署指南》）
• 运行时配置位置：/var/www/uguu/dist/config.json
• 源码引用：src/Classes/Upload.php、src/Classes/expireChecker.php、src/Classes/Database.php（1.9.9 源码）

二、配置文件的位置与加载机制

Uguu 的配置有两份、一进一出：

加载机制有三个必须理解的细节（均有源码与实测依据）：

1. APCu 缓存：Connector::loadConfig() 与 expireChecker::loadConfig() 优先从 APCu 取配置（缓存键 UC），只有 APCu 未启用或未命中才读文件。因此改完 dist/config.json 必须重载 PHP-FPM（裸机 systemctl reload php8.3-fpm，Compose 部署 docker compose restart uguu），否则改了也白改——本系列实测中每一轮配置变更均以重启后行为变化确认了这一点；
2. 运行时与编译期分离：siteName、subTitle、max_upload_size 的页面展示文案等在 make 编译期就固定进了 dist/public/*.html。实测把运行时 config.json 的 siteName 改成 "Uguu Lab"、expireTime 改成 30 minutes 后，首页 <title> 仍是编译期的 Uguu · Temporary file hosting、提示仍是 Max upload size is 128 MiB & files expire after 8 hours.，但后端过期判断已按 30 分钟执行——要改页面文案必须改 src/config.json 重新构建；
3. JSON 健壮性：loadConfig() 对 JSON 解析失败直接报 Invalid JSON in config file.（HTTP 500），手改文件后建议先 jq . config.json 静默校验。

三、站点信息与编译期参数

四、上传限制参数：max_upload_size 的三层真相

这是 Uguu 官方文档里最容易被误解的参数：它在后端代码中没有任何执行点（1.9.9 源码中仅 src/templates/partials/upload_form.ejs 与 lead.ejs 两处模板引用）。服务端真正的硬限由另外两层把守：

实测证据：把 config.json 的 max_upload_size 改成 1（页面上会显示 1 MiB，但该值不重编译不生效）并重启后，直接用 curl 传一个 2MB 文件——成功：

curl -s -F "files[]=@big2m.bin" http://127.0.0.1:8134/upload.php

{
    "success": true,
    "files": [
        {
            "filename": "yGNjTZlU.bin",
            "size": 2097152,
            "dupe": false
        }
    ]
}

结论：要收紧 API 侧上限，必须同时调小 Nginx client_max_body_size 与 PHP upload_max_filesize/post_max_size；config.json 只改前端体验。三层保持「PHP ≥ Nginx = config 提示值」的比例（PHP 的 post_max_size 需容纳表单开销，官方建议设为文件上限的 2 倍）。

五、过期与存储参数

过期机制与 expireTime 的实测闭环（1 分钟过期档）：

# 到期前库里有 8 条记录、files 目录 8 个文件
php /var/www/uguu/dist/checkExpire.php
# （过期文件存在时脚本静默删除，无任何输出）

sqlite3 /var/www/db/uguu.sq3 "SELECT id, filename FROM files;"
# （空）——files 表记录与物理文件全部删除

curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8134/files/HEJAifkR.txt
# 404

完整实测与 cron 配置见《Uguu 1.9.9 常用命令详解》。

六、数据库参数

建库方式：SQLite 用官方 schema 一次性初始化（sqlite3 $DB_PATH -init src/static/dbSchemas/sqlite_schema.sql ""）；镜像部署由 entrypoint 检测 DB_PATH 不存在时自动执行。库内四张表实测结构（PRAGMA table_info(files) 原样回显）：

0|id|INTEGER|1||1
1|hash|char(40)|0|NULL|0
2|originalname|varchar(255)|0|NULL|0
3|filename|varchar(30)|0|NULL|0
4|size|INTEGER|0|NULL|0
5|date|INTEGER|0|NULL|0
6|ip|char(15)|0|NULL|0

其余三张表：ratelimit（限速记账：iphash/files/time）、blacklist（哈希黑名单）、accounts（管理面板 Moe Panel 使用的账号表，核心功能不依赖）。

七、内容管控参数

7.1 FILTER_MODE / FILTER_EXTENSIONS / FILTER_MIME

两个方向的实测（同一份 PNG，扩展名 png 不在默认表内）：

• 黑名单模式（FILTER_MODE: true，默认）：上传成功——png 不在黑名单；
• 白名单模式（FILTER_MODE: false）：上传被拒——

{
    "success": false,
    "errorcode": 415,
    "description": "Filetype not allowed"
}

黑名单模式的拦截实测（setup.exe）：

HTTP/1.1 415 Unsupported Media Type
Content-Type: application/json; charset=UTF-8

{
    "success": false,
    "errorcode": 415,
    "description": "Filetype not allowed"
}

💡 技术拓展：文件上传过滤的「扩展名 vs MIME」之争——扩展名是文件名的自我声明，MIME（libmagic/finfo）是内容的指纹判断，两者都可能被构造绕过（把脚本伪装成 image/jpeg 内容）。Uguu 的做法是双表联动 + 建议两表对齐，属于实用的纵深防御第一层；要做到更强的内容安全，可在 Nginx 层加病毒扫描（如 ClamAV 模块）或配合 BLACKLIST_DB 沉淀已知恶意哈希。

7.2 BLACKLIST_DB 与 ANTI_DUPE

八、限速参数

限速的记账对象不是裸 IP，而是「IP + User-Agent」的 xxh3 指纹（源码 fingerPrint()：hash('xxh3', CLIENT_IP . USER_AGENT)），写入 ratelimit 表；LOG_IP=false 时表里只有指纹哈希、无明文 IP。实测 RATE_LIMIT_FILES: 2 + TIMEOUT: 60：同指纹连续第 1、2 次上传成功，第 3 次被拒：

HTTP/1.1 500 Internal Server Error

{
    "success": false,
    "errorcode": 500,
    "description": "Rate limit, please wait 60 seconds before uploading again."
}

ratelimit 表实测内容（第 3 次被拒后）：1|a9e2bf4eb803d333|1793507088|2（id|iphash|time|files）。过期记录（24 小时前）由 checkExpire.php 每次顺带清理（cleanRateLimitDB()）。

九、隐私与调试参数

十、参数速查：改了谁要动哪里

十一、参考链接

• 官方配置 Wiki（参数定义出处）：https://github.com/nokonoko/Uguu/wiki/Uguu-Configuration-%26-Installation
• 默认配置文件（1.9.9 源码）：https://github.com/nokonoko/Uguu/blob/master/src/config.json
• 本系列选型篇：《Uguu 1.9.9 介绍与选型指南》
• 本系列部署篇：《Uguu 1.9.9 Docker Compose 部署指南》
• 本系列命令篇：《Uguu 1.9.9 常用命令详解》