zdh
5167d9e36e
Deploy Wiki to Production / deploy (push) Has been cancelled
覆盖 27 个此前缺少返回链接的报告页和独立页面（共 50 个 HTML 页，index.html 首页除外） - 标准报告页：header/header-bar 内插入 back-link - 特殊页面：深国际、中医馆、YqBoot、交互式演示等单独适配 - 统一文案「← 返回知识库」，URL 按目录深度自动推算
1143 lines
56 KiB
HTML
1143 lines
56 KiB
HTML
<!DOCTYPE html>
|
||
<html lang="zh-CN">
|
||
<head>
|
||
<meta charset="UTF-8">
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||
<title>Spring AI Alibaba 全功能部署指南 — 本地内网环境</title>
|
||
<style>
|
||
:root {
|
||
--color-primary: #1677FF; --color-primary-hover: #4096FF; --color-primary-active: #0958D9; --color-primary-bg: #E6F4FF;
|
||
--color-success: #52C41A; --color-success-bg: #F6FFED; --color-success-border: #B7EB8F;
|
||
--color-warning: #FAAD14; --color-warning-bg: #FFFBE6; --color-warning-border: #FFE58F;
|
||
--color-error: #FF4D4F; --color-error-bg: #FFF2F0; --color-error-border: #FFCCC7;
|
||
--bg: #F5F5F5; --bg-container: #FFFFFF; --bg-elevated: #FAFAFA;
|
||
--border: #D9D9D9; --border-light: #F0F0F0;
|
||
--text-primary: #141414; --text-secondary: #595959; --text-tertiary: #8C8C8C;
|
||
--radius-sm: 6px; --radius-md: 8px; --radius-lg: 12px;
|
||
--shadow-sm: 0 1px 2px rgba(0,0,0,0.03), 0 1px 6px -1px rgba(0,0,0,0.02);
|
||
--shadow-md: 0 2px 4px rgba(0,0,0,0.04), 0 4px 12px -2px rgba(0,0,0,0.04);
|
||
--shadow-lg: 0 4px 8px rgba(0,0,0,0.06), 0 8px 24px -4px rgba(0,0,0,0.08);
|
||
--sidebar-w: 260px; --header-h: 64px;
|
||
}
|
||
*{margin:0;padding:0;box-sizing:border-box;}
|
||
body{font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,'PingFang SC','Hiragino Sans GB','Microsoft YaHei',sans-serif;background:var(--bg);color:var(--text-primary);line-height:1.57;font-size:14px;}
|
||
::-webkit-scrollbar{width:6px;height:6px;}
|
||
::-webkit-scrollbar-track{background:transparent;}
|
||
::-webkit-scrollbar-thumb{background:var(--border);border-radius:3px;}
|
||
|
||
.header{position:fixed;top:0;left:0;right:0;height:var(--header-h);background:rgba(255,255,255,0.88);backdrop-filter:blur(12px);border-bottom:1px solid var(--border-light);display:flex;align-items:center;padding:0 2rem;z-index:100;}
|
||
.header h1{font-size:18px;font-weight:700;background:linear-gradient(135deg,var(--color-primary),#722ED1);-webkit-background-clip:text;background-clip:text;-webkit-text-fill-color:transparent;color:transparent;}
|
||
.header .back-link{margin-right:16px;font-size:13px;color:var(--color-primary);text-decoration:none;flex-shrink:0;}
|
||
.header .back-link:hover{text-decoration:underline;}
|
||
.header .version{margin-left:auto;font-size:12px;color:var(--text-tertiary);font-family:'SF Mono',Monaco,monospace;}
|
||
|
||
.menu-btn{display:none;width:40px;height:40px;border:none;background:none;cursor:pointer;border-radius:var(--radius-sm);font-size:20px;margin-right:12px;flex-shrink:0;}
|
||
.menu-btn:hover{background:var(--bg-elevated);}
|
||
.drawer-overlay{display:none;position:fixed;inset:0;background:rgba(0,0,0,0.5);z-index:200;opacity:0;transition:opacity .25s;}
|
||
.drawer-overlay.show{display:block;opacity:1;}
|
||
|
||
.sidebar{position:fixed;top:var(--header-h);left:0;bottom:0;width:var(--sidebar-w);background:var(--bg-container);border-right:1px solid var(--border);overflow-y:auto;padding:1.25rem 0;z-index:90;}
|
||
.sidebar .toc-label{font-size:11px;text-transform:uppercase;letter-spacing:.1em;color:var(--text-tertiary);padding:0 1.25rem;margin-bottom:.75rem;font-weight:600;}
|
||
.sidebar .toc-part{font-size:12px;font-weight:700;color:var(--color-primary);padding:.6rem 1.25rem .2rem;margin-top:.4rem;}
|
||
.sidebar nav ol{list-style:none;counter-reset:toc;}
|
||
.sidebar nav li{counter-increment:toc;}
|
||
.sidebar nav a{display:block;padding:.4rem 1.25rem;color:var(--text-secondary);text-decoration:none;font-size:12px;line-height:1.4;border-left:2px solid transparent;transition:all .15s;}
|
||
.sidebar nav a:hover,.sidebar nav a.active{color:var(--color-primary);background:var(--color-primary-bg);}
|
||
.sidebar nav a.active{border-left-color:var(--color-primary);font-weight:600;}
|
||
|
||
.main{margin-left:var(--sidebar-w);margin-top:var(--header-h);padding:32px 40px 64px;min-height:calc(100vh - var(--header-h));max-width:1100px;}
|
||
section{margin:48px 0;scroll-margin-top:calc(var(--header-h) + 1rem);}
|
||
section h2{font-size:24px;line-height:32px;padding-bottom:8px;border-bottom:1px solid var(--border);margin-bottom:20px;color:var(--color-primary);}
|
||
section h3{font-size:20px;line-height:28px;margin:24px 0 12px;color:#722ED1;}
|
||
section h4{font-size:16px;line-height:24px;margin:16px 0 8px;color:var(--color-success);}
|
||
p{color:var(--text-secondary);font-size:14px;margin:10px 0;text-align:justify;}
|
||
|
||
blockquote{background:var(--color-primary-bg);border-left:4px solid var(--color-primary);margin:16px 0;padding:12px 20px;border-radius:0 var(--radius-sm) var(--radius-sm) 0;}
|
||
blockquote p{text-indent:0;color:var(--text-primary);font-size:14px;}
|
||
strong{color:var(--text-primary);}
|
||
|
||
.box{border-radius:var(--radius-md);padding:20px 24px;margin:18px 0;}
|
||
.box-info{background:var(--color-primary-bg);border:1px solid #91CAFF;}
|
||
.box-idea{background:#F9F0FF;border:1px solid #D3ADF7;}
|
||
.box-good{background:var(--color-success-bg);border:1px solid var(--color-success-border);}
|
||
.box-warn{background:var(--color-warning-bg);border:1px solid var(--color-warning-border);}
|
||
.box-danger{background:var(--color-error-bg);border:1px solid var(--color-error-border);}
|
||
.box h4{margin:0 0 8px;font-size:14px;font-weight:700;}
|
||
.box-info h4{color:var(--color-primary);}.box-idea h4{color:#722ED1;}.box-good h4{color:var(--color-success);}.box-warn h4{color:var(--color-warning);}.box-danger h4{color:var(--color-error);}
|
||
.box p{font-size:14px;margin:4px 0;text-indent:0;}
|
||
|
||
.table-wrap{overflow-x:auto;margin:20px 0;}
|
||
.table-caption{font-size:13px;font-weight:700;color:var(--text-primary);margin-bottom:8px;}
|
||
table{width:100%;border-collapse:collapse;font-size:13px;}
|
||
th,td{padding:10px 14px;border:1px solid var(--border);text-align:left;vertical-align:top;}
|
||
th{background:var(--bg-elevated);font-weight:700;color:var(--text-primary);white-space:nowrap;}
|
||
td{background:var(--bg-container);color:var(--text-secondary);}
|
||
tbody tr:hover td{background:var(--color-primary-bg);}
|
||
|
||
.tag{display:inline-block;padding:2px 10px;border-radius:12px;font-size:11px;font-weight:600;margin-right:4px;}
|
||
.tag-green{background:var(--color-success-bg);color:var(--color-success);border:1px solid var(--color-success-border);}
|
||
.tag-blue{background:var(--color-primary-bg);color:var(--color-primary);border:1px solid #91CAFF;}
|
||
.tag-warn{background:var(--color-warning-bg);color:var(--color-warning);border:1px solid var(--color-warning-border);}
|
||
.tag-red{background:var(--color-error-bg);color:var(--color-error);border:1px solid var(--color-error-border);}
|
||
.tag-purple{background:#F9F0FF;color:#722ED1;border:1px solid #D3ADF7;}
|
||
|
||
.kpi-row{display:flex;flex-wrap:wrap;gap:12px;margin:16px 0;}
|
||
.kpi{flex:1;min-width:110px;background:var(--color-primary-bg);border-radius:var(--radius-md);padding:14px 12px;text-align:center;}
|
||
.kpi .num{font-size:20px;font-weight:800;color:var(--color-primary);line-height:1.2;}
|
||
.kpi .label{font-size:10px;color:var(--text-tertiary);margin-top:4px;}
|
||
.kpi.warn{background:var(--color-warning-bg);}.kpi.warn .num{color:#D48806;}
|
||
.kpi.good{background:var(--color-success-bg);}.kpi.good .num{color:var(--color-success);}
|
||
.kpi.danger{background:var(--color-error-bg);}.kpi.danger .num{color:var(--color-error);}
|
||
.kpi.purple{background:#F9F0FF;}.kpi.purple .num{color:#722ED1;}
|
||
|
||
ul,ol{margin:8px 0 8px 20px;}
|
||
li{margin:4px 0;color:var(--text-secondary);font-size:14px;}
|
||
|
||
.pros-cons{display:grid;grid-template-columns:1fr 1fr;gap:16px;margin:12px 0;}
|
||
.pros{background:var(--color-success-bg);border:1px solid var(--color-success-border);border-radius:var(--radius-md);padding:16px 20px;}
|
||
.cons{background:var(--color-error-bg);border:1px solid var(--color-error-border);border-radius:var(--radius-md);padding:16px 20px;}
|
||
.pros h4{color:var(--color-success);margin:0 0 8px;}
|
||
.cons h4{color:var(--color-error);margin:0 0 8px;}
|
||
.pros ul,.cons ul{padding-left:18px;font-size:13px;}
|
||
.pros li,.cons li{margin-bottom:2px;}
|
||
|
||
.code-block{background:#1E1E1E;color:#D4D4D4;border-radius:var(--radius-md);padding:16px 20px;margin:12px 0;overflow-x:auto;font-family:'SF Mono',Monaco,'Cascadia Code',Consolas,monospace;font-size:12px;line-height:1.6;}
|
||
.code-block .kw{color:#569CD6;}.code-block .str{color:#CE9178;}.code-block .cm{color:#6A9955;}.code-block .fn{color:#DCDCAA;}.code-block .num{color:#B5CEA8;}
|
||
|
||
.step{display:flex;align-items:flex-start;gap:12px;margin:12px 0;padding:14px 18px;background:var(--bg-container);border:1px solid var(--border);border-radius:var(--radius-md);}
|
||
.step-num{flex-shrink:0;width:28px;height:28px;border-radius:50%;background:var(--color-primary);color:#fff;display:flex;align-items:center;justify-content:center;font-size:13px;font-weight:700;}
|
||
.step-body{flex:1;font-size:14px;color:var(--text-secondary);}
|
||
.step-body strong{display:block;color:var(--text-primary);margin-bottom:2px;}
|
||
|
||
.footer{text-align:center;padding:28px 0;color:var(--text-tertiary);font-size:13px;border-top:1px solid var(--border-light);margin-top:40px;}
|
||
|
||
.back-to-top{display:none;position:fixed;bottom:24px;right:24px;width:48px;height:48px;border-radius:50%;background:var(--color-primary);color:#fff;border:none;cursor:pointer;font-size:20px;box-shadow:var(--shadow-md);z-index:80;}
|
||
.back-to-top:hover{transform:scale(1.1);}
|
||
.back-to-top.show{display:flex;align-items:center;justify-content:center;}
|
||
|
||
@media(max-width:992px){:root{--sidebar-w:220px;}.main{padding:24px 20px 48px;}}
|
||
@media(max-width:768px){
|
||
.menu-btn{display:flex;align-items:center;justify-content:center;}
|
||
.sidebar{display:block;position:fixed;top:0;left:0;bottom:0;width:280px;max-width:85vw;transform:translateX(-100%);transition:transform .25s ease;z-index:201;padding-top:60px;}
|
||
.drawer-overlay.show ~ .sidebar,.drawer-overlay.show .sidebar,.sidebar.show{transform:translateX(0);}
|
||
.main{margin-left:0;padding:20px 16px 40px;}
|
||
.header h1{font-size:15px;}
|
||
.pros-cons{grid-template-columns:1fr;}
|
||
}
|
||
</style>
|
||
</head>
|
||
<body>
|
||
|
||
<div class="drawer-overlay" id="drawerOverlay"></div>
|
||
|
||
<header class="header">
|
||
<button class="menu-btn" id="menuBtn" aria-label="打开目录">☰</button>
|
||
<a href="../../index.html" class="back-link">← 返回知识库</a>
|
||
<h1>Spring AI Alibaba 全功能部署指南</h1>
|
||
<span class="version">V1.0 · 2026-06-05</span>
|
||
</header>
|
||
|
||
<aside class="sidebar">
|
||
<div class="toc-label">部署指南目录</div>
|
||
<nav>
|
||
<div class="toc-part">第一部分：环境准备</div>
|
||
<ol>
|
||
<li><a href="#s1">环境评估与缺口分析</a></li>
|
||
<li><a href="#s2">WSL2 环境准备</a></li>
|
||
</ol>
|
||
<div class="toc-part">第二部分：中间件部署</div>
|
||
<ol>
|
||
<li><a href="#s3">中间件总览</a></li>
|
||
<li><a href="#s4">PostgreSQL 16 安装</a></li>
|
||
<li><a href="#s5">Nacos 3.x 安装</a></li>
|
||
<li><a href="#s6">MinIO 安装</a></li>
|
||
</ol>
|
||
<div class="toc-part">第三部分：平台部署</div>
|
||
<ol>
|
||
<li><a href="#s7">项目骨架搭建</a></li>
|
||
<li><a href="#s8">核心配置详解</a></li>
|
||
<li><a href="#s9">全功能模块激活</a></li>
|
||
</ol>
|
||
<div class="toc-part">第四部分：内网与运维</div>
|
||
<ol>
|
||
<li><a href="#s10">内网访问配置</a></li>
|
||
<li><a href="#s11">运维手册</a></li>
|
||
<li><a href="#s12">故障排查</a></li>
|
||
</ol>
|
||
</nav>
|
||
</aside>
|
||
|
||
<main class="main">
|
||
|
||
<!-- ============================================================ -->
|
||
<!-- S1: 环境评估 -->
|
||
<!-- ============================================================ -->
|
||
<section id="s1">
|
||
<h2>环境评估与缺口分析</h2>
|
||
|
||
<blockquote><p>部署目标：本地 WSL2（Debian 13）内网环境，全功能 Spring AI Alibaba 平台。模型 API 走外网（阿里云百炼），中间件全部本地部署。</p></blockquote>
|
||
|
||
<div class="table-wrap">
|
||
<div class="table-caption">表：当前环境检测结果</div>
|
||
<table>
|
||
<thead><tr><th style="width:20%">检测项</th><th style="width:15%">当前值</th><th style="width:12%">状态</th><th>说明</th></tr></thead>
|
||
<tbody>
|
||
<tr><td>操作系统</td><td>Debian 13 (trixie) WSL2</td><td><span class="tag tag-green">OK</span></td><td>x86_64 架构，systemd 已启用</td></tr>
|
||
<tr><td>内存</td><td>15GB 总 / ~9.7GB 可用</td><td><span class="tag tag-green">OK</span></td><td>满足全套部署（建议 ≥8GB）</td></tr>
|
||
<tr><td>磁盘</td><td>/mnt/d 289GB 空闲</td><td><span class="tag tag-green">OK</span></td><td>建议路径 /mnt/d/wiki/ 下创建子目录</td></tr>
|
||
<tr><td>JDK</td><td>OpenJDK 21.0.11</td><td><span class="tag tag-green">OK</span></td><td>满足要求（≥17）</td></tr>
|
||
<tr><td>Maven</td><td>3.9.9</td><td><span class="tag tag-green">OK</span></td><td>满足要求（≥3.8）</td></tr>
|
||
<tr><td>Node.js</td><td>v24.15.0</td><td><span class="tag tag-green">OK</span></td><td>满足要求（≥20.12）</td></tr>
|
||
<tr><td>pnpm</td><td>已安装</td><td><span class="tag tag-green">OK</span></td><td>前端 Admin UI 构建需要</td></tr>
|
||
<tr><td>Docker</td><td><span class="tag tag-red">未安装</span></td><td><span class="tag tag-red">缺失</span></td><td>需安装 Docker 或改用原生安装方案</td></tr>
|
||
<tr><td>WSL2 网络</td><td>NAT 模式 172.18.79.x</td><td><span class="tag tag-warn">需配置</span></td><td>需端口转发或切换到 mirrored 模式</td></tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
|
||
<div class="box box-warn">
|
||
<h4>⚠️ 关键缺口</h4>
|
||
<p>1. <strong>Docker 未安装</strong> — 中间件（PostgreSQL/Nacos/MinIO）建议用 Docker 部署，也可原生安装</p>
|
||
<p>2. <strong>WSL2 NAT 网络</strong> — 默认 NAT 模式外部无法直接访问，需配置端口转发或 mirrored 模式</p>
|
||
</div>
|
||
|
||
<h3>部署架构总览</h3>
|
||
|
||
<div class="table-wrap">
|
||
<div class="table-caption">图：全功能平台部署架构（本地内网版）</div>
|
||
<table>
|
||
<thead><tr><th style="width:8%">层级</th><th style="width:16%">组件</th><th style="width:10%">端口</th><th>职责</th><th>部署方式</th></tr></thead>
|
||
<tbody>
|
||
<tr><td><strong>L5 前端</strong></td><td>Admin Studio (React)</td><td>8080</td><td>可视化编排 + 评测管理 + Agent 监控</td><td>Spring Boot 内嵌</td></tr>
|
||
<tr><td><strong>L4 应用</strong></td><td>Spring AI Alibaba</td><td>8080</td><td>Agent 框架 + Graph 引擎 + MCP/A2A</td><td>裸进程 (java -jar)</td></tr>
|
||
<tr><td><strong>L3 注册中心</strong></td><td>Nacos 3.x</td><td>8848/9848</td><td>服务注册发现 + 动态配置 + MCP 调度</td><td>Docker / 原生</td></tr>
|
||
<tr><td><strong>L2 数据层</strong></td><td>PostgreSQL 16 + pgvector</td><td>5432</td><td>Agent 状态 + 数据集 + 向量检索</td><td>Docker / 原生</td></tr>
|
||
<tr><td><strong>L1 对象存储</strong></td><td>MinIO</td><td>9000/9001</td><td>文件存储 + Agent 记忆持久化</td><td>Docker / 原生</td></tr>
|
||
<tr><td><strong>L0 模型</strong></td><td>阿里云百炼 DashScope</td><td>外网 443</td><td>LLM 推理（通义千问系列）</td><td>SaaS（无需部署）</td></tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
|
||
<div class="kpi-row">
|
||
<div class="kpi"><div class="num">5</div><div class="label">本地组件</div></div>
|
||
<div class="kpi good"><div class="num">1</div><div class="label">外网服务</div></div>
|
||
<div class="kpi warn"><div class="num">~2GB</div><div class="label">内存占用</div></div>
|
||
<div class="kpi purple"><div class="num">~30min</div><div class="label">预计耗时</div></div>
|
||
</div>
|
||
|
||
</section>
|
||
|
||
<!-- ============================================================ -->
|
||
<!-- S2: WSL2 环境准备 -->
|
||
<!-- ============================================================ -->
|
||
<section id="s2">
|
||
<h2>WSL2 环境准备</h2>
|
||
|
||
<h3>选项 A：安装 Docker（推荐）</h3>
|
||
|
||
<blockquote><p>中间件（PostgreSQL/Nacos/MinIO）使用 Docker 部署，一行命令启动，运维最简单。</p></blockquote>
|
||
|
||
<div class="code-block"><span class="cm"># 1. 安装 Docker（Debian）</span>
|
||
sudo apt update && sudo apt install -y ca-certificates curl
|
||
sudo install -m 0755 -d /etc/apt/keyrings
|
||
curl -fsSL https://download.docker.com/linux/debian/gpg | sudo tee /etc/apt/keyrings/docker.asc
|
||
<span class="kw">echo</span> <span class="str">"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian trixie stable"</span> | sudo tee /etc/apt/sources.list.d/docker.list
|
||
sudo apt update && sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
|
||
sudo usermod -aG docker $USER
|
||
<span class="cm"># 重新登录 WSL2 使 docker 组生效</span></div>
|
||
|
||
<div class="box box-idea">
|
||
<h4>💡 Docker 不工作时</h4>
|
||
<p>WSL2 中 Docker daemon 需要手动启动：<code>sudo dockerd &</code> 或 <code>sudo service docker start</code>。如果使用 Docker Desktop for Windows，在 Docker Desktop 设置中启用 WSL2 集成即可自动管理。</p>
|
||
</div>
|
||
|
||
<div class="code-block"><span class="cm"># 2. 验证 Docker</span>
|
||
docker --version
|
||
docker compose version</div>
|
||
|
||
<h3>选项 B：原生安装（不依赖 Docker）</h3>
|
||
|
||
<blockquote><p>如果不想安装 Docker，所有中间件均可在 WSL2 内原生安装。PostgreSQL 和 MinIO 通过 apt 安装，Nacos 下载二进制包直接运行。</p></blockquote>
|
||
|
||
<div class="box box-info">
|
||
<h4>ℹ️ 原生 vs Docker 对比</h4>
|
||
<p><strong>Docker</strong>：统一管理、数据隔离、升级方便、端口统一映射。推荐。</p>
|
||
<p><strong>原生</strong>：不依赖 Docker daemon、资源占用略低、但每个组件需单独管理。</p>
|
||
<p>下文同时提供两种方式的具体步骤。</p>
|
||
</div>
|
||
|
||
<h3>WSL2 系统优化</h3>
|
||
|
||
<div class="code-block"><span class="cm"># 编辑 /etc/wsl.conf，添加以下内容（如已有则合并）</span>
|
||
<span class="kw">sudo tee -a /etc/wsl.conf</span> <<EOF
|
||
[boot]
|
||
systemd=true
|
||
|
||
[network]
|
||
hostname=wsl2-dev
|
||
generateResolvConf=true
|
||
EOF
|
||
|
||
<span class="cm"># 创建项目目录</span>
|
||
mkdir -p /mnt/d/wiki/智能体平台调研/代码/spring-ai-alibaba-platform
|
||
<span class="kw">cd</span> /mnt/d/wiki/智能体平台调研/代码/</div>
|
||
|
||
</section>
|
||
|
||
<!-- ============================================================ -->
|
||
<!-- S3: 中间件总览 -->
|
||
<!-- ============================================================ -->
|
||
<section id="s3">
|
||
<h2>中间件部署总览</h2>
|
||
|
||
<div class="table-wrap">
|
||
<div class="table-caption">表：三个中间件的资源配置</div>
|
||
<table>
|
||
<thead><tr><th>组件</th><th>版本</th><th>端口</th><th>内存建议</th><th>磁盘建议</th><th>凭证（开发环境）</th></tr></thead>
|
||
<tbody>
|
||
<tr><td><strong>PostgreSQL</strong></td><td>16</td><td>5432</td><td>256MB</td><td>2GB</td><td>sa_agent / agent_2026</td></tr>
|
||
<tr><td><strong>Nacos</strong></td><td>3.1.0</td><td>8848 (HTTP), 9848 (gRPC)</td><td>512MB</td><td>1GB</td><td>nacos / nacos</td></tr>
|
||
<tr><td><strong>MinIO</strong></td><td>latest</td><td>9000 (API), 9001 (Console)</td><td>256MB</td><td>5GB</td><td>minioadmin / minioadmin</td></tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
|
||
<div class="box box-warn">
|
||
<h4>⚠️ 安全提醒</h4>
|
||
<p>以上为<strong>开发环境</strong>默认凭证。部署到生产内网后，务必修改所有默认密码。Nacos 尤其需要关注——<strong>不要将 Nacos 暴露到公网</strong>（默认鉴权较简单），当前内网使用可接受。</p>
|
||
</div>
|
||
|
||
</section>
|
||
|
||
<!-- ============================================================ -->
|
||
<!-- S4: PostgreSQL -->
|
||
<!-- ============================================================ -->
|
||
<section id="s4">
|
||
<h2>PostgreSQL 16 + pgvector 安装</h2>
|
||
|
||
<h3>方式一：Docker（推荐）</h3>
|
||
|
||
<div class="code-block"><span class="cm"># docker-compose.yml 片段（完整文件见附录）</span>
|
||
services:
|
||
postgres:
|
||
image: pgvector/pgvector:pg16
|
||
container_name: sa-pg
|
||
restart: unless-stopped
|
||
environment:
|
||
POSTGRES_DB: spring_ai_agent
|
||
POSTGRES_USER: sa_agent
|
||
POSTGRES_PASSWORD: agent_2026
|
||
ports:
|
||
- <span class="str">"5432:5432"</span>
|
||
volumes:
|
||
- pg_data:/var/lib/postgresql/data
|
||
healthcheck:
|
||
test: [<span class="str">"CMD-SHELL"</span>, <span class="str">"pg_isready -U sa_agent"</span>]
|
||
interval: 10s
|
||
timeout: 5s
|
||
retries: 5</div>
|
||
|
||
<p><strong>关键点</strong>：使用 <code>pgvector/pgvector:pg16</code> 镜像而非官方 postgres，因为它内置了向量扩展。如果你已有官方 PostgreSQL，可以手动安装 pgvector 扩展。</p>
|
||
|
||
<h3>方式二：原生 apt 安装</h3>
|
||
|
||
<div class="code-block"><span class="cm"># 安装 PostgreSQL 16</span>
|
||
sudo apt update && sudo apt install -y postgresql-16 postgresql-client-16
|
||
|
||
<span class="cm"># 安装 pgvector 扩展（从源码编译）</span>
|
||
sudo apt install -y postgresql-server-dev-16 build-essential git
|
||
git clone https://github.com/pgvector/pgvector.git
|
||
<span class="kw">cd</span> pgvector && make && sudo make install
|
||
|
||
<span class="cm"># 创建数据库和用户</span>
|
||
sudo -u postgres psql <<SQL
|
||
CREATE USER sa_agent WITH PASSWORD <span class="str">'agent_2026'</span>;
|
||
CREATE DATABASE spring_ai_agent OWNER sa_agent;
|
||
\c spring_ai_agent
|
||
CREATE EXTENSION vector;
|
||
SQL
|
||
|
||
<span class="cm"># 配置远程访问（内网其他机器连接）</span>
|
||
<span class="kw">echo</span> <span class="str">"listen_addresses = '*'"</span> | sudo tee -a /etc/postgresql/16/main/postgresql.conf
|
||
<span class="kw">echo</span> <span class="str">"host all sa_agent 0.0.0.0/0 md5"</span> | sudo tee -a /etc/postgresql/16/main/pg_hba.conf
|
||
sudo systemctl restart postgresql</div>
|
||
|
||
</section>
|
||
|
||
<!-- ============================================================ -->
|
||
<!-- S5: Nacos -->
|
||
<!-- ============================================================ -->
|
||
<section id="s5">
|
||
<h2>Nacos 3.x 安装</h2>
|
||
|
||
<h3>方式一：Docker（推荐）</h3>
|
||
|
||
<div class="code-block"><span class="cm"># docker-compose.yml 片段</span>
|
||
services:
|
||
nacos:
|
||
image: nacos/nacos-server:v3.1.0
|
||
container_name: sa-nacos
|
||
restart: unless-stopped
|
||
environment:
|
||
MODE: standalone
|
||
NACOS_AUTH_ENABLE: <span class="str">"true"</span>
|
||
NACOS_AUTH_TOKEN: SecretKey012345678901234567890123456789012345678901234567890123456789
|
||
NACOS_AUTH_IDENTITY_KEY: sa-nacos-identity
|
||
NACOS_AUTH_IDENTITY_VALUE: sa-nacos-secret
|
||
ports:
|
||
- <span class="str">"8848:8848"</span>
|
||
- <span class="str">"9848:9848"</span>
|
||
volumes:
|
||
- nacos_data:/home/nacos/data</div>
|
||
|
||
<p>Nacos 控制台：<code>http://localhost:8848/nacos</code>，默认用户名密码 <code>nacos/nacos</code>。</p>
|
||
|
||
<h3>方式二：原生二进制</h3>
|
||
|
||
<div class="code-block"><span class="cm"># 下载并启动 Nacos</span>
|
||
wget https://github.com/alibaba/nacos/releases/download/3.1.0/nacos-server-3.1.0.tar.gz
|
||
tar -xzf nacos-server-3.1.0.tar.gz
|
||
<span class="kw">cd</span> nacos/bin
|
||
<span class="cm"># Standalone 模式启动（内网够用）</span>
|
||
bash startup.sh -m standalone</div>
|
||
|
||
<div class="box box-info">
|
||
<h4>ℹ️ Nacos 命名空间规划</h4>
|
||
<p>启动后登录 Nacos 控制台（8848），创建以下命名空间：</p>
|
||
<p>1. <strong>sa-agent-mcp</strong> — MCP Server/Client 注册发现</p>
|
||
<p>2. <strong>sa-agent-config</strong> — 动态配置（Prompt 模板、模型参数）</p>
|
||
<p>3. <strong>sa-agent-a2a</strong> — 多 Agent A2A 通信（可选）</p>
|
||
</div>
|
||
|
||
</section>
|
||
|
||
<!-- ============================================================ -->
|
||
<!-- S6: MinIO -->
|
||
<!-- ============================================================ -->
|
||
<section id="s6">
|
||
<h2>MinIO 对象存储安装</h2>
|
||
|
||
<h3>方式一：Docker（推荐）</h3>
|
||
|
||
<div class="code-block"><span class="cm"># docker-compose.yml 片段</span>
|
||
services:
|
||
minio:
|
||
image: minio/minio:latest
|
||
container_name: sa-minio
|
||
restart: unless-stopped
|
||
command: server /data --console-address <span class="str">":9001"</span>
|
||
environment:
|
||
MINIO_ROOT_USER: minioadmin
|
||
MINIO_ROOT_PASSWORD: minioadmin
|
||
ports:
|
||
- <span class="str">"9000:9000"</span>
|
||
- <span class="str">"9001:9001"</span>
|
||
volumes:
|
||
- minio_data:/data
|
||
healthcheck:
|
||
test: [<span class="str">"CMD"</span>, <span class="str">"curl"</span>, <span class="str">"-f"</span>, <span class="str">"http://localhost:9000/minio/health/live"</span>]
|
||
interval: 10s
|
||
timeout: 5s
|
||
retries: 5</div>
|
||
|
||
<h3>方式二：原生安装</h3>
|
||
|
||
<div class="code-block"><span class="cm"># 下载 MinIO 二进制</span>
|
||
wget https://dl.min.io/server/minio/release/linux-amd64/minio
|
||
chmod +x minio
|
||
sudo mv minio /usr/local/bin/
|
||
|
||
<span class="cm"># 创建数据目录并启动</span>
|
||
mkdir -p /mnt/d/minio-data
|
||
MINIO_ROOT_USER=minioadmin MINIO_ROOT_PASSWORD=minioadmin \
|
||
minio server /mnt/d/minio-data --console-address <span class="str">":9001"</span> &</div>
|
||
|
||
<h3>创建 Spring AI Alibaba 专用 Bucket</h3>
|
||
|
||
<p>MinIO 启动后，访问 <code>http://localhost:9001</code> 登录控制台，创建 Bucket：</p>
|
||
|
||
<div class="table-wrap">
|
||
<table>
|
||
<thead><tr><th>Bucket 名称</th><th>用途</th></tr></thead>
|
||
<tbody>
|
||
<tr><td><strong>sa-agent-memory</strong></td><td>Agent 记忆文件持久化（MEMORY.md / 快照 / 知识图谱）</td></tr>
|
||
<tr><td><strong>sa-agent-datasets</strong></td><td>评测数据集存储</td></tr>
|
||
<tr><td><strong>sa-agent-skills</strong></td><td>自定义 Skill 文件存储</td></tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
|
||
</section>
|
||
|
||
<!-- ============================================================ -->
|
||
<!-- S7: 项目骨架搭建 -->
|
||
<!-- ============================================================ -->
|
||
<section id="s7">
|
||
<h2>Spring AI Alibaba 项目骨架搭建</h2>
|
||
|
||
<blockquote><p>采用 Spring Boot 3.5.x + Spring AI Alibaba 1.1.2.3。推荐使用 <a href="https://start.spring.io" target="_blank">Spring Initializr</a> 生成骨架，或直接克隆官方示例仓库。</p></blockquote>
|
||
|
||
<h3>方式一：Spring Initializr 生成（推荐新项目）</h3>
|
||
|
||
<div class="code-block"><span class="cm"># 用 curl 调 Spring Initializr API 生成项目（也可手动在 start.spring.io 操作）</span>
|
||
curl -s https://start.spring.io/starter.zip \
|
||
-d type=maven-project \
|
||
-d language=java \
|
||
-d bootVersion=3.5.3 \
|
||
-d baseDir=spring-ai-alibaba-platform \
|
||
-d groupId=com.demo \
|
||
-d artifactId=agent-platform \
|
||
-d name=AgentPlatform \
|
||
-d packageName=com.demo.agent \
|
||
-d javaVersion=21 \
|
||
-d dependencies=web,actuator,lombok \
|
||
-o spring-ai-alibaba-platform.zip
|
||
unzip spring-ai-alibaba-platform.zip</div>
|
||
|
||
<h3>方式二：克隆官方示例（推荐快速验证）</h3>
|
||
|
||
<div class="code-block">git clone https://github.com/alibaba/spring-ai-alibaba.git
|
||
<span class="kw">cd</span> spring-ai-alibaba
|
||
<span class="cm"># 官方示例在 spring-ai-alibaba-examples/ 目录下</span></div>
|
||
|
||
<h3>方式三：从零搭建 Maven 项目</h3>
|
||
|
||
<p>最小 <code>pom.xml</code> 如下（完整版见附录）：</p>
|
||
|
||
<div class="code-block"><span class="cm"><!-- 版本锁定 --></span>
|
||
<properties>
|
||
<spring-boot.version>3.5.3</spring-boot.version>
|
||
<spring-ai.version>1.1.2</spring-ai.version>
|
||
<spring-ai-alibaba.version>1.1.2.3</spring-ai-alibaba.version>
|
||
</properties>
|
||
|
||
<dependencyManagement>
|
||
<dependencies>
|
||
<span class="kw"><dependency></span>
|
||
<groupId>org.springframework.boot</groupId>
|
||
<artifactId>spring-boot-dependencies</artifactId>
|
||
<version>${spring-boot.version}</version>
|
||
<type>pom</type><scope>import</scope>
|
||
<span class="kw"></dependency></span>
|
||
<span class="kw"><dependency></span>
|
||
<groupId>org.springframework.ai</groupId>
|
||
<artifactId>spring-ai-bom</artifactId>
|
||
<version>${spring-ai.version}</version>
|
||
<type>pom</type><scope>import</scope>
|
||
<span class="kw"></dependency></span>
|
||
<span class="kw"><dependency></span>
|
||
<groupId>com.alibaba.cloud.ai</groupId>
|
||
<artifactId>spring-ai-alibaba-bom</artifactId>
|
||
<version>${spring-ai-alibaba.version}</version>
|
||
<type>pom</type><scope>import</scope>
|
||
<span class="kw"></dependency></span>
|
||
</dependencies>
|
||
</dependencyManagement>
|
||
|
||
<span class="cm"><!-- 核心依赖（详见下一节） --></span></div>
|
||
|
||
</section>
|
||
|
||
<!-- ============================================================ -->
|
||
<!-- S8: 核心配置详解 -->
|
||
<!-- ============================================================ -->
|
||
<section id="s8">
|
||
<h2>核心配置详解</h2>
|
||
|
||
<h3>application.yml — 全功能配置</h3>
|
||
|
||
<blockquote><p>以下为<strong>本地内网全功能</strong>配置，覆盖五大功能模块。放在 <code>src/main/resources/application.yml</code>。</p></blockquote>
|
||
|
||
<div class="code-block"><span class="cm"># ===========================================</span>
|
||
<span class="cm"># Spring AI Alibaba 全功能内网配置</span>
|
||
<span class="cm"># ===========================================</span>
|
||
|
||
<span class="cm"># --- 基础配置 ---</span>
|
||
<span class="kw">server:</span>
|
||
port: 8080
|
||
address: 0.0.0.0 <span class="cm"># 绑定所有网卡，允许内网访问</span>
|
||
|
||
<span class="kw">spring:</span>
|
||
application:
|
||
name: agent-platform
|
||
|
||
<span class="cm"># --- 数据源 ---</span>
|
||
datasource:
|
||
url: jdbc:postgresql://localhost:5432/spring_ai_agent
|
||
username: sa_agent
|
||
password: agent_2026
|
||
driver-class-name: org.postgresql.Driver
|
||
hikari:
|
||
maximum-pool-size: 10
|
||
minimum-idle: 2
|
||
|
||
<span class="cm"># --- AI 模型配置（外网） ---</span>
|
||
ai:
|
||
dashscope:
|
||
api-key: ${DASHSCOPE_API_KEY} <span class="cm"># 环境变量注入</span>
|
||
chat:
|
||
options:
|
||
model: qwen-plus
|
||
temperature: 0.7
|
||
|
||
<span class="cm"># --- Nacos 配置中心 ---</span>
|
||
alibaba:
|
||
nacos:
|
||
config:
|
||
server-addr: localhost:8848
|
||
namespace: ${NACOS_CONFIG_NAMESPACE:sa-agent-config}
|
||
|
||
<span class="cm"># --- Nacos MCP 注册发现 ---</span>
|
||
mcp:
|
||
nacos:
|
||
enabled: true
|
||
server-addr: localhost:8848
|
||
username: nacos
|
||
password: nacos
|
||
registry:
|
||
service-namespace: ${NACOS_MCP_NAMESPACE:sa-agent-mcp}
|
||
enabled: true
|
||
|
||
<span class="cm"># --- 对象存储（MinIO）---</span>
|
||
cloud:
|
||
aws:
|
||
s3:
|
||
endpoint: http://localhost:9000
|
||
region: us-east-1
|
||
path-style-access-enabled: true
|
||
credentials:
|
||
access-key: minioadmin
|
||
secret-key: minioadmin
|
||
|
||
<span class="cm"># --- Spring AI Alibaba Admin Studio ---</span>
|
||
<span class="kw">spring.ai.alibaba:</span>
|
||
studio:
|
||
enabled: true
|
||
path: /chatui <span class="cm"># Studio UI 路径</span>
|
||
|
||
<span class="cm"># --- Graph 工作流 ---</span>
|
||
<span class="kw">spring.ai.alibaba.graph:</span>
|
||
observation:
|
||
enabled: true <span class="cm"># OpenTelemetry 追踪</span>
|
||
|
||
<span class="cm"># --- Actuator 健康检查 ---</span>
|
||
<span class="kw">management:</span>
|
||
endpoints:
|
||
web:
|
||
exposure:
|
||
include: health,info,metrics,env
|
||
endpoint:
|
||
health:
|
||
show-details: when-authorized</div>
|
||
|
||
<h3>环境变量配置</h3>
|
||
|
||
<div class="code-block"><span class="cm"># 在 ~/.bashrc 或项目 .env 文件中配置</span>
|
||
<span class="kw">export</span> DASHSCOPE_API_KEY=sk-your-dashscope-api-key
|
||
<span class="kw">export</span> NACOS_CONFIG_NAMESPACE=sa-agent-config
|
||
<span class="kw">export</span> NACOS_MCP_NAMESPACE=sa-agent-mcp
|
||
<span class="kw">export</span> JINA_API_KEY=jina-your-key <span class="cm"># 可选：深度搜索功能</span></div>
|
||
|
||
<div class="box box-warn">
|
||
<h4>⚠️ DashScope API Key 获取</h4>
|
||
<p>1. 访问 <a href="https://dashscope.console.aliyun.com/" target="_blank">阿里云百炼控制台</a></p>
|
||
<p>2. 注册/登录 → API-KEY 管理 → 创建 API Key</p>
|
||
<p>3. 新用户有大量免费额度（通义千问 Plus 100万 Token/月）</p>
|
||
<p>4. <strong>内网部署 + 外网模型</strong>：确保 WSL2 可以访问 api dashscope.aliyuncs.com</p>
|
||
</div>
|
||
|
||
<h3>完整 pom.xml 依赖清单</h3>
|
||
|
||
<div class="code-block"><span class="cm"><!-- ============================================ --></span>
|
||
<span class="cm"><!-- Spring AI Alibaba 全功能依赖清单 --></span>
|
||
<span class="cm"><!-- ============================================ --></span>
|
||
|
||
<span class="cm"><!-- 1. 核心 DashScope AI Starter（必选）--></span>
|
||
<span class="kw"><dependency></span>
|
||
<groupId>com.alibaba.cloud.ai</groupId>
|
||
<artifactId>spring-ai-alibaba-starter-dashscope</artifactId>
|
||
<span class="kw"></dependency></span>
|
||
|
||
<span class="cm"><!-- 2. Agent 框架（必选：多 Agent 编排 + Graph）--></span>
|
||
<span class="kw"><dependency></span>
|
||
<groupId>com.alibaba.cloud.ai</groupId>
|
||
<artifactId>spring-ai-alibaba-agent-framework</artifactId>
|
||
<span class="kw"></dependency></span>
|
||
|
||
<span class="cm"><!-- 3. Admin Studio UI（必选：可视化编排 + 评测）--></span>
|
||
<span class="kw"><dependency></span>
|
||
<groupId>com.alibaba.cloud.ai</groupId>
|
||
<artifactId>spring-ai-alibaba-studio</artifactId>
|
||
<span class="kw"></dependency></span>
|
||
|
||
<span class="cm"><!-- 4. Nacos MCP Server（必选：MCP 分布式）--></span>
|
||
<span class="kw"><dependency></span>
|
||
<groupId>com.alibaba.cloud.ai</groupId>
|
||
<artifactId>spring-ai-alibaba-starter-nacos-mcp-server</artifactId>
|
||
<span class="kw"></dependency></span>
|
||
|
||
<span class="cm"><!-- 5. Nacos MCP Client（必选：发现 MCP 服务）--></span>
|
||
<span class="kw"><dependency></span>
|
||
<groupId>com.alibaba.cloud.ai</groupId>
|
||
<artifactId>spring-ai-alibaba-starter-nacos-mcp-client</artifactId>
|
||
<span class="kw"></dependency></span>
|
||
|
||
<span class="cm"><!-- 6. Nacos 配置中心（推荐：动态 Prompt + 参数热更新）--></span>
|
||
<span class="kw"><dependency></span>
|
||
<groupId>com.alibaba.cloud.ai</groupId>
|
||
<artifactId>spring-ai-alibaba-starter-config-nacos</artifactId>
|
||
<span class="kw"></dependency></span>
|
||
|
||
<span class="cm"><!-- 7. Graph 可观测性（推荐：OTel 追踪）--></span>
|
||
<span class="kw"><dependency></span>
|
||
<groupId>com.alibaba.cloud.ai</groupId>
|
||
<artifactId>spring-ai-alibaba-starter-graph-observation</artifactId>
|
||
<span class="kw"></dependency></span>
|
||
|
||
<span class="cm"><!-- 8. PostgreSQL（必选：数据持久化）--></span>
|
||
<span class="kw"><dependency></span>
|
||
<groupId>org.postgresql</groupId>
|
||
<artifactId>postgresql</artifactId>
|
||
<scope>runtime</scope>
|
||
<span class="kw"></dependency></span>
|
||
|
||
<span class="cm"><!-- 9. MinIO S3 兼容客户端（必选：对象存储）--></span>
|
||
<span class="kw"><dependency></span>
|
||
<groupId>io.awspring.cloud</groupId>
|
||
<artifactId>spring-cloud-aws-starter-s3</artifactId>
|
||
<span class="kw"></dependency></span>
|
||
|
||
<span class="cm"><!-- 10. Actuator（推荐：健康检查 + 指标 --></span>
|
||
<span class="kw"><dependency></span>
|
||
<groupId>org.springframework.boot</groupId>
|
||
<artifactId>spring-boot-starter-actuator</artifactId>
|
||
<span class="kw"></dependency></span></div>
|
||
|
||
</section>
|
||
|
||
<!-- ============================================================ -->
|
||
<!-- S9: 全功能模块激活 -->
|
||
<!-- ============================================================ -->
|
||
<section id="s9">
|
||
<h2>全功能模块激活指南</h2>
|
||
|
||
<blockquote><p>Spring AI Alibaba 五项核心功能中，四项在开源版完整提供。以下是逐模块激活步骤。</p></blockquote>
|
||
|
||
<h3>模块 1：多智能体平面 <span class="tag tag-green">⭐⭐⭐⭐⭐</span></h3>
|
||
|
||
<p>Spring AI Alibaba 的 <strong>Graph 引擎</strong> 原生支持 6 种 Agent 编排模式。无需额外配置，引入 <code>agent-framework</code> 依赖即生效。</p>
|
||
|
||
<div class="code-block"><span class="cm">// 6 种编排模式示例入口</span>
|
||
<span class="kw">@RestController</span>
|
||
<span class="kw">public class</span> AgentOrchestrationController {
|
||
|
||
<span class="cm">// 1. Sequential — 顺序执行</span>
|
||
<span class="kw">@GetMapping</span>(<span class="str">"/agent/sequential"</span>)
|
||
<span class="kw">public</span> String sequential() {
|
||
<span class="kw">var</span> graph = <span class="kw">new</span> SequentialAgentGraph()
|
||
.addAgent(<span class="str">"researcher"</span>, researchAgent)
|
||
.addAgent(<span class="str">"writer"</span>, writerAgent);
|
||
<span class="kw">return</span> graph.execute(input);
|
||
}
|
||
|
||
<span class="cm">// 2. Parallel — 并行执行</span>
|
||
<span class="cm">// 3. Routing — 条件路由</span>
|
||
<span class="cm">// 4. Loop — 循环迭代</span>
|
||
<span class="cm">// 5. Supervisor — 监督模式</span>
|
||
<span class="cm">// 6. Handoff — Agent 间交接</span>
|
||
}</div>
|
||
|
||
<div class="box box-idea">
|
||
<h4>💡 多 Agent 分布式（A2A 协议）</h4>
|
||
<p>如果多个 Agent 部署在不同微服务中，通过 <strong>Nacos + A2A 协议</strong> 实现跨服务通信。每个 Agent 应用引入 Nacos MCP 依赖后，自动注册到 Nacos，其他 Agent 通过服务名发现并调用。无需硬编码 IP:Port。</p>
|
||
</div>
|
||
|
||
<h3>模块 2：低代码编排 <span class="tag tag-blue">⭐⭐⭐⭐</span></h3>
|
||
|
||
<p>Admin Studio 提供了可视化 Graph 编排能力。引入 <code>spring-ai-alibaba-studio</code> 依赖后：</p>
|
||
|
||
<div class="step">
|
||
<div class="step-num">1</div>
|
||
<div class="step-body">
|
||
<strong>启动应用</strong>
|
||
<code>mvn spring-boot:run</code>（或 java -jar），访问 <code>http://localhost:8080/chatui</code>
|
||
</div>
|
||
</div>
|
||
|
||
<div class="step">
|
||
<div class="step-num">2</div>
|
||
<div class="step-body">
|
||
<strong>进入 Graph 编排视图</strong>
|
||
左侧导航 → Agent Graph → 拖拽节点 → 连线 → 配置每个节点的 Agent/工具/条件
|
||
</div>
|
||
</div>
|
||
|
||
<div class="step">
|
||
<div class="step-num">3</div>
|
||
<div class="step-body">
|
||
<strong>导出/导入</strong>
|
||
支持 PlantUML / Mermaid 导出，便于文档化；支持 JSON 导入复用工作流
|
||
</div>
|
||
</div>
|
||
|
||
<h3>模块 3：Harness 基建 <span class="tag tag-blue">⭐⭐⭐⭐</span></h3>
|
||
|
||
<p>Harness 含上下文管理、人工审核、Skill 管理、安全沙箱四大子模块：</p>
|
||
|
||
<div class="table-wrap">
|
||
<table>
|
||
<thead><tr><th>子模块</th><th>激活方式</th><th>说明</th></tr></thead>
|
||
<tbody>
|
||
<tr><td><strong>上下文压缩</strong></td><td>框架内置，自动启用</td><td>超长对话自动摘要+压缩，节省 Token。阈值可在 Nacos 动态配置</td></tr>
|
||
<tr><td><strong>上下文持久化</strong></td><td>配置 PostgreSQL 后自动启用</td><td>Agent 会话状态持久化到 DB，重启不丢失</td></tr>
|
||
<tr><td><strong>Human-in-the-Loop</strong></td><td>代码配置 <code>.humanApproval()</code></td><td>敏感操作（发邮件/删除文件）需人工审批</td></tr>
|
||
<tr><td><strong>Agent Skills</strong></td><td><code>spring-ai-alibaba-starter-skills</code></td><td>渐进式披露 + 按需加载，大幅降低 Token 消耗</td></tr>
|
||
<tr><td><strong>安全沙箱</strong></td><td>框架内置</td><td>代码执行隔离，工具调用权限检查</td></tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
|
||
<h3>模块 4：技能市场 <span class="tag tag-warn">⭐⭐⭐</span></h3>
|
||
|
||
<p>Spring AI Alibaba 的 "技能市场" 基于 Agent Skills 机制（v1.1.2.0 新增），与 OpenClaw 的 ClawHub 不同，<strong>没有公开社区市场</strong>。技能以本地文件/代码形式管理：</p>
|
||
|
||
<div class="code-block"><span class="cm">// 定义 Agent Skill</span>
|
||
<span class="kw">@Component</span>
|
||
<span class="kw">public class</span> WeatherSkill <span class="kw">implements</span> AgentSkill {
|
||
<span class="kw">public</span> String getName() { <span class="kw">return</span> <span class="str">"weather-query"</span>; }
|
||
<span class="kw">public</span> String getDescription() { <span class="kw">return</span> <span class="str">"查询指定城市的天气"</span>; }
|
||
<span class="kw">public</span> SkillResult execute(SkillContext ctx) { <span class="cm">/*...*/</span> }
|
||
}
|
||
|
||
<span class="cm">// Agent 声明可用 Skills（渐进式披露——只发描述不发实现）</span>
|
||
<span class="kw">@Agent</span>(skills={<span class="str">"weather-query"</span>, <span class="str">"stock-price"</span>, <span class="str">"file-search"</span>})
|
||
<span class="kw">public class</span> AssistantAgent { }</div>
|
||
|
||
<p>内网小团队场景下，可以自建内部 Skill 仓库（Git 仓库 + MinIO 存储），通过 <code>Agent Skills</code> 机制加载。</p>
|
||
|
||
<h3>模块 5：评测服务 <span class="tag tag-blue">⭐⭐⭐⭐</span></h3>
|
||
|
||
<p>Admin Studio 内置评测平台，无需额外部署！</p>
|
||
|
||
<div class="step">
|
||
<div class="step-num">1</div>
|
||
<div class="step-body">
|
||
<strong>创建数据集</strong>
|
||
Admin → 数据集管理 → 新建 → 上传 JSONL/CSV（问答对格式）
|
||
</div>
|
||
</div>
|
||
<div class="step">
|
||
<div class="step-num">2</div>
|
||
<div class="step-body">
|
||
<strong>配置评估器</strong>
|
||
选择评估维度：准确性 / 相关性 / 完整性 / 安全性 / 延迟
|
||
</div>
|
||
</div>
|
||
<div class="step">
|
||
<div class="step-num">3</div>
|
||
<div class="step-body">
|
||
<strong>创建实验</strong>
|
||
指定 Agent + 数据集 + 评估器 → 运行实验 → 查看结果面板
|
||
</div>
|
||
</div>
|
||
|
||
<div class="box box-good">
|
||
<h4>✅ 评测功能总结</h4>
|
||
<p>Spring AI Alibaba 的评测模块在 10 个平台中排名前列。优势是 <strong>评测内置在 Admin 平台</strong>，无需像其他平台那样单独部署评测工具（如 Future AGI / EvalMonkey）。开发→编排→评估→优化的闭环全部在一个 Admin 界面内完成。</p>
|
||
</div>
|
||
|
||
</section>
|
||
|
||
<!-- ============================================================ -->
|
||
<!-- S10: 内网访问 -->
|
||
<!-- ============================================================ -->
|
||
<section id="s10">
|
||
<h2>内网访问配置</h2>
|
||
|
||
<blockquote><p>WSL2 默认 NAT 模式下，局域网其他设备无法直接访问 WSL2 内服务。有三种解决方案，按推荐度排序。</p></blockquote>
|
||
|
||
<h3>方案 A：WSL2 Mirrored 模式（最推荐 — Windows 11 24H2+）</h3>
|
||
|
||
<div class="code-block"><span class="cm"># 在 Windows 用户目录创建 %USERPROFILE%\.wslconfig</span>
|
||
<span class="cm"># 或编辑 /mnt/c/Users/<你的用户名>/.wslconfig</span>
|
||
[wsl2]
|
||
networkingMode=mirrored
|
||
dnsTunneling=true
|
||
firewall=false
|
||
autoProxy=true
|
||
|
||
<span class="cm"># 保存后在 PowerShell 中执行：</span>
|
||
<span class="cm"># wsl --shutdown</span>
|
||
<span class="cm"># wsl</span></div>
|
||
|
||
<div class="box box-good">
|
||
<h4>✅ Mirrored 模式优点</h4>
|
||
<p>WSL2 与 Windows 共享 IP 地址，局域网设备直接通过 <strong>Windows 的局域网 IP</strong> 访问 WSL2 内服务。无需端口转发，无需 netsh 配置。</p>
|
||
</div>
|
||
|
||
<h3>方案 B：NAT + 端口转发（Windows 10 / 不支持 Mirrored 时）</h3>
|
||
|
||
<div class="code-block"><span class="cm"># 1. 在 WSL2 中查看 IP</span>
|
||
ip addr show eth0 | grep inet
|
||
<span class="cm"># 假设得到 172.18.79.129</span>
|
||
|
||
<span class="cm"># 2. 在 Windows PowerShell（管理员）中添加端口转发</span>
|
||
<span class="cm"># 将 Windows 宿主机端口 → 转发到 WSL2 端口</span>
|
||
netsh interface portproxy add v4tov4 listenport=8080 listenaddress=0.0.0.0 connectport=8080 connectaddress=172.18.79.129
|
||
netsh interface portproxy add v4tov4 listenport=8848 listenaddress=0.0.0.0 connectport=8848 connectaddress=172.18.79.129
|
||
netsh interface portproxy add v4tov4 listenport=9001 listenaddress=0.0.0.0 connectport=9001 connectaddress=172.18.79.129
|
||
|
||
<span class="cm"># 3. 放行 Windows 防火墙</span>
|
||
New-NetFirewallRule -DisplayName <span class="str">"WSL2 Agent Platform 8080"</span> -Direction Inbound -LocalPort 8080 -Protocol TCP -Action Allow
|
||
New-NetFirewallRule -DisplayName <span class="str">"WSL2 Nacos 8848"</span> -Direction Inbound -LocalPort 8848 -Protocol TCP -Action Allow
|
||
|
||
<span class="cm"># 4. 查看已配置的转发规则</span>
|
||
netsh interface portproxy show all
|
||
|
||
<span class="cm"># 5. 删除转发规则（如果需要）</span>
|
||
netsh interface portproxy delete v4tov4 listenport=8080 listenaddress=0.0.0.0</div>
|
||
|
||
<div class="box box-warn">
|
||
<h4>⚠️ NAT 端口转发注意事项</h4>
|
||
<p>WSL2 重启后 IP 会变化，端口转发规则会失效。需要重新执行 step 2。建议写一个 PowerShell 脚本自动化此过程。</p>
|
||
</div>
|
||
|
||
<h3>方案 C：nginx 反向代理（灵活但复杂）</h3>
|
||
|
||
<p>在 Windows 宿主机安装 nginx，反向代理到 WSL2 内的服务。适合需要统一入口 + SSL + 认证的场景。</p>
|
||
|
||
<h3>验证内网可达性</h3>
|
||
|
||
<div class="code-block"><span class="cm"># 在 WSL2 内确认服务监听 0.0.0.0</span>
|
||
ss -tlnp | grep -E <span class="str">"8080|8848|5432|9000"</span>
|
||
|
||
<span class="cm"># 在局域网另一台设备（手机/笔记本）浏览器访问：</span>
|
||
<span class="cm"># http://<Windows局域网IP>:8080/chatui → Admin Studio</span>
|
||
<span class="cm"># http://<Windows局域网IP>:8848/nacos → Nacos 控制台</span>
|
||
<span class="cm"># http://<Windows局域网IP>:9001 → MinIO 控制台</span></div>
|
||
|
||
<div class="table-wrap">
|
||
<div class="table-caption">表：内网访问地址速查</div>
|
||
<table>
|
||
<thead><tr><th>服务</th><th>WSL2 内访问</th><th>局域网访问（Mirrored 模式）</th></tr></thead>
|
||
<tbody>
|
||
<tr><td>Admin Studio</td><td>http://localhost:8080/chatui</td><td>http://<Windows-IP>:8080/chatui</td></tr>
|
||
<tr><td>Nacos 控制台</td><td>http://localhost:8848/nacos</td><td>http://<Windows-IP>:8848/nacos</td></tr>
|
||
<tr><td>MinIO 控制台</td><td>http://localhost:9001</td><td>http://<Windows-IP>:9001</td></tr>
|
||
<tr><td>PostgreSQL</td><td>localhost:5432</td><td><Windows-IP>:5432</td></tr>
|
||
<tr><td>MinIO API</td><td>localhost:9000</td><td><Windows-IP>:9000</td></tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
|
||
</section>
|
||
|
||
<!-- ============================================================ -->
|
||
<!-- S11: 运维手册 -->
|
||
<!-- ============================================================ -->
|
||
<section id="s11">
|
||
<h2>运维手册</h2>
|
||
|
||
<h3>服务自启动</h3>
|
||
|
||
<h4>Docker 中间件自启动</h4>
|
||
<p>Docker Compose 中已设置 <code>restart: unless-stopped</code>，WSL2 启动后 Docker daemon 运行即自动拉起中间件。</p>
|
||
|
||
<h4>Spring Boot 应用自启动（systemd）</h4>
|
||
|
||
<div class="code-block"><span class="cm"># 创建 systemd service 文件</span>
|
||
sudo tee /etc/systemd/system/agent-platform.service <<'UNIT'
|
||
[Unit]
|
||
Description=Spring AI Alibaba Agent Platform
|
||
After=network.target docker.service
|
||
Wants=docker.service
|
||
|
||
[Service]
|
||
Type=simple
|
||
User=zdh
|
||
WorkingDirectory=/mnt/d/wiki/智能体平台调研/代码/spring-ai-alibaba-platform
|
||
Environment=<span class="str">"DASHSCOPE_API_KEY=sk-your-key"</span>
|
||
Environment=<span class="str">"NACOS_CONFIG_NAMESPACE=sa-agent-config"</span>
|
||
Environment=<span class="str">"NACOS_MCP_NAMESPACE=sa-agent-mcp"</span>
|
||
ExecStart=/usr/bin/java -jar -Xms512m -Xmx2g target/agent-platform-1.0.0.jar
|
||
Restart=on-failure
|
||
RestartSec=10
|
||
StandardOutput=journal
|
||
StandardError=journal
|
||
|
||
[Install]
|
||
WantedBy=multi-user.target
|
||
UNIT
|
||
|
||
sudo systemctl daemon-reload
|
||
sudo systemctl enable agent-platform
|
||
sudo systemctl start agent-platform</div>
|
||
|
||
<h3>日志管理</h3>
|
||
|
||
<div class="code-block"><span class="cm"># 查看应用日志（systemd 方式）</span>
|
||
journalctl -u agent-platform -f -n 100
|
||
|
||
<span class="cm"># 查看应用日志（直接运行方式）</span>
|
||
tail -f logs/agent-platform.log
|
||
|
||
<span class="cm"># Docker 中间件日志</span>
|
||
docker compose logs -f postgres
|
||
docker compose logs -f nacos</div>
|
||
|
||
<h3>数据备份</h3>
|
||
|
||
<div class="code-block"><span class="cm">#!/bin/bash</span>
|
||
<span class="cm"># backup-agent-platform.sh — 每日备份脚本</span>
|
||
BACKUP_DIR=/mnt/d/backups/agent-platform/$(date +%Y%m%d)
|
||
mkdir -p $BACKUP_DIR
|
||
|
||
<span class="cm"># 1. PostgreSQL 备份</span>
|
||
docker compose <span class="kw">exec</span> -T postgres pg_dump -U sa_agent spring_ai_agent > $BACKUP_DIR/pg_dump.sql
|
||
|
||
<span class="cm"># 2. MinIO 数据备份</span>
|
||
rsync -av /mnt/d/minio-data/ $BACKUP_DIR/minio-data/
|
||
|
||
<span class="cm"># 3. Nacos 配置导出</span>
|
||
curl -X GET <span class="str">"http://localhost:8848/nacos/v1/cs/configs?dataId=&group=&tenant=sa-agent-config&pageNo=1&pageSize=100"</span> > $BACKUP_DIR/nacos-config.json
|
||
|
||
<span class="kw">echo</span> <span class="str">"Backup complete: $BACKUP_DIR"</span></div>
|
||
|
||
<h3>版本升级</h3>
|
||
|
||
<div class="code-block"><span class="cm"># 1. 检查当前版本</span>
|
||
curl -s http://localhost:8080/actuator/info
|
||
|
||
<span class="cm"># 2. 更新 pom.xml 中的版本号</span>
|
||
<span class="cm"># spring-ai-alibaba.version → 新版本</span>
|
||
|
||
<span class="cm"># 3. 重建并重启</span>
|
||
mvn clean package -DskipTests
|
||
sudo systemctl restart agent-platform
|
||
|
||
<span class="cm"># 4. 验证</span>
|
||
curl -s http://localhost:8080/actuator/health</div>
|
||
|
||
</section>
|
||
|
||
<!-- ============================================================ -->
|
||
<!-- S12: 故障排查 -->
|
||
<!-- ============================================================ -->
|
||
<section id="s12">
|
||
<h2>故障排查</h2>
|
||
|
||
<div class="table-wrap">
|
||
<div class="table-caption">表：常见问题与解决方案</div>
|
||
<table>
|
||
<thead><tr><th style="width:25%">症状</th><th style="width:20%">可能原因</th><th>解决步骤</th></tr></thead>
|
||
<tbody>
|
||
<tr>
|
||
<td><strong>Nacos 连接超时</strong></td>
|
||
<td>Nacos 未启动 / 端口冲突</td>
|
||
<td>1. <code>docker compose ps nacos</code> 检查容器状态<br>2. <code>ss -tlnp | grep 8848</code> 检查端口<br>3. 检查 Nacos 日志 <code>docker compose logs nacos</code></td>
|
||
</tr>
|
||
<tr>
|
||
<td><strong>DashScope API 调用失败</strong></td>
|
||
<td>API Key 无效 / 网络不通</td>
|
||
<td>1. <code>curl -H "Authorization: Bearer $DASHSCOPE_API_KEY" https://dashscope.aliyuncs.com/api/v1/models</code> 测试<br>2. 检查 WSL2 外网连通性 <code>ping dashscope.aliyuncs.com</code><br>3. 检查环境变量是否注入 <code>echo $DASHSCOPE_API_KEY</code></td>
|
||
</tr>
|
||
<tr>
|
||
<td><strong>PostgreSQL 连接拒绝</strong></td>
|
||
<td>PG 未启动 / 认证失败</td>
|
||
<td>1. <code>docker compose ps postgres</code> 检查容器<br>2. 手动测试 <code>psql -h localhost -U sa_agent -d spring_ai_agent</code><br>3. 检查 pg_hba.conf 远程访问配置</td>
|
||
</tr>
|
||
<tr>
|
||
<td><strong>Admin Studio 白屏</strong></td>
|
||
<td>前端资源未构建 / 路径不对</td>
|
||
<td>1. 确认依赖包含 <code>spring-ai-alibaba-studio</code><br>2. 访问 <code>http://localhost:8080/chatui/index.html</code><br>3. 检查浏览器控制台 Network 错误</td>
|
||
</tr>
|
||
<tr>
|
||
<td><strong>MCP Server 注册不到 Nacos</strong></td>
|
||
<td>Nacos 命名空间不存在</td>
|
||
<td>1. 登录 Nacos 控制台检查 <code>sa-agent-mcp</code> 命名空间是否存在<br>2. 检查 application.yml 中 mcp.nacos.registry 配置<br>3. 查看应用日志 <code>grep "MCP" logs/*.log</code></td>
|
||
</tr>
|
||
<tr>
|
||
<td><strong>内网设备无法访问</strong></td>
|
||
<td>WSL2 NAT 网络隔离</td>
|
||
<td>1. 确认 <code>server.address=0.0.0.0</code><br>2. 试用 Mirrored 模式或端口转发（详见 S10）<br>3. <code>ss -tlnp | grep 8080</code> 确认监听 0.0.0.0 而非 127.0.0.1</td>
|
||
</tr>
|
||
<tr>
|
||
<td><strong>内存不足（OOM）</strong></td>
|
||
<td>JVM 内存占用过大</td>
|
||
<td>1. 降低 JVM 参数 <code>-Xmx1g</code> 到 <code>-Xmx512m</code><br>2. 减少 Nacos JVM：修改 nacos/bin/startup.sh 中的 <code>-Xms</code>/<code>-Xmx</code><br>3. 检查是否有内存泄漏 <code>jmap -heap <pid></code></td>
|
||
</tr>
|
||
<tr>
|
||
<td><strong>WSL2 重启后 IP 变化</strong></td>
|
||
<td>WSL2 默认 DHCP</td>
|
||
<td>使用 Mirrored 模式（方案 A）彻底解决，或编写端口转发自动修复脚本</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
|
||
<h3>快速健康检查脚本</h3>
|
||
|
||
<div class="code-block"><span class="cm">#!/bin/bash</span>
|
||
<span class="cm"># health-check.sh — 一键检测全平台状态</span>
|
||
<span class="kw">echo</span> <span class="str">"=== Spring AI Alibaba 全平台健康检查 ==="</span>
|
||
|
||
<span class="cm"># 中间件</span>
|
||
<span class="kw">echo</span> -n <span class="str">"[PostgreSQL] "</span>; psql -h localhost -U sa_agent -d spring_ai_agent -c <span class="str">"SELECT 1"</span> >/dev/null <span class="num">2</span>>&<span class="num">1</span> && <span class="kw">echo</span> <span class="str">"✅ OK"</span> || <span class="kw">echo</span> <span class="str">"❌ FAIL"</span>
|
||
<span class="kw">echo</span> -n <span class="str">"[Nacos] "</span>; curl -s http://localhost:8848/nacos/v1/console/health/readiness >/dev/null && <span class="kw">echo</span> <span class="str">"✅ OK"</span> || <span class="kw">echo</span> <span class="str">"❌ FAIL"</span>
|
||
<span class="kw">echo</span> -n <span class="str">"[MinIO] "</span>; curl -s http://localhost:9000/minio/health/live >/dev/null && <span class="kw">echo</span> <span class="str">"✅ OK"</span> || <span class="kw">echo</span> <span class="str">"❌ FAIL"</span>
|
||
|
||
<span class="cm"># 应用</span>
|
||
<span class="kw">echo</span> -n <span class="str">"[Agent Platform] "</span>; curl -s http://localhost:8080/actuator/health >/dev/null && <span class="kw">echo</span> <span class="str">"✅ OK"</span> || <span class="kw">echo</span> <span class="str">"❌ FAIL"</span>
|
||
<span class="kw">echo</span> -n <span class="str">"[Admin Studio] "</span>; curl -s -o /dev/null -w <span class="str">"%{http_code}"</span> http://localhost:8080/chatui/index.html | grep <span class="str">"200"</span> >/dev/null && <span class="kw">echo</span> <span class="str">"✅ OK"</span> || <span class="kw">echo</span> <span class="str">"❌ FAIL"</span>
|
||
|
||
<span class="cm"># 外网模型</span>
|
||
<span class="kw">echo</span> -n <span class="str">"[DashScope API] "</span>; curl -s -o /dev/null -w <span class="str">"%{http_code}"</span> https://dashscope.aliyuncs.com/api/v1/models -H <span class="str">"Authorization: Bearer $DASHSCOPE_API_KEY"</span> | grep <span class="str">"200"</span> >/dev/null && <span class="kw">echo</span> <span class="str">"✅ OK"</span> || <span class="kw">echo</span> <span class="str">"❌ FAIL"</span></div>
|
||
|
||
</section>
|
||
|
||
<footer class="footer">
|
||
<p>Spring AI Alibaba 全功能部署指南 · V1.0 · 2026-06-05</p>
|
||
<p style="margin-top:4px;">目标环境：WSL2 Debian 13 · 本地内网 · Java 21 · Nacos 3.x · PostgreSQL 16 · MinIO · DashScope</p>
|
||
</footer>
|
||
|
||
</main>
|
||
|
||
<button class="back-to-top" id="backToTop" aria-label="回到顶部">↑</button>
|
||
|
||
<script>
|
||
(function(){
|
||
var menuBtn = document.getElementById('menuBtn');
|
||
var overlay = document.getElementById('drawerOverlay');
|
||
var sidebar = document.querySelector('.sidebar');
|
||
var open = false;
|
||
function toggle(){ open ? close() : show(); }
|
||
function show(){ overlay.classList.add('show'); sidebar.classList.add('show'); open = true; document.body.style.overflow='hidden'; }
|
||
function close(){ overlay.classList.remove('show'); sidebar.classList.remove('show'); open = false; document.body.style.overflow=''; }
|
||
if(menuBtn) menuBtn.addEventListener('click', toggle);
|
||
if(overlay) overlay.addEventListener('click', close);
|
||
var sidebarLinks = document.querySelectorAll('.sidebar nav a');
|
||
sidebarLinks.forEach(function(a){
|
||
a.addEventListener('click', function(){
|
||
if(window.innerWidth <= 768) close();
|
||
});
|
||
});
|
||
var sections = document.querySelectorAll('section[id]');
|
||
var navLinks = document.querySelectorAll('.sidebar nav a');
|
||
function onScroll(){
|
||
var current = '';
|
||
sections.forEach(function(sec){
|
||
if(window.scrollY >= sec.offsetTop - 100) current = sec.id;
|
||
});
|
||
navLinks.forEach(function(a){
|
||
a.classList.toggle('active', a.getAttribute('href') === '#' + current);
|
||
});
|
||
}
|
||
window.addEventListener('scroll', onScroll, {passive:true});
|
||
var btt = document.getElementById('backToTop');
|
||
function toggleBTT(){ btt.classList.toggle('show', window.scrollY > 400); }
|
||
window.addEventListener('scroll', toggleBTT, {passive:true});
|
||
if(btt) btt.addEventListener('click', function(){ window.scrollTo({top:0,behavior:'smooth'}); });
|
||
})();
|
||
</script>
|
||
</body>
|
||
</html> |