miniserve - 一个用于通过 HTTP 提供文件和目录的 CLI 工具

当你真的只想立即通过 HTTP 提供一些文件时使用！

miniserve 是一个小巧、自包含的多平台 CLI 工具，允许您直接获取二进制文件并通过 HTTP 提供一些文件。有时这比正确做事更实用、更快。

截图

如何使用

提供目录

miniserve linux-distro-collection/

提供单个文件

miniserve linux-distro.iso

设置自定义索引文件以替代文件列表提供

miniserve --index test.html

提供单页应用程序 (SPA)，使不存在的路径转发到 SPA 的路由器

miniserve --spa --index index.html

需要用户名/密码

miniserve --auth joe:123 unreleased-linux-distros/

需要以哈希形式提供用户名/密码

pw=$(echo -n "123" | sha256sum | cut -f 1 -d ' ')
miniserve --auth joe:sha256:$pw unreleased-linux-distros/

从文件中需要用户名/密码（使用新行分隔不同的登录）

miniserve --auth-file auth.txt unreleased-linux-distros/

生成随机的 6 位十六进制数字 URL

miniserve -i 192.168.0.1 --random-route /tmp
# Serving path /private/tmp at http://192.168.0.1/c789b6

绑定到多个接口

miniserve -i 192.168.0.1 -i 10.13.37.10 -i ::1 /tmp/myshare

以 TLS 启动

miniserve --tls-cert my.cert --tls-key my.key /tmp/myshare

使用 curl 上传文件

# in one terminal
miniserve -u -- .
# in another terminal
curl -F "path=@$FILE" http://localhost:8080/upload\?path\=/

(其中 $FILE 是文件的路径。这使用 miniserve 的默认端口 8080)

注意，对于上传，我们必须使用 -- 来区分 -u 的参数。这是因为 -u 也可以接受路径（或多个）。如果为 -u 提供了路径参数，则上传将只能到提供的路径，而不是每个路径。

这种做法的另一个影响是，当使用 -u 时，不能简单地组合标志，如 -uv。在这个例子中，您需要使用 -u -v。

使用 curl 创建目录

# in one terminal
miniserve --upload-files --mkdir .
# in another terminal
curl -F "mkdir=$DIR_NAME" http://localhost:8080/upload\?path=\/

（其中 $DIR_NAME 是目录的名称。这使用 miniserve 的默认端口 8080。）

从智能手机拍照并上传

miniserve -u -m image -q

这使用 --media-type 选项，向浏览器发送预期媒体类型的提示。一些移动浏览器，如 Android 上的 Firefox，在看到这个提示时会提供打开相机应用程序的选项。

功能

• 易于使用
• 即插即用：默认正确处理 MIME 类型
• 单二进制文件，无需额外依赖
• 支持用户名和密码（以及哈希密码）的认证
• 极快且高度并行（归功于 Rust 和 Actix）
• 文件夹下载（实时压缩为 .tar.gz 或 .zip）
• 文件上传
• 创建目录
• 漂亮的主题（支持浅色和深色主题）
• 扫描二维码快速访问
• Shell 完成功能
• 合理的默认设置且安全
• TLS（对于支持的架构）
• 支持 README.md 渲染，如 GitHub 上的那样
• 范围请求

用法

For when you really just want to serve some files over HTTP right now!

Usage: miniserve [OPTIONS] [PATH]

Arguments:
  [PATH]
          Which path to serve

          [env: MINISERVE_PATH=]

Options:
  -v, --verbose
          Be verbose, includes emitting access logs

          [env: MINISERVE_VERBOSE=]

      --index <INDEX>
          The name of a directory index file to serve, like "index.html"

          Normally, when miniserve serves a directory, it creates a listing for that directory. However, if a directory
          contains this file, miniserve will serve that file instead.

          [env: MINISERVE_INDEX=]

      --spa
          Activate SPA (Single Page Application) mode

          This will cause the file given by --index to be served for all non-existing file paths. In effect, this will serve
          the index file whenever a 404 would otherwise occur in order to allow the SPA router to handle the request instead.

          [env: MINISERVE_SPA=]

      --pretty-urls
          Activate Pretty URLs mode

          This will cause the server to serve the equivalent `.html` file indicated by the path.

          `/about` will try to find `about.html` and serve it.

          [env: MINISERVE_PRETTY_URLS=]

  -p, --port <PORT>
          Port to use

          [env: MINISERVE_PORT=]
          [default: 8080]

  -i, --interfaces <INTERFACES>
          Interface to listen on

          [env: MINISERVE_INTERFACE=]

  -a, --auth <AUTH>
          Set authentication

          Currently supported formats:
          username:password, username:sha256:hash, username:sha512:hash
          (e.g. joe:123, joe:sha256:a665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3)

          [env: MINISERVE_AUTH=]

      --auth-file <AUTH_FILE>
          Read authentication values from a file

          Example file content:

          joe:123
          bob:sha256:a665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3
          bill:

          [env: MINISERVE_AUTH_FILE=]

      --route-prefix <ROUTE_PREFIX>
          Use a specific route prefix

          [env: MINISERVE_ROUTE_PREFIX=]

      --random-route
          Generate a random 6-hexdigit route

          [env: MINISERVE_RANDOM_ROUTE=]

  -P, --no-symlinks
          Hide symlinks in listing and prevent them from being followed

          [env: MINISERVE_NO_SYMLINKS=]

  -H, --hidden
          Show hidden files

          [env: MINISERVE_HIDDEN=]

  -S, --default-sorting-method <DEFAULT_SORTING_METHOD>
          Default sorting method for file list

          [env: MINISERVE_DEFAULT_SORTING_METHOD=]
          [default: name]

          Possible values:
          - name: Sort by name
          - size: Sort by size
          - date: Sort by last modification date (natural sort: follows alphanumerical order)

  -O, --default-sorting-order <DEFAULT_SORTING_ORDER>
          Default sorting order for file list

          [env: MINISERVE_DEFAULT_SORTING_ORDER=]
          [default: desc]

          Possible values:
          - asc:  Ascending order
          - desc: Descending order

  -c, --color-scheme <COLOR_SCHEME>
          Default color scheme

          [env: MINISERVE_COLOR_SCHEME=]
          [default: squirrel]
          [possible values: squirrel, archlinux, zenburn, monokai]

  -d, --color-scheme-dark <COLOR_SCHEME_DARK>
          Default color scheme

          [env: MINISERVE_COLOR_SCHEME_DARK=]
          [default: archlinux]
          [possible values: squirrel, archlinux, zenburn, monokai]

  -q, --qrcode
          Enable QR code display

          [env: MINISERVE_QRCODE=]

  -u, --upload-files [<ALLOWED_UPLOAD_DIR>]
          Enable file uploading (and optionally specify for which directory)

          [env: MINISERVE_ALLOWED_UPLOAD_DIR=]

  -U, --mkdir
          Enable creating directories

          [env: MINISERVE_MKDIR_ENABLED=]

  -m, --media-type <MEDIA_TYPE>
          Specify uploadable media types

          [env: MINISERVE_MEDIA_TYPE=]
          [possible values: image, audio, video]

  -M, --raw-media-type <MEDIA_TYPE_RAW>
          Directly specify the uploadable media type expression

          [env: MINISERVE_RAW_MEDIA_TYPE=]

  -o, --overwrite-files
          Enable overriding existing files during file upload

          [env: OVERWRITE_FILES=]

  -r, --enable-tar
          Enable uncompressed tar archive generation

          [env: MINISERVE_ENABLE_TAR=]

  -g, --enable-tar-gz
          Enable gz-compressed tar archive generation

          [env: MINISERVE_ENABLE_TAR_GZ=]

  -z, --enable-zip
          Enable zip archive generation

          WARNING: Zipping large directories can result in out-of-memory exception because zip generation is done in memory
          and cannot be sent on the fly

          [env: MINISERVE_ENABLE_ZIP=]

  -C, --compress-response
          Compress response

          WARNING: Enabling this option may slow down transfers due to CPU overhead, so it is disabled by default.

          Only enable this option if you know that your users have slow connections or if you want to minimize your server's bandwidth usage.

          [env: MINISERVE_COMPRESS_RESPONSE=]

  -D, --dirs-first
          List directories first

          [env: MINISERVE_DIRS_FIRST=]

  -t, --title <TITLE>
          Shown instead of host in page title and heading

          [env: MINISERVE_TITLE=]

      --header <HEADER>
          Set custom header for responses

          [env: MINISERVE_HEADER=]

  -l, --show-symlink-info
          Visualize symlinks in directory listing

          [env: MINISERVE_SHOW_SYMLINK_INFO=]

  -F, --hide-version-footer
          Hide version footer

          [env: MINISERVE_HIDE_VERSION_FOOTER=]

      --hide-theme-selector
          Hide theme selector

          [env: MINISERVE_HIDE_THEME_SELECTOR=]

  -W, --show-wget-footer
          If enabled, display a wget command to recursively download the current directory

          [env: MINISERVE_SHOW_WGET_FOOTER=]

      --print-completions <shell>
          Generate completion file for a shell

          [possible values: bash, elvish, fish, powershell, zsh]

      --print-manpage
          Generate man page

      --tls-cert <TLS_CERT>
          TLS certificate to use

          [env: MINISERVE_TLS_CERT=]

      --tls-key <TLS_KEY>
          TLS private key to use

          [env: MINISERVE_TLS_KEY=]

      --readme
          Enable README.md rendering in directories

          [env: MINISERVE_README=]

  -I, --disable-indexing
          Disable indexing

          This will prevent directory listings from being generated and return an error instead.

          [env: MINISERVE_DISABLE_INDEXING=]

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

如何安装

在 Linux 上：从 发布页面 下载 miniserve-linux 并运行

chmod +x miniserve-linux
./miniserve-linux

或者，如果您使用的是 Arch Linux，您可以这样做

pacman -S miniserve

在 Termux 上

pkg install miniserve

在 OSX 上：从 发布页面 下载 miniserve-osx 并运行

chmod +x miniserve-osx
./miniserve-osx

或者使用 Homebrew 安装

brew install miniserve
miniserve

在 Windows 上：从 发布页面 下载 miniserve-win.exe 并运行

miniserve-win.exe

或者使用 Scoop 安装

scoop install miniserve

使用 Cargo：请确保您有最新版本的 Rust。然后您可以运行

cargo install --locked miniserve
miniserve

使用 Docker：请确保 Docker daemon 正在运行，然后运行

docker run -v /tmp:/tmp -p 8080:8080 --rm -it docker.io/svenstaro/miniserve /tmp

使用 Podman：只需运行

podman run -v /tmp:/tmp -p 8080:8080 --rm -it docker.io/svenstaro/miniserve /tmp

使用 Helm：请参阅 @wrenix 提供的 此第三方 Helm 图表。

Shell 完成功能

如果您想使用内置的 shell 完成功能，您需要运行 miniserve --print-completions <your-shell> 并将完成功能放在您 shell 的正确位置。以下提供了一些常见路径的示例

# For bash
miniserve --print-completions bash > ~/.local/share/bash-completion/completions/miniserve
# For zsh
miniserve --print-completions zsh > /usr/local/share/zsh/site-functions/_miniserve
# For fish
miniserve --print-completions fish > ~/.config/fish/completions/miniserve.fish

systemd

在 packaging/miniserve@.service 中可以找到一个加固的与 systemd 兼容的单位文件。您可以将此安装到 /etc/systemd/system/[email protected] 并以守护进程的方式在特定的服务路径 /my/serve/path 上启动和启用 miniserve，如下所示

systemctl enable --now miniserve@-my-serve-path

请注意，您将需要使用 systemd-escape 来正确转义路径。

如果您想自定义 miniserve 启动时使用的特定标志，您可以使用

systemctl edit miniserve@-my-serve-path

并将生成的 [Service] 部分设置为 override.conf 文件。例如

[Service]
ExecStart=/usr/bin/miniserve --enable-tar --enable-zip --no-symlinks --verbose -i ::1 -p 1234 --title hello --color-scheme monokai --color-scheme-dark monokai -- %I

请确保在最后留下%I，否则可能会服务错误的路径。如果您打算在公共接口上直接提供miniserve，可能还需要覆盖IPAddressAllow和IPAddressDeny。

绑定行为

为了方便，miniserve默认会尝试绑定到所有接口（如果没有提供-i）。如果明确提供了- 0.0.0.0或- ::，它也会这样做。在上述所有情况下，它将绑定到IPv4和IPv6。如果您提供了明确的非默认接口，它将只绑定到该接口。您可以通过多次提供-来同时绑定到多个接口。