Jirafeau 4.7.2 常用 CLI 命令与工具详解

Jirafeau 4.7.2 脚本化操作详解：script.php 全端点与错误码速查、官方 Bash 客户端 send/get/delete 实测、admin.php 管理端脚本化（admin_csrf 排障实录）与 PHP-CLI 维护命令。

JirafeauJirafeau文件传输2026/10/30

Jirafeau 4.7.2 常用 CLI 命令与工具详解

目标：把 Jirafeau 的命令行/脚本化操作一次讲全——script.php 脚本接口的全部端点、官方自动生成的 Bash 客户端（send/get/delete）、admin.php 管理端的脚本化调用与 PHP-CLI 维护命令。全部命令与回显均在 4.7.2 真实实例上逐条实测（实测日期 2026-10-30）。

一、环境信息

  • Jirafeau 版本：4.7.2（官方镜像 registry.gitlab.com/jirafeau/jirafeau:4.7.2，部署见《Jirafeau Docker Compose 部署指南》）
  • 服务地址：http://127.0.0.1:8150/（下文示例均以该地址实测；实际使用替换为你的站点地址）
  • 管理口令（示例演示）：q1w2e3r4
  • 客户端工具：curl（脚本接口）、官方 Bash 客户端（由 script.php 自动生成）、php-cli（维护命令）
  • 数据目录：/data（files/links/async 三子目录）

二、工具概览

Jirafeau 没有"一个大而全的 CLI"，而是三个互补的脚本化入口（官方仓库源码实读）：

工具形态用途
script.phpHTTP 脚本接口（curl 直调）上传/下载/删除/查询版本与容量，程序化集成的标准入口
官方 Bash 客户端script.php 自动生成的 bash 脚本服务器间文件收发的顺手工装，send/get/delete 三命令
admin.phpWeb 管理动作 + PHP-CLI 子命令存储清点、过期清理、按名称/哈希/链接检索、删除链接；clean_expired / clean_async 两个 CLI 子命令供 cron/内置清理调用

💡 技术拓展：script.php 与 f.php 的分工——script.php 是"机器接口"（文本协议：成功返回纯文本行、失败返回 Error N）；f.php 是"人机接口"（HTML 下载页）。二者操作同一批数据：script.php 的上传返回值拼出的就是 f.php 链接。REST 风格的 JSON API 不是 Jirafeau 的设计目标，它坚持 KISS 的文本行协议。

三、前置条件

  • 实例可达且已通过首启配置（script.php?get_version 能返回版本号）；
  • 客户端有 curl；使用 Bash 客户端需 bash；
  • 若配置了 UPLOAD_PASSWORD，准备上传口令；管理操作准备 ADMIN_PASSWORD。

四、各工具详解

4.1 script.php 查询端点

三个只读查询参数（GET）：

curl -sS "http://127.0.0.1:8150/script.php?get_version"             # 服务版本
curl -sS "http://127.0.0.1:8150/script.php?get_capacity"            # PHP 层单请求上限（字节）
curl -sS "http://127.0.0.1:8150/script.php?get_maximal_upload_size" # 应用层上限（MB）

实测回显（依次三行）：

4.7.2
1048576
0

get_capacity 可用于客户端上传前的预检（超过则先分块或压缩）；返回 1048576 对应镜像 php.ini 的 upload_max_filesize = 1M。

4.2 script.php 上传端点

POST multipart 上传，核心参数：file（文件）、time（有效期档位，必须在 availabilities 中开启）、可选 key（下载口令）、可选 one_time_download=1（一次性）：

echo "jirafeau test file 2026-10-30" > upload_test.txt   # 准备文件
curl -sS -X POST -F "file=@upload_test.txt" -F "time=month" http://127.0.0.1:8150/script.php

实测回显（两行：下载链接名 + 删除码）：

0MUAUAsM
c841f

返回行语义（源码 script.php）：

  • 第 1 行：链接名（拼 f.php?h=<链接名> 为下载页、&d=1 直接下载）；
  • 第 2 行：删除码（拼 f.php?h=<链接名>&d=<删除码> 可随时删除）；
  • 第 3 行：解密密钥（仅 enable_crypt 开启时非空，URL 编码；实测未加密上传只输出前两行）。

带下载口令与一次性选项的上传：

curl -sS -X POST -F "file=@secret.txt" -F "time=week" -F "key=q1w2e3r4" http://127.0.0.1:8150/script.php
curl -sS -X POST -F "file=@onetime.txt" -F "time=day" -F "one_time_download=1" http://127.0.0.1:8150/script.php

实测回显（依次）：

1Ga0zOhX
cfafb

2cPISNJJ
e9664

配置了上传口令的实例，脚本上传必须带 -F "upload_password=<口令>"，否则实测返回 Error 2: No password nor allowed IP（未带口令）或 Error 3: Invalid password（口令错误）。全量错误码见 4.7 节。

4.3 script.php 下载与删除端点

下载（GET h 参数 + 可选 k/d）：

curl -sS "http://127.0.0.1:8150/script.php?h=0MUAUAsM&d=1"                      # 无口令直取
curl -sS -X POST -F "key=q1w2e3r4" "http://127.0.0.1:8150/script.php?h=1Ga0zOhX&d=1"   # 带下载口令

实测回显（依次）：

jirafeau test file 2026-10-30

secret content with password

保存为原始文件名建议用 curl 的 -OJ（按服务端 Content-Disposition 命名）。删除（GET h + 删除码 d）：

curl -sS "http://127.0.0.1:8150/script.php?h=0MUAUAsM&d=c841f"   # 删除码来自上传回显第 2 行

实测回显：

Ok

边界行为实测：过期链接返回 Error 9（实测 minute 档上传等 65 秒后取回）；不存在的链接返回 Error 8；下载口令错误返回 Error 10（服务端故意延迟 2 秒防爆破，源码实读）。

4.4 官方 Bash 客户端

获取：访问 script.php?lang=bash 即下载按当前实例配置预填的客户端脚本：

curl -sS "http://127.0.0.1:8150/script.php?lang=bash" -o jirafeau_bash_client.sh   # 获取客户端
chmod +x jirafeau_bash_client.sh
head -12 jirafeau_bash_client.sh   # 头部为可编辑配置区

实测回显（头部 12 行）：

#!/bin/bash

# This script has been auto-generated by Jirafeau but you can still edit options below.

# Config begin
proxy='' # Or set JIRAFEAU_PROXY.
url='' # Or set JIRAFEAU_URL.
time='month' # Or set JIRAFEAU_TIME.
one_time='' # Or set JIRAFEAU_ONE_TIME.
curl='' # Or set JIRAFEAU_CURL_PATH.
upload_password='' # Or set JIRAFEAU_UPLOAD_PASSWD
# Config end

注意 url=''：未设置 WEB_ROOT 的实例生成的脚本不预填地址（实测联动，见部署篇 FAQ），可用环境变量补齐。无地址直接调用时输出用法自述：

./jirafeau_bash_client.sh   # 无参数调用

实测回显：

Please set url in script parameters or export JIRAFEAU_URL
Jirafeau Bash Script 4.7.2
--------------------------
Usage:
    ./jirafeau_bash_client.sh OPTIONS

Options:
    ./jirafeau_bash_client.sh send FILE [PASSWORD]
    ./jirafeau_bash_client.sh get URL [PASSWORD]
    ./jirafeau_bash_client.sh delete URL

Global variables to export:
    JIRAFEAU_PROXY: Domain and port of proxy server, eg. »proxyserver.example.com:3128«
    JIRAFEAU_URL : URI to Jirafeau installation with trailing slash, eg. »https://example.com/jirafeau/«
    JIRAFEAU_TIME : expiration time, eg. »minute«, »hour«, »day«, »week«, fortnight, »month«, »quarter«, »year« or »none«
    JIRAFEAU_ONE_TIME : self-destroy after first download, eg. »1« to enable or »« (empty) to disable
    JIRAFEAU_CURL : alternative path to curl binary
    JIRAFEAU_UPLOAD_PASSWD : upload password

send 上传（设置 JIRAFEAU_URL 后）：

export JIRAFEAU_URL='http://127.0.0.1:8150/'
echo "bash client upload" > bsend.txt
./jirafeau_bash_client.sh send bsend.txt

实测回显：


Download page:
    http://127.0.0.1:8150/f.php?h=0FwV5xwE
Direct download:
    http://127.0.0.1:8150/f.php?h=0FwV5xwE&d=1
Delete link:
    http://127.0.0.1:8150/f.php?h=0FwV5xwE&d=37771

Download via API:
    ./jirafeau_bash_client.sh get http://127.0.0.1:8150/script.php?h=0FwV5xwE [PASSWORD]
Delete via API:
    ./jirafeau_bash_client.sh delete "http://127.0.0.1:8150/f.php?h=0FwV5xwE&d=37771"

五段输出即五条即用链接：下载页 / 直接下载 / 删除链接 / API 下载命令 / API 删除命令。

get 下载（第二个参数是 script.php 形态的 API 链接，带口令文件加第三参数）：

./jirafeau_bash_client.sh get http://127.0.0.1:8150/script.php?h=0FwV5xwE

实测回显（取回的文件内容）：

bash client upload

delete 删除（第二个参数传完整的删除链接，注意整体加引号防止 & 截断）：

./jirafeau_bash_client.sh delete "http://127.0.0.1:8150/f.php?h=3_nQQQiv&d=0ed4a"

实测回显（页面文本，服务端确认删除）：

File has been deleted.

客户端内置的全局变量：JIRAFEAU_PROXY（走代理时）、JIRAFEAU_URL（服务地址，带尾斜杠）、JIRAFEAU_TIME（默认档位）、JIRAFEAU_ONE_TIME（置 1 全部一次性）、JIRAFEAU_CURL_PATH（指定 curl 路径）、JIRAFEAU_UPLOAD_PASSWD（上传口令）。

4.5 admin.php 管理端脚本化调用

管理动作入口是 POST action 参数。登录（会话 cookie）：

curl -sS -c admin_cookies.txt -o admin_login.html -X POST -F "admin_password=q1w2e3r4" http://127.0.0.1:8150/admin.php

登录成功页标题为 "Admin interface (version 4.7.2)"（实测），动作菜单：Clean expired files / Clean old unfinished transfers / List all files / Data size / Search for files by name / Search for files by file hash / Search a specific link / Reporting an issue。

⚠️ 注意（实测排障实录）：每个动作 POST 必须携带登录页下发的隐藏字段 admin_csrf，缺失时服务端校验失败、响应永远停留在登录表单页——实测不带 csrf 调 action=size 三次全部返回 "Admin password:" 登录页。正确姿势是先提取 csrf 再随动作提交：

CSRF=$(grep -o "admin_csrf' value='[0-9a-f]*'" admin_login.html | head -1 | grep -o '[0-9a-f]\{64\}')
curl -sS -b admin_cookies.txt -X POST -F "action=size" -F "admin_csrf=${CSRF}" http://127.0.0.1:8150/admin.php

实测回显（action=size，存储清点）：

Data size: 226B

清理过期（action=clean）：

curl -sS -b admin_cookies.txt -X POST -F "action=clean" -F "admin_csrf=${CSRF}" http://127.0.0.1:8150/admin.php

实测回显：

Number of cleaned files : 0

列全部文件（action=list，含下载统计）：

curl -sS -b admin_cookies.txt -X POST -F "action=list" -F "admin_csrf=${CSRF}" http://127.0.0.1:8150/admin.php

实测回显（清单条目节选，一行一链接）：

secret.txt   Type: text/plain Size: 29B Expire:  2026-11-06 08:06 (GMT)  One-time: No Encrypted: No Upload date:  2026-10-30 08:06 (GMT)  Origin: 10.89.58.1 Downloads: 1 Last download:  2026-10-30 08:06 (GMT)  Downloaded from: 10.89.58.1

按名称/哈希/链接检索：action=search_by_name + name、action=search_by_file_hash + hash、action=search_link + link，输出格式与 list 相同。删除链接（action=delete_link + link 参数）实测返回管理菜单页、目标链接随即失效；action=delete_file 按内容哈希删除物理文件；action=clean_async 清理超时未完成的分块传输。

4.6 PHP-CLI 维护命令

admin.php 支持 two 个命令行子命令（供 cron 或镜像内置清理循环调用）：

php /www/admin.php clean_expired   # 清理全部过期文件
php /www/admin.php clean_async     # 清理超时未完成的分块传输

实测回显（依次两行）：

0 expired files deleted.
0 old unfinished transfers deleted.

无参数执行则提示用法（实测回显）：No command found. Should be admin.php <clean_expired|clean_async>.

镜像部署无需自建 cron：官方镜像内置清理循环，启动 10 秒后开始每 24 小时执行一次上述两个命令（官方 docker/cleanup.sh 源码逻辑）。源码部署则建议将这两条命令写入 crontab（如每日凌晨执行）。

4.7 script.php 错误码速查

错误以 Error N: 说明 文本行返回（源码 script.php 全量核对）：

错误码含义
Error 1服务端配置错误（check_errors 未通过）
Error 2上传缺口令且来源 IP 不在白名单
Error 3上传口令错误
Error 4time 参数无效（档位未开启或拼写错误）
Error 5文件超过 maximal_upload_size
Error 6上传内部错误（附具体原因）
Error 7链接名格式非法
Error 8链接不存在
Error 9链接已过期
Error 10下载口令错误（服务端延迟 2 秒防爆破）
Error 11链接在但物理文件丢失
Error 12请求的语言不支持
Error 13下载口令为必填（required 策略）但未提供
Error 14下载口令不符合 regex 策略
Error 19-24异步分块上传族错误（认证/参数/分块引用等）
Error 25未知请求
Error 26one_time_download 功能未启用但请求了一次性

五、注意事项

  • 删除链接即删除数据：删除码一经使用无法恢复；去重模式下删除一个链接只递减引用计数，最后一个引用被删时物理文件才消失（实测全部测试链接删除后 files/ 自动清空）。
  • 管理端脚本化必须带 admin_csrf（4.5 节排障实录）；cookie 与 csrf 成对使用，会话过期后重新登录提取。
  • Bash 客户端 delete 的第二个参数要整体加引号（URL 含 &），且必须传完整删除链接（f.php?h=<名>&d=<删除码>）——只传 f.php?h=<名> 时 d 参数缺失不会删除。
  • 下载口令在链接元数据中为 SHA256 摘要（4.7.2 起），服务端无法找回原文；一次性链接首读即焚，务必保存好取回的内容。
  • 脚本上传受 PHP 层 upload_max_filesize 约束（实测 1M，get_capacity 可查）；大文件走浏览器分块上传或调大 PHP 层限制。
  • 上传口令与下载口令是两回事：前者管"谁能传"（UPLOAD_PASSWORD），后者管"谁能下"（上传时 -F key=）。

六、常见问题（FAQ）

Q1：脚本上传报 Error 4？ time 档位拼写错误或该档位在 availabilities 中未开启（如 fortnight 写成 fortnight 之外的形态）。先 curl script.php?get_version 确认接口可达，再核对档位名（minute/hour/day/week/fortnight/month/quarter/year/none）。

Q2：Bash 客户端 send 报 "Could not resolve host: script.php"？ JIRAFEAU_URL 未设置或末尾缺斜杠——url 为空时客户端把 script.php 当主机名解析（实测报 curl: (6) Could not resolve host: script.php）。export JIRAFEAU_URL='http://<地址>/'（带尾斜杠）后重试。

Q3：管理端动作一直返回登录页？ 动作 POST 缺 admin_csrf 字段（4.5 节排障实录）。从登录响应 HTML 提取 64 位十六进制 csrf 值并随每个动作提交。

Q4：如何批量核对线上有哪些未过期文件？ 管理端 action=list（全部）或 action=search_by_name（按文件名）输出每个链接的过期时间、一次性标记、下载次数与来源 IP；配合 action=clean 定期回收。

Q5：想自动化"上传即取回直链"？ 两行脚本足够：res=$(curl -sS -X POST -F file=@$1 -F time=day http://<地址>/script.php)，echo "http://<地址>/f.php?h=$(echo "$res" | head -1)&d=1"。需要删除能力则同时保存第二行删除码。或直接用 4.4 节官方客户端。

七、参考链接