Stash

Stash 是一个基于 Rust、Tokio 和 Axum 实现的本地静态页面托管工具。它既可以直接托管一个静态站点，也可以扫描托管目录下的多个前端项目，并通过内置导航页统一访问。

核心功能

单站点托管

当托管根目录中存在 index.html 时，访问 / 会直接返回该页面。页面依赖的 JavaScript、CSS、图片、字体等资源继续通过静态文件服务加载，因此可以直接运行常见的纯静态前端项目。

多项目导航

当根目录没有 index.html 时，Stash 会扫描根目录下的一级子目录，并将包含 index.html 或 index.htm 的目录识别为前端项目。

• 自动排除以 . 开头的隐藏目录。
• 项目按名称进行不区分大小写的升序排列。
• 每个项目生成一个卡片链接，地址格式为 /<项目目录名>/。
• 项目名称首字符会作为圆形标记显示。
• 没有识别到项目时显示空状态提示。
• 导航页采用 4 列、2 列、1 列的响应式布局，分别适配桌面、平板和手机。
• 项目和目录列表在每次请求时重新扫描，新增项目通常无需重启服务。
• 文件监听会在项目快照发生变化后主动通知已打开的导航页，无需手动刷新。

静态文件服务

Stash 使用 tower-http 的 ServeDir 托管根目录内容：

• 自动为目录追加 index.html。
• 根据文件扩展名返回对应的 MIME 类型。
• 未找到的路径会返回内置的中文 404 页面，并显示请求路径。
• 每次 HTTP 请求都会经过 Trace 层，可通过调整日志级别观察请求日志。
• 内置控制台资源通过保留路径 /__stash__/ 提供，避免与用户托管的项目文件冲突。

内置控制台

• 使用 Askama 在编译期渲染项目导航页和 404 页面。
• 页面 HTML、CSS 和 JavaScript 分别维护，不再使用字符串替换拼接卡片。
• 项目名称和请求路径由模板引擎自动进行 HTML 转义。
• 项目目录名会进行 URL 路径段编码，再生成项目访问地址。
• 少量 JavaScript 通过 SSE 订阅项目变化，并在不刷新整个页面的情况下更新卡片；脚本不可用时，服务端渲染的导航和手动 API 仍可正常使用。

同源 API

服务提供两个只读 JSON 接口和一个 SSE 推送接口，可供导航页或同源前端调用。

CORS

默认允许任意来源、任意请求方法和任意请求头访问服务，适合本地联调。通过 --no-cors 可以关闭 CORS 标头注入。

服务管理

• 默认监听 127.0.0.1:8080。
• 支持自定义绑定地址、端口和托管目录。
• 默认托管目录 ./public 不存在时会自动创建。
• 用户显式指定的托管目录不存在时，会输出错误并退出。
• 端口绑定失败、目录无效等错误会以清晰的错误信息返回。
• 支持分别通过 Ctrl+C 以及 Unix 系统的 SIGTERM 触发优雅停机。

可复用核心库

stash-core 同时作为库导出 Config、StashError、start、ServerHandle、scan_projects 和 AppProject，既可由 stash-cli 使用，也可以被其他 Rust 程序嵌入或复用。

快速开始

环境要求

• Rust 工具链，需支持 Rust 2024 Edition。
• Cargo。

启动示例

# 托管默认目录 ./public，监听 127.0.0.1:8080
cargo run -p stash-cli

# 托管指定目录并修改端口
cargo run -p stash-cli -- --root ./sites --port 3000

# 允许局域网设备访问
cargo run -p stash-cli -- --root ./sites --host 0.0.0.0 --port 3000

# 关闭 CORS
cargo run -p stash-cli -- --root ./sites --no-cors

启动成功后访问终端中显示的地址即可，例如：

http://127.0.0.1:8080/

构建发布版本

cargo build --release -p stash-cli

构建产物为 target/release/stash；Windows 下为 target/release/stash.exe。

托管目录示例

单个静态站点

public/
├── index.html
├── assets/
│   ├── app.js
│   └── style.css
└── images/
    └── logo.png

此时访问 / 会直接展示 public/index.html。

多个前端项目

public/
├── admin-console/
│   └── index.html
├── docs/
│   └── index.html
└── landing-page/
    └── index.html

由于根目录没有 index.html，访问 / 时会展示项目导航页。对应访问地址为：

/admin-console/
/docs/
/landing-page/

命令行参数

参数	默认值	说明
-r, --root <DIR>	./public	静态页面托管根目录，支持相对路径和绝对路径
-p, --port <PORT>	8080	HTTP 服务监听端口
--host <HOST>	127.0.0.1	监听地址；使用 0.0.0.0 可供局域网访问
--no-listing	关闭	设计用于关闭根目录项目导航页
--no-cors	关闭	关闭全局 CORS 标头注入
-h, --help	-	查看命令行帮助
-V, --version	-	查看程序版本

注意：--no-listing 当前已由命令行解析并写入 Config.directory_listing，但根路径处理器尚未读取该配置。因此根目录没有 index.html 时，导航页目前仍会显示。

HTTP API

健康检查

GET /api/health

响应：

{
  "status": "ok",
  "service": "stash"
}

获取项目列表

GET /api/projects

响应示例：

{
  "projects": [
    {
      "name": "admin-console",
      "route_path": "/admin-console/"
    },
    {
      "name": "docs",
      "route_path": "/docs/"
    }
  ]
}

该接口与导航页使用相同的项目扫描规则。即使托管根目录包含 index.html，接口仍会返回当前根目录下可识别的项目列表。

订阅项目变化

GET /api/projects/events
Accept: text/event-stream

连接建立后，服务会立即发送当前项目快照，随后在文件监听检测到项目列表变化时推送新快照：

event: projects
data: {"projects":[{"name":"docs","route_path":"/docs/"}]}

服务端会递归监听托管目录，将短时间内的连续文件事件合并为一次扫描，并且只在项目名称或访问路径实际变化时广播。SSE 连接每 15 秒发送一次保活消息，浏览器断开后会自动重连。

项目结构

.
├── Cargo.toml                 # Rust workspace 配置
├── Cargo.lock                 # 依赖锁定文件
├── README.md
├── stash-cli/
│   ├── Cargo.toml
│   └── src/
│       └── main.rs            # CLI 参数解析、启动信息和停机信号
└── stash-core/
    ├── Cargo.toml
    ├── assets/
    │   ├── dashboard.css      # 控制台与 404 页面样式
    │   └── dashboard.js       # 项目列表刷新增强
    ├── src/
    │   ├── config.rs          # 服务配置
    │   ├── error.rs           # 错误类型与 HTTP 错误响应
    │   ├── lib.rs             # 核心库导出
    │   ├── listing.rs         # 项目扫描与页面渲染
    │   ├── server.rs          # Axum 路由、SSE、静态托管与服务器生命周期
    │   └── watcher.rs         # 文件监听、事件防抖和项目快照广播
    └── templates/
        ├── index.html         # Askama 多项目导航页模板
        └── 404.html           # Askama 404 页面模板

测试

运行核心库测试：

cargo test -p stash-core

当前测试覆盖项目目录扫描、隐藏目录过滤、一级目录限制、项目排序、项目路径编码、空状态渲染、项目内容 HTML 转义、404 页面渲染与路径转义，以及新增项目后的文件监听广播。

已知限制

• 项目扫描只检查托管根目录的一级子目录，不递归查找更深层项目。
• 根目录存在 index.html 时会优先进入单站点模式，不再展示项目导航页。
• 静态服务只为目录自动追加 index.html；导航扫描虽然也识别 index.htm，但建议项目统一使用 index.html。
• 未配置 SPA History API 回退。刷新前端路由等不存在的物理路径时，会返回 404 页面。
• SSE 仅用于服务端向浏览器推送项目快照，不提供浏览器向服务端发送命令的双向通道。
• 文件事件会经过约 150ms 防抖后再扫描，因此项目出现在导航页中可能有短暂延迟。
• 启动横幅中显示的接口地址为 /api/pages，实际实现的项目列表接口是 /api/projects。
• 服务没有身份认证机制，默认仅建议绑定 127.0.0.1。使用 0.0.0.0 暴露到局域网前，应确认目录内容适合被其他设备访问。