tao.chenandClaude
d6dd2b846f
- README.md (英文): 项目概览 + 11 Tool 表格 + 12 env 变量全表 + 6 admin 端点 + 安全模型 (3 道防线 + 4 项额外保证) + dev 命令 - .env.example: 12 env 变量 + 默认值 + 必填标注 - scripts/dev.sh: 一键 build + 后台启动 (nohup + PID 文件) + healthz 验证 - scripts/seed.sh: admin POST 一个示例 cluster (从 .env 读 admin token) - ARCHITECTURE.md (中文): 包依赖图 + 数据流 + 11 Tool 分类 + 关键设计决策 - docs/runbook.md (中文): 部署 + 升级 + 故障排查 (401/404/422 等) - docs/systemd/spark-mcp-go.service: systemd unit 模板 README 安全模型小修正: 第 3 道防线从"spark_submit flag 白名单" (实际不存在) 改为 "upload_file 路径白名单", 加 Additional guarantees 小节列 slice form / json:"-" / 跨主机 redirect / per-tool log 权限。 Co-Authored-By: Claude <noreply@anthropic.com>
2.6 KiB
2.6 KiB
spark-mcp-go 架构说明
包依赖图
main
├─ config
├─ logging
├─ storage (SQLite)
├─ admin
│ └─ storage / cluster / audit
├─ mcp
│ ├─ tools
│ │ ├─ rm
│ │ ├─ httpclient
│ │ ├─ analyzer
│ │ └─ storage / cluster
│ └─ server (mark3labs/mcp-go)
└─ middleware
admin只依赖storage、cluster、audit、middleware。tools依赖rm（ResourceManager 客户端）、httpclient（通用 HTTP 原语）、analyzer（日志分析）。mcp聚合所有 Tools，注册到mark3labs/mcp-go的 Streamable HTTP server。main负责加载配置、打开数据库、挂载路由、启动 HTTP 服务。
数据流
- 管理员调用
/admin/clustersPOST，写入 cluster JSON。 storage把 cluster 持久化到 SQLite（后续会对敏感字段加密）。- LLM Agent 调用
/mcpTool（如list_clusters）。 - Tool 从 storage 读取 cluster，携带 auth 信息，通过
httpclient或本地spark-submit调用 YARN/Spark。 - 结果返回给 LLM；每次 Tool 调用同时写入独立审计日志。
11 Tools 分类
| 分类 | Tools |
|---|---|
| discovery | list_clusters |
| exec | spark_submit |
| RM | list_applications, get_application_status, get_application_logs, kill_application, fetch_cluster_env |
| SHS | fetch_spark_metrics |
| analyzer | analyze_spark_log |
| 原语 | fetch_url, upload_file |
关键设计决策
- slice-form
spark_submit：参数以字符串数组传入，避免 shell 拼接和注入。 - cluster
url_allowlist：所有外发 HTTP（fetch_url、RM、SHS）必须匹配 allowlist，防止 SSRF。 - 日志降级链：
get_application_logs依次尝试amContainerLogs、aggregated-logs、通用 logs 端点。 - 多 token admin：
ADMIN_TOKENS支持逗号分隔多管理员 token，便于轮换。 - per-tool 独立审计日志：每个 Tool 每次调用写入
${LOG_DIR}/tools/<tool>.log，文件权限0600。 auth_password不可通过 JSON 创建：字段带json:"-"tag，避免接口泄露密码；生产通过专用端点或数据库初始化写入。
安全模型（三道防线）
- Token 鉴权：
ADMIN_TOKENS保护管理面，AGENT_TOKEN保护 MCP 面。 - SSRF 防护：
fetch_url与所有集群请求都走 cluster allowlist，且内置 DNS rebinding 检查。 - 路径/参数白名单：
spark_submit仅允许 jar、class、--conf 等安全参数；禁止 shell 元字符与重定向。
运行与部署
详见 docs/runbook.md。