Nasiko 控制平面全景：单进程架构、Docker 快速部署、CLI 工作流与源码级解析

【免费下载链接】nasikoDeveloper Control Plane for your AI Agents项目地址https://gitcode.com/gh_mirrors/na/nasiko点击查看免费下载Nasiko 是一个面向 A2A 协议 Agent 的开发者控制平面Developer Control Plane以单个控制平面进程完成 Agent 的部署、路由、代理、密钥托管与可观测性。本文基于仓库根目录的 README.md 展开覆盖 Docker-only 快速启动、Rust 开发者路径、CLI 常用命令、Coding Agents 与 LLM Router 集成并结合 docker-compose.yml、config/src/lib.rs 与 justfile 等仓库文件补充实现证据读完后可独立完成一套本地 Nasiko 平台搭建与 Agent 部署。一、Nasiko 是什么把 Agent 运维问题收敛到一个进程当运行的 Agent 数量超过两三个运维问题会迅速涌现谁在调用谁每个 Agent 持有什么密钥一次调用花了多少钱失败原因是什么Nasiko 的定位是单一控制平面进程single control-plane process位于所有 Agent 之前一次性回答上述问题。它的核心机制包括终结 TLS、对每个请求做身份认证并自行代理所有 Agent 间流量——Agent 永远不对外暴露每一跳都是限流、ACL 与追踪的检查点语言无关Agent 可以用 Python、Rust、Go 或 TypeScript 编写只要说 A2A 协议即可接入无专有 Agent 格式、无锁定内置组件智能路由引擎、MCP Gateway、LLM Router、内嵌 OCI 镜像仓库、Flow Guards、加密 Secrets 引擎等。这一单进程、无独立网关的设计直接体现在工作区成员划分上Cargo.toml 将server、orchestrator、mcp-gateway、llm-router、oci、flow、secrets、agent-proxy、auth、observability、runtime等 crate 放在同一个 workspace 中各自对应一个控制平面内部能力。二、核心能力一览README 的功能表完整列出了平台能力以下按原文继承并补充源码位置佐证能力说明部署任意 A2A Agentnasiko deploy一条命令完成构建、推送到内嵌 registry、运行无需外部镜像仓库对应 oci/ crate智能路由引擎三级流水线embedding 相似度初筛 → 对话上下文重排 → LLM 最终选择对应 orchestrator/ crate单入口、恒代理Agent 不对外可达所有 Agent 间调用经服务端代理对应 agent-proxy/ 与 server/src/agent_proxy.rsMCP Gateway一个固定 URL 向所有 Agent 提供合并的、按权限过滤的 Composio 工具集与自定义 MCP 服务器视图Agent 不持有凭证对应 mcp-gateway/ crateLLM RouterAgent 拿到OPENAI_BASE_URL 短期身份令牌而非真实密钥provider/model/key 在服务端解析对应 llm-router/ crate全链路可观测每次分发与代理跳发出真实 OTel span形成端到端 tracetoken 用量与成本从gen_ai.*属性自动采集对应 observability/ crateFlow GuardsRedis 支撑的级联限制深度、扇出、token 预算、超时、环检测阻止失控 Agent 循环对应 flow/ crate加密 Secrets每 Agent 密钥 AES-256-GCM 静态加密仅在部署时注入对应 secrets/ crate访问控制用户-Agent 所有权/授权 与 Agent-Agent 白名单独立地门控每次代理调用内嵌 OCI Registry自托管、S3 支撑、层去重nasiko push/nasiko deploy不依赖外部仓库CLI 优先、无锁定nasiko new、run、chat、deploy自带 LLM provider三、架构单进程控制平面 三类支撑服务Nasiko 是单进程——没有独立网关。所有 Agent 间调用都经服务端代理回来服务端是唯一执行 flow 限制、ACL 与可观测性的咽喉点。持久化状态存放在Postgres、Redis和S3RustFS可观测性通过Tempo / Loki / OTel Collector提供可选。README 给出的架构总图如下mermaid对 Agent 的每个请求要么由路由引擎分发、要么被通用代理——两条路径都发源于服务端内部。Agent 永不接收直接的公开请求也不持有真实 API key 或工具凭证而是回连 LLM Router 与 MCP Gateway。从 docker-compose.yml 可以印证这套架构的落地形态postgrespgvector/pg16 镜像供向量检索、redis:7-alpine、rustfsS3 兼容存储9000 端口、otel-collector0.119.0、tempo:2.6.1、loki:3.3.2以及server服务本身。几个值得注意的实现细节server使用depends_on: condition: service_healthy等待 Postgres 与 Redis 健康检查通过后才启动——这正是 READMERequirements中要求 Compose V2 插件的原因V1 不支持service_healthy条件server挂载/var/run/docker.sock以便用 bollard 管理 Agent 容器对应 runtime/ 中的 DockerRuntimecompose 中显式覆写DATABASE_URL、REDIS_URL、S3_ENDPOINT等连接 URL 为 Docker 服务名并注入MCP_GATEWAY_PUBLIC_URL: http://server:8080/api/mcp与LLM_GATEWAY_BASE_URL——即 Agent 容器内如何回连网关的具体地址所有服务接入名为nasiko的共享网络DOCKER_AGENT_NETWORK: nasiko使服务端能通过容器 IP 直达 Agent 容器。四、环境要求Requirements组件最低版本说明Docker Engine Compose V2Compose V2 插件docker compose命令而非旧版独立docker-composev1 二进制docker-compose.yml 使用扩展语法depends_on: condition: service_healthyDocker-only 路径无需其他东西Rust1.85stable工作区目标为edition 2024见 Cargo.toml 中edition 2024在 Rust 1.85 稳定——仅 CLI / Path B 开发者路径需要Docker-only 路径不需要A2A 协议精确要求 Specv1.0上游最新v1.0.1Linux FoundationNasiko 在每个请求上强制A2A-Version: 1.0头旧版本如 0.2.x、0.3.0的 Agent 会被-32009 VersionNotSupported拒绝见 docs/A2A_PROTOCOL.md。任何说 v1.0 的 Agent 均可接入与实现语言无关源码级佐证版本头的硬编码可以在 CLI 中找到例如 cli/src/commands/chat.rs 中.header(A2A-Version, 1.0)示例 Agent如 agents/assistant-agent/main.py与 TUIcli/src/commands/tui/event.rs同样注入该头错误码语义定义在 docs/A2A_PROTOCOL.md-32009对应 VersionNotSupportedHTTP 层映射为 406。五、快速启动 — Docker-only无需 Rust最快路径只需要 Docker带 Compose。服务端在 Docker 内从源码自行编译。1. 克隆并配置git clone https://gitcode.com/gh_mirrors/na/nasiko cd nasiko cp .env.example .env编辑.env至少设置OPENAI_API_KEY— OpenAI key路由引擎使用并注入 AgentADMIN_PASSWORD— 引导管理员账号的密码.env.example 本身就是带完整注释的配置手册按Required / Optional / Credential三级组织必填项如SECRETS_ENCRYPTION_KEYAES-256-GCM 密钥openssl rand -base64 32生成、JWT_SECRET、S3 凭证须与 compose 中的rustfs服务完全一致nasiko/nasiko123/us-east-1/ bucketnasiko可选项如AGENT_JWT_SECRETLLM Router 短期令牌签名密钥、COMPOSIO_API_KEY、SEED_AGENTS、可观测性端点等。2. 启动平台docker compose up -d这会构建 server 镜像并启动完整栈Postgres · Redis · RustFS (S3) · OTel Collector · Tempo · Loki · nasiko-server。首次构建需数分钟Docker 内编译 Rust后续构建很快打开http://localhost:8080进入 Dashboard用ADMIN_USERNAME/ADMIN_PASSWORD登录默认admin/changeme。日常运维命令docker compose logs -f server # 跟踪服务端日志 docker compose down # 停止全部 docker compose up -d --build # 拉取新变更后重建六、按操作系统的部署指南两条受支持路径路径依赖适用对象A. Docker-only仅 Docker只想跑平台的任何人B. Source / RustRust just贡献者、开发者、热重载Path A — Docker-only分系统要点Windows安装 Docker Desktop 并等待引擎就绪然后在 PowerShell/Git Bash 中Copy-Item .env.example .env编辑后docker compose up -d打开 http://localhost:8080 登录。macOS安装 Docker Desktop for Maccp .env.example .env后同上。host.docker.internal在 Docker DesktopmacOS/Windows上默认可解析Agent 无需额外设置即可到达 MCP 网关。Linux安装 Docker 引擎 Compose 插件将用户加入docker组sudo usermod -aG docker $USER newgrp docker后执行标准步骤。注意原生 Docker不提供host.docker.internal——若 Agent 报[Errno -2] Name or service not known需用--add-host host.docker.internal:host-gateway启动 Docker或把MCP_GATEWAY_PUBLIC_URL设为网桥 IP。工具链安装CLI / Path B 用Windowswinget install --id Rustlang.Rustup -e安装 Rust随后cargo install just cargo-watch如需构建原生 Windows 二进制MSVC 工具链接ring等 crate 失败时再装 VS C Build Tools——仅构建 CLI 并不需要 C Build Tools走的是纯 Rust 工具链。macOSxcode-select --installC 工具链/链接器→ rustup 安装脚本 →cargo install just cargo-watch。Linux (Debian/Ubuntu)sudo apt install -y build-essential pkg-config libssl-dev→ rustup →cargo install just cargo-watch。装完统一验证rustc --version cargo --version just --version docker --version docker compose versionPath B — 开发者 / Rust 路径依赖 Rustrustup、justcargo install just与 Docker。# 1. 只启动基础设施Postgres, Redis, RustFS, OTel 栈 just infra # 2. 配置服务端环境变量 cp server/.env.example server/.env # 编辑 server/.env - 至少设置 OPENAI_API_KEY # 3. 原生运行服务端热重载 just dev # ...或不带热重载 just run服务端运行在 http://localhost:8080just dev依赖 cargo-watch仓库内通过cargo watch -x run -p nasiko-server --bin nasiko-server实现见 justfile 第 50–54 行改动即自动重建。常用开发命令与 justfile 逐条对应just check # cargo check --workspace just clippy # lint零警告策略 just test-unit # 快速、无外部依赖的单元测试无需基础设施 just test # 单元 集成测试先运行 just infrajust test实际拆为两阶段test-unit覆盖nasiko-auth、nasiko-secrets、nasiko-config等 11 个 crate 的单元测试test-server以--test-threads1串行运行服务端集成测试。从源码构建二进制cargo build --release -p nasiko # CLI 二进制 cargo build --release -p nasiko-server # 服务端二进制七、CLI — 安装与使用CLI 需要从源码构建独立的cli/crate构建/部署 Agent 镜像还需要 Docker。安装# 从仓库根目录 cargo install --path cli/ # ...或构建独立二进制 cargo build --release -p nasiko确保在PATH中Cargo 的bin目录~/.cargo/bin。部署你的第一个 Agentnasiko connect http://localhost:8080 nasiko auth login # 用 ADMIN_USERNAME / ADMIN_PASSWORD 登录 nasiko new openai my-agent cd my-agent # 从模板脚手架 nasiko deploy . # 构建、推送、部署 nasiko chat Hello there # 与 Agent 对话消息须含空格 # 或用 --agentnasiko chat --agent my-agent Hello除 CLI 外也可以在 Dashboard 上直接部署 Agent——上传源码、从 GitHub 导入或从制品 registry 拉取。常用 CLI 命令命令说明nasiko connect url注册并切换到某个控制平面nasiko auth login向当前集群认证nasiko new [template] [name]脚手架一个新 Agent 工程nasiko build/nasiko run构建 Agent 镜像 / 构建 本地运行nasiko push/nasiko deploy image推送镜像 / 构建-推送-部署到集群nasiko upload [source]上传源码由服务端构建本地无需 Dockernasiko ps列出运行中的 Agentnasiko logs agent -f流式跟踪 Agent 日志nasiko stop/start/restart/scale nAgent 生命周期nasiko rm --name agent终止并注销 Agent位置参数id仅接受 UUIDnasiko chat agent交互式或一次性 A2A 对话nasiko secrets set配置加密的每 Agent 密钥nasiko mcp管理 MCP Gateway 连接器与工具权限nasiko observe可观测性会话、trace、span、统计、FinOpsnasiko maf多 Agent 流工作流创建/运行/查看nasiko registry浏览制品 registrynasiko githubGitHub 集成status/repos/connect/disconnect/clonenasiko --help可按工作流顺序查看完整命令列表。八、Coding Agents 与 LLM RouterNasiko 可以管理已安装在本机的编码 Agent CLI——记录其行为、代理其 LLM 调用或两者都做两者是相互独立的开关。支持Claude Code、Codex、Cursor CLI、OpenCode。会话上报Session reportingnasiko agents discover # 每个 Agent 的 DETECTED / CONNECTED / VERSION / CONFIG nasiko agents install agent # 安装会话上报 hook nasiko agents uninstall agent nasiko agents sync # 将排队的会话轮次事件刷到控制平面nasiko connect/nasiko use/nasiko auth login也会自动触发安装但仅针对尚无安装记录的 Agent——绝不会把已安装的 Agent 静默重绑到新集群重绑须显式nasiko agents install agent。每个 Agent 会获得一个 Stop/session-idle hook。已完成的轮次先本地排队于~/.nasiko/integrations/queue/再投递到POST /telemetry/coding-agent/events/batch因此控制平面短暂不可达不丢数据永久失败的投递如集群被删除/改名后落入~/.nasiko/integrations/rejected/可安全删除。摄入的轮次立即可作为聊天会话查看nasiko sessions、nasiko history id。Trace、token 数与成本还依赖CODING_AGENT_OTLP_ENDPOINT见下文。对应的服务端实现位于 server/src/coding_agent_telemetry.rs 与 server/src/coding_agent_otlp.rs持久化模式见 migrations/0017_coding_agent_telemetry_events.sql。把 LLM 调用路由到 Nasikonasiko connect claude --config llm-config-name nasiko connect codex --config llm-config-name nasiko connect opencode --config llm-config-name nasiko disconnect agent # 回滚 settings/plugin 变更 nasiko status agent # 查看当前绑定connect claude/connect codex把 Agent 的apiKeyHelper与*_BASE_URL指向 Nasiko于是每个请求通过POST /api/agents/{id}/llm-token铸造一个短期 JWT。Claude Code 将该凭证放在x-api-key头而非Authorization路由两者都接受。connect opencode则安装一个 JS 插件~/.config/opencode/plugins/nasiko-llm-router.js注册nasikoprovider 并将nasiko/router设为新OpenCode 会话的默认模型——OpenCode 在会话创建时就把模型固定在自己的数据库里所以恢复旧会话不会走路由需开新会话或显式选择 Nasiko Router。入站协议与出站 provider 完全解耦nasiko connect claude --config my-openai-config即可把 Claude Code 的 Anthropic 格式流量路由到 OpenAI。这一双向翻译能力在 llm-router/src/inbound/anthropic/openai/gemini 各一个解析器与 llm-router/src/providers/openai/anthropic/gemini/openrouter 出站实现中成对实现。~/.claude/settings.json与 OpenCode 配置是每用户、全局的文件。连接某个 Agent 会影响本机上所有 Claude Code / OpenCode 进程而不只是当前项目。LLM 配置管理nasiko llm-config create --name name --provider provider --model model nasiko llm-config list nasiko llm-config update name [--provider ...] [--model ...] nasiko llm-config set-default name nasiko llm-config attach name --agent agent # 挂接到已部署 Agent nasiko llm-config detach --agent agent nasiko llm-config get agent # 查看某 Agent 解析后的路由配置 nasiko llm-config providers # 合法 provider/model 取值 定价配置中的model字段是路由生效的必需项——未设置时list显示provider/?。相关服务端配置变量作用AGENT_JWT_SECRET为每请求的短期路由 JWT 签名。留空 ⇒ 每个路由请求被 401 拒绝fail-closedCODING_AGENT_OTLP_ENDPOINT遥测 outbox worker 的 OTLP/HTTP JSON 基址服务端自动追加/v1/traces与/v1/logs。未设置则摄入回执保持 pending、不启动 workercoding-agent trace 到不了 Tempo/Loki九、环境变量总览一切配置经单一Config结构体由环境变量驱动config/src/lib.rs约 500 行缺失的必需键在启动时快速失败。通过docker compose运行时基础设施 URLDATABASE_URL、REDIS_URL、S3_ENDPOINT、OTel/Tempo/Loki、Agent 网络由 docker-compose.yml 自动设置。全部变量及说明见 .env.example。变量用途默认值OPENAI_API_KEY路由 Agent 的 LLM provider可选sk-...SECRETS_ENCRYPTION_KEYBase64 32 字节 AES-256-GCM 密钥必填ADMIN_USERNAME/ADMIN_PASSWORD引导管理员账号admin/changemeJWT_SECRETJWT 签名密钥必填S3_BUCKET/S3_ACCESS_KEY/S3_SECRET_KEY/S3_REGIONOCI registry 的 S3 存储由 compose 设置AGENT_RUNTIME容器运行时OSS 中为dockerdockerDATABASE_URL/REDIS_URL/S3_ENDPOINT基础设施连接由 compose 设置COMPOSIO_API_KEYComposio 平台MCP 工具集可选SEED_TOOLKITS启动时自动注册的 Composio 工具集可选MCP_GATEWAY_PUBLIC_URL注入 Agent 的 MCP 网关公网 URL由 compose 设置SEED_AGENTS启动时自动部署的空格分隔镜像列表可选AGENT_JWT_SECRET为 coding-agent LLM-router 请求令牌签名nasiko connect必填CODING_AGENT_OTLP_ENDPOINTcoding-agent 遥测 outbox 的 OTLP/HTTP JSON 端点未设置worker 禁用ROUTER_MODEL/EMBEDDING_MODEL路由引擎模型见config/NASIKO_FLOW_MAX_DEPTH/NASIKO_FLOW_MAX_FAN_OUT/NASIKO_FLOW_MAX_TOKENSFlow-guard 级联限制见config/源码中这些键如何被解析可直接在 config/src/lib.rs 查证例如flow_max_depth、flow_max_fan_out、flow_max_tokens为 FlowGuard 的级联上限embedding_model默认text-embedding-3-smallopenai_api_key未设置时跳过 Stage 1 向量初筛mcp_gateway_public_url未设置时部署期不注入 MCP 环境变量。十、项目结构server/ 控制平面Axum 路由、认证、Agent 代理、构建 worker、内嵌 UI orchestrator/ 路由引擎语义化 Agent 选择初筛、重排、选择 mcp-gateway/ MCP 网关连接器、工具聚合、每 Agent 权限、OAuth llm-router/ provider 无关的 OpenAI 兼容出站代理Agent LLM 调用 runtime/ ContainerRuntime trait DockerRuntimebollard auth/ AuthService trait OSS 实现JWT 登录、RBAC 钩子 flow/ FlowGuard反 DoS 级联限制 实时流事件 secrets/ Agent 密钥静态 AES-256-GCM 加密 oci/ 内嵌 OCI Distribution v2 registryS3 支撑、层去重 observability/ OTel 初始化、Tempo/Loki 客户端、DB 模型定价 agent-proxy/ Agent ID - 运行容器端点解析 github/ GitHub OAuth 源码部署的仓库导入 types/ A2A 协议 registry 类型 config/ 单一环境变量驱动 Config 结构体 utils/ 共享工具 cli/ nasiko 二进制Agent 开发者 CLIureq 同步 HTTP agents/ 示例与 seed Agent各自独立 A2A 容器 migrations/ Postgres 迁移sqlx启动时自动执行 ui/ 前端vanilla JS web components内嵌于服务端二进制 docs/ 设计文档架构、协议、约定十一、故障排查一条命令快速修复问题一条命令CLI 编译失败link.exe not found/cc not foundWindows走 Docker-only 路径或winget install Microsoft.VisualStudio.2022.BuildTools --override --wait --quiet --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended后重开终端CLI 编译失败dlltool ... Invalid bfd targetwinget install MSYS2.MSYS2并把C:\msys64\mingw64\bin放到C:\MinGW之前或改用 MSVCsource .env时报: command not foundsed -i s/\r$// server/.env启动报invalid SECRETS_ENCRYPTION_KEYsed -i.bak s/^SECRETS_ENCRYPTION_KEY.*/SECRETS_ENCRYPTION_KEY$(openssl rand -base64 32)/ .env端口 9000/4317/4318address already in use停掉 Docker DesktopWindows 下wsl --shutdown再docker compose up -dDocker socketpermission deniedsudo usermod -aG docker $USER newgrp dockerWSLext4.vhdx: path not foundwsl --unregister Ubuntu wsl --install -d UbuntuAgent 上传后500 agents_owner_id_fkey登出重登或docker compose down -v docker compose up -d后重新登录服务端连不上 Postgresdocker compose up -d并等待healthyAgentName or service not knownLinux Docker用--add-host host.docker.internal:host-gateway重建启动时SEED_TOOLKITS is set but COMPOSIO_API_KEY is not预期且无害——.env.example中SEED_TOOLKITS默认启用设COMPOSIO_API_KEY才能真正注册或注释掉SEED_TOOLKITS消音分系统要点Windowslink.exe not found/linker cc not found未装 MSVC C Build Tools可走 Docker-only 路径或安装带 Desktop development with C 工作负载的 VS Build Toolsdlltool ... Invalid bfd target坏掉的 32 位 MinGW 无法构建 64 位装 MSYS2 或切 MSVCCRLF 破坏 bashsourcesed -i s/\r$// server/.envinvalid SECRETS_ENCRYPTION_KEY ... Invalid paddingopenssl rand -base64 32重新生成双 Docker 引擎冲突保留一个wsl --shutdown后重启WSL 内 Docker socket 权限sudo usermod -aG docker $USERagents_owner_id_fkey500旧库的陈旧登录 token登出重登或docker compose down -v后全新登录。macOSlinker cc not found→xcode-select --installpermission denied ... Docker daemon→ 启动 Docker Desktop 并等待引擎就绪端口占用 →lsof -i :9000定位占用进程。LinuxDocker socket 权限 →sudo usermod -aG docker $USER后重新登录或newgrp docker构建 CLI 缺工具链 →sudo apt install -y build-essential pkg-config libssl-devAgent[Errno -2]→ 原生 Docker 不提供host.docker.internal按 Path A 的 Linux 注记处理或把MCP_GATEWAY_PUBLIC_URL设为网桥 IP首次cargo构建极慢属正常整 workspace 编译建议本地盘克隆而非挂载/9p 文件系统。全平台启动时failed to connect to Postgres→ 基础设施未就绪docker compose up -d或just infra后等 healthydocker: command not found→ 安装/启动 DockerDashboard 加载不出 → 确认docker compose ps中server为Up再打开 http://localhost:8080。十二、延伸阅读与许可设计文档集中在 docs/A2A_PROTOCOL.md协议与错误码、A2A_REGISTRY_DESIGN.md、AGENT_LIFECYCLE.md、MCP_GATEWAY_DESIGN.md、CLI_DESIGN.md、BOOTSTRAP_AND_NETWORKING.md、CONTROL_PLANE_UI.md、ORGANIZATION.md 等贡献流程本地环境、代码规范、PR 流程见 CONTRIBUTING.md其中同样声明了A2A-Version: 1.0请求头为必需项许可Apache-2.0见 LICENSE。赞分享【免费下载链接】nasikoDeveloper Control Plane for your AI Agents项目地址https://gitcode.com/gh_mirrors/na/nasiko点击查看免费下载相关推荐Dify 开源自托管部署与核心功能全景从 Docker Compose 快速上手到源码级架构解析Dify 开源自托管部署与核心功能全景从 Docker Compose 快速上手到源码级架构解析 本文以 Dify 仓库官方繁体中文 README 为骨架完人工智能大模型LLMOpsAI 应用RAGAI Agent低代码Crossplane 云原生控制平面项目全景、源码架构与版本演进解读Crossplane 云原生控制平面项目全景、源码架构与版本演进解读 Crossplane 是一个无需编写代码即可构建云原生控制平面的开源框架也是 CNCF云原生后端PyCaret 4.0 自托管 ML 平台快速上手Docker Compose 部署、控制平面架构与端到端训练部署实战PyCaret 4.0 自托管 ML 平台快速上手Docker Compose 部署、控制平面架构与端到端训练部署实战 PyCaret 4.0 是一个开源的、上一篇ParlAI 预训练 Transformer 模型库实战从 ConvAI2 实时对话到多任务微调下一篇终极黑苹果实战指南7个专业步骤在普通PC上完美运行macOS系统创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考