详细部署指南

部署架构选择

根据您的规模和需求选择合适的部署架构：

🖥️

单机部署

适合小型团队，QPS < 100

单台服务器

SQLite 数据库

内存限流器

🔗

标准部署

适合中型团队，QPS < 1000

单台或多台服务器

MySQL/PostgreSQL

Redis 缓存

🔧

高可用部署

适合企业级应用，QPS > 1000

多实例负载均衡

主从数据库

Redis 集群

监控告警

☁️

云原生部署

适合容器化环境

Kubernetes 编排

自动伸缩

服务网格

云原生监控

环境准备

系统要求

最低配置
推荐配置（生产）
高可用配置

CPU：2 核
内存：2GB RAM
磁盘：10GB SSD
网络：10Mbps
操作系统：Linux / macOS / Windows

依赖软件

安装 Go（源码编译）

# 下载 Go 1.21+
wget https://go.dev/dl/go1.21.5.linux-amd64.tar.gz
sudo tar -C /usr/local -xzf go1.21.5.linux-amd64.tar.gz

# 配置环境变量
echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc
source ~/.bashrc

# 验证安装
go version

安装数据库

MySQL 8.0
PostgreSQL 14+
SQLite（默认）

# Ubuntu/Debian
sudo apt update
sudo apt install mysql-server
sudo systemctl start mysql
sudo systemctl enable mysql

# 创建数据库和用户
mysql -u root -p

CREATE DATABASE llm_gateway CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'llmgateway'@'%' IDENTIFIED BY 'your_password';
GRANT ALL PRIVILEGES ON llm_gateway.* TO 'llmgateway'@'%';
FLUSH PRIVILEGES;

# Ubuntu/Debian
sudo apt update
sudo apt install postgresql postgresql-contrib
sudo systemctl start postgresql
sudo systemctl enable postgresql

# 创建数据库和用户
sudo -u postgres psql

CREATE DATABASE llm_gateway;
CREATE USER llmgateway WITH PASSWORD 'your_password';
GRANT ALL PRIVILEGES ON DATABASE llm_gateway TO llmgateway;

SQLite 已内置，无需额外安装。适合开发和小规模部署。

# 数据文件将自动创建在：
./data/llm-gateway.db

安装 Redis（推荐）

# Ubuntu/Debian
sudo apt update
sudo apt install redis-server
sudo systemctl start redis-server
sudo systemctl enable redis-server

# 测试连接
redis-cli ping
# 应返回：PONG

Redis Stack（语义缓存必需）

如需使用语义缓存功能，必须安装 Redis Stack：

# Docker 方式（推荐）
docker run -d \
  --name redis-stack \
  -p 6379:6379 \
  -v redis-data:/data \
  redis/redis-stack:latest

或使用包管理器安装：

curl -fsSL https://packages.redis.io/gpg | sudo gpg --dearmor -o /usr/share/keyrings/redis-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/redis-archive-keyring.gpg] https://packages.redis.io/deb $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/redis.list
sudo apt-get update
sudo apt-get install redis-stack-server

部署方式

一键部署（推荐）

快速部署 LLM Gateway 到生产环境，支持开发模式和生产模式。

方式一：自动部署脚本

开发模式（默认）
生产模式

无需域名，快速启动开发环境：

# 下载并运行部署脚本
curl -O https://llmgateway.deep-cells.com/downloads/deployment/ec2-deploy.sh
chmod +x ec2-deploy.sh
./ec2-deploy.sh

# 特点：
# - 无需域名
# - 不配置 SSL/Nginx
# - 直接通过 http://localhost:3000 访问
# - 包含 LLM Gateway + MySQL + Redis

部署完成后访问：http://localhost:3000

需要域名，自动配置 SSL 证书：

# 下载并运行部署脚本（需替换为您的域名）
curl -O https://llmgateway.deep-cells.com/downloads/deployment/ec2-deploy.sh
chmod +x ec2-deploy.sh
./ec2-deploy.sh --prod your-domain.com

# 特点：
# - 需要域名（DNS 已解析到服务器）
# - 自动配置 Let's Encrypt SSL 证书
# - Nginx 反向代理
# - 通过 https://your-domain.com 访问
# - 包含完整的生产环境配置

部署完成后访问：https://your-domain.com

推荐使用场景

开发/测试环境：使用开发模式，快速启动
生产环境：使用生产模式，获得完整的安全配置
云服务器部署：AWS EC2、阿里云 ECS、腾讯云 CVM 等均适用

方式二：Docker Compose 手动部署

适合需要自定义配置的场景。

下载配置文件

# 下载 Docker Compose 配置
curl -O https://llmgateway.deep-cells.com/downloads/docker-compose/docker-compose.yml
curl -O https://llmgateway.deep-cells.com/downloads/docker-compose/.env.example

# 复制环境变量配置
cp .env.example .env

配置环境变量

# 生成安全的会话密钥
echo "SESSION_SECRET=$(openssl rand -base64 32)" >> .env

# 编辑 .env 文件，修改数据库密码等配置
nano .env

重要配置项：

MYSQL_ROOT_PASSWORD：MySQL root 密码
MYSQL_PASSWORD：应用数据库密码
SESSION_SECRET：会话加密密钥
REDIS_PASSWORD：Redis 密码（可选）

启动服务

# 开发模式：启动基础服务
docker-compose up -d

# 生产模式：启动包含 Nginx 的服务
docker-compose --profile production up -d

# 查看服务状态
docker-compose ps

# 查看日志
docker-compose logs -f llm-gateway

访问 http://localhost:3000 默认账号：root / 123456

安全提示

生产环境部署后，请立即：

修改默认管理员密码
更新 .env 中的所有密码
配置防火墙规则
启用 HTTPS（生产模式自动配置）

Docker 部署（完整配置）

准备 docker-compose.yml

docker-compose.yml
version: '3.8'

services:
  llm-gateway:
    image: deepcells/llm-gateway:latest
    container_name: llm-gateway
    restart: always
    ports:
      - "3000:3000"
    environment:
      - PORT=3000
      - GIN_MODE=release
      - SQL_DSN=mysql://llmgateway:password@mysql:3306/llm_gateway?charset=utf8mb4&parseTime=True&loc=Local
      - REDIS_CONN_STRING=redis://redis:6379
      - SESSION_SECRET=your-secret-key-change-me
      - LOG_DIR=/app/logs
    volumes:
      - ./data:/app/data
      - ./logs:/app/logs
    depends_on:
      - mysql
      - redis
    networks:
      - llm-network
  
  mysql:
    image: mysql:8.0
    container_name: llm-mysql
    restart: always
    environment:
      - MYSQL_ROOT_PASSWORD=rootpassword
      - MYSQL_DATABASE=llm_gateway
      - MYSQL_USER=llmgateway
      - MYSQL_PASSWORD=password
    volumes:
      - mysql-data:/var/lib/mysql
    ports:
      - "3306:3306"
    networks:
      - llm-network
    command: --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci
  
  redis:
    image: redis/redis-stack:latest
    container_name: llm-redis
    restart: always
    ports:
      - "6379:6379"
    volumes:
      - redis-data:/data
    networks:
      - llm-network
  
  nginx:
    image: nginx:alpine
    container_name: llm-nginx
    restart: always
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
      - ./ssl:/etc/nginx/ssl:ro
    depends_on:
      - llm-gateway
    networks:
      - llm-network

volumes:
  mysql-data:
  redis-data:

networks:
  llm-network:
    driver: bridge

配置 Nginx 反向代理

nginx.conf
events {
    worker_connections 4096;
}

http {
    upstream llm_backend {
        least_conn;
        server llm-gateway:3000 max_fails=3 fail_timeout=30s;
    }
    
    server {
        listen 80;
        server_name your-domain.com;
        
        # 重定向到 HTTPS
        return 301 https://$server_name$request_uri;
    }
    
    server {
        listen 443 ssl http2;
        server_name your-domain.com;
        
        ssl_certificate /etc/nginx/ssl/cert.pem;
        ssl_certificate_key /etc/nginx/ssl/key.pem;
        ssl_protocols TLSv1.2 TLSv1.3;
        ssl_ciphers HIGH:!aNULL:!MD5;
        
        client_max_body_size 100M;
        
        location / {
            proxy_pass http://llm_backend;
            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 支持（流式响应）
            proxy_buffering off;
            proxy_cache off;
            proxy_http_version 1.1;
            proxy_set_header Connection '';
            chunked_transfer_encoding off;
        }
    }
}

启动服务

# 启动所有服务
docker-compose up -d

# 查看日志
docker-compose logs -f llm-gateway

# 检查服务状态
docker-compose ps

# 停止服务
docker-compose down

二进制部署

下载二进制文件

# Linux AMD64
# 从官网下载最新版本
wget https://llmgateway.deep-cells.com/downloads/llm-gateway-linux-amd64.tar.gz
tar -xzf llm-gateway-linux-amd64.tar.gz
chmod +x llm-gateway

# 创建目录结构
sudo mkdir -p /opt/llm-gateway
sudo mv llm-gateway /opt/llm-gateway/
sudo mkdir -p /opt/llm-gateway/{data,logs}

创建配置文件

.env
# 数据库配置
SQL_DSN=mysql://llmgateway:password@localhost:3306/llm_gateway?charset=utf8mb4&parseTime=True&loc=Local

# Redis 配置
REDIS_CONN_STRING=redis://localhost:6379

# 服务配置
PORT=3000
GIN_MODE=release
SESSION_SECRET=your-secret-key-change-me
LOG_DIR=/opt/llm-gateway/logs

# 可选：HTTPS 配置
# TLS_CERT=/path/to/cert.pem
# TLS_KEY=/path/to/key.pem

创建 Systemd 服务

/etc/systemd/system/llm-gateway.service
[Unit]
Description=LLM Gateway Service
After=network.target mysql.service redis.service
Wants=mysql.service redis.service

[Service]
Type=simple
User=llmgateway
Group=llmgateway
WorkingDirectory=/opt/llm-gateway
EnvironmentFile=/opt/llm-gateway/.env
ExecStart=/opt/llm-gateway/llm-gateway
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal
SyslogIdentifier=llm-gateway

# 安全加固
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/opt/llm-gateway/data /opt/llm-gateway/logs

[Install]
WantedBy=multi-user.target

# 创建用户
sudo useradd -r -s /bin/false llmgateway
sudo chown -R llmgateway:llmgateway /opt/llm-gateway

# 启动服务
sudo systemctl daemon-reload
sudo systemctl enable llm-gateway
sudo systemctl start llm-gateway

# 查看状态
sudo systemctl status llm-gateway

# 查看日志
sudo journalctl -u llm-gateway -f

Kubernetes 部署

准备 Kubernetes 配置

k8s-deployment.yaml
apiVersion: v1
kind: Namespace
metadata:
  name: llm-gateway

---
apiVersion: v1
kind: ConfigMap
metadata:
  name: llm-gateway-config
  namespace: llm-gateway
data:
  PORT: "3000"
  GIN_MODE: "release"
  SQL_DSN: "mysql://llmgateway:password@mysql:3306/llm_gateway?charset=utf8mb4&parseTime=True&loc=Local"
  REDIS_CONN_STRING: "redis://redis:6379"

---
apiVersion: v1
kind: Secret
metadata:
  name: llm-gateway-secrets
  namespace: llm-gateway
type: Opaque
stringData:
  SESSION_SECRET: "your-secret-key-change-me"

---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: llm-gateway
  namespace: llm-gateway
spec:
  replicas: 3
  selector:
    matchLabels:
      app: llm-gateway
  template:
    metadata:
      labels:
        app: llm-gateway
    spec:
      containers:
      - name: llm-gateway
        image: deepcells/llm-gateway:latest
        ports:
        - containerPort: 3000
          name: http
        envFrom:
        - configMapRef:
            name: llm-gateway-config
        - secretRef:
            name: llm-gateway-secrets
        resources:
          requests:
            memory: "512Mi"
            cpu: "500m"
          limits:
            memory: "2Gi"
            cpu: "2000m"
        livenessProbe:
          httpGet:
            path: /api/status
            port: 3000
          initialDelaySeconds: 30
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /api/status
            port: 3000
          initialDelaySeconds: 10
          periodSeconds: 5
        volumeMounts:
        - name: data
          mountPath: /app/data
        - name: logs
          mountPath: /app/logs
      volumes:
      - name: data
        persistentVolumeClaim:
          claimName: llm-gateway-data
      - name: logs
        emptyDir: {}

---
apiVersion: v1
kind: Service
metadata:
  name: llm-gateway
  namespace: llm-gateway
spec:
  selector:
    app: llm-gateway
  ports:
  - protocol: TCP
    port: 3000
    targetPort: 3000
  type: ClusterIP

---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: llm-gateway
  namespace: llm-gateway
  annotations:
    cert-manager.io/cluster-issuer: "letsencrypt-prod"
    nginx.ingress.kubernetes.io/proxy-body-size: "100m"
    nginx.ingress.kubernetes.io/proxy-buffering: "off"
spec:
  ingressClassName: nginx
  tls:
  - hosts:
    - your-domain.com
    secretName: llm-gateway-tls
  rules:
  - host: your-domain.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: llm-gateway
            port:
              number: 3000

---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: llm-gateway-data
  namespace: llm-gateway
spec:
  accessModes:
  - ReadWriteMany
  resources:
    requests:
      storage: 50Gi
  storageClassName: standard

---
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: llm-gateway-hpa
  namespace: llm-gateway
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: llm-gateway
  minReplicas: 3
  maxReplicas: 10
  metrics:
  - type: Resource
    resource:
      name: cpu
      target:
        type: Utilization
        averageUtilization: 70
  - type: Resource
    resource:
      name: memory
      target:
        type: Utilization
        averageUtilization: 80

部署到 Kubernetes

# 应用配置
kubectl apply -f k8s-deployment.yaml

# 查看 Pod 状态
kubectl get pods -n llm-gateway

# 查看服务
kubectl get svc -n llm-gateway

# 查看日志
kubectl logs -f -n llm-gateway deployment/llm-gateway

# 查看 HPA 状态
kubectl get hpa -n llm-gateway

配置优化

数据库优化

MySQL 配置
PostgreSQL 配置

/etc/mysql/my.cnf
[mysqld]
# 基础配置
max_connections = 1000
max_allowed_packet = 100M

# InnoDB 配置
innodb_buffer_pool_size = 4G
innodb_log_file_size = 512M
innodb_flush_log_at_trx_commit = 2
innodb_flush_method = O_DIRECT

# 字符集
character-set-server = utf8mb4
collation-server = utf8mb4_unicode_ci

# 慢查询日志
slow_query_log = 1
long_query_time = 2
slow_query_log_file = /var/log/mysql/slow.log

/etc/postgresql/14/main/postgresql.conf
# 连接配置
max_connections = 1000
shared_buffers = 4GB
effective_cache_size = 12GB

# 写入优化
wal_buffers = 16MB
checkpoint_completion_target = 0.9

# 查询优化
random_page_cost = 1.1
effective_io_concurrency = 200
work_mem = 10MB

# 日志
log_min_duration_statement = 1000

Redis 配置

/etc/redis/redis.conf
# 内存配置
maxmemory 2gb
maxmemory-policy allkeys-lru

# 持久化（根据需求选择）
save 900 1
save 300 10
save 60 10000

# AOF 持久化（推荐）
appendonly yes
appendfsync everysec

# 性能优化
tcp-backlog 511
timeout 300
tcp-keepalive 300

# 慢查询日志
slowlog-log-slower-than 10000
slowlog-max-len 128

系统参数优化

# 增加文件描述符限制
echo "* soft nofile 65535" >> /etc/security/limits.conf
echo "* hard nofile 65535" >> /etc/security/limits.conf

# 优化网络参数
cat >> /etc/sysctl.conf <<EOF
net.core.somaxconn = 65535
net.ipv4.tcp_max_syn_backlog = 8192
net.ipv4.tcp_tw_reuse = 1
net.ipv4.ip_local_port_range = 1024 65535
EOF

sysctl -p

安全加固

配置防火墙

# UFW (Ubuntu)
sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable

# Firewalld (CentOS)
sudo firewall-cmd --permanent --add-service=http
sudo firewall-cmd --permanent --add-service=https
sudo firewall-cmd --reload

配置 SSL/TLS

使用 Let's Encrypt 免费证书

# 安装 Certbot
sudo apt install certbot python3-certbot-nginx

# 获取证书
sudo certbot --nginx -d your-domain.com

# 自动续期
sudo certbot renew --dry-run

使用自签名证书（测试）

openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
  -keyout /etc/nginx/ssl/key.pem \
  -out /etc/nginx/ssl/cert.pem \
  -subj "/CN=your-domain.com"

配置访问控制

在 LLM Gateway 中启用：

✅ 强制 HTTPS
✅ 启用限流保护
✅ 启用 Prompt 防火墙
✅ 配置 IP 白名单（令牌级别）
✅ 启用审计日志

监控告警

Prometheus + Grafana

Prometheus 配置

prometheus.yml
global:
  scrape_interval: 15s
  evaluation_interval: 15s

scrape_configs:
  - job_name: 'llm-gateway'
    static_configs:
      - targets: ['localhost:3000']
    metrics_path: '/api/metrics'

日志管理

日志轮转
集中式日志（ELK）

/etc/logrotate.d/llm-gateway
/opt/llm-gateway/logs/*.log {
    daily
    rotate 30
    compress
    delaycompress
    notifempty
    create 0644 llmgateway llmgateway
    sharedscripts
    postrotate
        systemctl reload llm-gateway
    endscript
}

使用 Filebeat 收集日志：

filebeat.yml
filebeat.inputs:
- type: log
  enabled: true
  paths:
    - /opt/llm-gateway/logs/*.log
  fields:
    service: llm-gateway

output.elasticsearch:
  hosts: ["elasticsearch:9200"]

备份策略

数据库备份

# MySQL 每日自动备份
cat > /etc/cron.daily/backup-llm-db <<'EOF'
#!/bin/bash
BACKUP_DIR="/backup/llm-gateway"
DATE=$(date +%Y%m%d)
mkdir -p $BACKUP_DIR

mysqldump -u llmgateway -p'password' llm_gateway \
  | gzip > $BACKUP_DIR/llm-gateway-$DATE.sql.gz

# 保留最近 30 天
find $BACKUP_DIR -name "*.sql.gz" -mtime +30 -delete
EOF

chmod +x /etc/cron.daily/backup-llm-db

文件备份

# 备份配置和数据
tar -czf llm-gateway-backup-$(date +%Y%m%d).tar.gz \
  /opt/llm-gateway/.env \
  /opt/llm-gateway/data \
  /etc/nginx/sites-available/llm-gateway

升级指南

备份当前版本

# 备份数据库
mysqldump -u llmgateway -p llm_gateway > backup-before-upgrade.sql

# 备份配置文件
cp /opt/llm-gateway/.env /opt/llm-gateway/.env.backup

停止服务

# Systemd
sudo systemctl stop llm-gateway

# Docker
docker-compose down

更新程序

# 二进制
wget https://llmgateway.deep-cells.com/downloads/llm-gateway-linux-amd64.tar.gz
tar -xzf llm-gateway-linux-amd64.tar.gz
sudo mv llm-gateway /opt/llm-gateway/llm-gateway.new
sudo mv /opt/llm-gateway/llm-gateway /opt/llm-gateway/llm-gateway.old
sudo mv /opt/llm-gateway/llm-gateway.new /opt/llm-gateway/llm-gateway

# Docker
docker-compose pull

启动服务

# Systemd
sudo systemctl start llm-gateway
sudo systemctl status llm-gateway

# Docker
docker-compose up -d
docker-compose logs -f

验证升级

# 检查版本
curl http://localhost:3000/api/status

# 检查日志
sudo journalctl -u llm-gateway -n 50

故障排查

服务无法启动

检查步骤：

查看日志：

sudo journalctl -u llm-gateway -n 100 --no-pager

检查端口占用：
```
sudo netstat -tlnp | grep 3000
```

检查数据库连接：

mysql -h localhost -u llmgateway -p llm_gateway

检查 Redis 连接：
```
redis-cli ping
```

数据库连接失败

常见原因：

SQL_DSN 格式错误
数据库用户权限不足
数据库服务未启动
防火墙拦截

解决方法：

# 检查 MySQL 状态
sudo systemctl status mysql

# 测试连接
mysql -h localhost -u llmgateway -p

# 检查权限
SHOW GRANTS FOR 'llmgateway'@'%';

API 请求超时

可能原因：

上游 LLM 提供商响应慢
数据库查询慢
网络延迟

解决方法：

查看慢查询日志
检查渠道健康状态
调整超时配置
启用语义缓存

内存占用过高

优化措施：

调整 Go GC 参数：
```
GOGC=50 ./llm-gateway
```
限制并发数：在系统设置中降低最大并发连接数

优化 Redis 缓存策略：

maxmemory 2gb
maxmemory-policy allkeys-lru

性能调优

🗄️

数据库调优

添加适当索引

定期清理历史日志

启用查询缓存

使用连接池

⚡

应用层调优

启用 Redis 缓存

启用语义缓存

调整 Gin 性能参数

使用 CDN 加速静态资源

🌐

网络调优

使用 HTTP/2

启用 Gzip 压缩

配置 CDN

优化 TCP 参数

🖥️

系统调优

增加文件描述符限制

优化内核参数

使用 SSD 存储

配置 NUMA

下一步

🔌

渠道管理

开始配置您的 LLM 渠道

部署架构选择​

环境准备​

系统要求​

依赖软件​

安装 Go（源码编译）

安装数据库

安装 Redis（推荐）

部署方式​

一键部署（推荐）​

方式一：自动部署脚本​

方式二：Docker Compose 手动部署​

下载配置文件

配置环境变量

启动服务

Docker 部署（完整配置）​

准备 docker-compose.yml

配置 Nginx 反向代理

启动服务

二进制部署​

下载二进制文件

创建配置文件

创建 Systemd 服务

Kubernetes 部署​

准备 Kubernetes 配置

部署到 Kubernetes

配置优化​

数据库优化​

Redis 配置​

系统参数优化​

安全加固​

配置防火墙

配置 SSL/TLS

配置访问控制

监控告警​

Prometheus + Grafana​

日志管理​

备份策略​

数据库备份

文件备份

升级指南​

备份当前版本

停止服务

更新程序

启动服务

验证升级

故障排查​

性能调优​

下一步​

部署架构选择

环境准备

系统要求

依赖软件

部署方式

一键部署（推荐）

方式一：自动部署脚本

方式二：Docker Compose 手动部署

Docker 部署（完整配置）

二进制部署

Kubernetes 部署

配置优化

数据库优化

Redis 配置

系统参数优化

安全加固

监控告警

Prometheus + Grafana

日志管理

备份策略

升级指南

故障排查

性能调优

下一步