Jirafeau 4.7.2 配置参数详解

目标：逐项讲清 Jirafeau 4.7.2 的全部配置参数——配置文件结构、约 30 个配置项的语义与默认值、容器化部署的环境变量映射，以及"改了配置被还原"这一高频问题的实测结论。文中查看方式、修改路径与覆盖行为均在 4.7.2 实例上实测验证（实测日期 2026-10-30）。

一、环境信息

• Jirafeau 版本：4.7.2（官方镜像 registry.gitlab.com/jirafeau/jirafeau:4.7.2）
• 部署形态：Docker Compose 单服务（部署过程见《Jirafeau Docker Compose 部署指南》，服务端口 8150，数据目录 /data）
• 配置文件：服务内 /www/lib/config.local.php（运行时生效配置）；模板 /www/lib/config.original.php（全量参数注释版）
• 参考基线：官方源码 4.7.2 tag（gitlab.com/jirafeau/Jirafeau，查询日期 2026-10-30）
• 示例管理口令：q1w2e3r4（示例演示值，配置中以 SHA256 摘要存储）

二、前置条件

• 一个可访问的 Jirafeau 4.7.2 实例（容器化或源码部署均可，本文命令以 8150 端口实例为例）；
• 了解自身部署形态：镜像部署的配置入口是环境变量（首启脚本生成配置文件），源码部署的配置入口是手工编辑 lib/config.local.php（安装向导生成初始版）。两种形态的参数语义完全一致，仅修改方式不同。

三、参数查看与修改方式

3.1 查看当前生效配置

配置文件是纯 PHP 数组（var_export 形态），直接读取即可。镜像部署在宿主上执行：

docker exec jirafeau-4.7.2-web head -30 /www/lib/config.local.php   # 查看生成配置前 30 行

实测回显（节选）：

<?php
/* This file was generated by the install process. You can edit it. Please see config.original.php to understand the configuration items. */
$cfg = array (
  'web_root' => '',
  'var_root' => '/data/',
  'use_shortlinks' => false,
  'lang' => 'auto',
  'style' => 'courgette',
  'dark_style' => 'dark-courgette',
  'organisation' => 'ACME',
  'contactperson' => '',
  'title' => false,
  'preview' => true,
  'enable_crypt' => false,
  'link_name_length' => 8,
  'upload_password' =>
  array (
  ),

源码部署直接查看 <站点根>/lib/config.local.php。全部参数的注释版模板在同目录 config.original.php（官方升级指引也要求升级后对照它补齐新增项）。

3.2 修改方式一：环境变量（镜像部署唯一正路）

官方镜像首启脚本把大写环境变量映射为配置项并每次启动重写 lib/config.local.php。在 compose 中追加或修改环境变量后重建：

    environment:
      ADMIN_PASSWORD: q1w2e3r4
      MAXIMAL_UPLOAD_SIZE: 1024
      ONE_TIME_DOWNLOAD: 1
      DOWNLOAD_PASSWORD_REQUIREMENT: required

docker compose up -d   # 重建使环境变量生效

3.3 修改方式二：直接编辑 config.local.php（源码部署）

编辑 $cfg 数组对应键后无需重启（PHP 每请求加载配置）。注意口令类参数存的是 SHA256 摘要：

echo -n "q1w2e3r4" | sha256sum   # 生成管理口令摘要

实测回显：

13a5c202e320d0bf9bb2c6e2c7cf380a6f7de5d392509fee260b809c893ff2f9  -

把该值填入 'admin_password' 即完成口令设定（实测：以 q1w2e3r4 环境变量部署的实例，生成配置中的 admin_password 恰为该摘要，双向印证）。

3.4 修改方式三：安装向导（仅源码部署）

源码部署首次访问时进入 install.php 三步向导：第一步设置管理口令（空则不启用口令），第二步设置数据目录路径，第三步校验目录可写并写入 installation_done = true 完成安装。官方 4.7.2 容器镜像不含 install.php（实测镜像内无此文件），容器化路径不适用本方式。

⚠️ 注意（实测排障结论）：镜像部署下直接编辑服务内 config.local.php 会在下一次重启时被环境变量生成的配置覆盖——实测把 title 手改为 MY-TITLE（编辑后 grep -c MY-TITLE 返回 1），docker restart 后同字段还原为默认 false（grep -c 返回 0）。持久化修改必须走环境变量。

四、参数总览

以下为 lib/config.original.php 全部参数（与官方 4.7.2 源码逐项核对；"环境变量"列为镜像部署的对应键名）：

💡 技术拓展：file_hash 是 Jirafeau 存储模型的开关。random（默认）给每个文件随机名，安全但不去重；md5 对整个文件取 MD5，同内容文件只存一份（引用计数管理）；md5_outside 只取文件首尾部分 MD5 加文件大小，去重成本更低但存在不同文件同哈希的碰撞风险——官方注释明确提示这是"dangerous"的取舍。启用去重与 enable_crypt 互斥：加密后每个文件的密文都不同，去重失去意义。

五、核心参数分类详解

5.1 站点基础（web_root / title / organisation / lang / style）

• web_root：对外访问入口 URL，必须带尾斜杠。影响所有生成链接的绝对路径与自动生成 Bash 客户端中预填的 url 字段。实测：不设（空值）时链接走相对路径，首启日志出现 warning: you may want to have set WEB_ROOT ...，且 script.php?lang=bash 生成的客户端 url=''（需手工 export JIRAFEAU_URL）；反代/域名场景务必设置（如 https://file.example.com/）。
• title：站点标题，显示在浏览器标题与页面头部；organisation/contactperson 出现在服务条款页（tos.php）与页脚（实测页脚 "Designed and hosted by ACME"）。
• lang：auto 时按浏览器语言自动匹配（lib/locales/ 下 60+ 语言含简繁中文），固定值可省去每次探测。
• style/dark_style：亮/暗主题，镜像内 media/ 目录下可用主题含 courgette 及 dark-courgette 等官方主题。

5.2 有效期与一次性（availabilities / availability_default / one_time_download）

availabilities 是 9 档布尔数组：minute(1 分钟)、hour(1 小时)、day(1 天)、week(1 周)、fortnight(2 周)、month(1 月)、quarter(3 月)、year(1 年)、none(永久)。只开放需要的档位可收窄使用面（如内网仅保留 day/week）；availability_default 必须取一个已开启档位。one_time_download 控制上传页是否出现"下载一次后删除"选项，实测开启后带 one_time_download=1 上传的链接首次下载即销毁、第二次下载返回"文件不存在"；one_time_download_preselected 让该选项默认勾选。

5.3 上传控制（upload_password / upload_ip / maximal_upload_size / max_upload_chunk_size_bytes）

• upload_password：非空数组后，所有上传（Web 与脚本接口）都需口令——脚本接口缺口令实测返回 Error 2: No password nor allowed IP，口令错误返回 Error 3: Invalid password；镜像部署用逗号分隔多个口令（UPLOAD_PASSWORD=p1,p2）。
• upload_ip / upload_ip_nopassword：IPv4 CIDR 白名单，前者限定"谁可以传"，后者允许名单内 IP 免口令上传（内网免密、外网带密的常用组合）。
• maximal_upload_size：应用层单文件上限（MB，0 不限）。实际单请求上限还受 PHP 层约束——实测镜像内置 php.ini 为 upload_max_filesize = 1M、post_max_size = 2M，因此 script.php?get_capacity 返回 1048576（字节）。两者是"应用闸门 + PHP 闸门"的关系，调大需同时动两层。
• max_upload_chunk_size_bytes：浏览器分块异步上传的单块上限，官方默认 5000000（5MB）。官方注释与 CHANGELOG 明确：更大值在启用 HTTP/3 的服务器上会触发 Chromium 系浏览器异步上传失败，除非确有理由否则不要调大；0 取消限制。
• store_uploader_ip：是否在上传记录（管理端 list 可见）中保留上传者 IP；受数据留存法规约束时可关闭。

5.4 下载口令体系（download_password_requirement 族）

• download_password_requirement：optional（默认，上传者可选设口令）/ required（强制所有上传必须带下载口令，脚本接口不带口令实测返回 Error 13: The parameter password is required.）/ generated（服务端自动生成口令并在上传完成后展示给上传者）。
• download_password_policy + download_password_policy_regex：口令复杂度校验（regex 模式下不符口令实测返回 Error 14）；download_password_gen_len / download_password_gen_chars 控制自动生成口令的长度与字符集。
• 口令存储：4.7.2 起下载口令与 admin_password 一样以 SHA256 摘要存于链接元数据（CHANGELOG 4.7.2 明确 "Download passwords are now stored as SHA256 hashes"）。

5.5 管理与安全（admin_password / admin_ip / admin_http_auth_user / proxy_ip / debug）

• admin_password：管理界面口令的 SHA256 摘要；生成方式 echo -n "口令" | sha256sum（实测见 3.3 节）。镜像部署传 ADMIN_PASSWORD 原文，首启自动转摘要。
• admin_http_auth_user：交给 Web 服务器 HTTP 认证托管时，列出的用户名登录即视为管理员；设置了 admin_password 时本项被忽略（官方注释明确）。
• admin_ip：管理界面 IP 白名单（CIDR），建议生产收敛到运维网段。
• proxy_ip：置于反向代理之后时，列出代理 IP 后访客来源改从 X-Forwarded-For 解析——影响上传记录、下载统计与管理端白名单的判定。
• debug：打开后输出 PHP 错误详情，官方注释警告可能泄露 var 目录路径（数据目录名含随机后缀、被直接访问有数据泄露风险），生产保持 false。

5.6 存储与传输特性（enable_crypt / file_hash / use_xsendfile / litespeed_workaround / link_name_length）

• enable_crypt：服务端加密，密钥仅返回给上传者不落盘；与去重互斥（见第四节技术拓展），且 use_xsendfile 卸载对加密文件不生效。
• file_hash：random（默认）/ md5（去重）/ md5_outside（低成本去重，有碰撞风险）。
• use_xsendfile：需要 Web 服务器支持 X-Sendfile（Apache mod_xsendfile / lighttpd 对应配置），收益是支持断点续传与播放器拖动进度条。
• litespeed_workaround：仅 LiteSpeed 服务器可用；与加密、一次性下载互斥（同开会报不兼容错误）。
• link_name_length：链接名长度（默认 8 位随机串，实测链接形如 0MUAUAsM），加长可降低碰撞/猜测概率。

5.7 运行标记与排障（installation_done / debug_enforce_classic_upload / use_shortlinks）

• installation_done：安装完成标记，false 时首页 302 跳转安装向导（源码部署）或报错（镜像无向导）。不要手工改动此值。
• debug_enforce_classic_upload：强制走经典同步上传（单请求全量 POST），用于排查分块上传链路问题。
• use_shortlinks：4.7.0 新增的短链支持，需要 Web 服务器 URL 重写（Apache mod_rewrite 或 lighttpd 等效规则）；镜像内置 lighttpd 未预配重写规则，启用需自行扩展配置。

六、生产配置模板

场景：200 人内网团队临时文件中转站，8GB 内存服务器、NVMe 磁盘、单实例、前置 Nginx 反代（终止 TLS）、内网免口令上传、外网口令上传、保留 3 种有效期档位：

name: jirafeau-4.7.2-stack
services:
  web:
    image: registry.gitlab.com/jirafeau/jirafeau:4.7.2
    container_name: jirafeau-4.7.2-web
    ports:
      - "127.0.0.1:8150:80"        # 只监听本机，由前置反代对外
    volumes:
      - ./jirafeau_data:/data
    environment:
      ADMIN_PASSWORD: q1w2e3r4              # 管理口令（示例演示值，生产请改强口令）
      WEB_ROOT: 'file.example.com/'         # 对外域名（带尾斜杠）
      TITLE: 'Company File Relay'
      ORGANISATION: 'ACME'
      UPLOAD_PASSWORD: 'Str0ngPass!2026'    # 外网上传口令
      UPLOAD_IP_NOPASSWORD: '10.0.0.0/8,192.168.0.0/16'   # 内网免口令
      AVAILABILITIES: |
        {
          "minute": true,
          "hour": true,
          "day": true,
          "week": false,
          "fortnight": false,
          "month": false,
          "quarter": false,
          "year": false,
          "none": false
        }
      AVAILABILITY_DEFAULT: 'day'
      ONE_TIME_DOWNLOAD: 1
      DOWNLOAD_PASSWORD_REQUIREMENT: 'optional'
      MAXIMAL_UPLOAD_SIZE: 2048             # 应用层 2GB 上限（PHP 层另行调大）
      FILE_HASH: 'md5'                      # 开启去重（不启用加密时）
      STORE_UPLOADER_IP: 1
      ADMIN_IP: '10.0.0.0/8'
      PREVIEW: 0                            # 关闭预览，规避 MIME 嗅探类风险
    restart: unless-stopped
    networks:
      jirafeau-4.7.2-net:
        ipv4_address: 10.89.58.10
networks:
  jirafeau-4.7.2-net:
    driver: bridge
    ipam:
      config:
        - subnet: 10.89.58.0/24

模板要点：资源方面 Jirafeau 本身近乎无内存开销（lighttpd + php-fpm 双进程，实测镜像解压后 129MB），磁盘规划决定于留存档位与去重情况；PREVIEW: 0 与 ADMIN_IP 收敛是低成本高收益的安全项；PHP 层上限需同步挂载自定义 php.ini 才能让 2GB 应用层上限真正可用。

七、常见问题（FAQ）

Q1：为什么手工改的配置重启后丢失？ 镜像部署的首启脚本每次启动都按环境变量重写 config.local.php（第三节实测：手改 title 重启即还原）。镜像部署走环境变量，源码部署才可直接编辑配置文件。

Q2：开启了去重，为什么有的文件还是存了两份？ 确认 file_hash 是否真的设为 md5——默认值是 random（不去重）。且 enable_crypt 开启时去重失效（密文不同），两者互斥。

Q3：get_capacity 返回 1048576，可我设了 MAXIMAL_UPLOAD_SIZE: 0 不限大小？ MAXIMAL_UPLOAD_SIZE 是应用层闸门；get_capacity 返回的是 PHP 层上限（镜像 php.ini upload_max_filesize = 1M）。浏览器分块上传不受单块限制约束总量，但脚本接口单请求上传受 PHP 层约束——需要大文件单请求上传时同步调大 PHP 层。

Q4：availability_default 改成 quarter 后报错？ availability_default 必须取 availabilities 中已开启的档位；官方注释明确该约束，把 quarter 档同时置 true 即可。

Q5：管理口令忘了怎么办？ 镜像部署改 ADMIN_PASSWORD 环境变量后 docker compose up -d 重建（首启会重写摘要）；源码部署用 echo -n "新口令" | sha256sum 生成摘要填入 admin_password。

Q6：想限定"只有内网能传文件"？ UPLOAD_IP 设内网网段（CIDR）后其余来源一律 Error 2: No password nor allowed IP；若希望内网免口令、外网凭口令上传，用 UPLOAD_IP_NOPASSWORD（免口令名单）+ UPLOAD_PASSWORD（其余来源的口令）组合。

八、参考链接

• 配置模板源文件：https://gitlab.com/jirafeau/Jirafeau/-/blob/master/lib/config.original.php （查询日期 2026-10-30）
• 官方镜像环境变量说明：https://gitlab.com/jirafeau/Jirafeau/-/blob/master/docker/README.md
• 版本变更记录：https://gitlab.com/jirafeau/Jirafeau/-/blob/master/CHANGELOG.md
• 本系列认知篇：《Jirafeau 介绍与选型指南》
• 本系列部署篇：《Jirafeau Docker Compose 部署指南》
• 本系列操作篇：《Jirafeau 4.7.2 常用 CLI 命令与工具详解》