{"meta":{"title":"为后端服务设置 Copilot SDK","intro":"在服务器端应用程序中运行 GitHub Copilot SDK ，例如 API、Web 后端、微服务和后台辅助角色。","product":"GitHub Copilot","breadcrumbs":[{"href":"/zh/copilot","title":"GitHub Copilot"},{"href":"/zh/copilot/how-tos","title":"操作方法"},{"href":"/zh/copilot/how-tos/copilot-sdk","title":"Copilot SDK"},{"href":"/zh/copilot/how-tos/copilot-sdk/set-up-copilot-sdk","title":"设置 Copilot SDK"},{"href":"/zh/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/backend-services","title":"后端服务"}],"documentType":"article"},"body":"# 为后端服务设置 Copilot SDK\n\n在服务器端应用程序中运行 GitHub Copilot SDK ，例如 API、Web 后端、微服务和后台辅助角色。\n\n> \\[!NOTE]\n> Copilot SDK 当前处于 技术预览版. 功能和可用性可能会发生更改。\n\nCLI 作为一个无头服务器运行，你的后端代码通过网络连接到它。\n\n**最适合：** Web 应用后端、API 服务、内部工具、CI/CD 集成、任何服务器端工作负载。\n\n## 工作原理\n\n与生成 CLI 子进程的 SDK 相反，可以在 **无外设服务器模式下**独立运行 CLI。 后端通过 TCP 使用 `cliUrl` 选项连接到它。  有关无外设服务器体系结构的详细关系图及其与默认自动管理的 CLI 的比较方式，请参阅 `github/copilot-sdk`[存储库](https://github.com/github/copilot-sdk/blob/main/docs/setup/backend-services.md#how-it-works)。\n\n主要特征：\n\n* CLI 作为持久性服务器进程运行，而不是根据请求生成。\n* SDK 通过 TCP 进行连接 — CLI 和应用可以在不同的容器中运行。\n* 多个 SDK 客户端可以共享一个 CLI 服务器。\n* 适用于任何身份验证方法（GitHub 令牌、环境变量、BYOK）。\n\n## 步骤 1：在无头模式下启动 CLI\n\n在后台服务器模式下运行 CLI。\n\n```shell\n# Start with a specific port\ncopilot --headless --port 4321\n\n# Or let it pick a random port (prints the URL)\ncopilot --headless\n# Output: Listening on http://localhost:52431\n```\n\n对于生产，请将其作为系统服务或在容器中运行：\n\n```shell\n# Docker\ndocker run -d --name copilot-cli \\\n    -p 4321:4321 \\\n    -e COPILOT_GITHUB_TOKEN=\"$TOKEN\" \\\n    ghcr.io/github/copilot-cli:latest \\\n    --headless --port 4321\n```\n\n```shell\n# systemd\n[Service]\nExecStart=/usr/local/bin/copilot --headless --port 4321\nEnvironment=COPILOT_GITHUB_TOKEN=YOUR-GITHUB-TOKEN\nRestart=always\n```\n\n## 步骤 2：连接 SDK\n\n### Node.js/TypeScript\n\n```typescript\nimport { CopilotClient } from \"@github/copilot-sdk\";\n\nconst client = new CopilotClient({\n    cliUrl: \"localhost:4321\",\n});\n\nconst session = await client.createSession({\n    sessionId: `user-${userId}-${Date.now()}`,\n    model: \"gpt-4.1\",\n});\n\nconst response = await session.sendAndWait({ prompt: req.body.message });\nres.json({ content: response?.data.content });\n```\n\n### Python\n\n```python\nfrom copilot import CopilotClient\n\nclient = CopilotClient({\n    \"cli_url\": \"localhost:4321\",\n})\nawait client.start()\n\nsession = await client.create_session({\n    \"session_id\": f\"user-{user_id}-{int(time.time())}\",\n    \"model\": \"gpt-4.1\",\n})\n\nresponse = await session.send_and_wait({\"prompt\": message})\n```\n\n### Go\n\n```golang\nclient := copilot.NewClient(&copilot.ClientOptions{\n    CLIUrl: \"localhost:4321\",\n})\nclient.Start(ctx)\ndefer client.Stop()\n\nsession, _ := client.CreateSession(ctx, &copilot.SessionConfig{\n    SessionID: fmt.Sprintf(\"user-%s-%d\", userID, time.Now().Unix()),\n    Model:     \"gpt-4.1\",\n})\n\nresponse, _ := session.SendAndWait(ctx, copilot.MessageOptions{Prompt: message})\n```\n\n### .NET\n\n```csharp\nvar client = new CopilotClient(new CopilotClientOptions\n{\n    CliUrl = \"localhost:4321\",\n    UseStdio = false,\n});\n\nawait using var session = await client.CreateSessionAsync(new SessionConfig\n{\n    SessionId = $\"user-{userId}-{DateTimeOffset.UtcNow.ToUnixTimeSeconds()}\",\n    Model = \"gpt-4.1\",\n});\n\nvar response = await session.SendAndWaitAsync(\n    new MessageOptions { Prompt = message });\n```\n\n## 后端服务的身份验证\n\n### 环境变量令牌\n\n最简单的方法 - 在 CLI 服务器上设置令牌：\n\n```shell\n# All requests use this token\nexport COPILOT_GITHUB_TOKEN=\"YOUR-SERVICE-ACCOUNT-TOKEN\"\ncopilot --headless --port 4321\n```\n\n将 `YOUR-SERVICE-ACCOUNT-TOKEN` 替换为 GitHubpersonal access token 或服务帐户的 OAuth 令牌。\n\n### 每用户令牌 (OAuth)\n\n创建会话时传递单个用户令牌：\n\n```typescript\n// Your API receives user tokens from your auth layer\napp.post(\"/chat\", authMiddleware, async (req, res) => {\n    const client = new CopilotClient({\n        cliUrl: \"localhost:4321\",\n        githubToken: req.user.githubToken,\n        useLoggedInUser: false,\n    });\n\n    const session = await client.createSession({\n        sessionId: `user-${req.user.id}-chat`,\n        model: \"gpt-4.1\",\n    });\n\n    const response = await session.sendAndWait({\n        prompt: req.body.message,\n    });\n\n    res.json({ content: response?.data.content });\n});\n```\n\n### BYOK （无 GitHub 身份验证）\n\n请为模型提供商使用自己的 API 密钥：\n\n```typescript\nconst client = new CopilotClient({\n    cliUrl: \"localhost:4321\",\n});\n\nconst session = await client.createSession({\n    model: \"gpt-4.1\",\n    provider: {\n        type: \"openai\",\n        baseUrl: \"https://api.openai.com/v1\",\n        apiKey: process.env.OPENAI_API_KEY,\n    },\n});\n```\n\n## 常见后端模式\n\n### 使用 Express 的 Web API\n\n```typescript\nimport express from \"express\";\nimport { CopilotClient } from \"@github/copilot-sdk\";\n\nconst app = express();\napp.use(express.json());\n\n// Single shared CLI connection\nconst client = new CopilotClient({\n    cliUrl: process.env.CLI_URL || \"localhost:4321\",\n});\n\napp.post(\"/api/chat\", async (req, res) => {\n    const { sessionId, message } = req.body;\n\n    // Create or resume session\n    let session;\n    try {\n        session = await client.resumeSession(sessionId);\n    } catch {\n        session = await client.createSession({\n            sessionId,\n            model: \"gpt-4.1\",\n        });\n    }\n\n    const response = await session.sendAndWait({ prompt: message });\n    res.json({\n        sessionId,\n        content: response?.data.content,\n    });\n});\n\napp.listen(3000);\n```\n\n### 后台工作者\n\n```typescript\nimport { CopilotClient } from \"@github/copilot-sdk\";\n\nconst client = new CopilotClient({\n    cliUrl: process.env.CLI_URL || \"localhost:4321\",\n});\n\n// Process jobs from a queue\nasync function processJob(job: Job) {\n    const session = await client.createSession({\n        sessionId: `job-${job.id}`,\n        model: \"gpt-4.1\",\n    });\n\n    const response = await session.sendAndWait({\n        prompt: job.prompt,\n    });\n\n    await saveResult(job.id, response?.data.content);\n    await session.disconnect(); // Clean up after job completes\n}\n```\n\n### Docker Compose 部署\n\n```yaml\nversion: \"3.8\"\n\nservices:\n  copilot-cli:\n    image: ghcr.io/github/copilot-cli:latest\n    command: [\"--headless\", \"--port\", \"4321\"]\n    environment:\n      - COPILOT_GITHUB_TOKEN=${COPILOT_GITHUB_TOKEN}\n    ports:\n      - \"4321:4321\"\n    restart: always\n    volumes:\n      - session-data:/root/.copilot/session-state\n\n  api:\n    build: .\n    environment:\n      - CLI_URL=copilot-cli:4321\n    depends_on:\n      - copilot-cli\n    ports:\n      - \"3000:3000\"\n\nvolumes:\n  session-data:\n```\n\n## 健康检查\n\n监视 CLI 服务器的运行状况：\n\n```typescript\n// Periodic health check\nasync function checkCLIHealth(): Promise<boolean> {\n    try {\n        const status = await client.getStatus();\n        return status !== undefined;\n    } catch {\n        return false;\n    }\n}\n```\n\n## 会话清理\n\n后端服务应主动清理会话，以避免资源泄漏：\n\n```typescript\n// Clean up expired sessions periodically\nasync function cleanupSessions(maxAgeMs: number) {\n    const sessions = await client.listSessions();\n    const now = Date.now();\n\n    for (const session of sessions) {\n        const age = now - new Date(session.createdAt).getTime();\n        if (age > maxAgeMs) {\n            await client.deleteSession(session.sessionId);\n        }\n    }\n}\n\n// Run every hour\nsetInterval(() => cleanupSessions(24 * 60 * 60 * 1000), 60 * 60 * 1000);\n```\n\n## 局限性\n\n| 限度                       | 详细信息              |\n| ------------------------ | ----------------- |\n| **单 CLI 服务器 = 单一故障点**    | 考虑生产部署的高可用性模式。    |\n| **SDK 和 CLI 之间没有内置身份验证** | 保护网络路径（同一主机、网吧等）。 |\n| **本地磁盘上的会话状态**           | 装载持久存储以便容器重启时使用。  |\n| **30 分钟空闲超时**            | 不活动的会话将被自动清理。     |\n\n## 后续步骤\n\n* 有关安装和第一条消息，请参阅 [开始使用 Copilot SDK](/zh/copilot/how-tos/copilot-sdk/sdk-getting-started)。\n* 有关在重启期间恢复会话的信息，请参阅存储库中的[](https://github.com/github/copilot-sdk/blob/main/docs/features/session-persistence.md)`github/copilot-sdk`。\n* 有关添加用户身份验证的信息，请参阅存储库中的 [](https://github.com/github/copilot-sdk/blob/main/docs/setup/github-oauth.md)`github/copilot-sdk`。"}