Metadata-Version: 2.5
Name: mysphinx-webserver
Version: 0.1.0
Summary: A FastAPI web server for browsing a directory tree and downloading files from it.
Project-URL: Homepage, https://github.com/my-sphinx/mysphinx-webserver
Project-URL: Repository, https://github.com/my-sphinx/mysphinx-webserver
Author: mysphinx
License: MIT
License-File: LICENSE
Keywords: download,fastapi,file-browser,file-server
Classifier: Framework :: FastAPI
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.9
Requires-Dist: fastapi>=0.110
Requires-Dist: uvicorn[standard]>=0.29
Description-Content-Type: text/markdown

# mysphinx-webserver

一个基于 [FastAPI](https://fastapi.tiangolo.com/) 的极简 Web 文件服务器：在浏览器中浏览指定目录及其子目录，点击文件即可下载。

## 功能特性

- 目录树浏览：以网页表格形式展示目录下的子目录与文件（含大小、修改时间），支持面包屑导航和返回上级目录。
- 点击文件下载：点击文件名会以 `Content-Disposition: attachment` 方式下载该文件。
- 根目录可配置：通过环境变量 `MYSPHINX_WEBSERVER_ROOT` 指定要暴露的根目录；未设置时，默认使用**启动服务时的当前工作目录**。
- 路径安全：所有请求路径都会被规范化并校验，禁止越权访问根目录之外的文件（防目录穿越）。
- 零本地依赖运行：可直接从 PyPI 拉取已发布的包运行，无需克隆本项目源码。

## 快速开始（一键启动脚本，推荐）

`scripts/start.sh` 会自动安装 [uv](https://docs.astral.sh/uv/)（如果本机没有），然后通过 `uv tool run`
**直接从 PyPI 拉取 `mysphinx-webserver` 的 wheel 包**运行，全程不依赖本地项目代码：

```bash
# 下载脚本（也可以直接从本仓库获取 scripts/start.sh）
curl -LsSf https://raw.githubusercontent.com/my-sphinx/mysphinx-webserver/main/scripts/start.sh -o start.sh
chmod +x start.sh

# 浏览当前目录，监听 127.0.0.1:8000
./start.sh

# 指定要浏览的目录、监听地址和端口
MYSPHINX_WEBSERVER_ROOT=/data/shared ./start.sh --host 0.0.0.0 --port 9000

# 固定使用某个已发布的版本
MYSPHINX_WEBSERVER_VERSION=0.1.0 ./start.sh
```

脚本会把所有命令行参数原样透传给 `mysphinx-webserver`（见下方“命令行参数”）。

## 安装 / 运行方式

### 方式一：`uvx`（推荐，无需事先安装）

```bash
# 临时运行，浏览当前目录
uvx mysphinx-webserver

# 指定根目录与监听端口
MYSPHINX_WEBSERVER_ROOT=/path/to/dir uvx mysphinx-webserver --host 0.0.0.0 --port 8000
```

### 方式二：`pip install`

```bash
pip install mysphinx-webserver
MYSPHINX_WEBSERVER_ROOT=/path/to/dir mysphinx-webserver --host 0.0.0.0 --port 8000
```

### 方式三：`uv` 常驻安装

```bash
uv tool install mysphinx-webserver
mysphinx-webserver --help
```

## 命令行参数

```
mysphinx-webserver [-h] [--host HOST] [--port PORT] [--reload]

--host HOST   监听地址（默认 127.0.0.1）
--port PORT   监听端口（默认 8000）
--reload      开发模式下启用自动重载（生产环境不建议开启）
```

## 环境变量

| 变量名 | 说明 | 默认值 |
| --- | --- | --- |
| `MYSPHINX_WEBSERVER_ROOT` | 要浏览/下载的根目录路径 | 未设置时使用启动进程时的当前工作目录 |

根目录在服务启动时解析一次；如果路径不存在或不是目录，服务会在启动时报错退出。

## 使用示例

```bash
# 在 /var/www/shared 目录下启动，对外监听 0.0.0.0:8080
MYSPHINX_WEBSERVER_ROOT=/var/www/shared uvx mysphinx-webserver --host 0.0.0.0 --port 8080
```

浏览器打开 `http://<服务器地址>:8080/` 即可看到目录列表：

- 点击文件夹名会进入该子目录继续浏览。
- 点击文件名会直接触发浏览器下载该文件。
- 顶部面包屑可快速跳转回任意上级目录。

> 安全提示：该服务不包含身份认证，任何能访问到该端口的人都可以浏览和下载根目录下的所有文件。请仅在受信任的网络内使用，或自行在前面加一层反向代理 + 认证（如 Nginx Basic Auth）。

## 本地开发

本项目使用 [uv](https://docs.astral.sh/uv/) 管理 Python 依赖。

```bash
# 安装依赖（含开发依赖）
uv sync

# 以本地源码方式启动服务（浏览当前目录）
uv run mysphinx-webserver

# 运行测试
uv run pytest

# 构建 wheel / sdist
uv build   # 产物在 dist/ 目录
```

## 发布到 PyPI（维护者）

本项目通过 GitHub Actions 使用 PyPI 的 **Trusted Publishing（OIDC 可信发布）** 自动发布，不需要在仓库中保存任何 PyPI Token。

首次发布前，需要在 PyPI 上配置 Trusted Publisher：

1. 登录 PyPI，进入 <https://pypi.org/manage/account/publishing/>。
2. 在 “Add a new pending publisher” 中填写：
   - PyPI Project Name: `mysphinx-webserver`
   - Owner: `my-sphinx`
   - Repository name: `mysphinx-webserver`
   - Workflow name: `publish.yml`
   - Environment name: `pypi`
3. 保存后，在 GitHub 仓库 Settings → Environments 中创建一个名为 `pypi` 的 environment（可选，用于审批/保护）。
4. 在 GitHub 上创建一个 Release（或手动触发 `.github/workflows/publish.yml` 的 `workflow_dispatch`），
   workflow 会自动执行 `uv build` 并通过 [`pypa/gh-action-pypi-publish`](https://github.com/pypa/gh-action-pypi-publish) 将构建产物发布到 PyPI。

后续每次想发布新版本，只需：

1. 更新 `pyproject.toml` 与 `src/mysphinx_webserver/__init__.py` 中的 `version`。
2. 提交并打 tag（如 `v0.1.1`），在 GitHub 上创建对应 Release。
3. GitHub Actions 会自动构建并发布新版本到 PyPI。

## 项目结构

```
.
├── pyproject.toml                # 项目元数据、依赖，uv/hatchling 构建配置
├── uv.lock                       # uv 锁定的依赖版本
├── src/mysphinx_webserver/
│   ├── __init__.py
│   ├── __main__.py               # CLI 入口（mysphinx-webserver 命令）
│   ├── config.py                 # 根目录解析（MYSPHINX_WEBSERVER_ROOT）
│   └── app.py                    # FastAPI 应用：目录浏览 + 文件下载
├── scripts/start.sh              # 一键启动脚本（从 PyPI 拉取运行）
└── .github/workflows/publish.yml # PyPI Trusted Publishing 发布流水线
```

## License

MIT
