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 @@
# Instalación
Guía detallada de instalación de 9Router con consejos de solución de problemas.
---
## Requisitos
### Requisitos del sistema
- **Node.js**: Versión 20.0.0 o superior
- **npm**: Versión 10.0.0 o superior (viene con Node.js)
- **OS**: macOS, Linux, Windows (WSL recomendado)
- **Espacio en disco**: ~200MB para la instalación
### Verifica tu versión
```bash
node --version
# Debería mostrar v20.x.x o superior
npm --version
# Debería mostrar 10.x.x o superior
```
**¿No tienes Node.js?** Instálalo desde [nodejs.org](https://nodejs.org/)
---
## Métodos de instalación
### Método 1: Instalación global (Recomendado)
Instala 9Router globalmente para usar desde cualquier lugar:
```bash
npm install -g 9router
```
**Iniciar 9Router:**
```bash
9router
```
**Beneficios:**
- ✅ Ejecuta desde cualquier directorio
- ✅ Comando simple: `9router`
- ✅ Auto-actualizaciones con `npm update -g 9router`
### Método 2: Instalación local
Instala en un proyecto específico:
```bash
mkdir my-9router
cd my-9router
npm install 9router
```
**Iniciar 9Router:**
```bash
npx 9router
```
**Beneficios:**
- ✅ Aislado por proyecto
- ✅ Control de versiones por proyecto
- ✅ Sin contaminación del namespace global
### Método 3: Desde el código fuente (Desarrollo)
Clona y compila desde GitHub:
```bash
git clone https://github.com/decolua/9router.git
cd 9router/app
npm install
npm run build
npm start
```
**Beneficios:**
- ✅ Últimas características de desarrollo
- ✅ Contribuir al desarrollo
- ✅ Modificaciones personalizadas
---
## Primera ejecución
### Iniciar el servidor
```bash
9router
```
**Qué sucede:**
1. El servidor inicia en `http://localhost:20128`
2. El dashboard se abre automáticamente en el navegador
3. Se crea el directorio de datos en `~/.9router`
4. API key generada automáticamente
### Login del dashboard
**Credenciales por defecto:**
- Contraseña: `123456`
**⚠️ Cambia la contraseña inmediatamente:**
1. Inicia sesión en el dashboard
2. Settings → Change Password
3. Usa una contraseña fuerte
### Obtén tu API key
```
Dashboard → Settings → API Keys
→ Copia tu API key
→ Úsala en herramientas CLI
```
**Ejemplo de formato de API key:**
```
9r_1234567890abcdef1234567890abcdef
```
---
## Verificar la instalación
### Verifica el estado del servidor
```bash
curl http://localhost:20128/health
```
**Respuesta esperada:**
```json
{
"status": "ok",
"version": "1.0.0"
}
```
### Lista los modelos disponibles
```bash
curl http://localhost:20128/v1/models \
-H "Authorization: Bearer your-api-key"
```
**Respuesta esperada:**
```json
{
"object": "list",
"data": [
{
"id": "cc/claude-opus-4-5-20251101",
"object": "model",
"created": 1234567890,
"owned_by": "claude-code"
}
]
}
```
### Prueba el 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!"}
]
}'
```
---
## Configuración
### Variables de entorno
Crea un archivo `.env` o establece variables de entorno:
```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"
```
### Directorio de datos
**Ubicación por defecto:** `~/.9router`
**Contenido:**
```
~/.9router/
├── db.json # Database (providers, combos, usage)
├── api-keys.json # API keys
└── logs/ # Request logs (if enabled)
```
**Cambiar ubicación:**
```bash
export DATA_DIR="/custom/path"
9router
```
### Configuración de puerto
**Puerto por defecto:** `20128`
**Cambiar puerto:**
```bash
export PORT="3000"
9router
```
**O usa la línea de comandos:**
```bash
9router --port 3000
```
---
## Solución de problemas
### Puerto ya en uso
**Error:**
```
Error: listen EADDRINUSE: address already in use :::20128
```
**Solución 1: Mata el proceso existente**
```bash
# Encuentra proceso usando el puerto 20128
lsof -i :20128
# Mata el proceso
kill -9 <PID>
```
**Solución 2: Usa otro puerto**
```bash
9router --port 3000
```
### Permiso denegado
**Error:**
```
Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules/9router'
```
**Solución: Usa sudo (no recomendado) o corrige los permisos de npm**
```bash
# Corregir permisos de npm (recomendado)
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
# Luego instalar nuevamente
npm install -g 9router
```
### Versión de Node.js muy antigua
**Error:**
```
Error: The engine "node" is incompatible with this module
```
**Solución: Actualizar Node.js**
```bash
# Usando nvm (recomendado)
nvm install 20
nvm use 20
# O descargar desde nodejs.org
```
### El dashboard no se abre
**Problema:** El dashboard no se abre automáticamente
**Solución 1: Abrir manualmente**
```
http://localhost:20128
```
**Solución 2: Verifica el firewall**
```bash
# macOS: Permitir Node.js en System Preferences → Security
# Linux: Verificar iptables
# Windows: Verificar Windows Firewall
```
### No se puede conectar a proveedores
**Problema:** El login OAuth falla o la API key es inválida
**Solución 1: Verifica la conexión a internet**
```bash
ping google.com
```
**Solución 2: Verifica el estado del proveedor**
- 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)
**Solución 3: Regenera la API key**
```
Dashboard → Provider → Disconnect → Reconnect
```
### Uso alto de memoria
**Problema:** 9Router usa demasiada RAM
**Solución: Reinicia el servidor**
```bash
# Detener
pkill -f 9router
# Iniciar
9router
```
**O usa PM2 para auto-reinicio:**
```bash
npm install -g pm2
pm2 start 9router --name 9router
pm2 save
```
---
## Opciones de despliegue
### Desarrollo local
```bash
npm install -g 9router
9router
```
**Caso de uso:** Codificación personal, pruebas
### Servidor VPS/Cloud
```bash
# Instalar
npm install -g 9router
# Configurar
export JWT_SECRET="your-secure-secret"
export INITIAL_PASSWORD="your-password"
export NODE_ENV="production"
# Iniciar con PM2
npm install -g pm2
pm2 start 9router --name 9router
pm2 save
pm2 startup
```
**Caso de uso:** Acceso de equipo, codificación remota
### 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
```
**Caso de uso:** Despliegue containerizado, Kubernetes
### Proxy reverso (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;
}
}
```
**Caso de uso:** HTTPS, dominio personalizado, balanceo de carga
---
## Desinstalación
### Eliminar instalación global
```bash
npm uninstall -g 9router
```
### Eliminar el directorio de datos
```bash
rm -rf ~/.9router
```
### Eliminar la configuración
```bash
# Eliminar variables de entorno del archivo de configuración del shell
nano ~/.bashrc # o ~/.zshrc
# Eliminar exports relacionados con 9router
```
---
## Próximos pasos
- [Guía para empezar](../getting-started.md) - Conecta proveedores y comienza a codificar
- [Características](../features/) - Explora seguimiento de cuota, combos, despliegue
- [Solución de problemas](../troubleshooting.md) - Resuelve problemas comunes
---
## ¿Necesitas ayuda?
- **Sitio web**: [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 @@
# Empezar
Pon en marcha 9Router en 5 minutos y comienza a enrutar solicitudes de IA de forma inteligente.
---
## Inicio rápido
### 1. Instalar
```bash
npm install -g 9router
```
**Requisitos:** Node.js 20+ ([Detalles de instalación](getting-started/installation.md))
### 2. Iniciar
```bash
9router
```
🎉 **El dashboard se abre automáticamente** en `http://localhost:20128`
- Contraseña por defecto: `123456` (cámbiala en el dashboard)
- API key generada automáticamente
- Listo para conectar proveedores
### 3. Conectar proveedores
Tienes 3 formas de conectar proveedores:
#### Opción A: OAuth (Proveedores de suscripción)
**Ideal para:** Claude Code, Codex, Gemini CLI, GitHub Copilot
```
Dashboard → Providers → Connect [Provider]
→ Login OAuth → Refresh automático de token
→ Seguimiento de cuota habilitado
```
**Ejemplo: Claude Code**
1. Clic en "Connect Claude Code"
2. Inicia sesión con tu cuenta de Claude
3. Autoriza 9Router
4. ✅ ¡Listo! Usa el modelo: `cc/claude-opus-4-5-20251101`
#### Opción B: API Key (Proveedores baratos)
**Ideal para:** GLM, MiniMax, Kimi, OpenRouter
```
Dashboard → Providers → Add API Key
→ Selecciona proveedor
→ Pega API key
→ Guardar
```
**Ejemplo: GLM-4.7**
1. Regístrate en [Zhipu AI](https://open.bigmodel.cn/)
2. Obtén la API key del Coding Plan
3. Dashboard → Add API Key → Provider: `glm` → Pega la key
4. ✅ ¡Listo! Usa el modelo: `glm/glm-4.7`
#### Opción C: Proveedores gratis (Sin costo)
**Ideal para:** iFlow, Qwen, Kiro
```
Dashboard → Providers → Connect [Free Provider]
→ Device code u OAuth
→ Uso ilimitado
```
**Ejemplo: iFlow**
1. Clic en "Connect iFlow"
2. Inicia sesión con tu cuenta de iFlow
3. Autoriza
4. ✅ ¡Listo! Usa 8 modelos: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, etc.
---
## 4. Usar en herramientas CLI
Apunta tu herramienta de codificación a 9Router:
### Cursor IDE
```
Settings → Models → Advanced:
OpenAI API Base URL: http://localhost:20128/v1
OpenAI API Key: [desde el dashboard de 9router]
Model: cc/claude-opus-4-5-20251101
```
### Claude Desktop
Edita `~/.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: [desde el 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. Crear combos inteligentes (Opcional)
Los combos habilitan el fallback automático entre modelos:
```
Dashboard → Combos → Create New
Name: premium-coding
Models:
1. cc/claude-opus-4-5-20251101 (Suscripción principal)
2. glm/glm-4.7 (Respaldo barato, $0.6/1M)
3. if/kimi-k2-thinking (Fallback gratis)
Usar en CLI: premium-coding
```
**Cómo funciona:**
1. Intenta primero Claude Opus (tu suscripción)
2. Si la cuota se agota → GLM-4.7 (ultra-barato)
3. Si llega al límite de presupuesto → iFlow (gratis)
4. ¡Cero tiempo de inactividad, cambio automático!
---
## Modelos disponibles
### Modelos de suscripción (Maximiza primero)
**Claude Code (`cc/`)** - Suscripción 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/`)** - Suscripción 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/`)** - GRATIS 180K/mes:
- `gc/gemini-3-flash-preview` - Gemini 3 Flash Preview
- `gc/gemini-2.5-pro` - Gemini 2.5 Pro
**GitHub Copilot (`gh/`)** - Suscripción:
- `gh/gpt-5` - GPT-5
- `gh/claude-4.5-sonnet` - Claude 4.5 Sonnet
### Modelos baratos (Respaldo)
**GLM (`glm/`)** - $0.6/$2.2 por 1M:
- `glm/glm-4.7` - GLM 4.7 (reinicio diario 10AM)
**MiniMax (`minimax/`)** - $0.20/$1.00 por 1M:
- `minimax/MiniMax-M2.1` - MiniMax M2.1 (reinicio 5h)
**Kimi (`kimi/`)** - $9/mes (10M tokens):
- `kimi/kimi-latest` - Kimi Latest
### Modelos GRATIS (Emergencia)
**iFlow (`if/`)** - 8 modelos GRATIS:
- `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 modelos GRATIS:
- `qw/qwen3-coder-plus` - Qwen3 Coder Plus
- `qw/qwen3-coder-flash` - Qwen3 Coder Flash
**Kiro (`kr/`)** - 2 modelos GRATIS:
- `kr/claude-sonnet-4.5` - Claude Sonnet 4.5
- `kr/claude-haiku-4.5` - Claude Haiku 4.5
---
## Estrategia de optimización de costos
### Presupuesto mensual: $10-20/mes
```
1. Usa el nivel gratis de Gemini CLI (180K/mes) para tareas rápidas
2. Usa la cuota de suscripción de Claude Code al máximo (ya pagas)
3. Fallback a GLM ($0.6/1M) cuando se agote la cuota
4. Emergencia: MiniMax M2.1 ($0.20/1M) o iFlow (gratis)
Ejemplo real (100M tokens/mes):
60M vía Gemini CLI: $0 (nivel gratis)
30M vía Claude Code: $0 (suscripción que ya tienes)
8M vía GLM: $4.80
2M vía MiniMax: $0.40
Total: $5.20/mes + suscripciones existentes
```
### Estrategia de reinicio de cuota
```
Rutina diaria:
1. Mañana: Cuota fresca de Claude Code (reinicio 5h)
2. Tarde: Cambia a Gemini CLI (1K/día)
3. Noche: Cuota diaria de GLM (reinicio 10AM del día siguiente)
4. Madrugada: MiniMax (rolling 5h) o iFlow (gratis)
→ ¡Codifica 24/7 con costo extra mínimo!
```
---
## Próximos pasos
- [Detalles de instalación](getting-started/installation.md) - Requisitos, troubleshooting
- [Características](features/) - Explora seguimiento de cuota, combos, despliegue
- [FAQ](faq.md) - Preguntas y respuestas comunes
- [Troubleshooting](troubleshooting.md) - Soluciona problemas comunes
---
## ¿Necesitas ayuda?
- **Sitio web**: [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)