Update Readme
This commit is contained in:
115
README.md
115
README.md
@@ -1,62 +1,81 @@
|
|||||||
# Hysteria Control Panel
|
# 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.
|

|
||||||
|

|
||||||
|

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

|

|
||||||
|
|
||||||
## Features
|
## Features
|
||||||
|
|
||||||
- **Secure Connection**: Connect to your Hysteria server's API using its address, port, and secret.
|
- Secure connection with API secret; optional HTTPS toggle.
|
||||||
- **Connection Profiles**: Save connection details (except for the secret, optionally) for quick access.
|
- Connection profiles: remember host/port; optionally save the secret.
|
||||||
- **Traffic Monitoring**: View real-time and total data usage (Upload/Download) for all users.
|
- Traffic monitoring: live TX/RX per user.
|
||||||
- **Online User Management**: See a list of currently connected users and their IP addresses.
|
- Online users: view connections and kick selected users.
|
||||||
- **User Disconnection**: Forcefully disconnect (kick) one or more users from the server.
|
- Active streams viewer: JSON or plain-text view.
|
||||||
- **Active Stream Viewer**: Monitor the active data streams on the server.
|
- Auto-refresh every 2 seconds (toggleable).
|
||||||
- **Auto-Refresh**: Automatically updates statistics every 2 seconds to provide a live view of the server status.
|
|
||||||
|
|
||||||
## Technical Details
|
## Requirements
|
||||||
|
|
||||||
This application is built with Python and leverages the following libraries:
|
- Python 3.13+ (matches `pyproject.toml`)
|
||||||
|
|
||||||
- **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+
|
|
||||||
- A running Hysteria server with the API enabled.
|
- A running Hysteria server with the API enabled.
|
||||||
|
|
||||||
### Installation & Running
|
## Install & Run (uv)
|
||||||
|
|
||||||
1. **Clone the repository:**
|
From the `hysteria-panel-python` directory:
|
||||||
```bash
|
|
||||||
git clone https://github.com/your-username/hysteria-panel.git
|
|
||||||
cd hysteria-panel
|
|
||||||
```
|
|
||||||
|
|
||||||
2. **Install dependencies:**
|
```bash
|
||||||
```bash
|
# Install dependencies and project in a venv
|
||||||
pip install -r requirements.txt
|
uv sync
|
||||||
```
|
|
||||||
|
|
||||||
3. **Run the application:**
|
# Launch the GUI via entry point
|
||||||
```bash
|
uv run hysteria-panel
|
||||||
python -m src.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.
|
||||||
|
|||||||
@@ -1,4 +1,4 @@
|
|||||||
from typing import Any, Dict, List, Optional, Any, Tuple
|
from typing import Any, Dict, List, Optional, Tuple
|
||||||
import requests
|
import requests
|
||||||
|
|
||||||
from . import __version__
|
from . import __version__
|
||||||
|
|||||||
2
uv.lock
generated
2
uv.lock
generated
@@ -44,7 +44,7 @@ wheels = [
|
|||||||
|
|
||||||
[[package]]
|
[[package]]
|
||||||
name = "hysteria-panel"
|
name = "hysteria-panel"
|
||||||
version = "0.2.3"
|
version = "0.3.0"
|
||||||
source = { editable = "." }
|
source = { editable = "." }
|
||||||
dependencies = [
|
dependencies = [
|
||||||
{ name = "requests" },
|
{ name = "requests" },
|
||||||
|
|||||||
Reference in New Issue
Block a user