diff --git a/.claude/skills/proxy-deploy/SKILL.md b/.claude/skills/proxy-deploy/SKILL.md index 38184c0..52e8ef9 100644 --- a/.claude/skills/proxy-deploy/SKILL.md +++ b/.claude/skills/proxy-deploy/SKILL.md @@ -1,27 +1,29 @@ --- name: proxy-deploy -description: 部署 Claude API 代理服务到 K8S ECI。当用户要求部署代理服务、创建新的代理实例、查看代理状态、删除代理服务时使用。触发词: deploy, 部署, 代理, proxy, k8s, eci, 服务状态, 删除服务。 +description: 部署 Claude API 代理服务到 K8S ECI。只要用户提到部署、代理服务、K8S、ECI、容器实例、服务状态、删除服务等相关操作就必须使用此技能。触发词包括: deploy, 部署, 代理, proxy, k8s, eci, 服务状态, 删除服务, 启动服务, 容器, pod, ingress。即使用户没有明确说"deploy"，只要意图是管理代理服务，就应该使用此技能。 --- # Claude API 代理服务部署 -用于管理 Claude API 代理服务在 K8S ECI 环境中的部署。 +管理 Claude API 代理服务在阿里云 K8S ECI 环境中的完整生命周期。 -## 可用命令 +## 执行流程 -### 部署代理服务 +当用户要求部署或管理代理服务时，按以下步骤操作： + +### 1. 部署新服务 ```bash pnpm deploy [options] ``` -**参数:** -- `name` - 服务名称（唯一标识） +**必须参数:** +- `name` - 服务名称（唯一标识，如 claude-proxy-1） - `image` - Docker 镜像地址 -**选项:** +**可选参数:** - `--replicas ` - 副本数（默认: 1） -- `--port ` - 容器端口（默认: 3000） +- `--port ` - 容器端口（默认: 80） - `--eip-bandwidth ` - EIP 带宽 Mbps（默认: 5） **示例:** @@ -29,64 +31,74 @@ pnpm deploy [options] # 部署单个代理实例 pnpm deploy claude-proxy-1 registry.cn-beijing.aliyuncs.com/d8dcloud/claude-api-proxy:v0.0.1 -# 部署 3 个副本 -pnpm deploy claude-proxy-1 registry.cn-beijing.aliyuncs.com/d8dcloud/claude-api-proxy:v0.0.1 --replicas 3 - -# 自定义端口 -pnpm deploy claude-proxy-2 registry.cn-beijing.aliyuncs.com/d8dcloud/claude-api-proxy:v0.0.2 --port 80 +# 部署多个副本 +pnpm deploy claude-proxy-1 registry.cn-beijing.aliyuncs.com/d8dcloud/claude-api-proxy:v0.0.2 --replicas 2 ``` -### 删除代理服务 - -```bash -pnpm deploy delete -``` - -### 查询服务状态 +### 2. 查询服务状态 ```bash pnpm deploy status ``` -## 环境配置 +返回服务的 Pod 状态、访问地址等关键信息。 -部署前需要确保 `.env` 文件包含以下配置: +### 3. 删除服务 + +```bash +pnpm deploy delete +``` + +删除指定的代理服务及其关联资源（Deployment、Service、Ingress）。 + +## 环境配置要求 + +部署前必须确保 `.env` 文件包含以下配置，否则部署会失败： ```env -# K8S API 配置 +# K8S API 配置（必须） K8S_API_URL=http://10.0.0.52:23972 K8S_API_TOKEN=your_fixed_token_here -# 域名配置 +# 域名配置（必须） DEV_HOST="*.dev.d8d.fun" DEV_TLS_SECRET_NAME="d8d-proxy-tls" -# 上游 API（会注入到容器） +# 上游 API 地址（会注入到容器环境变量） ANTHROPIC_BASE_URL=https://open.bigmodel.cn/api/anthropic ``` -## 部署特性 +## 部署特性说明 -- **ECI 实例**: 使用阿里云 ECI 弹性容器实例 -- **Spot 实例**: 自动使用抢占式实例降低成本 -- **自动 EIP**: 自动分配公网 IP -- **TLS**: 自动配置 HTTPS 域名访问 -- **健康检查**: 自动配置就绪探针和存活探针 +这些特性会在部署时自动配置，无需手动指定： -## 访问地址格式 +- **ECI 弹性容器** - 使用阿里云 Serverless 容器实例 +- **Spot 抢占式实例** - 自动使用低成本抢占实例（通过注解 `k8s.aliyun.com/eci-spot-instance: "true"`） +- **自动 EIP** - 自动分配公网 IP 用于外部访问 +- **TLS/HTTPS** - 自动配置域名证书，支持 HTTPS 访问 +- **健康检查** - 自动配置就绪探针和存活探针 -部署成功后，服务可通过以下地址访问: +## 访问地址 + +部署成功后，服务访问地址格式： ``` https://-. ``` -例如: `https://claude-proxy-1-80.dev.d8d.fun` +示例: `https://claude-proxy-1-80.dev.d8d.fun` -## 工作流程 +## 故障排查 -1. 确认 `.env` 配置正确 -2. 运行 `pnpm deploy ` 部署服务 -3. 等待 Pod 启动（通常需要 1-2 分钟） -4. 使用 `pnpm deploy status ` 检查状态 -5. 通过返回的 HTTPS 地址访问服务 +如果部署失败或服务不可用： + +1. **检查 Pod 状态**: `pnpm deploy status ` +2. **检查环境变量**: 确认 `.env` 配置正确 +3. **检查镜像**: 确认镜像版本存在且可访问 +4. **检查 K8S 连接**: 确认 K8S_API_URL 和 K8S_API_TOKEN 有效 + +## 典型工作流 + +``` +1. 确认 .env 配置 → 2. 运行 deploy 命令 → 3. 等待 Pod 启动(1-2分钟) → 4. 检查 status → 5. 通过 HTTPS 访问 +``` diff --git a/.claude/skills/release/SKILL.md b/.claude/skills/release/SKILL.md index c884dac..16b77e1 100644 --- a/.claude/skills/release/SKILL.md +++ b/.claude/skills/release/SKILL.md @@ -1,86 +1,109 @@ --- name: release -description: 创建和推送版本标签触发 CI/CD 发布流程。当用户要求发布新版本、创建标签、发布 release、触发构建时使用。触发词: release, 发布, 版本, tag, 标签, v0.0.x, 构建镜像, docker build。 +description: 创建和推送版本标签触发 CI/CD 构建 Docker 镜像。只要用户想要发布新版本、打标签、触发构建、更新镜像就必须使用此技能。触发词: release, 发布, 版本, tag, 标签, v0.0.x, 构建镜像, docker build, 推送镜像, 新版本, 更新版本, 打包发布。即使用户只说"发布一下"或"打个新版本"，也应使用此技能。 --- # 版本发布管理 -用于创建和管理版本标签，触发 Gitea Actions 自动构建 Docker 镜像。 +创建和管理版本标签，通过 Gitea Actions 自动构建并推送 Docker 镜像。 -## 发布新版本 +## 核心命令 ```bash ./scripts/release_tag.sh [version] ``` -### 使用方式 +## 使用方式 -1. **自动递增版本（推荐）** - ```bash - ./scripts/release_tag.sh - ``` - 自动检测最新版本并递增 PATCH 号。 +### 1. 自动递增版本（推荐日常使用） -2. **指定版本号** - ```bash - # 以下格式都支持，会自动添加 release/v 前缀 - ./scripts/release_tag.sh 1.0.0 - ./scripts/release_tag.sh v1.0.0 - ./scripts/release_tag.sh release/v1.0.0 - ``` +```bash +./scripts/release_tag.sh +``` -3. **查看所有标签** - ```bash - ./scripts/release_tag.sh --list - # 或 - ./scripts/release_tag.sh -l - ``` +自动检测最新版本并递增 PATCH 号（如 v0.0.1 → v0.0.2）。 -## 版本命名规则 +### 2. 指定版本号 -- 标签格式: `release/v..` -- 示例: `release/v0.0.1`, `release/v0.0.2`, `release/v1.0.0` -- 从 `release/v0.0.1` 开始 +```bash +# 以下格式都支持，脚本会自动标准化 +./scripts/release_tag.sh 1.0.0 # → release/v1.0.0 +./scripts/release_tag.sh v1.0.0 # → release/v1.0.0 +./scripts/release_tag.sh release/v1.0.0 # → release/v1.0.0 +``` -## 发布流程 +### 3. 查看现有标签 -执行发布脚本后会自动: +```bash +./scripts/release_tag.sh --list +# 或 +./scripts/release_tag.sh -l +``` -1. **检查工作目录** - 提示未提交的更改 +## 版本命名规范 + +- **格式**: `release/v..` +- **示例**: `release/v0.0.1`, `release/v0.0.2`, `release/v1.0.0` +- **递增规则**: + - PATCH: Bug 修复、小改进 + - MINOR: 新功能、向后兼容 + - MAJOR: 重大变更、不兼容更新 + +## 发布流程（执行脚本后自动进行） + +1. **检查工作目录** - 如果有未提交更改会提示 2. **拉取最新代码** - `git pull gitea ` 3. **创建标签** - `git tag release/vX.X.X` 4. **推送标签** - `git push gitea release/vX.X.X` -5. **触发 CI** - Gitea Actions 自动构建 Docker 镜像 +5. **触发 CI** - Gitea Actions 自动开始构建 -## CI/CD 说明 +## CI/CD 自动化 -标签推送后，Gitea Actions 会自动: +标签推送后，Gitea Actions 会自动： 1. 构建多架构 Docker 镜像 (amd64, arm64) 2. 推送到阿里云容器镜像仓库 3. 镜像地址: `registry.cn-beijing.aliyuncs.com/d8dcloud/claude-api-proxy:vX.X.X` -## 注意事项 - -- 发布前确保所有更改已提交 -- 版本号格式必须符合语义化版本规范 -- ECI 容器环境会自动配置 SSH 连接参数 -- 如果推送失败，检查 `gitea` 远程仓库配置 - ## 完整发布工作流 ```bash -# 1. 确保代码已提交 +# 步骤 1: 确保代码已提交并推送 git add . git commit -m "feat: 新功能描述" git push gitea main -# 2. 发布新版本 +# 步骤 2: 发布新版本 ./scripts/release_tag.sh -# 3. 等待 CI 构建完成 -# 访问 Gitea Actions 页面查看构建状态 +# 步骤 3: 等待 CI 构建完成（约 3-5 分钟） +# 可在 Gitea Actions 页面查看进度 -# 4. 部署新版本 +# 步骤 4: 部署新版本镜像 pnpm deploy claude-proxy-1 registry.cn-beijing.aliyuncs.com/d8dcloud/claude-api-proxy:vX.X.X ``` + +## 常见问题 + +### 推送标签失败 + +- 检查 `gitea` 远程仓库配置: `git remote -v` +- 确认有推送权限 +- 检查网络连接 + +### 标签已存在 + +- 使用 `--list` 查看现有标签 +- 选择一个新的版本号 + +### CI 构建失败 + +- 检查 Gitea Actions 日志 +- 确认 Dockerfile 语法正确 +- 验证镜像仓库凭据配置 + +## 注意事项 + +- 发布前务必确保代码已推送到远程 +- 版本号一旦推送不可修改（需删除后重建） +- ECI 环境会自动处理 SSH 相关配置