配置参考

本文档提供 Snail AI 后端服务 application.yml 的完整配置项说明，涵盖数据库连接、向量存储、gRPC 通信、文件存储、记忆系统、模型默认值、加密等全部配置。

完整配置示例

yaml

# ============================================================
# Snail AI Server 配置参考
# ============================================================

server:
  port: 8080                          # HTTP 服务端口

spring:
  application:
    name: snail-ai-server

  # ----------------------------------------------------------
  # 数据源配置
  # ----------------------------------------------------------
  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
    hikari:
      maximum-pool-size: 20           # 连接池最大连接数
      minimum-idle: 5                 # 最小空闲连接数
      idle-timeout: 600000            # 空闲连接超时（毫秒）
      connection-timeout: 30000       # 获取连接超时（毫秒）
      max-lifetime: 1800000           # 连接最大存活时间（毫秒）

  # ----------------------------------------------------------
  # 文件上传限制
  # ----------------------------------------------------------
  servlet:
    multipart:
      max-file-size: 100MB
      max-request-size: 100MB


# ============================================================
# Snail AI 业务配置
# ============================================================
snail-ai:
  server:
    grpc-port: 18888
  skill:
    upload-dir: ./upload/skills
  crypto:
    secret-key: ${SNAIL_AI_CRYPTO_KEY:0123456789abcdef0123456789abcdef}
    iv: ${SNAIL_AI_CRYPTO_IV:fedcba9876543210fedcba9876543210}
  resource:
    storage-type: LOCAL
    upload-dir: ./upload/resource
    minio:
      endpoint: http://localhost:9000
      access-key: minioadmin
      secret-key: minioadmin
      bucket: snail-ai
  # 短期记忆配置
  memory:
    short-term:
      # 存储类型选项: memory(内存) | db(数据库)
      # - memory: 适用于单机部署，高性能，重启后数据丢失
      # - db: 适用于分布式部署，数据持久化，性能较低
      store-type: memory
           # 存储桶名称

数据库连接配置详解

Snail AI 支持 5 种关系型数据库，以下为各数据库的连接配置示例。

MySQL

yaml

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

参数	说明
`useUnicode=true`	启用 Unicode 编码
`characterEncoding=utf-8`	字符编码设为 UTF-8
`serverTimezone=Asia/Shanghai`	时区设置
`allowPublicKeyRetrieval=true`	允许公钥检索（MySQL 8 新认证方式需要）
`useSSL=false`	关闭 SSL（内网部署可关闭，公网建议开启）

PostgreSQL

yaml

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

PostgreSQL + PgVector 共用实例

如果关系数据库也使用 PostgreSQL，向量存储的 PgVector 数据源可以指向同一个实例，但建议使用不同的 schema 或数据库以便管理：

yaml

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

PgVector 数据源可通过以下配置指定独立连接：

yaml

spring:
  datasource:
    pgvector:
      url: jdbc:postgresql://localhost:5432/snail_ai_vector
      username: postgres
      password: your_password

SQL Server

yaml

spring:
  datasource:
    url: jdbc:sqlserver://localhost:1433;databaseName=snail_ai;encrypt=false;trustServerCertificate=true
    username: sa
    password: your_password
    driver-class-name: com.microsoft.sqlserver.jdbc.SQLServerDriver

参数	说明
`encrypt=false`	关闭传输加密（内网可关闭）
`trustServerCertificate=true`	信任服务端证书

达梦数据库 (DM)

yaml

spring:
  datasource:
    url: jdbc:dm://localhost:5236/snail_ai
    username: SYSDBA
    password: your_password
    driver-class-name: dm.jdbc.driver.DmDriver

达梦数据库注意事项

需要手动将达梦 JDBC 驱动 DmJdbcDriver.jar 安装到 Maven 本地仓库或放到项目 lib/ 目录
达梦默认端口为 5236
表名和字段名默认大写，如果遇到大小写问题，可在 JDBC URL 中添加 ?QUOTE_CASE_SENSITIVITY=false
初始化 SQL 脚本请使用 docs/sql/ 目录下的达梦专用版本

MariaDB

yaml

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

MariaDB 配置与 MySQL 类似，但需注意：

驱动类使用 org.mariadb.jdbc.Driver 而非 com.mysql.cj.jdbc.Driver
JDBC URL 前缀使用 jdbc:mariadb:// 而非 jdbc:mysql://

向量存储配置详解

PgVector

yaml

spring:
  ai:
    vectorstore:
      pgvector:
        enabled: true
        dimensions: 1536              # 向量维度（需与 Embedding 模型匹配）
        distance-type: cosine_distance # 距离类型：cosine_distance / euclidean_distance / negative_inner_product
        index-type: hnsw              # 索引类型：hnsw / ivfflat
  datasource:
    pgvector:
      url: jdbc:postgresql://localhost:5432/snail_ai_vector
      username: postgres
      password: your_password

PgVector 扩展安装

首次使用 PgVector 需要在 PostgreSQL 中安装扩展：

sql

CREATE EXTENSION IF NOT EXISTS vector;

Client 端 gRPC 配置

Agent Client 的 application.yml 中配置 Server 连接：

yaml

snail-ai:
  app-id: your-app-id                 # 应用 ID（管理后台分配）
  token: your-token                    # 应用 Token（管理后台分配）
  server:
    host: 192.168.1.100               # Server 地址
    port: 18888                        # Server gRPC 端口
  client:
    name: client-node-01              # 客户端节点名称
    heartbeat-interval: 30s           # 心跳间隔
    reconnect-interval: 5s            # 断线重连间隔
    max-reconnect-attempts: -1        # 最大重连次数（-1 为无限重试）

文件存储配置详解

本地存储

yaml

snail-ai:
  storage:
    type: LOCAL
    local:
      path: /data/snail-ai/storage    # 存储根路径

WARNING

本地存储仅适合单节点部署或开发测试环境。生产环境推荐使用 MinIO 对象存储，以便支持多节点共享和数据冗余。

MinIO 对象存储

yaml

snail-ai:
  storage:
    type: MINIO
    minio:
      endpoint: http://minio.example.com:9000
      access-key: ${MINIO_ACCESS_KEY}
      secret-key: ${MINIO_SECRET_KEY}
      bucket: snail-ai
      region: us-east-1               # 可选，部分 S3 兼容存储需要

记忆系统配置

yaml

snail-ai:
  memory:
    storage: memory                    # 存储方式
    sliding-window-size: 20            # 短期记忆窗口大小（对话轮数）

参数	可选值	说明
`storage`	`memory`	记忆数据存储在应用内存中，重启后丢失
`storage`	`db`	记忆数据持久化到数据库，重启后保留
`sliding-window-size`	正整数	短期记忆保留的最近对话轮数，默认 20

建议

开发/测试环境使用 memory 模式，启动快、无额外依赖
生产环境推荐使用 db 模式，确保记忆数据不因重启丢失
sliding-window-size 建议设置为 10-30，过大会增加上下文 Token 消耗

加密配置

Snail AI 使用 AES 对称加密保护敏感数据（如模型 API Key、数据库密码等）。

yaml

snail-ai:
  crypto:
    key: ${SNAIL_AI_CRYPTO_KEY}       # 16 位 AES 密钥
    iv: ${SNAIL_AI_CRYPTO_IV}         # 16 位 AES 初始化向量

密钥生成方式

bash

# 生成随机 16 位密钥
openssl rand -hex 8
# 输出示例：a1b2c3d4e5f6a7b8

# 生成随机 16 位 IV
openssl rand -hex 8
# 输出示例：1a2b3c4d5e6f7a8b

然后通过环境变量注入：

bash

export SNAIL_AI_CRYPTO_KEY=a1b2c3d4e5f6a7b8
export SNAIL_AI_CRYPTO_IV=1a2b3c4d5e6f7a8b

安全警告

加密密钥请勿硬编码在配置文件中，务必通过环境变量注入
密钥一旦设定并有数据加密后，不可更换，否则已加密数据将无法解密
请妥善备份加密密钥，密钥丢失将导致加密数据不可恢复

模型默认配置

yaml

snail-ai:
  model:
    default-temperature: 0.7          # 默认温度（0.0 - 2.0）
    default-max-tokens: 4096          # 默认最大输出 Token 数
    request-timeout: 120s             # 模型 API 请求超时

参数	默认值	说明
`default-temperature`	`0.7`	控制生成的随机性。0 = 确定性输出，1+ = 更随机
`default-max-tokens`	`4096`	单次回复的最大 Token 数量
`request-timeout`	`120s`	模型 API 调用的超时时间。长文本生成可适当增大

环境变量覆盖

所有 YAML 配置项均可通过环境变量覆盖，规则为将配置路径中的 . 替换为 _，- 替换为 _，并转为大写。

YAML 配置路径	环境变量名
`spring.datasource.url`	`SPRING_DATASOURCE_URL`
`spring.datasource.password`	`SPRING_DATASOURCE_PASSWORD`
`grpc.server.port`	`GRPC_SERVER_PORT`
`snail-ai.storage.type`	`SNAIL_AI_STORAGE_TYPE`
`snail-ai.crypto.key`	`SNAIL_AI_CRYPTO_KEY`

Docker 部署和 CI/CD 流水线中推荐使用环境变量方式覆盖敏感配置，避免将密码等信息写入配置文件。

日志配置

yaml

logging:
  level:
    root: INFO
    com.opensnail.snailai: DEBUG      # Snail AI 业务日志级别
    org.springframework.ai: INFO      # Spring AI 框架日志
    io.grpc: WARN                     # gRPC 日志
  file:
    name: /app/logs/snail-ai.log      # 日志文件路径
  logback:
    rollingpolicy:
      max-file-size: 100MB            # 单文件最大大小
      max-history: 30                 # 保留天数
      total-size-cap: 3GB             # 日志总大小上限

下一步

Docker 部署 -- 使用 Docker Compose 快速部署
生产环境部署 -- 高可用和性能调优
升级指南 -- 版本升级步骤
故障排除 -- 常见问题排查

配置参考 ​

完整配置示例 ​

数据库连接配置详解 ​

MySQL ​

PostgreSQL ​

SQL Server ​

达梦数据库 (DM) ​

MariaDB ​

向量存储配置详解 ​

PgVector ​

Client 端 gRPC 配置 ​

文件存储配置详解 ​

本地存储 ​

MinIO 对象存储 ​

记忆系统配置 ​

加密配置 ​

密钥生成方式 ​

模型默认配置 ​

环境变量覆盖 ​

日志配置 ​

下一步 ​

配置参考

完整配置示例

数据库连接配置详解

MySQL

PostgreSQL

SQL Server

达梦数据库 (DM)

MariaDB

向量存储配置详解

PgVector

Client 端 gRPC 配置

文件存储配置详解

本地存储

MinIO 对象存储

记忆系统配置

加密配置

密钥生成方式

模型默认配置

环境变量覆盖

日志配置

下一步