ljwx-stock/DEPLOYMENT.md

Claude Stock - 部署指南

目录

• 一键部署
• 手动部署
• CI/CD 自动部署
• 配置 API Keys
• 故障排查

---

一键部署

快速开始

使用提供的部署脚本一键部署到 Kubernetes：

cd /Users/brunogao/work/codes/stock/claude-stock
./deploy.sh

部署脚本功能

脚本将自动完成以下步骤：

1. ✅ 构建 Docker 镜像

   • Backend: stock-backend:latest
   • Frontend: stock-frontend:latest

2. ✅ 创建 Kubernetes 资源

   • Namespace: stock
   • PostgreSQL 数据库（StatefulSet）
   • Redis 缓存
   • Backend 和 Frontend 部署（各 2 副本）

3. ✅ 等待部署完成

   • 自动等待所有 Pod 就绪

4. ✅ 显示部署状态

   • Pods、Services、Ingress 状态

访问应用

部署成功后，访问：

• URL: https://stock.omniverseai.net
• API: https://stock.omniverseai.net/api
• WebSocket: https://stock.omniverseai.net/ws

---

手动部署

步骤 1: 构建镜像

# 构建 Backend
cd backend
docker build -t stock-backend:latest .

# 构建 Frontend
cd ../frontend
docker build -t stock-frontend:latest .

步骤 2: 部署到 Kubernetes

# 创建 namespace
kubectl create namespace stock

# 部署应用
kubectl apply -f k8s/stock-deployment.yaml

步骤 3: 配置 API Keys (可选)

# 更新 secrets
kubectl edit secret stock-secrets -n stock

# 或使用 kubectl create secret
kubectl create secret generic stock-secrets \
  --from-literal=OPENROUTER_API_KEY=sk-or-v1-xxx \
  --from-literal=TUSHARE_TOKEN=your-token \
  --from-literal=ALPHA_VANTAGE_API_KEY=your-key \
  -n stock --dry-run=client -o yaml | kubectl apply -f -

步骤 4: 验证部署

# 查看 Pods
kubectl get pods -n stock

# 查看 Services
kubectl get svc -n stock

# 查看 Ingress
kubectl get ingress -n stock

---

CI/CD 自动部署

配置 Gitea Secrets

在 Gitea 仓库设置中添加以下 Secrets：

1. KUBECONFIG

cat ~/.kube/config | base64 | tr -d '\n'

将输出的 base64 字符串作为 Secret 值

2. OPENROUTER_API_KEY

OpenRouter API Key for Claude AI

sk-or-v1-xxxxxxxxxxxxxxxx

3. TUSHARE_TOKEN

TuShare Token for Chinese stock data

your-tushare-token

4. ALPHA_VANTAGE_API_KEY

Alpha Vantage API Key

your-alpha-vantage-key

触发部署

推送代码到 main 分支会自动触发 CI/CD 流程：

git add .
git commit -m "Update application"
git push origin main

CI/CD 流程

1. Build - 构建 Docker 镜像（Backend + Frontend）
2. Test - 运行单元测试（使用 PostgreSQL service）
3. Deploy - 部署到 Kubernetes（stock namespace）
4. Verify - 健康检查验证

查看 CI/CD 状态

访问 Gitea Actions 页面查看部署进度：

• Gitea URL: http://<gitea-url>/claude-stock/actions

---

配置 API Keys

为什么需要 API Keys？

• OPENROUTER_API_KEY: Claude AI 分析和推荐功能
• TUSHARE_TOKEN: 获取中国 A 股数据
• ALPHA_VANTAGE_API_KEY: 获取美股和外汇数据

配置方法

方法 1: 通过 kubectl

kubectl edit secret stock-secrets -n stock

方法 2: 更新 K8s YAML

编辑 k8s/stock-deployment.yaml 中的 Secret 部分：

apiVersion: v1
kind: Secret
metadata:
  name: stock-secrets
  namespace: stock
type: Opaque
stringData:
  OPENROUTER_API_KEY: "sk-or-v1-your-real-key"
  TUSHARE_TOKEN: "your-real-token"
  ALPHA_VANTAGE_API_KEY: "your-real-key"

然后重新应用：

kubectl apply -f k8s/stock-deployment.yaml
kubectl rollout restart deployment/stock-backend -n stock

---

常用命令

查看日志

# Backend 日志
kubectl logs -n stock -l app=stock-backend -f

# Frontend 日志
kubectl logs -n stock -l app=stock-frontend -f

# PostgreSQL 日志
kubectl logs -n stock stock-postgres-0 -f

# Redis 日志
kubectl logs -n stock -l app=stock-redis -f

重启服务

# 重启 Backend
kubectl rollout restart deployment/stock-backend -n stock

# 重启 Frontend
kubectl rollout restart deployment/stock-frontend -n stock

# 重启 Redis
kubectl rollout restart deployment/stock-redis -n stock

扩缩容

# 扩容 Backend 到 3 个副本
kubectl scale deployment/stock-backend -n stock --replicas=3

# 扩容 Frontend 到 3 个副本
kubectl scale deployment/stock-frontend -n stock --replicas=3

访问数据库

# 进入 PostgreSQL Pod
kubectl exec -it -n stock stock-postgres-0 -- psql -U stockai -d stock_ai

# 直接执行 SQL
kubectl exec -it -n stock stock-postgres-0 -- psql -U stockai -d stock_ai -c "SELECT * FROM recommendations LIMIT 10;"

# 导出数据
kubectl exec -it -n stock stock-postgres-0 -- pg_dump -U stockai stock_ai > backup.sql

访问 Redis

# 进入 Redis Pod
kubectl exec -it -n stock <redis-pod-name> -- redis-cli

# 查看缓存统计
kubectl exec -it -n stock <redis-pod-name> -- redis-cli INFO stats

# 清空缓存
kubectl exec -it -n stock <redis-pod-name> -- redis-cli FLUSHALL

---

故障排查

Pod 无法启动

# 查看 Pod 事件
kubectl describe pod -n stock <pod-name>

# 查看 Pod 日志
kubectl logs -n stock <pod-name>

# 查看上一次的日志（如果 Pod 重启）
kubectl logs -n stock <pod-name> --previous

Backend 健康检查失败

检查 TuShare 初始化问题：

# 查看 backend 日志
kubectl logs -n stock -l app=stock-backend | grep -i tushare

# 确认 API keys 是否配置
kubectl get secret stock-secrets -n stock -o yaml

常见原因：

• TuShare token 为 "placeholder" 导致初始化失败（已修复）
• 健康检查超时（已优化 probe 配置）

数据库连接失败

检查 PostgreSQL 状态：

kubectl get pods -n stock -l app=stock-postgres
kubectl logs -n stock stock-postgres-0

验证数据库连接：

kubectl exec -it -n stock stock-postgres-0 -- psql -U stockai -d stock_ai -c "SELECT 1;"

Redis 连接失败

检查 Redis 状态：

kubectl get pods -n stock -l app=stock-redis
kubectl logs -n stock -l app=stock-redis

测试 Redis 连接：

kubectl exec -it -n stock <redis-pod> -- redis-cli PING

Ingress 无法访问

检查 Ingress 配置：

kubectl describe ingress -n stock

检查 Ingress Controller：

kubectl get pods -n infra -l app.kubernetes.io/name=ingress-nginx
kubectl logs -n infra -l app.kubernetes.io/name=ingress-nginx

测试本地访问：

curl -H "Host: stock.omniverseai.net" http://localhost:31080/
curl -H "Host: stock.omniverseai.net" http://localhost:31080/api/health

---

配置说明

环境变量

Backend 环境变量在 K8s ConfigMap 和 Secret 中配置：

ConfigMap (stock-config):

• APP_ENV: production
• API_PORT: 8000
• LLM_MODEL: anthropic/claude-4.5-sonnet
• LLM_TEMPERATURE: 0.7
• CACHE_TTL_*: 各类数据的缓存时间

Secret (stock-secrets):

• DATABASE_URL: PostgreSQL 连接字符串
• REDIS_URL: Redis 连接字符串
• OPENROUTER_API_KEY: OpenRouter API Key
• TUSHARE_TOKEN: TuShare Token
• ALPHA_VANTAGE_API_KEY: Alpha Vantage API Key

资源限制

默认资源配置：

Backend:

• Requests: 512Mi memory, 500m CPU
• Limits: 2Gi memory, 2000m CPU
• Replicas: 2

Frontend:

• Requests: 128Mi memory, 100m CPU
• Limits: 512Mi memory, 500m CPU
• Replicas: 2

PostgreSQL:

• Requests: 256Mi memory, 200m CPU
• Limits: 1Gi memory, 1000m CPU
• Storage: 默认使用 emptyDir (可改为 PVC)

Redis:

• Requests: 128Mi memory, 100m CPU
• Limits: 512Mi memory, 500m CPU

健康检查

Backend 健康检查端点：

• Liveness: /health (45s 初始延迟, 每 15 秒检查, 10s 超时)
• Readiness: /health (20s 初始延迟, 每 10 秒检查, 8s 超时)

说明：

• /health: 快速健康检查（不查询数据库/缓存）
• /api/health: 详细健康检查（包含数据库和缓存状态）

---

数据持久化

PostgreSQL 数据持久化

当前使用 StatefulSet + emptyDir（数据会在 Pod 重启时丢失）。

生产环境建议使用 PVC：

volumeClaimTemplates:
  - metadata:
      name: postgres-data
    spec:
      accessModes: ["ReadWriteOnce"]
      resources:
        requests:
          storage: 10Gi

数据备份

# 备份数据库
kubectl exec -n stock stock-postgres-0 -- pg_dump -U stockai stock_ai > backup-$(date +%Y%m%d).sql

# 恢复数据库
kubectl exec -i -n stock stock-postgres-0 -- psql -U stockai stock_ai < backup-20231123.sql

---

更新应用

方式 1: 使用部署脚本

./deploy.sh

方式 2: 手动更新

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

# 重启部署触发更新
kubectl rollout restart deployment/stock-backend -n stock
kubectl rollout restart deployment/stock-frontend -n stock

方式 3: Git Push 触发 CI/CD

git push origin main

---

回滚部署

# 查看部署历史
kubectl rollout history deployment/stock-backend -n stock

# 回滚到上一个版本
kubectl rollout undo deployment/stock-backend -n stock

# 回滚到特定版本
kubectl rollout undo deployment/stock-backend -n stock --to-revision=2

---

监控和日志

实时监控

# 监控 Pod 状态
watch kubectl get pods -n stock

# 监控资源使用
kubectl top pods -n stock
kubectl top nodes

日志聚合

# 查看所有 Backend Pods 的日志
kubectl logs -n stock -l app=stock-backend --tail=100 -f

# 查看特定时间范围的日志
kubectl logs -n stock <pod-name> --since=1h

# 过滤特定关键词
kubectl logs -n stock -l app=stock-backend | grep ERROR

---

性能优化

缓存优化

Redis 缓存配置（在 ConfigMap 中）：

• CACHE_TTL_QUOTE: 60 秒 - 股票行情缓存
• CACHE_TTL_FEATURES: 300 秒 - 技术指标缓存
• CACHE_TTL_RECOMMENDATION: 60 秒 - 推荐结果缓存
• CACHE_TTL_LLM: 3600 秒 - AI 分析缓存

数据库优化

# 进入数据库查看索引
kubectl exec -it -n stock stock-postgres-0 -- psql -U stockai -d stock_ai

# 查看表大小
SELECT schemaname, tablename, 
       pg_size_pretty(pg_total_relation_size(schemaname||'.'||tablename)) AS size
FROM pg_tables
WHERE schemaname = 'public'
ORDER BY pg_total_relation_size(schemaname||'.'||tablename) DESC;

# 创建索引（如果需要）
CREATE INDEX idx_recommendations_symbol ON recommendations(symbol);
CREATE INDEX idx_recommendations_created_at ON recommendations(created_at);

---

清理资源

删除应用

# 删除应用但保留 namespace
kubectl delete -f k8s/stock-deployment.yaml

# 删除整个 namespace（包括所有资源）
kubectl delete namespace stock

清理 Docker 镜像

docker rmi stock-backend:latest
docker rmi stock-frontend:latest

---

支持

如有问题，请查看：

• Kubernetes 日志
• 应用日志
• Ingress Controller 日志
• PostgreSQL 日志
• Redis 日志

或查看项目文档和 GitHub Issues。