1. 项目概述一个为异构AI智能体打造的分布式指挥中心如果你和我一样管理着几台散落在不同角落的机器——云上的GPU实例、办公室的MacBook、家里那台常年开着的Linux工作站——并且试图让它们协同工作跑一些AI任务那你一定体会过那种“精神分裂”般的痛苦。每台机器环境不同、配置各异任务调度靠手动SSH状态监控靠肉眼日志分散在各个角落。这根本不是规模化协作该有的样子。ACC全称Agent Command Center就是为了解决这个问题而生的。你可以把它理解为一个专为AI智能体Agent设计的“分布式操作系统内核”或“任务调度中心”。它的核心目标很简单将一群异构的机器我们称之为“节点”或“智能体”无缝连接起来形成一个统一的、可协调的算力池。无论是需要Claude Code进行代码生成的开发任务还是需要vLLM进行大模型推理的GPU任务抑或是简单的数据抓取脚本你都可以通过ACC的中心枢纽Hub进行统一派发、监控和管理。这个项目最吸引我的地方在于它的“务实”和“解耦”。它没有试图创造一个无所不能的超级AI而是专注于做好“协调”这件事。Hub中心节点提供REST API和一个简洁的Web仪表盘负责维护工作队列、注册表、密钥库而各个Agent工作节点则根据自身能力是否有GPU、是否运行了Claude CLI等主动拉取任务、执行并上报结果。这种基于“能力声明”和“工作拉取”的模型使得集群可以轻松地混搭不同架构和用途的机器。2. 核心架构与设计哲学拆解ACC的架构清晰地区分了“控制平面”和“数据/执行平面”这是一种在分布式系统中被反复验证的有效模式。2.1 中心化的控制与去中心化的执行控制平面Hub这是系统的大脑运行在acc-server这个Rust服务上默认端口8789。它承担着几个关键职责注册中心所有Agent启动后都需要向Hub注册上报自己的AGENT_NAME、AGENT_HOST以及最关键的能力标识如AGENT_HAS_GPU、AGENT_CLAUDE_CLI等。Hub的仪表盘让你对所有在线节点的状态和能力一目了然。工作队列任务以JSON格式被提交到队列中。每个任务都带有一个preferred_executor字段例如claude_cli、hermes、gpu。Hub并不主动推送任务而是等待具有相应能力的Agent来“认领”Claim。这避免了中心节点成为性能瓶颈和单点故障。消息总线AgentBus这是节点间直接通信的通道。Hub在这里扮演了“交换机”的角色负责将签名后的消息分发给指定的或所有Agent。例如一个需要远程执行命令的请求就会通过这条总线传递。密钥管理所有敏感配置如API Keys都通过Hub的/api/secrets接口统一管理并由一个同步脚本deploy/secrets-sync.sh安全地分发到各个Agent的本地环境文件中。这从根本上杜绝了密钥在多个节点上手散拷贝的安全隐患。数据/执行平面Agents这是系统的四肢由分布在各地的节点组成。每个节点上运行着一组守护进程Servicesccc-queue-worker: 核心工人持续轮询Hub上的工作队列寻找与自己能力匹配的待处理任务。hermes-driver: 如果节点负责运行hermes-agent一个具体的AI智能体运行时这个驱动会负责启动、监控并驱动任务完成。ccc-exec-listen: 监听来自AgentBus的远程执行请求在沙箱环境中运行命令并返回结果。各种能力特定的服务如保持Claude Code会话的tmux守护进程、维持vLLM服务温暖的ollama-keepalive等。这种设计的好处是显而易见的Hub即使短暂离线已经领取任务的Agent仍可继续执行新节点加入时只需配置好Hub地址和令牌其能力会自动融入集群节点的异构性被抽象为统一的能力标签调度逻辑变得清晰。2.2 能力模型如何让机器“自我介绍”ACC的精妙之处在于它用一套简单的环境变量就让每台机器学会了“自我介绍”。这不是简单的硬件信息汇报而是声明自己“能干什么”。# 这是一台拥有GPU的推理节点可能的部分配置 AGENT_NAME“natasha-gpu01” AGENT_HAS_GPUtrue AGENT_GPU_MODEL“RTX 4090” AGENT_GPU_COUNT1 VLLM_ENABLEDtrue VLLM_MODEL“Qwen2.5-7B-Instruct”# 这是一台开发机专注于代码生成任务 AGENT_NAME“bullwinkle-mac” AGENT_CLAUDE_CLItrue AGENT_CLAUDE_MODEL“claude-3-5-sonnet”当ccc-queue-worker去查询队列时它会将自己的能力列表发送给Hub。Hub在匹配任务时会寻找preferred_executor与Agent能力相符的项。例如一个标记为preferred_executor: claude_cli的任务只会被AGENT_CLAUDE_CLItrue的节点领取。这种基于声明的调度比基于复杂资源探测的调度要轻量和灵活得多特别适合小规模、异构的私有集群。2.3 通信层AgentBus与反向隧道节点间的通信是分布式系统的血脉。ACC提供了两种主要模式AgentBus基于SSE的发布/订阅这是节点间直接通信的主干道。消息使用AGENTBUS_TOKEN进行HMAC-SHA256签名确保完整性。Hub作为消息中转站将消息通过Server-Sent Events (SSE)推送给所有连接的Agent。远程执行/api/exec就是基于此实现的Hub收到执行请求通过AgentBus转发给目标节点上的ccc-exec-listen服务执行结果再通过回调接口返回。这个过程实现了安全的远程过程调用RPC。反向SSH隧道用于防火墙后的节点这是ACC解决网络穿透问题的“神来之笔”。很多个人机器位于NAT或严格防火墙之后无法被Hub直接访问。ACC的解决方案是让这些“防火墙内”的节点主动向外建立一条到Hub的SSH反向隧道。流程是Agent先通过API将自己的SSH公钥注册到HubHub将其授权给一个专用的tunnel用户然后Agent发起ssh -N -R port:localhost:8080 tunnelhub-ip连接。这样Hub本地的port就被映射到了Agent内部的8080端口或其他服务端口。系统服务sparky-reverse-tunnel.service自动化了这个过程。这意味着你家里的笔记本即使没有公网IP也能作为集群的一个完整节点参与工作极大地扩展了集群的边界。实操心得网络配置是最大拦路虎在部署ACC集群时我踩的第一个坑就是网络。确保Hub节点有一个稳定的、能被所有Agent访问的地址域名或IP是重中之重。对于家庭网络中的节点我强烈推荐使用Tailscale等工具组建虚拟局域网并将CCC_TAILSCALE_URL配置为Tailscale内网IP这比处理复杂的端口转发要可靠得多。反向隧道方案是最后的保障但SSH长连接的稳定性需要留意。3. 从零开始部署与配置实战指南理论说再多不如动手搭一遍。下面我将以部署一个最小化的“1 Hub 1 Agent”集群为例展示完整流程。假设Hub运行在一台Ubuntu云服务器上Agent是一台本地MacBook。3.1 Hub节点部署搭建指挥中心首先在你的云服务器Hub上操作。第一步克隆代码与基础准备# 1. 克隆仓库 git clone ACC仓库地址 cd ACC # 2. 安装基础依赖 (Rust, Docker, make等)。以Ubuntu为例 sudo apt update sudo apt install -y curl build-essential docker.io docker-compose make # 安装Rust (如果尚未安装) curl --proto https --tlsv1.2 -sSf https://sh.rustup.rs | sh source $HOME/.cargo/env # 3. 创建配置目录并复制环境模板 mkdir -p ~/.ccc cp deploy/.env.server.template ~/.ccc/.env第二步编辑Hub核心配置文件现在编辑~/.ccc/.env这是Hub的“大脑配置文件”。nano ~/.ccc/.env你需要关注并修改以下关键变量# 核心服务端口 CCC_PORT8789 # 认证令牌这是Agent用来连接Hub的密码。可以生成一个强随机字符串。 # 格式为名称:令牌多个用逗号分隔。这里我们创建一个名为‘default’的令牌。 CCC_AUTH_TOKENS“default:your_super_strong_agent_token_here” # 管理员令牌用于高危操作务必与CCC_AUTH_TOKENS不同且更复杂。 CCC_ADMIN_TOKEN“your_even_stronger_admin_token_keep_it_secret” # MinIO对象存储配置用于Agent间共享文件 MINIO_ENDPOINT“http://localhost:9000” MINIO_ACCESS_KEY“minioadmin” MINIO_SECRET_KEY“minioadmin” # 生产环境务必更改 MINIO_BUCKET“agents” # 可选Slack/Mattermost集成用于接收通知 # SLACK_TOKEN“xoxb-...” # SLACK_DEFAULT_CHANNEL“#acc-alerts”第三步启动Docker核心服务栈ACC使用Docker Compose来管理MinIO、Qdrant等依赖服务。# 启动服务 make docker-up # 查看日志 make docker-logs执行make docker-up后你应该能看到MinIO对象存储、Qdrant向量数据库等容器成功启动。此时Hub的Rust API服务acc-server可能还未运行因为我们需要先构建它。第四步构建并启动Rust API服务器# 构建acc-server二进制文件 make build # 启动acc-server服务。ACC提供了systemd单元文件最规范的方式是使用它。 sudo cp deploy/systemd/acc-server.service /etc/systemd/system/ sudo systemctl daemon-reload sudo systemctl enable --now acc-server.service # 检查服务状态和日志 sudo systemctl status acc-server.service journalctl -u acc-server.service -f如果一切顺利访问http://你的服务器IP:8789就能看到ACC的Web仪表盘了。一个新鲜的、空荡荡的指挥中心就此诞生。3.2 Agent节点部署招募第一名“士兵”现在切换到你的MacBookAgent节点。第一步克隆与准备git clone ACC仓库地址 cd ACC mkdir -p ~/.ccc cp deploy/.env.template ~/.ccc/.env第二步编辑Agent配置文件编辑~/.ccc/.env告诉Agent如何找到Hub以及它是谁。nano ~/.ccc/.env# 指向Hub的地址 CCC_URL“http://你的云服务器IP:8789” # 使用之前在Hub配置中定义的Agent令牌 CCC_AGENT_TOKEN“your_super_strong_agent_token_here” # 注意这里只填令牌不填名称 # 为你的Agent起个名字和主机名 AGENT_NAME“my-macbook-agent” AGENT_HOST“MacBook-Pro-Local” # 声明你的能力这台MacBook假设我们安装了Claude Code CLI AGENT_CLAUDE_CLItrue AGENT_CLAUDE_MODEL“claude-3-5-sonnet” # 根据你安装的Claude版本调整 # 其他能力根据实际情况设置例如没有GPU AGENT_HAS_GPUfalse第三步注册Agent到Hub这是关键一步将本地的“能力声明”发送到中心。make register这个命令会读取你的~/.ccc/.env文件并向Hub的/api/agents/register端点发送一个POST请求包含你的AGENT_NAME和所有以AGENT_开头的变量。如果成功你会在Hub的仪表盘“Agents”页面看到一个新节点在线。第四步启动Agent后台服务Agent需要持续运行几个后台进程来拉取任务、监听消息。# ACC为macOS提供了launchd plist文件这是原生的后台服务管理方式。 # 复制并加载队列工作者服务 cp deploy/launchd/com.ccc.queue-worker.plist ~/Library/LaunchAgents/ launchctl load ~/Library/LaunchAgents/com.ccc.queue-worker.plist # 复制并加载总线监听服务 cp deploy/launchd/com.ccc.bus-listener.plist ~/Library/LaunchAgents/ launchctl load ~/Library/LaunchAgents/com.ccc.bus-listener.plist # 启动定时心跳任务每10分钟报告一次状态 cp deploy/launchd/com.ccc.agent.plist ~/Library/LaunchAgents/ launchctl load ~/Library/LaunchAgents/com.ccc.agent.plist launchctl start com.ccc.agent # 立即运行一次注意事项环境变量与服务加载顺序launchd服务在加载时就会读取环境。如果你在加载服务后才修改~/.ccc/.env文件需要先launchctl unload再重新load对应的plist文件或者直接重启电脑。更稳妥的做法是在plist文件中通过EnvironmentVariables键直接指定CCC_ENV_PATH指向你的环境文件路径。ACC的模板plist通常已经考虑了这一点但检查一下总是好的。3.3 核心组件配置详解让系统“活”起来基础部署只是让节点通了电要真正让集群智能地工作还需要配置几个核心“器官”。TokenHubLLM调用的智能路由ACC本身不直接调用LLM API而是通过一个名为tokenhub的独立组件进行路由。这相当于一个本地的、带计量和路由功能的LLM API网关。在Hub节点上克隆并配置tokenhub。在tokenhub的配置中填入你的OpenAI、Anthropic、Google AI或本地vLLM端点的API密钥和地址。在ACC的Agent环境变量中设置TOKENHUB_URLhttp://localhost:8090假设tokenhub与Hub同机和对应的TOKENHUB_API_KEY。 这样当任务需要调用LLM时请求会发给TokenHub由它决定是使用昂贵的商用API还是转发给集群内某台GPU节点上的vLLM服务实现了成本与性能的优化。vLLM GPU节点配置释放本地算力对于拥有GPU的节点配置vLLM可以极大提升推理任务的效率和降低成本。# 在GPU节点的 ~/.ccc/.env 中启用并配置vLLM VLLM_ENABLEDtrue VLLM_MODEL“Qwen2.5-7B-Instruct” # 你下载并准备好的模型 VLLM_SERVED_NAME“qwen-7b” # 在TokenHub中注册的别名 VLLM_PORT8000 VLLM_MODEL_PATH“/path/to/your/models” # 模型存放目录同时你需要在该节点上安装并运行vLLM服务。ACC的deploy/systemd/目录下可能有相关的服务文件模板如ollama-keepalive.service需根据vLLM调整。核心是确保一个vLLM服务在localhost:8000运行并加载了指定模型。之后在TokenHub的配置中将这个节点的vLLM端点添加为一个上游源。这样需要inference_key执行器的任务就可能被路由到这台机器的本地模型上执行。Claude Code CLI集成自动化编程助手对于标记为preferred_executor: claude_cli的任务需要Agent有一个持久的Claude Code会话在tmux中运行。确保在Agent机器上安装了Claude Code CLI。使用ACC提供的launchd plist (com.ccc.claude-main.plist) 或手动创建一个tmux会话tmux new-session -d -s claude-main tmux send-keys -t claude-main ‘claude --dangerously-skip-permissions’ Enter确保AGENT_CLAUDE_CLItrue。ACC的claude-worker.mjs脚本会通过tmux发送命令到这个会话来执行代码任务。4. 工作流实战提交、执行与监控一个任务集群搭建好了我们来真正跑一个任务。假设我们想让集群帮我们写一个Python脚本来获取天气信息。4.1 通过API提交任务ACC的所有操作都可通过Hub的REST API完成。我们使用curl命令来模拟。# 在任意能访问Hub的机器上执行 HUB_URL“http://你的hub-ip:8789” AGENT_TOKEN“your_super_strong_agent_token_here” curl -X POST “${HUB_URL}/api/queue” \ -H “Authorization: Bearer ${AGENT_TOKEN}” \ -H “Content-Type: application/json” \ -d ‘{ “name”: “fetch-weather-script”, “preferred_executor”: “claude_cli”, “payload”: { “instruction”: “请编写一个Python脚本使用requests库从‘wttr.in’获取指定城市默认为北京的当前天气并以美观的格式打印温度、天气状况和湿度。请添加简单的错误处理。”, “language”: “zh”, “max_tokens”: 1000 } }‘如果成功API会返回一个JSON响应包含任务的唯一IDitem_id。这个任务现在进入了Hub的全局工作队列状态为pending。4.2 Agent领取与执行配置了AGENT_CLAUDE_CLItrue的MacBook Agent其ccc-queue-worker服务会定期例如每30秒扫描队列。当它发现这个preferred_executor: claude_cli的任务时会将其状态改为claimed然后调用workqueue/scripts/claude-worker.mjs脚本。该脚本的核心逻辑是将任务payload中的instruction等信息格式化。通过tmux向名为claude-main的会话发送命令与Claude Code交互。获取Claude生成的代码。将生成的代码作为结果通过POST /api/queue/{item_id}/result回调接口提交给Hub。你可以在Hub的仪表盘“Queue”页面实时看到任务状态从pending-claimed-completed的变化。完成后点击任务详情就能看到Claude生成的Python脚本。4.3 远程执行与AgentBus消息除了队列任务ACC还支持直接的远程命令执行。这利用了AgentBus通道。# 向名为‘my-macbook-agent’的节点发送命令 curl -X POST “${HUB_URL}/api/exec” \ -H “Authorization: Bearer ${AGENT_TOKEN}” \ -H “Content-Type: application/json” \ -d ‘{ “agent”: “my-macbook-agent”, “command”: “ls -la ~/”, “timeout_secs”: 30 }‘Hub收到请求后不会直接执行而是通过AgentBus的ccc.exec频道将这条签名后的消息发送给目标Agent。目标Agent上的ccc-exec-listen服务接收到消息在沙箱环境可能是docker或nsjail中执行ls -la ~/命令然后将标准输出、标准错误和退出码封装起来通过POST /api/exec/:exec_id/result发送回Hub。整个过程是异步且安全的。5. 运维、调试与故障排查实录运行一个分布式系统总会遇到各种问题。以下是基于我个人实践整理的常见问题与解决思路。5.1 节点注册失败或心跳异常症状Agent在仪表盘上显示为离线或者刚注册就断开。检查网络连通性在Agent节点上执行curl -v ${CCC_URL}/api/health。确保能收到200响应。如果Hub在公网检查防火墙是否开放了8789端口。如果使用Tailscale检查CCC_TAILSCALE_URL配置是否正确。检查认证令牌确认CCC_AGENT_TOKEN的值与Hub端CCC_AUTH_TOKENS中定义的某个令牌完全一致不包括前面的名称部分。注意大小写和特殊字符。检查环境变量文件路径ACC服务默认从~/.ccc/.env读取配置。使用cat ~/.ccc/.env确认文件存在且内容正确。对于systemd/launchd服务确认其配置文件中指定的环境文件路径是否正确。查看日志Hub端journalctl -u acc-server.service -f --lines50Agent端队列工作者journalctl -u ccc-queue-worker.service -f(Linux) 或log stream --predicate ‘process “ccc-queue-worker”’(macOS如果日志输出到系统)。5.2 任务长时间处于Pending状态无人领取症状任务提交成功但一直卡在pending没有Agent去claim它。检查执行器匹配确认任务的preferred_executor例如claude_cli是否有在线的Agent声明了对应的能力AGENT_CLAUDE_CLItrue。在仪表盘的“Agents”页面查看各节点的能力标签。检查队列工作者状态登录到对应能力的Agent节点检查ccc-queue-worker服务是否在正常运行。systemctl status ccc-queue-worker.service(Linux) 或launchctl list | grep ccc.queue-worker(macOS)。检查轮询间隔ccc-queue-worker的轮询间隔在代码中定义。如果觉得慢可以查阅其源码或配置但通常不建议设置得太频繁以免给Hub造成压力。查看工作者日志在Agent节点查看队列工作者的日志看它是否在正常扫描Hub的/api/queue/pending端点以及是否报告了任何错误如网络错误、解析错误。5.3 AgentBus消息无法接收或远程执行失败症状通过/api/exec发起的远程执行请求超时或失败。检查AgentBus监听服务确保目标Agent上的ccc-bus-listener和ccc-exec-listen服务都在运行。检查AGENTBUS_TOKEN这是消息签名的密钥。必须确保Hub和所有Agent的~/.ccc/.env文件中的AGENTBUS_TOKEN值完全相同。这是最常见的配置错误。任何不一致都会导致签名验证失败消息被丢弃。检查反向隧道如适用如果目标Agent在防火墙后并使用反向隧道确认隧道是否建立成功。在Hub上执行ss -tlnp | grep assigned-port查看端口是否在监听。在Agent上检查sparky-reverse-tunnel.service的日志。查看执行日志Hub的acc-server日志会记录/api/exec请求的接收和转发。Agent的ccc-exec-listen服务日志会记录命令的执行过程和结果。两边对照排查。5.4 Claude Code任务执行失败症状claude_cli任务被领取但最终失败结果可能是超时或空输出。确认tmux会话存在在Agent节点执行tmux list-sessions确认名为claude-main的会话存在且状态正常。进入会话手动测试tmux attach -t claude-main然后手动输入一段指令看Claude Code是否能正常响应。可能Claude CLI需要重新认证或遇到了其他交互式提示。检查claude-worker脚本查看workqueue/scripts/claude-worker.mjs脚本。它通过tmux send-keys发送指令。确认发送的指令格式符合Claude Code CLI的预期。有时需要额外的换行符(Enter)或等待时间。检查脚本权限和环境确保claude-worker.mjs有可执行权限并且它运行在正确的Node.js环境下。5.5 数据持久化与备份ACC Hub的状态队列、Agent注册信息、密钥等默认以JSON文件形式存储在~/.ccc/data/目录下。这不是一个工业级的数据库但足够轻量和小规模使用。定期备份最简单的备份策略就是定期压缩拷贝整个~/.ccc目录。你可以写一个cron任务来完成。不要手动编辑JSON文件除非你确切知道自己在做什么并且服务已停止。直接编辑可能导致数据损坏。所有操作都应通过API进行。MinIO数据如果使用了MinIO存储任务产生的文件需要单独备份MinIO的数据卷Docker volume。docker-compose.yml中通常已经配置了卷映射。6. 进阶技巧与生态集成当基础集群稳定运行后你可以探索更多高级用法来提升效率。技能Skills与自动化ACC支持“技能”的概念你可以将复杂的、多步骤的任务如“部署一个静态网站”封装成一个技能脚本存放在Hub。然后通过API或未来可能的UI一键触发ACC会自动将其分解为多个队列项并按顺序执行。与外部系统集成ACC的Webhook支持和消息网关Hermes Gateway允许它与外部世界互动。GitHub Issue扫描器配置GITHUB_TOKEN和WATCH_CHANNEL可以让ACC监控特定GitHub仓库的Issue并将其自动转化为队列任务。例如自动处理功能请求或Bug报告。Slack/Telegram机器人通过配置hermes gateway和相应的令牌你可以直接在Slack或Telegram频道里向你的AI集群下达自然语言指令结果也会被发送回频道。这提供了极其便捷的人机交互界面。混合云与成本优化这是ACC架构带来的巨大优势。你可以这样配置本地GPU节点配置VLLM_ENABLEDtrue处理大部分对延迟敏感或需要频繁调用的推理任务。云端按需GPU实例配置为普通Agent但AGENT_HAS_GPUtrue。当本地算力满载或需要特定型号GPU时通过TokenHub的路由策略将任务定向到云实例。结合云的弹性伸缩可以在需要时自动创建任务完成后销毁最大化成本效益。开发机处理所有claude_cli的代码生成和审查任务。通过TokenHub的智能路由整个集群对外呈现为一个统一的、能力强大的LLM端点而内部则在动态、经济地调配算力。监控与告警虽然ACC自带基础仪表盘但对于生产级关注你需要更细致的监控。Prometheus/Grafana可以为acc-server添加Prometheus指标导出监控队列长度、各状态任务数量、Agent在线率、API请求延迟等。日志聚合使用Loki或ELK栈来集中收集所有Hub和Agent节点的日志便于全局问题排查。自定义心跳检查除了内置的心跳你可以编写自定义脚本定期检查关键服务的健康状态如vLLL服务是否响应、GPU显存使用率并通过AgentBus将结果报告给Hub在仪表盘上展示自定义的健康指标。部署和运维ACC集群的过程就像在组建一支小而精的特种部队。每台机器都有自己的专长Hub则是那位运筹帷幄的指挥官。它可能没有Kubernetes那样庞大和复杂但在管理小规模、异构、且以AI任务为核心的私有计算资源时它的简洁、直接和高度可定制化带来了令人愉悦的掌控感和效率。最大的挑战往往不在软件本身而在前期的网络打通和各个组件Claude CLI, vLLM, TokenHub的独立配置上。一旦跨过这个门槛你会发现一个自动化的、可扩展的AI算力池正在为你7x24小时待命。