ljwx-stock/DEPLOYMENT_GUIDE.md

部署指南：Claude × DeepSeek 智能投顾系统

快速开始 (5 分钟)

前置条件

# 检查 Docker 安装
docker --version        # >= 20.10
docker-compose --version # >= 1.29

# 检查系统资源
df -h /                 # 需要 60GB+ 可用空间
free -h                 # 需要 32GB+ RAM (推荐 64GB)

部署步骤

1️⃣ 准备环境变量

cd /root/work/stock

# 创建 .env 文件
cat > .env <<EOF
# OpenRouter API (用于 Claude)
OPENROUTER_API_KEY=your-openrouter-key-here

# TuShare API (可选，用于中文股票数据)
TUSHARE_TOKEN=your-tushare-token-here

# 应用环境
ENVIRONMENT=production
LOG_LEVEL=info
EOF

获取 API Key：

• OpenRouter: https://openrouter.ai/keys
• TuShare: https://tushare.pro/

2️⃣ 启动 Docker 服务

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

# 查看服务状态
docker-compose ps

# 输出应该类似：
# NAME                COMMAND              STATUS          PORTS
# stock_postgres      "docker-entrypoint"  Up 2 minutes    5433:5432
# stock_redis         "redis-server"       Up 2 minutes    6380:6379
# stock_ollama        "ollama serve"       Up 1 minute     11434:11434
# stock_backend       "python -m uvicorn" Up 1 minute     8001:8000
# stock_frontend      "docker-entrypoint"  Up 1 minute     8090:80
# stock_adminer       "docker-php"         Up 1 minute     8091:8080

3️⃣ 等待 DeepSeek 模型下载

# 监控 Ollama 容器日志
docker-compose logs -f ollama

# 预期输出：
# Pulling deepseek-coder:33b...
# Downloading 100%
# Model loaded successfully

# 验证模型是否已加载
docker-compose exec ollama ollama list

# 应该显示：
# NAME                    ID              SIZE
# deepseek-coder:33b      xxxxxxxx        33GB

⏱️ 首次启动时间：

• 模型下载：30-120 分钟（取决于网络速度）
• 后续启动：2-3 分钟

4️⃣ 验证系统健康

# 检查后端 API
curl http://localhost:8001/health
# 预期响应：
# {"status": "healthy", "database": true, "cache": true}

# 检查 Claude × DeepSeek 系统
curl http://localhost:8001/api/collab/health
# 预期响应：
# {
#   "status": "operational",
#   "components": {
#     "ollama": "available",
#     "deepseek": "available",
#     "claude": "available",
#     "yahoo_finance": "available"
#   }
# }

5️⃣ 打开前端

前端地址：http://localhost:8090
API 基地址：http://localhost:8001
数据库管理：http://localhost:8091 (Adminer)

---

完整部署清单

✅ 检查项

• Docker & Docker Compose 已安装
• 磁盘空间 >= 60GB
• 内存 >= 32GB
• 网络连接正常
• 防火墙规则已配置
• OPENROUTER_API_KEY 已配置
• docker-compose.yml 已调整（如需自定义）

📋 配置调整

1. 模型选择

# docker-compose.yml - ollama 服务
ollama:
  # ...
  entrypoint: |
    /bin/bash -c "
    /bin/ollama serve &
    OLLAMA_PID=$!;
    sleep 10;
    # 修改这行选择不同模型
    /bin/ollama pull deepseek-coder:33b;  # ← 默认
    # /bin/ollama pull deepseek-coder:7b;   # ← 轻量版
    wait $OLLAMA_PID;
    "

2. GPU 加速（可选）

# 如果有 NVIDIA GPU
ollama:
  runtime: nvidia
  environment:
    CUDA_VISIBLE_DEVICES: "0"  # 指定 GPU 编号
  # 性能提升：3-8 秒 → 1-2 秒

3. 端口映射调整

# 修改端口以避免冲突
services:
  backend:
    ports:
      - "8001:8000"  # ← 改为其他端口，如 8002:8000

  frontend:
    ports:
      - "8090:80"    # ← 改为其他端口，如 3000:80

4. 资源限制

# 为容器设置资源限制
services:
  backend:
    deploy:
      resources:
        limits:
          cpus: '4'
          memory: 8G
        reservations:
          cpus: '2'
          memory: 4G

---

生产环境部署

架构推荐

┌─────────────────────────┐
│   Nginx 反向代理         │
│  (端口 80, 443)         │
└────────────┬────────────┘
             │
    ┌────────┴────────┐
    │                 │
┌───▼────┐      ┌──────▼──┐
│ API    │      │ Frontend │
│ Gunicorn│     │ Nginx    │
│ (多进程) │     │ Static   │
└───┬────┘     └──────────┘
    │
┌───▼────────────────────────┐
│  容器编排 (Kubernetes)      │
│  - PostgreSQL StatefulSet  │
│  - Redis StatefulSet       │
│  - Ollama StatefulSet      │
│  - Backend Deployment      │
└────────────────────────────┘

Kubernetes 部署

# 1. 构建镜像
docker build -t stock-backend:latest ./backend
docker build -t stock-frontend:latest ./frontend

# 2. 推送到镜像仓库
docker tag stock-backend:latest your-registry/stock-backend:v1.0
docker push your-registry/stock-backend:v1.0

# 3. 部署
kubectl apply -f k8s/namespace.yaml
kubectl apply -f k8s/configmap.yaml
kubectl apply -f k8s/secrets.yaml
kubectl apply -f k8s/postgres.yaml
kubectl apply -f k8s/redis.yaml
kubectl apply -f k8s/ollama.yaml
kubectl apply -f k8s/backend.yaml
kubectl apply -f k8s/frontend.yaml
kubectl apply -f k8s/ingress.yaml

安全配置

# 1. 生成 SSL 证书
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
  -keyout /etc/nginx/ssl/key.pem \
  -out /etc/nginx/ssl/cert.pem

# 2. 配置 Nginx (SSL 终端)
# 见 nginx.conf 示例

# 3. 限制 API 访问
# 实现 Rate Limiting：每个 IP 每分钟 60 请求
# 实现 CORS：仅允许特定域名

# 4. 数据库加密
# 启用 PostgreSQL SSL 连接
# 启用 Redis 认证和 SSL

监控和日志

# 1. 日志聚合 (ELK Stack)
docker-compose up -d elasticsearch logstash kibana

# 2. 性能监控 (Prometheus + Grafana)
docker-compose up -d prometheus grafana

# 3. 应用追踪 (Jaeger)
docker-compose up -d jaeger

# 4. 告警规则
# - Ollama 不可用时告警
# - API 响应时间 > 10s 告警
# - 缓存命中率 < 50% 告警

---

故障恢复

容器崩溃恢复

# 自动重启
docker-compose up -d --restart=always

# 或在 docker-compose.yml 中配置
services:
  backend:
    restart: always  # 或 unless-stopped

数据备份

# 备份 PostgreSQL
docker-compose exec postgres pg_dump -U stockai stock_ai > backup.sql

# 备份 Redis
docker-compose exec redis redis-cli BGSAVE
docker cp stock_redis:/data/dump.rdb ./backup/

# 定期备份脚本
*/6 * * * * /root/work/stock/backup.sh  # 每 6 小时执行一次

升级流程

# 1. 备份数据
./backup.sh

# 2. 停止服务
docker-compose down

# 3. 更新代码
git pull origin main

# 4. 重建镜像
docker-compose build --no-cache

# 5. 启动服务
docker-compose up -d

# 6. 验证
docker-compose ps
curl http://localhost:8001/health

---

性能调优

1. 数据库优化

-- 创建索引
CREATE INDEX idx_stock_symbol ON stocks(symbol);
CREATE INDEX idx_recommendation_date ON recommendations(created_at DESC);

-- 查询优化
ANALYZE stock_ai;
VACUUM ANALYZE;

2. Redis 优化

# 调整最大内存
docker-compose exec redis redis-cli CONFIG SET maxmemory 2gb
docker-compose exec redis redis-cli CONFIG SET maxmemory-policy allkeys-lru

# 启用 AOF 持久化
docker-compose exec redis redis-cli CONFIG SET appendonly yes

3. 应用优化

# 批量操作
# 不好：逐条查询
for symbol in symbols:
    price = get_price(symbol)

# 好：批量操作
prices = batch_get_prices(symbols)

# 连接池
from sqlalchemy.pool import QueuePool
engine = create_engine(..., poolclass=QueuePool, pool_size=20)

4. 前端优化

// 请求防抖
const debouncedSearch = debounce(performSearch, 500);

// 结果缓存
const cache = new Map();
if (cache.has(symbol)) {
  return cache.get(symbol);
}

// 懒加载
const recommendation = await import('./ClaudeDeepSeekRecommendation.vue');

---

故障排查

问题 1：Ollama 容器无法启动

# 查看日志
docker-compose logs ollama

# 检查磁盘空间
df -h

# 手动运行 ollama
docker run -it -v ollama_data:/root/.ollama ollama/ollama:latest bash
ollama pull deepseek-coder:33b

问题 2：模型下载失败

# 配置 DNS
echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf

# 使用代理
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=https://proxy.example.com:8080

# 重试下载
docker-compose restart ollama

问题 3：API 响应超时

# 增加超时时间
# 在 deepseek_engine.py 中
self.timeout = 300  # 从 120 改为 300 秒

# 或在 docker-compose.yml 中
backend:
  environment:
    DEEPSEEK_TIMEOUT: "300"

问题 4：内存不足

# 查看内存使用
docker stats

# 减少容器内存限制
services:
  backend:
    deploy:
      resources:
        limits:
          memory: 4G

# 使用轻量级模型
ollama pull deepseek-coder:7b

---

清理和移除

# 停止所有服务
docker-compose down

# 删除容器和卷
docker-compose down -v

# 删除所有数据（谨慎！）
rm -rf postgres_data/ redis_data/ ollama_data/

# 完全清理
docker system prune -a

---

常见命令

# 查看日志
docker-compose logs -f backend

# 进入容器
docker-compose exec backend bash

# 查看进程
docker-compose ps

# 重启服务
docker-compose restart backend

# 查看网络
docker network ls
docker network inspect stock_network

# 查看卷
docker volume ls
docker volume inspect stock_postgres_data

# 导出/导入
docker-compose config > config-export.yml

---

支持和社区

• 📖 完整文档
• 🐛 提交 Issue
• 💬 讨论区
• 📧 Email: [email protected]

---

版本：1.0.0 最后更新：2025-11-12