Update Readme

This commit is contained in:
Yunxiao Xu
2025-09-19 05:08:53 -07:00
parent 4c34e350dd
commit b08bab5266
3 changed files with 69 additions and 50 deletions

103
README.md
View File

@@ -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. ![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) ![Hysteria Control Panel Screenshot](screenshot.png)
## 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)
From the `hysteria-panel-python` directory:
1. **Clone the repository:**
```bash ```bash
git clone https://github.com/your-username/hysteria-panel.git # Install dependencies and project in a venv
cd hysteria-panel uv sync
# Launch the GUI via entry point
uv run hysteria-panel
# Alternatively run the module directly
uv run -m hysteria_panel
``` ```
2. **Install dependencies:** If you prefer pip:
```bash ```bash
pip install -r requirements.txt python -m venv .venv
. .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -e .
hysteria-panel
``` ```
3. **Run the application:** ## 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 ```bash
python -m src.hysteria_panel 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.

View File

@@ -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
View File

@@ -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" },