Update Readme
This commit is contained in:
Yunxiao Xu
115
README.md
115
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.
|
||||
|
||||
|
||||
|
||||
|
||||
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
|
||||
|
||||
- **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.
|
||||
|
||||
Reference in New Issue
Block a user