claude-code-mirror/claude-code-中文Wiki/14-网络与代理.md

# 网络与代理

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`

```typescript
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
}
```

**代理认证**:
```typescript
interface ProxyAuth {
  type: 'basic' | 'ntlm' | 'negotiate'
  username: string
  password?: string
  domain?: string  // NTLM 专用
}
```

### 1.2 代理中继 (relay.ts)

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

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

**功能**:
- 代理链构建
- 请求/响应转发
- 头部处理
- 连接复用

```typescript
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 实例的会话。

**核心功能**:
- 会话生命周期管理
- 连接状态监控
- 消息路由
- 断开重连

**主要接口**:

```typescript
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 连接建立
- 心跳检测
- 消息序列化/反序列化
- 重连逻辑

```typescript
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)

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

```typescript
// 本地权限检查
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 消息格式与内部消息格式。

```typescript
// 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)

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

```typescript
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)

管理所有直连会话。

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

```typescript
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`

```typescript
// 服务器模式配置
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)

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

### 6.2 服务器模式配置

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