fec235eade
- 新增 src/k8s-client.ts: K8S 客户端封装 - 新增 src/deploy.ts: 部署/删除/状态查询逻辑 - 新增 scripts/deploy.ts: 命令行部署工具 - 更新 .env.example: 添加 K8S 配置项 - 安装 @kubernetes/client-node@1.3.0 依赖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
168 lines
5.3 KiB
Markdown
168 lines
5.3 KiB
Markdown
---
|
||
title: 'K8S 部署脚本'
|
||
slug: 'k8s-deploy'
|
||
created: '2026-03-20T07:00:00.000Z'
|
||
status: 'ready-for-dev'
|
||
stepsCompleted: [1, 2, 3, 4]
|
||
tech_stack: ['TypeScript', '@kubernetes/client-node', 'Node.js', 'dotenv', 'express']
|
||
files_to_modify:
|
||
- 'package.json'
|
||
- 'scripts/deploy.ts'
|
||
code_patterns:
|
||
- 'K8S 客户端: @kubernetes/client-node SDK 封装'
|
||
- '部署流程: Deployment → Service → Ingress'
|
||
- 'EIP: k8s.aliyun.com/eci-open-enable-eip 自动创建'
|
||
- '抢占式实例: 未启用（可选优化）'
|
||
- '命名空间: d8d-proxy (专用命名空间)'
|
||
- '实例规格: ecs.t5-lc2m1.nano (完整字符串)'
|
||
- 'Ingress 域名: {name}-{port}.{hostSuffix}'
|
||
test_patterns: []
|
||
---
|
||
|
||
# Tech-Spec: K8S 部署脚本
|
||
|
||
**Created:** 2026-03-20T07:00:00.000Z
|
||
|
||
## Overview
|
||
|
||
### Problem Statement
|
||
|
||
Claude API 代理服务已完成，需要添加 K8S 部署脚本来动态创建和管理 Pod 实例。每个 Pod 需要独立的出口 IP (通过 EIP)，以便分散请求绕过官方 API 的 IP 并发限制。
|
||
|
||
### Solution
|
||
|
||
1. 安装 `@kubernetes/client-node` 依赖
|
||
2. 使用已实现的 `src/k8s-client.ts` K8S 客户端封装
|
||
3. 使用已实现的 `src/deploy.ts` 部署模块
|
||
4. 创建 `scripts/deploy.ts` 命令行入口
|
||
|
||
### Scope
|
||
|
||
**In Scope:**
|
||
- 安装 @kubernetes/client-node 依赖
|
||
- 命令行部署工具
|
||
- 部署脚本：创建/删除 Deployment、Service、Ingress
|
||
- 自动 EIP 创建支持
|
||
- 专用命名空间 `d8d-proxy`
|
||
- 健康检查配置
|
||
|
||
**Out of Scope:**
|
||
- API Key 池管理（由 D8D 主项目处理）
|
||
- 复杂的监控和告警
|
||
- HPA 自动扩缩容
|
||
|
||
## Context for Development
|
||
|
||
### Codebase Patterns
|
||
|
||
**已实现的文件：**
|
||
|
||
| 文件 | 状态 | 描述 |
|
||
|------|------|------|
|
||
| `src/k8s-client.ts` | ✅ 已完成 | K8S SDK 封装类 |
|
||
| `src/deploy.ts` | ✅ 已完成 | 部署/删除/状态查询功能 |
|
||
| `.env.example` | ✅ 已完成 | K8S 环境变量配置 |
|
||
| `package.json` | ❌ 缺少依赖 | 需添加 @kubernetes/client-node |
|
||
| `scripts/deploy.ts` | ❌ 未创建 | 命令行入口 |
|
||
|
||
**阿里云 ECI 注解（已实现写法）：**
|
||
- `k8s.aliyun.com/eci-use-specs: "ecs.t5-lc2m1.nano"` - 指定 ECI 规格
|
||
- `k8s.aliyun.com/eci-open-enable-eip: "true"` - 自动创建 EIP
|
||
- `k8s.aliyun.com/eci-eip-bandwidth: "5"` - EIP 带宽 5Mbps
|
||
- `k8s.aliyun.com/eci-eip-internet-charge-type: "PayByBandwidth"` - 按带宽计费
|
||
|
||
### Files to Reference
|
||
|
||
| File | Purpose |
|
||
| ---- | ------- |
|
||
| `src/k8s-client.ts` | K8S SDK 封装（已实现） |
|
||
| `src/deploy.ts` | 部署模块（已实现） |
|
||
|
||
### Technical Decisions
|
||
|
||
- **命名空间**: `d8d-proxy` (专用，避免与 d8d-dev/d8d-prd 冲突)
|
||
- **K8S 客户端**: 使用 @kubernetes/client-node SDK
|
||
- **认证方式**: K8S_API_URL + K8S_API_TOKEN 环境变量
|
||
- **EIP 配置**: 自动创建（通过 ECI annotation）
|
||
- **容器规格**: `ecs.t5-lc2m1.nano` (0.5 CPU, 1G 内存)
|
||
- **Ingress 域名**: `{name}-{port}.{hostSuffix}`
|
||
- **镜像**: registry.cn-beijing.aliyuncs.com/d8dcloud/claude-api-proxy:${VERSION}
|
||
- **健康检查**: /health 端点
|
||
- **Ingress**: 无需 SSO 认证（代理服务）
|
||
|
||
## Implementation Plan
|
||
|
||
### Tasks
|
||
|
||
**Task 1: 安装 K8S 依赖**
|
||
- [ ] 执行 `pnpm add @kubernetes/client-node`
|
||
- [ ] 验证依赖安装成功
|
||
|
||
**Task 2: 创建命令行入口**
|
||
- [ ] File: `scripts/deploy.ts`
|
||
- [ ] Action: 创建命令行工具，支持以下命令：
|
||
- `deploy <name> <image>` - 部署代理服务
|
||
- `delete <name>` - 删除代理服务
|
||
- `status <name>` - 查询服务状态
|
||
- [ ] Notes: 使用 tsx 运行，参考参数：
|
||
- `--replicas` 副本数（默认 1）
|
||
- `--port` 端口（默认 3000）
|
||
- `--eip-bandwidth` EIP 带宽（默认 5）
|
||
|
||
**Task 3: 添加 npm 脚本**
|
||
- [ ] File: `package.json`
|
||
- [ ] Action: 添加部署相关脚本：
|
||
```json
|
||
"deploy": "tsx scripts/deploy.ts"
|
||
```
|
||
|
||
### Acceptance Criteria
|
||
|
||
- [ ] **AC1: 依赖安装成功**
|
||
- Given: 执行 pnpm install
|
||
- When: 安装 @kubernetes/client-node
|
||
- Then: 依赖正确安装，TypeScript 编译无错误
|
||
|
||
- [ ] **AC2: 部署命令可执行**
|
||
- Given: 环境变量 K8S_API_URL 和 K8S_API_TOKEN 已配置
|
||
- When: 执行 `pnpm deploy <name> <image>`
|
||
- Then: 成功创建 Deployment、Service、Ingress，返回访问 URL
|
||
|
||
- [ ] **AC3: EIP 自动创建**
|
||
- Given: 部署时启用 EIP 选项（默认启用）
|
||
- When: Pod 启动
|
||
- Then: 自动创建并绑定 EIP
|
||
|
||
- [ ] **AC4: 删除功能正常**
|
||
- Given: 已部署的代理服务
|
||
- When: 执行 `pnpm deploy delete <name>`
|
||
- Then: 清理所有 K8S 资源（Deployment、Service、Ingress）
|
||
|
||
- [ ] **AC5: 状态查询正常**
|
||
- Given: 已部署的代理服务
|
||
- When: 执行 `pnpm deploy status <name>`
|
||
- Then: 返回服务运行状态和访问 URL
|
||
|
||
## Additional Context
|
||
|
||
### Dependencies
|
||
|
||
**新增依赖：**
|
||
- @kubernetes/client-node - K8S 官方 Node.js SDK
|
||
|
||
### Testing Strategy
|
||
|
||
**手动测试步骤：**
|
||
1. 配置 `.env` 文件中的 K8S 环境变量
|
||
2. 执行 `pnpm deploy claude-proxy-1 registry.cn-beijing.aliyuncs.com/d8dcloud/claude-api-proxy:v0.0.1`
|
||
3. 验证 Deployment、Service、Ingress 创建成功
|
||
4. 访问返回的 HTTPS URL 验证服务可用
|
||
5. 执行删除命令验证资源清理
|
||
|
||
### Notes
|
||
|
||
- 命名空间独立，避免与 d8d-dev/d8d-prd 冲突
|
||
- 代理服务无需 SSO 认证
|
||
- EIP 自动创建简化了 IP 管理
|
||
- 当前未启用抢占式实例，后续可优化成本
|