FileRise 3.38 Docker Compose 部署指南

目标：在 Ubuntu 服务器上以 Docker Compose 部署 FileRise v3.38.0（nginx 直出静态资源 + PHP-FPM 8.3 运行应用，应用代码与三个数据目录全部 bind mount 持久化），并实测管理员创建、登录、上传、重命名、删除/回收站、恢复、下载、WebDAV 与重启持久化。全部命令与回显均在 Ubuntu 22.04 + Docker Compose v2 环境实测通过。

一、环境信息

本文实测环境与版本基准如下（版本号均为部署当日实查值）：

项目	值	获取方式
操作系统	Ubuntu 22.04	服务器实机
Docker	29.9.2	`docker version` 实查
Compose 编排	Docker Compose v2（compose 插件）	`docker compose version` 实查
FileRise 版本	v3.38.0（官方 Release ZIP）	GitHub Releases，查询日期 2026-10-30
PHP-FPM	8.3.36（php:8.3-fpm 基础镜像 + zip 扩展）	容器内 `php -v` 实查
nginx	1.31.8（nginx:alpine 基础镜像）	`nginx -v` 实查
对外端口	8152（HTTP）	部署前 `ss -ltn` 实查空闲
Compose 项目网络	10.89.58.0/24	部署前实查空闲网段后显式指定
演示管理员账号	admin / q1w2e3r4	首次启动初始化创建

⚠️ 网络说明：Release ZIP 的官方下载源 github.com 当时直连失败（curl: (7) Failed to connect to github.com port 443），实测改走代理渠道可稳定下载（代理用法见本机网络约定）；部署时请按「官方源 → 代理」顺序尝试，当前代理渠道实测可用。Docker 基础镜像拉取（php:8.3-fpm、nginx:alpine）已由 Docker 守护进程代理配置覆盖，无需额外操作。

二、镜像选型说明

FileRise 官方提供两条容器化路径，部署前需先做选型：

方案	说明	适合场景
官方一体镜像 `error311/filerise-docker:latest`	内置 Apache + PHP 8.3，入口脚本 `start.sh` 自动处理权限（PUID/PGID）、配置改写与目录扫描，开箱即用	快速上手、单容器交付
nginx + PHP-FPM 分离组合（本文采用）	nginx 直出静态资源并反代 `fastcgi` 到 PHP-FPM；应用代码与数据目录全部 bind mount	Web 层解耦、静态资源性能、与既有 nginx 体系一致

本文采用第二种：由 php:8.3-fpm 加装 zip 扩展构建应用镜像（官方要求扩展仅 json/curl/zip，前两者官方 PHP 镜像已内置），由 nginx:alpine 承担 Web 层。理由：静态资源（js/css/字体）由 nginx 直接服务、上传大文件时 client_max_body_size 独立可控、后续接反向代理/TLS 时只需动 nginx 层。

三、前置条件

服务器已安装 Docker 与 Docker Compose v2，且 Docker 守护进程可拉取镜像（国外网络环境需已配置代理）；
对外端口空闲：部署前实查目标端口（本文实测选用 8152，选端口前先查占用）：

ss -ltn | awk '{print $4}' | grep -oE '[0-9]+$' | sort -un | tr '\n' ' '

实测回显（当时 81xx 段已有服务占用 8147/8149/8150，故避开）：

22 53 631 1935 8147 8149 8150 8554 8888 8889 8892 38443 40051 40973

自定义网络网段空闲：先查看既有网络已占用的 10.89.x.0/24 网段，从空闲槽位显式指定子网（避免与其他 Compose 项目网段冲突）：

docker network ls --format '{{.Name}}' | while read n; do
  s=$(docker network inspect "$n" --format '{{range .IPAM.Config}}{{.Subnet}}{{end}}' 2>/dev/null); echo "$n  $s"
done

实测回显（10.89.56.0/24、10.89.57.0/24 已被其他项目网络占用，本文取 10.89.58.0/24）：

bridge  172.17.0.0/16
directory-lister-5.8.3-net  10.89.57.0/24
filegator-v7.16.8-net  10.89.56.0/24
host
none

服务器可下载 GitHub Release 件（官方源不通时代理，见环境信息中的网络说明）。

四、部署步骤

本章从零完成：目录规划 → 下载解压 → 数据目录授权 → 应用镜像构建 → nginx 配置 → Compose 编排 → 启动验证。约定部署根目录为 /opt/filerise/。

4.1 目录规划与下载应用

# 创建部署目录结构：compose/ 编排件、app/ 应用代码、data/ 三个数据目录
mkdir -p /opt/filerise/{compose,data/uploads,data/users,data/metadata} /opt/filerise/dl
cd /opt/filerise/dl
# 下载官方 Release ZIP（官方源不通时改走代理，本文实测直连失败后经代理取得）
curl -fsSL -o FileRise-v3.38.0.zip \
  "https://github.com/error311/FileRise/releases/download/v3.38.0/FileRise-v3.38.0.zip"

直连失败时的实测现象与降级后的下载回显：

curl: (7) Failed to connect to github.com port 443 after 21048 ms: Couldn't connect to server

代理渠道下载成功后核验文件（约 18 MB）：

ls -la /opt/filerise/dl/

-rw-r--r-- 1 root root 18029874 Oct 30 14:11 FileRise-v3.38.0.zip

解压到应用目录并确认结构（发布件自带 vendor/ 全量依赖，无需 composer install）：

cd /opt/filerise && mkdir -p app && cd app && unzip -qo ../dl/FileRise-v3.38.0.zip
ls

CHANGELOG.md      Dockerfile        LICENSE     README.md    SECURITY.md  config   docs    openapi.json.dist  phpcs.xml  scripts  start.sh  tests   THIRD_PARTY.md
codeql-config.yml  composer.json  composer.lock  custom-php.ini  docker-compose.yml  licenses  public  src  vendor

关键结构：public/（Web 根，含 index.php、api/、webdav.php）、config/config.php（应用配置）、src/（业务源码）、vendor/（依赖）、openapi.json.dist（REST API 规范）。

4.2 数据目录授权

FileRise 三个数据目录必须可被 PHP-FPM 进程用户（Debian/Ubuntu 下 www-data，UID/GID 33）写入：

chown -R www-data:www-data /opt/filerise/data

⚠️ 注意：bind mount 进 PHP 容器后，容器内 www-data 与宿主机 www-data 同为 UID 33，宿主机侧授权即可生效，无需进入容器操作。

4.3 构建 PHP-FPM 应用镜像（含 zip 扩展）

官方 PHP 镜像不含 zip 扩展，需要一个小 Dockerfile（保存为 /opt/filerise/compose/Dockerfile.php）：

FROM php:8.3-fpm

RUN apt-get update \
    && apt-get install -y --no-install-recommends libzip-dev \
    && docker-php-ext-install zip \
    && rm -rf /var/lib/apt/lists/*

# 对齐官方 custom-php.ini 的上传与会话约束
RUN { \
    echo "upload_max_filesize=5G"; \
    echo "post_max_size=5G"; \
    echo "memory_limit=512M"; \
    echo "max_execution_time=300"; \
    echo "max_input_time=300"; \
    echo "max_file_uploads=20"; \
    echo "display_errors=Off"; \
    echo "log_errors=On"; \
    echo "session.upload_progress.enabled=Off"; \
  } > /usr/local/etc/php/conf.d/zz-filerise.ini

EXPOSE 9000
CMD ["php-fpm"]

配置块逐项说明：upload_max_filesize/post_max_size 提到 5G 对齐官方镜像默认的 TOTAL_UPLOAD_SIZE=5G（PHP 默认仅 2M/8M，不改则大文件上传必失败）；memory_limit=512M、max_execution_time=300、max_input_time=300 沿用官方 custom-php.ini 的取值，保障大文件处理与长耗时请求；session.upload_progress.enabled=Off 与官方一致（FileRise 在浏览器侧跟踪上传进度，关闭 PHP 会话进度可规避已知漏洞面）。

构建：

cd /opt/filerise/compose && docker compose build php

实测回显（节选）：

#9 resolving provenance for metadata file
#9 DONE 0.0s
 Image filerise-v3.38.0-php:8.3 Built

4.4 nginx 站点配置

保存为 /opt/filerise/compose/nginx.conf：

server {
    listen 80;
    server_name _;

    root /var/www/filerise/public;
    index index.php index.html;

    client_max_body_size 5G;
    client_body_timeout 300s;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        try_files $uri =404;
        fastcgi_pass php:9000;
        fastcgi_index index.php;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME /var/www/filerise/public$fastcgi_script_name;
        fastcgi_param HTTP_AUTHORIZATION $http_authorization;
        fastcgi_read_timeout 300s;
        fastcgi_buffer_size 64k;
        fastcgi_buffers 8 64k;
    }

    location ~* \.(css|js|ico|svg|woff2?|ttf|png|jpg|jpeg|gif|webmanifest)$ {
        expires 7d;
        access_log off;
        try_files $uri =404;
    }

    location ~ ^/(uploads|users|metadata)(/|$) {
        deny all;
    }
}

逐项说明：root 指向应用内 public/ 子目录（官方要求，源码与数据不可直接暴露）；client_max_body_size 5G 必须与 PHP 的 post_max_size 同量级，否则 nginx 层先拒 413；fastcgi_pass php:9000 使用 Compose 服务名寻址 PHP-FPM；fastcgi_param SCRIPT_FILENAME 用容器内统一路径 /var/www/filerise/public；HTTP_AUTHORIZATION 透传是 WebDAV 的 HTTP Basic 认证可用前提（nginx 默认不传 Authorization 头）；静态资源段给 7 天缓存；最后一段封禁三个数据目录的直接 HTTP 访问——数据必须经 API 读写。

4.5 Compose 编排文件

保存为 /opt/filerise/compose/docker-compose.yml（显式项目名 + 显式子网，避免与他项目冲突）：

name: filerise-v3.38.0-stack

services:
  web:
    image: nginx:alpine
    container_name: filerise-v3.38.0-web
    restart: unless-stopped
    ports:
      - "8152:80"
    volumes:
      - ../app:/var/www/filerise:ro
      - ./nginx.conf:/etc/nginx/conf.d/default.conf:ro
    depends_on:
      - php
    networks:
      - filerise-net

  php:
    build:
      context: .
      dockerfile: Dockerfile.php
    image: filerise-v3.38.0-php:8.3
    container_name: filerise-v3.38.0-php
    restart: unless-stopped
    environment:
      SECURE: "false"          # 有 TLS 反代时改为 "true"
      FR_TRUSTED_PROXIES: ""   # 反代场景填代理网段，如 10.89.58.0/24
    volumes:
      - ../app:/var/www/filerise
      - ../data/uploads:/var/www/uploads
      - ../data/users:/var/www/users
      - ../data/metadata:/var/www/metadata
    networks:
      - filerise-net

networks:
  filerise-net:
    driver: bridge
    ipam:
      config:
        - subnet: 10.89.58.0/24

逐项说明：name 固定项目名为 filerise-v3.38.0-stack（版本化命名，docker compose down 只影响本项目）；web 以只读方式挂应用代码与 nginx 配置；php 侧应用目录保持可读写（应用要写站点自身需要的运行时文件），三个数据目录按官方默认容器内路径挂载；environment.SECURE=false 对应 HTTP 部署，上 TLS 反代后改 true（影响 Cookie 安全标记与跳转逻辑）；网络显式 10.89.58.0/24。

4.6 启动与状态确认

cd /opt/filerise/compose && docker compose up -d

实测回显：

 Container filerise-v3.38.0-php Starting
 Container filerise-v3.38.0-php Started
 Container filerise-v3.38.0-web Starting
 Container filerise-v3.38.0-web Started

docker compose ps

NAME                   IMAGE                      COMMAND                  SERVICE   CREATED        STATUS                  PORTS
filerise-v3.38.0-php   filerise-v3.38.0-php:8.3   "docker-php-entrypoi…"   php       1 second ago   Up Less than a second   9000/tcp
filerise-v3.38.0-web   nginx:alpine               "/docker-entrypoint.…"   web       1 second ago   Up Less than a second   0.0.0.0:8152->80/tcp, [::]:8152->80/tcp

首启验证——访问首页应返回 200 与 FileRise 页面：

curl -sS -o /dev/null -w 'HTTP %{http_code}\n' http://localhost:8152/
curl -sS http://localhost:8152/ | head -c 300

实测回显：

HTTP 200
<!DOCTYPE html>
<html lang="en">

<head>
  <meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>FileRise</title>
  <meta name="theme-color" content="#0b5ed7">

4.7 首次启动：创建管理员

全新实例（users 目录无用户）首次访问 Web 界面会进入管理员创建引导页；脚本化部署可用初始化接口直接建号（无用户状态下开放，建号后即关闭）：

cd /opt/filerise
curl -sS -c cookies.txt -X POST 'http://localhost:8152/api/addUser.php?setup=1' \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"q1w2e3r4"}' -w '\n[HTTP %{http_code}]\n'

实测回显：

{"ok":true,"data":{"success":"User added successfully"},"success":true,"message":"User added successfully"}
[HTTP 200]

⚠️ 注意：初始化窗口只在无用户时开放，首个管理员创建完成后该入口自动失效（用户目录会生成 .setup_complete 标记），务必在部署完成后立即建号。

登录并核验会话（HTTP 接口方式，浏览器登录等价）：

curl -sS -c cookies.txt -b cookies.txt -X POST 'http://localhost:8152/api/auth/auth.php' \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"q1w2e3r4"}' -w '\n[HTTP %{http_code}]\n'
curl -sS -b cookies.txt 'http://localhost:8152/api/auth/checkAuth.php' -w '\n[HTTP %{http_code}]\n'

实测回显：

{"status":"ok","success":"Login successful","isAdmin":true,"folderOnly":false,"readOnly":false,"disableUpload":false,"username":"admin"}
[HTTP 200]
{"authenticated":true,"isAdmin":true,"totp_enabled":false,"username":"admin","folderOnly":false,"readOnly":false,"disableUpload":false}
[HTTP 200]

五、功能实测：上传 / 重命名 / 删除 / 恢复 / 下载 / WebDAV

本章全部命令在 4.6 部署完成并登录后逐条实测。所有写操作接口受 CSRF 令牌保护，先按 5.1 取得令牌，再携带 X-CSRF-Token 头调用。

5.1 取得 CSRF 令牌（实测排障沉淀）

直接调用写接口会收到 403：

curl -sS -b cookies.txt -X POST 'http://localhost:8152/api/folder/createFolder.php' \
  -H 'Content-Type: application/json' -d '{"folderName":"reports","parent":"root"}'

{"error":"Invalid CSRF token"} [HTTP 403]

CSRF 令牌与登录会话绑定，实测最直接的取法：向任一写接口（如上传）不带令牌发一次请求，服务端会软失效并回发新令牌（响应同时已写入会话，下一次请求即可使用）：

curl -sS -b cookies.txt -X POST 'http://localhost:8152/api/upload/upload.php' -F 'file=@/dev/null' -F 'folder=root'

实测回显（令牌为当时实测原值，每次会话不同）：

{"csrf_expired":true,"csrf_token":"452fc4cb5b644aa4bac7ec74aa70cc0fae5d074f0bc4c3e7329f267afc468ae5"} [HTTP 200]

后续命令统一携带 -H "X-CSRF-Token: 452fc4cb5b644aa4bac7ec74aa70cc0fae5d074f0bc4c3e7329f267afc468ae5"（下文以 $T 指代该值）。

5.2 创建文件夹

curl -sS -b cookies.txt -X POST 'http://localhost:8152/api/folder/createFolder.php' \
  -H "X-CSRF-Token: $T" -H 'Content-Type: application/json' \
  -d '{"folderName":"reports","parent":"root"}' -w ' [HTTP %{http_code}]\n'

实测回显：

{"success":true,"folder":"reports"} [HTTP 200]

5.3 上传文件（含一次真实排障）

准备两个测试文件并上传（单发上传接口为 multipart 表单，文件字段名为 file）：

printf 'FileRise upload test line 1\nline 2 你好\n' > upload-demo.txt
head -c 1048576 /dev/urandom > demo-1mb.bin
curl -sS -b cookies.txt -X POST 'http://localhost:8152/api/upload/upload.php' \
  -H "X-CSRF-Token: $T" -F 'file=@upload-demo.txt' -F 'folder=root' -w ' [HTTP %{http_code}]\n'
curl -sS -b cookies.txt -X POST 'http://localhost:8152/api/upload/upload.php' \
  -H "X-CSRF-Token: $T" -F 'file=@demo-1mb.bin' -F 'folder=root' -w ' [HTTP %{http_code}]\n'

实测回显：

{"success":"Files uploaded successfully","newFilename":null} [HTTP 200]
{"success":"Files uploaded successfully","newFilename":null} [HTTP 200]

⚠️ 排障实录：首次实测按 OpenAPI 文档描述使用字段名 fileToUpload，服务端返回 {"error":"No files received"} [HTTP 400]；核对服务端实现后确认实际接受字段名为 file（分块续传与单发两条路径均如此），改用 file 后成功。遇同类报错先检查表单字段名与 CSRF 头。

上传后核验落盘（数据目录即真实服务器磁盘）：

ls -la /opt/filerise/data/uploads/

实测回显：

-rw-r--r-- 1 www-data www-data 1048576 Oct 30 14:36 demo-1mb.bin
drwxr-xr-x 2 www-data www-data     4096 Oct 30 14:36 reports
drwxr-xr-x 2 www-data www-data     4096 Oct 30 14:37 trash
-rw-r--r-- 1 www-data www-data      42 Oct 30 14:36 演示文档.txt

5.4 文件列表与重命名

curl -sS -b cookies.txt 'http://localhost:8152/api/file/getFileList.php?folder=root'

实测回显（节选）：

{"files":[{"name":"demo-1mb.bin","modified":"10/30/26  02:36AM","uploaded":"10/30/26  02:36AM","size":"1.0 MB","sizeBytes":1048576,"uploader":"admin","tags":[],"mime":"application/octet-stream","sourceId":"local","content":"","contentTruncated":false},{"name":"upload-demo.txt","modified":"10/30/26  02:36AM","uploaded":"10/30/26  02:36AM","size":"42 bytes","sizeBytes":42,"uploader":"admin","tags":[],"mime":"text/plain","sourceId":"local","content":"","contentTruncated":false}],"globalTags":[],"sourceId":"local"}

重命名（支持中文文件名）：

curl -sS -b cookies.txt -X PUT 'http://localhost:8152/api/file/renameFile.php' \
  -H "X-CSRF-Token: $T" -H 'Content-Type: application/json' \
  -d '{"folder":"root","oldName":"upload-demo.txt","newName":"演示文档.txt"}' -w ' [HTTP %{http_code}]\n'

实测回显：

{"success":"File renamed successfully","newName":"演示文档.txt"} [HTTP 200]

再次拉列表确认改名生效：

['demo-1mb.bin', '演示文档.txt']

5.5 删除（进回收站）与恢复

curl -sS -b cookies.txt -X POST 'http://localhost:8152/api/file/deleteFiles.php' \
  -H "X-CSRF-Token: $T" -H 'Content-Type: application/json' \
  -d '{"folder":"root","files":["演示文档.txt"]}' -w ' [HTTP %{http_code}]\n'

实测回显：

{"success":"Files moved to Trash: 演示文档.txt"} [HTTP 200]

查看回收站（文件以「原名_时间戳_随机串」形式暂存）：

curl -sS -b cookies.txt 'http://localhost:8152/api/file/getTrashItems.php'

实测回显：

[{"type":"file","originalFolder":"/var/www/uploads/","originalName":"演示文档.txt","trashName":"演示文档.txt_1793342223_21d315a7","trashedAt":1793342223,"uploaded":"10/30/26  02:36AM","uploader":"admin","deletedBy":"admin"}]

按回收站名恢复：

curl -sS -b cookies.txt -X POST 'http://localhost:8152/api/file/restoreFiles.php' \
  -H "X-CSRF-Token: $T" -H 'Content-Type: application/json' \
  -d '{"files":["演示文档.txt_1793342223_21d315a7"]}' -w ' [HTTP %{http_code}]\n'

实测回显：

{"success":"Items restored: 演示文档.txt","restored":["演示文档.txt"]} [HTTP 200]

5.6 下载验证

curl -sS -b cookies.txt 'http://localhost:8152/api/file/download.php?folder=root&file=%E6%BC%94%E7%A4%BA%E6%96%87%E6%A1%A3.txt' -w ' [HTTP %{http_code}]\n'

实测回显（内容逐字一致，中文未乱码）：

FileRise upload test line 1
line 2 你好
 [HTTP 200]

⚠️ 排障实录：下载接口的文件参数名是 file（不是 filename）。实测用错参数名时返回 {"error":"Invalid file name."} [HTTP 400]；另外若目标文件已在回收站中，返回 {"error":"Access forbidden."} [HTTP 404]——先恢复再下载。

5.7 WebDAV 开启与挂载验证

WebDAV 默认关闭（管理员配置项），实测未开启时访问返回：

[HTTP 403]
WebDAV access is currently disabled by administrator.

经管理接口开启（该配置落在 users 目录的加密管理配置中，详见《FileRise 3.38 配置参数详解》）：

curl -sS -b cookies.txt -X POST 'http://localhost:8152/api/admin/updateConfig.php' \
  -H "X-CSRF-Token: $T" -H 'Content-Type: application/json' \
  -d '{"enableWebDAV":true}' -w ' [HTTP %{http_code}]\n'

实测回显：

{"success":"Configuration updated successfully."} [HTTP 200]

用 HTTP Basic 认证（WebDAV 独立于浏览器会话）列根目录：

curl -sS -u admin:q1w2e3r4 -X PROPFIND 'http://localhost:8152/webdav.php' -H 'Depth: 1' -w '[HTTP %{http_code}]\n' | head -c 500

实测回显（HTTP 207 Multi-Status，可看到 5.2 建的 reports 目录）：

[HTTP 207]
<?xml version="1.0"?>
<d:multistatus xmlns:d="DAV:" xmlns:s="http://sabredav.org/ns"><d:response><d:href>/webdav.php/</d:href><d:propstat><d:prop><d:getlastmodified>Fri, 30 Oct 2026 06:37:56 GMT</d:getlastmodified><d:resourcetype><d:collection/></d:resourcetype></d:prop><d:status>HTTP/1.1 200 OK</d:status></d:propstat></d:response><d:response><d:href>/webdav.php/reports/</d:href>…（节选）

⚠️ 注意：WebDAV 的 Basic 认证依赖 nginx 透传 Authorization 头（见 4.4 的 HTTP_AUTHORIZATION 行）；若漏配，PROPFIND 会始终 403。

5.8 重启持久化验证

重启 PHP 服务后数据应完整保留：

cd /opt/filerise/compose && docker compose restart php
sleep 2
curl -sS -b ../cookies.txt 'http://localhost:8152/api/file/getFileList.php?folder=root' | python3 -c "import json,sys; d=json.load(sys.stdin); print('after restart files:', [f['name'] for f in d['files']])"

实测回显：

after restart files: ['demo-1mb.bin', '演示文档.txt']

六、数据持久化说明

FileRise 是零数据库应用，状态全部落在三个 bind mount 目录（宿主机 /opt/filerise/data/，容器内 /var/www/ 对应路径）：

宿主机目录	容器内路径	内容	实测产物举例
data/uploads	/var/www/uploads	上传文件、子目录、trash/ 回收站	demo-1mb.bin、演示文档.txt、reports/
data/users	/var/www/users	用户清单 users.txt、管理配置 adminConfig.json（加密）、站点配置 siteConfig.json、初始化标记	adminConfig.json、.setup_complete
data/metadata	/var/www/metadata	文件元数据 JSON、文件夹 ACL（folder_acl.json）、持久化令牌密钥（600 权限）	root_metadata.json、persistent_tokens.key

实测注意三点：目录属主需为 www-data（4.2）；persistent_tokens.key 为 0600 私有权限，备份时一并带走（丢失则「记住登录」令牌全部失效）；adminConfig.json 在磁盘上是密文，读取请走管理接口 /api/admin/getConfig.php。备份策略：定时打包三个目录即可整体备份；迁移到新机 = 拷贝 app/（或重新解压同版本 ZIP）+ 三个数据目录。

七、环境变量表

本方案 PHP 服务读取的环境变量（compose environment: 注入）：

变量	本方案取值	说明
SECURE	"false"	HTTPS 部署时置 true，影响安全 Cookie 与跳转
FR_TRUSTED_PROXIES	""	信任的反代网段列表；有反代时填如 10.89.58.0/24，配合 FR_IP_HEADER 取真实客户端 IP

作为对照，官方一体镜像（error311/filerise-docker）的完整变量集（实查自官方发布件 docker-compose.yml 与 start.sh，官方镜像在启动时把这些值写回应用配置）：

变量	官方默认	说明
TIMEZONE	UTC	站点时区（写回 config.php 的 TIMEZONE 常量）
DATE_TIME_FORMAT	m/d/y h:iA	列表时间格式
TOTAL_UPLOAD_SIZE	5G	上传总量上限（写回 config.php）
SECURE	false	HTTPS 标记
PERSISTENT_TOKENS_KEY	空	持久化令牌密钥；留空则首启自动生成并落 metadata/persistent_tokens.key
PUID / PGID	1000 / 1000	官方镜像将 www-data 重映射到该 UID/GID 后 chown 数据目录
CHOWN_ON_START	true	每次启动递归修正 uploads/metadata 属主（权限就绪后建议改 false）
SCAN_ON_START	true	启动时扫描上传目录建立元数据（一次性）
SHARE_URL	空	分享链接对外展示域名

⚠️ 注意：nginx+PHP-FPM 自组方案不经过官方 start.sh，时区与上传上限等常量直接在 config/config.php 中定义（详见《FileRise 3.38 配置参数详解》的三层配置体系）；FR_* 系列环境变量则对两种方案同等生效。

八、配置参数说明与配置文件挂载

本方案的配置文件挂载清单：

文件	挂载方式	作用
compose/nginx.conf	:ro 挂到 web 的 /etc/nginx/conf.d/default.conf	站点路由、PHP 反代、上传体积、数据目录封禁
compose/Dockerfile.php	构建期生效	zip 扩展 + zz-filerise.ini（上传/超时/会话约束）
app/（应用代码）	web 只读、php 可写	官方 Release v3.38.0 解压件
data/{uploads,users,metadata}	php 可写	三目录数据模型

PHP 层关键参数与 nginx 层必须对齐：client_max_body_size（nginx）≥ post_max_size（PHP）≥ 单文件 upload_max_filesize（PHP）；本方案统一 5G。运行时业务配置（管理员界面/管理接口管理的站点标题、登录方式、WebDAV 开关、分享上限、OnlyOffice、ClamAV、缩略图等）存于 users 目录，逐项解释见《FileRise 3.38 配置参数详解》。

九、等价 docker run（单命令对照）

与上述 Compose 等价的单命令形态（便于快速对照理解，实际交付仍建议用 4.5 的 compose 文件管理）：

# PHP-FPM 应用服务（应用代码与三个数据目录 bind mount）
docker run -d --name filerise-v3.38.0-php \
  -e SECURE=false \
  -v /opt/filerise/app:/var/www/filerise \
  -v /opt/filerise/data/uploads:/var/www/uploads \
  -v /opt/filerise/data/users:/var/www/users \
  -v /opt/filerise/data/metadata:/var/www/metadata \
  --network filerise-v3380-stack_filerise-net \
  filerise-v3.38.0-php:8.3

# nginx Web 层（8152 对外，静态直出 + fastcgi 反代）
docker run -d --name filerise-v3.38.0-web \
  -p 8152:80 \
  -v /opt/filerise/app:/var/www/filerise:ro \
  -v /opt/filerise/compose/nginx.conf:/etc/nginx/conf.d/default.conf:ro \
  --network filerise-v3380-stack_filerise-net \
  nginx:alpine

十、常用运维命令

cd /opt/filerise/compose
docker compose ps                 # 服务状态
docker compose logs -f web        # Web 层日志（nginx 访问/错误）
docker compose logs -f php        # PHP-FPM 日志（应用 error_log 也落此处）
docker compose restart php        # 重启应用服务（数据不受影响，见 5.8 实测）
docker compose down               # 停止并移除本项目容器与网络（bind mount 数据保留）
docker compose up -d              # 再次拉起

升级流程（保持数据不动，只换应用代码）：下载新版本 Release ZIP → 备份 data/ 三目录 → 清空 app/ 并解压新 ZIP（保留 data 不动）→ docker compose restart php web。若官方镜像路径有变（如 newlib 依赖变化），以官方升级说明为准。

十一、常见问题

Q1：docker compose up 报 invalid pool request: Pool overlaps with other one on this address space 自定义子网与既有网络冲突。实测本文最初指定 10.89.56.0/24 时命中已被占用的网段（错误回显如上），按第三章命令实查后改用空闲槽位（10.89.58.0/24）解决。选端口同理：8149 实查已被既有服务占用，改用 8152。

Q2：写操作一律 {"error":"Invalid CSRF token"} CSRF 令牌与会话绑定且登录后不自动下发到接口响应头。按 5.1：先对任一写接口空发一次拿回 csrf_token，再统一携带 X-CSRF-Token。

Q3：上传返回 {"error":"No files received"} multipart 文件字段名必须是 file（不是 OpenAPI 示例里的 fileToUpload），且请求需带 CSRF 头。

Q4：大文件上传 413 或中途失败 检查三层限制是否同量级对齐：nginx client_max_body_size、PHP post_max_size/upload_max_filesize、应用层 TOTAL_UPLOAD_SIZE（config.php）；以及 client_body_timeout/max_input_time 是否足够。本文均按 5G / 300s 实测对齐。

Q5：WebDAV 一直 403 两种原因实测均出现：未开启（响应体为 WebDAV access is currently disabled by administrator.，经管理接口置 enableWebDAV=true）；nginx 未透传 Authorization 头（漏配 fastcgi_param HTTP_AUTHORIZATION 时 Basic 认证永远失败）。

Q6：下载返回 Invalid file name. 或 Access forbidden. 参数名用 file；文件在回收站中时不可下载，先恢复（5.6）。

Q7：首页 200 但样式错乱 nginx 的 root 必须指向 public/ 子目录而非应用根；静态资源由 nginx 直出，若误把整站交给 PHP 处理会出现资源 404。

十二、参考链接

FileRise 官方文档 Installation & Setup：https://filerise.net/docs/?page=installation-setup
FileRise GitHub 仓库：https://github.com/error311/FileRise
FileRise v3.38.0 Release：https://github.com/error311/FileRise/releases/tag/v3.38.0
站内延伸阅读：《FileRise 介绍与选型指南》（定位与量化对比）、《FileRise 3.38 配置参数详解》（三层配置体系逐项说明）、《FileRise 3.38 API 使用详解》（REST API 全量实测）