Feat : Gitbook

This commit is contained in:
decolua
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 @@
# Cài đặt
Hướng dẫn cài đặt chi tiết cho 9Router với mẹo troubleshooting.
---
## Yêu cầu
### Yêu cầu hệ thống
- **Node.js**: Phiên bản 20.0.0 trở lên
- **npm**: Phiên bản 10.0.0 trở lên (đi kèm Node.js)
- **OS**: macOS, Linux, Windows (khuyên dùng WSL)
- **Dung lượng**: ~200MB để cài đặt
### Kiểm tra Phiên bản
```bash
node --version
# Should show v20.x.x or higher
npm --version
# Should show 10.x.x or higher
```
**Chưa có Node.js?** Cài đặt từ [nodejs.org](https://nodejs.org/)
---
## Phương thức Cài đặt
### Cách 1: Cài Global (Khuyên dùng)
Cài 9Router toàn cục để dùng ở bất kỳ đâu:
```bash
npm install -g 9router
```
**Khởi động 9Router:**
```bash
9router
```
**Lợi ích:**
- ✅ Chạy từ mọi thư mục
- ✅ Lệnh đơn giản: `9router`
- ✅ Auto-update với `npm update -g 9router`
### Cách 2: Cài Local
Cài trong project cụ thể:
```bash
mkdir my-9router
cd my-9router
npm install 9router
```
**Khởi động 9Router:**
```bash
npx 9router
```
**Lợi ích:**
- ✅ Cô lập mỗi project
- ✅ Version control mỗi project
- ✅ Không làm bẩn global namespace
### Cách 3: Từ Source (Development)
Clone và build từ GitHub:
```bash
git clone https://github.com/decolua/9router.git
cd 9router/app
npm install
npm run build
npm start
```
**Lợi ích:**
- ✅ Tính năng phát triển mới nhất
- ✅ Đóng góp cho dự án
- ✅ Tùy chỉnh
---
## Lần chạy Đầu tiên
### Khởi động Server
```bash
9router
```
**Điều gì xảy ra:**
1. Server khởi động tại `http://localhost:20128`
2. Dashboard tự động mở trong browser
3. Data directory được tạo tại `~/.9router`
4. API key được tạo tự động
### Đăng nhập Dashboard
**Credentials mặc định:**
- Mật khẩu: `123456`
**⚠️ Đổi mật khẩu ngay:**
1. Đăng nhập dashboard
2. Settings → Change Password
3. Dùng mật khẩu mạnh
### Lấy API Key
```
Dashboard → Settings → API Keys
→ Copy your API key
→ Use in CLI tools
```
**Ví dụ format API key:**
```
9r_1234567890abcdef1234567890abcdef
```
---
## Xác minh Cài đặt
### Kiểm tra trạng thái Server
```bash
curl http://localhost:20128/health
```
**Phản hồi dự kiến:**
```json
{
"status": "ok",
"version": "1.0.0"
}
```
### Liệt kê Model khả dụng
```bash
curl http://localhost:20128/v1/models \
-H "Authorization: Bearer your-api-key"
```
**Phản hồi dự kiến:**
```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!"}
]
}'
```
---
## Cấu hình
### Biến môi trường
Tạo file `.env` hoặc set biến môi trường:
```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
**Vị trí mặc định:** `~/.9router`
**Nội dung:**
```
~/.9router/
├── db.json # Database (providers, combos, usage)
├── api-keys.json # API keys
└── logs/ # Request logs (if enabled)
```
**Đổi vị trí:**
```bash
export DATA_DIR="/custom/path"
9router
```
### Cấu hình Port
**Port mặc định:** `20128`
**Đổi port:**
```bash
export PORT="3000"
9router
```
**Hoặc dùng command line:**
```bash
9router --port 3000
```
---
## Troubleshooting
### Port đã được dùng
**Lỗi:**
```
Error: listen EADDRINUSE: address already in use :::20128
```
**Giải pháp 1: Kill process hiện có**
```bash
# Find process using port 20128
lsof -i :20128
# Kill process
kill -9 <PID>
```
**Giải pháp 2: Dùng port khác**
```bash
9router --port 3000
```
### Permission Denied
**Lỗi:**
```
Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules/9router'
```
**Giải pháp: Dùng sudo (không khuyến nghị) hoặc 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 Phiên bản quá cũ
**Lỗi:**
```
Error: The engine "node" is incompatible with this module
```
**Giải pháp: Cập nhật Node.js**
```bash
# Using nvm (recommended)
nvm install 20
nvm use 20
# Or download from nodejs.org
```
### Dashboard không mở
**Vấn đề:** Dashboard không tự mở
**Giải pháp 1: Mở thủ công**
```
http://localhost:20128
```
**Giải pháp 2: Kiểm tra firewall**
```bash
# macOS: Allow Node.js in System Preferences → Security
# Linux: Check iptables
# Windows: Check Windows Firewall
```
### Không kết nối được Provider
**Vấn đề:** OAuth login thất bại hoặc API key không hợp lệ
**Giải pháp 1: Kiểm tra kết nối internet**
```bash
ping google.com
```
**Giải pháp 2: Kiểm tra trạng thái provider**
- 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)
**Giải pháp 3: Tạo lại API key**
```
Dashboard → Provider → Disconnect → Reconnect
```
### Sử dụng RAM cao
**Vấn đề:** 9Router dùng quá nhiều RAM
**Giải pháp: Khởi động lại server**
```bash
# Stop
pkill -f 9router
# Start
9router
```
**Hoặc dùng PM2 để auto-restart:**
```bash
npm install -g pm2
pm2 start 9router --name 9router
pm2 save
```
---
## Tùy chọn Deployment
### Phát triển cục bộ
```bash
npm install -g 9router
9router
```
**Use case:** Code cá nhân, 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
---
## Gỡ cài đặt
### Gỡ Global Installation
```bash
npm uninstall -g 9router
```
### Xóa Data Directory
```bash
rm -rf ~/.9router
```
### Xóa Cấu hình
```bash
# Remove environment variables from shell config
nano ~/.bashrc # or ~/.zshrc
# Delete 9router-related exports
```
---
## Bước tiếp theo
- [Hướng dẫn Bắt đầu](../getting-started.md) - Kết nối provider và bắt đầu code
- [Tính năng](../features/) - Khám phá quota tracking, combos, deployment
- [Troubleshooting](../troubleshooting.md) - Sửa các vấn đề thường gặp
---
## Cần trợ giúp?
- **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 @@
# Bắt đầu
Khởi chạy 9Router trong 5 phút và bắt đầu định tuyến các request AI một cách thông minh.
---
## Bắt đầu nhanh
### 1. Cài đặt
```bash
npm install -g 9router
```
**Yêu cầu:** Node.js 20+ ([Chi tiết cài đặt](getting-started/installation.md))
### 2. Khởi chạy
```bash
9router
```
🎉 **Dashboard tự động mở** tại `http://localhost:20128`
- Mật khẩu mặc định: `123456` (đổi trong dashboard)
- API key được tạo tự động
- Sẵn sàng kết nối provider
### 3. Kết nối Provider
Bạn có 3 cách để kết nối provider:
#### Cách A: OAuth (Subscription Provider)
**Tốt nhất cho:** Claude Code, Codex, Gemini CLI, GitHub Copilot
```
Dashboard → Providers → Connect [Provider]
→ OAuth login → Auto token refresh
→ Quota tracking enabled
```
**Ví dụ: Claude Code**
1. Click "Connect Claude Code"
2. Đăng nhập tài khoản Claude
3. Cho phép 9Router
4. ✅ Xong! Dùng model: `cc/claude-opus-4-5-20251101`
#### Cách B: API Key (Cheap Provider)
**Tốt nhất cho:** GLM, MiniMax, Kimi, OpenRouter
```
Dashboard → Providers → Add API Key
→ Select provider
→ Paste API key
→ Save
```
**Ví dụ: GLM-4.7**
1. Đăng ký tại [Zhipu AI](https://open.bigmodel.cn/)
2. Lấy API key từ Coding Plan
3. Dashboard → Add API Key → Provider: `glm` → Paste key
4. ✅ Xong! Dùng model: `glm/glm-4.7`
#### Cách C: Free Provider (Miễn phí)
**Tốt nhất cho:** iFlow, Qwen, Kiro
```
Dashboard → Providers → Connect [Free Provider]
→ Device code or OAuth
→ Unlimited usage
```
**Ví dụ: iFlow**
1. Click "Connect iFlow"
2. Đăng nhập tài khoản iFlow
3. Cho phép
4. ✅ Xong! Dùng 8 model: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, v.v.
---
## 4. Dùng trong CLI Tools
Trỏ công cụ code của bạn tới 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
Sửa `~/.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. Tạo Smart Combos (Tùy chọn)
Combo cho phép fallback tự động giữa các model:
```
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
```
**Cách hoạt động:**
1. Thử Claude Opus trước (subscription của bạn)
2. Nếu hết quota → GLM-4.7 (siêu rẻ)
3. Nếu hết budget → iFlow (miễn phí)
4. Zero downtime, chuyển đổi tự động!
---
## Model có sẵn
### Subscription Models (Dùng đầu tiên)
**Claude Code (`cc/`)** - Subscription Pro/Max:
- `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/`)** - Subscription Plus/Pro:
- `cx/gpt-5.2-codex` - GPT 5.2 Codex
- `cx/gpt-5.1-codex-max` - GPT 5.1 Codex Max
**Gemini CLI (`gc/`)** - MIỄN PHÍ 180K/tháng:
- `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 (reset 10AM hàng ngày)
**MiniMax (`minimax/`)** - $0.20/$1.00 per 1M:
- `minimax/MiniMax-M2.1` - MiniMax M2.1 (reset 5h)
**Kimi (`kimi/`)** - $9/tháng (10M tokens):
- `kimi/kimi-latest` - Kimi Latest
### Model MIỄN PHÍ (Khẩn cấp)
**iFlow (`if/`)** - 8 models MIỄN PHÍ:
- `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 MIỄN PHÍ:
- `qw/qwen3-coder-plus` - Qwen3 Coder Plus
- `qw/qwen3-coder-flash` - Qwen3 Coder Flash
**Kiro (`kr/`)** - 2 models MIỄN PHÍ:
- `kr/claude-sonnet-4.5` - Claude Sonnet 4.5
- `kr/claude-haiku-4.5` - Claude Haiku 4.5
---
## Chiến lược Tối ưu Chi phí
### Ngân sách hàng tháng: $10-20/tháng
```
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
```
### Chiến lược Reset Quota
```
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!
```
---
## Bước tiếp theo
- [Chi tiết cài đặt](getting-started/installation.md) - Yêu cầu, troubleshooting
- [Tính năng](features/) - Khám phá quota tracking, combos, deployment
- [FAQ](faq.md) - Câu hỏi thường gặp
- [Troubleshooting](troubleshooting.md) - Sửa các vấn đề phổ biến
---
## Cần trợ giúp?
- **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)