108 lines
2.8 KiB
Markdown
108 lines
2.8 KiB
Markdown
# Hysteria Control Panel
|
||
|
||
|
||
|
||
|
||
|
||
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 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).
|
||
|
||
## Requirements
|
||
|
||
- Python 3.13+ (matches `pyproject.toml`)
|
||
- A running Hysteria server with the API enabled.
|
||
|
||
## Install & Run (uv)
|
||
|
||
From the `hysteria-panel-python` directory:
|
||
|
||
```bash
|
||
# Install dependencies and project in a venv
|
||
uv sync
|
||
|
||
# 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
|
||
```
|
||
|
||
## Testing
|
||
|
||
Run the included unit tests with the standard library `unittest` runner.
|
||
|
||
```bash
|
||
# Using uv
|
||
uv run python -m unittest discover -s tests -v
|
||
|
||
# Or with an activated venv
|
||
python -m unittest discover -s tests -v
|
||
```
|
||
|
||
Run a single test file:
|
||
|
||
```bash
|
||
uv run python -m unittest tests/test_api.py -v
|
||
```
|
||
|
||
## Development
|
||
|
||
Run directly from source without installing (useful while iterating):
|
||
|
||
```bash
|
||
PYTHONPATH=src uv run python -m hysteria_panel
|
||
```
|
||
|
||
## 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.
|