gao/ljwx-stock
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
ljwx-stock/DEPLOYMENT_CHECKLIST.md
T
bruno cbc9e25fd9 transfer to macbook
2025-11-15 20:38:47 +08:00

9.9 KiB
Raw Permalink Blame History

🚀 部署检查清单（Deployment Checklist）

📋 预部署步骤（Pre-Deployment Steps）

Step 1: 验证本地代码状态

cd /Users/brunogao/work/codes/stock/claude-stock

# 检查是否有未提交的变更
git status
# 预期: 干净的工作区 (clean working tree)

# 查看最新提交
git log --oneline -1
# 预期: d306a0d feat: Complete CICD automation with .env configuration and K8s secrets

Status: ✅ VERIFIED

  • All files committed
  • 2 commits ahead of origin/main ready to push

Step 2: 配置 Gitea Secrets（一次性配置）

访问地址: http://192.168.1.83:33000/gao/claude-stock/settings/secrets

需要添加的 Secrets:

Secret 名称 值 用途
OPENROUTER_API_KEY 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 Claude API 访问
ALPHA_VANTAGE_API_KEY FFJVQK6LCQ5RSPNH 美股数据 API
TUSHARE_TOKEN 64176da873385fb344ab6420494f2fac6fc2c3c0e1b10d47f8d9925a A股数据 API
HARBOR_PASSWORD Harbor12345 Harbor 镜像仓库密码
KUBECONFIG (已配置) Kubernetes 访问凭证

添加步骤:

  1. 登录 Gitea (http://192.168.1.83:33000)
  2. 进入 gao/claude-stock 仓库
  3. 点击 Settings → Secrets
  4. 逐个添加上表中的 Secret
  5. 点击 "Add Secret" 确认

Verification Command:

# 验证 Secrets 已创建 (访问后确认页面显示所有 Secret)
curl -s http://192.168.1.83:33000/api/v1/repos/gao/claude-stock/keys \
  -H "Authorization: token $GITEA_TOKEN" | jq '.[] | .name'

Step 3: 验证本地文件配置

检查 .env 文件:

# 确认 API Keys 已正确设置
grep -E "OPENROUTER|ALPHA_VANTAGE|TUSHARE" /Users/brunogao/work/codes/stock/claude-stock/.env

# 预期输出:
# OPENROUTER_API_KEY=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
# ALPHA_VANTAGE_API_KEY=FFJVQK6LCQ5RSPNH
# TUSHARE_TOKEN=64176da873385fb344ab6420494f2fac6fc2c3c0e1b10d47f8d9925a

Status: ✅ VERIFIED

  • .env file contains all required credentials
  • .env.example available as template

Step 4: 验证 K8s 集群连接

# 检查 kubectl 访问
kubectl cluster-info

# 预期: 显示 Kubernetes 集群信息

# 检查节点状态
kubectl get nodes

# 预期: 所有节点 Ready 状态

Status: ✅ VERIFIED

  • Kubernetes cluster accessible
  • KUBECONFIG properly configured

🚀 部署步骤（Deployment Steps）

Step 5: 推送代码触发 CICD

# 进入项目目录
cd /Users/brunogao/work/codes/stock/claude-stock

# 推送到 main 分支（触发自动部署）
git push origin main

预期输出:

Counting objects: 15, done.
Delta compression using up to 12 threads.
Compressing objects: 100% (12/12), done.
Writing objects: 100% (15/15), ...
remote: ✅ All tasks completed successfully!

Status: ⏳ PENDING

  • Execute: git push origin main

Step 6: 实时监控 CICD 进度

方法 1: 查看 Gitea Actions:

访问: http://192.168.1.83:33000/gao/claude-stock/actions

预期工作流程:

  1. Build & Push (3-5 分钟)

    • ✅ 检出代码
    • ✅ 登录 Harbor
    • ✅ 构建 Backend 镜像
    • ✅ 推送到 Harbor
    • ✅ 构建 & 推送 Frontend 镜像

  2. Test (2-3 分钟)

    • ✅ 安装测试工具
    • ✅ 运行 pytest
    • ✅ 生成覆盖率报告

  3. Security Scan (1-2 分钟)

    • ✅ Trivy 镜像扫描

  4. Deploy (5-10 分钟)

    • ✅ 创建 namespace
    • ✅ 创建 Harbor Secret
    • ✅ 创建 API Keys Secret ← 关键步骤
    • ✅ 部署 PostgreSQL & Redis
    • ✅ 部署 ConfigMap & Service
    • ✅ 部署 Backend Deployment
    • ✅ 等待所有服务就绪

  5. Smoke Test (2-3 分钟)

    • ✅ 健康检查
    • ✅ API 验证

方法 2: 监控 Kubernetes 部署:

# 实时查看 Pod 状态
kubectl get pods -n claude-stock -w

# 预期输出 (After ~10-15 minutes):
# NAME                              READY   STATUS    RESTARTS   AGE
# postgres-0                        1/1     Running   0          5m
# redis-0                           1/1     Running   0          5m
# claude-stock-backend-abc123       1/1     Running   0          3m
# claude-stock-frontend-def456      1/1     Running   0          3m

完整部署时间: 约 15-25 分钟

✅ 验证部署成功（Verification Steps）

Step 7: 检查所有 K8s 资源

# 查看所有资源
kubectl get all -n claude-stock

# 预期输出示例:
# pod/postgres-0                          1/1     Running   0      5m
# pod/redis-0                             1/1     Running   0      5m
# pod/claude-stock-backend-abc123         1/1     Running   0      3m
# pod/claude-stock-frontend-def456        1/1     Running   0      3m
#
# service/postgres                ClusterIP   None         <none>
# service/redis                   ClusterIP   None         <none>
# service/claude-stock-backend    LoadBalancer  192.168.194.248  <pending>
# service/claude-stock-frontend   LoadBalancer  192.168.194.249  <pending>
#
# deployment.apps/claude-stock-backend    1/1     1            1           3m
# deployment.apps/claude-stock-frontend   1/1     1            1           3m
#
# statefulset.apps/postgres   1         1         5m
# statefulset.apps/redis      1         1         5m

Verification Checklist:

  • All 4 Pods in "Running" status
  • All Services created
  • All Deployments at desired replicas
  • PostgreSQL StatefulSet ready
  • Redis StatefulSet ready

Step 8: 验证 API Keys Secret

# 确认 Secret 已创建
kubectl get secret claude-stock-secrets -n claude-stock

# 预期输出:
# NAME                      TYPE     DATA   AGE
# claude-stock-secrets      Opaque   3      3m

# 查看 Secret 详情（不显示实际值，只显示 key）
kubectl get secret claude-stock-secrets -n claude-stock -o jsonpath='{.data}'

# 预期: {"alpha_vantage_api_key":"...", "openrouter_api_key":"...", "tushare_token":"..."}

Status: ✅ VERIFIED

  • CICD workflow includes Secret creation step
  • All 3 API keys will be stored in claude-stock-secrets

Step 9: 测试后端 API

# 获取后端 Pod 名称
BACKEND_POD=$(kubectl get pods -n claude-stock -l app=claude-stock-backend -o name | head -1)
echo "Backend Pod: $BACKEND_POD"

# 方法 1: 通过 Port Forward
kubectl port-forward -n claude-stock $BACKEND_POD 8001:8000 &
sleep 2

# 测试健康检查
curl http://localhost:8001/health

# 预期输出:
# {"status":"ok","timestamp":"2025-11-13T..."}

# 测试推荐 API (使用 Alpha Vantage API)
curl -X POST http://localhost:8001/api/collab/recommend \
  -H "Content-Type: application/json" \
  -d '{"symbol": "AAPL"}'

# 预期: 返回股票推荐数据

# 停止端口转发
pkill -f "kubectl port-forward"

Step 10: 查看版本追踪

# 查看所有 Pod 的 git commit SHA
kubectl get pods -n claude-stock -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.metadata.labels.git-commit}{"\n"}{end}'

# 预期输出:
# postgres-0                     d306a0d
# redis-0                        d306a0d
# claude-stock-backend-abc123    d306a0d
# claude-stock-frontend-def456   d306a0d

# 查看完整注解
kubectl describe pod postgres-0 -n claude-stock | grep -A 10 "Labels:"

# 预期包含: git-commit=d306a0d, git-repository=gao/claude-stock

🔍 故障排查（Troubleshooting）

问题 1: CICD 部署失败

检查步骤:

# 1. 查看 CICD 日志
curl -s http://192.168.1.83:33000/gao/claude-stock/actions

# 2. 检查是否所有 Secrets 已添加
curl -s http://192.168.1.83:33000/api/v1/repos/gao/claude-stock/keys \
  -H "Authorization: token $GITEA_TOKEN" | jq '.[] | .name'

# 预期: 应显示 OPENROUTER_API_KEY, ALPHA_VANTAGE_API_KEY, TUSHARE_TOKEN, HARBOR_PASSWORD, KUBECONFIG

# 3. 检查 Kubernetes 连接
kubectl cluster-info

问题 2: Pod 无法启动

# 查看 Pod 状态
kubectl describe pod <pod-name> -n claude-stock

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

# 查看事件
kubectl get events -n claude-stock --sort-by='.lastTimestamp'

问题 3: 后端无法连接数据库

# 检查 PostgreSQL Pod 日志
kubectl logs postgres-0 -n claude-stock

# 检查数据库连接
kubectl exec -it postgres-0 -n claude-stock -- psql -U stockai -d stock_ai -c "SELECT version();"

# 预期: 显示 PostgreSQL 版本信息

问题 4: 缺少 API Keys

# 验证 Secret 是否已创建
kubectl get secret claude-stock-secrets -n claude-stock -o yaml

# 验证 Deployment 环境变量配置
kubectl get deployment claude-stock-backend -n claude-stock -o yaml | grep -A 30 "env:"

📊 最终验证清单（Final Verification Checklist）

项目 检查项 状态
代码提交 所有变更已提交 ✅
CICD 配置 .gitea/workflows/cicd.yml 完整 ✅
K8s 清单 所有 5 个 YAML 文件存在 ✅
环境配置 .env 包含所有 API Keys ✅
Backend 配置 config.py 支持 ALPHA_VANTAGE_API_KEY ✅
Gitea Secrets 5 个 Secrets 已配置 ⏳ 待配置
代码推送 git push origin main 已执行 ⏳ 待执行
CICD 完成 所有工作流任务成功 ⏳ 待执行
Pod 运行 4 个 Pods 全部 Running ⏳ 待验证
API 测试 /health 和 /api/collab/recommend 可用 ⏳ 待验证

🎯 立即开始（Quick Start）

# 1. 在 Gitea 中配置 Secrets (http://192.168.1.83:33000)
# 2. 执行推送
cd /Users/brunogao/work/codes/stock/claude-stock
git push origin main

# 3. 监控部署
kubectl get pods -n claude-stock -w

# 4. 验证 API
curl http://localhost:8001/health

最后更新: 2025-11-13 部署版本: d306a0d (Complete CICD automation) 预期部署时间: 15-25 分钟 状态: ✅ 就绪部署 (Ready for Deployment)

Reference in New Issue View Git Blame Copy Permalink