Feat : Gitbook

2026-09-22 20:00:47 +00:00 · 2026-05-11 11:50:24 +07:00
parent 7ad538bcf2
commit fd92af77a0
124 changed files with 34154 additions and 4 deletions
@@ -0,0 +1,478 @@
+# Installation
+
+Detailed installation guide for 9Router with troubleshooting tips.
+
+---
+
+## Requirements
+
+### System Requirements
+
+- **Node.js**: Version 20.0.0 or higher
+- **npm**: Version 10.0.0 or higher (comes with Node.js)
+- **OS**: macOS, Linux, Windows (WSL recommended)
+- **Disk Space**: ~200MB for installation
+
+### Check Your Version
+
+```bash
+node --version
+# Should show v20.x.x or higher
+
+npm --version
+# Should show 10.x.x or higher
+```
+
+**Don't have Node.js?** Install from [nodejs.org](https://nodejs.org/)
+
+---
+
+## Installation Methods
+
+### Method 1: Global Installation (Recommended)
+
+Install 9Router globally to use from anywhere:
+
+```bash
+npm install -g 9router
+```
+
+**Start 9Router:**
+
+```bash
+9router
+```
+
+**Benefits:**
+- ✅ Run from any directory
+- ✅ Simple command: `9router`
+- ✅ Auto-updates with `npm update -g 9router`
+
+### Method 2: Local Installation
+
+Install in a specific project:
+
+```bash
+mkdir my-9router
+cd my-9router
+npm install 9router
+```
+
+**Start 9Router:**
+
+```bash
+npx 9router
+```
+
+**Benefits:**
+- ✅ Isolated per project
+- ✅ Version control per project
+- ✅ No global namespace pollution
+
+### Method 3: From Source (Development)
+
+Clone and build from GitHub:
+
+```bash
+git clone https://github.com/decolua/9router.git
+cd 9router/app
+npm install
+npm run build
+npm start
+```
+
+**Benefits:**
+- ✅ Latest development features
+- ✅ Contribute to development
+- ✅ Custom modifications
+
+---
+
+## First Run
+
+### Start the Server
+
+```bash
+9router
+```
+
+**What happens:**
+1. Server starts on `http://localhost:20128`
+2. Dashboard opens automatically in browser
+3. Data directory created at `~/.9router`
+4. API key generated automatically
+
+### Dashboard Login
+
+**Default credentials:**
+- Password: `123456`
+
+**⚠️ Change password immediately:**
+1. Login to dashboard
+2. Settings → Change Password
+3. Use strong password
+
+### Get Your API Key
+
+```
+Dashboard → Settings → API Keys
+→ Copy your API key
+→ Use in CLI tools
+```
+
+**Example API key format:**
+```
+9r_1234567890abcdef1234567890abcdef
+```
+
+---
+
+## Verify Installation
+
+### Check Server Status
+
+```bash
+curl http://localhost:20128/health
+```
+
+**Expected response:**
+```json
+{
+  "status": "ok",
+  "version": "1.0.0"
+}
+```
+
+### List Available Models
+
+```bash
+curl http://localhost:20128/v1/models \
+  -H "Authorization: Bearer your-api-key"
+```
+
+**Expected response:**
+```json
+{
+  "object": "list",
+  "data": [
+    {
+      "id": "cc/claude-opus-4-5-20251101",
+      "object": "model",
+      "created": 1234567890,
+      "owned_by": "claude-code"
+    }
+  ]
+}
+```
+
+### Test Chat Completion
+
+```bash
+curl http://localhost:20128/v1/chat/completions \
+  -H "Authorization: Bearer your-api-key" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "cc/claude-opus-4-5-20251101",
+    "messages": [
+      {"role": "user", "content": "Hello!"}
+    ]
+  }'
+```
+
+---
+
+## Configuration
+
+### Environment Variables
+
+Create `.env` file or set environment variables:
+
+```bash
+# Security (REQUIRED in production)
+export JWT_SECRET="your-secure-secret-change-this"
+export INITIAL_PASSWORD="your-password"
+
+# Storage
+export DATA_DIR="~/.9router"
+
+# Server
+export PORT="20128"
+export NODE_ENV="production"
+
+# Logging
+export ENABLE_REQUEST_LOGS="false"
+```
+
+### Data Directory
+
+**Default location:** `~/.9router`
+
+**Contents:**
+```
+~/.9router/
+  ├── db.json           # Database (providers, combos, usage)
+  ├── api-keys.json     # API keys
+  └── logs/             # Request logs (if enabled)
+```
+
+**Change location:**
+
+```bash
+export DATA_DIR="/custom/path"
+9router
+```
+
+### Port Configuration
+
+**Default port:** `20128`
+
+**Change port:**
+
+```bash
+export PORT="3000"
+9router
+```
+
+**Or use command line:**
+
+```bash
+9router --port 3000
+```
+
+---
+
+## Troubleshooting
+
+### Port Already in Use
+
+**Error:**
+```
+Error: listen EADDRINUSE: address already in use :::20128
+```
+
+**Solution 1: Kill existing process**
+
+```bash
+# Find process using port 20128
+lsof -i :20128
+
+# Kill process
+kill -9 <PID>
+```
+
+**Solution 2: Use different port**
+
+```bash
+9router --port 3000
+```
+
+### Permission Denied
+
+**Error:**
+```
+Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules/9router'
+```
+
+**Solution: Use sudo (not recommended) or fix npm permissions**
+
+```bash
+# Fix npm permissions (recommended)
+mkdir ~/.npm-global
+npm config set prefix '~/.npm-global'
+echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
+source ~/.bashrc
+
+# Then install again
+npm install -g 9router
+```
+
+### Node.js Version Too Old
+
+**Error:**
+```
+Error: The engine "node" is incompatible with this module
+```
+
+**Solution: Update Node.js**
+
+```bash
+# Using nvm (recommended)
+nvm install 20
+nvm use 20
+
+# Or download from nodejs.org
+```
+
+### Dashboard Not Opening
+
+**Issue:** Dashboard doesn't open automatically
+
+**Solution 1: Open manually**
+
+```
+http://localhost:20128
+```
+
+**Solution 2: Check firewall**
+
+```bash
+# macOS: Allow Node.js in System Preferences → Security
+# Linux: Check iptables
+# Windows: Check Windows Firewall
+```
+
+### Cannot Connect to Providers
+
+**Issue:** OAuth login fails or API key invalid
+
+**Solution 1: Check internet connection**
+
+```bash
+ping google.com
+```
+
+**Solution 2: Check provider status**
+
+- Claude Code: [status.anthropic.com](https://status.anthropic.com)
+- OpenAI: [status.openai.com](https://status.openai.com)
+- Gemini: [status.cloud.google.com](https://status.cloud.google.com)
+
+**Solution 3: Regenerate API key**
+
+```
+Dashboard → Provider → Disconnect → Reconnect
+```
+
+### High Memory Usage
+
+**Issue:** 9Router using too much RAM
+
+**Solution: Restart server**
+
+```bash
+# Stop
+pkill -f 9router
+
+# Start
+9router
+```
+
+**Or use PM2 for auto-restart:**
+
+```bash
+npm install -g pm2
+pm2 start 9router --name 9router
+pm2 save
+```
+
+---
+
+## Deployment Options
+
+### Local Development
+
+```bash
+npm install -g 9router
+9router
+```
+
+**Use case:** Personal coding, testing
+
+### VPS/Cloud Server
+
+```bash
+# Install
+npm install -g 9router
+
+# Configure
+export JWT_SECRET="your-secure-secret"
+export INITIAL_PASSWORD="your-password"
+export NODE_ENV="production"
+
+# Start with PM2
+npm install -g pm2
+pm2 start 9router --name 9router
+pm2 save
+pm2 startup
+```
+
+**Use case:** Team access, remote coding
+
+### Docker
+
+```bash
+docker pull 9router/9router:latest
+
+docker run -d \
+  -p 20128:20128 \
+  -e JWT_SECRET="your-secure-secret" \
+  -e INITIAL_PASSWORD="your-password" \
+  -v 9router-data:/root/.9router \
+  --name 9router \
+  9router/9router:latest
+```
+
+**Use case:** Containerized deployment, Kubernetes
+
+### Reverse Proxy (Nginx)
+
+```nginx
+server {
+    listen 80;
+    server_name your-domain.com;
+
+    location / {
+        proxy_pass http://localhost:20128;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection 'upgrade';
+        proxy_set_header Host $host;
+        
+        # SSE support for streaming
+        proxy_buffering off;
+        proxy_read_timeout 86400;
+    }
+}
+```
+
+**Use case:** HTTPS, custom domain, load balancing
+
+---
+
+## Uninstallation
+
+### Remove Global Installation
+
+```bash
+npm uninstall -g 9router
+```
+
+### Remove Data Directory
+
+```bash
+rm -rf ~/.9router
+```
+
+### Remove Configuration
+
+```bash
+# Remove environment variables from shell config
+nano ~/.bashrc  # or ~/.zshrc
+# Delete 9router-related exports
+```
+
+---
+
+## Next Steps
+
+- [Getting Started Guide](../getting-started.md) - Connect providers and start coding
+- [Features](../features/) - Explore quota tracking, combos, deployment
+- [Troubleshooting](../troubleshooting.md) - Fix common issues
+
+---
+
+## Need Help?
+
+- **Website**: [9router.com](https://9router.com)
+- **GitHub**: [github.com/decolua/9router](https://github.com/decolua/9router)
+- **Issues**: [github.com/decolua/9router/issues](https://github.com/decolua/9router/issues)
@@ -0,0 +1,247 @@
+# Getting Started
+
+Get 9Router running in 5 minutes and start routing AI requests intelligently.
+
+---
+
+## Quick Start
+
+### 1. Install
+
+```bash
+npm install -g 9router
+```
+
+**Requirements:** Node.js 20+ ([Installation details](getting-started/installation.md))
+
+### 2. Start
+
+```bash
+9router
+```
+
+🎉 **Dashboard opens automatically** at `http://localhost:20128`
+
+- Default password: `123456` (change in dashboard)
+- API key generated automatically
+- Ready to connect providers
+
+### 3. Connect Providers
+
+You have 3 ways to connect providers:
+
+#### Option A: OAuth (Subscription Providers)
+
+**Best for:** Claude Code, Codex, Gemini CLI, GitHub Copilot
+
+```
+Dashboard → Providers → Connect [Provider]
+→ OAuth login → Auto token refresh
+→ Quota tracking enabled
+```
+
+**Example: Claude Code**
+1. Click "Connect Claude Code"
+2. Login with your Claude account
+3. Authorize 9Router
+4. ✅ Done! Use model: `cc/claude-opus-4-5-20251101`
+
+#### Option B: API Key (Cheap Providers)
+
+**Best for:** GLM, MiniMax, Kimi, OpenRouter
+
+```
+Dashboard → Providers → Add API Key
+→ Select provider
+→ Paste API key
+→ Save
+```
+
+**Example: GLM-4.7**
+1. Sign up at [Zhipu AI](https://open.bigmodel.cn/)
+2. Get API key from Coding Plan
+3. Dashboard → Add API Key → Provider: `glm` → Paste key
+4. ✅ Done! Use model: `glm/glm-4.7`
+
+#### Option C: Free Providers (No Cost)
+
+**Best for:** iFlow, Qwen, Kiro
+
+```
+Dashboard → Providers → Connect [Free Provider]
+→ Device code or OAuth
+→ Unlimited usage
+```
+
+**Example: iFlow**
+1. Click "Connect iFlow"
+2. Login with iFlow account
+3. Authorize
+4. ✅ Done! Use 8 models: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, etc.
+
+---
+
+## 4. Use in CLI Tools
+
+Point your coding tool to 9Router:
+
+### Cursor IDE
+
+```
+Settings → Models → Advanced:
+  OpenAI API Base URL: http://localhost:20128/v1
+  OpenAI API Key: [from 9router dashboard]
+  Model: cc/claude-opus-4-5-20251101
+```
+
+### Claude Desktop
+
+Edit `~/.claude/config.json`:
+
+```json
+{
+  "anthropic_api_base": "http://localhost:20128/v1",
+  "anthropic_api_key": "your-9router-api-key"
+}
+```
+
+### Cline / Continue / RooCode
+
+```
+Provider: OpenAI Compatible
+Base URL: http://localhost:20128/v1
+API Key: [from dashboard]
+Model: cc/claude-opus-4-5-20251101
+```
+
+### Codex CLI
+
+```bash
+export OPENAI_BASE_URL="http://localhost:20128"
+export OPENAI_API_KEY="your-9router-api-key"
+
+codex "your prompt"
+```
+
+---
+
+## 5. Create Smart Combos (Optional)
+
+Combos enable automatic fallback between models:
+
+```
+Dashboard → Combos → Create New
+
+Name: premium-coding
+Models:
+  1. cc/claude-opus-4-5-20251101 (Subscription primary)
+  2. glm/glm-4.7 (Cheap backup, $0.6/1M)
+  3. if/kimi-k2-thinking (Free fallback)
+
+Use in CLI: premium-coding
+```
+
+**How it works:**
+1. Tries Claude Opus first (your subscription)
+2. If quota exhausted → GLM-4.7 (ultra-cheap)
+3. If budget limit → iFlow (free)
+4. Zero downtime, automatic switching!
+
+---
+
+## Available Models
+
+### Subscription Models (Maximize First)
+
+**Claude Code (`cc/`)** - Pro/Max subscription:
+- `cc/claude-opus-4-5-20251101` - Claude 4.5 Opus
+- `cc/claude-sonnet-4-5-20250929` - Claude 4.5 Sonnet
+- `cc/claude-haiku-4-5-20251001` - Claude 4.5 Haiku
+
+**Codex (`cx/`)** - Plus/Pro subscription:
+- `cx/gpt-5.2-codex` - GPT 5.2 Codex
+- `cx/gpt-5.1-codex-max` - GPT 5.1 Codex Max
+
+**Gemini CLI (`gc/`)** - FREE 180K/month:
+- `gc/gemini-3-flash-preview` - Gemini 3 Flash Preview
+- `gc/gemini-2.5-pro` - Gemini 2.5 Pro
+
+**GitHub Copilot (`gh/`)** - Subscription:
+- `gh/gpt-5` - GPT-5
+- `gh/claude-4.5-sonnet` - Claude 4.5 Sonnet
+
+### Cheap Models (Backup)
+
+**GLM (`glm/`)** - $0.6/$2.2 per 1M:
+- `glm/glm-4.7` - GLM 4.7 (daily reset 10AM)
+
+**MiniMax (`minimax/`)** - $0.20/$1.00 per 1M:
+- `minimax/MiniMax-M2.1` - MiniMax M2.1 (5h reset)
+
+**Kimi (`kimi/`)** - $9/month (10M tokens):
+- `kimi/kimi-latest` - Kimi Latest
+
+### FREE Models (Emergency)
+
+**iFlow (`if/`)** - 8 models FREE:
+- `if/kimi-k2-thinking` - Kimi K2 Thinking
+- `if/qwen3-coder-plus` - Qwen3 Coder Plus
+- `if/glm-4.7` - GLM 4.7
+- `if/deepseek-r1` - DeepSeek R1
+
+**Qwen (`qw/`)** - 3 models FREE:
+- `qw/qwen3-coder-plus` - Qwen3 Coder Plus
+- `qw/qwen3-coder-flash` - Qwen3 Coder Flash
+
+**Kiro (`kr/`)** - 2 models FREE:
+- `kr/claude-sonnet-4.5` - Claude Sonnet 4.5
+- `kr/claude-haiku-4.5` - Claude Haiku 4.5
+
+---
+
+## Cost Optimization Strategy
+
+### Monthly Budget: $10-20/month
+
+```
+1. Use Gemini CLI free tier (180K/month) for quick tasks
+2. Use Claude Code subscription quota fully (you already pay)
+3. Fallback to GLM ($0.6/1M) when quota out
+4. Emergency: MiniMax M2.1 ($0.20/1M) or iFlow (free)
+
+Real example (100M tokens/month):
+  60M via Gemini CLI: $0 (free tier)
+  30M via Claude Code: $0 (subscription you already have)
+  8M via GLM: $4.80
+  2M via MiniMax: $0.40
+  Total: $5.20/month + existing subscriptions
+```
+
+### Quota Reset Strategy
+
+```
+Daily routine:
+1. Morning: Fresh Claude Code quota (5h reset)
+2. Afternoon: Switch to Gemini CLI (1K/day)
+3. Evening: GLM daily quota (reset 10AM next day)
+4. Late night: MiniMax (5h rolling) or iFlow (free)
+
+→ Code 24/7 with minimal extra cost!
+```
+
+---
+
+## Next Steps
+
+- [Installation Details](getting-started/installation.md) - Requirements, troubleshooting
+- [Features](features/) - Explore quota tracking, combos, deployment
+- [FAQ](faq.md) - Common questions and answers
+- [Troubleshooting](troubleshooting.md) - Fix common issues
+
+---
+
+## Need Help?
+
+- **Website**: [9router.com](https://9router.com)
+- **GitHub**: [github.com/decolua/9router](https://github.com/decolua/9router)
+- **Issues**: [github.com/decolua/9router/issues](https://github.com/decolua/9router/issues)