first commit

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

@@ -0,0 +1,387 @@
+# 网络与代理
+
+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"
+  }
+}
+```