自学教程

Claude Agent SDK 部署方案

Claude Code 教程

一、部署方案总览

Claude Agent SDK 区别于普通接口服务，存在网络调用、长会话、工具权限、Token 计费、子代理并发特性，部署核心目标：

  1. 环境隔离：开发/测试/生产完全隔离，配置、密钥、配额互不干扰
  2. 安全可控：容器沙箱、最小权限、禁止高危操作、密钥不落地
  3. 稳定可用：限流、重试、熔断、会话持久化、异常降级
  4. 成本可控：配额管控、Token 监控、并发限制、无效任务拦截
  5. 可运维：日志、监控、告警、链路追踪、版本可回滚

部署分级（由轻到重）：

  • 本地开发部署：单机调试、快速验证功能
  • 测试环境部署：集成测试、压测、功能验收
  • 生产容器部署：Docker 单容器、稳定上线
  • 生产集群部署：K8s 高可用、多租户 SaaS、弹性扩容

二、基础环境规范（全环境通用）

1. 运行依赖

  • Python 栈：Python 3.10+、anthropic、tenacity、jinja2、asyncio
  • TS 栈：Node.js 18+、@anthropic-ai/sdk、p-retry、handlebars
  • 基础服务：Redis（限流/缓存/配额）、MySQL（会话/租户/模板存储）

2. 强制环境变量（生产必填）

所有密钥、模型配置、安全开关全部通过环境变量注入，禁止硬编码、禁止配置文件明文存储。

# 核心鉴权
ANTHROPIC_API_KEY=xxx
CLAUDE_CODE_BASE_URL=xxx
CLAUDE_CODE_MODEL=claude-3-5-sonnet-latest安全开关
CLAUDE_CODE_NO_MEMORY=true
CLAUDE_CODE_NO_MCP=true
CLAUDE_CODE_DISABLE_AUTO_MEMORY=1
超时与日志
CLAUDE_CODE_LOG_LEVEL=warn
SDK_REQUEST_TIMEOUT=20
并发限流
MAX_PARALLEL_SUBAGENT=3
TENANT_MAX_RPM=10

3. 目录与权限规范

  • 工作目录独立：/opt/claude-agent/workspace
  • 租户隔离目录：workspace/{tenant_id}/
  • 进程运行普通用户，禁止 root 启动
  • 禁止目录遍历、禁止跨租户文件访问

三、分级部署落地流程

1. 本地开发部署（调试专用）

适用：功能开发、工具调试、子代理、流式响应、提示词模板测试

  1. 本地安装依赖，配置 .env 环境变量
  2. 本地 SQLite/临时 JSON 存储会话，无需完整数据库
  3. 关闭限流、熔断，开启 debug 日志
  4. 禁用自动记忆、禁用 MCP，避免本地配置污染会话

开发环境核心开关：CLAUDE_CODE_NO_MEMORY=true

2. 测试环境部署（集成验收）

完全复刻生产配置，用于压测、异常测试、安全测试、版本验证

  • 使用独立测试 API Key、独立数据库、独立 Redis
  • 开启完整错误重试、限流、熔断机制
  • 开启全量日志，记录 Token 消耗、工具调用、异常堆栈
  • 执行安全测试：提示注入、路径穿越、越权访问、DoS 测试

3. 生产单容器部署（中小型项目首选）

采用 Docker 容器沙箱部署，实现进程隔离、资源限制、环境统一，是最通用的生产部署方案。

Dockerfile 标准模板

# Node.js 版本
FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm install --production
COPY . .安全权限限制
RUN addgroup -S appgroup && adduser -S appuser -G appgroup
USER appuser
环境变量默认安全配置
ENV CLAUDE_CODE_NO_MEMORY=true
ENV CLAUDE_CODE_NO_MCP=true
ENV CLAUDE_CODE_LOG_LEVEL=warn
ENV MAX_PARALLEL_SUBAGENT=3
EXPOSE 3000
CMD ["node", "index.js"]

Python 版本可替换基础镜像为 python:3.11-slim，逻辑一致。

Docker Compose 一键部署

version: "3.8"
services:
  claude-agent:
    build: .
    ports:
      - "3000:3000"
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - CLAUDE_CODE_MODEL=claude-3-5-sonnet-latest
      - SDK_REQUEST_TIMEOUT=20
    depends_on:
      - redis
      - mysql
    restart: always
    deploy:
      resources:
        limits:
          cpus: "1.0"
          memory: 1G  redis:
    image: redis:alpine
    ports:
      - "6379:6379"
  mysql:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD=${DB_PASSWORD}
      MYSQL_DATABASE=claude_agent
    volumes:
      - mysql-data:/var/lib/mysql
volumes:
  mysql-data:

4. K8s 集群高可用部署（多租户 SaaS 必备）

适配大规模、多用户、高并发场景，支持弹性扩容、故障自愈、灰度发布。

核心配置要点

  • 资源限制：单 Pod CPU/内存封顶，防止单个 Agent 耗尽节点资源
  • 弹性扩缩容：依据 QPS、内存使用率自动扩缩 Pod
  • 会话适配：无状态部署，会话数据全部下沉 MySQL/Redis
  • 租户隔离：K8s 层面资源配额 + 业务 tenant_id 双层隔离
  • 健康检查：接口存活探测、任务卡死自动重启

生产禁止配置

  • 禁止开启本地记忆、禁止自动 MCP 加载
  • 禁止容器内持久化文件，所有临时文件随容器销毁
  • 禁止特权容器、禁止挂载系统目录

四、CI/CD 自动化部署（GitHub Actions）

对接代码提交自动构建、镜像推送、测试、部署，全程无人工干预。

核心流水线逻辑

  1. 代码提交触发：Lint 代码、格式校验
  2. 自动运行单元测试、Agent 能力自测
  3. 构建 Docker 镜像，打版本标签
  4. 推送镜像至镜像仓库
  5. 测试环境自动部署，生产环境手动确认发布

流水线强制参数：--no-memory --no-mcp，杜绝 CI 环境残留配置。

五、生产安全与资源隔离规范

1. 沙箱隔离（官方推荐）

生产环境必须使用容器沙箱运行 SDK，实现：

  • 进程独立隔离，Agent 异常不影响宿主服务
  • 临时文件系统，任务结束自动清理
  • 网络白名单，禁止访问内网、元数据地址
  • 资源配额限制，防止 Token 雪崩、资源耗尽

2. 密钥与配置安全

  • API Key、数据库密钥全部通过环境变量/密钥管理服务注入
  • 租户自定义密钥数据库 AES 加密存储，内存用完销毁
  • 禁止日志打印密钥、禁止环境变量明文输出

3. 并发与配额管控

  • 全局最大并发 + 租户独立 RPM 双层限流
  • 月度 Token 配额封顶，超量直接拦截请求
  • 子代理最大并发限制，避免 429 限流雪崩

六、可观测与运维配置

1. 日志规范

统一日志字段：request_id、tenant_id、session_id、token消耗、工具调用次数、耗时、错误类型

生产日志级别固定warn/error，关闭冗余 debug 日志。

2. 监控告警指标

  • 接口 QPS、响应延迟、错误率（4xx/5xx/429）
  • Token 消耗趋势、租户用量排行
  • 子代理并发数、工具调用失败率
  • 异常告警：突增流量、超额用量、频繁限流、密钥异常

3. 故障自愈

  • 接口超时、服务异常自动重试（指数退避）
  • 短时间大量失败自动熔断，开启降级
  • 卡死任务自动终止，释放资源
  • Pod 异常自动重启、重新调度

七、部署环境差异化清单

配置项开发环境测试环境生产环境
日志级别debuginfowarn
记忆功能关闭关闭关闭
MCP 服务可选开启关闭关闭
限流熔断关闭开启全开
资源限制无基础限制严格限制
密钥存储本地.env环境变量密钥服务+加密

八、常见部署坑与避坑指南

  1. 生产开启记忆/MCP：导致会话污染、权限泄露、配置混乱
  2. 无资源限制：突发大量子代理并发，触发 API 限流、账单暴增
  3. 密钥明文存储：极易泄露，造成巨额扣费风险
  4. 跨租户文件/会话未隔离：产生越权安全漏洞
  5. 未配置超时与重试：长连接卡死、服务堆积请求雪崩
  6. 开发配置直接上线：debug 日志泄露敏感信息、权限过大

九、部署最终验收标准

上线前必须全部通过：

  • ✅ 无硬编码密钥、无明文配置
  • ✅ 记忆、自动 MCP 全部关闭
  • ✅ 容器资源限制、网络隔离生效
  • ✅ 限流、重试、熔断、超时机制正常
  • ✅ 多租户数据、文件、配额完全隔离
  • ✅ 日志、监控、告警完整落地
  • ✅ 安全测试无注入、越权、路径穿越漏洞

小结

Claude Agent SDK 部署核心：环境隔离 + 容器沙箱 + 最小权限 + 配额管控 + 可观测运维。开发环境侧重调试便捷，测试环境复刻生产，生产环境严格安全加固、资源限流、故障自愈。多租户 SaaS 场景优先 K8s 集群部署，中小项目使用 Docker 容器即可稳定落地。

标签：

0 条笔记