RouteScope

中文说明 | Repository

RouteScope is a self-hosted operations console for monitoring upstream channels, comparing rates and costs, synchronizing Sub2API accounts, and serving a controlled API relay from one workspace.

Current version: v0.1.0

RouteScope is built for a single trusted operator. It brings upstream status, operational history, routing configuration, notifications, and runtime settings into one local control plane. The primary deployment is Docker Compose with SQLite and a persistent ./data directory.

What It Does

• Overview: summarizes channel health, balances, costs, recent collection facts, and operational risks.
• Channels and accounts: manages NewAPI and Sub2API channels, credentials, monitoring state, favorites, API keys, recharge, redeem, and account checks.
• Activity: brings alerts, upstream announcements, collection facts, and health probes into one timeline.
• Group rates: compares each upstream group's current rate and rate-change history.
• Upstream sync: synchronizes selected channel accounts to Sub2API targets with groups, proxies, model limits, rate conversion, execution logs, and controlled remote actions.
• API relay: exposes a unified /v1 gateway with model mapping, weighted routing, protocol conversion, failover, access keys, direct providers, and usage records.
• Actual costs: shows upstream request usage, token counts, latency, and cost estimates from collected data and relay traffic.
• Notification center: configures notification channels, subscriptions, cooldowns, retry behavior, and delivery history.
• System settings: controls admin authentication, proxy, schedules, retention, backup checks, Captcha providers, version checks, and hot-reloadable runtime settings.

Screenshots

Quick Start

Docker Compose with SQLite

1. Create the local environment file:

   cp .env.example .env

2. Set a stable application secret and enable admin login in .env:

   APP_SECRET=replace-with-a-random-string-at-least-32-bytes
   AUTH_ENABLED=true
   ADMIN_USERNAME=admin
   ADMIN_PASSWORD=replace-with-a-strong-password

3. Start RouteScope:

   docker compose up -d

4. Open http://localhost:8080 and sign in with the configured admin account.

The image is pulled from ghcr.io/owen891/routescope. Change the host port with HTTP_PORT. SQLite data and runtime configuration are stored under ./data:

data/upstream-ops.db
data/config.yaml

Pin a release instead of using latest:

IMAGE_TAG=v0.1.0

Optional MySQL

Use the MySQL overlay when required:

docker compose -f docker-compose.yml -f docker-compose.mysql.yml up -d

Set APP_SECRET, MYSQL_DATABASE, MYSQL_USER, MYSQL_PASSWORD, and MYSQL_ROOT_PASSWORD in .env before starting the stack.

First-Run Tutorial

1. Protect the console

Keep AUTH_ENABLED=true for any host that is not strictly private. Use a strong admin password and put the service behind a reverse proxy or equivalent access control.

APP_SECRET encrypts upstream passwords, cookies, tokens, notification secrets, SMTP passwords, Captcha keys, and Sub2API target keys. Keep it unchanged after data is created.

2. Add upstream channels

Open Channels and accounts and add a NewAPI or Sub2API channel:

1. Enter the site URL and choose the credential mode.
2. Use username/password or token/cookie credentials as supported by the upstream.
3. Enable monitoring and set the low-balance threshold.
4. Save, test login, and run the first balance/rate sync.
5. Review the channel detail and API key actions after the first successful collection.

RouteScope can also use a configured Captcha provider and an HTTP/HTTPS/SOCKS5 proxy for upstream requests.

3. Read the operational state

Use Overview for the current summary. Use Activity to inspect failed collections, health probes, announcements, and alert delivery. Use Group rates to compare source-group rates and review changes before making a routing or synchronization decision.

4. Configure notifications

Open Notification center, add a channel, then create a subscription rule. Rules can receive all events or be limited to selected upstreams and rate groups. Delivery attempts, failures, and cooldown state are retained for troubleshooting.

Supported transports include Telegram, Webhook, Email, WeCom, DingTalk, Feishu, ServerChan3, and QQ Bot where enabled by the current build.

5. Synchronize accounts to Sub2API

Open Upstream sync:

1. Add and test a writable Sub2API target.
2. Synchronize target groups and proxies.
3. Create a sync group and select the source channel, source group, target group, proxy, model limits, concurrency, weight, and rate conversion.
4. Preview the account mapping, then apply it.
5. Inspect execution logs and run an account test when needed.

Remote deletion and other writes are explicit actions. Review the target and sync-group state before applying them.

6. Set up the API relay

Open API relay and configure:

1. A gateway group with retry, failover, cooldown, and ordering policy.
2. One or more routes from monitored channels or direct providers.
3. Model mappings and the model-list mode: auto, manual, or hybrid.
4. A gateway key for client applications.

Clients use the gateway key, not an upstream account key:

Authorization: Bearer sk-your-gateway-key

Common endpoints:

GET  /v1/models
POST /v1/chat/completions
POST /v1/responses
POST /v1/messages
GET  /v1/usage

The relay supports OpenAI Chat/Completions, OpenAI Responses, and Anthropic Messages flows, including streaming conversion where the selected route supports it. Routes can use weighted scheduling, rate conversion, model rewrites, first-token timeout, temporary pause, and failover on upstream errors.

7. Review usage and costs

Open Actual costs to filter relay and upstream usage by model, endpoint, group, success state, and time. Check token counts, latency, request IDs, base cost, and actual cost before changing prices or route ratios.

Configuration

Variable	Purpose
HTTP_PORT	Host port exposed by Compose; defaults to 8080.
IMAGE_TAG	Container image tag; use v0.1.0 for a pinned release.
APP_SECRET	Stable AES-GCM key for encrypted application data. Required.
AUTH_ENABLED	Enables the admin login gate. Use true for public or shared hosts.
ADMIN_USERNAME	Admin login username.
ADMIN_PASSWORD	Admin login password. Required when auth is enabled.
AUTH_TOKEN_SECRET	Optional token signing secret; falls back to APP_SECRET.
DATABASE_DRIVER	sqlite or mysql.
DATABASE_PATH	SQLite path, normally /app/data/upstream-ops.db.
DATABASE_HOST / DATABASE_PORT	MySQL connection settings.
DATABASE_USER / DATABASE_PASSWORD / DATABASE_NAME	MySQL credentials and database name.
SERVER_MODE / LOG_LEVEL	Runtime mode and log level.

Proxy, scheduler, retention, notification, Captcha, upstream HTTP, and API relay settings can be edited in System settings. Authentication, scheduler, notification policy, proxy, upstream HTTP, and relay runtime settings can be applied without restarting the process. Database connection, HTTP port, and log level changes require a restart.

Local Development

Requirements: Go 1.23+, Node.js 20+, and pnpm 10.4.0.

Start the backend:

go run ./cmd/server

The backend listens on http://127.0.0.1:8418 by default.

Start the frontend in another terminal:

cd frontend
pnpm install
pnpm dev

The Vite development server listens on http://127.0.0.1:3010 and proxies API requests to the backend.

Run the main checks:

go test ./...
cd frontend
pnpm lint
pnpm test
pnpm exec tsc --noEmit --incremental false
pnpm build

Backup and Security

• SQLite deployments can use System Settings → Data Backup → Web Backup and Restore to create a consistent snapshot, download its ZIP, or upload a ZIP for restoration. Web restore first creates a safety snapshot, verifies SHA-256 hashes, the database driver, and the APP_SECRET fingerprint, then replaces the database/config and restarts the service. MySQL deployments continue to use the verified server-side helper below; the Web API reports that limitation explicitly.

• Create and verify a tagged snapshot before upgrades, migrations, imports, or remote writes:

  BACKUP_TAG=before-upgrade ./scripts/backup-data.sh backup
  ./scripts/backup-data.sh verify before-upgrade

  On Windows use powershell -ExecutionPolicy Bypass -File scripts/backup-data.ps1 -Command backup and pass -Tag before-upgrade to verify or restore. The helper detects the effective SQLite or MySQL Compose configuration. SQLite snapshots contain the live database and config.yaml; MySQL snapshots contain a verified mysqldump and the same runtime configuration. Database rows cover upstream accounts, notification channels/subscriptions, Captcha/API credentials, sync targets, Gateway providers/keys/routes, and their operational history.

• Restore only a verified tag, then check the health endpoint:

  ./scripts/backup-data.sh restore before-upgrade

  Encrypted credentials require the same APP_SECRET. The manifest stores only its SHA-256 fingerprint and restore refuses a mismatched key; the secret itself is never copied into the snapshot.

• Never change APP_SECRET after encrypted data has been created unless the data has been migrated deliberately.

• Do not place real passwords, API keys, cookies, or tokens in README examples, screenshots, test fixtures, or logs.

• Keep the admin console behind authentication and restrict gateway keys with group status, quotas, IP rules, and route policy where appropriate.

• Review sync previews, execution logs, gateway usage, and notification failures after operational changes.

License

MIT