# pfs

**Repository Path**: archx/pfs

## Basic Information

- **Project Name**: pfs
- **Description**: 便携式文件服务器， 使用 Gemini 生成
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-14
- **Last Updated**: 2026-04-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 便携式文件服务器 (PFS)

一个用 Rust 编写的简单、轻量级、跨平台的 HTTP 文件服务器。

## ✨ 功能特性

-   **文件和目录服务**: 轻松共享指定目录下的所有文件和子目录。
-   **自动生成目录列表**: 当访问一个目录时，PFS 会在浏览器中生成一个可点击的 HTML 列表。
-   **UTF-8 字符支持**: 正确处理和显示包含中文、空格及特殊字符的文件名和路径。
-   **智能字符集**: 自动为文本类文件（如 `.txt`, `.html`, `.rs`）的 HTTP 响应头添加 `charset=utf-8`，避免浏览器乱码。
-   **跨平台**: 可在 Windows, macOS, Linux 上编译和运行。
-   **命令行配置**: 通过命令行参数轻松指定端口和共享目录。

## 🚀 快速开始

### 1. 构建

确保你已经安装了 Rust 环境。

```bash
# 克隆项目 (如果需要)
# git clone <repository-url>
# cd pfs

# 构建 Release 版本的可执行文件
cargo build --release
```

构建完成后，可执行文件会位于 `./target/release/pfs`。

### 2. 运行

将可执行文件（例如 `pfs.exe` 或 `pfs`）复制到你希望的位置。

#### 默认用法

直接运行，它会共享当前目录，并监听 `8099` 端口。

```bash
./pfs
```

输出:
```
🚀 PFS 启动成功!
监听地址: http://0.0.0.0:8099
共享目录: /path/to/current/directory
```

现在，你可以在浏览器中打开 `http://127.0.0.1:8099` 来浏览文件。

#### 自定义端口和目录

使用 `-p` (或 `--port`) 和 `-d` (或 `--dir`) 参数来指定端口和要共享的目录。

```bash
# 在 8080 端口共享 /home/user/documents 目录
./pfs -p 8080 -d /home/user/documents

# 在 9000 端口共享 D:\Downloads 目录 (Windows)
./pfs.exe --port 9000 --dir "D:\Downloads"
```

## 🛠️ 命令行选项

| 短选项 | 长选项    | 默认值 | 描述               |
| ------ | --------- | ------ | ------------------ |
| `-p`   | `--port`  | `8099` | 指定服务器监听的端口 |
| `-d`   | `--dir`   | `.`    | 指定要共享的根目录   |

## 📝 代码解读

本项目基于 Axum Web 框架构建，核心逻辑如下：

1.  **`main.rs`**:
    -   **命令行解析**: 使用 `clap` 库解析 `--port` 和 `--dir` 参数。
    -   **路径处理**: 获取共享目录的绝对路径，并检查其是否存在。
    -   **服务配置**:
        -   使用 `tower_http::services::ServeDir` 作为主要服务。它能高效地处理静态文件请求。
        -   设置一个 `fallback` 处理器 `render_dir`。当 `ServeDir` 找不到文件或请求路径是目录时，请求将被转发到 `render_dir`。
    -   **中间件 (`fix_charset`)**: 添加一个中间件来拦截所有响应。如果响应是文本类型 (`text/*`) 且没有指定字符集，它会自动添加 `charset=utf-8`，解决了浏览器查看文本文件时的乱码问题。
    -   **服务器启动**: 绑定指定地址和端口，启动 `tokio` 异步运行时和 `axum` 服务器。

2.  **`render_dir` 函数**:
    -   当用户访问一个目录时，此函数被调用。
    -   它会异步读取目录下的所有文件和子目录。
    -   动态生成一个 HTML 页面，其中包含所有条目的列表。
    -   为每个条目生成一个链接，并用 `📁` 和 `📄` 图标区分目录和文件。
    -   支持 "返回上一级" 的功能。
    -   通过 `percent_decode_str` 对 URL 路径进行解码，确保包含中文、空格等特殊字符的路径能够被正确映射到文件系统。

3.  **`fix_charset` 中间件**:
    -   这是一个 `map_response` 中间件，用于在响应发送给客户端之前对其进行修改。
    -   它检查 `Content-Type` 响应头，如果内容是文本类型但缺少 `charset` 定义，则自动补充 `charset=utf-8`。