91 lines
3.6 KiB
Markdown
91 lines
3.6 KiB
Markdown
|
# OpenGFW Web UI
|
||
|
|
|
||
|
|
A Vue 3 + Tailwind CSS dashboard for OpenGFW, built with [shadcn/ui](https://ui.shadcn.com)
|
||
|
|
style components on top of [Reka UI](https://reka-ui.com) primitives. It is embedded into
|
||
|
|
the OpenGFW binary and served by the `web` package.
|
||
|
|
|
||
|
|
- **Dashboard** — live counters, traffic chart, verdict/protocol split, top hosts,
|
||
|
|
blocked destinations and triggered rules
|
||
|
|
- **Events** — real-time feed of verdicts, rule logs and errors with filters and a
|
||
|
|
detail view showing raw analyzer properties
|
||
|
|
- **Rules** — visual rule editor and a raw YAML editor, both validated by the engine
|
||
|
|
itself; saving writes the rule file and hot reloads the running engine
|
||
|
|
- **Analyzers** — which analyzers are compiled in and how much traffic each one saw
|
||
|
|
- **Settings** — theme (light/dark/system), language (English/中文) and instance info
|
||
|
|
|
||
|
|
The layout is responsive: a sidebar on desktop, a bottom tab bar and bottom-sheet
|
||
|
|
dialogs on phones.
|
||
|
|
|
||
|
|
## Enabling it
|
||
|
|
|
||
|
|
```yaml
|
||
|
|
# config.yaml
|
||
|
|
web:
|
||
|
|
enabled: true
|
||
|
|
listen: :8080
|
||
|
|
secret: your-password-here
|
||
|
|
# cert: /path/to/fullchain.pem
|
||
|
|
# key: /path/to/privkey.pem
|
||
|
|
```
|
||
|
|
|
||
|
|
If `secret` is empty a random password is generated and printed to the log on startup.
|
||
|
|
|
||
|
|
## Layout
|
||
|
|
|
||
|
|
```
|
||
|
|
web/
|
||
|
|
├── api.go HTTP handlers (JSON API + SSE)
|
||
|
|
├── auth.go password login, session tokens
|
||
|
|
├── hub.go statistics collection and the live event fan-out
|
||
|
|
├── server.go routes, static file serving, public types
|
||
|
|
├── embed.go //go:embed of dist
|
||
|
|
├── devserver/ standalone server with synthetic data (any OS)
|
||
|
|
├── dist/ built UI, embedded into the binary (committed)
|
||
|
|
└── frontend/ Vue sources
|
||
|
|
```
|
||
|
|
|
||
|
|
## Development
|
||
|
|
|
||
|
|
The engine only builds on Linux, so for UI work there is a standalone server that
|
||
|
|
feeds the UI synthetic traffic and an in-memory ruleset:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
go run ./web/devserver # http://127.0.0.1:8080, password: opengfw
|
||
|
|
```
|
||
|
|
|
||
|
|
Then, in another terminal, run Vite with hot reload (it proxies `/api` to `:8080`):
|
||
|
|
|
||
|
|
```bash
|
||
|
|
cd web/frontend
|
||
|
|
npm install
|
||
|
|
npm run dev
|
||
|
|
```
|
||
|
|
|
||
|
|
To produce the embedded build (this is what `make web` runs):
|
||
|
|
|
||
|
|
```bash
|
||
|
|
cd web/frontend && npm run build # writes ../dist
|
||
|
|
```
|
||
|
|
|
||
|
|
`web/dist` is committed so that `go build` works without Node installed. Rebuild it
|
||
|
|
whenever you change the frontend.
|
||
|
|
|
||
|
|
## API
|
||
|
|
|
||
|
|
All endpoints live under `/api/v1` and return JSON. Except for `login`, every request
|
||
|
|
must carry `Authorization: Bearer <token>`; `GET` endpoints also accept the session
|
||
|
|
cookie set at login, which is what the `EventSource` connection uses. Mutating
|
||
|
|
endpoints only accept the bearer token, which makes them immune to CSRF.
|
||
|
|
|
||
|
|
| Method | Path | Description |
|
||
|
|
| ---------- | -------------------- | -------------------------------------------------- |
|
||
|
|
| `POST` | `/login` | exchange the password for a session token |
|
||
|
|
| `POST` | `/logout` | invalidate the current session |
|
||
|
|
| `GET` | `/info` | version, platform and engine configuration |
|
||
|
|
| `GET` | `/meta` | available analyzers, modifiers, actions, functions |
|
||
|
|
| `GET` | `/metrics` | counters, time series and top N lists |
|
||
|
|
| `GET` | `/events?limit=` | recent events from the ring buffer |
|
||
|
|
| `GET` | `/live` | server-sent events: `event` and `metrics` frames |
|
||
|
|
| `GET/PUT` | `/rules` | read / replace the ruleset (`raw` YAML or `rules`) |
|
||
|
|
| `POST` | `/rules/validate` | compile without applying; also converts YAML ⇄ rules |
|