快速开始

欢迎使用 Astrsomn！本文档将帮助你快速部署 Astrsomn 服务端，或将 AI 能力引入你的 Spring Boot 项目。

第一部分：服务端部署

从下载安装包到启动服务，完整部署 Astrsomn Server。

1. 环境要求

部署前请确保已安装以下基础环境：

环境	版本要求	说明
JDK	17+	运行环境
MySQL	8.0+	数据存储
Node.js	18+	前端开发（仅源码构建需要）
Maven	3.8+	项目构建（仅源码构建需要）

2. 下载安装包

从 GitHub Releases 下载对应平台的打包产物。每个包已内嵌前端静态资源、数据库迁移脚本和启停脚本。

📦 下载地址： https://github.com/Astrsomn/Astrsomn/releases

平台	文件
Windows	`astrsomn-windows.zip`
Linux	`astrsomn-linux.tar.gz`
macOS	`astrsomn-macos.tar.gz`

解压后的目录结构：

astrsomn/
├── astrsomn-server.jar        # Spring Boot 主程序（内嵌前端）
├── config/
│   └── application.yml         # 配置文件
├── database/
│   └── V1__Initial.sql         # 数据库初始化脚本
├── bin/
│   ├── start.sh / start.bat    # 启动脚本
│   ├── stop.sh / stop.bat      # 停止脚本
│   └── .env                    # JVM 参数配置
└── VERSION                     # 版本号

3. 创建并初始化数据库

sql

-- 创建数据库
CREATE DATABASE astro_ai DEFAULT CHARACTER SET utf8mb4;

手动导入（可选）

如果不想依赖 Flyway 自动迁移，也可以手动执行 SQL：

bash

mysql -u root -p astro_ai < database/V1__Initial.sql

4. 修改应用配置

编辑 config/application.yml，填入你的 MySQL 连接信息：

yaml

# config/application.yml
spring:
  profiles:
    active: mysql

astrsomn:
  enabled: true
  datasource:
    url: jdbc:mysql://127.0.0.1:3306/astro_ai?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai&useSSL=false
    username: root
    password: root
    driver-class-name: com.mysql.cj.jdbc.Driver

server:
  port: 4481   # 默认端口

安全提醒

生产环境请务必修改默认的数据库密码和 JWT 密钥。

5. 启动服务

运行对应平台的启动脚本。可通过 .env 文件调整 JVM 参数。

WindowsLinux / macOS

bash

bin\start.bat

bash

chmod +x bin/*.sh
./bin/start.sh

关键启动参数（bin/.env）：

properties

JAVA_OPTS=-Xms256m -Xmx1024m -Dfile.encoding=UTF-8

参数	默认值	说明
`-Xms`	256m	初始堆内存
`-Xmx`	1024m	最大堆内存
`-Dfile.encoding`	UTF-8	文件编码
服务端口	4481	可在 `application.yml` 中修改

6. 访问系统

服务启动后，打开浏览器访问 http://localhost:4481。

项目	内容
访问地址	`http://localhost:4481`
默认用户名	`admin`
默认密码	`admin`

首次登录后

请立即修改默认密码！然后前往「控制台」完成以下初始配置：

模型实例 — 配置 AI 模型连接（API Key、端点等）
Agent 管理 — 创建你的第一个 AI Agent
账号管理 — 管理模型供应商的 API 账号

第二部分：框架引入

将 Astrsomn 作为 Maven 依赖接入你的 Spring Boot 项目，通过注解直接调用 AI 能力。

1. 添加 Maven 仓库

Astrsomn 发布在 Sonatype Central。Snapshot 版本需要添加 Snapshots 仓库：

xml

<!-- pom.xml -->
<repositories>
  <repository>
    <id>central</id>
    <url>https://repo1.maven.org/maven2</url>
  </repository>
  <repository>
    <id>sonatype-snapshots</id>
    <url>https://s01.oss.sonatype.org/content/repositories/snapshots</url>
    <snapshots><enabled>true</enabled></snapshots>
  </repository>
</repositories>

2. 引入 Runtime Starter

astrsomn-runtime-starter 是核心启动器，会自动托管模型、Memory 并在 Spring 容器内完成自动装配：

xml

<dependency>
  <groupId>com.astrsomn</groupId>
  <artifactId>astrsomn-runtime-starter</artifactId>
  <version>0.2.0-SNAPSHOT</version>
</dependency>

3. 引入模型 Provider

选择至少一个模型提供方。当前已适配多个主流 Provider：

DeepSeek（推荐）ZhipuOpenAI

xml

<dependency>
  <groupId>com.astrsomn</groupId>
  <artifactId>astrsomn-provider-deepseek</artifactId>
  <version>0.2.0-SNAPSHOT</version>
</dependency>

xml

<dependency>
  <groupId>com.astrsomn</groupId>
  <artifactId>astrsomn-provider-zhipu</artifactId>
  <version>0.2.0-SNAPSHOT</version>
</dependency>

xml

<dependency>
  <groupId>com.astrsomn</groupId>
  <artifactId>astrsomn-provider-openai</artifactId>
  <version>0.2.0-SNAPSHOT</version>
</dependency>

4. 配置数据源

确保你的项目已具备 Spring Boot + MyBatis-Plus + MySQL 驱动依赖，然后配置数据库连接：

yaml

# application.yml
spring:
  profiles:
    active: mysql

# application-mysql.yml
astrsomn:
  enabled: true
  datasource:
    url: jdbc:mysql://127.0.0.1:3306/astro_ai?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai&useSSL=false
    username: root
    password: root

5. 使用 @Astro 注入调用

在 Spring Boot 启动类上添加 @EnableAstroRuntime，然后在需要的地方使用 @Astro 注解注入 Assistant：

java

// 1. 启用框架
@EnableAstroRuntime
@SpringBootApplication
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

// 2. 在 Service 中使用 @Astro 注入
@Service
public class MyService {

    @Astro(agentKey = "MY-AGENT", envCode = "PRO")
    private AstroChatAssistant assistant;

    public void demo() {
        String reply = assistant.chat("你好，Astrsomn！", "session-001");
        System.out.println(reply);
    }
}

@Astro 注解参数说明

参数	类型	说明
`agentKey`	String	Agent 唯一标识，需在控制台预先创建
`envCode`	String	环境编码，用于多环境隔离
`promptKey`	String	关联的 Prompt 模板标识（可选）
`enableStream`	boolean	是否启用流式输出（可选）
`enableNetwork`	boolean	是否启用网络搜索（可选）
`enableDeepThinking`	boolean	是否启用深度思考（可选）

下一步

框架使用 — 深入了解模型配置、MCP、工具、Prompt 等功能
框架开发 — 学习如何扩展自定义 Provider、向量库、MCP
项目架构 — 了解项目整体架构与模块设计

快速开始 ​

第一部分：服务端部署 ​

1. 环境要求 ​

2. 下载安装包 ​

3. 创建并初始化数据库 ​

4. 修改应用配置 ​

5. 启动服务 ​

6. 访问系统 ​

第二部分：框架引入 ​

1. 添加 Maven 仓库 ​

2. 引入 Runtime Starter ​

3. 引入模型 Provider ​

4. 配置数据源 ​

5. 使用 @Astro 注入调用 ​

下一步 ​

快速开始

第一部分：服务端部署

1. 环境要求

2. 下载安装包

3. 创建并初始化数据库

4. 修改应用配置

5. 启动服务

6. 访问系统

第二部分：框架引入

1. 添加 Maven 仓库

2. 引入 Runtime Starter

3. 引入模型 Provider

4. 配置数据源

5. 使用 @Astro 注入调用

下一步