pyfileserv 0.4.1

带登录认证的安全文件服务器

File Server

带登录认证的安全文件服务器

---

功能特性

• 用户认证系统 - 基于用户名/密码的登录认证，使用 bcrypt 加密存储密码
• 会话管理 - 基于 Cookie 的安全会话机制，1小时超时
• 文件浏览 - 目录列表功能，分开展示 HTML 文件和其他文件
• 文件下载 - 支持任意文件下载，显示文件大小
• 文件上传 - 支持多文件上传，拖拽上传，自动处理文件名冲突
• 用户管理 - 创建、删除、修改用户密码

安全特性

• bcrypt 密码加密（rounds=12）
• 安全会话 ID（secrets.token_hex）
• HttpOnly + SameSite Cookie
• 会话超时机制
• 访问控制（未认证用户重定向到登录页）
• 路径遍历防护（防止 ../ 攻击）
• 文件上传安全（文件名清理、大小限制 100MB）

安装

pip install pyfileserv

或使用 pipx 安装（推荐）：

pipx install pyfileserv

使用方法

1. 创建用户

pyfileserv user create
# 或指定用户名
pyfileserv user create -u admin

2. 启动服务器

pyfileserv
# 或指定端口
pyfileserv -p 9000

命令行参数

参数	说明	默认值
-p, --port	服务器端口	8000
-d, --directory	文件服务目录	当前目录
-c, --config-dir	配置文件目录	脚本目录
-s, --static-dir	静态文件目录	脚本目录

用户管理命令

# 创建用户
pyfileserv user create [-u 用户名]

# 列出用户
pyfileserv user list

# 删除用户
pyfileserv user delete [-u 用户名]

# 修改密码
pyfileserv user passwd [-u 用户名]

示例

# 在端口 9000 启动服务器
pyfileserv -p 9000

# 指定文件服务目录
pyfileserv -d /path/to/files

# 自定义配置和静态文件目录
pyfileserv -c /etc/pyfileserv -s /var/www/files

访问

启动后访问 http://localhost:8000 或局域网 IP 地址。

项目结构

pyfileserv/
├── .github/
│   └── workflows/
│       └── python-publish.yml  # PyPI 自动发布工作流
├── src/file_server/
│   ├── __init__.py      # 包入口
│   ├── __main__.py      # CLI 入口
│   ├── config.py        # 配置模块
│   ├── auth.py          # 认证模块
│   ├── templates.py     # HTML 模板
│   ├── handlers.py      # HTTP 处理器
│   ├── server.py        # 服务器启动
│   ├── cli.py           # 命令行工具
│   └── static/
│       ├── logo.svg     # Logo 图标
│       └── favicon.svg  # Favicon 图标
├── tests/
│   ├── __init__.py      # 测试包入口
│   ├── conftest.py      # pytest 配置
│   ├── test_auth.py     # 认证模块测试
│   ├── test_config.py   # 配置模块测试
│   └── test_handlers.py # 处理器测试
├── CHANGELOG.md         # 变更日志
├── pyproject.toml       # 项目配置
├── release.py           # 发布脚本
└── README.md            # 文档

开发与发布

安装开发依赖

pip install -e ".[test]"

运行测试

pytest tests/ -v

构建

pip install build
python -m build

发布到 TestPyPI

pip install twine
python -m twine upload --repository testpypi dist/*

发布到 PyPI

python -m twine upload dist/*

要求

• Python >= 3.13
• bcrypt >= 5.0.0

许可证

MIT License