MJ-IT/claude-code-mirror

Fork 0

Files

H 538eced414 first commit

2026-04-03 13:01:19 +08:00

7.5 KiB

Raw Blame History

网络与代理

Claude Code 的网络系统处理代理配置、远程会话管理和服务器模式。

目录结构

src/
├── upstreamproxy/     # 上游代理配置
│   ├── upstreamproxy.ts    # 代理核心
│   └── relay.ts           # 代理中继
├── remote/           # 远程会话
│   ├── RemoteSessionManager.ts  # 会话管理
│   ├── SessionsWebSocket.ts    # WebSocket 会话
│   ├── remotePermissionBridge.ts  # 权限桥接
│   └── sdkMessageAdapter.ts    # SDK 消息适配
└── server/           # 服务器模式
    ├── createDirectConnectSession.ts  # 直连会话
    ├── directConnectManager.ts       # 直连管理
    └── types.ts                     # 类型定义

1. 上游代理 (upstreamproxy/)

1.1 代理核心 (upstreamproxy.ts)

文件: src/upstreamproxy/upstreamproxy.ts (~10KB)

管理 Claude Code 与上游服务之间的 HTTP/SOCKS 代理连接。

核心功能:

代理协议支持 (HTTP, HTTPS, SOCKS4, SOCKS5)
代理认证 (Basic,NTLM, Negotiate)
连接池管理
自动重试和故障转移

主要类: UpstreamProxy

class UpstreamProxy {
  // 代理配置
  readonly type: 'http' | 'https' | 'socks4' | 'socks5'
  readonly host: string
  readonly port: number
  readonly auth?: ProxyAuth

  // 连接池
  private pool: ConnectionPool

  // 方法
  async getConnection(url: URL): Promise<Connection>
  async request(req: Request): Promise<Response>
  close(): void
}

代理认证:

interface ProxyAuth {
  type: 'basic' | 'ntlm' | 'negotiate'
  username: string
  password?: string
  domain?: string  // NTLM 专用
}

1.2 代理中继 (relay.ts)

文件: src/upstreamproxy/relay.ts (~15KB)

在代理链中转发请求，支持多层代理。

功能:

代理链构建
请求/响应转发
头部处理
连接复用

class ProxyRelay {
  // 上游代理链
  private relays: UpstreamProxy[]

  // 添加跳点
  addHop(proxy: UpstreamProxy): void

  // 转发请求
  async relayRequest(req: Request): Promise<Response>
}

2. 远程会话 (remote/)

2.1 会话管理器 (RemoteSessionManager.ts)

文件: src/remote/RemoteSessionManager.ts (~9KB)

管理远程 Claude Code 实例的会话。

核心功能:

会话生命周期管理
连接状态监控
消息路由
断开重连

主要接口:

interface RemoteSession {
  id: string
  remoteId: string
  status: 'connecting' | 'connected' | 'disconnected'
  createdAt: number
  lastActivity: number
}

class RemoteSessionManager {
  // 创建会话
  async createSession(config: RemoteConfig): Promise<RemoteSession>

  // 获取会话
  getSession(id: string): RemoteSession | null

  // 列出所有会话
  listSessions(): RemoteSession[]

  // 终止会话
  async terminateSession(id: string): Promise<void>

  // 事件
  onSessionCreated: Event<RemoteSession>
  onSessionClosed: Event<string>
  onSessionError: Event<{ id: string; error: Error }>
}

2.2 WebSocket 会话 (SessionsWebSocket.ts)

文件: src/remote/SessionsWebSocket.ts (~12.5KB)

通过 WebSocket 管理远程会话的实时通信。

功能:

WebSocket 连接建立
心跳检测
消息序列化/反序列化
重连逻辑

class SessionsWebSocket {
  // 连接 URL
  readonly url: string

  // WebSocket 实例
  private ws: WebSocket

  // 状态
  get status(): 'connecting' | 'open' | 'closing' | 'closed'

  // 发送消息
  send(message: SessionMessage): void

  // 接收消息
  onMessage: (message: SessionMessage) => void

  // 重连
  async reconnect(): Promise<void>
}

2.3 权限桥接 (remotePermissionBridge.ts)

文件: src/remote/remotePermissionBridge.ts (~2.4KB)

在远程会话中桥接权限检查。

// 本地权限检查
const localCheck = await checkPermission(tool, args)

// 远程权限请求
const remoteGrant = await remoteSession.requestPermission({
  tool,
  args,
  reason: 'Remote session requested'
})

// 合并结果
return localCheck || remoteGrant

2.4 SDK 消息适配器 (sdkMessageAdapter.ts)

文件: src/remote/sdkMessageAdapter.ts (~9KB)

适配 Claude SDK 消息格式与内部消息格式。

// SDK 消息 -> 内部消息
function adaptFromSDK(sdkMessage: SDKMessage): InternalMessage

// 内部消息 -> SDK 消息
function adaptToSDK(internalMessage: InternalMessage): SDKMessage

// 工具结果适配
function adaptToolResult(result: ToolResult): ToolResultBlockParam

3. 服务器模式 (server/)

3.1 直连会话 (createDirectConnectSession.ts)

文件: src/server/createDirectConnectSession.ts (~2.2KB)

创建直接的点对点连接会话。

interface DirectConnectConfig {
  remoteId: string
  authToken: string
  endpoint: URL
}

async function createDirectConnectSession(
  config: DirectConnectConfig
): Promise<DirectSession> {
  // 1. 验证配置
  validateConfig(config)

  // 2. 建立连接
  const connection = await establishConnection(config)

  // 3. 创建会话
  return new DirectSession(connection)
}

3.2 直连管理器 (directConnectManager.ts)

文件: src/server/directConnectManager.ts (~6KB)

管理所有直连会话。

功能:

会话注册/注销
连接状态跟踪
资源清理
并发控制

class DirectConnectManager {
  // 注册新会话
  register(session: DirectSession): void

  // 注销会话
  unregister(sessionId: string): void

  // 获取活跃会话
  getActiveSessions(): DirectSession[]

  // 广播消息
  broadcast(message: Message): void

  // 清理闲置会话
  cleanupIdleSessions(): void
}

3.3 类型定义 (types.ts)

文件: src/server/types.ts

// 服务器模式配置
interface ServerConfig {
  host: string
  port: number
  tls: boolean
  cert?: string
  key?: string
}

// 直连配置
interface DirectConnectConfig {
  remoteId: string
  authToken: string
  endpoint: string
}

// 会话消息
interface SessionMessage {
  type: 'query' | 'result' | 'error' | 'heartbeat'
  sessionId: string
  payload: unknown
  timestamp: number
}

4. 连接流程

4.1 远程会话建立

Client                          Server
  |                               |
  |--- WebSocket Connect --------->|
  |                               |
  |<-- Handshake Challenge -------|
  |                               |
  |--- Handshake Response ------->|
  |                               |
  |<-- Session Created ----------|
  |                               |
  |<====== Session Active =======>|
  |                               |
  |<-- Session Terminated --------|

4.2 代理请求流程

Claude Code
    |
    v
UpstreamProxy
    |
    +---> HTTP Proxy
    |
    +---> SOCKS5 Proxy
    |
    v
Anthropic API

5. 安全考虑

5.1 TLS/SSL

服务器模式支持 TLS 终止
证书验证可选
支持自签名证书 (开发模式)

5.2 认证

Token-based 认证
定期心跳检测
会话超时控制

5.3 网络隔离

敏感数据加密传输
代理链逐跳认证
审计日志记录

6. 配置示例

6.1 代理配置 (settings.json)

{
  "proxy": {
    "type": "socks5",
    "host": "proxy.example.com",
    "port": 1080,
    "auth": {
      "type": "basic",
      "username": "user",
      "password": "pass"
    }
  }
}

6.2 服务器模式配置

{
  "server": {
    "enabled": true,
    "host": "0.0.0.0",
    "port": 8080,
    "tls": true,
    "cert": "/path/to/cert.pem",
    "key": "/path/to/key.pem"
  }
}

7.5 KiB Raw Blame History