Metadata-Version: 2.4
Name: pyfileserv
Version: 0.7.0
Summary: 带登录认证的安全文件服务器
Project-URL: Homepage, https://github.com/yzutyc/pyfileserv
Project-URL: Repository, https://github.com/yzutyc/pyfileserv
Author-email: yzutyc <yucheng@email.cn>
License-Expression: MIT
Keywords: authentication,bcrypt,http,pyfileserv
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Requires-Python: >=3.7
Requires-Dist: bcrypt>=4.0.0
Requires-Dist: cryptography
Requires-Dist: dataclasses; python_version < '3.7'
Requires-Dist: psycopg2>=2.9.9
Requires-Dist: pyyaml>=6.0.1
Provides-Extra: cert
Requires-Dist: cryptography>=41.0.0; extra == 'cert'
Provides-Extra: full
Requires-Dist: cryptography>=41.0.0; extra == 'full'
Requires-Dist: psycopg2-binary>=2.9.0; extra == 'full'
Requires-Dist: pyyaml>=6.0; extra == 'full'
Provides-Extra: postgres
Requires-Dist: psycopg2-binary>=2.9.0; extra == 'postgres'
Provides-Extra: test
Requires-Dist: pytest>=7.0.0; extra == 'test'
Provides-Extra: yaml
Requires-Dist: pyyaml>=6.0; extra == 'yaml'
Description-Content-Type: text/markdown

<p align="center">
  <img src="src/file_server/static/logo.svg" alt="File Server Logo" width="128" height="128">
</p>

<h1 align="center">File Server</h1>

<p align="center">带登录认证的安全文件服务器</p>

---

## 功能特性

- **用户认证系统** - 基于用户名/密码的登录认证，使用 bcrypt 加密存储密码
- **HTTPS 支持** - 支持 SSL/TLS 加密传输，可使用自签名证书或正规证书
- **YAML 配置文件** - 支持 YAML 格式配置文件，所有配置项持久化
- **PostgreSQL 数据库** - 支持将用户信息存储到 PostgreSQL 数据库
- **会话管理** - 基于 Cookie 的安全会话机制，1小时超时
- **多级目录浏览** - 支持子目录导航，面包屑路径显示
- **文件分类浏览** - 目录列表按类型分类展示：HTML、XMind、JSON 和其他文件
- **文件下载** - 支持任意文件下载，显示文件大小和修改时间
- **文件上传** - 支持多文件上传，拖拽上传，自动处理文件名冲突
- **文件搜索** - 实时搜索/过滤文件名和目录名
- **文件排序** - 支持按名称、大小或修改时间排序
- **JSON 查看器** - JSON 文件语法高亮显示，支持复制和下载
- **用户管理** - 创建、删除、修改用户密码
- **证书管理** - 内置自签名证书生成工具

## 安全特性

- **HTTPS 加密** - 支持 SSL/TLS 加密传输，防止数据窃听
- bcrypt 密码加密（rounds=12）
- 安全会话 ID（secrets.token_hex）
- HttpOnly + SameSite Cookie
- 会话超时机制
- 访问控制（未认证用户重定向到登录页）
- 路径遍历防护（防止 `../` 攻击）
- 文件上传安全（文件名清理、大小限制 100MB）
- 用户数据文件权限限制（0o600）
- 服务器路径信息隐藏（防止信息泄露）

## 安装

```bash
pip install pyfileserv
```

或使用 pipx 安装（推荐）：

```bash
pipx install pyfileserv
```

## 使用方法

### 1. 创建用户

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

### 2. 启动服务器

```bash
pyfileserv
# 或指定端口
pyfileserv -p 9000
```

### 命令行参数

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `-p, --port` | 服务器端口 | 8000 |
| `-d, --directory` | 文件服务目录 | 当前目录 |
| `-c, --config-dir` | 配置文件目录 | 脚本目录 |
| `-f, --config-file` | 配置文件路径 | - |
| `-s, --static-dir` | 静态文件目录 | 脚本目录 |
| `--ssl-cert` | SSL 证书文件路径（启用 HTTPS） | - |
| `--ssl-key` | SSL 私钥文件路径（启用 HTTPS） | - |

### 配置文件

pyfileserv 支持 YAML 格式的配置文件，配置优先级：
**命令行参数 > 配置文件 > 环境变量 > 默认值**

#### 生成默认配置文件

```bash
# 生成默认配置文件 config.yml
pyfileserv config init

# 指定输出路径
pyfileserv config init -o myconfig.yml
```

#### 配置文件示例

```yaml
# pyfileserv 配置文件

# 服务器配置
server:
  port: 8000
  host: ""

# 路径配置
paths:
  serve_dir: null
  static_dir: null
  users_file: "users.json"

# SSL/HTTPS 配置
ssl:
  cert_file: null
  key_file: null

# 数据库配置
database:
  # 存储类型: json (文件) 或 postgres
  type: "json"

  # PostgreSQL 配置（仅 type=postgres 时使用）
  host: "localhost"
  port: 5432
  database: "pyfileserv"
  username: null
  password: null

  # 连接池配置
  pool_size: 5
  max_overflow: 10

# 会话配置
session:
  timeout: 3600

# 安全配置
security:
  bcrypt_rounds: 12
```

#### 使用配置文件

```bash
# 使用当前目录的 config.yml
pyfileserv

# 指定配置文件路径
pyfileserv -f /path/to/config.yml

# 指定配置文件目录
pyfileserv -c /etc/pyfileserv
```

### 数据库配置

pyfileserv 支持两种用户存储方式：JSON 文件（默认）和 PostgreSQL 数据库。

#### 使用 PostgreSQL

1. 安装依赖：
```bash
pip install psycopg2-binary
# 或安装完整功能包
pip install pyfileserv[postgres]
```

2. 创建数据库和用户：

使用 postgres 超级用户登录：
```bash
sudo -u postgres psql
```

或在 Windows 上：
```bash
psql -U postgres
```

然后执行以下 SQL 命令：
```sql
-- 创建数据库
CREATE DATABASE pyfileserv;

-- 创建用户（请修改密码）
CREATE USER pyfileserv WITH PASSWORD 'your_secure_password';

-- 授权
GRANT ALL PRIVILEGES ON DATABASE pyfileserv TO pyfileserv;

-- 连接到新数据库
\c pyfileserv

-- 授权 schema 权限（PostgreSQL 15+ 需要）
GRANT ALL ON SCHEMA public TO pyfileserv;

-- 退出
\q
```

3. 修改配置文件：
```yaml
database:
  type: "postgres"
  host: "localhost"
  port: 5432
  database: "pyfileserv"
  username: "your_user"
  password: "your_password"
```

4. 表会在首次启动时自动创建。

#### 用户管理命令与数据库

所有用户管理命令（`user create/list/delete/passwd`）都支持通过配置文件使用数据库：

```bash
# 使用配置文件管理数据库用户
pyfileserv -f config.yml user create -u admin
pyfileserv -f config.yml user list
```

### 用户管理命令

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

# 列出用户
pyfileserv user list

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

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

### HTTPS 配置

#### 生成自签名证书

```bash
# 生成默认证书（cert.pem 和 key.pem）
pyfileserv cert generate

# 自定义证书路径和参数
pyfileserv cert generate --cert mycert.pem --key mykey.pem --cn mydomain.com --days 365
```

证书生成需要 `cryptography` 库，可通过以下命令安装：
```bash
pip install cryptography
```

#### 启动 HTTPS 服务器

```bash
# 使用自签名证书启动
pyfileserv --ssl-cert cert.pem --ssl-key key.pem

# 同时指定端口
pyfileserv --ssl-cert cert.pem --ssl-key key.pem -p 8443
```

#### 使用正规 CA 证书

如果你有正规 CA 签发的证书，直接使用 `--ssl-cert` 和 `--ssl-key` 参数指定证书和私钥文件路径即可。

### 示例

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

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

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

## 访问

- HTTP 模式：访问 `http://localhost:8000` 或局域网 IP 地址
- HTTPS 模式：访问 `https://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            # 文档
```

## 开发与发布

### 安装开发依赖

```bash
pip install -e ".[test]"
```

### 运行测试

```bash
pytest tests/ -v
```

### 构建

```bash
pip install build
python -m build
```

### 发布到 TestPyPI

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

### 发布到 PyPI

```bash
python -m twine upload dist/*
```

## 要求

- Python >= 3.6
- bcrypt >= 4.0.0
- dataclasses (仅 Python 3.6 需要)

### 可选依赖

- **cryptography >= 41.0.0** - 用于生成自签名证书
- **pyyaml >= 6.0** - 用于 YAML 配置文件支持
- **psycopg2-binary >= 2.9.0** - 用于 PostgreSQL 数据库支持

### 安装可选依赖

```bash
# 安装所有可选依赖
pip install pyfileserv[full]

# 或按需安装
pip install pyfileserv[cert,yaml,postgres]
```

## 许可证

MIT License
