快速开始

本指南将帮助你在本地环境快速搭建并运行 Snail AI 平台。

环境准备

在开始之前，请确保本地已安装以下软件：

软件	最低版本	说明
Java (JDK)	21+	推荐使用 OpenJDK 或 GraalVM
Maven	3.8+	后端构建工具
Node.js	20+	前端运行环境
pnpm	10+	前端包管理器，npm install -g pnpm 安装
MySQL	8.0+	或 PostgreSQL / SQL Server / 达梦 / MariaDB
向量数据库	--	推荐 PgVector（随 PostgreSQL 安装），也可选 Milvus 或 Elasticsearch

数据库选择建议

如果你使用 PostgreSQL 作为关系型数据库，可以同时安装 PgVector 扩展，这样只需一个数据库实例即可同时满足业务存储和向量存储需求。

第一步：克隆仓库

分别克隆后端和前端代码仓库：

# 克隆后端仓库
git clone https://gitee.com/aizuda/snail-ai.git

# 克隆前端仓库
git clone https://gitee.com/opensnail/snail-ai-admin.git

第二步：数据库初始化

创建数据库

CREATE DATABASE snail_ai DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;

导入表结构

在后端仓库的 docs/sql/ 目录下找到对应数据库的初始化脚本，执行导入：

# MySQL 示例
mysql -u root -p snail_ai < docs/sql/snail_ai_schema.sql

注意

不同数据库类型使用不同的 SQL 文件，请根据你选择的数据库选取正确的脚本。

第三步：配置后端

编辑后端启动模块的配置文件：

snail-ai/snail-ai-starter/src/main/resources/application.yml

数据库连接配置

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/snail_ai?useUnicode=true&characterEncoding=utf-8&serverTimezone=Asia/Shanghai
    username: root
    password: your_password
    driver-class-name: com.mysql.cj.jdbc.Driver

PostgreSQL 配置示例

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/snail_ai
    username: postgres
    password: your_password
    driver-class-name: org.postgresql.Driver

第四步：启动后端

在后端项目根目录下执行：

cd snail-ai
mvn spring-boot:run -pl snail-ai-starter

启动成功后，将会暴露以下端口：

端口	协议	说明
8080	HTTP	REST API 和 SSE 推送
18888	gRPC	Agent Client 通信端口

看到类似以下日志说明启动成功：

Started SnailAiApplication in X.XXX seconds
gRPC Server started, listening on port 18888

第六步：登录与体验

1. 登录系统

打开浏览器访问 http://localhost:8080/snail-ai，使用默认管理员账号登录：

• 用户名： admin
• 密码： SnailAi123456

2. 配置模型

3. 创建一个应用

比如: appI的=snail-ai-agent-demo, token: 页面复制token

3. 创建第一个智能体

登录后进入智能体管理页面，点击「新建智能体」按钮：

1. 描述你想要的智能体
2. 由Ai自动生成名称、描述、预设问题、欢迎语等

4. 开始第一次对话

在智能体详情页或对话入口，选择刚创建的智能体，输入问题开始对话：

下一步

• 配置更多大模型提供商 -- 参见 模型管理
• 创建 RAG 知识库 -- 参见 RAG 知识库
• 接入 MCP 工具 -- 参见 MCP 集成
• 部署到生产环境 -- 参见 部署指南