Spring AI Alibaba 全功能部署指南

环境评估与缺口分析

部署目标：本地 WSL2（Debian 13）内网环境，全功能 Spring AI Alibaba 平台。模型 API 走外网（阿里云百炼），中间件全部本地部署。

表：当前环境检测结果

检测项	当前值	状态	说明
操作系统	Debian 13 (trixie) WSL2	OK	x86_64 架构，systemd 已启用
内存	15GB 总 / ~9.7GB 可用	OK	满足全套部署（建议 ≥8GB）
磁盘	/mnt/d 289GB 空闲	OK	建议路径 /mnt/d/wiki/ 下创建子目录
JDK	OpenJDK 21.0.11	OK	满足要求（≥17）
Maven	3.9.9	OK	满足要求（≥3.8）
Node.js	v24.15.0	OK	满足要求（≥20.12）
pnpm	已安装	OK	前端 Admin UI 构建需要
Docker	未安装	缺失	需安装 Docker 或改用原生安装方案
WSL2 网络	NAT 模式 172.18.79.x	需配置	需端口转发或切换到 mirrored 模式

⚠️ 关键缺口

1. Docker 未安装 — 中间件（PostgreSQL/Nacos/MinIO）建议用 Docker 部署，也可原生安装

2. WSL2 NAT 网络 — 默认 NAT 模式外部无法直接访问，需配置端口转发或 mirrored 模式

部署架构总览

图：全功能平台部署架构（本地内网版）

层级	组件	端口	职责	部署方式
L5 前端	Admin Studio (React)	8080	可视化编排 + 评测管理 + Agent 监控	Spring Boot 内嵌
L4 应用	Spring AI Alibaba	8080	Agent 框架 + Graph 引擎 + MCP/A2A	裸进程 (java -jar)
L3 注册中心	Nacos 3.x	8848/9848	服务注册发现 + 动态配置 + MCP 调度	Docker / 原生
L2 数据层	PostgreSQL 16 + pgvector	5432	Agent 状态 + 数据集 + 向量检索	Docker / 原生
L1 对象存储	MinIO	9000/9001	文件存储 + Agent 记忆持久化	Docker / 原生
L0 模型	阿里云百炼 DashScope	外网 443	LLM 推理（通义千问系列）	SaaS（无需部署）

本地组件

外网服务

~2GB

内存占用

~30min

预计耗时

WSL2 环境准备

选项 A：安装 Docker（推荐）

中间件（PostgreSQL/Nacos/MinIO）使用 Docker 部署，一行命令启动，运维最简单。

# 1. 安装 Docker（Debian）
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
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian trixie stable" | 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
# 重新登录 WSL2 使 docker 组生效

💡 Docker 不工作时

WSL2 中 Docker daemon 需要手动启动：sudo dockerd & 或 sudo service docker start。如果使用 Docker Desktop for Windows，在 Docker Desktop 设置中启用 WSL2 集成即可自动管理。

# 2. 验证 Docker
docker --version
docker compose version

选项 B：原生安装（不依赖 Docker）

如果不想安装 Docker，所有中间件均可在 WSL2 内原生安装。PostgreSQL 和 MinIO 通过 apt 安装，Nacos 下载二进制包直接运行。

ℹ️ 原生 vs Docker 对比

Docker：统一管理、数据隔离、升级方便、端口统一映射。推荐。

原生：不依赖 Docker daemon、资源占用略低、但每个组件需单独管理。

下文同时提供两种方式的具体步骤。

WSL2 系统优化

# 编辑 /etc/wsl.conf，添加以下内容（如已有则合并）
sudo tee -a /etc/wsl.conf <<EOF
[boot]
systemd=true

[network]
hostname=wsl2-dev
generateResolvConf=true
EOF

# 创建项目目录
mkdir -p /mnt/d/wiki/智能体平台调研/代码/spring-ai-alibaba-platform
cd /mnt/d/wiki/智能体平台调研/代码/

中间件部署总览

表：三个中间件的资源配置

组件	版本	端口	内存建议	磁盘建议	凭证（开发环境）
PostgreSQL	16	5432	256MB	2GB	sa_agent / agent_2026
Nacos	3.1.0	8848 (HTTP), 9848 (gRPC)	512MB	1GB	nacos / nacos
MinIO	latest	9000 (API), 9001 (Console)	256MB	5GB	minioadmin / minioadmin

⚠️ 安全提醒

以上为开发环境默认凭证。部署到生产内网后，务必修改所有默认密码。Nacos 尤其需要关注——不要将 Nacos 暴露到公网（默认鉴权较简单），当前内网使用可接受。

PostgreSQL 16 + pgvector 安装

方式一：Docker（推荐）

# docker-compose.yml 片段（完整文件见附录）
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:
      - "5432:5432"
    volumes:
      - pg_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U sa_agent"]
      interval: 10s
      timeout: 5s
      retries: 5

关键点：使用 pgvector/pgvector:pg16 镜像而非官方 postgres，因为它内置了向量扩展。如果你已有官方 PostgreSQL，可以手动安装 pgvector 扩展。

方式二：原生 apt 安装

# 安装 PostgreSQL 16
sudo apt update && sudo apt install -y postgresql-16 postgresql-client-16

# 安装 pgvector 扩展（从源码编译）
sudo apt install -y postgresql-server-dev-16 build-essential git
git clone https://github.com/pgvector/pgvector.git
cd pgvector && make && sudo make install

# 创建数据库和用户
sudo -u postgres psql <<SQL
CREATE USER sa_agent WITH PASSWORD 'agent_2026';
CREATE DATABASE spring_ai_agent OWNER sa_agent;
\c spring_ai_agent
CREATE EXTENSION vector;
SQL

# 配置远程访问（内网其他机器连接）
echo "listen_addresses = '*'" | sudo tee -a /etc/postgresql/16/main/postgresql.conf
echo "host all sa_agent 0.0.0.0/0 md5" | sudo tee -a /etc/postgresql/16/main/pg_hba.conf
sudo systemctl restart postgresql

Nacos 3.x 安装

方式一：Docker（推荐）

# docker-compose.yml 片段
services:
  nacos:
    image: nacos/nacos-server:v3.1.0
    container_name: sa-nacos
    restart: unless-stopped
    environment:
      MODE: standalone
      NACOS_AUTH_ENABLE: "true"
      NACOS_AUTH_TOKEN: SecretKey012345678901234567890123456789012345678901234567890123456789
      NACOS_AUTH_IDENTITY_KEY: sa-nacos-identity
      NACOS_AUTH_IDENTITY_VALUE: sa-nacos-secret
    ports:
      - "8848:8848"
      - "9848:9848"
    volumes:
      - nacos_data:/home/nacos/data

Nacos 控制台：http://localhost:8848/nacos，默认用户名密码 nacos/nacos。

方式二：原生二进制

# 下载并启动 Nacos
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
cd nacos/bin
# Standalone 模式启动（内网够用）
bash startup.sh -m standalone

ℹ️ Nacos 命名空间规划

启动后登录 Nacos 控制台（8848），创建以下命名空间：

1. sa-agent-mcp — MCP Server/Client 注册发现

2. sa-agent-config — 动态配置（Prompt 模板、模型参数）

3. sa-agent-a2a — 多 Agent A2A 通信（可选）

MinIO 对象存储安装

方式一：Docker（推荐）

# docker-compose.yml 片段
services:
  minio:
    image: minio/minio:latest
    container_name: sa-minio
    restart: unless-stopped
    command: server /data --console-address ":9001"
    environment:
      MINIO_ROOT_USER: minioadmin
      MINIO_ROOT_PASSWORD: minioadmin
    ports:
      - "9000:9000"
      - "9001:9001"
    volumes:
      - minio_data:/data
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:9000/minio/health/live"]
      interval: 10s
      timeout: 5s
      retries: 5

方式二：原生安装

# 下载 MinIO 二进制
wget https://dl.min.io/server/minio/release/linux-amd64/minio
chmod +x minio
sudo mv minio /usr/local/bin/

# 创建数据目录并启动
mkdir -p /mnt/d/minio-data
MINIO_ROOT_USER=minioadmin MINIO_ROOT_PASSWORD=minioadmin \
  minio server /mnt/d/minio-data --console-address ":9001" &

创建 Spring AI Alibaba 专用 Bucket

MinIO 启动后，访问 http://localhost:9001 登录控制台，创建 Bucket：

Bucket 名称	用途
sa-agent-memory	Agent 记忆文件持久化（MEMORY.md / 快照 / 知识图谱）
sa-agent-datasets	评测数据集存储
sa-agent-skills	自定义 Skill 文件存储

Spring AI Alibaba 项目骨架搭建

采用 Spring Boot 3.5.x + Spring AI Alibaba 1.1.2.3。推荐使用 Spring Initializr 生成骨架，或直接克隆官方示例仓库。

方式一：Spring Initializr 生成（推荐新项目）

# 用 curl 调 Spring Initializr API 生成项目（也可手动在 start.spring.io 操作）
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

方式二：克隆官方示例（推荐快速验证）

git clone https://github.com/alibaba/spring-ai-alibaba.git
cd spring-ai-alibaba
# 官方示例在 spring-ai-alibaba-examples/ 目录下

方式三：从零搭建 Maven 项目

最小 pom.xml 如下（完整版见附录）：

<!-- 版本锁定 -->
<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>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-dependencies</artifactId>
      <version>${spring-boot.version}</version>
      <type>pom</type><scope>import</scope>
    </dependency>
    <dependency>
      <groupId>org.springframework.ai</groupId>
      <artifactId>spring-ai-bom</artifactId>
      <version>${spring-ai.version}</version>
      <type>pom</type><scope>import</scope>
    </dependency>
    <dependency>
      <groupId>com.alibaba.cloud.ai</groupId>
      <artifactId>spring-ai-alibaba-bom</artifactId>
      <version>${spring-ai-alibaba.version}</version>
      <type>pom</type><scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<!-- 核心依赖（详见下一节） -->

核心配置详解

application.yml — 全功能配置

以下为本地内网全功能配置，覆盖五大功能模块。放在 src/main/resources/application.yml。

# ===========================================
# Spring AI Alibaba 全功能内网配置
# ===========================================

# --- 基础配置 ---
server:
  port: 8080
  address: 0.0.0.0    # 绑定所有网卡，允许内网访问

spring:
  application:
    name: agent-platform

  # --- 数据源 ---
  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

  # --- AI 模型配置（外网） ---
  ai:
    dashscope:
      api-key: ${DASHSCOPE_API_KEY}   # 环境变量注入
      chat:
        options:
          model: qwen-plus
          temperature: 0.7

    # --- Nacos 配置中心 ---
    alibaba:
      nacos:
        config:
          server-addr: localhost:8848
          namespace: ${NACOS_CONFIG_NAMESPACE:sa-agent-config}

      # --- Nacos MCP 注册发现 ---
      mcp:
        nacos:
          enabled: true
          server-addr: localhost:8848
          username: nacos
          password: nacos
          registry:
            service-namespace: ${NACOS_MCP_NAMESPACE:sa-agent-mcp}
            enabled: true

  # --- 对象存储（MinIO）---
  cloud:
    aws:
      s3:
        endpoint: http://localhost:9000
        region: us-east-1
        path-style-access-enabled: true
      credentials:
        access-key: minioadmin
        secret-key: minioadmin

# --- Spring AI Alibaba Admin Studio ---
spring.ai.alibaba:
  studio:
    enabled: true
    path: /chatui    # Studio UI 路径

# --- Graph 工作流 ---
spring.ai.alibaba.graph:
  observation:
    enabled: true     # OpenTelemetry 追踪

# --- Actuator 健康检查 ---
management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics,env
  endpoint:
    health:
      show-details: when-authorized

环境变量配置

# 在 ~/.bashrc 或项目 .env 文件中配置
export DASHSCOPE_API_KEY=sk-your-dashscope-api-key
export NACOS_CONFIG_NAMESPACE=sa-agent-config
export NACOS_MCP_NAMESPACE=sa-agent-mcp
export JINA_API_KEY=jina-your-key  # 可选：深度搜索功能

⚠️ DashScope API Key 获取

1. 访问阿里云百炼控制台

2. 注册/登录 → API-KEY 管理 → 创建 API Key

3. 新用户有大量免费额度（通义千问 Plus 100万 Token/月）

4. 内网部署 + 外网模型：确保 WSL2 可以访问 api dashscope.aliyuncs.com

完整 pom.xml 依赖清单

<!-- ============================================ -->
<!-- Spring AI Alibaba 全功能依赖清单           -->
<!-- ============================================ -->

<!-- 1. 核心 DashScope AI Starter（必选）-->
<dependency>
  <groupId>com.alibaba.cloud.ai</groupId>
  <artifactId>spring-ai-alibaba-starter-dashscope</artifactId>
</dependency>

<!-- 2. Agent 框架（必选：多 Agent 编排 + Graph）-->
<dependency>
  <groupId>com.alibaba.cloud.ai</groupId>
  <artifactId>spring-ai-alibaba-agent-framework</artifactId>
</dependency>

<!-- 3. Admin Studio UI（必选：可视化编排 + 评测）-->
<dependency>
  <groupId>com.alibaba.cloud.ai</groupId>
  <artifactId>spring-ai-alibaba-studio</artifactId>
</dependency>

<!-- 4. Nacos MCP Server（必选：MCP 分布式）-->
<dependency>
  <groupId>com.alibaba.cloud.ai</groupId>
  <artifactId>spring-ai-alibaba-starter-nacos-mcp-server</artifactId>
</dependency>

<!-- 5. Nacos MCP Client（必选：发现 MCP 服务）-->
<dependency>
  <groupId>com.alibaba.cloud.ai</groupId>
  <artifactId>spring-ai-alibaba-starter-nacos-mcp-client</artifactId>
</dependency>

<!-- 6. Nacos 配置中心（推荐：动态 Prompt + 参数热更新）-->
<dependency>
  <groupId>com.alibaba.cloud.ai</groupId>
  <artifactId>spring-ai-alibaba-starter-config-nacos</artifactId>
</dependency>

<!-- 7. Graph 可观测性（推荐：OTel 追踪）-->
<dependency>
  <groupId>com.alibaba.cloud.ai</groupId>
  <artifactId>spring-ai-alibaba-starter-graph-observation</artifactId>
</dependency>

<!-- 8. PostgreSQL（必选：数据持久化）-->
<dependency>
  <groupId>org.postgresql</groupId>
  <artifactId>postgresql</artifactId>
  <scope>runtime</scope>
</dependency>

<!-- 9. MinIO S3 兼容客户端（必选：对象存储）-->
<dependency>
  <groupId>io.awspring.cloud</groupId>
  <artifactId>spring-cloud-aws-starter-s3</artifactId>
</dependency>

<!-- 10. Actuator（推荐：健康检查 + 指标 -->
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

全功能模块激活指南

Spring AI Alibaba 五项核心功能中，四项在开源版完整提供。以下是逐模块激活步骤。

模块 1：多智能体平面 ⭐⭐⭐⭐⭐

Spring AI Alibaba 的 Graph 引擎 原生支持 6 种 Agent 编排模式。无需额外配置，引入 agent-framework 依赖即生效。

// 6 种编排模式示例入口
@RestController
public class AgentOrchestrationController {

    // 1. Sequential — 顺序执行
    @GetMapping("/agent/sequential")
    public String sequential() {
        var graph = new SequentialAgentGraph()
            .addAgent("researcher", researchAgent)
            .addAgent("writer", writerAgent);
        return graph.execute(input);
    }

    // 2. Parallel — 并行执行
    // 3. Routing — 条件路由
    // 4. Loop — 循环迭代
    // 5. Supervisor — 监督模式
    // 6. Handoff — Agent 间交接
}

💡 多 Agent 分布式（A2A 协议）

如果多个 Agent 部署在不同微服务中，通过 Nacos + A2A 协议 实现跨服务通信。每个 Agent 应用引入 Nacos MCP 依赖后，自动注册到 Nacos，其他 Agent 通过服务名发现并调用。无需硬编码 IP:Port。

模块 2：低代码编排 ⭐⭐⭐⭐

Admin Studio 提供了可视化 Graph 编排能力。引入 spring-ai-alibaba-studio 依赖后：

启动应用 mvn spring-boot:run（或 java -jar），访问 http://localhost:8080/chatui

进入 Graph 编排视图 左侧导航 → Agent Graph → 拖拽节点 → 连线 → 配置每个节点的 Agent/工具/条件

导出/导入 支持 PlantUML / Mermaid 导出，便于文档化；支持 JSON 导入复用工作流

模块 3：Harness 基建 ⭐⭐⭐⭐

Harness 含上下文管理、人工审核、Skill 管理、安全沙箱四大子模块：

子模块	激活方式	说明
上下文压缩	框架内置，自动启用	超长对话自动摘要+压缩，节省 Token。阈值可在 Nacos 动态配置
上下文持久化	配置 PostgreSQL 后自动启用	Agent 会话状态持久化到 DB，重启不丢失
Human-in-the-Loop	代码配置 `.humanApproval()`	敏感操作（发邮件/删除文件）需人工审批
Agent Skills	`spring-ai-alibaba-starter-skills`	渐进式披露 + 按需加载，大幅降低 Token 消耗
安全沙箱	框架内置	代码执行隔离，工具调用权限检查

模块 4：技能市场 ⭐⭐⭐

Spring AI Alibaba 的 "技能市场" 基于 Agent Skills 机制（v1.1.2.0 新增），与 OpenClaw 的 ClawHub 不同，没有公开社区市场。技能以本地文件/代码形式管理：

// 定义 Agent Skill
@Component
public class WeatherSkill implements AgentSkill {
    public String getName() { return "weather-query"; }
    public String getDescription() { return "查询指定城市的天气"; }
    public SkillResult execute(SkillContext ctx) { /*...*/ }
}

// Agent 声明可用 Skills（渐进式披露——只发描述不发实现）
@Agent(skills={"weather-query", "stock-price", "file-search"})
public class AssistantAgent { }

内网小团队场景下，可以自建内部 Skill 仓库（Git 仓库 + MinIO 存储），通过 Agent Skills 机制加载。

模块 5：评测服务 ⭐⭐⭐⭐

Admin Studio 内置评测平台，无需额外部署！

创建数据集 Admin → 数据集管理 → 新建 → 上传 JSONL/CSV（问答对格式）

配置评估器 选择评估维度：准确性 / 相关性 / 完整性 / 安全性 / 延迟

创建实验 指定 Agent + 数据集 + 评估器 → 运行实验 → 查看结果面板

✅ 评测功能总结

Spring AI Alibaba 的评测模块在 10 个平台中排名前列。优势是 评测内置在 Admin 平台，无需像其他平台那样单独部署评测工具（如 Future AGI / EvalMonkey）。开发→编排→评估→优化的闭环全部在一个 Admin 界面内完成。

内网访问配置

WSL2 默认 NAT 模式下，局域网其他设备无法直接访问 WSL2 内服务。有三种解决方案，按推荐度排序。

方案 A：WSL2 Mirrored 模式（最推荐 — Windows 11 24H2+）

# 在 Windows 用户目录创建 %USERPROFILE%\.wslconfig
# 或编辑 /mnt/c/Users/<你的用户名>/.wslconfig
[wsl2]
networkingMode=mirrored
dnsTunneling=true
firewall=false
autoProxy=true

# 保存后在 PowerShell 中执行：
# wsl --shutdown
# wsl

✅ Mirrored 模式优点

WSL2 与 Windows 共享 IP 地址，局域网设备直接通过 Windows 的局域网 IP 访问 WSL2 内服务。无需端口转发，无需 netsh 配置。

方案 B：NAT + 端口转发（Windows 10 / 不支持 Mirrored 时）

# 1. 在 WSL2 中查看 IP
ip addr show eth0 | grep inet
# 假设得到 172.18.79.129

# 2. 在 Windows PowerShell（管理员）中添加端口转发
# 将 Windows 宿主机端口 → 转发到 WSL2 端口
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

# 3. 放行 Windows 防火墙
New-NetFirewallRule -DisplayName "WSL2 Agent Platform 8080" -Direction Inbound -LocalPort 8080 -Protocol TCP -Action Allow
New-NetFirewallRule -DisplayName "WSL2 Nacos 8848" -Direction Inbound -LocalPort 8848 -Protocol TCP -Action Allow

# 4. 查看已配置的转发规则
netsh interface portproxy show all

# 5. 删除转发规则（如果需要）
netsh interface portproxy delete v4tov4 listenport=8080 listenaddress=0.0.0.0

⚠️ NAT 端口转发注意事项

WSL2 重启后 IP 会变化，端口转发规则会失效。需要重新执行 step 2。建议写一个 PowerShell 脚本自动化此过程。

方案 C：nginx 反向代理（灵活但复杂）

在 Windows 宿主机安装 nginx，反向代理到 WSL2 内的服务。适合需要统一入口 + SSL + 认证的场景。

验证内网可达性

# 在 WSL2 内确认服务监听 0.0.0.0
ss -tlnp | grep -E "8080|8848|5432|9000"

# 在局域网另一台设备（手机/笔记本）浏览器访问：
# http://<Windows局域网IP>:8080/chatui   → Admin Studio
# http://<Windows局域网IP>:8848/nacos    → Nacos 控制台
# http://<Windows局域网IP>:9001          → MinIO 控制台

表：内网访问地址速查

服务	WSL2 内访问	局域网访问（Mirrored 模式）
Admin Studio	http://localhost:8080/chatui	http://<Windows-IP>:8080/chatui
Nacos 控制台	http://localhost:8848/nacos	http://<Windows-IP>:8848/nacos
MinIO 控制台	http://localhost:9001	http://<Windows-IP>:9001
PostgreSQL	localhost:5432	<Windows-IP>:5432
MinIO API	localhost:9000	<Windows-IP>:9000

运维手册

服务自启动

Docker 中间件自启动

Docker Compose 中已设置 restart: unless-stopped，WSL2 启动后 Docker daemon 运行即自动拉起中间件。

Spring Boot 应用自启动（systemd）

# 创建 systemd service 文件
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="DASHSCOPE_API_KEY=sk-your-key"
Environment="NACOS_CONFIG_NAMESPACE=sa-agent-config"
Environment="NACOS_MCP_NAMESPACE=sa-agent-mcp"
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

日志管理

# 查看应用日志（systemd 方式）
journalctl -u agent-platform -f -n 100

# 查看应用日志（直接运行方式）
tail -f logs/agent-platform.log

# Docker 中间件日志
docker compose logs -f postgres
docker compose logs -f nacos

数据备份

#!/bin/bash
# backup-agent-platform.sh — 每日备份脚本
BACKUP_DIR=/mnt/d/backups/agent-platform/$(date +%Y%m%d)
mkdir -p $BACKUP_DIR

# 1. PostgreSQL 备份
docker compose exec -T postgres pg_dump -U sa_agent spring_ai_agent > $BACKUP_DIR/pg_dump.sql

# 2. MinIO 数据备份
rsync -av /mnt/d/minio-data/ $BACKUP_DIR/minio-data/

# 3. Nacos 配置导出
curl -X GET "http://localhost:8848/nacos/v1/cs/configs?dataId=&group=&tenant=sa-agent-config&pageNo=1&pageSize=100" > $BACKUP_DIR/nacos-config.json

echo "Backup complete: $BACKUP_DIR"

版本升级

# 1. 检查当前版本
curl -s http://localhost:8080/actuator/info

# 2. 更新 pom.xml 中的版本号
#    spring-ai-alibaba.version → 新版本

# 3. 重建并重启
mvn clean package -DskipTests
sudo systemctl restart agent-platform

# 4. 验证
curl -s http://localhost:8080/actuator/health

故障排查

表：常见问题与解决方案

症状	可能原因	解决步骤
Nacos 连接超时	Nacos 未启动 / 端口冲突	1. `docker compose ps nacos` 检查容器状态 2. `ss -tlnp \| grep 8848` 检查端口 3. 检查 Nacos 日志 `docker compose logs nacos`
DashScope API 调用失败	API Key 无效 / 网络不通	1. `curl -H "Authorization: Bearer $DASHSCOPE_API_KEY" https://dashscope.aliyuncs.com/api/v1/models` 测试 2. 检查 WSL2 外网连通性 `ping dashscope.aliyuncs.com` 3. 检查环境变量是否注入 `echo $DASHSCOPE_API_KEY`
PostgreSQL 连接拒绝	PG 未启动 / 认证失败	1. `docker compose ps postgres` 检查容器 2. 手动测试 `psql -h localhost -U sa_agent -d spring_ai_agent` 3. 检查 pg_hba.conf 远程访问配置
Admin Studio 白屏	前端资源未构建 / 路径不对	1. 确认依赖包含 `spring-ai-alibaba-studio` 2. 访问 `http://localhost:8080/chatui/index.html` 3. 检查浏览器控制台 Network 错误
MCP Server 注册不到 Nacos	Nacos 命名空间不存在	1. 登录 Nacos 控制台检查 `sa-agent-mcp` 命名空间是否存在 2. 检查 application.yml 中 mcp.nacos.registry 配置 3. 查看应用日志 `grep "MCP" logs/*.log`
内网设备无法访问	WSL2 NAT 网络隔离	1. 确认 `server.address=0.0.0.0` 2. 试用 Mirrored 模式或端口转发（详见 S10） 3. `ss -tlnp \| grep 8080` 确认监听 0.0.0.0 而非 127.0.0.1
内存不足（OOM）	JVM 内存占用过大	1. 降低 JVM 参数 `-Xmx1g` 到 `-Xmx512m` 2. 减少 Nacos JVM：修改 nacos/bin/startup.sh 中的 `-Xms`/`-Xmx` 3. 检查是否有内存泄漏 `jmap -heap <pid>`
WSL2 重启后 IP 变化	WSL2 默认 DHCP	使用 Mirrored 模式（方案 A）彻底解决，或编写端口转发自动修复脚本

快速健康检查脚本

#!/bin/bash
# health-check.sh — 一键检测全平台状态
echo "=== Spring AI Alibaba 全平台健康检查 ==="

# 中间件
echo -n "[PostgreSQL] "; psql -h localhost -U sa_agent -d spring_ai_agent -c "SELECT 1" >/dev/null 2>&1 && echo "✅ OK" || echo "❌ FAIL"
echo -n "[Nacos] "; curl -s http://localhost:8848/nacos/v1/console/health/readiness >/dev/null && echo "✅ OK" || echo "❌ FAIL"
echo -n "[MinIO] "; curl -s http://localhost:9000/minio/health/live >/dev/null && echo "✅ OK" || echo "❌ FAIL"

# 应用
echo -n "[Agent Platform] "; curl -s http://localhost:8080/actuator/health >/dev/null && echo "✅ OK" || echo "❌ FAIL"
echo -n "[Admin Studio] "; curl -s -o /dev/null -w "%{http_code}" http://localhost:8080/chatui/index.html | grep "200" >/dev/null && echo "✅ OK" || echo "❌ FAIL"

# 外网模型
echo -n "[DashScope API] "; curl -s -o /dev/null -w "%{http_code}" https://dashscope.aliyuncs.com/api/v1/models -H "Authorization: Bearer $DASHSCOPE_API_KEY" | grep "200" >/dev/null && echo "✅ OK" || echo "❌ FAIL"