内容
# 本地 HTTP 文件服务器
使用 [Bun](https://bun.sh) 构建的轻量级 HTTP 文件服务器，动态注册本地目录。每个文件夹都获得一个唯一的 URL 别名，并可以通过基于路径的路由和基于子域的访问方式访问。
> **完全由 LLM 生成** — 项目中的每一行代码都由 [Qwen3.6-27B](https://qwen.ai) 编写。没有人类编写的源代码。
## 功能
- **运行时文件夹注册** — 添加、删除和更新服务目录，无需重启
- **基于别名的路由** — 自动 URL 安全别名（`/documents-a3k9xZ/`）或自定义别名
- **子域访问** — 通过 `slug.localhost` 提供服务，此外还支持基于路径的 URL
- **CRUD API** — 用于管理文件夹注册的完整 JSON API（`GET`、`POST`、`PUT`、`DELETE`）
- **文件服务** — 自动 MIME 检测、范围请求（206）、ETags 和条件响应（304）
- **目录列表** — HTML 目录浏览，带有父链接和文件大小
- **仪表盘 UI** — 自包含的 HTML 接口，用于可视化管理
- **MCP stdio 服务器** — `--mcp stdio` 模式，用于通过模型上下文协议与 AI 代理集成
- **可选持久性** — 通过磁盘上的 `registry.json` 生存重启
- **路径遍历保护** — 解析路径验证为注册文件夹根目录
- **最小依赖** — 仅 `@modelcontextprotocol/sdk` 和 `zod`
## AI 代理
该项目包含一个 [SKILL.md](SKILL.md) 文件，帮助 AI 代理使用 HTTP API 提供目录服务、预览构建和调试 Web 应用程序。将它复制到代理的技能目录中或直接引用。
## 快速入门
```bash
# 安装依赖（仅类型定义）
bun install
# 启动服务器
bun run src/index.ts
# 或启用持久性
PERSIST=true bun run src/index.ts
# 自定义端口
PORT=3000 bun run src/index.ts
# MCP stdio 模式（用于 AI 代理）
bun run src/index.ts --mcp stdio
```
服务器默认在 `http://0.0.0.0:6868` 启动。
## 构建
编译一个独立的可执行文件 — 目标机器上不需要安装 Bun：
```bash
# 当前平台（原生）
bun run build
# 特定平台
bun run build:linux-x64
bun run build:linux-arm64
bun run build:windows-x64
bun run build:darwin-x64
bun run build:darwin-arm64
# 所有平台一次构建
bun run build:all
```
输出文件位于 `dist/`，带有平台后缀（例如 `dist/local-http-fs-server-0.1.0-linux-x64`）。Windows 构建自动追加 `.exe`。
## 使用
### 注册文件夹
```bash
curl -X POST http://localhost:6868/ \
-H 'Content-Type: application/json' \
-d '{"folder_path": "/home/user/documents"}'
```
响应：
```json
{
"status": "success",
"message": "文件夹 'documents-a3k9xZ' 注册在 '/home/user/documents'。现在提供文件服务。",
"data": {
"slug": "documents-a3k9xZ",
"path": "/home/user/documents",
"url": "http://localhost:6868/documents-a3k9xZ",
"subdomain_url": "http://documents-a3k9xZ.localhost:6868",
"registered_at": "2025-01-15T10:30:00.000Z"
},
"hint": "在 http://localhost:6868/documents-a3k9xZ/filename.txt 访问文件"
}
```
### 列出已注册文件夹
```bash
curl http://localhost:6868/?format=json
```
### 访问文件
```bash
# 基于路径
curl http://localhost:6868/documents-a3k9xZ/readme.txt
# 基于子域
curl -H "Host: documents-a3k9xZ.localhost:6868" http://localhost:6868/readme.txt
```
### 更新注册
```bash
# 更改文件夹路径
curl -X PUT http://localhost:6868/ \
-H 'Content-Type: application/json' \
-d '{"slug": "documents-a3k9xZ", "folder_path": "/home/user/new-documents"}'
# 更改别名
curl -X PUT http://localhost:6868/ \
-H 'Content-Type: application/json' \
-d '{"folder_path": "/home/user/documents", "slug": "new-name"}'
```
### 注销文件夹
```bash
# 按别名
curl -X DELETE "http://localhost:6868/?slug=documents-a3k9xZ"
# 按路径
curl -X DELETE http://localhost:6868/ \
-H 'Content-Type: application/json' \
-d '{"folder_path": "/home/user/documents"}'
```
### 仪表盘
在浏览器中打开 `http://localhost:6868/`，即可访问可视化管理界面。
## API 参考
| 方法 | 路径 | 描述 |
|--------|------|-------------|
| `GET` | `/` | 列出文件夹（JSON 格式，`?format=json` 或 `Accept: application/json`，否则为 HTML 仪表盘） |
| `POST` | `/` | 注册新文件夹 |
| `PUT` | `/` | 更新现有注册的别名和/或路径 |
| `DELETE` | `/` | 注销文件夹（按别名或路径） |
| `GET` | `/<slug>/<path>` | 提供文件或目录列表 |
完整的 API 规范和所有请求/响应示例位于 [SPEC.md](SPEC.md)。
## 配置
| 选项 | 默认值 | 描述 |
|--------|---------|-------------|
| `PORT` 环境变量或 `--port <n>` | `6868` | 服务器端口 |
| `PERSIST` 环境变量或 `--persist` | `false` | 启用 `registry.json` 持久性 |
| `--mcp stdio` | 关闭 | 启动 MCP stdio 服务器 |
### 构建目标
| 脚本 | 目标 | 操作系统 | 架构 |
|--------|--------|----|------|
| `build` | 原生 | 当前 | 当前 |
| `build:linux-x64` | `bun-linux-x64` | Linux | x64（glibc） |
| `build:linux-arm64` | `bun-linux-arm64` | Linux | ARM64（glibc） |
| `build:windows-x64` | `bun-windows-x64` | Windows | x64 |
| `build:darwin-x64` | `bun-darwin-x64` | macOS | x64（Intel） |
| `build:darwin-arm64` | `bun-darwin-arm64` | macOS | ARM64（Apple Silicon） |
| `build:all` | 以上所有 | — | — |
## 安全
- **路径遍历保护** — 所有解析路径均验证为在注册文件夹根目录内
- **不暴露完整路径** — 文件响应仅通过 `X-Folder-Path` 头部包含文件夹路径的基本名称
- **别名验证** — 别名必须匹配 `^[a-z0-9][a-z0-9_-]{0,63}$`
- **需要绝对路径** — `folder_path` 必须以 `/` 开头
## 测试
```bash
bun test
```
运行测试套件，涵盖 CRUD API、文件服务、持久性和 MCP 集成。
## 项目结构
```
src/
index.ts — 入口点：启动 HTTP，条件启动 MCP，连接信号
cli.ts — CLI 配置和日志记录
registry.ts — 内存注册表映射和持久性
slug.ts — 别名生成和验证
handlers.ts — CRUD 业务逻辑（返回 CrudResult）
http.ts — Bun.serve 获取处理程序、路由、文件服务
mcp.ts — MCP 工具定义和服务器设置
utils.ts — 帮助程序：ok/err 响应、路径安全性、ETag、范围解析
dashboard.html — 自包含的 HTML 仪表盘
tests/ — bun:test 套件（CRUD、文件服务、持久性、MCP）
package.json — Bun 配置
tsconfig.json — TypeScript 严格配置
SPEC.md — 完整的 API 规范
CONTEXT.md — 词汇表和架构决策
```
## 致谢
如果没有以下项目，该项目就不会存在：
- **[Bun](https://bun.sh)** — 使这个零开销单进程服务器成为可能
- **[Qwen](https://qwen.ai)** — 编写每一行代码的 Qwen3.6-27B 模型
- **[llama.cpp](https://github.com/ggerganov/llama.cpp)** — 为本地 LLM 执行提供推理引擎
- **[llama-swap](https://github.com/mostlygeek/llama-swap)** — 使在消费级硬件上运行大型模型成为可行的内存管理工具
- **[pi coding agent](https://github.com/earendil-works/pi-coding-agent)** — 协调整个项目的 AI 编程代理
## 许可证
MIT
