# local-file-system

**Repository Path**: xiaomans/local-file-system

## Basic Information

- **Project Name**: local-file-system
- **Description**: 局域网本地文件系统
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-16
- **Last Updated**: 2026-10-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Local File System



一个面向局域网的轻量本地文件浏览与预览服务。将可执行文件放在需要共享的目录中启动，即可让同一局域网设备通过浏览器访问文档、网页、代码和媒体文件；文件始终保留在本机，不需要上传到第三方平台。

## 功能概览

![Local File System 项目封面](images/README/local-file-system-hero.svg)



- 浏览目录并下载文件，支持电脑右键和手机长按操作菜单。
- 预览 Markdown、TXT、HTML、CSS、SQL、JSON、XML、YAML、Python、Java、JavaScript 等常见文本与代码文件。
- Markdown 支持标题目录、代码高亮、`==橘黄色高亮==`、Mermaid 流程图、图片双击放大和代码一键复制。
- HTML 保留原始布局、样式和交互，仅叠加隔离的返回按钮与代码复制工具。
- 支持图片、PDF、音频、视频的浏览器原生预览。
- 支持局域网受限分享、移动端阅读、目录宽度拖动和阅读进度回到顶部；预览页顶部提供项目开源地址。
- Windows / Linux 均提供后台启动和停止脚本；启动时打印本机与全部局域网 IPv4 访问地址。

## 系统结构

```mermaid
flowchart TB
    Client["电脑或手机浏览器"] -->|"HTTP / 局域网"| Server["Local File System 服务"]

    subgraph HTTP["HTTP 接口层"]
        Router["请求处理器"]
        Pages["目录 / 阅读 / 媒体页面"]
        Assets["本地 CSS / JavaScript / Mermaid"]
    end

    subgraph Application["应用层"]
        Preview["预览用例"]
        Download["下载用例"]
    end

    subgraph Domain["领域层"]
        Model["文档值对象与类型"]
        Port["文件仓储与渲染端口"]
    end

    subgraph Infrastructure["基础设施层"]
        FileSystem["本地文件系统"]
        Renderer["Markdown / 文本 / 代码渲染器"]
        Network["局域网 IPv4 发现"]
        Log["轮转日志"]
    end

    Server --> Router
    Router --> Pages
    Router --> Assets
    Router --> Preview
    Router --> Download
    Preview --> Model
    Preview --> Port
    Download --> Port
    Port --> FileSystem
    Preview --> Renderer
    Server --> Network
    Server --> Log
```

## 技术栈与架构

| 分类 | 技术与方案 | 作用 |
| --- | --- | --- |
| 运行时 | Python 3.10+ | 轻量单进程服务运行环境 |
| HTTP 服务 | `http.server`、`socketserver` | 提供目录浏览、文件传输、预览与受限分享接口 |
| 架构模型 | DDD 领域驱动设计 | 按 `domain`、`application`、`infrastructure`、`interfaces` 分层，隔离业务规则、用例、文件系统实现与 HTTP 页面适配 |
| 领域模型 | `Document`、`DirectoryEntry`、`ShareLink` | 表达文件、目录、分享令牌、期限及下载权限等核心概念 |
| Markdown | `Markdown`、`Pygments` | Markdown 转换、代码块高亮和文本阅读体验 |
| 流程图 | Mermaid 浏览器资源 | 在 Markdown 预览中渲染流程图与架构图 |
| 前端 | 原生 HTML、CSS、JavaScript | 无前端构建依赖，提供目录、目录树、代码复制、图片预览、分享和下载交互 |
| 安全边界 | 根目录路径校验、随机分享令牌、私有分享模式 | 防止越界文件访问，并将局域网访问限制到已分享的文件或文件夹范围 |
| 日志 | `logging`、`RotatingFileHandler` | 控制台与本地滚动日志输出 |
| 打包发布 | PyInstaller | 在 Windows 打包为 `.exe`，在 Linux 打包为原生可执行文件 |

DDD 分层职责：

```text
domain/          文档、分享链接、领域错误、端口协议
application/     预览、下载、分享创建与批量删除等用例
infrastructure/  本地文件系统、JSON 分享记录、渲染器、配置、日志与网络发现
interfaces/http/ HTTP 路由、响应、页面模板、离线 CSS 和 JavaScript
bootstrap.py     组合根：装配各层实现并启动 HTTP 服务
```

## 快速开始

### 1. 打包

在目标操作系统中执行。PyInstaller 不跨平台打包：Windows 产出 Windows EXE，Linux 产出 Linux ELF。

Windows：

```powershell
python -m pip install -r requirements.txt pyinstaller
python -m PyInstaller --onefile --console --name html_server --collect-submodules markdown --collect-submodules pygments --collect-data local_preview html_server.py
```

Linux：

```bash
python3 -m pip install -r requirements.txt pyinstaller
python3 -m PyInstaller --onefile --console --name html_server --collect-submodules markdown --collect-submodules pygments --collect-data local_preview html_server.py
```

产物为 Windows 的 `dist/html_server.exe` 或 Linux 的 `dist/html_server`。

### 2. 配置与启动

启动脚本开头集中放置配置项：

| 变量 | 默认值 | 说明 |
| --- | --- | --- |
| `PORT` | `8000` | 服务端口 |
| `BIND_HOST` | `0.0.0.0` | 监听地址，允许局域网访问 |
| `PROGRAM` | `./dist/html_server` | 打包可执行文件路径 |
| `DOCUMENT_DIR` | `.` | 需要共享浏览的目录 |
| `LOG_DIR` | `.` | 服务日志目录 |

Windows 双击 `start_server.cmd`，Linux 执行：

```bash
bash start_server.sh
```

Windows 会在控制台显示本机地址与全部局域网 IPv4 地址，并等待回车后关闭启动窗口；服务继续在后台运行。Linux 会打印同样信息后结束脚本，服务由 `nohup` 保持后台运行。

例如：

```text
本机访问：http://127.0.0.1:8000/
局域网访问：http://192.168.1.20:8000/
```

### 3. 停止服务

Windows 双击 `stop_server.cmd`；Linux 执行：

```bash
bash stop_server.sh
```

停止脚本会按可执行文件完整路径与端口匹配进程，避免仅按端口或名称结束其他服务。停止脚本开头的 `PORT`、`PROGRAM` 需要和启动时保持一致。

## 文件预览能力

| 类型 | 示例 | 展示方式 |
| --- | --- | --- |
| 文档 | `.md`、`.txt`、`.log` | 阅读排版、标题目录、代码复制 |
| 网页 | `.html`、`.htm` | 原样显示，保留页面样式与交互 |
| 代码 | `.css`、`.sql`、`.json`、`.xml`、`.yaml`、`.py`、`.java`、`.js` | 语法高亮与下载 |
| 图片 | `.png`、`.jpg`、`.gif`、`.webp`、`.svg` | 原生预览与放大 |
| 媒体 | `.pdf`、`.mp3`、`.mp4`、`.webm` | 浏览器原生控件 |
| 其他 | Office、压缩包、未知二进制 | 下载后使用本地程序打开 |

## 受限分享

- 文件和文件夹均可创建分享链接；文件夹链接仅允许浏览该文件夹及其子文件夹。
- 可创建永久链接或 1 小时、24 小时、7 天的临时链接，并可单独开启下载权限。
- `share_mode=private` 时，局域网设备只能访问有效分享链接；本机通过 `127.0.0.1` 管理完整目录。
- 分享页面在文件夹范围内保留“返回上级”导航，不会跳出已分享的文件夹范围。
- 右上角“分享列表”仅限本机访问，支持勾选多条链接批量删除；删除后立即失效。
- 预览页和分享页顶部均显示 [开源 Local File System](https://gitee.com/xiaomans/local-file-system)。

## 项目结构

```text
html_server.py                  程序入口
local_preview/
  bootstrap.py                  组合根
  domain/                       文档模型、端口和异常
  application/                  预览与下载用例
  infrastructure/               文件系统、渲染、网络、日志、配置
  interfaces/http/              HTTP 处理、页面模板与离线静态资源
tests/                          单元测试
examples/                       演示文件
start_server.cmd / .sh          Windows / Linux 后台启动
stop_server.cmd / .sh           Windows / Linux 后台停止
```

## 源码运行

需要 Python 3.10+：

```powershell
python -m pip install -r requirements.txt
python html_server.py --config server_config.json
```

`server_config.json` 支持配置端口、监听地址、共享目录、日志目录、文本预览大小上限和 `share_mode`。命令行参数（含 `--share-mode open|private`）优先于配置文件；未配置时默认使用 `private`。

## 日志与安全边界

- 服务日志位于 `LOG_DIR/html_server_<端口>.log`，单文件达到 5 MB 后轮转，保留 3 份历史文件。
- 服务仅允许访问配置的共享目录及其内部文件，目录跳转不会越过根目录。
- 分享链接只在当前局域网中可用，不会将文件上传或自动发送给任何人。
- `share_mode` 可设为 `open` 或 `private`，默认及启动脚本均使用 `private`：本机使用 `127.0.0.1` 管理全部文件，局域网设备只能通过受限分享链接查看指定文件，不能直接浏览 `IP:8000` 的目录。
- 文件和文件夹均可点击“分享”。文件夹分享链接可浏览该文件夹及其全部子文件夹，可在该分享文件夹范围内返回上级，但不能访问文件夹外的内容。
- 点击“分享”可选择永久有效或 1 小时、24 小时、7 天的临时链接，并可单独控制是否允许下载。有效令牌记录在本机 `share_links.json`，该文件不会提交到仓库。右上角“分享列表”仅允许在本机查看，可勾选多条记录批量删除；删除后链接立即失效。
- 请在受信任的局域网使用；如无法访问，检查系统防火墙入站规则与路由器设备隔离设置。

## 开源许可

MIT License