生产环境部署

本文介绍如何将 Snail AI 部署到生产环境，涵盖硬件规划、JVM 调优、Nginx 反向代理、HTTPS 配置、数据库选型以及向量数据库容量规划等关键主题。

硬件资源推荐

服务端（Snail AI Server）

规模	CPU	内存	磁盘	适用场景
小型（试用）	2 核	4 GB	50 GB SSD	10 人以内体验评估
中型（团队）	4 核	8 GB	100 GB SSD	50 人以内日常使用
大型（企业）	8 核+	16 GB+	500 GB+ SSD	100+ 用户，高并发场景

数据库服务器

组件	CPU	内存	磁盘	说明
MySQL / PostgreSQL	2-4 核	4-8 GB	100 GB+ SSD	推荐 SSD 以保证 IO 性能
PgVector	2-4 核	4-8 GB	按向量规模计算	与 PG 共用实例时合并计算
Milvus	4-8 核	8-16 GB	200 GB+ SSD	独立部署，需 etcd + MinIO
Elasticsearch	4-8 核	8-16 GB	200 GB+ SSD	推荐 3 节点集群

Agent Client 节点

场景	CPU	内存	说明
轻量级（仅 LLM 调用）	2 核	2 GB	无本地工具执行
标准（含工具执行）	4 核	4 GB	含 Shell / HTTP / MCP 工具执行
重量级（含本地模型）	8 核+	16 GB+	运行 Ollama 本地模型

网络要求

Server 与 Client 之间需保证 gRPC 连接稳定，推荐内网部署或 VPN 互通
Server 需能访问外部 LLM API（如 OpenAI、Claude），请确保出站网络畅通
建议使用固定 IP 或内部 DNS，避免因 IP 漂移导致连接中断

JVM 调优

堆内存配置

bash

# 推荐生产环境 JVM 参数
JAVA_OPTS="-Xms2g -Xmx4g \
  -XX:+UseG1GC \
  -XX:MaxGCPauseMillis=200 \
  -XX:G1HeapRegionSize=8m \
  -XX:+ParallelRefProcEnabled \
  -XX:InitiatingHeapOccupancyPercent=45 \
  -XX:+HeapDumpOnOutOfMemoryError \
  -XX:HeapDumpPath=/app/logs/heapdump.hprof \
  -Djava.security.egd=file:/dev/./urandom \
  -Dfile.encoding=UTF-8"

内存规划建议

用户规模	堆内存 (-Xms / -Xmx)	MetaSpace	说明
10 人以内	512 MB / 1 GB	默认	试用评估
50 人以内	1 GB / 2 GB	256 MB	团队使用
100+ 用户	2 GB / 4 GB	512 MB	企业生产
高并发	4 GB / 8 GB	512 MB	大量并发对话

GC 日志开启

生产环境建议开启 GC 日志，便于性能分析：

bash

JAVA_OPTS="$JAVA_OPTS \
  -Xlog:gc*:file=/app/logs/gc.log:time,uptime,level,tags:filecount=10,filesize=50m"

Nginx 反向代理配置

基础配置（HTTP）

nginx

upstream snail_ai_backend {
    server 127.0.0.1:8080;
    keepalive 32;
}

server {
    listen 80;
    server_name ai.example.com;

    # 静态资源 -- 前端构建产物
    root /var/www/snail-ai-admin/dist;
    index index.html;

    # 前端路由 -- SPA History 模式
    location / {
        try_files $uri $uri/ /index.html;
    }

    # API 代理
    location /api/ {
        proxy_pass http://snail_ai_backend/;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Connection "";

        # SSE 流式输出必须关闭缓冲
        proxy_buffering off;
        proxy_cache off;
        proxy_read_timeout 300s;
        proxy_send_timeout 300s;
        chunked_transfer_encoding on;
    }

    # 文件上传大小限制
    client_max_body_size 100m;

    # Gzip 压缩
    gzip on;
    gzip_types text/plain application/json application/javascript text/css text/xml;
    gzip_min_length 1024;
    gzip_comp_level 5;

    # 安全头
    add_header X-Frame-Options SAMEORIGIN;
    add_header X-Content-Type-Options nosniff;
    add_header X-XSS-Protection "1; mode=block";
}

HTTPS / SSL 配置

生产环境强烈建议启用 HTTPS。以下配置使用 Let's Encrypt 证书：

nginx

server {
    listen 80;
    server_name ai.example.com;
    # HTTP 强制跳转 HTTPS
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name ai.example.com;

    # SSL 证书配置
    ssl_certificate /etc/letsencrypt/live/ai.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/ai.example.com/privkey.pem;

    # SSL 安全参数
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384;
    ssl_prefer_server_ciphers on;
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 10m;

    # HSTS
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

    # ---------- 以下与 HTTP 版相同 ----------
    root /var/www/snail-ai-admin/dist;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    location /api/ {
        proxy_pass http://snail_ai_backend/;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Connection "";
        proxy_buffering off;
        proxy_cache off;
        proxy_read_timeout 300s;
        proxy_send_timeout 300s;
        chunked_transfer_encoding on;
    }

    client_max_body_size 100m;
    gzip on;
    gzip_types text/plain application/json application/javascript text/css text/xml;
    gzip_min_length 1024;
    gzip_comp_level 5;
}

使用 Certbot 自动申请证书

bash

# 安装 Certbot
apt install certbot python3-certbot-nginx

# 申请证书（自动修改 Nginx 配置）
certbot --nginx -d ai.example.com

# 设置自动续期
systemctl enable certbot.timer

多数据库选型指南

Snail AI 原生支持 5 种关系型数据库，以下为各数据库的对比和选型建议：

特性	MySQL	PostgreSQL	SQL Server	达梦 (DM)	MariaDB
开源许可	GPL	PostgreSQL License	商业付费	商业付费	GPL
信创合规	--	--	--	国产数据库，全面适配	--
向量扩展	不支持	PgVector 原生支持	不支持	不支持	不支持
生态成熟度	极高	高	高（企业市场）	中（国内政企）	高
运维复杂度	低	中	中	中	低
适用场景	互联网团队，熟悉 MySQL 生态	需要向量+关系数据库合一	已有 SQL Server 基础设施	政企信创项目	MySQL 替代方案
高可用	主从复制、MGR	流复制、Patroni	AlwaysOn	DM 集群	Galera Cluster
连接配置	`jdbc:mysql://`	`jdbc:postgresql://`	`jdbc:sqlserver://`	`jdbc:dm://`	`jdbc:mariadb://`

选型建议

场景	推荐数据库	理由
初次体验 / 快速上手	MySQL	最广泛使用，社区资源丰富，运维简单
需要向量+关系合一	PostgreSQL + PgVector	一个实例同时承担关系存储和向量存储，架构最简
政企信创项目	达梦 (DM)	国产数据库，满足信创合规要求
已有 SQL Server 基础设施	SQL Server	与现有 IT 基础设施保持一致，降低运维成本
追求 MySQL 兼容 + 更开放许可	MariaDB	与 MySQL 高度兼容，社区更活跃

向量数据库容量规划

PgVector vs Milvus vs Elasticsearch 选型

特性	PgVector	Milvus	Elasticsearch
定位	PostgreSQL 向量扩展	专业向量数据库	搜索引擎 + 向量检索
部署复杂度	低（PG 扩展即可）	中-高（需 etcd + MinIO）	中（推荐集群模式）
适合数据量	< 500 万向量	500 万 - 10 亿+向量	< 1000 万向量
检索性能	良好（IVFFlat/HNSW）	优秀（专业优化）	良好（近似最近邻）
混合检索	需自行实现	原生支持	原生 BM25 + 向量
运维成本	低	中-高	中
资源占用	低	高	中-高

容量规划参考

以 1536 维向量（OpenAI text-embedding-3-small）为例：

文档数量	预估分片数	向量存储空间	推荐方案	内存建议
1,000 篇	~10,000	~60 MB	PgVector	2 GB
10,000 篇	~100,000	~600 MB	PgVector	4 GB
100,000 篇	~1,000,000	~6 GB	PgVector / Milvus	8 GB
1,000,000 篇	~10,000,000	~60 GB	Milvus	16 GB+
10,000,000+ 篇	~100,000,000+	~600 GB+	Milvus 集群	64 GB+（分布式）

计算公式

单向量存储空间 ≈ 维度数 x 4 字节（float32）= 1536 x 4 = 6,144 字节 ≈ 6 KB。索引额外开销约为原始数据的 1.5-2 倍。

各方案推荐场景

场景	推荐方案	说明
中小企业，文档 < 10 万篇	PgVector	架构最简，与 PostgreSQL 共用实例，运维成本最低
大型企业，文档 10 万 - 1000 万篇	Milvus	专业向量数据库，检索性能优异，支持水平扩展
需要混合检索（向量 + 全文）	Elasticsearch	原生支持 BM25 + 向量检索，适合对全文检索有较高要求的场景
信创环境	PgVector	可配合国产 PG 衍生数据库使用

多节点 Agent Client 部署

在生产环境中，通常需要部署多个 Agent Client 节点以实现负载均衡和高可用。

部署架构

部署步骤

1. 在管理后台创建应用

进入「应用管理」页面，创建一个新应用，获取 appId 和 token。

2. 在各节点配置并启动 Client

每个 Client 节点的 application.yml：

yaml

snail-ai:
  app-id: ${APP_ID}          # 管理后台分配的应用 ID
  token: ${APP_TOKEN}        # 管理后台分配的 Token
  server:
    host: ${SERVER_HOST}     # Server 地址
    port: 18888              # Server gRPC 端口
  client:
    name: ${NODE_NAME}       # 节点名称，建议唯一（如 client-node-01）

3. 配置路由策略

在应用详情页配置路由策略：

策略	适用场景
轮询路由	多节点负载均衡，推荐默认使用
随机路由	简单场景，节点间无状态差异
指定节点	特定智能体需要使用特定节点的资源

4. 监控节点状态

通过管理后台的「应用管理」→「客户端节点」页面，可以实时查看各节点的连接状态、心跳时间和负载情况。

注意事项

确保所有 Client 节点到 Server 的 gRPC 端口（默认 18888）网络畅通
Client 节点应配置相同的 app-id 和 token 以加入同一应用
节点下线时 Server 会自动感知并将流量切换到其他可用节点
建议至少部署 2 个 Client 节点以实现高可用

系统服务化部署

使用 systemd 管理服务（Linux）

创建 /etc/systemd/system/snail-ai-server.service：

ini

[Unit]
Description=Snail AI Server
After=network.target mysql.service

[Service]
Type=simple
User=snailai
Group=snailai
WorkingDirectory=/opt/snail-ai
ExecStart=/usr/bin/java ${JAVA_OPTS} -jar snail-ai-starter.jar
ExecStop=/bin/kill -SIGTERM $MAINPID
Restart=on-failure
RestartSec=10
StandardOutput=journal
StandardError=journal
LimitNOFILE=65536
LimitNPROC=4096

Environment="JAVA_OPTS=-Xms2g -Xmx4g -XX:+UseG1GC -XX:MaxGCPauseMillis=200"
EnvironmentFile=/opt/snail-ai/.env

[Install]
WantedBy=multi-user.target

bash

# 加载配置
systemctl daemon-reload

# 启动服务
systemctl start snail-ai-server

# 设置开机自启
systemctl enable snail-ai-server

# 查看状态
systemctl status snail-ai-server

# 查看日志
journalctl -u snail-ai-server -f

生产环境检查清单

部署到生产环境前，请逐项确认以下配置：

[ ] 修改默认密码：修改 admin 账号默认密码，修改数据库默认密码
[ ] 配置加密密钥：设置 SNAIL_AI_CRYPTO_KEY 和 SNAIL_AI_CRYPTO_IV
[ ] 启用 HTTPS：配置 SSL 证书，强制 HTTPS 访问
[ ] JVM 调优：根据服务器配置调整堆内存和 GC 参数
[ ] 数据库备份：配置定期自动备份策略
[ ] 日志管理：配置日志轮转，避免磁盘写满
[ ] 监控告警：配置 CPU、内存、磁盘使用率告警
[ ] 防火墙：仅开放必要端口（80/443 对外，8080/18888 内网）
[ ] 文件存储：生产环境推荐使用 MinIO 而非本地存储
[ ] 向量数据库：根据数据规模选择合适的向量存储方案

下一步

配置参考 -- 完整的配置项说明
升级指南 -- 版本升级步骤
故障排除 -- 常见问题排查

生产环境部署 ​

硬件资源推荐 ​

服务端（Snail AI Server） ​

数据库服务器 ​

Agent Client 节点 ​

JVM 调优 ​

堆内存配置 ​

内存规划建议 ​

GC 日志开启 ​

Nginx 反向代理配置 ​

基础配置（HTTP） ​

HTTPS / SSL 配置 ​

使用 Certbot 自动申请证书 ​

多数据库选型指南 ​

选型建议 ​

向量数据库容量规划 ​

PgVector vs Milvus vs Elasticsearch 选型 ​

容量规划参考 ​

各方案推荐场景 ​

多节点 Agent Client 部署 ​

部署架构 ​

部署步骤 ​

系统服务化部署 ​

使用 systemd 管理服务（Linux） ​

生产环境检查清单 ​

下一步 ​

生产环境部署

硬件资源推荐

服务端（Snail AI Server）

数据库服务器

Agent Client 节点

JVM 调优

堆内存配置

内存规划建议

GC 日志开启

Nginx 反向代理配置

基础配置（HTTP）

HTTPS / SSL 配置

使用 Certbot 自动申请证书

多数据库选型指南

选型建议

向量数据库容量规划

PgVector vs Milvus vs Elasticsearch 选型

容量规划参考

各方案推荐场景

多节点 Agent Client 部署

部署架构

部署步骤

系统服务化部署

使用 systemd 管理服务（Linux）

生产环境检查清单

下一步