Claude Plane：集中管理多机Claude CLI会话与自动化编排的开源控制平面

1. 项目概述与核心价值如果你和我一样经常需要在多台开发机、测试服务器甚至远程的云实例上运行Claude Code CLI来处理不同的任务那你肯定也遇到过类似的麻烦每次都得SSH登录到不同的机器手动启动Claude会话窗口一关任务就中断更别提在不同会话间切换、监控进度有多费劲了。这种碎片化的管理方式不仅效率低下还容易出错。最近我在GitHub上发现了一个名为Claude Plane的开源项目它精准地击中了这个痛点。简单来说Claude Plane是一个自托管的控制平面专门用来集中管理分布在多台机器上的Claude CLI交互式会话。你可以把它想象成一个专为AI命令行助手设计的“机场塔台”而每台运行着Claude的机器就是等待调度的“飞机”。通过一个统一的Web界面你就能创建、监控并与任何一台已连接机器上的Claude会话进行交互彻底告别了在多终端间疲于奔命的日子。这个项目的核心价值在于它将原本孤立的、临时的CLI会话变成了可持久化、可远程管理、可编排的“一等公民”。无论是想同时观察六台服务器上代码生成任务的进度还是定义一个包含依赖关系的多步骤自动化作业比如先让Claude在A机器上生成代码再在B机器上运行测试Claude Plane都能轻松搞定。它采用Go语言编写核心服务React构建前端界面架构清晰并且坚持Docker优先的部署理念一条docker compose up命令就能拉起整个系统对运维非常友好。对于需要规模化、自动化使用Claude CLI的开发者、运维工程师或技术团队来说这无疑是一个能显著提升工作流效率的利器。2. 架构深度解析三足鼎立的精巧设计Claude Plane的架构设计体现了清晰的关注点分离思想整个系统由三个独立的Go二进制组件构成各自承担明确的职责通过定义良好的接口进行通信。理解这个架构是后续进行部署、排错和深度定制的基础。2.1 核心组件Server、Agent与BridgeServer控制平面这是整个系统的大脑和指挥中心。它是一个常驻进程主要提供四大功能。第一它内嵌并服务于React构建的Web前端用户通过浏览器访问的仪表盘就是由它提供的。第二它负责所有会话Session的生命周期管理包括创建、销毁、状态维护以及与前端WebSocket的实时数据流桥接。第三它实现了作业Job编排引擎可以解析用户定义的DAG有向无环图作业并根据依赖关系在合适的Agent上调度执行。第四它作为gRPC服务端持续监听来自各个Agent的入站连接。所有元数据如用户信息、作业定义、会话历史等都存储在一个内嵌的SQLite数据库中这使得Server本身成为一个无状态依赖、易于部署的单体。注意Server的“无状态”是相对的其状态存储在SQLite文件中。因此在Docker部署时务必通过Volume将/data目录持久化否则重启容器会导致所有配置和会话历史丢失。Agent工作节点这是运行在目标工作机器Worker上的“手脚”。每个Agent负责管理本机上的一个或多个Claude CLI进程。它的核心任务包括通过PTY伪终端与Claude CLI进程交互实时捕获终端的标准输出和标准错误并将这些数据流通过持久的gRPC连接流式传输回Server。同时它也接收来自Server的指令例如“启动一个新的Claude会话”或“向当前会话发送一条命令”。Agent采用“拨入”模式主动连接Server这意味着工作节点可以位于NAT或防火墙之后无需在防火墙上为每个工作节点开放入站端口极大地简化了网络配置。Bridge桥接器这是一个可选的集成组件充当Claude Plane内部世界与外部服务如GitHub、Telegram、Slack的桥梁。它监听外部事件例如GitHub仓库的Push事件、Telegram的聊天命令并将其转换为Claude Plane内部的作业触发或通知动作。Bridge默认与Server运行在同一个容器中其连接器Connector可以通过Web UI进行配置提供了极大的灵活性。2.2 通信与安全gRPC与mTLS组件间的通信是系统可靠性的基石。Agent与Server之间使用gRPC进行通信。gRPC基于HTTP/2支持双向流、多路复用等特性非常适合Agent需要向Server持续上报终端数据流同时随时接收Server控制指令的场景。相比传统的REST API其性能更高延迟更低。在安全方面Claude Plane没有采用简单的静态令牌而是实现了**双向TLSmTLS**认证。系统内置了一个CA证书颁发机构。当Server首次启动时会自动生成CA证书和服务器证书。Agent在通过join命令注册时会从Server处获取一个由该CA签名的客户端证书。此后所有Agent与Server之间的gRPC通信都使用TLS加密并且双方会验证对方的证书确保连接双方都是可信的。这有效防止了恶意节点接入或通信被窃听。# 简化的安全握手流程 1. Server启动 - 生成CA根证书 Server证书。 2. Agent执行 join - 向Server提供临时凭证Provisioning Code。 3. Server验证凭证 - 用CA为Agent签发客户端证书。 4. 后续通信 - Agent与Server使用各自的证书进行mTLS握手建立安全通道。2.3 数据流从按键到渲染理解一次用户交互的完整数据流能帮助你在出现问题时快速定位。假设你在Web界面的一个终端窗格中输入命令ls -la并按下回车前端浏览器中的xterm.js终端模拟器捕获按键事件通过WebSocket连接将ls -la\r\n包含回车符发送到Server。ServerWebSocket处理器收到数据根据会话ID找到对应的gRPC流。Server - AgentServer通过该会话的gRPC流将ls -la\r\n作为输入发送给管理此会话的Agent。AgentAgent将接收到的输入写入到对应Claude CLI进程的PTY主设备。Claude CLI进程从PTY从设备读取到输入ls -la执行并产生输出。Agent - ServerAgent从PTY主设备实时读取进程的输出通过gRPC流流式传输回Server。Server - 前端Server将收到的输出数据通过WebSocket转发给对应的浏览器客户端。前端渲染xterm.js接收到数据将其渲染到终端屏幕上用户看到ls -la命令的执行结果。这个过程是双向、实时的从而实现了与本地终端几乎无异的交互体验。同时由于所有终端输出都流经Server它能够将会话内容持久化到数据库实现“断线重连历史回放”的功能。3. 从零开始生产级部署实操指南虽然项目提供了快速的Docker运行命令但对于想要用于实际工作环境的用户我们需要一个更健壮、可维护的部署方案。下面我将分享一个基于Docker Compose的生产级配置并详细解释每个参数的意义。3.1 使用Docker Compose部署Server与Bridge我们不使用简单的docker run而是采用docker-compose.yml来定义服务这便于管理、版本控制和扩展。首先创建一个项目目录并编写配置文件。# docker-compose.yml version: 3.8 services: claude-plane: image: jurel89/claude-plane:latest container_name: claude-plane-server restart: unless-stopped ports: - 4200:4200 # Web UI 和 API - 4201:4201 # gRPC 端口供Agent连接 environment: - ADMIN_EMAILadminyourcompany.com # 强烈建议修改 - ADMIN_PASSWORDYourStrongPassword123! # 使用强密码 - SERVER_URLhttps://claude-plane.yourdomain.com # 关键必须是Agent能访问到的地址 - TZAsia/Shanghai # 设置容器时区 volumes: - claude-plane-data:/data # 持久化数据SQLite、配置、证书 - ./custom-config.toml:/config.toml:ro # 可选挂载外部配置文件 networks: - claude-plane-net volumes: claude-plane-data: driver: local networks: claude-plane-net: driver: bridge关键配置解析SERVER_URL这是整个配置中最重要的一环。这个URL会被写入到Agent的配置中Agent用它来连接Server。它必须是一个从Agent所在网络能够正确解析和访问的地址。场景一本地测试如果Server和Agent在同一台机器的Docker中运行可以使用http://host.docker.internal:4200Mac/Windows Docker Desktop或http://172.17.0.1:4200Linux Docker桥接网络网关。场景二服务器部署如果Server部署在公网或内网服务器IP为192.168.1.100则设置为http://192.168.1.100:4200。若配置了域名和反向代理如Nginx则设置为https://claude-plane.yourdomain.com。设置错误后果Agent会无法连接Server表现为join命令成功但Agent日志显示连接失败。数据持久化通过命名卷claude-plane-data将容器内的/data目录持久化。这个目录包含了自动生成的TLS证书、SQLite数据库文件和配置文件。务必确保此卷存在否则容器重启后所有数据清零。自定义配置环境变量可以覆盖基本设置。对于更复杂的配置如日志级别、存储路径、gRPC调优可以编写一个config.toml文件并通过Volume挂载到容器内的/config.toml。项目文档中的configuration.md列出了所有选项。启动服务# 在包含 docker-compose.yml 的目录下执行 docker-compose up -d启动后使用docker-compose logs -f claude-plane查看日志找到自动生成的admin账户密码如果你没通过环境变量设置的话。然后访问http://your-server-ip:4200即可登录仪表盘。3.2 工作节点Agent安装与系统服务化Agent的安装目标是让它成为一个可靠的后台服务。以下步骤以Linuxsystemd为例macOSlaunchd原理类似。第一步下载Agent二进制文件Agent二进制文件由Server直接提供这是一个非常巧妙的设计避免了去GitHub Releases页面手动寻找对应版本。# 从你的Claude Plane Server下载agent # 将 SERVER_IP 替换为你的实际服务器地址 export SERVER_IP192.168.1.100 curl -fL -o claude-plane-agent http://${SERVER_IP}:4200/dl/agent/linux-amd64 chmod x claude-plane-agent提示通过Server下载能确保Agent与Server版本兼容。URL路径中的linux-amd64可根据你的工作节点架构替换为linux-arm64树莓派等、darwin-amd64或darwin-arm64Mac。第二步生成并应用Provisioning CodeProvisioning Code是一个一次性令牌用于Agent向Server安全地注册自己并获取客户端证书。登录Claude Plane Web UI。导航到Settings-Provisioning。点击Create Token系统会生成一个6位代码如ABC123。这个代码有效时间很短默认5分钟。第三步执行Join命令在存放Agent二进制文件的工作节点上执行# 使用上一步获取的代码 ./claude-plane-agent join ABC123 --server http://${SERVER_IP}:4200 --insecure--insecure因为我们的Docker示例默认使用HTTP所以需要此标志来跳过TLS验证对Server证书。在生产环境使用HTTPS时必须移除--insecure标志。命令成功执行后会在用户家目录下生成~/.claude-plane/agent.toml配置文件其中包含了连接Server的地址和获取到的客户端证书。第四步安装为系统服务关键步骤这是保证Agent在机器重启后依然能自动运行的关键。sudo ./claude-plane-agent install-service --config ~/.claude-plane/agent.toml这个命令会做以下几件事将claude-plane-agent二进制文件复制到/usr/local/bin/。根据系统类型systemd或launchd生成并安装服务配置文件。启动服务并设置开机自启。安装完成后你可以通过系统命令管理Agent服务# 查看服务状态 sudo systemctl status claude-plane-agent # 查看实时日志 sudo journalctl -u claude-plane-agent -f # 重启服务 sudo systemctl restart claude-plane-agent第五步验证与前置条件登录Web UI在Dashboard或Agents页面你应该能看到新注册的Agent状态为Healthy。务必确保在工作节点上已经正确安装并配置了Claude CLI(claude) 且已经完成登录认证 (claude auth login)。因为Agent本质上是启动和管理本机的claude进程。4. 核心功能实战会话管理与作业编排部署完成只是开始真正发挥威力在于使用。Claude Plane的Web UI设计直观但理解其功能背后的逻辑能让你用得更得心应手。4.1 多视图会话管理像高手一样并行工作传统的终端 multiplexer如tmux, screen允许你在一个SSH连接中管理多个窗格但Claude Plane将其提升到了跨机器的维度。创建会话在Web UI中点击New Session你可以选择在哪台已注册的Agent上创建会话甚至可以指定工作目录和环境变量。点击创建后一个真正的Claude CLI进程就在远端的Agent机器上启动了其终端界面通过WebSocket实时推送到你的浏览器。多视图布局这是提升效率的杀手锏。你可以点击布局按钮选择将屏幕分割成2、3、4甚至6个窗格。每个窗格可以独立连接到不同Agent上的不同会话。使用场景同时监控三台服务器上的日志尾输出tail -f在第四台开发机上让Claude编写代码所有画面同屏展示。保存工作区你可以将当前打开的会话集合和布局保存为一个“工作区”Workspace。下次登录后直接加载工作区所有会话会自动重建并恢复连接立即回到之前的工作上下文。会话持久化即使你关闭了浏览器标签页甚至电脑休眠远端Agent上的Claude进程并不会终止。它继续在后台运行。当你重新打开Claude Plane页面时可以重新连接到这个“持久化会话”并且之前的所有终端输出scrollback都会被完整地重新播放给你真正做到“无缝续接”。4.2 作业系统定义与执行自动化工作流作业Job功能将Claude Plane从一个会话管理器升级为一个自动化编排引擎。你可以定义复杂的、多步骤的任务。作业定义作业使用YAML格式定义核心是描述一个有向无环图DAG。每个节点是一个“步骤”节点间可以定义依赖关系。# 示例一个简单的代码生成与测试作业 name: Generate API and Test description: Let Claude create a REST API endpoint and then run tests. steps: generate_code: agent: dev-machine-1 # 指定运行此步骤的Agent script: | cd /projects/myapp claude 请为用户模型创建一个完整的RESTful CRUD API使用Go和Gin框架。 # 此步骤没有依赖会最先运行 run_unit_tests: agent: dev-machine-1 script: | cd /projects/myapp go test ./... -v depends_on: [generate_code] # 依赖于 generate_code 完成 deploy_staging: agent: prod-agent-aws script: | cd /projects/myapp ./deploy.sh staging depends_on: [run_unit_tests] # 依赖于测试通过在这个例子中run_unit_tests会等待generate_code步骤成功完成后才执行。如果generate_code失败依赖它的后续步骤都不会执行。触发与监控作业定义可以通过UI创建或上传。定义好后可以手动触发运行也可以通过Bridge组件由外部事件触发如GitHub push。在Jobs页面你可以实时看到DAG的执行进度每个步骤是待执行、运行中、成功还是失败一目了然。点击任意步骤可以查看其详细的终端输出日志。实操心得脚本健壮性作业步骤中的script应该包含错误处理。例如在claude命令前可以检查所需文件是否存在在部署命令后可以添加健康检查。Agent选择策略可以根据Agent的标签如env: prod,gpu: true来动态选择运行步骤的机器而不是写死主机名。这需要在Agent注册时通过--tag参数指定标签。利用环境变量作业定义中可以引用环境变量如${API_KEY}这些变量可以在UI中集中管理避免将敏感信息硬编码在YAML里。5. 外部集成Bridge与高级配置Bridge组件是Claude Plane连接外部世界的枢纽。默认情况下它与Server运行在同一个容器内无需单独部署。5.1 配置GitHub Webhook实现CI/CD一个典型的场景是每当有代码推送到GitHub主分支时自动触发一个Claude Plane作业让Claude进行代码审查或运行自动化测试。在Claude Plane中配置GitHub连接器进入Settings-Connectors-GitHub。点击Add Configuration。你需要提供一个GitHub Personal Access Token需要repo和admin:repo_hook权限。配置保存后Claude Plane会为你提供一个唯一的Webhook URL如http://your-server:4200/api/bridge/hooks/github/your-connector-id。在GitHub仓库中设置Webhook进入你的GitHub仓库 -Settings-Webhooks-Add webhook。Payload URL: 填入上一步获得的Webhook URL。Content type: 选择application/json。Which events?: 选择“Just thepushevent”或根据你的需求选择。保存Webhook。创建由GitHub事件触发的作业在创建或编辑作业时找到Triggers部分。添加一个触发器类型选择GitHub Push并选择你刚配置的连接器。你可以进一步过滤例如只针对main分支的推送触发。现在每次符合条件的Push事件发生时这个作业就会被自动触发。5.2 通过Telegram/Slack接收通知反过来你也可以让Claude Plane将重要事件如作业失败、Agent离线推送到你的即时通讯工具。配置Telegram Bot在Telegram中找BotFather创建一个新的Bot获取它的API Token。在Claude Plane的Connectors-Telegram中添加配置填入Bot Token。启动Bot并发送/start消息给它。Claude Plane Bridge会记录你的Chat ID。设置通知规则在Settings-Notifications中可以创建规则。例如规则名称“生产作业失败”条件选择“当任何作业失败时”动作选择“发送Telegram消息”并选择你配置的Bot。这样一旦有作业失败你就会立刻在Telegram上收到警报。5.3 服务器高级配置详解对于有更高要求的部署你可能需要调整默认配置。创建一个config.toml文件并挂载到容器中。# config.toml 示例 [server] addr :4200 # HTTP/WebSocket 监听地址 grpc_addr :4201 # gRPC 监听地址 data_dir /data # 数据目录通常由Volume挂载覆盖 [server.log] level info # 日志级别: debug, info, warn, error format json # 输出为JSON格式便于ELK等系统收集 [server.auth] session_ttl 720h # 用户会话有效期默认30天 [server.storage] # SQLite 连接池配置 max_open_conns 10 max_idle_conns 5 conn_max_lifetime 1h [server.tls] # 如果使用自己的证书在此配置 # cert_file /path/to/cert.pem # key_file /path/to/key.pem [bridge] # 独立配置各个连接器 [bridge.github] enabled true [bridge.telegram] enabled true [bridge.slack] enabled false # 禁用Slack连接器通过外部配置文件你可以实现更精细的控制而无需修改环境变量或进入容器内部。6. 故障排查与性能调优即使设计再精良的系统在实际运行中也可能遇到问题。以下是基于我个人使用经验总结的常见问题排查清单和优化建议。6.1 常见问题速查表问题现象可能原因排查步骤Agent状态为Unhealthy或Disconnected1. 网络不通。2.SERVER_URL配置错误。3. Agent服务未运行或崩溃。4. mTLS证书问题。1. 从Agent机器ping/curlServer的SERVER_URL。2. 检查Agent配置文件~/.claude-plane/agent.toml中的server_addr。3.sudo systemctl status claude-plane-agent查看服务状态和日志。4. 检查证书是否过期日志中可能有TLS握手错误。Web UI无法打开或连接中断1. Server容器未运行或端口冲突。2. 浏览器到Server网络问题。3. WebSocket连接被防火墙/代理阻断。1.docker-compose ps确认容器状态docker-compose logs查看错误。2. 在服务器本地curl http://localhost:4200测试。3. 检查Nginx/Apache等反向代理是否正确配置了WebSocket代理Upgrade和Connection头。创建会话失败1. 目标Agent上未安装Claude CLI。2. Claude CLI未登录无有效会话。3. Agent用户权限不足。1. 在Agent机器上执行which claude确认安装。2. 切换到运行Agent服务的用户如root执行claude auth status检查登录状态。3. 确保Agent进程有权限访问指定的工作目录。作业步骤卡在Pending1. 依赖的前置步骤未完成。2. 指定的Agent标签无匹配的在线Agent。3. 资源不足如并发作业数限制。1. 检查DAG视图确认前置步骤状态。2. 检查作业YAML中agent选择器或标签是否正确。3. 查看Server日志可能有调度相关的警告。终端输出延迟或卡顿1. 网络延迟高或丢包。2. Server或Agent负载过高。3. 浏览器资源占用高。1. 检查网络状况。2. 查看Server/Agent的CPU、内存使用率。3. 尝试减少同时打开的终端窗格数量或降低终端回滚缓冲区大小在UI设置中。6.2 性能监控与优化建议监控指标Server监控其内存和CPU使用。SQLite在并发写入高时可能成为瓶颈如果作业和会话量极大可以考虑将data_dir放在高性能SSD上。Agent监控每个Agent上的Claude CLI进程数量及其资源消耗。一个Agent管理过多活跃会话可能会影响性能。网络监控Agent与Server之间的网络延迟和带宽特别是当终端输出流量很大时。优化建议为Agent打标签根据机器特性如regionus-east,envstaging,gputrue给Agent打上标签。在创建会话或定义作业时通过标签选择器来分配任务实现负载均衡和定向调度。调整gRPC参数如果在大规模部署中出现连接不稳定可以尝试在Server和Agent的配置中调整gRPC的keepalive参数以维持长连接的心跳。会话超时与清理对于非持久化的临时会话在UI中创建时可以设置超时时间避免遗忘的会话占用资源。使用HTTPS在生产环境务必通过Nginx等反向代理为Claude Plane Server配置HTTPS。这不仅能加密前端通信也是Agent使用mTLS无需--insecure标志的前提安全性更高。日志聚合将Server和Agent的JSON格式日志输出到stdout然后使用Docker的日志驱动或journald配合Logstash/Fluentd等工具进行集中收集和分析便于问题追踪。6.3 备份与恢复系统的核心状态存储在Server容器的/data目录中。定期备份此目录是至关重要的。# 简单备份示例 docker run --rm --volumes-from claude-plane-server -v $(pwd):/backup alpine tar czf /backup/claude-plane-backup-$(date %Y%m%d).tar.gz /data # 恢复示例需先停止服务 docker-compose down docker run --rm --volumes-from claude-plane-server -v $(pwd):/backup alpine sh -c rm -rf /data/* tar xzf /backup/claude-plane-backup-latest.tar.gz -C / docker-compose up -d对于生产环境建议将此备份流程自动化并将备份文件存储到异地。经过一段时间的深度使用Claude Plane给我的最大感触是它用一种优雅的方式将“人机交互”与“自动化编排”结合在了一起。它没有试图取代完整的CI/CD系统而是在AI助手交互这个特定场景下填补了从手动操作到自动化流程之间的空白。对于那些重度依赖Claude Code进行开发、运维或数据分析的团队花点时间部署和磨合这个工具带来的效率提升会是立竿见影的。最后一个小技巧多利用“工作区”功能为不同的项目或任务场景创建不同的工作区模板这能让你在复杂的多任务环境中快速切换上下文保持专注。