English | 中文

A lightweight Hetzner traffic dashboard + automation monitor. Includes a web UI, Telegram alerts/commands, auto rebuilds, and DNS checks.

Table of Contents

• Quick Start
• Screenshots
• Highlights
• Use Cases
• Install Options
• Prerequisites
• Config Setup
• Telegram Setup
• Config File Locations
• Troubleshooting
• Project Layout
• GitHub Collaboration
• FAQ
• Security Notes

---

Quick Start

If this is your first time, use the all-in-one script to install Web + automation + Telegram support in one go.

curl -fsSL https://raw.githubusercontent.com/liuweiqiang0523/Hetzner-Web/main/scripts/install-all.sh | sudo bash

Then continue with Config Setup below.

---

Screenshots

---

Highlights

---

Use Cases

Short and practical: this is built for bandwidth caps, night-time ops, and fast actions from Telegram. Use it when you want visibility first, automation second, and manual control always nearby.

---

Install Options

Use the all-in-one script to install Web dashboard + traffic monitor in one go:

curl -fsSL https://raw.githubusercontent.com/liuweiqiang0523/Hetzner-Web/main/scripts/install-all.sh | sudo bash

Existing deployments are safe. To update an existing install:

curl -fsSL https://raw.githubusercontent.com/liuweiqiang0523/Hetzner-Web/main/scripts/install-all.sh | sudo ALLOW_UPDATE=1 bash

---

Prerequisites

Make sure these commands exist:

git --version
python3 --version
docker --version
docker compose version
systemctl --version

If any are missing, install them first (Ubuntu/Debian: apt).

---

Config Setup

Web config

• config.yaml: set hetzner.api_token
• web_config.json: set username / password (example defaults are admin / CHANGE_ME, must change)

Automation config

• automation/config.yaml: set Hetzner/Telegram/Cloudflare if needed

Optional tuning

• cloudflare.update_retries, cloudflare.update_retry_delay, cloudflare.rebuild_sync_delay_seconds for DNS retry + post-rebuild sync
• qbittorrent.rebuild_cooldown_seconds, qbittorrent.instances[].login_retries, qbittorrent.instances[].login_retry_delay for login retry + cooldown
• Telegram: /dnsync to force a DNS sync on demand
• report_state.json is backed up daily to report_state_backups/ (keeps the latest 3 files)

Apply changes:

cd /opt/hetzner-web

docker compose up -d --build
sudo systemctl restart hetzner-web.service

Open: http://<your-server-ip>:1227

---

Telegram Setup

In automation/config.yaml:

telegram:
  enabled: true
  bot_token: "YOUR_BOT_TOKEN"
  chat_id: "YOUR_CHAT_ID"

Then restart automation:

sudo systemctl restart hetzner-web.service

---

Config File Locations

• Web: /opt/hetzner-web/config.yaml
• Web login: /opt/hetzner-web/web_config.json
• Automation: /opt/hetzner-web/automation/config.yaml

---

Troubleshooting

Quick checks:

• docker ps
• sudo systemctl status hetzner-web.service
• sudo journalctl -u hetzner-web.service -n 50 --no-pager

---

Project Layout

• Web Dashboard (app/): Modular FastAPI architecture
  • app/main.py: Entry point and background task lifecycle
  • app/api/: REST API route definitions
  • app/services/: Integrations (Hetzner, Telegram, Cloudflare, qBittorrent)
  • app/tasks/: Traffic monitoring and scheduling loops
  • app/core/: Configuration and global state
  • app/utils/: Statistics and formatting helpers
• Frontend (static/): Compiled Vue assets
• Automation Scripts (automation/): Standalone monitor logic (CLI/systemd)

---

GitHub Collaboration

This repository includes basic GitHub collaboration guardrails:

• CI workflow: .github/workflows/ci.yml
  • Runs Python compile checks on push and pull requests
• PR template: .github/pull_request_template.md

Recommended contributor flow:

git checkout -b feat/your-change
# edit files
python3 -m py_compile app/*.py app/*/*.py automation/*.py
git add .
git commit -m "feat: your change"
git push origin feat/your-change
# then open a PR on GitHub

---

FAQ

Q: The dashboard doesn't open. What should I check first?
A: Make sure port 1227 is open and confirm containers are running with docker ps.

Q: Telegram messages are not arriving.
A: Verify bot_token and chat_id in automation/config.yaml, then restart the service.

Q: I edited configs but nothing changed.
A: Rebuild web with docker compose up -d --build and restart automation with systemctl restart.

Q: DNS points to the old IP after a rebuild. What should I do?
A: Run /dnsync or /dnstest <ID> in Telegram to force an update, then verify with /dnscheck <ID>. If it still points to the old IP, confirm the Cloudflare record exists, token permissions are correct, and the new server has an IPv4 assigned.

Q: Where are my config files stored?
A: Web configs live in /opt/hetzner-web/ and automation config is in /opt/hetzner-web/automation/.

Q: Which install should I choose?
A: Most users should pick the all-in-one script; only choose web-only or automation-only if you know you need just one.

Q: Can I re-run the install script safely?
A: The all-in-one script exits if the install dir exists unless you set ALLOW_UPDATE=1.

---

Security Notes

• config.yaml / web_config.json / automation/config.yaml are sensitive. Do not commit them.
• Use HTTPS reverse proxy for public access.