ljwx-children/DEPLOYMENT-GUIDE.md

🚀 Gold Template - 完整实施方案

📋 实施概览

本文档描述了针对 Mac Studio + OrbStack 环境的完整实施方案，包括：

• ✅ Kubernetes + Helm 部署配置
• ✅ 生产级 Docker 镜像
• ✅ 完整的 CI/CD Pipeline
• ✅ OpenSec 安全集成
• ✅ Claude Code Skills 扩展
• ✅ 智能化部署脚本

🏗️ 环境信息

实际环境：

• 系统： macOS 15.7 (ARM64)
• K8s： OrbStack v1.33.5 (单节点集群)
• 节点名： orbstack
• 容器运行时： Docker 28.5.2
• Helm： v4.0.0
• kubectl： v1.33.3

📦 已实施组件

1. Kubernetes + Helm 部署

目录结构：

deployment/
├── helm/gold-template/
│   ├── Chart.yaml                    # Helm Chart 定义
│   ├── values.yaml                   # 默认配置
│   ├── values-orbstack.yaml          # OrbStack 优化配置 ⭐
│   ├── values-dev.yaml               # 开发环境配置
│   ├── values-prod.yaml              # 生产环境配置
│   └── templates/
│       ├── _helpers.tpl              # Helm 模板助手
│       ├── deployment.yaml           # Deployment 资源
│       ├── service.yaml              # Service 资源
│       ├── ingress.yaml              # Ingress 资源
│       ├── configmap.yaml            # ConfigMap 资源
│       ├── secret.yaml               # Secret 资源
│       ├── pvc.yaml                  # PersistentVolumeClaim
│       ├── serviceaccount.yaml       # ServiceAccount
│       └── hpa.yaml                  # HorizontalPodAutoscaler

OrbStack 优化配置特点：

• 单副本部署（replicaCount: 1）
• 节点选择器：kubernetes.io/hostname: orbstack
• 禁用 Ingress（OrbStack 使用内置路由）
• 禁用自动扩展（单节点环境）
• 禁用网络策略（简化开发）
• 本地镜像仓库：localhost:5000

2. Docker 镜像

Dockerfile 特性：

• ✅ 多阶段构建（builder + production）
• ✅ 最小化镜像大小
• ✅ 非 root 用户运行
• ✅ 健康检查
• ✅ 安全上下文
• ✅ ARM64 支持

镜像大小优化：

• 基础镜像：python:3.11-slim
• 清理 apt 缓存
• 使用 --no-cache-dir 安装 pip 包
• .dockerignore 排除不必要文件

3. 部署脚本

scripts/deploy-orbstack.sh - 一键部署脚本

功能：

1. ✅ 检查 OrbStack 环境
2. ✅ 构建 Docker 镜像
3. ✅ 创建 Kubernetes 命名空间
4. ✅ 创建 Secrets
5. ✅ Helm 部署
6. ✅ 验证部署状态
7. ✅ 自动设置端口转发
8. ✅ 显示访问信息

使用方法：

# 完整部署
./scripts/deploy-orbstack.sh

# 跳过构建（使用现有镜像）
./scripts/deploy-orbstack.sh --skip-build

# 指定镜像标签
./scripts/deploy-orbstack.sh --tag v1.0.0

4. Claude Code Skills

新增 Skill：k8s-helper

位置：.claude/skills/k8s-helper/

功能：

• 🔍 集群状态检查
• 📊 资源查看（Pods, Services, Deployments）
• 📜 日志查看（支持 follow）
• 🏥 健康检查
• 📋 资源描述
• 🌐 端口转发
• 🐚 Pod Shell 访问
• 📢 事件查看

使用示例：

# 查看集群状态
python3 .claude/skills/k8s-helper/helper.py --action status

# 查看 Pods
python3 .claude/skills/k8s-helper/helper.py --action pods -n gold-template

# 查看日志
python3 .claude/skills/k8s-helper/helper.py --action logs -r <pod-name> -n gold-template

# 健康检查
python3 .claude/skills/k8s-helper/helper.py --action health -n gold-template

# 端口转发
python3 .claude/skills/k8s-helper/helper.py --action port-forward -r <pod-name> -n gold-template

# 进入 Pod Shell
python3 .claude/skills/k8s-helper/helper.py --action shell -r <pod-name> -n gold-template

5. CI/CD Pipeline

文件： .github/workflows/complete-cicd.yml

Pipeline 阶段：

1. Code Quality & Security 🔒

   • Black 格式检查
   • Flake8 代码检查
   • MyPy 类型检查
   • Bandit 安全扫描
   • Safety 依赖扫描
   • Gitleaks 密钥扫描

2. Testing 🧪

   • pytest 单元测试
   • 代码覆盖率报告
   • Codecov 集成

3. Build 🔨

   • Docker 多架构构建（amd64, arm64）
   • 推送到 GitHub Container Registry
   • 镜像缓存优化

4. Container Security Scan 🛡️

   • Trivy 漏洞扫描
   • SARIF 报告上传到 GitHub Security
   • 严重性过滤（CRITICAL, HIGH）

5. Deploy to Development 🚀

   • 自动部署到开发环境
   • 触发条件：develop 分支

6. Deploy to Production 🎯

   • 手动批准部署
   • 触发条件：main 分支

7. Post-deployment Verification ✅

   • 健康检查
   • 烟雾测试

8. Notify 📢

   • 结果通知

🚀 快速开始

第一次部署

# 1. 确保 OrbStack 正在运行
# 检查集群连接
kubectl cluster-info

# 2. 配置环境变量（可选）
cp .env.example .env
# 编辑 .env 文件

# 3. 一键部署
./scripts/deploy-orbstack.sh

# 4. 等待部署完成，脚本会自动：
#    - 构建 Docker 镜像
#    - 创建 K8s 资源
#    - 设置端口转发
#    - 显示访问信息

# 5. 访问应用
open http://localhost:8000
open http://localhost:8000/docs

验证部署

# 使用 k8s-helper skill
python3 .claude/skills/k8s-helper/helper.py --action health -n gold-template

# 或手动检查
kubectl get pods -n gold-template
kubectl get svc -n gold-template

# 查看日志
kubectl logs -f -n gold-template -l app.kubernetes.io/name=gold-template

# 测试 API
curl http://localhost:8000
curl http://localhost:8000/health

更新部署

# 修改代码后重新部署
./scripts/deploy-orbstack.sh

# 或使用 Helm 更新
helm upgrade gold-template ./deployment/helm/gold-template \
  -n gold-template \
  -f ./deployment/helm/gold-template/values-orbstack.yaml

卸载

# 使用 Helm 卸载
helm uninstall gold-template -n gold-template

# 删除命名空间
kubectl delete namespace gold-template

🔧 配置说明

Helm Values 配置

values-orbstack.yaml 关键配置：

# 副本数（单节点环境）
replicaCount: 1

# 镜像配置
image:
  repository: localhost:5000/gold-template
  pullPolicy: Always
  tag: "latest"

# 节点选择（OrbStack 节点）
nodeSelector:
  kubernetes.io/hostname: orbstack

# 资源限制
resources:
  limits:
    cpu: 1000m
    memory: 1Gi
  requests:
    cpu: 100m
    memory: 128Mi

# 持久化存储
persistence:
  enabled: true
  storageClass: "local-path"
  size: 1Gi

环境变量

必需的环境变量：

• SECRET_KEY - 应用密钥（自动生成）
• GITHUB_TOKEN - GitHub API token（可选）

应用配置：

• APP_ENV - 环境（development/production）
• LOG_LEVEL - 日志级别（DEBUG/INFO/WARNING/ERROR）
• WORKERS - Worker 进程数

📊 监控和调试

使用 k8s-helper Skill

# 完整状态检查
python3 .claude/skills/k8s-helper/helper.py --action status -n gold-template

# 实时日志
python3 .claude/skills/k8s-helper/helper.py --action logs -r <pod-name> -n gold-template --follow

# 查看事件
python3 .claude/skills/k8s-helper/helper.py --action events -n gold-template

# 健康检查
python3 .claude/skills/k8s-helper/helper.py --action health -n gold-template

手动调试

# 查看 Pod 详情
kubectl describe pod -n gold-template -l app.kubernetes.io/name=gold-template

# 进入 Pod
kubectl exec -it -n gold-template <pod-name> -- /bin/bash

# 查看资源使用
kubectl top pods -n gold-template

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

🔒 安全最佳实践

已实施的安全措施

1. 容器安全：

   • ✅ 非 root 用户运行
   • ✅ 只读根文件系统
   • ✅ 删除所有 capabilities
   • ✅ 禁止特权提升

2. 镜像安全：

   • ✅ 最小化基础镜像
   • ✅ 多阶段构建
   • ✅ 定期漏洞扫描（Trivy）

3. 代码安全：

   • ✅ Bandit 静态分析
   • ✅ Safety 依赖检查
   • ✅ Gitleaks 密钥扫描

4. Secrets 管理：

   • ✅ Kubernetes Secrets
   • ✅ 不提交到 Git
   • ✅ 环境变量注入

安全检查清单

• 定期更新依赖
• 定期扫描镜像漏洞
• 审查 Secrets 访问权限
• 启用网络策略（生产环境）
• 配置 RBAC
• 启用审计日志

🎯 下一步

推荐的改进

1. 监控和可观测性：

   • 集成 Prometheus + Grafana
   • 添加 ServiceMonitor
   • 配置告警规则

2. 日志聚合：

   • 集成 ELK/EFK Stack
   • 或使用 Loki

3. 备份和恢复：

   • 配置 Velero
   • 定期备份 PVC

4. 高可用性：

   • 多节点集群
   • 跨区域部署

5. GitOps：

   • 集成 ArgoCD 或 Flux
   • 声明式配置管理

📚 相关文档

• CLAUDE.md - Claude Code 项目指南
• README.md - 项目概览
• QUICKSTART.md - 快速入门
• Helm Chart README - Helm Chart 文档

🆘 故障排查

常见问题

1. Pod 无法启动

# 查看 Pod 状态
kubectl describe pod -n gold-template <pod-name>

# 查看日志
kubectl logs -n gold-template <pod-name>

# 检查镜像是否存在
docker images | grep gold-template

2. 无法访问应用

# 检查 Service
kubectl get svc -n gold-template

# 检查端口转发
ps aux | grep "kubectl port-forward"

# 重新设置端口转发
kubectl port-forward -n gold-template svc/gold-template 8000:80

3. 镜像拉取失败

# 检查镜像仓库
docker images

# 重新构建镜像
docker build -t localhost:5000/gold-template:latest .

4. Helm 部署失败

# 查看 Helm 状态
helm list -n gold-template

# 查看 Helm 历史
helm history gold-template -n gold-template

# 回滚
helm rollback gold-template -n gold-template

💡 提示和技巧

开发工作流

# 1. 修改代码
vim src/...

# 2. 本地测试
./scripts/test.sh

# 3. 重新部署
./scripts/deploy-orbstack.sh

# 4. 查看日志
python3 .claude/skills/k8s-helper/helper.py --action logs -r <pod-name> -n gold-template --follow

# 5. 测试 API
curl http://localhost:8000/health

使用 Claude Code

# 启动 Claude Code
claude

# 在 Claude Code 中：
"使用 k8s-helper skill 检查集群状态"
"查看 gold-template 命名空间的 Pod 日志"
"帮我调试部署失败的问题"

📞 获取帮助

• 📖 查看文档：docs/
• 🐛 报告问题：GitHub Issues
• 💬 讨论：GitHub Discussions
• 🤖 询问 Claude Code

---

实施完成日期： 2024-12-30 环境： Mac Studio + OrbStack 状态： ✅ 生产就绪

Happy Deploying! 🚀