Feat : Gitbook

gitbook/content/zh-CN/deployment/cloud.md

@@ -0,0 +1,473 @@
+# ☁️ 云端部署
+
+将 9Router 部署到 VPS 或 Docker,实现远程访问和生产使用。
+
+---
+
+## 🖥️ VPS 部署
+
+### 前置要求
+
+- Ubuntu 20.04+ 或类似 Linux 发行版
+- Node.js 20+
+- Git
+- root 或 sudo 权限
+
+### 步骤 1:克隆仓库
+
+```bash
+git clone https://github.com/decolua/9router.git
+cd 9router/app
+```
+
+### 步骤 2:安装依赖
+
+```bash
+npm install
+```
+
+### 步骤 3:构建应用
+
+```bash
+npm run build
+```
+
+### 步骤 4:配置环境变量
+
+创建 `.env` 文件或导出变量:
+
+```bash
+export JWT_SECRET="your-secure-secret-change-this-to-random-string"
+export INITIAL_PASSWORD="your-secure-password"
+export DATA_DIR="/var/lib/9router"
+export NODE_ENV="production"
+```
+
+**环境变量:**
+
+| 变量 | 默认值 | 说明 |
+|----------|---------|-------------|
+| `JWT_SECRET` | 自动生成 | **生产环境必须修改!** 用于 JWT token 签名 |
+| `INITIAL_PASSWORD` | `123456` | 仪表盘登录密码 |
+| `DATA_DIR` | `~/.9router` | 数据库与数据存储路径 |
+| `NODE_ENV` | `development` | 部署时设为 `production` |
+| `ENABLE_REQUEST_LOGS` | `false` | 启用 debug 请求/响应日志 |
+
+### 步骤 5:创建数据目录
+
+```bash
+sudo mkdir -p /var/lib/9router
+sudo chown $USER:$USER /var/lib/9router
+```
+
+### 步骤 6:启动应用
+
+```bash
+npm run start
+```
+
+### 步骤 7:用 PM2 部署到生产环境
+
+PM2 让应用持续运行,崩溃时自动重启:
+
+```bash
+# 全局安装 PM2
+npm install -g pm2
+
+# 用 PM2 启动 9Router
+pm2 start npm --name 9router -- start
+
+# 保存 PM2 配置
+pm2 save
+
+# 设置开机自启
+pm2 startup
+# 按上一条命令打印的提示执行
+```
+
+**PM2 管理命令:**
+
+```bash
+# 查看日志
+pm2 logs 9router
+
+# 重启应用
+pm2 restart 9router
+
+# 停止应用
+pm2 stop 9router
+
+# 查看状态
+pm2 status
+
+# 监控资源
+pm2 monit
+```
+
+---
+
+## 🐳 Docker 部署
+
+### 方式 1:使用 Dockerfile
+
+在 `app` 目录中创建 `Dockerfile`:
+
+```dockerfile
+FROM node:20-alpine
+
+WORKDIR /app
+
+# Copy package files
+COPY package*.json ./
+
+# Install dependencies
+RUN npm ci --only=production
+
+# Copy application files
+COPY . .
+
+# Build application
+RUN npm run build
+
+# Expose ports
+EXPOSE 3000 20128
+
+# Set environment variables
+ENV NODE_ENV=production
+ENV DATA_DIR=/app/data
+
+# Create data directory
+RUN mkdir -p /app/data
+
+# Start application
+CMD ["npm", "run", "start"]
+```
+
+**构建并运行:**
+
+```bash
+# 构建镜像
+docker build -t 9router .
+
+# 运行容器
+docker run -d \
+  --name 9router \
+  -p 3000:3000 \
+  -p 20128:20128 \
+  -e JWT_SECRET="your-secure-secret-change-this" \
+  -e INITIAL_PASSWORD="your-secure-password" \
+  -v 9router-data:/app/data \
+  9router
+```
+
+### 方式 2:Docker Compose
+
+创建 `docker-compose.yml`:
+
+```yaml
+version: '3.8'
+
+services:
+  9router:
+    build: .
+    container_name: 9router
+    ports:
+      - "3000:3000"
+      - "20128:20128"
+    environment:
+      - NODE_ENV=production
+      - JWT_SECRET=your-secure-secret-change-this
+      - INITIAL_PASSWORD=your-secure-password
+      - DATA_DIR=/app/data
+    volumes:
+      - 9router-data:/app/data
+    restart: unless-stopped
+
+volumes:
+  9router-data:
+```
+
+**使用 Docker Compose 运行:**
+
+```bash
+# 启动服务
+docker-compose up -d
+
+# 查看日志
+docker-compose logs -f
+
+# 停止服务
+docker-compose down
+
+# 重新构建并重启
+docker-compose up -d --build
+```
+
+---
+
+## 🌐 Nginx 反向代理
+
+### 为什么使用 Nginx?
+
+- SSL/TLS 终止
+- 域名映射
+- 负载均衡
+- 更好的安全性
+
+### 步骤 1:安装 Nginx
+
+```bash
+sudo apt update
+sudo apt install nginx
+```
+
+### 步骤 2:配置 Nginx
+
+创建 `/etc/nginx/sites-available/9router`:
+
+```nginx
+server {
+    listen 80;
+    server_name your-domain.com;
+
+    # Redirect HTTP to HTTPS
+    return 301 https://$server_name$request_uri;
+}
+
+server {
+    listen 443 ssl http2;
+    server_name your-domain.com;
+
+    # SSL certificates (use certbot to generate)
+    ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;
+
+    # SSL configuration
+    ssl_protocols TLSv1.2 TLSv1.3;
+    ssl_ciphers HIGH:!aNULL:!MD5;
+    ssl_prefer_server_ciphers on;
+
+    # Proxy to 9Router
+    location / {
+        proxy_pass http://localhost:3000;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection 'upgrade';
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_cache_bypass $http_upgrade;
+        
+        # SSE support - CRITICAL for streaming
+        proxy_buffering off;
+        proxy_read_timeout 86400;
+    }
+
+    # API endpoint
+    location /v1 {
+        proxy_pass http://localhost:20128;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        
+        # SSE support - CRITICAL for streaming
+        proxy_buffering off;
+        proxy_read_timeout 86400;
+    }
+}
+```
+
+### 步骤 3:启用站点
+
+```bash
+# 创建软链接
+sudo ln -s /etc/nginx/sites-available/9router /etc/nginx/sites-enabled/
+
+# 测试配置
+sudo nginx -t
+
+# 重新加载 Nginx
+sudo systemctl reload nginx
+```
+
+### 步骤 4:使用 Let's Encrypt 配置 SSL
+
+```bash
+# 安装 certbot
+sudo apt install certbot python3-certbot-nginx
+
+# 获取 SSL 证书
+sudo certbot --nginx -d your-domain.com
+
+# 自动续期已自动配置
+# 测试续期
+sudo certbot renew --dry-run
+```
+
+---
+
+## 🔒 安全注意事项
+
+### 1. 修改默认凭据
+
+**关键:** 部署前修改 `JWT_SECRET` 和 `INITIAL_PASSWORD`:
+
+```bash
+# 生成安全的 JWT secret
+openssl rand -base64 32
+
+# 将该值用于 JWT_SECRET
+export JWT_SECRET="generated-secret-here"
+```
+
+### 2. 防火墙配置
+
+```bash
+# 允许 SSH
+sudo ufw allow 22/tcp
+
+# 允许 HTTP/HTTPS(若使用 Nginx)
+sudo ufw allow 80/tcp
+sudo ufw allow 443/tcp
+
+# 若不使用反向代理,放开 9Router 端口
+sudo ufw allow 3000/tcp
+sudo ufw allow 20128/tcp
+
+# 启用防火墙
+sudo ufw enable
+```
+
+### 3. 限制仪表盘访问
+
+如果只需要 API 访问,可限制仪表盘端口:
+
+```bash
+# 仅允许 localhost 访问仪表盘
+sudo ufw deny 3000/tcp
+```
+
+通过 SSH 隧道访问仪表盘:
+
+```bash
+ssh -L 3000:localhost:3000 user@your-server.com
+# 然后在浏览器打开 http://localhost:3000
+```
+
+### 4. 定期更新
+
+```bash
+# 更新系统包
+sudo apt update && sudo apt upgrade -y
+
+# 更新 9Router
+cd /path/to/9router/app
+git pull
+npm install
+npm run build
+pm2 restart 9router
+```
+
+### 5. 备份策略
+
+```bash
+# 备份数据目录
+tar -czf 9router-backup-$(date +%Y%m%d).tar.gz /var/lib/9router
+
+# 每日自动备份(加入 crontab)
+0 2 * * * tar -czf /backups/9router-$(date +\%Y\%m\%d).tar.gz /var/lib/9router
+```
+
+---
+
+## 📊 监控
+
+### 检查应用状态
+
+```bash
+# PM2 状态
+pm2 status
+
+# 查看日志
+pm2 logs 9router --lines 100
+
+# 监控资源
+pm2 monit
+```
+
+### Nginx 日志
+
+```bash
+# 访问日志
+sudo tail -f /var/log/nginx/access.log
+
+# 错误日志
+sudo tail -f /var/log/nginx/error.log
+```
+
+### 系统资源
+
+```bash
+# CPU 和内存使用
+htop
+
+# 磁盘使用
+df -h
+
+# 网络连接
+netstat -tulpn | grep -E '3000|20128'
+```
+
+---
+
+## 🚨 故障排除
+
+### 应用无法启动
+
+```bash
+# 查看日志
+pm2 logs 9router
+
+# 检查端口是否被占用
+sudo lsof -i :3000
+sudo lsof -i :20128
+
+# 检查环境变量
+pm2 env 9router
+```
+
+### Nginx 502 Bad Gateway
+
+```bash
+# 检查 9Router 是否运行
+pm2 status
+
+# 查看 Nginx 错误日志
+sudo tail -f /var/log/nginx/error.log
+
+# 测试 Nginx 配置
+sudo nginx -t
+```
+
+### SSE 流式输出无法工作
+
+确保 Nginx 配置中已设置 `proxy_buffering off` 以支持 SSE。
+
+### 权限被拒绝错误
+
+```bash
+# 修复数据目录权限
+sudo chown -R $USER:$USER /var/lib/9router
+chmod 755 /var/lib/9router
+```
+
+---
+
+## 🔗 下一步
+
+- [连接提供商](/providers/subscription.md)
+- [配置组合](/features/combos.md)
+- [集成工具](/integration/cursor.md)

gitbook/content/zh-CN/deployment/localhost.md

@@ -0,0 +1,164 @@
+# 🏠 本地部署
+
+在本机运行 9Router,用于开发和个人使用。
+
+---
+
+## 📦 安装
+
+通过 npm 全局安装 9Router:
+
+```bash
+npm install -g 9router
+```
+
+**要求:**
+- Node.js 20 或更高
+- npm 9 或更高
+
+---
+
+## 🚀 启动服务器
+
+一条命令启动 9Router:
+
+```bash
+9router
+```
+
+仪表盘会自动在浏览器中打开,地址为 `http://localhost:3000`
+
+**默认配置:**
+- **仪表盘**: `http://localhost:3000`
+- **API Endpoint**: `http://localhost:20128/v1`
+- **数据目录**: `~/.9router`
+
+---
+
+## 🔧 配置
+
+### 自定义数据目录
+
+通过环境变量设置自定义数据目录:
+
+```bash
+DATA_DIR=/path/to/data 9router
+```
+
+### 自定义端口
+
+API 端口(20128)和仪表盘端口(3000)在应用中配置。如需修改,你需要改源码或使用支持的环境变量(如果有)。
+
+---
+
+## 🛑 停止服务器
+
+在运行 9Router 的终端中按 `Ctrl+C`。
+
+```bash
+# 在运行 9router 的终端中
+^C  # 按 Ctrl+C
+```
+
+服务器会优雅关闭并保存所有数据。
+
+---
+
+## 🔄 重启服务器
+
+再次运行启动命令即可:
+
+```bash
+9router
+```
+
+所有配置、API keys 和组合都保存在数据目录中。
+
+---
+
+## 📊 更新 9Router
+
+更新到最新版本:
+
+```bash
+npm update -g 9router
+```
+
+查看当前版本:
+
+```bash
+npm list -g 9router
+```
+
+---
+
+## 🔍 故障排除
+
+### 端口已被占用
+
+如果端口 20128 或 3000 已被占用:
+
+```bash
+# 找到使用该端口的进程(macOS/Linux)
+lsof -i :20128
+lsof -i :3000
+
+# 杀掉进程
+kill -9 <PID>
+```
+
+### 权限错误
+
+安装过程中遇到权限错误:
+
+```bash
+# 使用 sudo(不推荐)
+sudo npm install -g 9router
+
+# 或修复 npm 权限(推荐)
+mkdir ~/.npm-global
+npm config set prefix '~/.npm-global'
+echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
+source ~/.bashrc
+```
+
+### 数据目录问题
+
+数据目录无法访问:
+
+```bash
+# 检查权限
+ls -la ~/.9router
+
+# 修复权限
+chmod 755 ~/.9router
+```
+
+---
+
+## 📁 数据目录结构
+
+```
+~/.9router/
+├── db.json           # 主数据库(提供商、组合、设置)
+├── logs/             # 应用日志
+└── cache/            # 临时缓存文件
+```
+
+**备份数据:**
+
+```bash
+# 备份
+cp -r ~/.9router ~/.9router.backup
+
+# 恢复
+cp -r ~/.9router.backup ~/.9router
+```
+
+---
+
+## 🔗 下一步
+
+- [连接提供商](/providers/subscription.md)
+- [创建组合](/features/combos.md)
+- [集成 CLI 工具](/integration/cursor.md)