tokenlive-admin

README

TokenLive Admin

中文文档

📖 "In the syntax of code, let governance endure and life remain forever green." — Learn more about the tribute and story behind our name: The Origin of TokenLive.

Introduction

TokenLive Admin is the operations and management console for the TokenLive ecosystem. It manages model providers, models, endpoints, tenant authorization, API keys, RBAC, observability views, and gateway policy configuration. Runtime request execution is handled by TokenLive Gateway; Admin focuses on configuring, auditing, and synchronizing the data that the gateway consumes.

Online Demo

• Demo URL: https://tokenlive.store
• Username: admin
• Password: tokenlive

Features

Resource Management

Manage AI model providers (e.g. OpenAI, Azure, custom endpoints) and their models. Each model can have multiple aliases and endpoints with weighted routing.

Governance Policies

A set of gateway policy configuration pages for managing:

• Tagging Policies — Request tagging rules used by downstream routing
• Route Policies — Tag-based model routing and route detail configuration
• Rate Limiting — Request, token, or cost limit policies with configurable dimensions
• Circuit Breaking — Failure-rate and slow-call based isolation, including TTFT-oriented slow-call metrics and degrade responses
• Load Balancing — Endpoint load-balancing policy configuration
• Invocation Policies — Failfast/failover behavior, retry rules, and fallback response configuration
• Policy Binding — Bind policies by tenant, user, model, and policy priority

RBAC & System Management

• Role-based access control powered by Casbin
• Menu and permission management with resource-group support
• User management with department grouping
• API Key management for downstream client authentication
• Operation log audit

Space Management

Multi-space (tenant-level) resource isolation for organizing providers, models, and policies.

Project Structure

This project uses an integrated frontend-backend architecture:

• Frontend: Vue 3 + Vite + Ant Design Vue
• Backend: Go + Gin + GORM
• Deployment: Multi-stage Docker build, single image containing both frontend and backend

tokenlive-admin/
├── frontend/              # Frontend Vue 3 SPA
│   └── src/
│       ├── apis/modules/  # API service modules (mirrors backend modules)
│       ├── router/routes/ # Route definitions (menu-driven, dynamic)
│       ├── views/         # Page components by domain
│       └── store/         # Pinia state management
├── internal/              # Backend Go code
│   ├── mods/              # Domain modules (rbac, resource, space, policy)
│   │   ├── api/           # HTTP handlers
│   │   ├── biz/           # Business logic
│   │   ├── dal/           # Data access layer (GORM)
│   │   └── schema/        # Data models & DTOs
│   └── wirex/             # Google Wire dependency injection
├── pkg/                   # Shared packages (cachex, gormx, jwtx, middleware, etc.)
├── configs/               # TOML configuration files
├── cmd/                   # CLI commands (start/stop/version)
├── scripts/               # Database init scripts & utilities
├── docs/                  # Swagger docs, ADRs, and specs
├── main.go                # Application entry point
├── Makefile               # Build scripts
└── deploy/                # Docker build and docker-compose files

Tech Stack

Layer	Technology
Frontend	Vue 3, Vite, Ant Design Vue, Pinia
Backend	Go, Gin, GORM, Google Wire
Auth	JWT, Casbin RBAC
Database	MySQL / PostgreSQL / SQLite
Cache	Redis / Badger / In-memory
Deploy	Docker multi-stage, docker-compose

Quick Start

Local Development

1. Prerequisites

• Go 1.19+
• Node.js 18+
• MySQL 5.7+ (or PostgreSQL / SQLite)
• Redis 6.0+ (optional, can use in-memory cache)

2. Initialize Database

Create the database and import the schema:

CREATE DATABASE tokenlive CHARACTER SET utf8mb4 COLLATE utf8mb4_bin;

mysql -u root tokenlive < scripts/init.sql

3. Configure

Edit the backend config in configs/dev/server.toml to match your database and cache settings.

4. Build and Run

# Build frontend and backend, then start
make serve

# Or run backend only (with hot-reload via air)
make start

5. Access

Open your browser and navigate to http://localhost:8040. Default admin credentials:

• Username: admin
• Password: admin

Docker Deployment

# Build image
make docker-build

# Run with Docker Compose (recommended)
cd deploy/docker-compose
docker-compose up -d

See DEPLOY.md (or DEPLOY-zh.md for Chinese) for detailed deployment instructions.

Production Deployment

For production environments, it is highly recommended to use the unified orchestration repository tokenlive-deploy. It provides a production-ready, one-click Docker Compose deployment configuration containing Admin Console, Gateway, Caddy reverse proxy, Redis, and Prometheus. For full setup instructions, see the tokenlive-deploy orchestrated guide in DEPLOY.md (or Chinese version).

Homebrew (macOS Single-Host)

For macOS single-host deployment with Admin + Gateway in one process:

brew tap tokenlive/tokenlive
brew install tokenlive
brew services start tokenlive
# http://127.0.0.1:2525  admin / admin

See tokenlive-standalone for details.

Build Commands

make start             # Run backend with hot-reload (air)
make build             # Build backend binary to bin/tokenlive-admin
make build-frontend    # Build frontend to frontend/dist
make build-all         # Build frontend + backend
make serve             # Build all then start server on :8040
make wire              # Regenerate Wire dependency injection
make swagger           # Regenerate Swagger docs
make docker-build      # Build Docker image
make docker-push       # Build and push image
make clean             # Clean build artifacts
make build-cross-all   # Cross-compile for linux/darwin/windows

Configuration

Frontend

• frontend/.env.dev — Development environment
• frontend/.env.prod — Production environment

Backend (TOML)

Configuration files are located in configs/:

• configs/dev/ — Development (MySQL + Redis)
• configs/prod/ — Production

Key config sections: [General], [Storage], [Storage.DB], [Storage.Cache], [Middleware].

Configuration with Environment Variables

Sensitive configurations (passwords, tokens, connection strings) use environment variable placeholders with defaults. The backend loads .env.local and .env from the config work directory (default: configs/). Create a local environment file for development:

# Copy the example file
cp configs/.env.example configs/.env

# Edit configs/.env with your actual values
vi configs/.env

Environment variable format: ${VAR_NAME:default_value}

Examples:

• ${ROOT_PASSWORD:admin} — Uses admin if ROOT_PASSWORD not set
• ${REDIS_ADDR:localhost:6379} — Uses localhost:6379 if REDIS_ADDR not set
• ${DB_DSN:data/tokenlive-admin.db} — Uses SQLite if DB_DSN not set

The configs/.env file is automatically loaded at startup (not committed to git). Existing system environment variables take precedence over values in the .env file.

API Structure

All APIs are prefixed with /api/v1/. Standard CRUD pattern:

Method	Path	Description
GET	/<resource>	Query list
GET	/<resource>/:id	Get by ID
POST	/<resource>	Create
PUT	/<resource>/:id	Update
DELETE	/<resource>/:id	Delete

Swagger docs are auto-generated from annotations — run make swagger to regenerate.

FAQ

Q: How do I change the frontend API endpoint?

Modify VITE_API_HTTP in frontend/.env.prod, then rebuild.

Q: How do I persist data?

When using Docker Compose, data is automatically mounted to the ./data directory.

Q: How do I view logs?

cd deploy/docker-compose
docker-compose logs -f tokenlive

License

This project is licensed under the Apache License. See the LICENSE file for details.