FileBrowser 网盘软件架构设计与教程指南

📘 完整文档 v2.x

从零到一，全面掌握 FileBrowser 的系统架构设计、安装部署、配置管理、API 开发及安全加固的终极参考手册

30+

知识章节

50+

代码示例

100%

开源免费

Go+Vue

技术栈

找到 0 个匹配项

📖

第一章：FileBrowser 项目概述

入门

🔹 什么是 FileBrowser？

FileBrowser（原名 File Manager）是一款开源的、轻量级的 Web 文件管理器。它提供了一个美观的 Web 界面，允许用户通过浏览器对服务器上的文件进行上传、下载、编辑、分享和管理操作。整个应用编译为一个单一的可执行文件，部署极为简单。

💡

项目地址：

https://github.com/filebrowser/filebrowser

官方文档：

https://filebrowser.org

开源协议：

Apache License 2.0

🔹 设计理念

• 极简主义：单二进制文件，零依赖部署，无需复杂的环境配置
• 安全优先：内建用户认证、权限控制、目录沙箱隔离
• 跨平台：支持 Linux、macOS、Windows、FreeBSD、ARM 等
• 可扩展：提供完善的 RESTful API，支持 Webhook 和自定义命令
• 嵌入式：前端静态资源编译进二进制，无需单独的 Web 服务器

🔹 适用场景

✨

核心功能特性详解

功能

🔹 文件管理

• 上传：支持拖拽上传、多文件上传、文件夹上传，显示实时进度
• 下载：单文件下载、多文件/文件夹打包 ZIP 下载
• 预览：图片、视频、音频、PDF、Markdown、代码文件等即时预览
• 编辑：内建文本编辑器，支持语法高亮（基于 Monaco/Ace）
• 操作：新建、重命名、移动、复制、删除文件/文件夹
• 搜索：文件名全文搜索，支持正则匹配
• 排序：按名称、大小、修改时间、类型排序

🔹 用户与权限

• 多用户系统，支持管理员与普通用户角色
• 每个用户可独立设置根目录（Scope），实现目录隔离
• 细粒度权限控制：上传、下载、删除、重命名、创建、编辑
• 支持命令执行权限的独立开关
• 用户配额管理（磁盘使用限制）

🔹 分享系统

• 生成文件/文件夹的公开分享链接
• 支持设置分享密码保护
• 支持设置分享过期时间
• 管理所有已创建的分享链接

🔹 其他特性

• 多语言支持（中文、英文、日文等 20+ 种语言）
• 暗色主题切换
• Shell 命令执行（受限模式）
• Webhook 事件通知
• 完整的 RESTful API
• 自定义 CSS/JS 品牌定制

🛠️

技术栈选型说明

技术

✅

为什么选择 Go？

Go 语言的交叉编译特性使得 FileBrowser 可以为几乎所有主流平台（amd64、arm、arm64、mips 等）生成单一二进制文件，用户无需安装任何运行时环境即可直接使用。

🏗️

第二章：系统整体架构设计

架构

🔹 分层架构图

🌐 客户端浏览器 (Vue.js SPA)

⬇️ HTTP/HTTPS (JSON / Binary) ⬇️

🔒 TLS 终止层 (Nginx/Caddy)

⬇️ Reverse Proxy ⬇️

🛡️ 中间件层

Auth → Rate Limit → CORS → Logging → Recovery

⬇️

📡 API Router (chi)

⬇️

📁 文件服务层

👤 用户服务层

🔗 分享服务层

💻 命令服务层

⬇️

🗄️ SQLite/BoltDB

📂 本地文件系统

🔹 请求处理流程

请求接入

客户端发起 HTTP 请求，经 Nginx 反向代理转发至 FileBrowser 监听端口

中间件链处理

依次通过 Recovery → Logger → CORS → Auth 中间件，完成错误恢复、日志记录、跨域处理和身份验证

路由分发

chi 路由器根据 URL 路径和 HTTP 方法匹配对应的 Handler

业务逻辑

Handler 调用相应的 Service 层，执行业务逻辑（文件操作、用户管理等）

数据持久化

Service 层与 SQLite/BoltDB 交互完成数据读写，或直接操作文件系统

响应返回

将结果序列化为 JSON 或二进制流，通过 HTTP Response 返回客户端

🔹 目录结构设计

Project Structure

filebrowser/
├── main.go              # 程序入口
├── cmd/                 # CLI 命令定义（Cobra）
│   ├── root.go          # 根命令
│   ├── config.go        # 配置管理命令
│   ├── users.go         # 用户管理命令
│   ├── upgrade.go       # 数据库升级命令
│   └── version.go       # 版本信息
├── http/                # HTTP 层
│   ├── http.go          # HTTP 服务器启动
│   ├── middleware.go     # 中间件定义
│   ├── auth.go          # 认证处理器
│   ├── resource.go      # 文件资源处理器
│   ├── share.go         # 分享处理器
│   ├── users.go         # 用户处理器
│   ├── settings.go      # 设置处理器
│   ├── commands.go      # 命令执行处理器
│   └── static.go        # 静态文件嵌入服务
├── files/               # 文件操作层
│   ├── file.go          # 文件/目录信息结构
│   ├── listing.go       # 目录列表
│   └── utils.go         # 工具函数
├── users/               # 用户管理
│   ├── users.go         # 用户 CRUD
│   ├── storage.go       # 用户存储接口
│   └── permissions.go   # 权限模型
├── share/               # 分享管理
│   ├── share.go         # 分享结构
│   └── storage.go       # 分享存储
├── settings/            # 全局设置
│   ├── settings.go      # 设置结构
│   └── storage.go       # 设置存储
├── auth/                # 认证模块
│   ├── auth.go          # 认证接口
│   ├── json.go          # JSON 认证
│   ├── proxy.go         # 代理头认证
│   ├── hook.go          # Hook 认证
│   └── none.go          # 无认证模式
├── storage/             # 数据持久化
│   ├── storage.go       # 存储引擎接口
│   ├── bolt.go          # BoltDB 实现
│   └── sqlite.go        # SQLite 实现
├── runner/              # 命令执行器
│   └── runner.go        # Shell 命令管理
├── errors/              # 错误定义
│   └── errors.go
├── frontend/            # Vue.js 前端
│   ├── src/
│   │   ├── api/         # API 调用封装
│   │   ├── components/  # Vue 组件
│   │   ├── store/       # Pinia 状态管理
│   │   ├── router/      # 路由配置
│   │   ├── views/       # 页面视图
│   │   ├── i18n/        # 国际化
│   │   └── utils/       # 工具函数
│   ├── dist/            # 构建产物
│   └── package.json
└── go.mod               # Go 模块定义

🎨

前端架构详细设计

架构

🔹 前端技术选型

FileBrowser 前端基于 Vue 3 构建为单页应用 (SPA)，采用 Composition API，使用 Vite 作为构建工具。构建产物通过 Go 1.16+ 的 embed 包嵌入到最终二进制文件中。

🔹 路由设计

🔹 状态管理（Pinia Store）

JavaScript

// store/auth.js
export const useAuthStore = defineStore('auth', {
  state: () => ({
    user: null,          // 当前用户信息
    token: null,         // JWT Token
    isAuthenticated: false,
  }),
  actions: {
    async login(username, password) {
      const response = await api.post('/api/login', { username, password });
      this.token = response.data;
      this.isAuthenticated = true;
      localStorage.setItem('jwt', this.token);
      await this.fetchUser();
    },
    async fetchUser() {
      const response = await api.get('/api/me');
      this.user = response.data;
    },
    logout() {
      this.token = null;
      this.user = null;
      this.isAuthenticated = false;
      localStorage.removeItem('jwt');
    }
  }
});

// store/files.js
export const useFilesStore = defineStore('files', {
  state: () => ({
    current: null,       // 当前目录信息
    items: [],           // 当前目录下的文件列表
    selected: [],        // 已选中的文件
    loading: false,
    uploadProgress: {},
    clipboard: null,     // 剪贴板（复制/剪切）
    searchQuery: '',
    sortBy: 'name',
    sortOrder: 'asc',
  }),
  actions: {
    async fetchDir(path) {
      this.loading = true;
      const response = await api.get(`/api/resources${path}`);
      this.current = response.data;
      this.items = response.data.items || [];
      this.loading = false;
    },
    async deleteFiles(paths) {
      await api.delete('/api/resources', { data: { paths } });
      await this.fetchDir(this.current.path);
    },
    async upload(file, path) {
      const formData = new FormData();
      formData.append('file', file);
      await api.post(`/api/resources${path}`, formData, {
        headers: { 'Content-Type': 'multipart/form-data' },
        onUploadProgress: (e) => {
          this.uploadProgress[file.name] = Math.round(e.loaded / e.total * 100);
        }
      });
    }
  }
});

🔹 API 请求封装

JavaScript

// api/index.js
import axios from 'axios';

const api = axios.create({
  baseURL: '/',
  timeout: 30000,
});

// 请求拦截器：自动附加 JWT
api.interceptors.request.use(config => {
  const token = localStorage.getItem('jwt');
  if (token) {
    config.headers['X-Auth'] = token;
  }
  return config;
});

// 响应拦截器：处理 401
api.interceptors.response.use(
  response => response,
  error => {
    if (error.response?.status === 401) {
      localStorage.removeItem('jwt');
      window.location.href = '/login';
    }
    return Promise.reject(error);
  }
);

export default api;

⚙️

后端架构详细设计

架构

🔹 HTTP 路由注册

Go

// http/http.go
func NewHandler(storage *storage.Storage, auth auth.Auth) http.Handler {
    r := chi.NewRouter()

    // 全局中间件
    r.Use(middleware.Recoverer)
    r.Use(middleware.RequestID)
    r.Use(middleware.RealIP)
    r.Use(customLogger)
    r.Use(corsHandler)

    // 公开路由
    r.Post("/api/login", loginHandler(storage, auth))
    r.Get("/api/health", healthHandler)
    r.Get("/share/{hash}", shareDownloadHandler(storage))

    // 受保护路由
    r.Group(func(r chi.Router) {
        r.Use(authMiddleware(storage))

        // 用户信息
        r.Get("/api/me", meHandler(storage))
        r.Put("/api/me", updateUserHandler(storage))

        // 文件资源
        r.Get("/api/resources/*", resourceGetHandler)
        r.Post("/api/resources/*", resourcePostHandler)
        r.Put("/api/resources/*", resourcePutHandler)
        r.Delete("/api/resources/*", resourceDeleteHandler)
        r.Patch("/api/resources/*", resourcePatchHandler)

        // 分享管理
        r.Get("/api/shares", shareListHandler(storage))
        r.Post("/api/shares", shareCreateHandler(storage))
        r.Delete("/api/shares/{hash}", shareDeleteHandler(storage))

        // 命令执行
        r.Post("/api/command", commandHandler)

        // 管理员路由
        r.Group(func(r chi.Router) {
            r.Use(adminMiddleware)
            r.Get("/api/users", usersListHandler(storage))
            r.Post("/api/users", userCreateHandler(storage))
            r.Put("/api/users/{id}", userUpdateHandler(storage))
            r.Delete("/api/users/{id}", userDeleteHandler(storage))
            r.Get("/api/settings", settingsGetHandler(storage))
            r.Put("/api/settings", settingsPutHandler(storage))
        })
    })

    // SPA 静态资源兜底
    r.Get("/*", staticHandler)

    return r
}

🔹 中间件设计

Go

// authMiddleware: JWT 认证中间件
func authMiddleware(store *storage.Storage) func(http.Handler) http.Handler {
    return func(next http.Handler) http.Handler {
        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            token := r.Header.Get("X-Auth")
            if token == "" {
                http.Error(w, "Unauthorized", http.StatusUnauthorized)
                return
            }

            // 验证 JWT
            claims, err := validateJWT(token)
            if err != nil {
                http.Error(w, "Invalid token", http.StatusUnauthorized)
                return
            }

            // 加载用户
            user, err := store.Users.Get(claims.UserID)
            if err != nil {
                http.Error(w, "User not found", http.StatusUnauthorized)
                return
            }

            // 将用户信息注入 Context
            ctx := context.WithValue(r.Context(), "user", user)
            next.ServeHTTP(w, r.WithContext(ctx))
        })
    }
}

// adminMiddleware: 管理员权限检查
func adminMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        user := r.Context().Value("user").(*users.User)
        if !user.Perm.Admin {
            http.Error(w, "Forbidden", http.StatusForbidden)
            return
        }
        next.ServeHTTP(w, r)
    })
}

🔹 文件服务核心逻辑

Go

// files/file.go
type FileInfo struct {
    Path        string    `json:"path"`
    Name        string    `json:"name"`
    Size        int64     `json:"size"`
    Extension   string    `json:"extension"`
    Modified    time.Time `json:"modified"`
    Mode        os.FileMode `json:"mode"`
    IsDir       bool      `json:"isDir"`
    Type        string    `json:"type"`       // "file" | "dir"
    ContentType string    `json:"contentType"`
    Items       []*FileInfo `json:"items,omitempty"`
    NumDirs     int       `json:"numDirs"`
    NumFiles    int       `json:"numFiles"`
}

// GetFileInfo: 获取文件/目录信息
func GetFileInfo(fs afero.Fs, path string, expand bool) (*FileInfo, error) {
    info, err := fs.Stat(path)
    if err != nil {
        return nil, err
    }

    file := &FileInfo{
        Path:     path,
        Name:     info.Name(),
        Size:     info.Size(),
        Modified: info.ModTime(),
        Mode:     info.Mode(),
        IsDir:    info.IsDir(),
    }

    if info.IsDir() && expand {
        entries, _ := afero.ReadDir(fs, path)
        for _, entry := range entries {
            item := &FileInfo{
                Path:    filepath.Join(path, entry.Name()),
                Name:    entry.Name(),
                Size:    entry.Size(),
                IsDir:   entry.IsDir(),
                Modified: entry.ModTime(),
            }
            file.Items = append(file.Items, item)
            if entry.IsDir() {
                file.NumDirs++
            } else {
                file.NumFiles++
            }
        }
    }

    return file, nil
}

🗄️

数据存储层设计（SQLite / BoltDB）

架构

🔹 存储引擎选择

FileBrowser 支持两种嵌入式存储引擎：

🔹 SQLite 数据模型

SQL

-- 用户表
CREATE TABLE users (
    id          INTEGER PRIMARY KEY AUTOINCREMENT,
    username    TEXT UNIQUE NOT NULL,
    password    TEXT NOT NULL,           -- bcrypt 哈希
    scope       TEXT DEFAULT '/',        -- 用户根目录
    locale      TEXT DEFAULT 'zh-cn',
    view_mode   TEXT DEFAULT 'mosaic',   -- mosaic | list
    single_click BOOLEAN DEFAULT 0,
    sort_by     TEXT DEFAULT 'name',
    sort_asc    BOOLEAN DEFAULT 1,
    perm_admin   BOOLEAN DEFAULT 0,
    perm_execute BOOLEAN DEFAULT 0,
    perm_create  BOOLEAN DEFAULT 1,
    perm_rename  BOOLEAN DEFAULT 1,
    perm_modify  BOOLEAN DEFAULT 1,
    perm_delete  BOOLEAN DEFAULT 1,
    perm_share   BOOLEAN DEFAULT 1,
    perm_download BOOLEAN DEFAULT 1,
    lock_password BOOLEAN DEFAULT 0,
    commands    TEXT DEFAULT '[]',       -- JSON 数组
    created_at  DATETIME DEFAULT CURRENT_TIMESTAMP
);

-- 分享表
CREATE TABLE shares (
    hash        TEXT PRIMARY KEY,
    path        TEXT NOT NULL,
    user_id     INTEGER NOT NULL,
    expire      INTEGER DEFAULT 0,       -- Unix timestamp, 0=永不过期
    password    TEXT DEFAULT '',         -- bcrypt 哈希
    FOREIGN KEY (user_id) REFERENCES users(id)
);

-- 全局设置表
CREATE TABLE settings (
    key   TEXT PRIMARY KEY,
    value TEXT NOT NULL                  -- JSON 格式存储
);

-- 索引
CREATE INDEX idx_shares_user ON shares(user_id);
CREATE INDEX idx_shares_path ON shares(path);

🔹 存储接口抽象

Go

// storage/storage.go
type Storage struct {
    Users    UsersStore
    Shares   ShareStore
    Settings SettingsStore
}

type UsersStore interface {
    Get(id uint) (*users.User, error)
    GetByUsername(username string) (*users.User, error)
    Gets() ([]*users.User, error)
    Save(user *users.User) error
    Update(user *users.User, fields ...string) error
    Delete(id uint) error
}

type ShareStore interface {
    GetByHash(hash string) (*share.Link, error)
    GetPermanent(path string, userID uint) (*share.Link, error)
    GetByPath(path string) ([]*share.Link, error)
    GetByUserID(userID uint) ([]*share.Link, error)
    Save(link *share.Link) error
    Delete(hash string) error
}

type SettingsStore interface {
    Get() (*settings.Settings, error)
    Save(settings *settings.Settings) error
    GetServer() (*settings.Server, error)
    SaveServer(server *settings.Server) error
}

🔐

认证授权体系设计

安全

🔹 认证方式

FileBrowser 支持多种认证方式，通过策略模式实现可插拔：

🔹 JWT Token 结构

JSON

{
  "header": {
    "alg": "HS256",
    "typ": "JWT"
  },
  "payload": {
    "user": 1,                    // 用户 ID
    "iss": "File Browser",        // 签发者
    "iat": 1700000000,            // 签发时间
    "exp": 1700003600             // 过期时间（默认1小时）
  }
}

🔹 权限模型（RBAC）

Go

// users/permissions.go
type Permissions struct {
    Admin    bool `json:"admin"`     // 管理员（拥有所有权限）
    Execute  bool `json:"execute"`   // 执行命令
    Create   bool `json:"create"`    // 创建文件/目录
    Rename   bool `json:"rename"`    // 重命名
    Modify   bool `json:"modify"`    // 修改/编辑文件内容
    Delete   bool `json:"delete"`    // 删除文件/目录
    Share    bool `json:"share"`     // 创建分享链接
    Download bool `json:"download"`  // 下载文件
}

// 权限检查
func CheckPermission(user *User, action string) bool {
    if user.Perm.Admin {
        return true
    }
    switch action {
    case "create":   return user.Perm.Create
    case "rename":   return user.Perm.Rename
    case "modify":   return user.Perm.Modify
    case "delete":   return user.Perm.Delete
    case "share":    return user.Perm.Share
    case "download": return user.Perm.Download
    case "execute":  return user.Perm.Execute
    default:         return false
    }
}

⚠️

安全提示：

默认管理员账号密码为

admin/admin

，首次部署后务必立即修改密码！建议使用

bcrypt

或更安全的哈希算法存储密码。

📦

第三章：安装部署 — 二进制文件安装

教程

🔹 Linux / macOS 一键安装

Bash

# 官方一键安装脚本
curl -fsSL https://raw.githubusercontent.com/filebrowser/get/master/get.sh | bash

# 指定安装目录
curl -fsSL https://raw.githubusercontent.com/filebrowser/get/master/get.sh | bash -s -- -d /usr/local/bin

# 指定版本安装
curl -fsSL https://raw.githubusercontent.com/filebrowser/get/master/get.sh | bash -s -- -v v2.30.0

🔹 手动下载安装

Bash

# 1. 下载对应平台的压缩包
wget https://github.com/filebrowser/filebrowser/releases/latest/download/linux-amd64-filebrowser.tar.gz

# 2. 解压
tar -xzf linux-amd64-filebrowser.tar.gz

# 3. 移动到系统路径
sudo mv filebrowser /usr/local/bin/
sudo chmod +x /usr/local/bin/filebrowser

# 4. 验证安装
filebrowser version

🔹 Windows 安装

PowerShell

# 使用 winget
winget install filebrowser

# 或手动下载
# 1. 从 GitHub Releases 下载 windows-amd64-filebrowser.zip
# 2. 解压得到 filebrowser.exe
# 3. 添加到系统 PATH 环境变量

🔹 基本启动

Bash

# 最简单启动（当前目录为根目录，默认端口 8080）
filebrowser

# 指定根目录和端口
filebrowser -r /srv/files -p 8080

# 指定数据库路径
filebrowser -r /srv/files -d /etc/filebrowser/filebrowser.db

# 指定监听地址
filebrowser -r /srv/files -a 0.0.0.0 -p 8080

🐳

Docker / Docker Compose 部署

教程

🔹 Docker Run 快速启动

Bash

docker run -d \
  --name filebrowser \
  --restart unless-stopped \
  -p 8080:80 \
  -v /path/to/your/files:/srv \
  -v /path/to/filebrowser.db:/database.db \
  -v /path/to/settings.json:/.filebrowser.json \
  -e PUID=1000 \
  -e PGID=1000 \
  filebrowser/filebrowser:latest

🔹 Docker Compose（推荐）

YAML

# docker-compose.yml
version: '3.8'

services:
  filebrowser:
    image: filebrowser/filebrowser:latest
    container_name: filebrowser
    restart: unless-stopped
    ports:
      - "8080:80"
    volumes:
      # 挂载文件存储目录
      - ./data:/srv
      # 挂载数据库文件（持久化）
      - ./config/filebrowser.db:/database.db
      # 挂载配置文件
      - ./config/settings.json:/.filebrowser.json
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Asia/Shanghai
    # 资源限制
    deploy:
      resources:
        limits:
          memory: 256M
          cpus: '0.5'
    # 健康检查
    healthcheck:
      test: ["CMD", "wget", "--spider", "-q", "http://localhost:80/health"]
      interval: 30s
      timeout: 5s
      retries: 3

  # 可选：搭配 Nginx 反向代理
  nginx:
    image: nginx:alpine
    container_name: nginx
    restart: unless-stopped
    ports:
      - "443:443"
      - "80:80"
    volumes:
      - ./nginx/conf.d:/etc/nginx/conf.d
      - ./nginx/certs:/etc/nginx/certs
    depends_on:
      - filebrowser

💡

多架构支持：

FileBrowser Docker 镜像支持

linux/amd64

、

linux/arm64

、

linux/arm/v7

，Docker 会自动拉取对应架构的镜像，可直接在树莓派上使用。

🔹 Docker 数据备份

Bash

# 备份数据库
docker exec filebrowser cp /database.db /database.db.bak
docker cp filebrowser:/database.db.bak ./backup/filebrowser.db.$(date +%Y%m%d)

# 恢复数据库
docker cp ./backup/filebrowser.db filebrowser:/database.db
docker restart filebrowser

🔨

从源码编译构建

高级

🔹 环境要求

• Go 1.21+
• Node.js 18+ 和 npm/yarn
• Git

🔹 编译步骤

Bash

# 1. 克隆仓库
git clone https://github.com/filebrowser/filebrowser.git
cd filebrowser

# 2. 构建前端
cd frontend
npm install
npm run build
cd ..

# 3. 编译后端（前端产物已通过 go:embed 嵌入）
go build -ldflags="-s -w -X github.com/filebrowser/filebrowser/v2/version.Version=$(git describe --tags)" \
  -o filebrowser .

# 4. 交叉编译示例
# Linux ARM64
GOOS=linux GOARCH=arm64 go build -o filebrowser-linux-arm64 .
# Windows AMD64
GOOS=windows GOARCH=amd64 go build -o filebrowser.exe .
# macOS ARM64 (Apple Silicon)
GOOS=darwin GOARCH=arm64 go build -o filebrowser-darwin-arm64 .

🔧

Systemd 服务配置（生产环境）

配置

🔹 创建服务用户

Bash

# 创建专用用户（无登录权限）
sudo useradd -r -s /sbin/nologin -d /var/lib/filebrowser filebrowser

# 创建必要目录
sudo mkdir -p /etc/filebrowser /var/lib/filebrowser /srv/files
sudo chown -R filebrowser:filebrowser /var/lib/filebrowser /srv/files

# 初始化数据库
sudo -u filebrowser filebrowser config init --database /var/lib/filebrowser/filebrowser.db
sudo -u filebrowser filebrowser config set --database /var/lib/filebrowser/filebrowser.db \
  --address 127.0.0.1 --port 8080 --root /srv/files --log /var/log/filebrowser.log

🔹 Systemd 单元文件

INI

# /etc/systemd/system/filebrowser.service
[Unit]
Description=FileBrowser Web File Manager
Documentation=https://filebrowser.org
After=network.target

[Service]
Type=simple
User=filebrowser
Group=filebrowser
ExecStart=/usr/local/bin/filebrowser --database /var/lib/filebrowser/filebrowser.db
Restart=on-failure
RestartSec=5
TimeoutStopSec=30

# 安全加固
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/srv/files /var/lib/filebrowser
PrivateTmp=true
ProtectKernelTunables=true
ProtectControlGroups=true

# 资源限制
LimitNOFILE=65536
MemoryMax=512M

[Install]
WantedBy=multi-user.target

🔹 启用服务

Bash

sudo systemctl daemon-reload
sudo systemctl enable filebrowser
sudo systemctl start filebrowser
sudo systemctl status filebrowser

# 查看日志
sudo journalctl -u filebrowser -f

📋

第四章：配置详解 — 基础配置

配置

🔹 配置方式

FileBrowser 支持三种配置方式，优先级从高到低：

1. 命令行参数：--port 8080 --root /data
2. 环境变量：FB_PORT=8080 FB_ROOT=/data
3. 配置文件：.filebrowser.json 或数据库存储

🔹 配置文件示例

JSON

{
  "port": 8080,
  "baseURL": "",
  "address": "127.0.0.1",
  "log": "/var/log/filebrowser.log",
  "database": "/etc/filebrowser/filebrowser.db",
  "root": "/srv/files",
  "auth": {
    "method": "json",
    "header": ""
  },
  "defaults": {
    "scope": "/",
    "locale": "zh-cn",
    "viewMode": "mosaic",
    "singleClick": false,
    "sortBy": "name",
    "sortAsc": true,
    "commands": [],
    "perm": {
      "admin": false,
      "execute": false,
      "create": true,
      "rename": true,
      "modify": true,
      "delete": true,
      "share": true,
      "download": true
    }
  }
}

🔹 完整配置项参考

配置项	类型	默认值	说明
port	int	8080	HTTP 监听端口
address	string	0.0.0.0	HTTP 监听地址
baseURL	string	""	子路径部署前缀，如 /files
root	string	.	文件系统根目录
database	string	filebrowser.db	数据库文件路径
log	string	stdout	日志文件路径
auth.method	string	json	认证方式：json/proxy/hook/none
defaults.scope	string	/	新用户默认 Scope
defaults.locale	string	en	默认语言

🔹 CLI 配置命令

Bash

# 查看当前配置
filebrowser config cat -d /path/to/db

# 修改全局配置
filebrowser config set -d /path/to/db \
  --address 0.0.0.0 \
  --port 8080 \
  --root /srv/files \
  --log /var/log/filebrowser.log \
  --auth.method json \
  --locale zh-cn

# 设置 Branding
filebrowser config set -d /path/to/db \
  --branding.name "我的网盘" \
  --branding.files "/branding" \
  --branding.disableExternal

# 设置默认用户 Shell 命令白名单
filebrowser config set -d /path/to/db \
  --commands "git,hugo,npm"

👤

用户管理配置详解

配置

🔹 CLI 用户管理

Bash

# 列出所有用户
filebrowser users ls -d /path/to/db

# 创建新用户
filebrowser users add newuser password123 \
  --perm.admin=false \
  --scope=/home/newuser \
  --locale=zh-cn \
  -d /path/to/db

# 创建管理员
filebrowser users add admin securePass! \
  --perm.admin \
  -d /path/to/db

# 修改用户密码
filebrowser users update admin \
  --password newSecurePass! \
  -d /path/to/db

# 修改用户权限
filebrowser users update john \
  --perm.create=true \
  --perm.delete=false \
  --perm.share=true \
  --scope=/shared/john \
  -d /path/to/db

# 删除用户
filebrowser users rm john -d /path/to/db

# 导入/导出用户
filebrowser users export users.json -d /path/to/db
filebrowser users import users.json -d /path/to/db

🔹 Scope（作用域）机制

Scope 是 FileBrowser 实现用户目录隔离的核心机制。每个用户都有一个 Scope 路径，该用户只能看到和操作其 Scope 目录下的文件。

⚠️

注意：

Scope 路径是相对于全局

root

目录的。例如，如果 root 设为

/srv/files

，用户的 scope 设为

/john

，则该用户实际能访问的是

/srv/files/john

目录。

🎨

品牌定制与主题配置

配置

🔹 Branding 配置

JSON

{
  "branding": {
    "name": "我的云盘",
    "disableExternal": true,
    "theme": "dark",
    "color": "#2563eb",
    "files": "/path/to/branding/assets",
    "customCSS": "body { font-family: 'Noto Sans SC', sans-serif; }",
    "customJS": "console.log('Custom JS loaded');"
  }
}

🔹 自定义静态资源

在 branding files 目录中放置以下文件可替换默认资源：

• logo.svg — 登录页和导航栏 Logo
• favicon.ico — 网站图标
• manifest.json — PWA 清单

🔹 自定义 CSS 示例

CSS

/* 自定义主题色 */
:root {
  --primary: #7c3aed;
  --primary-hover: #6d28d9;
}

/* 自定义登录页背景 */
#login {
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
}

/* 隐藏不需要的元素 */
.shell__prompt { display: none; }

/* 自定义滚动条 */
::-webkit-scrollbar { width: 8px; }
::-webkit-scrollbar-thumb {
  background: rgba(0,0,0,0.2);
  border-radius: 4px;
}

📁

第五章：使用教程 — 文件管理操作

教程

🔹 文件上传

1. 进入目标目录
2. 点击工具栏的 "上传" 按钮或直接将文件 拖拽 到页面
3. 支持多文件选择，显示上传进度条
4. 上传完成后可点击文件名预览

🔹 文件下载

• 单文件下载：选中文件后点击工具栏下载按钮
• 多文件下载：选中多个文件后下载，自动打包为 ZIP
• 文件夹下载：选中文件夹后下载，递归打包为 ZIP

🔹 文件操作快捷键

快捷键	操作
Ctrl + A	全选当前目录所有文件
Delete	删除选中文件
F2	重命名选中文件
Ctrl + C	复制选中文件
Ctrl + X	剪切选中文件
Ctrl + V	粘贴文件到当前目录
Ctrl + F	搜索文件
Esc	取消选择 / 关闭弹窗

🔹 文件预览支持

文件类型	预览方式
图片 (jpg, png, gif, webp, svg)	内建图片查看器，支持缩放和旋转
视频 (mp4, webm, ogg)	HTML5 Video 播放器
音频 (mp3, wav, ogg, flac)	HTML5 Audio 播放器
PDF	内建 PDF 查看器
Markdown	实时渲染预览
代码文件 (js, py, go, html, css...)	语法高亮编辑器
纯文本 (txt, log, csv)	文本查看器/编辑器

🔗

分享功能详细教程

教程

🔹 创建分享链接

选择文件

在文件浏览器中选中要分享的文件或文件夹

点击分享

点击工具栏的 "分享" 按钮（链接图标）

配置分享选项

可选设置：密码保护、过期时间（如24小时、7天、自定义日期）

获取链接

点击 "创建" 后生成唯一哈希链接，可一键复制

🔹 分享链接格式

URL

# 文件分享
https://your-domain.com/share/aB3xYz9K

# 带密码的分享（访问时需要输入密码）
# 文件夹分享（访问者可浏览和下载文件夹内容）
https://your-domain.com/share/fOlDeR_Hash/

🔹 管理分享链接

进入 设置 → 我的分享 页面，可以查看所有已创建的分享链接，支持：

• 查看分享的文件路径、创建时间、过期时间
• 修改分享密码和过期时间
• 删除不再需要的分享链接

✏️

在线编辑器使用

教程

🔹 编辑器功能

• 支持 50+ 种编程语言的语法高亮
• 行号显示、代码折叠
• 搜索替换（Ctrl+H）
• 自动缩进
• 文件编码选择（UTF-8, GBK 等）
• 大文件警告（超过一定大小会提示）

🔹 使用方式

单击文本类文件即可打开在线编辑器。编辑完成后点击 "保存" 按钮或按 Ctrl+S 保存更改。注意：需要用户拥有 Modify 权限才能保存修改。

💡

提示：

编辑器不支持二进制文件编辑。对于大型文件（>10MB），建议使用专业编辑器通过 WebDAV 或其他方式编辑。

💻

Shell 命令执行功能

配置

🔹 功能说明

FileBrowser 提供了受限的 Shell 命令执行功能。管理员可以预定义允许执行的命令列表，用户在文件浏览器中选择一个文件后，可以从下拉列表中选择命令对该文件执行操作。

🔹 配置允许的命令

Bash

# 设置全局可用命令
filebrowser config set -d /path/to/db --commands "git,hugo,convert,ffmpeg"

# 或为特定用户设置可用命令
filebrowser users update username -d /path/to/db --commands "git,convert"

🔹 命令执行原理

当用户执行命令时，FileBrowser 会：

1. 验证用户是否拥有 execute 权限
2. 验证请求的命令是否在白名单中
3. 以用户的 Scope 目录作为工作目录执行命令
4. 将选中的文件路径作为命令参数传入
5. 返回命令的标准输出和错误输出

🚨

安全风险：

命令执行功能存在严重安全风险。生产环境中建议：1) 默认关闭 execute 权限；2) 仅对信任的管理员开启；3) 严格限制白名单命令；4) 考虑使用容器隔离执行环境。

📡

第六章：RESTful API 完整参考

API

🔹 API 端点总览

方法	端点	说明	权限
POST	/api/login	用户登录，获取 JWT	公开
GET	/api/health	健康检查	公开
GET	/api/me	获取当前用户信息	已认证
PUT	/api/me	更新当前用户设置	已认证
GET	/api/resources/{path}	获取文件/目录信息	已认证
POST	/api/resources/{path}	上传文件/创建目录	Create
PUT	/api/resources/{path}	修改文件内容	Modify
DELETE	/api/resources/{path}	删除文件/目录	Delete
PATCH	/api/resources/{path}	移动/重命名	Rename
GET	/api/shares	获取分享列表	已认证
POST	/api/shares	创建分享	Share
GET	/api/users	用户列表	Admin
GET	/api/settings	全局设置	Admin

🔑

认证 API 详细说明

API

🔹 登录接口

HTTP

POST /api/login
Content-Type: application/json

{
  "username": "admin",
  "password": "your_password"
}

# 成功响应 200
# 响应体直接返回 JWT 字符串（纯文本）
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

# 失败响应 403
Forbidden

🔹 使用 Token 认证后续请求

Bash

# 获取 Token
TOKEN=$(curl -s -X POST http://localhost:8080/api/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin"}')

# 使用 Token 请求
curl -H "X-Auth: $TOKEN" http://localhost:8080/api/me

# 列出文件
curl -H "X-Auth: $TOKEN" http://localhost:8080/api/resources/

📄

文件资源 API 详细说明

API

🔹 获取目录列表

Bash

# GET /api/resources/{path}?content=true
curl -H "X-Auth: $TOKEN" \
  "http://localhost:8080/api/resources/?content=true"

# 响应 JSON
{
  "path": "/",
  "name": "",
  "size": 4096,
  "isDir": true,
  "modified": "2024-01-15T10:30:00Z",
  "items": [
    {
      "path": "/documents",
      "name": "documents",
      "size": 4096,
      "isDir": true,
      "modified": "2024-01-14T08:00:00Z"
    },
    {
      "path": "/readme.md",
      "name": "readme.md",
      "size": 2048,
      "isDir": false,
      "type": "text/markdown",
      "modified": "2024-01-15T09:00:00Z"
    }
  ],
  "numDirs": 1,
  "numFiles": 1
}

🔹 上传文件

Bash

# 上传单个文件
curl -X POST -H "X-Auth: $TOKEN" \
  -F "file=@/local/path/to/file.pdf" \
  "http://localhost:8080/api/resources/uploads/"

# 覆盖已有文件
curl -X POST -H "X-Auth: $TOKEN" \
  -H "X-Overwrite: true" \
  -F "file=@/local/path/to/file.pdf" \
  "http://localhost:8080/api/resources/uploads/file.pdf"

# 创建目录
curl -X POST -H "X-Auth: $TOKEN" \
  -H "Content-Type: application/json" \
  "http://localhost:8080/api/resources/new-folder/?action=mkdir"

🔹 下载文件

Bash

# 下载单个文件
curl -H "X-Auth: $TOKEN" -o output.pdf \
  "http://localhost:8080/api/resources/documents/file.pdf?download=true"

# 下载为 ZIP
curl -H "X-Auth: $TOKEN" -o archive.zip \
  "http://localhost:8080/api/resources/documents/?algo=zip"

# 下载为 tar.gz
curl -H "X-Auth: $TOKEN" -o archive.tar.gz \
  "http://localhost:8080/api/resources/documents/?algo=tar.gz"

🔹 删除、移动、重命名

Bash

# 删除文件
curl -X DELETE -H "X-Auth: $TOKEN" \
  "http://localhost:8080/api/resources/old-file.txt"

# 批量删除
curl -X DELETE -H "X-Auth: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"paths":["/file1.txt","/file2.txt"]}' \
  "http://localhost:8080/api/resources/"

# 重命名 / 移动
curl -X PATCH -H "X-Auth: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"destination":"/new-path/file.txt","action":"rename"}' \
  "http://localhost:8080/api/resources/old-file.txt"

# 复制
curl -X PATCH -H "X-Auth: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"destination":"/backup/file.txt","action":"copy"}' \
  "http://localhost:8080/api/resources/file.txt"

🪝

Webhook 事件通知

API

🔹 支持的 Webhook 事件

事件名称	触发时机
save	文件保存/修改后
upload	文件上传完成后
delete	文件删除后
rename	文件重命名后
copy	文件复制后

🔹 Webhook 配置

JSON

{
  "commands": [
    {
      "name": "after-upload",
      "events": ["upload"],
      "command": "/usr/local/bin/process-upload.sh {{ .Scope }} {{ .Path }}",
      "description": "上传后自动处理文件"
    },
    {
      "name": "notify-delete",
      "events": ["delete"],
      "command": "curl -X POST https://hooks.example.com/notify -d 'File deleted: {{ .Path }}'",
      "description": "删除文件时发送通知"
    }
  ]
}

🔹 模板变量

• {{ .Scope }} — 用户根目录
• {{ .Path }} — 文件相对路径
• {{ .Username }} — 操作用户名
• {{ .Event }} — 事件类型

🛡️

第七章：安全加固指南

安全

🔹 安全检查清单

🔒

部署前必做：

✅ 修改默认管理员密码

✅ 使用 HTTPS (TLS 加密)

✅ 绑定 127.0.0.1 + Nginx 反代（不直接暴露端口）

✅ 关闭不必要的用户权限（特别是 execute）

✅ 配置 Systemd 安全沙箱

✅ 定期备份数据库

✅ 设置强密码策略

✅ 配置防火墙规则

✅ 启用访问日志

🔹 密码安全

Bash

# 生成强密码
openssl rand -base64 24

# 使用 htpasswd 生成 bcrypt 哈希
htpasswd -nbBC 12 "" "your-strong-password" | tr -d ':\n'

# 通过 CLI 更新密码
filebrowser users update admin --password "新强密码" -d /path/to/db

🔹 文件路径遍历防护

FileBrowser 内置了路径遍历防护机制，防止用户通过 ../../../etc/passwd 等方式访问 Scope 之外的文件。系统会：

• 对所有路径进行 filepath.Clean() 规范化
• 验证规范化后的路径是否仍在用户 Scope 范围内
• 拒绝包含符号链接指向 Scope 外部的路径（可配置）

🔹 Rate Limiting（限流）

建议在 Nginx 层配置请求限流，防止暴力破解和 DDoS：

Nginx

# 定义限流区域
limit_req_zone $binary_remote_addr zone=login:10m rate=5r/m;
limit_req_zone $binary_remote_addr zone=api:10m rate=60r/m;

# 对登录接口严格限流
location /api/login {
    limit_req zone=login burst=3 nodelay;
    proxy_pass http://127.0.0.1:8080;
}

# 对 API 接口适度限流
location /api/ {
    limit_req zone=api burst=20 nodelay;
    proxy_pass http://127.0.0.1:8080;
}

🌐

Nginx 反向代理配置

配置

🔹 完整 Nginx 配置

Nginx

# /etc/nginx/sites-available/filebrowser
upstream filebrowser_backend {
    server 127.0.0.1:8080;
    keepalive 32;
}

# HTTP -> HTTPS 重定向
server {
    listen 80;
    listen [::]:80;
    server_name files.example.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    server_name files.example.com;

    # SSL 配置
    ssl_certificate     /etc/letsencrypt/live/files.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/files.example.com/privkey.pem;
    ssl_protocols       TLSv1.2 TLSv1.3;
    ssl_ciphers         HIGH:!aNULL:!MD5;
    ssl_prefer_server_ciphers on;
    ssl_session_cache   shared:SSL:10m;
    ssl_session_timeout 10m;

    # HSTS
    add_header Strict-Transport-Security "max-age=63072000" always;
    add_header X-Content-Type-Options nosniff;
    add_header X-Frame-Options DENY;
    add_header X-XSS-Protection "1; mode=block";

    # 上传大小限制
    client_max_body_size 10G;

    # 日志
    access_log /var/log/nginx/filebrowser_access.log;
    error_log  /var/log/nginx/filebrowser_error.log;

    # 主应用
    location / {
        proxy_pass http://filebrowser_backend;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # WebSocket 支持
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        # 超时设置
        proxy_connect_timeout 60s;
        proxy_send_timeout 600s;
        proxy_read_timeout 600s;

        # 禁用缓冲（大文件下载）
        proxy_buffering off;
        proxy_request_buffering off;
    }
}

🔒

HTTPS / TLS 证书配置

安全

🔹 Let's Encrypt 免费证书

Bash

# 安装 Certbot
sudo apt install certbot python3-certbot-nginx

# 获取证书（Nginx 模式）
sudo certbot --nginx -d files.example.com

# 手动模式
sudo certbot certonly --standalone -d files.example.com

# 自动续期测试
sudo certbot renew --dry-run

# Certbot 会自动配置 Nginx 并设置定时续期任务

🔹 Caddy 自动 HTTPS（最简方案）

Caddyfile

# Caddyfile - 仅需 4 行即可实现 HTTPS
files.example.com {
    reverse_proxy localhost:8080
}

# 启动 Caddy
caddy run --config /path/to/Caddyfile

🎯

推荐：

对于个人或小团队使用，Caddy 是最简单的 HTTPS 方案——自动获取和续期 Let's Encrypt 证书，无需任何额外配置。

💾

备份与灾难恢复策略

运维

🔹 需要备份的数据

数据	位置	说明
数据库	filebrowser.db	用户、权限、分享链接、设置
用户文件	root 目录	用户上传的所有文件
配置文件	.filebrowser.json	全局配置（如有）
品牌资源	branding 目录	自定义 Logo、CSS 等

🔹 自动备份脚本

Bash

#!/bin/bash
# /opt/scripts/backup-filebrowser.sh

BACKUP_DIR="/backup/filebrowser"
DATE=$(date +%Y%m%d_%H%M%S)
DB_PATH="/var/lib/filebrowser/filebrowser.db"
FILES_PATH="/srv/files"

mkdir -p "$BACKUP_DIR"

# 1. 备份数据库（SQLite 安全备份）
sqlite3 "$DB_PATH" ".backup '$BACKUP_DIR/filebrowser_$DATE.db'"

# 2. 备份配置文件
cp /etc/filebrowser/.filebrowser.json "$BACKUP_DIR/config_$DATE.json"

# 3. 备份用户文件（增量备份，使用 rsync）
rsync -a --delete "$FILES_PATH/" "$BACKUP_DIR/files/"

# 4. 压缩归档
tar -czf "$BACKUP_DIR/backup_$DATE.tar.gz" \
  "$BACKUP_DIR/filebrowser_$DATE.db" \
  "$BACKUP_DIR/config_$DATE.json"

# 5. 清理 30 天前的备份
find "$BACKUP_DIR" -name "backup_*.tar.gz" -mtime +30 -delete
find "$BACKUP_DIR" -name "filebrowser_*.db" -mtime +30 -delete
find "$BACKUP_DIR" -name "config_*.json" -mtime +30 -delete

echo "Backup completed: $DATE"

🔹 Cron 定时任务

Cron

# 每天凌晨 3 点执行备份
0 3 * * * /opt/scripts/backup-filebrowser.sh >> /var/log/fb-backup.log 2>&1

📊

监控与日志管理

运维

🔹 日志配置

Bash

# 配置日志文件输出
filebrowser config set -d /path/to/db --log /var/log/filebrowser.log

# 日志格式示例
2024/01/15 10:30:45 /api/resources/: 200 192.168.1.100 GET /files/
2024/01/15 10:30:46 /api/login: 200 192.168.1.100 POST
2024/01/15 10:30:50 /api/resources/file.pdf: 200 192.168.1.100 GET

🔹 Logrotate 配置

Config

# /etc/logrotate.d/filebrowser
/var/log/filebrowser.log {
    daily
    missingok
    rotate 30
    compress
    delaycompress
    notifempty
    create 0640 filebrowser filebrowser
    sharedscripts
    postrotate
        systemctl reload filebrowser > /dev/null 2>&1 || true
    endscript
}

🔹 健康检查端点

Bash

# 健康检查（无需认证）
curl -s http://localhost:8080/api/health
# 响应: {"status": "ok"}

# 结合监控工具（Prometheus + Blackbox Exporter）
# 配置探针检查此端点的可用性和响应时间

👥

第八章：高级功能 — 多用户权限体系

高级

🔹 典型多用户场景配置

以下示例展示如何为一个小型团队配置文件共享系统：

Bash

# 1. 设置全局根目录
filebrowser config set -d /srv/filebrowser.db --root /srv/shared

# 2. 创建管理员
filebrowser users add admin SuperSecure!123 --perm.admin -d /srv/filebrowser.db

# 3. 创建普通用户（只能访问自己的目录）
filebrowser users add alice alice123 --scope=/alice -d /srv/filebrowser.db
filebrowser users add bob bob123 --scope=/bob -d /srv/filebrowser.db

# 4. 创建共享只读用户
filebrowser users add viewer viewer123 \
  --scope=/public \
  --perm.create=false \
  --perm.delete=false \
  --perm.modify=false \
  --perm.rename=false \
  --perm.download=true \
  -d /srv/filebrowser.db

# 5. 创建对应目录
mkdir -p /srv/shared/{alice,bob,public}
chown -R www-data:www-data /srv/shared

🔹 权限矩阵

用户角色	上传	下载	删除	编辑	分享	命令
管理员 (Admin)	✅	✅	✅	✅	✅	✅
普通用户	✅	✅	✅	✅	✅	❌
只读用户	❌	✅	❌	❌	❌	❌
上传专用	✅	❌	❌	❌	❌	❌

🧩

自定义扩展与集成

高级

🔹 SSO 集成（Proxy Auth）

Nginx + Lua

# Nginx + Authelia 集成示例
server {
    # ... SSL 配置 ...

    # Authelia 认证
    location /authelia {
        internal;
        proxy_pass http://authelia:9091/api/verify;
        proxy_set_header X-Original-URL $scheme://$http_host$request_uri;
    }

    # FileBrowser
    location / {
        auth_request /authelia;
        auth_request_set $user $upstream_http_remote_user;

        # 将认证用户传递给 FileBrowser
        proxy_set_header X-Forwarded-User $user;
        proxy_pass http://127.0.0.1:8080;
    }
}

然后配置 FileBrowser 使用 Proxy 认证：

Bash

filebrowser config set -d /path/to/db \
  --auth.method=proxy \
  --auth.header="X-Forwarded-User"

🔹 API 脚本自动化

Python

import requests

BASE_URL = "https://files.example.com"

class FileBrowserAPI:
    def __init__(self, base_url, username, password):
        self.base_url = base_url
        self.token = self.login(username, password)

    def login(self, username, password):
        resp = requests.post(f"{self.base_url}/api/login",
                           json={"username": username, "password": password})
        resp.raise_for_status()
        return resp.text

    @property
    def headers(self):
        return {"X-Auth": self.token}

    def list_files(self, path="/"):
        resp = requests.get(f"{self.base_url}/api/resources{path}",
                          headers=self.headers)
        return resp.json()

    def upload_file(self, local_path, remote_dir="/"):
        with open(local_path, "rb") as f:
            resp = requests.post(
                f"{self.base_url}/api/resources{remote_dir}",
                headers=self.headers,
                files={"file": f}
            )
        return resp.status_code == 200

    def create_share(self, path, password=None, expires=None):
        data = {"path": path}
        if password: data["password"] = password
        if expires: data["expires"] = expires
        resp = requests.post(f"{self.base_url}/api/shares",
                           headers=self.headers, json=data)
        return resp.json()

# 使用示例
fb = FileBrowserAPI(BASE_URL, "admin", "password")
files = fb.list_files("/documents")
fb.upload_file("/local/report.pdf", "/reports/")

🚀

性能优化最佳实践

高级

🔹 文件系统优化

• 使用 SSD 存储用户文件，提升 I/O 性能
• 对于大量小文件场景，考虑使用 ext4 或 XFS 文件系统
• 挂载选项建议：noatime,nodiratime 减少元数据写入
• 大文件传输时确保网络带宽充足

🔹 Nginx 优化

Nginx

# 开启 gzip 压缩（减少 API 响应体积）
gzip on;
gzip_types application/json text/css application/javascript;
gzip_min_length 1024;

# 静态资源缓存
location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff2)$ {
    expires 30d;
    add_header Cache-Control "public, immutable";
}

# 增加并发连接数
worker_connections 4096;
keepalive_timeout 65;

🔹 数据库优化

• SQLite: 启用 WAL 模式 (PRAGMA journal_mode=WAL;)
• SQLite: 定期执行 VACUUM 压缩数据库
• 大量用户场景考虑迁移至 PostgreSQL

❓

第九章：常见问题（FAQ）

帮助

Q: 忘记密码怎么办？

A: 通过 CLI 重置管理员密码：

Bash

filebrowser users update admin --password "新密码" -d /path/to/filebrowser.db

Q: 上传大文件超时？

A: 需要在多个层面调整：

• Nginx: 增加 client_max_body_size、proxy_read_timeout、proxy_send_timeout
• FileBrowser: 本身没有文件大小限制，瓶颈通常在前端代理
• 网络：确保上行带宽充足

Q: 如何迁移数据库？

A: FileBrowser 支持从 BoltDB 迁移到 SQLite：

Bash

filebrowser upgrade --old /path/to/bolt.db --new /path/to/sqlite.db

Q: 如何实现文件同步？

A: FileBrowser 不提供文件同步功能。可配合以下工具：

• Syncthing — P2P 文件同步
• rclone — 命令行同步工具，支持多种存储后端
• rsync — 经典增量同步

Q: 如何限制用户磁盘配额？

A: FileBrowser 原生不支持磁盘配额。可通过以下方式实现：

• Linux 文件系统配额（quota）
• 为每个用户使用独立的 LVM 逻辑卷
• 使用 ZFS dataset 设置配额

🔍

故障排除手册

运维

🔹 启动失败排查

Bash

# 1. 检查端口占用
ss -tlnp | grep 8080
lsof -i :8080

# 2. 检查文件权限
ls -la /var/lib/filebrowser/filebrowser.db
ls -la /srv/files/

# 3. 检查数据库完整性
sqlite3 /var/lib/filebrowser/filebrowser.db "PRAGMA integrity_check;"

# 4. 查看系统日志
journalctl -u filebrowser --since "10 minutes ago"

# 5. 前台运行查看错误
filebrowser -d /path/to/db --log stdout

🔹 常见错误对照表

错误现象	可能原因	解决方案
502 Bad Gateway	FileBrowser 未运行或端口不匹配	检查服务状态和端口配置
413 Request Entity Too Large	Nginx 上传大小限制	增加 client_max_body_size
403 Forbidden	用户权限不足	检查用户 Scope 和权限配置
database is locked	SQLite 并发写入冲突	启用 WAL 模式或迁移数据库
permission denied	文件系统权限不足	检查文件目录的 owner 和 chmod
CORS error	跨域配置问题	检查 baseURL 和代理配置

📝

版本更新日志与路线图

信息

🔹 版本历史

版本	时间	主要变更
v2.30.x	2024	安全修复、依赖更新、Bug 修复
v2.27.x	2024	改进文件预览、性能优化
v2.25.x	2023	Vue 3 迁移、UI 重构
v2.23.x	2023	Go 1.21、SQLite 默认存储
v2.20.x	2022	暗色模式、国际化改进
v2.0.0	2019	项目重命名为 FileBrowser、架构重构

🔹 升级指南

Bash

# 1. 备份数据库
cp filebrowser.db filebrowser.db.bak

# 2. 停止服务
sudo systemctl stop filebrowser

# 3. 替换二进制文件
sudo wget -O /usr/local/bin/filebrowser \
  https://github.com/filebrowser/filebrowser/releases/latest/download/linux-amd64-filebrowser.tar.gz

# 4. 数据库迁移（如有需要）
filebrowser upgrade -d /path/to/filebrowser.db

# 5. 重启服务
sudo systemctl start filebrowser

🎉

感谢阅读！

本指南涵盖了 FileBrowser 从架构设计到生产部署的完整知识体系。如有问题，请参考官方 GitHub Issues 和 Discussions 获取社区支持。

🔍

未找到匹配内容

尝试使用不同的关键词搜索

FileBrowser 完整架构设计与教程指南 · 基于 FileBrowser v2.x · 文档持续更新中

📖 官方文档：filebrowser.org · 💻 GitHub：filebrowser/filebrowser