企业官网建设流程全解析

ChatOllama 部署与实践指南：基于 Nuxt 3 的多模型智能体聊天平台完整配置手册

【免费下载链接】chat-ollamaChatOllama is an open source agentic app for running AI agents across local and hosted models.项目地址: https://gitcode.com/GitHub_Trending/ch/chat-ollama

ChatOllama 是一个基于 Nuxt 3 构建的开源智能体聊天平台，支持 OpenAI、Anthropic、Gemini、Groq、Moonshot、Ollama 等多家模型服务商，并提供知识库 RAG、实时语音聊天、模型上下文协议（MCP）工具集成与 AI 智能体等高级能力。本文以仓库中的 README.zh-Hans.md 为主线，结合 docker-compose.yaml、nuxt.config.ts 等真实源码，完整讲解从快速启动、数据库迁移、环境变量配置、功能开关到 MCP 服务器权限管理与用户角色体系的部署与运维要点，帮助你构建一套生产可用的本地 / 混合模型智能体应用。

项目概览

ChatOllama 定位为“可运行于本地模型与托管模型之上的智能体应用（agentic app）”，核心亮点包括：

• AI 智能体：具有工具访问能力的智能代理，用于研究与任务执行，访问/agents页面即可使用；
• 多模态聊天：支持文本与图像输入；
• 知识库：基于 RAG（检索增强生成）与文档上传实现检索问答；
• 实时语音聊天：与 Gemini 2.0 Flash 进行语音对话；
• 模型上下文协议（MCP）：可扩展的工具集成体系；
• 向量数据库：同时支持 Chroma 与 Milvus；
• Docker 支持：通过 Docker Compose 一键部署；
• 国际化：内置多语言支持（仓库locales/目录下提供 en-US、zh-CN、fr-FR 等语言包）。

从源码依赖（见 package.json）可以确认，平台大量基于 LangChain 生态（langchain、@langchain/ollama、@langchain/anthropic、@langchain/groq、@langchain/mcp-adapters等）与@modelcontextprotocol/sdk构建模型接入与工具调用链路，同时使用 Nuxt UI、Tailwind CSS 与@nuxtjs/i18n支撑前端交互与国际化。

快速启动：两种部署方式

方式一：Docker（推荐）

最简入门方式是下载仓库根目录下的 docker-compose.yaml，直接运行：

docker compose up

启动完成后访问 http://localhost:3000 即可使用 ChatOllama。

从 docker-compose.yaml 可以看到，官方 Compose 编排了 5 个服务，理解它们有助于排查启动问题：

其中chatollama服务的depends_on声明了严格的启动依赖顺序：postgres必须通过pg_isready健康检查后才启动，chromadb与redis只需处于 started 状态。应用数据通过~/.chatollama:/app/data挂载持久化。

方式二：开发环境设置

用于开发或深度自定义时，按以下步骤操作：

1. 前置要求

   • Node.js 18+ 与 pnpm（注意根目录 package.json 中engines.node声明为>=24，建议按此版本准备）
   • 本地 PostgreSQL 数据库服务器
   • Ollama 服务器运行在 http://localhost:11434
   • ChromaDB 或 Milvus 向量数据库

2. 安装依赖

   git clone git@github.com:sugarforever/chat-ollama.git cd chat-ollama cp .env.example .env pnpm install

3. 数据库设置

   • 创建 PostgreSQL 数据库
   • 在.env中配置DATABASE_URL
   • 运行迁移：pnpm prisma migrate deploy

4. 启动开发服务器

   pnpm dev

从 SQLite 迁移到 PostgreSQL

自 2025-08-14 起，ChatOllama 已从 SQLite 迁移到 PostgreSQL 作为主要数据库提供商，以获得更好的性能与可扩展性（迁移脚本见 scripts/migrate-sqlite-to-postgres-simple.ts，Prisma 模式见 prisma/schema.prisma）。

Docker 用户：无需手动操作

Docker 部署会自动处理迁移过程：

• PostgreSQL 服务自动启动；
• 数据库迁移在容器启动时运行；
• 既有数据会被保留。

该逻辑由 scripts/startup.sh 实现：容器初始化时会等待 PostgreSQL 就绪、执行安全迁移，并可通过SKIP_MIGRATION=true跳过自动迁移，用MIGRATION_TIMEOUT控制迁移超时时间（Compose 中的默认配置见 docker-compose.yaml 第 40-42 行）。

开发环境用户：手动迁移步骤

1. 备份现有的 SQLite 数据（如果保留重要聊天记录）：

   cp chatollama.sqlite chatollama.sqlite.backup

2. 安装并启动 PostgreSQL：

   # macOS 使用 Homebrew brew install postgresql brew services start postgresql # 创建数据库与用户 psql postgres CREATE DATABASE chatollama; CREATE USER chatollama WITH PASSWORD 'your_password'; GRANT ALL PRIVILEGES ON DATABASE chatollama TO chatollama; \q

3. 更新.env文件，将 SQLite URL 替换为 PostgreSQL：

   DATABASE_URL="postgresql://chatollama:your_password@localhost:5432/chatollama"

4. 运行数据库迁移：

   pnpm prisma migrate deploy

5. 迁移现有 SQLite 数据（如有需要保留的历史数据）：

   pnpm migrate:sqlite-to-postgres

从 scripts/migrate-sqlite-to-postgres-simple.ts 的源码看，迁移工具提供了更细粒度的控制参数：

pnpm run migrate:sqlite-to-postgres [options] --sqlite-url <url> 指定 SQLite 数据库 URL（默认 file:./chatollama.sqlite） --postgres-url <url> 指定 PostgreSQL 数据库 URL（默认读取 DATABASE_URL） --skip-backup 跳过 SQLite 数据库备份 --dry-run 只做校验，不实际写入数据

例如干跑验证与自定义数据源：

pnpm run migrate:sqlite-to-postgres -- --dry-run pnpm run migrate:sqlite-to-postgres -- --sqlite-url file:./old-database.sqlite

迁移脚本会按顺序处理User、KnowledgeBase、KnowledgeBaseFile、Instruction、mcp_servers、mcp_server_env_vars、NextAuth 相关的Account/Session/VerificationToken等表，并采用upsert策略与事务（5 分钟超时）保证数据安全合并；日期字段同时兼容秒级 / 毫秒级时间戳与 ISO 字符串（见脚本中的parseDate方法）。

向量数据库配置

ChatOllama 支持两种向量数据库，在.env中配置：

# 选择：chroma 或 milvus VECTOR_STORE=chroma CHROMADB_URL=http://localhost:8000 MILVUS_URL=http://localhost:19530

ChromaDB（默认）一行命令即可启动：

docker run -d -p 8000:8000 chromadb/chroma

从依赖看，项目通过chromadbnpm 包与@zilliz/milvus2-sdk-node分别对接两类向量库，因此只要切换VECTOR_STORE环境变量即可在两种存储之间选择。

环境变量配置详解

.env中的关键配置项如下（完整定义同时体现在 nuxt.config.ts 的runtimeConfig与 docker-compose.yaml 中）：

# 数据库 DATABASE_URL=file:../../chatollama.sqlite # 服务器 PORT=3000 HOST= # 向量数据库 VECTOR_STORE=chroma CHROMADB_URL=http://localhost:8000 # 可选：商业模型的 API 密钥 OPENAI_API_KEY=your_openai_key ANTHROPIC_API_KEY=your_anthropic_key GOOGLE_API_KEY=your_gemini_key GROQ_API_KEY=your_groq_key MOONSHOT_API_KEY=your_moonshot_key # 可选：代理设置 NUXT_PUBLIC_MODEL_PROXY_ENABLED=false NUXT_MODEL_PROXY_URL=http://127.0.0.1:1080 # 可选：Cohere 用于重排序 COHERE_API_KEY=your_cohere_key

几个值得注意的细节：

• DATABASE_URL在开发环境默认仍可指向 SQLite 文件（file:../../chatollama.sqlite），便于轻量起步；生产环境建议切换为 PostgreSQL 连接串；
• 代理变量NUXT_MODEL_PROXY_ENABLED/NUXT_MODEL_PROXY_URL用于为模型请求配置 HTTP 代理，NUXT_前缀使其成为运行时配置；
• 除COHERE_API_KEY外，docker-compose.yaml 中还出现了COHERE_MODEL=ms-marco-MiniLM-L-6-v2与COHERE_BASE_URL=http://peanutshell:8000/v1，说明重排序默认使用本地 peanut-shell 服务承载的 Cohere 兼容模型，而非直连云端；
• 生产环境强烈建议配置SECRET（JWT 签名密钥），必须为部署专用的随机值且长度至少 32 个字符，可用openssl rand -base64 48生成；未设置或使用已知公开占位值时应用会拒绝启动，修改该值会使现有登录令牌全部失效。

功能开关：Docker 与 .env 的运行时控制

ChatOllama 提供 4 个可开关的产品模块，它们可在构建时通过.env设置，也可在 Docker 运行时通过带NUXT_前缀的变量覆盖：

Docker（部署环境推荐）

在docker-compose.yaml中通过NUXT_变量做运行时覆盖：

services: chatollama: environment: - NUXT_MCP_ENABLED=true - NUXT_KNOWLEDGE_BASE_ENABLED=true - NUXT_REALTIME_CHAT_ENABLED=true - NUXT_MODELS_MANAGEMENT_ENABLED=true

.env（构建时生效）

本地构建（非 Docker）或自定义镜像时，在.env中设置：

MCP_ENABLED=true KNOWLEDGE_BASE_ENABLED=true REALTIME_CHAT_ENABLED=true MODELS_MANAGEMENT_ENABLED=true

优先级与底层实现

• NUXT_变量在运行时直接映射到runtimeConfig键，在容器环境中优先级更高；
• 在 Compose 中使用MCP_ENABLED=true不能覆盖预构建镜像的runtimeConfig，必须使用NUXT_MCP_ENABLED=true；
• 从 nuxt.config.ts 第 94-99 行的runtimeConfig可以看到，四个开关在构建时通过process.env.X === 'true'求值写入；Docker 部署时则以NUXT_前缀变量在运行时注入覆盖。

这套开关的前端消费逻辑见 composables/useFeatures.ts：服务端从runtimeConfig读取布尔值，客户端优先从 SSR payload（由 plugins/features.server.ts 注入）读取，并带有 hydration 安全兜底；服务端 API 侧则由 server/utils/mcpFeature.ts 的isMcpEnabled()统一判断（例如 server/api/mcp-servers/index.get.ts 在开关关闭时会直接返回 403）。

MCP 集成与服务器管理

ChatOllama 通过 MCP（Model Context Protocol）接入外部工具与数据源来扩展 AI 能力，服务器全部通过设置中的用户友好界面管理。底层由 server/utils/mcp.ts 中的McpService实现：启用状态的服务器通过@langchain/mcp-adapters的MultiServerMCPClient动态加载为 LangChain 结构化工具，供聊天中的 AI 模型自动调用。

MCP 服务器管理权限（ACL）

为兼顾开发与生产环境，ChatOllama 提供灵活的访问控制：

• ACL_ENABLED=false（默认）：开放访问——所有用户都可以管理 MCP 服务器；
• ACL_ENABLED=true：限制访问——只有管理员/超级管理员用户可以管理 MCP 服务器。

开发与个人使用（推荐ACL_ENABLED=false）：

# .env 文件 ACL_ENABLED=false

按角色划分的用户体验：

重要说明：

• MCP 工具使用：无论 ACL 设置如何，所有用户都可以在聊天中使用已配置的 MCP 工具；
• 向后兼容性：现有安装无需任何改动即可继续工作；
• 安全迁移：可以随时通过设置ACL_ENABLED=true启用 ACL。

从源码看，ACL 逻辑集中在 server/utils/auth.ts：isAclEnabled()读取环境变量判断开关；requireAdminIfAclEnabled()在 ACL 关闭时允许匿名访问（仅解析已登录用户，不强制认证），开启时则调用requireAdmin()强制要求admin或superadmin角色（否则抛出 403）。MCP 的增删改查接口（如 server/api/mcp-servers/index.post.ts）统一先做功能开关与 ACL 双重校验。

支持的传输类型

• STDIO：命令行工具（最常用）；
• 服务器发送事件（SSE）：基于 HTTP 的流式传输；
• 流式 HTTP：基于 HTTP 的通信。

通过设置界面配置

1. 导航到设置 → MCP；
2. 点击“添加服务器”创建新的 MCP 服务器；
3. 配置服务器详情：
   • 名称：描述性服务器名称；
   • 传输类型：选择 STDIO、SSE 或流式 HTTP；
   • 命令/参数（STDIO）：可执行文件路径与参数；
   • URL（SSE/HTTP）：服务器端点 URL；
   • 环境变量：API 密钥与配置；
   • 启用/禁用：切换服务器状态。

STDIO 服务器示例：

名称: 文件系统工具 传输类型: stdio 命令: uvx 参数: mcp-server-filesystem 环境变量: PATH: ${PATH}

从旧配置迁移

如果存在旧的.mcp-servers.json文件，可运行迁移脚本（见 scripts/migrate-mcp-servers.ts）：

pnpm exec ts-node scripts/migrate-mcp-servers.ts

热门 MCP 服务器

• mcp-server-filesystem— 文件系统操作
• mcp-server-git— Git 仓库管理
• mcp-server-sqlite— SQLite 数据库查询
• mcp-server-brave-search— 网络搜索功能

MCP 在聊天中的工作原理

当 MCP 服务器启用时，其工具会在对话中对 AI 模型开放。AI 可以自动调用这些工具来：

• 讨论代码时读取/写入文件；
• 搜索网络获取最新信息；
• 查询数据库获取特定数据；
• 按需执行系统操作。

工具是动态加载并无缝集成到聊天体验中的（对应实现为 server/utils/mcp.ts 中的listTools()与loadToolsFromDatabase()，只加载enabled !== false的服务器）。

MCP 权限故障排除

1. 出现“需要管理员权限”消息

   • 原因：ACL_ENABLED=true且用户缺少管理员权限；
   • 解决方案：禁用 ACL 或将用户提升为管理员。

   # 选项 1：禁用 ACL（开发环境） ACL_ENABLED=false # 选项 2：将用户提升为管理员（联系超级管理员）

2. 启用 ACL 后无法访问 MCP 设置

   • 原因：系统中不存在管理员账户；
   • 解决方案：创建超级管理员账户（在首次用户注册前设置）：

   SUPER_ADMIN_NAME=admin-username

3. MCP 工具在聊天中不工作

   • 原因：MCP 功能被禁用或服务器配置错误；
   • 解决方案：检查 MCP 功能开关与服务器状态：

   # 启用 MCP 功能 NUXT_MCP_ENABLED=true # Docker MCP_ENABLED=true # .env

4. 权限更改未生效

   • 原因：浏览器缓存或会话问题；
   • 解决方案：退出登录后重新登录，或重启应用程序。

用户管理与管理员设置

创建超级管理员账户

超级管理员的创建规则由SUPER_ADMIN_NAME决定：

• 设置SUPER_ADMIN_NAME之前：第一个注册的用户自动成为超级管理员；
• 设置SUPER_ADMIN_NAME之后：只有指定用户名的用户在注册时才会成为超级管理员。
  • 在.env文件中设置：SUPER_ADMIN_NAME=your-admin-username；
  • 或在 Docker 中将其加入环境变量。

管理现有用户（脚本见 scripts/promote-super-admin.ts，内部通过 Prisma 按用户名或邮箱查找并更新role字段）：

# 将现有用户提升为超级管理员 pnpm promote-super-admin username_or_email # 列出当前的超级管理员 pnpm promote-super-admin --list

该脚本还支持--help查看用法；用户按用户名或邮箱匹配，目标已是超级管理员时会给出提示，成功/失败均有明确日志输出。

管理用户角色

从 server/utils/auth.ts 的源码可以印证这套角色体系：Role枚举定义USER = 0、ADMIN = 1、SUPERADMIN = 2，并提供requireAdmin、requireSuperAdmin、isAdmin、isSuperAdmin等校验函数。

生产环境安全建议

# 推荐的生产环境设置 ACL_ENABLED=true # 仅允许管理员管理 MCP SUPER_ADMIN_NAME=admin # 设置超级管理员用户名 SECRET= # 设置为以下命令的输出：openssl rand -base64 48

SECRET必须是部署专用的随机值，长度至少 32 个字符；未设置或使用已知的公开占位值时，应用将拒绝启动；修改该值会使现有登录令牌全部失效。

高级功能使用指南

实时语音聊天

启用与 Gemini 2.0 Flash 的语音对话：

1. 在设置中配置 Google API 密钥；
2. 在设置中启用“实时聊天”；
3. 点击麦克风图标开始语音对话；
4. 通过/realtime页面访问。

前端页面为 pages/realtime/index.vue，相关客户端实现可参考 utils/MultimodalLiveClient.ts 与 utils/multimodal-live.ts，服务端会话接口位于 server/api/audio/session.post.ts。

知识库（RAG）

创建知识库进行 RAG 对话：

1. 创建知识库：命名并配置分块参数（如父/子块大小与重叠、检索的 K 值等，参数定义见 prisma/schema.prisma 中的 KnowledgeBase 模型与迁移脚本）；
2. 上传文档：支持 PDF、DOCX、TXT 文件（依赖pdf-parse、mammoth等解析库）；
3. 与知识聊天：在对话中引用您的文档。

支持的向量数据库：

• ChromaDB（默认）：轻量级，易于设置；
• Milvus：生产级向量数据库。

数据存储

Docker 部署：

• 向量数据：存储在 Docker 卷中（chromadb_volume）；
• 关系数据：SQLite 数据库位于~/.chatollama/chatollama.sqlite（通过~/.chatollama:/app/data挂载；新版本主库为 PostgreSQL）；
• Redis：会话与缓存数据。

开发环境：

• 数据库：本地 SQLite 文件（或按需配置 PostgreSQL）；
• 向量存储：外部 ChromaDB / Milvus 实例。

开发：项目结构、脚本与技术栈

项目结构

chatollama/ ├── components/ # Vue 组件 ├── pages/ # Nuxt 页面（路由） ├── server/ # API 路由和服务器逻辑 ├── prisma/ # 数据库模式和迁移 ├── locales/ # 国际化文件 ├── config/ # 配置文件 └── docker-compose.yaml # Docker 部署

从当前仓库的完整目录看，还有composables/（客户端状态与业务逻辑）、packages/（agent-cli 与 agent-runtime 两个独立包）、scripts/（数据库迁移、用户管理等运维脚本）以及plugins/、middleware/等目录共同组成整体架构。

可用脚本

# 开发 pnpm dev # 启动开发服务器 pnpm build # 构建生产版本 pnpm preview # 预览生产构建 # 数据库 pnpm prisma-migrate # 运行数据库迁移（migrate dev） pnpm prisma-generate # 生成 Prisma 客户端 pnpm prisma-push # 推送模式更改（db push） # 用户管理 pnpm promote-super-admin <用户名|邮箱> # 将用户提升为超级管理员 pnpm promote-super-admin --list # 列出所有超级管理员

此外，package.json 中还提供了prisma-deploy（生产环境执行prisma migrate deploy）、migrate:sqlite-to-postgres（SQLite 数据迁移）以及面向 agent 子包的构建、测试与演示脚本，例如agent:cli、agent:tool-loop-demo、test:agent等。

贡献约定

1. 保持依赖项更新：每次git pull后运行pnpm install；
2. 运行迁移：当 schema 更改时运行pnpm prisma-migrate；
3. 遵循约定：使用 TypeScript、Vue 3 Composition API 与 Tailwind CSS；
4. 彻底测试：验证 Docker 与开发环境两套部署。

技术栈

• 前端：Nuxt 3、Vue 3、Nuxt UI、Tailwind CSS
• 后端：Nitro（Nuxt 服务器）、Prisma ORM
• 数据库：SQLite（开发）、PostgreSQL（生产就绪）
• 向量数据库：ChromaDB、Milvus
• AI/ML：LangChain、Ollama、OpenAI、Anthropic、Google AI
• 部署：Docker、Docker Compose

扩展阅读

本仓库还包含大量与 README 相呼应的实现资料，可进一步深入：

• 部署编排与启动逻辑：docker-compose.yaml、scripts/startup.sh；
• 数据库模型与迁移：prisma/schema.prisma、scripts/migrate-sqlite-to-postgres-simple.ts；
• MCP 服务与 ACL 权限：server/utils/mcp.ts、server/utils/auth.ts；
• 功能开关机制：nuxt.config.ts、plugins/features.server.ts、composables/useFeatures.ts；
• 实时语音聊天：utils/MultimodalLiveClient.ts、server/api/audio/session.post.ts；
• 面向智能体的独立包：packages/agent-cli/README.md、packages/agent-runtime/README.md。

项目采用 MIT 许可证（见 LICENSE），欢迎在了解上述部署与配置方式后，自行搭建并扩展你的本地智能体工作台。

【免费下载链接】chat-ollamaChatOllama is an open source agentic app for running AI agents across local and hosted models.项目地址: https://gitcode.com/GitHub_Trending/ch/chat-ollama