256 lines
8.6 KiB
Markdown
256 lines
8.6 KiB
Markdown
# 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。
|
||
|
||
### 启动示例
|
||
|
||
```bash
|
||
# 托管默认目录 ./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
|
||
```
|
||
|
||
启动成功后访问终端中显示的地址即可，例如：
|
||
|
||
```text
|
||
http://127.0.0.1:8080/
|
||
```
|
||
|
||
### 构建发布版本
|
||
|
||
```bash
|
||
cargo build --release -p stash-cli
|
||
```
|
||
|
||
构建产物为 `target/release/stash`；Windows 下为 `target/release/stash.exe`。
|
||
|
||
## 托管目录示例
|
||
|
||
### 单个静态站点
|
||
|
||
```text
|
||
public/
|
||
├── index.html
|
||
├── assets/
|
||
│ ├── app.js
|
||
│ └── style.css
|
||
└── images/
|
||
└── logo.png
|
||
```
|
||
|
||
此时访问 `/` 会直接展示 `public/index.html`。
|
||
|
||
### 多个前端项目
|
||
|
||
```text
|
||
public/
|
||
├── admin-console/
|
||
│ └── index.html
|
||
├── docs/
|
||
│ └── index.html
|
||
└── landing-page/
|
||
└── index.html
|
||
```
|
||
|
||
由于根目录没有 `index.html`，访问 `/` 时会展示项目导航页。对应访问地址为：
|
||
|
||
```text
|
||
/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
|
||
|
||
### 健康检查
|
||
|
||
```http
|
||
GET /api/health
|
||
```
|
||
|
||
响应：
|
||
|
||
```json
|
||
{
|
||
"status": "ok",
|
||
"service": "stash"
|
||
}
|
||
```
|
||
|
||
### 获取项目列表
|
||
|
||
```http
|
||
GET /api/projects
|
||
```
|
||
|
||
响应示例：
|
||
|
||
```json
|
||
{
|
||
"projects": [
|
||
{
|
||
"name": "admin-console",
|
||
"route_path": "/admin-console/"
|
||
},
|
||
{
|
||
"name": "docs",
|
||
"route_path": "/docs/"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
该接口与导航页使用相同的项目扫描规则。即使托管根目录包含 `index.html`，接口仍会返回当前根目录下可识别的项目列表。
|
||
|
||
### 订阅项目变化
|
||
|
||
```http
|
||
GET /api/projects/events
|
||
Accept: text/event-stream
|
||
```
|
||
|
||
连接建立后，服务会立即发送当前项目快照，随后在文件监听检测到项目列表变化时推送新快照：
|
||
|
||
```text
|
||
event: projects
|
||
data: {"projects":[{"name":"docs","route_path":"/docs/"}]}
|
||
```
|
||
|
||
服务端会递归监听托管目录，将短时间内的连续文件事件合并为一次扫描，并且只在项目名称或访问路径实际变化时广播。SSE 连接每 15 秒发送一次保活消息，浏览器断开后会自动重连。
|
||
|
||
## 项目结构
|
||
|
||
```text
|
||
.
|
||
├── 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 页面模板
|
||
```
|
||
|
||
## 测试
|
||
|
||
运行核心库测试：
|
||
|
||
```bash
|
||
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` 暴露到局域网前，应确认目录内容适合被其他设备访问。
|