self-hosted-ai-starter-kit完全指南：从安装到生产环境全流程

【免费下载链接】self-hosted-ai-starter-kit The Self-hosted AI Starter Kit is an open-source template that quickly sets up a local AI environment. Curated by n8n, it provides essential tools for creating secure, self-hosted AI workflows. 项目地址: https://gitcode.com/GitHub_Trending/se/self-hosted-ai-starter-kit

引言：告别AI部署困境，本地智能工作流零门槛搭建

你是否还在为以下问题困扰？

• 云端AI服务数据隐私风险高，企业敏感数据不敢上云
• 本地部署AI工具链组件繁多，Docker配置复杂且兼容性差
• LLM模型部署、向量数据库集成、工作流编排难以协同
• 不同硬件环境（CPU/GPU/AMD/NVIDIA）适配成本高

本文将系统解决以上痛点，通过self-hosted-ai-starter-kit实现从0到1的本地化AI环境搭建。读完你将获得：
✅ 跨硬件环境的一键部署方案（CPU/NVIDIA GPU/AMD GPU/Mac）
✅ 完整的本地AI技术栈（低代码编排+LLM运行时+向量数据库）
✅ 生产级环境配置指南（安全加固/性能调优/监控备份）
✅ 企业级工作流实战案例（文档分析/智能客服/数据处理）

技术架构全景：四大核心组件协同工作流

self-hosted-ai-starter-kit采用微服务架构，通过Docker Compose实现组件解耦与协同。以下是系统架构的核心组件与数据流向：

核心组件功能解析

组件名称	技术定位	核心功能	占用端口	数据存储路径
n8n	低代码工作流引擎	400+集成能力，AI节点编排，可视化流程设计	5678	/home/node/.n8n
Ollama	LLM本地运行时	一键部署Llama3/Gemma/Mistral等模型，GPU加速推理	11434	/root/.ollama
Qdrant	向量数据库	高维向量存储与检索，近似最近邻搜索	6333	/qdrant/storage
PostgreSQL	关系型数据库	存储工作流配置、凭证信息、运行日志	5432	/var/lib/postgresql/data

架构优势：组件间通过Docker网络隔离通信，各自使用独立存储卷，确保数据持久化与服务隔离。n8n作为中枢神经系统，串联LLM推理、向量检索与外部系统集成。

环境准备：硬件与软件兼容性矩阵

最低硬件配置要求

环境类型	CPU核心	内存	存储	GPU要求（可选）	适用场景
开发测试环境	4核	16GB	100GB SSD	无	流程调试，小型模型（7B参数）
生产入门环境	8核	32GB	500GB SSD	NVIDIA GTX 16GB	企业内部工具，中等模型（13B参数）
高性能环境	16核	64GB	2TB NVMe	NVIDIA A100/AMD MI250	高并发服务，大型模型（70B参数）

注意：Mac用户需确保使用Apple Silicon芯片（M1/M2/M3），Intel芯片仅支持CPU模式且性能受限。

必备软件依赖

• Docker Engine 20.10+
• Docker Compose v2+
• Git 2.30+
• 网络连接（首次启动需下载镜像，总量约5GB）

Linux系统额外依赖：

# Ubuntu/Debian
sudo apt update && sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
sudo usermod -aG docker $USER  # 允许当前用户运行docker命令（需重启终端）

# CentOS/RHEL
sudo yum install -y yum-utils
sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
sudo yum install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

极速部署：五分钟启动全栈AI环境

1. 获取项目代码

git clone https://gitcode.com/GitHub_Trending/se/self-hosted-ai-starter-kit.git
cd self-hosted-ai-starter-kit

2. 环境变量配置

cp .env.example .env  # 复制环境变量模板
# 使用文本编辑器修改关键配置（推荐VSCode或nano）
nano .env

核心环境变量说明（必须修改的安全项）：

# 数据库安全配置（生产环境必须修改）
POSTGRES_USER=aiadmin          # 默认：root
POSTGRES_PASSWORD=StrongP@ssw0rd  # 默认：password
POSTGRES_DB=aistack            # 默认：n8n

# 安全密钥（使用openssl rand -hex 32生成随机值）
N8N_ENCRYPTION_KEY=your-32-byte-encryption-key-here
N8N_USER_MANAGEMENT_JWT_SECRET=your-jwt-secret-here

# 存储路径自定义（可选）
# N8N_STORAGE_PATH=/data/n8n
# OLLAMA_STORAGE_PATH=/data/ollama

3. 启动命令（按硬件类型选择）

3.1 NVIDIA GPU用户（推荐）

# 首次启动（自动下载镜像并初始化）
docker compose --profile gpu-nvidia up -d

# 查看Ollama模型下载进度
docker logs -f ollama-pull-llama

3.2 AMD GPU用户

docker compose --profile gpu-amd up -d

3.3 纯CPU用户（性能有限）

docker compose --profile cpu up -d

3.4 Mac用户（Apple Silicon）

# 第一步：本地安装Ollama
brew install ollama && ollama serve &

# 第二步：修改.env文件
echo "OLLAMA_HOST=host.docker.internal:11434" >> .env

# 第三步：启动套件
docker compose up -d

4. 验证部署状态

# 检查服务状态（所有服务应显示healthy/running）
docker compose ps

# 查看资源占用
docker stats --no-stream

预期输出：

NAME                   IMAGE                       COMMAND                  SERVICE             STATUS              PORTS
n8n                    n8nio/n8n:latest            "/docker-entrypoint.…"   n8n                 running (healthy)   0.0.0.0:5678->5678/tcp
postgres               postgres:16-alpine          "docker-entrypoint.s…"   postgres            running (healthy)   5432/tcp
qdrant                 qdrant/qdrant               "./entrypoint.sh"        qdrant              running             0.0.0.0:6333->6333/tcp
ollama-gpu             ollama/ollama:latest        "/bin/ollama serve"      ollama-gpu          running             0.0.0.0:11434->11434/tcp

界面初探：n8n工作流平台核心功能

访问与初始化

1. 打开浏览器访问：http://localhost:5678
2. 首次登录创建管理员账户（用户名/密码）
3. 系统自动导入示例凭证与工作流（位于n8n/demo-data目录）

核心界面区域

示例工作流体验

1. 在左侧菜单选择 Workflows → srOnR8PAY3u4RSwb（示例工作流）
2. 点击画布底部的 Chat 按钮打开交互面板
3. 输入问题：请总结self-hosted-ai-starter-kit的核心组件
4. 观察流程执行过程，查看Ollama节点调用与Qdrant向量检索

工作流解析：该示例演示了文档加载→文本分割→向量存储→LLM问答的完整RAG流程，所有数据处理均在本地完成，无外部API调用。

核心功能深度应用

1. Ollama本地LLM管理

模型管理命令：

# 进入Ollama容器
docker exec -it ollama-gpu bash

# 查看已安装模型
ollama list

# 下载新模型（如gemma:7b）
ollama pull gemma:7b

# 模型性能调优（修改配置文件）
cat > /root/.ollama/config <<EOF
MODEL=llama3.2
NUM_THREAD=8
BATCH_SIZE=1024
EOF

n8n中切换模型：

1. 打开Ollama节点配置
2. 在"Model"下拉菜单选择已下载模型
3. 调整参数：温度（0.7）、最大 tokens（2048）、Top P（0.9）

2. Qdrant向量数据库操作

Web控制台：访问 http://localhost:6333/dashboard 管理向量集合

通过n8n操作Qdrant：

// 在Code节点中使用Qdrant API
const qdrant = new QdrantClient({ host: 'qdrant', port: 6333 });

// 创建集合
await qdrant.createCollection('company_docs', {
  vectors: { size: 768, distance: 'Cosine' }
});

// 插入向量
await qdrant.upsert('company_docs', {
  points: [
    { id: 1, vector: [0.1, 0.2, ..., 0.768], payload: { text: '文档内容' } }
  ]
});

3. 本地文件处理流程

共享文件夹配置：

• 宿主机路径：./shared（与项目同目录）
• 容器内路径：/data/shared
• 权限设置：chmod -R 777 ./shared（开发环境）

文件处理工作流示例：

1. 使用 Local File Trigger 节点监控/data/shared/incoming目录
2. 添加 Document Reader 节点解析PDF/Word文件
3. 连接 Text Splitter 节点（按500字符拆分，重叠100字符）
4. 通过 Qdrant Vector Store 节点存储向量
5. 配置 Ollama Chat 节点实现文档问答

生产环境部署指南

安全加固清单

安全项	配置方法	风险等级
更换默认凭证	修改.env中所有密码/密钥	高
启用HTTPS	配置Nginx反向代理+Let's Encrypt	高
网络隔离	限制端口访问，使用Docker network隔离	中
容器安全	添加用户非root运行，限制capabilities	中
数据加密	启用PostgreSQL透明数据加密	中

Nginx反向代理配置示例：

server {
    listen 443 ssl;
    server_name ai.yourcompany.com;

    ssl_certificate /etc/letsencrypt/live/ai.yourcompany.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/ai.yourcompany.com/privkey.pem;

    location / {
        proxy_pass http://localhost:5678;
        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;
    }
}

性能优化策略

Docker资源限制（docker-compose.yml）：

services:
  n8n:
    deploy:
      resources:
        limits:
          cpus: '4'
          memory: 16G
  ollama-gpu:
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]
        limits:
          memory: 24G

Ollama性能调优：

# 启用GPU共享内存
echo "OLLAMA_SHARED_MEMORY=1" >> /root/.ollama/config

Qdrant优化：

# 在docker-compose.yml的qdrant服务添加
environment:
  - QDRANT__SERVICE__GRPC_PORT=6334
  - QDRANT__STORAGE__MEMMAP=True
  - QDRANT__ENGINE__VECTOR_CACHE_SIZE=1000000

监控与告警

Prometheus监控配置：

# 添加prometheus服务到docker-compose.yml
prometheus:
  image: prom/prometheus
  volumes:
    - ./prometheus.yml:/etc/prometheus/prometheus.yml
  ports:
    - 9090:9090
  command:
    - '--config.file=/etc/prometheus/prometheus.yml'

关键监控指标：

• n8n: http://localhost:5678/healthz（健康检查）
• Qdrant: http://localhost:6333/metrics（向量查询性能）
• Ollama: http://localhost:11434/metrics（推理延迟，GPU利用率）

备份与恢复策略

自动备份脚本：

#!/bin/bash
BACKUP_DIR=/data/backups
TIMESTAMP=$(date +%Y%m%d_%H%M%S)

# 备份PostgreSQL
docker exec postgres pg_dump -U aiadmin aistack > $BACKUP_DIR/postgres_$TIMESTAMP.sql

# 备份存储卷（仅关键数据）
tar -czf $BACKUP_DIR/ollama_$TIMESTAMP.tar.gz ./ollama_storage
tar -czf $BACKUP_DIR/qdrant_$TIMESTAMP.tar.gz ./qdrant_storage

# 保留30天备份
find $BACKUP_DIR -type f -mtime +30 -delete

恢复命令：

# 恢复PostgreSQL
cat postgres_20240520_1030.sql | docker exec -i postgres psql -U aiadmin -d aistack

# 恢复存储卷
tar -xzf ollama_20240520_1030.tar.gz -C ./

常见问题解决方案

启动故障排查流程

典型问题解决

1. Ollama GPU加速不生效

   # 验证NVIDIA驱动
   docker run --rm --gpus all nvidia/cuda:12.1.1-base-ubuntu22.04 nvidia-smi
   # 确保使用正确profile
   docker compose --profile gpu-nvidia up -d
   

2. n8n工作流执行缓慢

   • 增加n8n内存限制（至少8GB）
   • 优化Ollama模型参数（降低temperature，增加batch size）
   • 对大文件处理添加异步节点

3. Qdrant向量检索准确率低

   • 调整嵌入模型（使用更大尺寸向量如1024维）
   • 修改距离度量（从Cosine改为Euclidean）
   • 增加向量数量，优化Chunk大小

企业级应用案例

案例1：财务文档分析系统

架构流程图：

核心节点配置：

• Document Reader：提取PDF文本，启用OCR处理扫描件
• Text Splitter：按会计科目拆分，块大小1000字符
• Ollama Embeddings：使用nomic-embed-text模型
• Qdrant：创建financial_docs集合，向量大小768

案例2：内部IT服务台智能助手

关键功能：

1. 自动分类工单（硬件/软件/网络）
2. 基于知识库自动回复常见问题
3. 复杂问题升级至人工坐席
4. 定期生成工单统计报告

实现要点：

• 使用n8n的AI Classifier节点进行工单分类
• 集成企业内部知识库（Confluence/SharePoint）
• 通过Slack/Teams节点实现消息通知
• 定时触发Report Generator节点生成Excel报表

升级与维护

组件版本管理

查看当前版本：

# 查看n8n版本
docker exec n8n n8n -v

# 查看Ollama版本
docker exec ollama-gpu ollama -v

安全更新命令：

# 备份关键数据（见备份章节）
# 更新镜像
docker compose --profile gpu-nvidia pull
# 重启服务
docker compose --profile gpu-nvidia up -d

长期维护建议

1. 订阅安全公告：

   • n8n: https://github.com/n8n-io/n8n/security/advisories
   • Ollama: https://github.com/ollama/ollama/security/advisories

2. 定期清理：

   # 清理未使用镜像
   docker system prune -a --volumes
   
   # 清理Ollama缓存
   docker exec ollama-gpu ollama rm unused-model
   

3. 性能监控：

   • 设置GPU利用率告警阈值（>80%持续5分钟）
   • 监控Qdrant磁盘增长（向量数据量每月评估）

总结与展望

self-hosted-ai-starter-kit通过Docker Compose实现了本地AI技术栈的无缝集成，解决了企业数据隐私与AI能力落地的核心矛盾。本文从架构解析、环境部署、功能应用到生产优化，提供了全生命周期指南，使技术团队能够快速构建安全可控的AI工作流平台。

未来演进方向：

• 集成多模态模型支持（图像/语音处理）
• 实现模型自动量化与优化
• 增强分布式部署能力（多节点负载均衡）
• 完善CI/CD流程实现工作流版本管理

通过持续优化与社区贡献，self-hosted-ai-starter-kit有望成为企业本地化AI基础设施的标准解决方案。立即部署体验，开启你的本地智能工作流之旅！

---

读完本文后，你可以： ✅ 部署安全可控的本地化AI环境 ✅ 构建企业级RAG应用与自动化工作流 ✅ 优化系统性能以适应生产负载 ✅ 制定可持续的维护与升级策略

下一步行动：

1. Star项目仓库获取更新通知
2. 加入n8n社区分享你的使用经验
3. 尝试扩展集成更多企业系统

【免费下载链接】self-hosted-ai-starter-kit The Self-hosted AI Starter Kit is an open-source template that quickly sets up a local AI environment. Curated by n8n, it provides essential tools for creating secure, self-hosted AI workflows. 项目地址: https://gitcode.com/GitHub_Trending/se/self-hosted-ai-starter-kit