Add admin UI
Some checks failed
Some checks failed
This commit is contained in:
241
docs/ADMIN_UI.md
Normal file
241
docs/ADMIN_UI.md
Normal file
@@ -0,0 +1,241 @@
|
||||
# Admin Web UI
|
||||
|
||||
The LLM Gateway includes a built-in admin web interface for monitoring and managing the gateway.
|
||||
|
||||
## Features
|
||||
|
||||
### System Information
|
||||
- Version and build details
|
||||
- Platform information (OS, architecture)
|
||||
- Go version
|
||||
- Server uptime
|
||||
- Git commit hash
|
||||
|
||||
### Health Status
|
||||
- Overall system health
|
||||
- Individual health checks:
|
||||
- Server status
|
||||
- Provider availability
|
||||
- Conversation store connectivity
|
||||
|
||||
### Provider Management
|
||||
- View all configured providers
|
||||
- See provider types (OpenAI, Anthropic, Google, etc.)
|
||||
- List models available for each provider
|
||||
- Monitor provider status
|
||||
|
||||
### Configuration Viewing
|
||||
- View current gateway configuration
|
||||
- Secrets are automatically masked for security
|
||||
- Collapsible JSON view
|
||||
- Shows all config sections:
|
||||
- Server settings
|
||||
- Providers
|
||||
- Models
|
||||
- Authentication
|
||||
- Conversations
|
||||
- Logging
|
||||
- Rate limiting
|
||||
- Observability
|
||||
|
||||
## Setup
|
||||
|
||||
### Production Build
|
||||
|
||||
1. **Enable admin UI in config:**
|
||||
```yaml
|
||||
admin:
|
||||
enabled: true
|
||||
```
|
||||
|
||||
2. **Build frontend and backend together:**
|
||||
```bash
|
||||
make build-all
|
||||
```
|
||||
|
||||
This command:
|
||||
- Builds the Vue 3 frontend
|
||||
- Copies frontend assets to `internal/admin/dist`
|
||||
- Embeds assets into the Go binary using `embed.FS`
|
||||
- Compiles the gateway with embedded admin UI
|
||||
|
||||
3. **Run the gateway:**
|
||||
```bash
|
||||
./bin/llm-gateway --config config.yaml
|
||||
```
|
||||
|
||||
4. **Access the admin UI:**
|
||||
Navigate to `http://localhost:8080/admin/`
|
||||
|
||||
### Development Mode
|
||||
|
||||
For faster frontend development with hot reload:
|
||||
|
||||
**Terminal 1 - Backend:**
|
||||
```bash
|
||||
make dev-backend
|
||||
# or
|
||||
go run ./cmd/gateway --config config.yaml
|
||||
```
|
||||
|
||||
**Terminal 2 - Frontend:**
|
||||
```bash
|
||||
make dev-frontend
|
||||
# or
|
||||
cd frontend/admin && npm run dev
|
||||
```
|
||||
|
||||
The frontend dev server runs on `http://localhost:5173` and automatically proxies API requests to the backend on `http://localhost:8080`.
|
||||
|
||||
## Architecture
|
||||
|
||||
### Backend Components
|
||||
|
||||
**Package:** `internal/admin/`
|
||||
|
||||
- `server.go` - AdminServer struct and initialization
|
||||
- `handlers.go` - API endpoint handlers
|
||||
- `routes.go` - Route registration
|
||||
- `response.go` - JSON response helpers
|
||||
- `static.go` - Embedded frontend asset serving
|
||||
|
||||
### API Endpoints
|
||||
|
||||
All admin API endpoints are under `/admin/api/v1/`:
|
||||
|
||||
- `GET /admin/api/v1/system/info` - System information
|
||||
- `GET /admin/api/v1/system/health` - Health checks
|
||||
- `GET /admin/api/v1/config` - Configuration (secrets masked)
|
||||
- `GET /admin/api/v1/providers` - Provider list and status
|
||||
|
||||
### Frontend Components
|
||||
|
||||
**Framework:** Vue 3 + TypeScript + Vite
|
||||
|
||||
**Directory:** `frontend/admin/`
|
||||
|
||||
```
|
||||
frontend/admin/
|
||||
├── src/
|
||||
│ ├── main.ts # App entry point
|
||||
│ ├── App.vue # Root component
|
||||
│ ├── router.ts # Vue Router config
|
||||
│ ├── api/
|
||||
│ │ ├── client.ts # Axios HTTP client
|
||||
│ │ ├── system.ts # System API calls
|
||||
│ │ ├── config.ts # Config API calls
|
||||
│ │ └── providers.ts # Providers API calls
|
||||
│ ├── components/ # Reusable components
|
||||
│ ├── views/
|
||||
│ │ └── Dashboard.vue # Main dashboard view
|
||||
│ └── types/
|
||||
│ └── api.ts # TypeScript type definitions
|
||||
├── index.html
|
||||
├── package.json
|
||||
├── vite.config.ts
|
||||
└── tsconfig.json
|
||||
```
|
||||
|
||||
## Security Features
|
||||
|
||||
### Secret Masking
|
||||
|
||||
All sensitive data is automatically masked in API responses:
|
||||
|
||||
- API keys show only first 4 and last 4 characters
|
||||
- Database connection strings are partially hidden
|
||||
- OAuth secrets are masked
|
||||
|
||||
Example:
|
||||
```json
|
||||
{
|
||||
"api_key": "sk-p...xyz"
|
||||
}
|
||||
```
|
||||
|
||||
### Authentication
|
||||
|
||||
In MVP version, the admin UI inherits the gateway's existing authentication:
|
||||
|
||||
- If `auth.enabled: true`, admin UI requires valid JWT token
|
||||
- If `auth.enabled: false`, admin UI is publicly accessible
|
||||
|
||||
**Note:** Production deployments should always enable authentication.
|
||||
|
||||
## Auto-Refresh
|
||||
|
||||
The dashboard automatically refreshes data every 30 seconds to keep information current.
|
||||
|
||||
## Browser Support
|
||||
|
||||
The admin UI works in all modern browsers:
|
||||
- Chrome/Edge (recommended)
|
||||
- Firefox
|
||||
- Safari
|
||||
|
||||
## Build Process
|
||||
|
||||
### Frontend Build
|
||||
|
||||
```bash
|
||||
cd frontend/admin
|
||||
npm install
|
||||
npm run build
|
||||
```
|
||||
|
||||
Output: `frontend/admin/dist/`
|
||||
|
||||
### Embedding in Go Binary
|
||||
|
||||
The `internal/admin/static.go` file uses Go's `embed` directive:
|
||||
|
||||
```go
|
||||
//go:embed all:dist
|
||||
var frontendAssets embed.FS
|
||||
```
|
||||
|
||||
This embeds all files from the `dist` directory into the compiled binary, creating a single-file deployment artifact.
|
||||
|
||||
### SPA Routing
|
||||
|
||||
The admin UI is a Single Page Application (SPA). The static file server implements fallback to `index.html` for client-side routing, allowing Vue Router to handle navigation.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Admin UI shows 404
|
||||
|
||||
- Ensure `admin.enabled: true` in config
|
||||
- Rebuild with `make build-all` to embed frontend assets
|
||||
- Check that `internal/admin/dist/` exists and contains built assets
|
||||
|
||||
### API calls fail
|
||||
|
||||
- Check that backend is running on port 8080
|
||||
- Verify CORS is not blocking requests (should not be an issue as UI is served from same origin)
|
||||
- Check browser console for errors
|
||||
|
||||
### Frontend won't build
|
||||
|
||||
- Ensure Node.js 18+ is installed: `node --version`
|
||||
- Install dependencies: `cd frontend/admin && npm install`
|
||||
- Check for npm errors in build output
|
||||
|
||||
### Assets not loading
|
||||
|
||||
- Verify Vite config has correct `base: '/admin/'`
|
||||
- Check that asset paths in `index.html` are correct
|
||||
- Ensure Go's embed is finding the dist folder
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
Planned features for future releases:
|
||||
|
||||
- [ ] RBAC with admin/viewer roles
|
||||
- [ ] Audit logging for all admin actions
|
||||
- [ ] Configuration editing (hot reload)
|
||||
- [ ] Provider management (add/edit/delete)
|
||||
- [ ] Model management
|
||||
- [ ] Circuit breaker reset controls
|
||||
- [ ] Real-time metrics and charts
|
||||
- [ ] Request/response inspection
|
||||
- [ ] Rate limit management
|
||||
Reference in New Issue
Block a user