# http_file_server

**Repository Path**: alaker/http_file_server

## Basic Information

- **Project Name**: http_file_server
- **Description**: 提供局域网文件服务功能
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# HTTP File Server

用 **Go** 写的跨平台 HTTP 文件服务器：浏览、上传、下载、预览、打包 zip。页面和接口都嵌进二进制里，**编译结果就是一个可执行文件**，拷到设备上即可运行。

## 能做什么

- 网页文件管理（电脑 / 手机浏览器都能用）
- 上传、新建文件夹、重命名、删除
- 拖拽上传、目录打包下载、Range 分片（可播视频）
- 可选账号密码 / Token
- 只读模式，适合给别人传文件
- 启动后打印本机和局域网地址，并生成二维码

## 支持的系统

| 目标 | 产物示例 | 说明 |
| --- | --- | --- |
| Windows | `fileserver-windows-amd64.exe` | Win10/11 x64；另有 arm64 / 386 |
| Linux | `fileserver-linux-amd64` | 桌面、服务器、WSL |
| 嵌入式 Linux | `linux-armv7` / `armv5` / `arm64` / `mipsle-softfloat` / `riscv64` | 树莓派、OpenWrt、工控板 |
| macOS (Apple) | `fileserver-darwin-arm64` / `amd64` | Apple Silicon / Intel Mac |
| Android | `fileserver-android-arm64` 或 `linux-arm64` | 推荐在 Termux 里运行 |
| iPhone / iPad | 浏览器访问即可；本机跑服务见下文 | iOS 不能像桌面那样直接丢一个后台可执行文件 |

纯 Go、默认 `CGO_ENABLED=0`，Linux 产物是静态链接，一般不依赖目标机上的 libc 版本。

## 本机编译

需要 [Go 1.22+](https://go.dev/dl/)。

```bash
go build -trimpath -ldflags "-s -w -X main.Version=1.0.0" -o fileserver.exe .
```

PowerShell 交叉编译（可多选、自由组合，或全编）：

```powershell
.\scripts\build.ps1                  # 交互选择；回车/a = 全编，q/0 = 取消
.\scripts\build.ps1 all              # 全编
.\scripts\build.ps1 windows linux-arm64
.\scripts\build.ps1 1,9,12           # 按编号组合
.\scripts\build.ps1 -List
```

Linux / macOS：

```bash
make dist
# 或
bash scripts/build.sh                # 交互选择；回车/a = 全编，q/0 = 取消
bash scripts/build.sh all
bash scripts/build.sh windows linux-arm64
```

分组：`all` / `linux` / `windows` / `darwin` / `embedded` / `mobile` / `dist`。`ios/arm64` 需要 cgo + Xcode，编不过会自动跳过。

国内若 `go` 拉模块失败：

```powershell
$env:GOPROXY = "https://goproxy.cn,direct"
```

## 运行

```text
# 共享当前目录，监听 8080（默认对局域网开放）
./fileserver -root . -addr :8080

# Windows
.\fileserver.exe -root D:\share -addr :8080 -open

# 账号密码
./fileserver -root /data/share -user admin -pass 改成你的密码

# 只读
./fileserver -root /mnt/sd -readonly -addr :80

# 自签 HTTPS（手机浏览器会提示证书不受信任，可继续访问）
./fileserver -https -root /data/share
```

启动后终端会打印：

```text
  Local    http://127.0.0.1:8080
  LAN      http://192.168.x.x:8080
```

同一 Wi-Fi 下用手机浏览器打开 LAN 地址即可。网页右上角 **连接** 可显示二维码。

### 常用参数

| 参数 | 环境变量 | 含义 |
| --- | --- | --- |
| `-root` | `FILESERVER_ROOT` | 要共享的目录 |
| `-addr` | `FILESERVER_ADDR` | 监听地址，默认 `:8080` |
| `-user` / `-pass` | `FILESERVER_USER` / `FILESERVER_PASS` | HTTP Basic 认证 |
| `-token` | `FILESERVER_TOKEN` | Bearer 或 `?access_token=` |
| `-readonly` | `FILESERVER_READONLY` | 禁止写入 |
| `-hide-dot` | `FILESERVER_HIDE_DOT` | 隐藏点文件 |
| `-max-upload` | `FILESERVER_MAX_UPLOAD` | 上传上限，如 `2G`；`0` 不限制 |
| `-https` | `FILESERVER_HTTPS` | HTTPS，无证书时自动自签 |
| `-tls-cert` / `-tls-key` | | 使用已有证书 |
| `-open` | `FILESERVER_OPEN` | 启动后打开本机浏览器 |

`curl` 上传：

```bash
curl -T photo.jpg "http://192.168.1.8:8080/api/upload?path=/photo.jpg"
```

## 各平台说明

### 嵌入式 Linux

把对应架构的二进制拷过去，`chmod +x` 后运行。常见对应关系：

- 树莓派 3/4/5（64 位系统）：`linux-arm64`
- 树莓派 32 位 / 很多 ARM 开发板：`linux-armv7`
- 很老的 ARM：`linux-armv5`
- 多数 OpenWrt 路由器：`linux-mipsle-softfloat`
- RISC-V 板子：`linux-riscv64`

内存很小的设备建议加 `-readonly`，避免大文件上传把磁盘写满。

### Android

1. 安装 [Termux](https://termux.dev/)
2. 把 `fileserver-linux-arm64`（或 `android-arm64`）拷进 Termux
3. `chmod +x fileserver-linux-arm64`
4. `./fileserver-linux-arm64 -root /sdcard -addr :8080`

Android 普通 App 不能任意执行一个裸二进制；要做成应用商店里的 App，需要再包一层 APK（本仓库提供的是可执行文件，不是 APK）。

### Apple

- **Mac**：直接运行 `darwin-arm64` 或 `darwin-amd64`。
- **iPhone / iPad 当客户端**：用 Safari 打开电脑或 NAS 上的 `http://局域网IP:8080`，可加到主屏幕。
- **在 iPhone 上当服务端**：iOS 不允许像桌面那样直接跑一个后台程序。可选：
  - [iSH](https://ish.app/) 里运行 `fileserver-ish-linux-386`（与 `linux-386` 相同）
  - 在装有 Xcode 的 Mac 上用 cgo 编 `GOOS=ios`，再嵌进自己的 App（需开发者账号，后台网络仍受系统限制）
  - 更常见的用法：服务跑在 Mac / PC / NAS 上，手机只当浏览器客户端

## 安全

这是局域网文件分享工具。绑定 `:8080` 等于把 `-root` 目录暴露给能访问这台机器的人。

- 只在受信网络使用，或加上 `-user` / `-token`
- 不要把系统根目录、SSH 私钥目录直接共享出去
- 需要公网访问时，请放在反向代理后面并启用 HTTPS 和认证

## HTTP API

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| `GET` | `/api/info` | 版本、系统、可访问 URL |
| `GET` | `/api/list?path=/` | 列目录 |
| `GET` | `/api/file?path=/a.txt` | 下载/预览（支持 Range） |
| `GET` | `/api/file?path=/a.txt&download=1` | 附件下载 |
| `POST` | `/api/upload?path=/` | `multipart/form-data`，字段名 `file` |
| `PUT` | `/api/upload?path=/a.bin` | 原始流上传 |
| `POST` | `/api/mkdir` | `{"path":"/","name":"new"}` |
| `POST` | `/api/rename` | `{"from":"/a","to":"b"}` |
| `POST` | `/api/delete` | `{"paths":["/a"]}` |
| `POST` | `/api/zip` | `{"paths":["/dir"]}` |
| `GET` | `/api/search?q=foo&path=/` | 搜索 |
| `GET` | `/api/qr?url=...` | 二维码 PNG |

## 开发

```bash
go test ./...
```