Phase 6: 部署文档 + 启动脚本 + 配置样例

- 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>

scripts/dev.sh

@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+# One-command build + start + health check for spark-mcp-go.
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+
+# Load .env if present
+if [ -f .env ]; then
+    set -a
+    # shellcheck source=/dev/null
+    . ./.env
+    set +a
+fi
+
+# Required tokens
+: "${ADMIN_TOKENS:?ADMIN_TOKENS is required}"
+: "${AGENT_TOKEN:?AGENT_TOKEN is required}"
+
+LISTEN_ADDR="${LISTEN_ADDR:-:8080}"
+PORT="${LISTEN_ADDR##*:}"
+PID_FILE="./data/spark-mcp.pid"
+
+echo ">> go build"
+go build -o ./spark-mcp-go .
+
+mkdir -p ./data/logs/tools
+
+echo ">> starting server on port ${PORT}"
+nohup ./spark-mcp-go > ./data/logs/spark-mcp.log 2>&1 &
+PID=$!
+echo "${PID}" > "${PID_FILE}"
+
+sleep 2
+
+echo ">> health check"
+if curl -sS "http://127.0.0.1:${PORT}/healthz"; then
+    echo
+    echo ">> running, PID=${PID}, log=./data/logs/spark-mcp.log"
+else
+    echo
+    echo ">> health check failed; see ./data/logs/spark-mcp.log"
+    kill "${PID}" 2>/dev/null || true
+    rm -f "${PID_FILE}"
+    exit 1
+fi

scripts/seed.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+# Admin POST to create a sample cluster.
+# Usage: ./scripts/seed.sh [cluster_id] [rm_url] [shs_url] [spark_submit_bin]
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+
+# Load .env if present
+if [ -f .env ]; then
+    set -a
+    # shellcheck source=/dev/null
+    . ./.env
+    set +a
+fi
+
+: "${ADMIN_TOKENS:?ADMIN_TOKENS is required}"
+
+HOST="${ADMIN_HOST:-http://127.0.0.1:8080}"
+TOKEN="${ADMIN_TOKENS%%,*}"
+AUTH="Authorization: Bearer ${TOKEN}"
+
+CLUSTER_ID="${1:-prod}"
+RM_URL="${2:-http://rm.example.com:8088}"
+SHS_URL="${3:-http://shs.example.com:18080}"
+SPARK_BIN="${4:-/opt/spark/bin/spark-submit}"
+
+echo ">> creating cluster '${CLUSTER_ID}' via ${HOST}/admin/clusters"
+
+curl -sS -X POST -H "${AUTH}" -H "Content-Type: application/json" \
+    -d "{\"id\":\"${CLUSTER_ID}\",\"name\":\"${CLUSTER_ID}\",\"rm_url\":\"${RM_URL}\",\"shs_url\":\"${SHS_URL}\",\"spark_submit_execute_bin\":\"${SPARK_BIN}\",\"is_active\":true,\"auth_type\":\"simple\",\"auth_username\":\"yarn\",\"rate_limit_per_min\":10,\"url_allowlist\":[\"${RM_URL#*://}\",\"${SHS_URL#*://}\"]}" \
+    "${HOST}/admin/clusters"
+
+echo