ljwx-harbor/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

🤖 AI 开发上下文生成（重要）

智能场景化上下文（推荐）⭐

为了提供更精准、更高效的 AI 辅助，项目提供了智能上下文优化器，根据不同使用场景生成针对性的配置信息。

快速使用

cd /Users/brunogao/work/codes/tools/macos

# 根据任务选择场景
./scripts/ai-context-optimizer.sh core      # 核心上下文（4KB，最快）
./scripts/ai-context-optimizer.sh dev       # 开发场景（4KB）
./scripts/ai-context-optimizer.sh deploy    # 部署场景（8KB）
./scripts/ai-context-optimizer.sh debug     # 故障排查（12KB）
./scripts/ai-context-optimizer.sh auto      # 智能推荐

场景选择指南

任务类型	推荐场景	文件大小	Token消耗
编写代码、构建应用	dev	4KB	~2000 ⬇️75%
部署到K8s、镜像管理	deploy	8KB	~3000 ⬇️62%
故障排查、性能诊断	debug	12KB	~4000 ⬇️50%
快速检查、一般咨询	core	4KB	~1000 ⬇️87%
不确定	auto	自动选择	-

对比: 原始全量上下文 32KB, ~8000 tokens

优势

• ✅ 减少 75-87% 的 Token 消耗（降低成本）
• ✅ 提高 2-3x 的响应速度（更快的交互）
• ✅ 增强信息针对性（更精准的建议）
• ✅ 支持安全模式（自动过滤敏感信息）

实际使用示例

# 1. 开发新功能
./scripts/ai-context-optimizer.sh dev

# 2. 在 Claude Code 中
# "请阅读 contexts/ai-context-dev.md"
# "帮我创建一个 FastAPI 应用"

# 3. 部署应用（切换场景）
./scripts/ai-context-optimizer.sh deploy

# 4. 在 Claude Code 中
# "请阅读 contexts/ai-context-deploy.md"
# "帮我部署到 K8s"

高级功能

# 安全模式（过滤敏感信息）
./scripts/ai-context-optimizer.sh dev --secure

# 自定义输出位置
./scripts/ai-context-optimizer.sh deploy -o ~/my-context.md

# 查看帮助
./scripts/ai-context-optimizer.sh --help

快捷命令（可选）

# 添加到 ~/.zshrc
alias ai-dev='cd ~/work/codes/tools/macos && ./scripts/ai-context-optimizer.sh dev'
alias ai-deploy='cd ~/work/codes/tools/macos && ./scripts/ai-context-optimizer.sh deploy'
alias ai-debug='cd ~/work/codes/tools/macos && ./scripts/ai-context-optimizer.sh debug'

# 使用
ai-dev    # 快速生成开发上下文

完整上下文生成（备选）

如需生成包含所有信息的完整上下文：

./scripts/generate-ai-context.sh
# 输出: AI-CONTEXT.md (32KB, 646行)

注意: 完整上下文会消耗更多 tokens，建议优先使用场景化上下文。

详细文档

• 优化分析: AI-CONTEXT-OPTIMIZATION.md - 详细的优化效果分析
• 使用指南: AI-CONTEXT-GUIDE.md - 完整的使用说明

---

🚨 镜像拉取问题自动修复（重要）

识别条件

当遇到以下情况时，必须立即执行镜像缓存：

• Kubernetes Pod 状态为 ImagePullBackOff 或 ErrImagePull
• kubectl apply/create 返回镜像拉取错误
• docker pull 命令超时或失败（context deadline exceeded）

⚡ 自动修复命令（首选）

cd /Users/brunogao/work/codes/tools/macos/k8s
./cache-image.sh --update-deployment <namespace>/<deployment-name>

示例：

# 修复 kubernetes-dashboard
./cache-image.sh --update-deployment kubernetes-dashboard/kubernetes-dashboard

# 修复自定义应用
./cache-image.sh --update-deployment default/myapp

效果：

• ✅ 自动提取所有镜像
• ✅ 自动缓存到本地 Harbor
• ✅ 自动更新 Deployment
• ✅ 自动触发 Pod 重启

手动缓存镜像

# 单个镜像
./cache-image.sh nginx:alpine

# 多个镜像
./cache-image.sh nginx:alpine redis:7 mysql:8.0

# 从文件批量缓存
./cache-image.sh -f images.txt

工作原理

输入镜像: nginx:alpine
    ↓
从 EU Harbor 拉取（harbor.eu.lingjingwanxiang.cn）
    ↓
推送到本地 Harbor（harbor.omniverseai.net:8080）
    ↓
更新 K8s 使用本地镜像
    ↓
✅ 完成

重要提示

• ⚠️ 遇到 ImagePull 问题必须立即执行，不要等待
• ⚠️ 优先使用 --update-deployment 自动修复
• ✅ 所有镜像会缓存到 harbor.omniverseai.net:8080/library/
• ✅ 支持 Docker Hub, GCR, Quay 等所有公共仓库
• ✅ 脚本位置：/Users/brunogao/work/codes/tools/macos/k8s/cache-image.sh

快速参考

场景	命令
Deployment 失败	./cache-image.sh --update-deployment ns/deploy
单个镜像	./cache-image.sh image:tag
批量镜像	./cache-image.sh -f images.txt
查看帮助	./cache-image.sh --help

---

Project Overview

This is a sophisticated macOS development and operations toolchain that provides a complete cloud-native DevOps infrastructure on macOS systems. It integrates enterprise-grade tools for version control, CI/CD, containerization, and AI-powered development, creating a self-contained production-ready environment.

Core Architecture

The system consists of three main layers:

1. DevOps Services Layer: Gitea (Git hosting + Actions CI/CD), Harbor (container registry), and optional GitLab
2. Container Runtime Layer: OrbStack/Docker with Kubernetes orchestration
3. AI Development Layer: Claude-Qwen integration with Ollama for AI-assisted development

Service Ports and Access

• Gitea: HTTP 33000, SSH 32222 (http://192.168.1.83:33000)
• Harbor: HTTP 8080, HTTPS 8443 (http://192.168.1.83:8080, admin/admin123)
• GitLab: HTTP 8890, SSH 8929 (http://192.168.1.83:8890, admin/admin123)
• Ollama: API 11434 (http://localhost:11434)

Essential Commands

Primary Deployment

./deploy.sh                    # One-click deployment of entire infrastructure
./init-ops.sh                 # Environment initialization

Service Management

Gitea Operations:

cd ~/ops/gitea
./gitea-data-protection.sh setup    # Initialize Gitea service
./gitea-data-protection.sh start    # Start Gitea
./gitea-data-protection.sh health   # Health check
./gitea-backup.sh                  # Manual backup
./gitea-restore.sh                 # Restore from backup

Harbor Operations:

cd ~/ops/harbor
./harbor-data-protection.sh start   # Start Harbor registry
./harbor-k8s-images.sh sync        # Sync Kubernetes images to registry
./harbor-k8s-images.sh list        # List available images
./harbor-k8s-images.sh cleanup 10  # Cleanup images older than 10 days

GitLab Operations:

cd ~/ops/gitlab
./gitlab-data-protection.sh start  # Start GitLab service

AI Development

claude-qwen chat                    # Interactive AI chat mode
claude-qwen project                 # Project mode (Claude-style development)
claude-qwen status                  # Check AI service status

Kubernetes Operations

kubectl get pods                    # Check cluster status
tkn pipelinerun list               # List Tekton pipelines
argocd application list             # List ArgoCD applications

Architecture Patterns

Container Orchestration

• Docker Compose: Service orchestration with volume persistence
• Network Isolation: Core network for inter-service communication
• Multi-service Architecture: Each service in isolated containers

Backup and Recovery

• Dual Strategy: Cron + Launchd for reliability
• Automated Rotation: 30-day retention with timestamp-based naming
• Safety Backups: Automatic backups before restore operations

Development Workflow

1. Code Creation: Use Claude-Qwen project mode for AI-assisted development
2. Version Control: Push to Gitea repositories ([email protected].1.83:32222)
3. CI/CD: Gitea Actions trigger quality gates and automated testing
4. Build and Deploy: Tekton pipelines build containers and deploy to Kubernetes
5. Monitor: Prometheus + Grafana for application observability

Directory Structure

~/ops/                                    # Runtime directory
├── logs/                                 # Unified service logs
├── backups/                              # Backup storage by service
├── data/                                 # Runtime data (repositories, registry)
├── brew/                                 # Homebrew maintenance scripts
├── gitea/                                # Gitea management and data
├── harbor/                               # Harbor registry management
└── gitlab/                               # GitLab management

Configuration Requirements

Hardware Prerequisites

• MacBook Pro 14-inch (2023): Apple M3 Pro recommended
• 18GB+ unified memory: For concurrent service execution
• 512GB+ SSD: For containers and database storage
• macOS 15.0+ Sequoia: Latest macOS version

Software Dependencies

• Docker Desktop or OrbStack: Container runtime
• Homebrew: Package management
• kubectl: Kubernetes cluster management
• Ollama: Local AI model service

Network Configuration

• Primary IP: 192.168.1.83 (configurable in environment files)
• Service URLs: All services accessible via configured ports
• Internet Access: Required for initial container image pulls

Development Standards

Quality Gates

• Type Coverage: ≥90%
• Test Coverage: ≥80%
• Code Quality: ≥B level
• Security: Zero high-severity OWASP vulnerabilities
• Performance: API response ≤3s, CPU usage ≤70%

GitOps and CI/CD

• Git Repository: Gitea at [email protected].1.83:32222
• CI/CD Platform: Gitea Actions for workflow automation
• Container Registry: Harbor at http://192.168.1.83:8080
• Deployment: ArgoCD for GitOps-based deployments

Security Practices

• Network Segmentation: Internal network isolation
• Authentication: Local authentication for all services
• Data Protection: Automated encrypted backups
• SSL/TLS: HTTPS encryption for web interfaces

Integration Notes

AI-Powered Development

The system includes Claude-Qwen integration for AI-assisted development. Use claude-qwen project for Claude-style project management with AI assistance.

Multi-Environment Support

The infrastructure supports development, staging, and production environments through Kubernetes namespaces and Harbor projects.

Monitoring and Observability

Prometheus and Grafana provide comprehensive monitoring of all services, with automated alerting for system health and performance metrics.