AI导哈

代理编排平台

Maple是一个多表面平台，用于代理编排、可观察性和安全防护。

  • by MianMMajid
  • JavaScript
  • 本地部署
  • 更新于
在 GitHub 查看 MianMMajid/MCp-Use

使用说明

枫树

Maple是一个用于代理编排、可观察性和保护的多面平台。

地表所有权（A/B/C）

  • frontendB-desktop-app （Catalyst）：编排控制平面。
  • frontendA-it-console （协议）：可观察性、审计、合规性、保障措施。
  • frontendC-marketing-download-site （突出）：营销、入职培训、下载CTA。

主动服务拓扑

活动运行时服务：

  • gateway-api
  • admin-console-api
  • context-wall
  • mcp-proxy
  • tool-runner
  • cyber-proxy
  • audit-writer
  • business-api

已存档的退休服务：

  • backend/legacy/retired-services/model-router
  • backend/legacy/retired-services/secrets-broker

先决条件

  • Node.js 22+ (nvm use 读取 .nvmrc 自动）
  • 码头工人 （适用于本地PostgreSQL 16和Redis 7——自动配置）
  • npm 8+ （搭载Node 22的船只）
  • 版本控制系统 （用于脚本中的repo根检测）

可选：

  • OpenClaw命令行界面 --只需要与 npm run dev:fast:openclaw

快速开始

npm install
npm run dev

这个命令：

  1. 运行飞行前检查（配置、TLS证书、合同）
  2. 构建所有8个后端服务
  3. 通过Docker启动PostgreSQL和Redis（自动配置）
  4. 生成本地TLS证书
  5. 推出全服务网格+3个前端开发服务器
  6. 等待所有服务准备就绪（首次运行约2-3分钟）

快速本地环路(npm run dev)启动本地依赖关系以及网关、核心服务和A/B/C表面。

默认本地URL:

  • http://127.0.0.1:3000 （网关api）
  • http://127.0.0.1:4101 （前端A）
  • http://127.0.0.1:4102 （前端B）
  • http://127.0.0.1:4103 （前端C）

停止快速循环过程：

npm run local:down

三环发展模式

1） 快速本地循环（每日编码）

npm run dev
npm run dev:fast
npm run dev:fast:openclaw

dev:fast:openclaw 启用OpenClaw配置文件验证和启动帮助程序。

2） K8s验证循环（集成现实主义）

npm run validate:k8s
npm run validate:k8s -- --full

验证工件：

  • artifacts/matrix/k8s-validation-summary.json
  • artifacts/matrix/k8s-service-utilization-summary.json

3） K8s释放门（合并/切换前需要）

npm run gate:k8s

释放门工件：

  • artifacts/matrix/k8s-release-gate-summary.json

矩阵、守卫和CI

在本地运行完整矩阵：

npm run test:matrix
# equivalent: bash scripts/run-full-matrix.sh --all

主要警卫：

npm run check:repo-hygiene
npm run check:command-surface
npm run check:no-legacy-modifier-endpoints
npm run check:service-topology-parity

分支保护要求检查：

  • backend-checks
  • frontend-tests
  • k8s-release-gate

直播提供商政策

政策是有条件严格的：

  • 如果存在所需的秘密，则运行实时提供者矩阵并打开。
  • 如果缺少秘密，矩阵将写入 artifacts/matrix/live-suite-skip.json 并继续（除非启用强制直播）。
  • PR标签 requires-live 在CI中强制严格的直播行为。

服务审核命令

npm run service:audit:inventory
npm run service:audit:callgraph
npm run service:audit:report
npm run check:service-route-coverage
npm run check:service-necessity
npm run check:service-utilization

审计产出：

  • artifacts/service-audit/service-inventory.json
  • artifacts/service-audit/static-callgraph.json
  • artifacts/service-audit/utilization-report.json
  • artifacts/service-audit/utilization-report.md

技术债务评估

bash scripts/run-flake-repetition.sh --iterations 5 --all
bash scripts/run-stateful-suite-loops.sh --iterations 20
node scripts/profile-build-test-hotspots.mjs
node scripts/dependency-security-pass.mjs
node scripts/check-docs-architecture-drift.mjs
node scripts/check-debt-slos.mjs
node scripts/build-debt-register-report.mjs

债务文物：

  • artifacts/debt/dependency-security-report.json
  • artifacts/debt/docs-architecture-drift.json
  • artifacts/debt/debt-slo-status.json
  • artifacts/debt/debt-register-report.json
  • artifacts/matrix/flake-repetition-summary.json
  • artifacts/matrix/stateful-suite-loop-summary.json
  • artifacts/matrix/build-test-hotspots.json

依赖/安全门策略：

  • 活动工作区中的高/关键漏洞是合并阻止。
  • 临时例外情况必须在 docs/dependency-security-allowlist.json 所有者+到期。

部署

铁路

多业务调度入口点：

  • backend/backendA-platform-infra/deploy/railway-entrypoint.sh

铁路拓扑通过以下方式对网格和K8s进行奇偶校验：

  • npm run check:service-topology-parity

北侧

  • backend/backendA-platform-infra/deploy/northflank/template.backend-mesh.json
  • backend/backendA-platform-infra/deploy/northflank/README.md

故障排除

问题 修复
npm run dev 挂起“等待postgres” 确保Docker正在运行： docker info
端口5432或6379已在使用中 停止现有容器： docker rm -f maple-dev-postgres maple-dev-redis
Node.js版本不匹配 安装正确的版本： nvm install && nvm use
启动时服务崩溃 检查日志： tail -f .maple/dev-fast/logs/<service>.log
TLS证书错误 强制重新生成： MAPLE_FORCE_CERT_REGEN=1 npm run dev
碰撞后的失效流程 清理： npm run local:down 然后 npm run dev

附加文档

  • docs/repo-topology.md
  • docs/backend-state-retry-walkthrough.md
  • docs/command-surface.md
  • docs/release-readiness-checklist.md
  • docs/lockfile-policy.md

相关 MCP