diff --git a/README.md b/README.md index b6d3b90..16c2c9f 100644 --- a/README.md +++ b/README.md @@ -1,62 +1,81 @@ # Hysteria Control Panel -A desktop GUI application for managing and monitoring a Hysteria server. This control panel provides a user-friendly interface to interact with the Hysteria server's API, allowing administrators to view server statistics and manage users. +![Static Badge](https://img.shields.io/badge/ver-0.3.0-blue) +![Static Badge](https://img.shields.io/badge/python-3.13%2B-blue) +![Static Badge](https://img.shields.io/badge/license-MIT-green) + +A desktop GUI application for managing and monitoring a Hysteria2 server. It communicates with the server's HTTP API and presents live stats and controls in a modern Tk/ttkbootstrap UI. ![Hysteria Control Panel Screenshot](screenshot.png) ## Features -- **Secure Connection**: Connect to your Hysteria server's API using its address, port, and secret. -- **Connection Profiles**: Save connection details (except for the secret, optionally) for quick access. -- **Traffic Monitoring**: View real-time and total data usage (Upload/Download) for all users. -- **Online User Management**: See a list of currently connected users and their IP addresses. -- **User Disconnection**: Forcefully disconnect (kick) one or more users from the server. -- **Active Stream Viewer**: Monitor the active data streams on the server. -- **Auto-Refresh**: Automatically updates statistics every 2 seconds to provide a live view of the server status. +- Secure connection with API secret; optional HTTPS toggle. +- Connection profiles: remember host/port; optionally save the secret. +- Traffic monitoring: live TX/RX per user. +- Online users: view connections and kick selected users. +- Active streams viewer: JSON or plain-text view. +- Auto-refresh every 2 seconds (toggleable). -## Technical Details +## Requirements -This application is built with Python and leverages the following libraries: - -- **UI Framework**: [ttkbootstrap](https://github.com/israel-dryer/ttkbootstrap) - - The user interface is built using `ttkbootstrap`, a theme extension for Python's standard `tkinter` GUI library. It provides modern and professional-looking widgets. -- **API Communication**: [requests](https://requests.readthedocs.io/en/latest/) - - The `requests` library is used to handle all HTTP communication with the Hysteria server's REST API. -- **Configuration**: - - Connection profiles are stored locally in a `config.json` file located in the user's system-specific configuration directory (`~/.config/hysteria_panel/` on Linux/macOS). - -### Project Structure - -The project is organized into several modules: - -- `src/hysteria_panel/`: Main package directory. - - `__main__.py`: The main entry point of the application. - - `gui.py`: Handles the main application window, layout, connection logic, and tab management. - - `api.py`: Contains the `HysteriaAPI` class, which encapsulates all the logic for making API calls to the server. - - `utils.py`: Provides helper functions for formatting data (e.g., bytes to KB/MB/GB) and managing the configuration file. - - `views/`: A sub-package containing the different UI tabs (Traffic, Online Users, Streams) as separate modules for better organization. - -## Getting Started - -### Prerequisites - -- Python 3.12+ +- Python 3.13+ (matches `pyproject.toml`) - A running Hysteria server with the API enabled. -### Installation & Running +## Install & Run (uv) -1. **Clone the repository:** - ```bash - git clone https://github.com/your-username/hysteria-panel.git - cd hysteria-panel - ``` +From the `hysteria-panel-python` directory: -2. **Install dependencies:** - ```bash - pip install -r requirements.txt - ``` +```bash +# Install dependencies and project in a venv +uv sync -3. **Run the application:** - ```bash - python -m src.hysteria_panel - ``` +# Launch the GUI via entry point +uv run hysteria-panel + +# Alternatively run the module directly +uv run -m hysteria_panel +``` + +If you prefer pip: + +```bash +python -m venv .venv +. .venv/bin/activate # Windows: .venv\Scripts\activate +pip install -e . +hysteria-panel +``` + +## Configuration + +- Connection settings are stored in `~/.config/hysteria_panel/config.json` (Linux/macOS). On Windows, the same path under your user profile is used. +- The “Use HTTPS” option switches the API scheme to `https://{host}:{port}`. Certificates are verified by default. + - If your server uses a self-signed certificate and you need to disable verification, you can add an option—open an issue or PR. + +## Project Structure + +- `src/hysteria_panel/` package + - `__main__.py` – application entry point + - `gui.py` – main window and tab layout + - `api.py` – `HysteriaAPI` client + - `utils.py` – formatting and config helpers + - `views/` – tab views (Traffic, Online Users, Streams, Login) + +## Build + +Build wheel/sdist artifacts to `dist/`: + +```bash +uv build +``` + +Install the built wheel elsewhere: + +```bash +uv pip install dist/*.whl +``` + +## Troubleshooting + +- No module named `hysteria-panel`: ensure the project is installed (`uv sync` or `pip install -e .`). +- Cannot connect: verify host/port/secret and whether HTTPS is required. diff --git a/src/hysteria_panel/api.py b/src/hysteria_panel/api.py index 7163805..e2e61f0 100644 --- a/src/hysteria_panel/api.py +++ b/src/hysteria_panel/api.py @@ -1,4 +1,4 @@ -from typing import Any, Dict, List, Optional, Any, Tuple +from typing import Any, Dict, List, Optional, Tuple import requests from . import __version__ diff --git a/uv.lock b/uv.lock index 709b7bf..336707e 100644 --- a/uv.lock +++ b/uv.lock @@ -44,7 +44,7 @@ wheels = [ [[package]] name = "hysteria-panel" -version = "0.2.3" +version = "0.3.0" source = { editable = "." } dependencies = [ { name = "requests" },