From 0590ed2c9516676f6eeb59771c6d90914f2d0211 Mon Sep 17 00:00:00 2001
From: liuxiaopai-ai <73659136+liuxiaopai-ai@users.noreply.github.com>
Date: Thu, 5 Mar 2026 23:52:25 +0800
Subject: [PATCH] docs(csharp): add Kubernetes proxy troubleshooting for
 RunAsync

---
 sdks/sandbox/csharp/README.md    | 22 ++++++++++++++++++++++
 sdks/sandbox/csharp/README_zh.md | 22 ++++++++++++++++++++++
 2 files changed, 44 insertions(+)

diff --git a/sdks/sandbox/csharp/README.md b/sdks/sandbox/csharp/README.md
index 6c52c1dc..7afdbebe 100644
--- a/sdks/sandbox/csharp/README.md
+++ b/sdks/sandbox/csharp/README.md
@@ -362,6 +362,28 @@ catch (SandboxException ex)
 }
 ```
 
+## Troubleshooting (Kubernetes)
+
+### `RunAsync` fails with connection timeout/refused to Pod IP
+
+If your OpenSandbox server runs in Kubernetes, your local client may not be able to
+directly access sandbox Pod IPs (for example `172.x.x.x:44772`). In this case,
+`sandbox.Commands.RunAsync(...)` can fail with socket timeout/refused errors.
+
+Use server-side proxy mode in the SDK connection config:
+
+```csharp
+var config = new ConnectionConfig(new ConnectionConfigOptions
+{
+    Domain = "your-opensandbox-server.example.com",
+    ApiKey = "your-api-key",
+    UseServerProxy = true,
+});
+```
+
+With `UseServerProxy = true`, the SDK sends execd/endpoint traffic through
+the OpenSandbox server proxy path, avoiding direct client -> Pod IP access.
+
 ## Supported Frameworks
 
 - .NET Standard 2.0 (for maximum compatibility with .NET Framework 4.6.1+, .NET Core 2.0+, Mono, Xamarin, etc.)
diff --git a/sdks/sandbox/csharp/README_zh.md b/sdks/sandbox/csharp/README_zh.md
index d6fd82d6..d61bd565 100644
--- a/sdks/sandbox/csharp/README_zh.md
+++ b/sdks/sandbox/csharp/README_zh.md
@@ -314,6 +314,28 @@ await using var sandbox = await Sandbox.CreateAsync(options);
 // 离开作用域时自动释放
 ```
 
+## 故障排查（Kubernetes）
+
+### `RunAsync` 连接 Pod IP 超时/被拒绝
+
+如果 OpenSandbox Server 部署在 Kubernetes 集群中，本地客户端通常无法直接访问
+沙箱 Pod IP（例如 `172.x.x.x:44772`）。此时调用 `sandbox.Commands.RunAsync(...)`
+可能出现 socket 超时或连接被拒绝。
+
+建议在 SDK 连接配置中开启服务端代理：
+
+```csharp
+var config = new ConnectionConfig(new ConnectionConfigOptions
+{
+    Domain = "your-opensandbox-server.example.com",
+    ApiKey = "your-api-key",
+    UseServerProxy = true,
+});
+```
+
+启用 `UseServerProxy = true` 后，SDK 会通过 OpenSandbox Server 的代理路径转发
+execd/endpoint 请求，避免客户端直连 Pod IP。
+
 ## 支持的框架
 
 - .NET Standard 2.0（最大兼容性，支持 .NET Framework 4.6.1+、.NET Core 2.0+、Mono、Xamarin 等）