LLocalSearch开发环境搭建：Go与Node.js协同工作流配置

LLocalSearch开发环境搭建：Go与Node.js协同工作流配置

【免费下载链接】LLocalSearch LLocalSearch is a completely locally running search aggregator using LLM Agents. The user can ask a question and the system will use a chain of LLMs to find the answer. The user can see the progress of the agents and the final answer. No OpenAI or Google API keys are needed. 项目地址: https://gitcode.com/GitHub_Trending/ll/LLocalSearch

开发痛点与解决方案

你是否在搭建本地LLM应用时遭遇这些困境：Docker容器网络互通失败、Go后端与Svelte前端热重载冲突、Ollama服务连接超时、开发/生产环境配置不一致？本文将提供一套完整的解决方案，通过12个步骤实现Go+Node.js技术栈的无缝协同开发，让你在15分钟内启动具备热重载功能的本地智能搜索系统。

读完本文你将掌握：

• Docker多容器网络的精准配置方法
• Go后端与Svelte前端的热重载实现
• Ollama本地大模型的跨平台连接方案
• 开发/生产环境的无缝切换技巧
• 完整的故障排查与性能优化指南

项目架构概览

LLocalSearch采用微服务架构设计，主要由四大组件构成：

核心技术栈说明

组件	技术栈	主要职责	开发语言
后端服务	Go 1.20+, LangChain Go	业务逻辑处理、LLM Agent调度	Go
前端应用	Svelte 3+, TypeScript, Vite	用户界面、实时交互	JavaScript/TypeScript
搜索引擎	SearXNG	聚合搜索结果	Python
向量数据库	ChromaDB	存储和检索嵌入向量	Python
大模型服务	Ollama	本地LLM推理	Go
容器编排	Docker Compose	服务部署与网络管理	YAML

环境准备与依赖安装

基础环境要求

环境	最低配置	推荐配置
操作系统	Linux/macOS/Windows	Ubuntu 22.04 LTS
CPU	4核	8核
内存	8GB	16GB
磁盘空间	20GB	40GB SSD
GPU	N/A	NVIDIA GTX 1650+ (8GB VRAM)
Docker	20.10+	24.0.0+
Git	2.30+	2.40+

必要工具安装

Linux系统

# Ubuntu/Debian系统
sudo apt update && sudo apt install -y git docker.io docker-compose make build-essential

# 启动Docker服务并设置开机自启
sudo systemctl enable --now docker
sudo usermod -aG docker $USER  # 允许当前用户管理Docker（需注销重登录生效）

# 安装Go环境（1.20+）
wget https://go.dev/dl/go1.21.0.linux-amd64.tar.gz
sudo rm -rf /usr/local/go && sudo tar -C /usr/local -xzf go1.21.0.linux-amd64.tar.gz
echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc
source ~/.bashrc

# 安装Node.js环境（18+）
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt install -y nodejs

macOS系统

# 使用Homebrew安装依赖
brew install git docker docker-compose go node

# 启动Docker Desktop
open -a Docker

源代码获取与项目结构

克隆代码仓库

# 通过GitCode克隆仓库（国内访问优化）
git clone https://gitcode.com/GitHub_Trending/ll/LLocalSearch.git
cd LLocalSearch

# 查看项目结构
tree -L 2  # 需安装tree命令：sudo apt install tree

项目目录结构解析

LLocalSearch/
├── Dockerfile           # 生产环境前端构建文件
├── Dockerfile.dev       # 开发环境前端构建文件
├── Makefile             # 项目构建脚本
├── OLLAMA_GUIDE.md      # Ollama配置指南
├── README.md            # 项目说明文档
├── backend/             # Go后端源代码
│   ├── Dockerfile       # 后端Docker构建文件
│   ├── main.go          # 后端入口文件
│   ├── apiServer.go     # API服务器实现
│   ├── llm_tools/       # LLM工具实现
│   └── utils/           # 工具函数库
├── docker-compose.yaml  # 生产环境编排配置
├── docker-compose.dev.yaml # 开发环境编排配置
├── src/                 # 前端源代码
│   ├── app.html         # 前端入口页面
│   ├── lib/             # 前端组件库
│   └── routes/          # 路由配置
└── searxng/             # 搜索引擎配置
    ├── settings.yml     # SearXNG配置
    └── uwsgi.ini        # 服务器配置

关键目录说明

• backend/llm_tools: 包含Web搜索、向量数据库查询等LLM工具实现
• backend/utils: 包含LLM后端连接、文件加载等通用工具函数
• src/lib: Svelte组件库，包含所有UI元素实现
• src/routes: 前端路由配置，采用文件系统路由
• searxng/: 元搜索引擎配置，用于聚合多个搜索引擎结果

开发环境配置详解

1. Docker开发环境配置

开发环境采用Docker Compose实现服务编排，支持代码热重载和实时调试：

# docker-compose.dev.yaml核心配置解析
version: '3.7'
services:
  backend:
    volumes:
      - ./backend/:/app/           # 代码目录挂载，支持热重载
      - /home/nils/Notes/:/localfiles/:ro  # 本地文件只读挂载
    build:
      context: ./backend
      dockerfile: Dockerfile.dev   # 使用开发环境Dockerfile
    environment:
      - OLLAMA_HOST=${OLLAMA_HOST:-host.docker.internal:11434}
      - CHROMA_DB_URL=${CHROMA_DB_URL:-http://chromadb:8000}
      - EMBEDDINGS_MODEL_NAME=${EMBEDDINGS_MODEL_NAME:-nomic-embed-text:v1.5}
    networks:
      - llm_network_dev

  frontend:
    depends_on:
      - backend
    build:
      context: .
      dockerfile: Dockerfile.dev   # 前端开发环境构建
    volumes:
      - ./:/app/                   # 前端代码挂载
    ports:
      - '3000:5173'                # Vite开发服务器端口

2. 环境变量配置

创建开发环境配置文件：

# 从模板创建环境变量文件
cp env-example .env
# 编辑环境变量
nano .env

关键环境变量配置

# Ollama服务地址配置
OLLAMA_HOST=host.docker.internal:11434

# 向量数据库配置
CHROMA_DB_URL=http://chromadb:8000

# 搜索引擎配置
SEARXNG_DOMAIN=http://searxng:8080

# 嵌入模型配置
EMBEDDINGS_MODEL_NAME=nomic-embed-text:v1.5

# 开发模式标识
VERSION=dev

3. Ollama本地大模型配置

Ollama是LLocalSearch的核心依赖，提供本地大模型推理能力：

安装Ollama

# Linux系统
curl -fsSL https://ollama.com/install.sh | sh

# macOS系统
brew install ollama

# 启动Ollama服务
ollama serve &

下载并运行模型

# 拉取推荐模型（7B参数，适合开发测试）
ollama pull mistral:7b-instruct

# 或拉取更小的模型（3B参数，适合低配置环境）
ollama pull phi3:3.8b-mini-instruct

# 查看已安装模型
ollama list

跨平台连接配置

部署场景	Ollama地址配置	额外步骤
本地主机（Linux/macOS）	host.docker.internal:11434	无需额外配置
本地主机（Windows）	host.docker.internal:11434	启用WSL2网络共享
外部服务器	ollama-server-ip:11434	配置防火墙开放11434端口
Docker内部	ollama容器名称:11434	添加到同一网络

服务启动与验证

开发环境启动流程

# 1. 启动Ollama服务（单独终端）
ollama serve

# 2. 启动开发环境所有服务
docker-compose -f docker-compose.dev.yaml up -d

# 3. 查看服务状态
docker-compose -f docker-compose.dev.yaml ps

# 4. 查看服务日志（按需）
docker-compose -f docker-compose.dev.yaml logs -f backend  # 后端日志
docker-compose -f docker-compose.dev.yaml logs -f frontend # 前端日志

预期服务状态

服务名称	状态	端口	说明
backend	Up	-	Go后端服务
frontend	Up	3000	Svelte前端服务
chromadb	Up	8000	向量数据库
searxng	Up	8080	元搜索引擎
redis	Up	6379	缓存服务

服务验证步骤

1. 前端服务验证：访问 http://localhost:3000，应显示LLocalSearch主界面
2. 后端API验证：访问 http://localhost:8080/health，应返回{"status":"ok"}
3. Ollama连接验证：

# 测试Ollama API连接
curl http://localhost:11434/api/tags
# 应返回包含已安装模型的JSON响应

4. 功能完整性测试：在前端界面输入问题"最新的Go语言版本是什么？"，验证系统是否能完成搜索并返回结果

代码热重载配置

后端热重载实现

Go后端使用air实现代码热重载：

# backend/Dockerfile.dev关键配置
FROM golang:1.20-alpine AS dev
WORKDIR /app
# 安装air热重载工具
RUN go install github.com/cosmtrek/air@latest
# 启动命令
CMD ["air", "-c", ".air.toml"]

自定义热重载配置：编辑backend/.air.toml可调整忽略文件、构建命令等参数

前端热重载实现

Svelte前端利用Vite的内置热模块替换(HMR)功能：

// vite.config.ts热重载配置
export default defineConfig({
  server: {
    watch: {
      usePolling: true, // 支持Docker环境下文件变更检测
    },
    host: true, // 允许外部访问
    port: 5173,
  },
  // 其他配置...
})

调试工具与工作流

Go后端调试

1. 日志查看：

# 实时查看后端日志
docker-compose -f docker-compose.dev.yaml logs -f backend

2. 远程调试配置：

# 修改docker-compose.dev.yaml添加调试端口
services:
  backend:
    # ...其他配置
    ports:
      - "2345:2345"  # 调试器端口
    command: dlv debug --headless --listen=:2345 --api-version=2 --log main.go

3. VSCode调试配置：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Remote Debug",
      "type": "go",
      "request": "attach",
      "mode": "remote",
      "remotePath": "/app",
      "port": 2345,
      "host": "127.0.0.1",
      "program": "${workspaceFolder}/backend"
    }
  ]
}

前端调试

1. 浏览器开发工具：F12打开开发者工具，Svelte有专门的调试插件
2. Vite开发服务器：访问 http://localhost:3000 查看应用， http://localhost:3000/__vite_debug 查看Vite调试界面
3. TypeScript类型检查：

# 在前端容器内运行类型检查
docker-compose -f docker-compose.dev.yaml exec frontend npm run check

常见问题排查与优化

网络连接问题

症状：后端无法连接Ollama服务，日志显示"connection refused"

性能优化建议

1. 模型优化：

   • 开发环境使用较小模型（如phi3:3.8b）
   • 调整Ollama模型参数：ollama run mistral:7b-instruct --n 512 --temperature 0.7

2. 资源配置：

   • 为Docker分配足够资源（至少4核CPU、8GB内存）
   • 启用GPU加速（需安装NVIDIA Docker运行时）

3. 缓存优化：

   • 增加Redis缓存大小
   • 调整向量数据库持久化策略

开发效率提升技巧

1. 使用Makefile简化命令：

# 查看所有可用命令
make help

# 一键启动开发环境
make dev-up

# 快速查看后端日志
make backend-logs

# 执行后端单元测试
make backend-test

2. 代码质量工具集成：

   • Go: golint, gofmt
   • TypeScript: eslint, prettier
   • 配置pre-commit钩子自动检查代码质量

3. 开发环境备份：定期备份.env配置文件和开发数据库状态

生产环境部署参考

虽然本文重点是开发环境，但了解生产环境配置有助于理解整体架构：

# 生产环境启动（最小化配置）
cp env-example .env.prod
# 编辑生产环境配置（禁用热重载，启用HTTPS等）
nano .env.prod
# 启动生产环境
docker-compose -f docker-compose.yaml --env-file .env.prod up -d

生产环境与开发环境主要差异：

特性	开发环境	生产环境
代码重载	启用	禁用
调试工具	包含	移除
日志级别	DEBUG	INFO
安全限制	宽松	严格
性能优化	关闭	启用
容器构建	本地构建	预构建镜像

总结与后续步骤

通过本文配置，你已成功搭建LLocalSearch完整开发环境，包括：

1. 基于Docker Compose的多服务开发环境
2. Go后端与Svelte前端的热重载配置
3. Ollama本地大模型服务的连接与优化
4. 完整的服务验证与故障排查流程

推荐后续学习路径：

1. 熟悉LLM Agent工作流程：阅读backend/agentChain.go
2. 了解工具调用机制：研究backend/llm_tools/目录下实现
3. 自定义UI组件：修改src/lib/目录下Svelte组件
4. 添加新工具：参考现有工具实现，扩展LLM能力

参与贡献指南：

1. Fork项目仓库
2. 创建特性分支：git checkout -b feature/your-feature
3. 提交更改：git commit -m "Add your feature"
4. 推送分支：git push origin feature/your-feature
5. 创建Pull Request

附录：完整命令清单

开发环境管理

# 启动开发环境
docker-compose -f docker-compose.dev.yaml up -d

# 停止开发环境
docker-compose -f docker-compose.dev.yaml down

# 重启单个服务
docker-compose -f docker-compose.dev.yaml restart backend

# 查看服务状态
docker-compose -f docker-compose.dev.yaml ps

# 查看服务日志
docker-compose -f docker-compose.dev.yaml logs -f [服务名]

代码管理

# 拉取最新代码
git pull origin main

# 创建功能分支
git checkout -b feature/new-tool

# 提交代码更改
git add .
git commit -m "Implement new search tool"

问题排查

# 检查容器网络
docker network inspect llm_network_dev

# 测试服务连通性
docker-compose -f docker-compose.dev.yaml exec backend curl searxng:8080

# 查看Ollama模型状态
docker-compose -f docker-compose.dev.yaml exec backend curl ${OLLAMA_HOST}/api/tags

希望本文能帮助你顺利开展LLocalSearch开发工作。如有任何问题，欢迎查阅项目文档或提交issue反馈。

如果觉得本文对你有帮助，请点赞、收藏并关注项目更新，下期将带来《LLM Agent自定义工具开发实战》！

【免费下载链接】LLocalSearch LLocalSearch is a completely locally running search aggregator using LLM Agents. The user can ask a question and the system will use a chain of LLMs to find the answer. The user can see the progress of the agents and the final answer. No OpenAI or Google API keys are needed. 项目地址: https://gitcode.com/GitHub_Trending/ll/LLocalSearch