Metadata-Version: 2.4
Name: pyfileserv
Version: 0.14.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.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.8
Requires-Dist: bcrypt>=4.0.0
Requires-Dist: jinja2>=3.1.6
Requires-Dist: pillow>=10.4.0
Provides-Extra: build
Requires-Dist: build; extra == 'build'
Requires-Dist: twine; extra == 'build'
Provides-Extra: cert
Requires-Dist: cryptography>=41.0.0; extra == 'cert'
Provides-Extra: full
Requires-Dist: cryptography>=41.0.0; extra == 'full'
Requires-Dist: mammoth>=1.6.0; extra == 'full'
Requires-Dist: markdown>=3.4.0; extra == 'full'
Requires-Dist: psycopg2-binary>=2.9.0; extra == 'full'
Requires-Dist: pytest>=7.0.0; extra == 'full'
Requires-Dist: pyyaml>=6.0; extra == 'full'
Requires-Dist: redis>=4.0.0; extra == 'full'
Requires-Dist: spire-presentation-free>=9.0.0; extra == 'full'
Requires-Dist: spire-xls-free>=14.0.0; extra == 'full'
Provides-Extra: markdown
Requires-Dist: markdown>=3.4.0; extra == 'markdown'
Provides-Extra: office
Requires-Dist: mammoth>=1.6.0; extra == 'office'
Requires-Dist: spire-presentation-free>=9.0.0; extra == 'office'
Requires-Dist: spire-xls-free>=14.0.0; extra == 'office'
Provides-Extra: postgres
Requires-Dist: psycopg2-binary>=2.9.0; extra == 'postgres'
Provides-Extra: redis
Requires-Dist: redis>=4.0.0; extra == 'redis'
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小时超时，支持内存和 Redis 存储
- **多级目录浏览** - 支持子目录导航，面包屑路径显示
- **文件分类浏览** - 目录列表按 14 种文件类型分类展示（图片/音频/视频/PDF/文本/Markdown/XMind/JSON/Word/Excel/PowerPoint/Draw.io/Edraw/其他），支持类型筛选
- **文件下载** - 支持任意文件下载，显示文件大小和修改时间
- **文件上传** - 支持多文件上传，拖拽上传，自动处理文件名冲突
- **文件搜索** - 实时搜索/过滤文件名和目录名
- **文件排序** - 支持按名称、大小或修改时间排序
- **图片预览** - JPG、PNG、GIF、WebP、SVG 等格式在线预览，支持同目录多图导航
- **音频预览** - MP3、WAV、OGG、FLAC 等格式在线播放，支持播放列表
- **视频预览** - MP4、WebM、AVI、MOV、MKV 等格式在线播放
- **文本/代码预览** - 多种编程语言语法高亮显示，带行号
- **Markdown 预览** - 实时渲染 MD 文件，支持 Mermaid 图表渲染（流程图、时序图等），效果/源码双视图，一键导出 PDF
- **HTML 预览** - 沙箱 iframe 渲染，支持效果/源码双视图
- **XMind 预览** - 树形结构展示思维导图，支持节点展开/折叠
- **JSON 预览** - 格式化显示，支持效果/源码双视图
- **PDF 预览** - PDF 文件在线预览，内嵌浏览器查看器
- **Word 预览** - DOCX 文档在线预览（Mammoth 渲染），支持图片（含 EMF/WMF 自动转 PNG）、列表、链接、表格、标题等完整格式
- **Excel 预览** - XLSX 表格在线预览（Spire.Xls 渲染），保留原始样式和格式，支持多工作表标签切换
- **PowerPoint 预览** - PPTX 演示文稿在线预览（Spire.Presentation 渲染），幻灯片导航浏览
- **Draw.io 预览** - Draw.io 图表在线预览（viewer.diagrams.net 渲染），多标签页 + 源码视图
- **Edraw 预览** - Edraw Max 图表在线预览（SVG 渲染），形状/连接线/文本精确转换，支持缩放
- **主题切换** - 所有预览页面均支持深色/浅色主题
- **JSON 查看器** - JSON 文件语法高亮显示，支持复制和下载
- **目录权限控制** - 细粒度目录级权限控制（读写/只读），最长前缀匹配，通配符支持，Web 管理界面
- **访问日志** - 文件操作审计追踪，同步记录操作者 IP，JSON-lines 文件 + PostgreSQL 双后端，Web 查看器支持多维搜索（含 IP 筛选）
- **高级搜索** - 按文件大小、日期范围、扩展名筛选，可折叠面板不影响日常使用
- **用户管理** - 创建、删除、修改用户密码，管理员标识显示
- **管理员权限控制** - 基于角色的访问控制，只有管理员可访问用户管理页面
- **证书管理** - 内置自签名证书生成工具

## 安全特性

- **HTTPS 加密** - 支持 SSL/TLS 加密传输，防止数据窃听
- bcrypt 密码加密（rounds=12），用户密码和分享密码均使用 bcrypt 哈希存储
- 安全会话 ID（secrets.token_hex）
- HttpOnly + SameSite Cookie
- 会话超时机制
- 访问控制（未认证用户重定向到登录页）
- 路径遍历防护（防止 `../` 攻击）
- 文件上传安全（文件名清理、大小限制 100MB）
- 用户数据文件权限限制（0o600）
- 服务器路径信息隐藏（防止信息泄露）
- **管理员权限控制** - 前后端双重验证，非管理员无法访问管理功能
- **目录权限控制** - 前后端双重验证，写操作需 rw 权限，只读用户无法执行删除/重命名/上传等操作
- **访问日志审计** - 记录所有文件操作的用户、时间、路径、详情，支持搜索与分页查看

## 安装

### 基础安装（推荐）

仅安装核心依赖，适合大多数用户：

```bash
pip install pyfileserv
```

**核心依赖**: `bcrypt`（密码加密）、`pillow`（Word 文档图片渲染）、`jinja2`（模板引擎）。

### 完整功能安装

如果需要所有高级功能：

```bash
pip install pyfileserv[full]
```

### 按需安装可选功能

根据需求选择安装：

```bash
# YAML 配置文件支持
pip install pyfileserv[yaml]

# PostgreSQL 数据库支持
pip install pyfileserv[postgres]

# Redis 会话存储支持
pip install pyfileserv[redis]

# Markdown 文件预览支持
pip install pyfileserv[markdown]

# Office 文档预览支持（Word/Excel/PPT）
pip install pyfileserv[office]

# SSL 证书生成工具
pip install pyfileserv[cert]

# 组合安装多个功能
pip install pyfileserv[yaml,postgres,redis]
```

或使用 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） | - |
| `-w, --workers` | 工作线程数（0 = CPU 核数 x 2） | 0（自动） |
| `--log-file` | 日志文件路径 | serve_dir/pyfileserv.log |

### 配置文件

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

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

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

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

#### 配置文件示例

```yaml
# pyfileserv 配置文件

# 服务器配置
server:
  port: 8000
  host: ""
  workers: 0  # 工作线程数（0 = CPU 核数 x 2）

# 路径配置
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:
  # 会话超时时间（秒），默认 1 小时
  timeout: 3600
  # 会话存储方式: memory (内存) 或 redis
  storage: "memory"

# Redis 配置（仅当 session.storage='redis' 时使用）
redis:
  enabled: true
  host: "localhost"
  port: 6379
  db: 0
  password: null
  key_prefix: "pyfileserv:session:"

# 安全配置
security:
  # bcrypt 加密轮数
  bcrypt_rounds: 12
  # 登录保护：最大失败尝试次数
  login_max_attempts: 5
  # 登录保护：锁定时长（秒），默认 15 分钟
  login_lockout_duration: 900

# 权限配置
permissions:
  # 默认权限：rw（读写）或 r（只读）
  # 当用户没有显式配置权限时使用此值
  default_permission: "rw"

# 访问日志配置
access_log:
  # 是否启用访问日志
  enabled: true
  # 日志文件路径（null 表示使用 serve_dir/access.log）
  log_file: null
  # 日志文件轮转大小（MB）
  max_size_mb: 10
  # 保留的旧日志文件数量
  keep: 7
```

#### 使用配置文件

```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
```

### Redis 会话存储配置

pyfileserv 支持将会话数据存储到 Redis，以实现多实例共享会话状态。

#### 使用 Redis 存储会话

1. 安装依赖：
```bash
pip install redis
# 或安装完整功能包
pip install pyfileserv[full]
```

2. 确保 Redis 服务器正在运行：
```bash
# Linux
sudo systemctl start redis

# Windows (如果使用 WSL)
wsl sudo service redis-server start

# macOS
brew services start redis
```

3. 修改配置文件：
```yaml
session:
  timeout: 3600
  storage: "redis"  # 改为 redis

redis:
  enabled: true
  host: "localhost"
  port: 6379
  db: 0
  password: null  # 如果 Redis 设置了密码，在此填写
  key_prefix: "pyfileserv:session:"  # 键前缀，用于隔离不同应用
```

4. 重启服务器即可生效。

#### Redis 配置说明

| 配置项 | 说明 | 默认值 |
|--------|------|--------|
| `enabled` | 是否启用 Redis | `true` |
| `host` | Redis 服务器地址 | `localhost` |
| `port` | Redis 端口 | `6379` |
| `db` | Redis 数据库编号 | `0` |
| `password` | Redis 密码（可选） | `null` |
| `key_prefix` | 键前缀 | `pyfileserv:session:` |

#### 环境变量配置

也可以通过环境变量配置 Redis：

```bash
export PYFILESERV_SESSION_STORAGE=redis
export PYFILESERV_REDIS_ENABLED=true
export PYFILESERV_REDIS_HOST=localhost
export PYFILESERV_REDIS_PORT=6379
export PYFILESERV_REDIS_DB=0
export PYFILESERV_REDIS_PASSWORD=your_redis_password
export PYFILESERV_REDIS_KEY_PREFIX="pyfileserv:session:"
```

#### 使用场景

- **单实例部署**：使用默认的内存存储即可，性能更好
- **多实例/负载均衡**：使用 Redis 存储，实现会话共享
- **容器化部署**：推荐使用 Redis，避免容器重启后会话丢失

### 登录保护配置

pyfileserv 内置登录失败锁定机制，防止暴力破解攻击。

#### 配置说明

```yaml
security:
  # 最大失败尝试次数
  login_max_attempts: 5
  # 锁定时长（秒），900秒 = 15分钟
  login_lockout_duration: 900
```

#### 环境变量配置

```bash
export PYFILESERV_LOGIN_MAX_ATTEMPTS=5
export PYFILESERV_LOGIN_LOCKOUT_DURATION=900
```

#### 推荐配置

| 场景 | 最大尝试次数 | 锁定时长 |
|------|------------|----------|
| 普通系统 | 5次 | 15分钟 |
| 高安全系统 | 3次 | 30分钟 |
| 内部系统 | 10次 | 5分钟 |

#### 工作原理

1. 用户登录失败时，记录失败次数
2. 达到最大尝试次数后，账户被临时锁定
3. 锁定期内无法登录，显示剩余锁定时间
4. 锁定过期后自动解锁
5. 成功登录后清除失败记录

注意：即使用户名不存在也会记录尝试，防止用户名枚举攻击。

### 目录权限控制

pyfileserv 支持细粒度的目录级权限控制，可以为不同用户设置不同目录的读写/只读权限。

#### 权限说明

| 权限 | 说明 |
|------|------|
| `rw` | 读写权限：可以浏览、下载、上传、删除、重命名、移动、复制文件 |
| `r` | 只读权限：只能浏览和下载文件，无法执行写操作 |

#### 默认权限

当用户没有针对某个目录显式配置权限时，使用配置文件中的 `default_permission`（默认为 `rw`）。可通过配置文件或环境变量修改：

```yaml
permissions:
  default_permission: "r"  # 默认只读
```

```bash
export PYFILESERV_DEFAULT_PERMISSION=r
```

#### CLI 管理命令

```bash
# 给用户 alice 授予 project-a 目录的读写权限
pyfileserv user permission -u alice --add project-a rw

# 给用户 bob 授予 public 目录的只读权限
pyfileserv user permission -u bob --add public r

# 移除用户对某个目录的权限设置
pyfileserv user permission -u alice --remove project-a

# 查看用户的所有权限
pyfileserv user permission -u alice --list
```

#### Web 管理界面

管理员可以通过 `/admin/permissions` 页面进行可视化管理：
- 查看所有用户的权限配置
- 多选目录下拉批量添加权限
- 一键移除权限
- 星号通配符 `*` 表示所有目录

#### 权限匹配规则

采用最长前缀匹配策略：
1. 查找与请求路径精确匹配的权限规则
2. 向上回溯父目录，取最长前缀匹配
3. 若未找到任何匹配，使用 `default_permission`
4. 管理员始终拥有所有目录的读写权限

### 访问日志

pyfileserv 自动记录所有文件操作，支持文件（JSON-lines）和 PostgreSQL 两种存储后端。

#### 配置

```yaml
access_log:
  enabled: true         # 是否启用访问日志
  log_file: null        # 日志文件路径（null = serve_dir/access.log）
  max_size_mb: 10       # 日志轮转大小阈值（MB）
  keep: 7               # 保留旧日志文件数量
```

环境变量：
```bash
export PYFILESERV_ACCESS_LOG_ENABLED=true
export PYFILESERV_ACCESS_LOG_FILE=/var/log/pyfileserv/access.log
export PYFILESERV_ACCESS_LOG_MAX_SIZE_MB=50
export PYFILESERV_ACCESS_LOG_KEEP=30
```

#### 记录的操作

`download`、`upload`、`delete`、`rename`、`move`、`copy`、`mkdir`、`preview`、`login`、`logout`

每条日志包含：时间戳、用户名、操作者 IP、操作类型、文件路径、详细信息（如文件大小、目标路径等）。

#### 日志查看

管理员可通过 `/admin/access-log` 页面查看和搜索日志：
- 按用户下拉筛选
- 按操作类型筛选
- 按文件路径下拉筛选
- 按 IP 地址筛选
- 详情模糊搜索
- 分页浏览

### 用户管理命令

```bash
# 创建用户（会询问是否为管理员）
pyfileserv user create [-u 用户名]

# 列出用户（显示 [管理员] 标记）
pyfileserv user list

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

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

# 设置/取消管理员状态
pyfileserv user admin [-u 用户名]

# 管理用户目录权限
pyfileserv user permission -u 用户名 --add 目录名 rw
pyfileserv user permission -u 用户名 --add 目录名 r
pyfileserv user permission -u 用户名 --remove 目录名
pyfileserv user permission -u 用户名 --list
```

#### 管理员权限说明

- **管理员用户**：可以访问 `/admin` 页面，管理所有用户
- **普通用户**：只能浏览和下载文件，无法访问管理功能
- **创建管理员**：使用 `user create` 时回答 "yes"，或创建后用 `user admin` 设置
- **权限验证**：前后端双重检查，非管理员访问管理 API 返回 403 Forbidden

### 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 使用多线程模式处理并发请求，默认自动根据 CPU 核数配置工作线程数。

```bash
# 自动检测（推荐）：工作线程数 = CPU 核数 x 2
pyfileserv

# 手动指定工作线程数
pyfileserv -w 10
pyfileserv --workers 20
```

配置文件方式：

```yaml
server:
  workers: 16  # 手动指定；0 表示自动
```

环境变量：`PYFILESERV_WORKERS=16`

### 推荐配置

| CPU 核数 | 推荐 workers | 适用场景 |
|---------|-------------|---------|
| 2 核 | 4（自动） | 轻量文件服务 / 个人使用 |
| 4 核 | 8（自动） | 小型团队文件共享 |
| 8 核 | 16（自动） | 中型企业文件服务 |
| 16 核 | 32（自动） | 高并发文件预览/下载 |
| 32 核+ | 64（自动）或手动调优 | 大规模部署 |

## 项目结构

```
pyfileserv/
├── .github/
│   └── workflows/
│       └── python-publish.yml  # PyPI 自动发布工作流
├── src/file_server/
│   ├── __init__.py          # 包入口
│   ├── __main__.py          # CLI 入口
│   ├── config.py            # 配置模块
│   ├── db.py                # PostgreSQL 数据库模块
│   ├── handlers.py          # HTTP 请求分发
│   ├── server.py            # 服务器启动
│   ├── cli.py               # 命令行工具
│   ├── core/                # 核心业务模块
│   │   ├── access_log.py    # 访问日志记录（双后端支持）
│   │   ├── auth.py          # 认证（密码哈希、用户存储、会话管理）
│   │   ├── permission.py    # 目录权限检查
│   │   ├── share.py         # 分享业务逻辑层
│   │   ├── share_store.py   # 分享 JSON 存储后端
│   │   └── trash.py         # 回收站管理
│   ├── handle/              # HTTP 请求处理器
│   │   ├── admin.py         # 管理员页面处理（用户/权限/日志）
│   │   ├── auth.py          # 登录/登出处理
│   │   ├── file_ops.py      # 文件操作（上传/下载/删除/重命名/移动/复制/创建目录）
│   │   ├── preview.py       # 文件预览处理
│   │   ├── share.py         # 分享功能处理
│   │   ├── trash.py         # 回收站页面处理
│   │   └── utils.py         # 文件类型检测等工具
│   ├── template/            # HTML 模板渲染
│   │   ├── base.py          # 公共 CSS/JS/工具函数
│   │   ├── access_log_viewer.py  # 访问日志查看页面
│   │   ├── admin.py         # 用户管理页面
│   │   ├── file_list.py     # 文件列表页面
│   │   ├── login.py         # 登录页面
│   │   ├── permission_admin.py   # 权限管理页面
│   │   ├── upload.py        # 文件上传页面
│   │   ├── share_*.py       # 分享相关页面
│   │   ├── trash.py         # 回收站页面
│   │   └── preview/         # 文件预览页面（15 种类型）
│   └── static/              # 静态资源
│       ├── logo.svg
│       ├── favicon.svg
│       ├── css/             # 7 个样式文件
│       └── js/              # 5 个脚本文件
├── tests/                   # 26 个测试模块, 626+ 个测试用例
├── CHANGELOG.md
├── pyproject.toml
└── 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.7

### 核心依赖

- **bcrypt >= 4.0.0** - 密码加密
- **pillow >= 10.4.0** - Word 文档图片处理（EMF/WMF 转 PNG）
- **jinja2 >= 3.1.6** - HTML 模板渲染

### 可选依赖

| 功能 | 依赖包 | 说明 |
|------|--------|------|
| YAML 配置 | `pyyaml>=6.0` | 使用 YAML 格式配置文件 |
| PostgreSQL | `psycopg2-binary>=2.9.0` | 将用户数据存储到 PostgreSQL |
| Redis | `redis>=4.0.0` | 使用 Redis 存储会话数据 |
| Markdown | `markdown>=3.4.0` | Markdown 文件预览渲染 |
| Office | `mammoth`、`Spire.Presentation.Free`、`Spire.Xls.Free` | Word/Excel/PPT 文档预览 |
| SSL 证书 | `cryptography>=41.0.0` | 生成自签名 SSL 证书 |

### 安装示例

```bash
# 基础安装（仅核心功能）
pip install pyfileserv

# 安装所有可选功能
pip install pyfileserv[full]

# 按需安装
pip install pyfileserv[yaml,postgres]  # YAML + PostgreSQL
pip install pyfileserv[redis,markdown]  # Redis + Markdown
```

## 许可证

MIT License
