Uguu 1.9.9 常用命令详解

目标：系统梳理 Uguu 1.9.9 部署后的全部日常命令入口——curl 上传 API（四种响应格式、多文件、防重复、黑名单与限速触发）、checkExpire.php 过期清理脚本（手动执行与 cron 化）、sqlite3 数据巡检、服务与日志巡检，逐条给出真实回显。Uguu 无官方 CLI 客户端，curl 与 PHP/SQLite 工具链就是它的「命令行界面」。本文所有命令与回显均在 Ubuntu 24.04 LTS（x86_64）上实测通过（Nginx 1.26.3 + PHP 8.3.15 + SQLite 3.45.3，服务端口 8134，2026-11-01）。

一、环境信息

操作系统：Ubuntu 24.04 LTS（x86_64）
软件版本：Uguu 1.9.9（部署形态见《Uguu 1.9.9 Docker Compose 部署指南》）
服务实例：Web 端口 8134（下文所有 URL 以 http://127.0.0.1:8134 为例，生产替换为实际域名）
关键路径：站点编译产物 /var/www/uguu/dist/、上传文件 /var/www/files/、SQLite 库 /var/www/db/uguu.sq3、Nginx 日志 /var/log/nginx/
参数变更生效方式：修改 dist/config.json 后重载 PHP-FPM（配置被 APCu 缓存，详见《Uguu 1.9.9 配置参数详解》）

二、命令入口总览

入口	命令形态	用途
curl 上传 API	`curl -F "files[]=@文件" http://127.0.0.1:8134/upload.php`	脚本化上传，四种响应格式
PHP CLI	`php /var/www/uguu/dist/checkExpire.php`	手动触发过期清理（cron 化入口）
sqlite3	`sqlite3 /var/www/db/uguu.sq3 "SQL"`	数据巡检、黑名单维护
系统服务	`nginx -v`、`php -v`、`/var/log/nginx/`	版本确认与日志巡检

上传端点说明：API 的物理端点是 upload.php（位于 dist/public/）。裸机按官方 Wiki 配置 Nginx 时有 extensionless 重写，/upload 与 /upload.php 等价；官方 Docker 用的精简 Nginx 配置没有该重写，统一用 /upload.php 最稳（前端 JS 的 XHR 也固定 POST 到 upload.php）。

三、curl 上传 API 详解

3.1 单文件上传（JSON 默认格式）

echo "hello uguu" > hello.txt
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
        }
    ]
}

响应字段：hash 为文件内容 xxh3 哈希（也用于防重复与黑名单比对）、filename 为生成的随机文件名、url 为下载直链、size 字节、dupe 是否命中防重复。注意 url 硬编码 https:// 前缀，本地 HTTP 验证时手动改 http://。

按返回链接下载并校验一致性：

curl -s http://127.0.0.1:8134/files/wnBwPUJr.txt

实测回显：

hello uguu

3.2 多文件上传

一个请求带多个 files[] 字段即可（1.9.9 发行注记明确修复了「多文件只上传第一个」的缺陷）：

echo "file A" > a.txt
echo "file B" > b.txt
curl -s -F "files[]=@a.txt" -F "files[]=@b.txt" http://127.0.0.1:8134/upload.php

实测回显：

{
    "success": true,
    "files": [
        {
            "hash": "4018508355b1320a",
            "filename": "ZmWOWgqA.txt",
            "url": "https:\/\/127.0.0.1:8134\/files\/ZmWOWgqA.txt",
            "size": 18,
            "dupe": false
        },
        {
            "hash": "e225f27efced4e24",
            "filename": "LeZzmPuN.txt",
            "url": "https:\/\/127.0.0.1:8134\/files\/LeZzmPuN.txt",
            "size": 18,
            "dupe": false
        }
    ]
}

3.3 其他响应格式（output 参数）

?output= 支持 json（默认）/text/html/csv 四种。text 与 html 实测（同一张 PNG，开启 ANTI_DUPE 后返回的是首次上传的既有文件）：

curl -s -F "files[]=@photo.png" "http://127.0.0.1:8134/upload.php?output=text"
curl -s -F "files[]=@photo.png" "http://127.0.0.1:8134/upload.php?output=html"

实测回显：

https://127.0.0.1:8134/files/bkBnnvRE.png

<a href="https://127.0.0.1:8134/files/bkBnnvRE.png">https://127.0.0.1:8134/files/bkBnnvRE.png</a><br>

text 输出纯 URL 行（适合管道与脚本取值），html 输出可嵌页面的锚点片段。csv 在 1.9.9 实测不可用，任何上传都会 500，详见第七章排障实录 ①。

3.4 防重复（ANTI_DUPE）触发

ANTI_DUPE: true 时重复上传同内容文件不落盘、直接返回既有链接：

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

实测回显（与 3.1 同一文件，注意 filename 与 dupe）：

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

3.5 黑名单拦截（415）

默认黑名单模式拦截 exe/bat/jar/svg 等 13 类扩展名：

printf 'MZ fake pe' > setup.exe
curl -s -i -F "files[]=@setup.exe" http://127.0.0.1:8134/upload.php

实测回显（响应头节选 + 正文）：

HTTP/1.1 415 Unsupported Media Type
Server: nginx/1.26.3
Content-Type: application/json; charset=UTF-8
X-Powered-By: PHP/8.3.15

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

MIME 按内容探测（finfo），把 exe 改名 .jpg 仍会被 MIME 表拦下。切白名单模式（FILTER_MODE: false）后语义反转：不在名单内的 png 同样返回上述 415——模式语义的完整实测见配置篇 7.1 节。

3.6 限速触发（500）

RATE_LIMIT: true + RATE_LIMIT_FILES: 2 + RATE_LIMIT_TIMEOUT: 60 时，同一「IP+UA 指纹」窗口内第 3 个文件：

curl -s -i -F "files[]=@r3.txt" http://127.0.0.1:8134/upload.php

实测回显（节选）：

HTTP/1.1 500 Internal Server Error

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

注意限速按指纹记账且以文件数为粒度（一次传 3 个文件记 3 份），限速记录由 checkExpire.php 每次顺带清理 24 小时前的旧账。

3.7 ShareX 对接

Windows 侧 ShareX「自定义上传器」按以下要点配置即可直传：Method=POST、RequestURL=https://你的域名/upload.php（或 /upload?output=text 配合 URL 解析）、File form name 填 files[]。Uguu README 官方声明支持 ShareX 及同类截图工具。

四、checkExpire.php 过期清理命令

4.1 手动执行

php /var/www/uguu/dist/checkExpire.php

两种实测输出：

无过期文件（清理前/刚清完）：

No file(s) expired, nothing to do.

有过期文件：静默删除，无任何输出。脚本内部分别执行：按 expireTime/expireTimeUnit 扫描 files 表 → 删除命中记录 → unlink 物理文件 → 顺带清理 24 小时前的 ratelimit 记录。执行后验证：

sqlite3 /var/www/db/uguu.sq3 "SELECT id, filename FROM files;"
ls /var/www/files/
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8134/files/HEJAifkR.txt

实测回显（1 分钟过期档实测：8 条记录全部到期，清理后三查皆空/404）：

（SELECT 无输出，表已清空）
（ls 无输出，目录已清空）
404

4.2 cron 化（必配）

过期删除不靠上传请求触发，不配 cron 文件就只逻辑过期、永不物理删除。裸机按官方 Wiki 在 root crontab（crontab -e）添加：

#Run file expiration check every 1 minute
* * * * * /usr/bin/php8.3 /var/www/uguu/dist/checkExpire.php

PHP 8.3 裸机二进制路径不同发行版可能是 /usr/bin/php，用 which php 确认；Compose 部署在宿主机 crontab 写 docker exec uguu-1.9.9-web php /var/www/uguu/dist/checkExpire.php（见部署篇第七章）。

五、sqlite3 数据巡检命令

5.1 库表总览与结构

sqlite3 /var/www/db/uguu.sq3 ".tables"

实测回显：

accounts   blacklist  files      ratelimit

files：上传记录主表；
ratelimit：限速记账（iphash/files/time）；
blacklist：哈希黑名单（BLACKLIST_DB 开启后生效）；
accounts：管理面板 Moe Panel 的账号表，核心功能不依赖。

files 表结构（实测 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

5.2 常用巡检 SQL

# 当前在架文件清单（含原始文件名与大小）
sqlite3 /var/www/db/uguu.sq3 "SELECT id, originalname, filename, size, date FROM files ORDER BY id;"

实测回显（清理前抓取）：

1|47272535fb3d837e|hello.txt|wnBwPUJr.txt|22|1793506876
2|32962fc36316ee0c|photo.png|bkBnnvRE.png|67|1793506876

上表为省略列名的历史抓取版本，完整列为 id|hash|originalname|filename|size|date，即 1|hello.txt|wnBwPUJr.txt|... 形态，读表时以 PRAGMA 结构为准。

# 磁盘占用对账（库内总大小 vs 目录实际占用）
sqlite3 /var/www/db/uguu.sq3 "SELECT count(*), sum(size) FROM files;"
du -sh /var/www/files/

# 隐私审计：确认未落明文 IP（LOG_IP=false 时 ip 列应为空）
sqlite3 /var/www/db/uguu.sq3 "SELECT id, filename, ip FROM files;"

实测回显（默认隐私配置）：

9|VdfUWvWZ.txt|

ip 列为空即 LOG_IP: false 生效。哈希黑名单维护（开启 BLACKLIST_DB 后）：

# 查看黑名单（默认空）
sqlite3 /var/www/db/uguu.sq3 "SELECT * FROM blacklist;"
# 沉淀恶意样本：先取其 xxh3 哈希，再入库
php -r "echo hash('xxh3', file_get_contents('/path/to/malware.bin'));\n"
sqlite3 /var/www/db/uguu.sq3 "INSERT INTO blacklist (hash) VALUES ('<样本哈希>');"

黑名单比对发生在上传入口（Upload::uploadFile() → checkFileBlacklist(xxh3)），命中即 415，无需重启。

六、服务与日志巡检命令

6.1 版本确认

nginx -v
php -v | head -1
sqlite3 --version | cut -d' ' -f1

实测回显：

nginx version: nginx/1.26.3
PHP 8.3.15 (cli) (built: Dec 20 2024 20:11:30) (NTS)
3.45.3

6.2 Nginx 日志巡检

官方 docker 配置关闭了 access_log（隐私考虑），排障主要看 error log：

tail -3 /var/log/nginx/error.log

实测回显（正是第七章排障实录 ② 定位 /files/ 404 时的关键证据）：

2026/11/01 04:22:08 [error] 18#18: *6 open() "/var/www/uguu/dist/public/files/bkBnnvRE.png" failed (2: No such file or directory), client: 10.89.56.1, server: _, request: "GET /files/bkBnnvRE.png HTTP/1.1", host: "127.0.0.1:8134"

裸机部署若按官方 Wiki 打开了站点 access log，重点巡检两类行：client_max_body_size 超限的 413（配合调大 Nginx/PHP 上限）与 PHP-FPM 报错（配合开 DEBUG 短暂定位后关闭）。PHP-FPM 侧日志：裸机看 journalctl -u php8.3-fpm 或 catch_workers_output 开启后的 error log；镜像部署统一汇入服务日志。

6.3 一键健康巡检（可入 cron/监控）

#!/bin/bash
# uguu-health.sh：首页 200 + 库可读 + 清理脚本可执行
curl -s -o /dev/null -w "home %{http_code}\n" http://127.0.0.1:8134/
sqlite3 /var/www/db/uguu.sq3 "SELECT 'db ok', count(*) FROM files;"
php -r "exit(is_readable('/var/www/uguu/dist/config.json') ? 0 : 1);" && echo "config ok"

实测回显：

home 200
db ok|0
config ok

七、排障实录汇总

本系列四篇实测沉淀的五个最典型问题，现象→根因→处置：

?output=csv 上传必 500：DEBUG=false 时只回 Server error. 无从下手；开 DEBUG: true 重载 PHP-FPM 后回显 Server error: Undefined array key "name"——1.9.9 上游缺陷（Upload::uploadFile() 已注释 name 字段，CSV 格式化器仍读取）。处置：机器可读输出用 output=text 或 json，等待上游修复；
图片类上传文件按 URL 访问 404、txt 正常：官方 docker/nginx.conf 的静态资源正则 location 抢占 /files/ 前缀 location（Nginx 正则优先于普通前缀），请求落进 dist/public/files/ 找文件。error.log 的 open() .../public/files/xxx failed 是铁证。处置：location /files/ 改 location ^~ /files/（详见部署篇 4.3）；
改了 config.json 不生效：配置被 APCu 缓存（键 UC）。处置：重载 PHP-FPM（Compose 部署 docker compose restart uguu）；
页面文案/上限提示改不动：站点名、副标题、Max upload size is … 文案在 make 编译期烧录进静态 HTML。处置：改 src/config.json 重新构建（后端行为与页面展示分离，见配置篇第二章）；
Makefile 替换 Composer 安装源后 vendor 缺失、上传 500：raw.githubusercontent.com 被阻断时需把 composer 安装器改为直下 getcomposer.org/composer-stable.phar，替换行若丢失行首 TAB，make 会把命令解析成伪 target，php composer.phar update 随之被吞。处置：核对替换行 TAB；部署后验证 dist/vendor/autoload.php 存在（详见部署篇第三章排障实录 ①）。

八、参考链接

官方 Wiki（cron 配置出处）：https://github.com/nokonoko/Uguu/wiki/Uguu-Configuration-%26-Installation
上传入口与响应类源码（1.9.9）：https://github.com/nokonoko/Uguu/blob/master/src/static/php/upload.php
本系列选型篇：《Uguu 1.9.9 介绍与选型指南》
本系列部署篇：《Uguu 1.9.9 Docker Compose 部署指南》
本系列配置篇：《Uguu 1.9.9 配置参数详解》