# 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-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# HTTP File Server

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

## 能做什么

- 网页文件管理（电脑 / 手机浏览器都能用）
- 上传、新建文件夹、重命名、删除
- 拖拽上传、目录打包下载、Range 分片（可播视频）
- 默认可浏览共享目录；点登录后可看该用户的个人目录，不会弹出浏览器自带登录框
- 只读模式，适合给别人传文件
- 启动后打印本机和局域网地址，并生成二维码

## 支持的系统

| 目标 | 产物示例 | 说明 |
| --- | --- | --- |
| 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
# 用配置文件启动（推荐：共享目录 + 多用户个人目录）
./fileserver -config fileserver.json

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

# Windows
.\fileserver.exe -config fileserver.json
.\fileserver.exe -root D:\share -addr :8000 -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:8000
  LAN      http://192.168.x.x:8000
```

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

### 常用参数

| 参数 | 环境变量 | 含义 |
| --- | --- | --- |
| `-config` | `FILESERVER_CONFIG` | JSON 配置文件，默认 `fileserver.json`；不存在则自动生成 |
| `-root` | `FILESERVER_ROOT` | 要共享的目录 |
| `-addr` | `FILESERVER_ADDR` | 监听地址，默认 `:8000` |
| `-user` / `-pass` | `FILESERVER_USER` / `FILESERVER_PASS` | 可选登录账号；登录后可见个人目录 |
| `-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:8000/api/upload?path=/photo.jpg"
```

### 配置文件

共享目录、账号，以及每个用户自己的额外目录，都写在一份 JSON 里。默认读取当前目录的 `fileserver.json`；文件不存在时会自动生成模板，再按这个文件启动。

```bash
./fileserver -config fileserver.json
```

```json
{
  "share_dir": "D:/share",
  "addr": ":8000",
  "users": [
    {
      "user": "alice",
      "pass": "secret",
      "dirs": [
        { "name": "docs", "path": "D:/alice/docs" },
        { "name": "photos", "path": "E:/photos" }
      ]
    },
    {
      "user": "bob",
      "pass": "other-secret",
      "dirs": ["D:/bob/work"]
    }
  ]
}
```

单用户也可以把个人目录写在顶层：

```json
{
  "share_dir": "/data/share",
  "addr": ":8000",
  "user": "alice",
  "pass": "secret",
  "dirs": [
    { "name": "docs", "path": "/home/alice/docs" }
  ]
}
```

字段说明：

| 字段 | 含义 |
| --- | --- |
| `share_dir` | 共享目录，未登录也可以访问 |
| `addr` | 监听地址，默认 `:8000` |
| `users` | 多用户列表 |
| `user` / `pass` | 单用户账号（也可与 `users` 一起用） |
| `dirs` | 该用户的额外目录；`name` 是网页里显示的文件夹名，不写则用路径最后一段 |
| `readonly` / `hide_dot` / `https` / `token` / `max_upload` | 与对应命令行参数相同 |

相对路径相对于**配置文件所在目录**。命令行里写过的参数会覆盖配置文件。

`share_dir` 是共享目录，打开网页即可浏览，不会弹出浏览器登录框。右上角 **登录** 后，该用户的个人目录会出现在根目录下（页面上带「个人目录」标记）。点 **退出** 后只剩共享目录。

注意：

- `share_dir` 为空，或设备上没有这个目录时，不使用共享目录
- 用户 `dirs` 里的路径不存在时，该文件夹不会出现在列表里
- 个人目录只对相应用户可见，其他人即使猜到路径也无法访问
- Token 认证仍然只能访问共享目录，拿不到某个用户的个人目录
- 不能删除或重命名个人目录这个挂载点本身；里面的文件可以照常改
- 个人目录的显示名不要和共享目录里已有的文件夹重名，否则个人目录优先

## 各平台说明

### 嵌入式 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 :8000`

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

### Apple

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

## 安全

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

- 只在受信网络使用。配置了账号也不会挡住共享目录，只是用来打开个人目录；需要限制写入时加 `-readonly`
- 不要把系统根目录、SSH 私钥目录直接共享出去
- 需要公网访问时，请放在反向代理后面并启用 HTTPS 和认证

## HTTP API

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| `GET` | `/api/info` | 版本、系统、可访问 URL；含 `login` / 当前 `user` |
| `POST` | `/api/login` | `{"user":"...","pass":"..."}`，返回会话 `token` |
| `POST` | `/api/logout` | 注销当前会话 |
| `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`；`filename` 可带相对路径以上传文件夹 |
| `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 ./...
```