PyFileServer

PyFileServer 是一套以 Python 開發的跨平台 GUI 檔案伺服器，可在同一個介面管理 HTTP / HTTPS / FTP / TFTP / SCP 服務。

目前版本：v1.2.0

支持作者

如果這個專案對你有幫助，歡迎打賞支持後續維護與功能優化：

你可以用它做什麼

• 單一視窗管理多協定啟停（含 Start All / Stop All）
• 協定層級設定：Bind IP、Port、自動啟動
• 全域來源限制：Allowlist（IP / CIDR）
• 即時上傳/下載速率與服務狀態燈號
• 事件記錄（SQLite）：START / STOP / ERROR / 傳輸事件
• HTTPS 憑證資訊檢視與憑證重建
• 多語系 UI（語言檔位於 pyfileserver/locales/）

支援平台

• Windows
• macOS

環境需求

• Python 3.14.4（建議）
• pip
• Windows 打包時需要：pyinstaller（已列於 requirements.txt）
• Windows 後續統一使用虛擬環境名稱：.venv-win（避免與其他專案衝突）

安裝與啟動（第一次使用）

1. 建立虛擬環境並安裝套件。

Windows (PowerShell)

py -3.14 -m venv .venv-win
.venv-win\Scripts\Activate.ps1
pip install -r requirements.txt

macOS/Linux

python3.14 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

2. 啟動程式。

python main.py

3. 首次啟動時，依畫面選擇共享資料夾（Share Folder）。

UI 操作教學（分頁）

Services

• 設定共享資料夾（Directory）。
• 設定全域允許清單（Allowlist）。
• 每個協定可個別設定：
  • Bind IP
  • Port
  • 啟用/關閉
• 可用 Start All Services / Stop All Services 一鍵控制。
• 右側會顯示每個協定的即時下載/上傳速率。

Logs

• 查看最近操作與傳輸事件。
• 常見事件類型：START、STOP、ERROR、DOWNLOAD_START、UPLOAD_START、DOWNLOAD_COMPLETE、UPLOAD_COMPLETE。
• 可查看欄位：協定、時間、訊息、檔名、大小、錯誤原因、Client IP。

HTTP / HTTPS / FTP / SCP / TFTP

• 每個協定分頁可設定「自動啟動」。
• 按下各自 Save ... Settings 後儲存設定。
• 若該協定正在執行，儲存後會自動重啟該協定套用新設定。

FTP 分頁

• 設定帳號密碼（或啟用匿名）。
• 可開啟 Allow Upload (No Delete)，允許上傳但不允許刪除。

SCP 分頁

• 設定帳號密碼。
• 可開啟 Allow Upload (No Delete)。

HTTPS 分頁

• 查看目前憑證狀態與資訊（Subject/Issuer/Validity）。
• 可重新產生憑證（Regenerate EC Certificate）。
• 憑證到期時會自動重建（依目前專案邏輯）。

TFTP 分頁

• 設定區塊大小、逾時、重試、socket buffer。
• 可啟用/設定 windowsize（RFC 7440）。
• 可啟用 Allow Upload (No Delete)。

Protocol Guide

• 提供常見協定速度、傳輸方式、安全性比較，方便選型。

Setting

• Theme：Light / Dark / Follow System
• Language：多語切換（文字來源為 pyfileserver/locales/*.json）
• 可執行清理動作（依 UI 按鈕）：刪除 Logs、刪除設定、回到出場設定。

多語言支援

本專案支援 UI 多語言切換，語言檔採 text_id -> 文本，位於 pyfileserver/locales/*.json。

目前語言清單：

• English (en)
• 简体中文 (zh-CN)
• 繁體中文 (zh-TW)
• Español (es)
• हिन्दी (hi)
• العربية (ar)
• Français (fr)
• Português (Brasil) (pt-BR)
• Русский (ru)
• 日本語 (ja)
• Deutsch (de)
• 한국어 (ko)
• Italiano (it)
• Türkçe (tr)
• Tiếng Việt (vi)
• Bahasa Indonesia (id)
• ไทย (th)
• Polski (pl)
• Nederlands (nl)
• Svenska (sv)

UI 截圖（各分頁）

Services

Logs

HTTP

FTP

HTTPS

SCP

TFTP

Protocol Guide

Setting

Allowlist 寫法（很重要）

Allowlist 是全域規則，所有協定共用。

可用格式：

• 單一 IP：172.16.3.48
• CIDR：172.16.3.0/24
• 多個條件以逗號分隔：172.16.3.0/24,10.0.0.5

行為說明：

• 不在 Allowlist 內的來源，會被阻擋。
• 阻擋事件會寫入 Logs。

常見使用流程範例

讓網管設備用 FTP 下載設定檔

1. 在 Services 設定 Directory 指到放設定檔的資料夾。
2. 在 FTP 分頁設定帳號密碼。
3. 在 Services 開啟 FTP。
4. 在設備端填入伺服器 IP、帳號、密碼、檔案路徑下載。

只允許上傳，不允許刪除

1. 到 FTP/SCP/TFTP 分頁勾選 Allow Upload (No Delete)。
2. 按 Save ... Settings。
3. 測試客戶端可上傳、不可刪除。

用 HTTPS 給內網瀏覽器下載檔案

1. 開啟 HTTPS 服務。
2. 在瀏覽器輸入 https://<server-ip>:443。
3. 若為自簽憑證，首次需信任例外。

Windows EXE 打包

方法 1（批次檔）：

scripts\build_exe_windows.bat

方法 2（PowerShell）：

.\scripts\build_exe_windows.ps1

輸出檔案： dist/PyFileServer.exe

如果你覺得本機打包流程較麻煩，也可以直接使用作者已打包好的 Windows 執行檔（請至 GitHub Releases 下載對應版本）。

專案目錄說明

main.py                        # 程式入口
pyfileserver/
  app.py                       # 啟動流程
  config.py                    # 設定讀寫
  db.py                        # SQLite 記錄
  transfer.py                  # 速率與傳輸統計
  service_manager.py           # 協定生命週期管理
  servers/                     # 各協定 server 實作
  ui/                          # Qt UI
  locales/                     # 多語系 JSON（text_id -> 文本）
PyFileServer.spec              # PyInstaller 規格
scripts/build_exe_windows.*    # Windows 打包腳本

預設連接埠

• HTTP: 80
• HTTPS: 443
• FTP: 21
• TFTP: 69
• SCP: 22

注意：macOS/Linux 若使用 <1024 連接埠，通常需要較高權限。

疑難排解

• 程式啟動後看不到服務：
  • 檢查連接埠是否被其他程式占用。
  • 把該協定 Port 改為其他值（例如 HTTP 改 8080）。
• 客戶端連不到：
  • 檢查防火牆是否放行連接埠。
  • 檢查 Allowlist 是否包含客戶端 IP。
• 速率顯示異常：
  • 先看 Logs 是否有 ERROR 或 timeout/retry 訊息。
• 語言顯示有缺字：
  • 到 pyfileserver/locales/<lang>.json 補上對應 text_id 文本。

CI 打包（GitHub Actions）

• Workflow：.github/workflows/build-windows-exe.yml
• 可手動觸發 workflow_dispatch
• 推送 v* tag 時可自動打包

License

MIT - see LICENSE