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-ollamaChatOllama 是一个基于 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 与 MilvusDocker 支持通过 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 个服务理解它们有助于排查启动问题服务镜像职责postgrespostgres:16-alpine主数据库带健康检查与postgres_data持久卷chromadbchromadb/chroma默认向量数据库暴露 8000 端口chatollama0001coder/chatollama:latest应用主服务映射 3000 端口redisredis:latest会话与缓存数据peanutshellghcr.io/sugarforever/peanut-shell:latest本地重排序模型服务配合 Cohere 兼容 API 使用其中chatollama服务的depends_on声明了严格的启动依赖顺序postgres必须通过pg_isready健康检查后才启动chromadb与redis只需处于 started 状态。应用数据通过~/.chatollama:/app/data挂载持久化。方式二开发环境设置用于开发或深度自定义时按以下步骤操作前置要求Node.js 18 与 pnpm注意根目录 package.json 中engines.node声明为24建议按此版本准备本地 PostgreSQL 数据库服务器Ollama 服务器运行在 http://localhost:11434ChromaDB 或 Milvus 向量数据库安装依赖git clone gitgithub.com:sugarforever/chat-ollama.git cd chat-ollama cp .env.example .env pnpm install数据库设置创建 PostgreSQL 数据库在.env中配置DATABASE_URL运行迁移pnpm prisma migrate deploy启动开发服务器pnpm dev从 SQLite 迁移到 PostgreSQL自 2025-08-14 起ChatOllama 已从 SQLite 迁移到 PostgreSQL 作为主要数据库提供商以获得更好的性能与可扩展性迁移脚本见 scripts/migrate-sqlite-to-postgres-simple.tsPrisma 模式见 prisma/schema.prisma。Docker 用户无需手动操作Docker 部署会自动处理迁移过程PostgreSQL 服务自动启动数据库迁移在容器启动时运行既有数据会被保留。该逻辑由 scripts/startup.sh 实现容器初始化时会等待 PostgreSQL 就绪、执行安全迁移并可通过SKIP_MIGRATIONtrue跳过自动迁移用MIGRATION_TIMEOUT控制迁移超时时间Compose 中的默认配置见 docker-compose.yaml 第 40-42 行。开发环境用户手动迁移步骤备份现有的 SQLite 数据如果保留重要聊天记录cp chatollama.sqlite chatollama.sqlite.backup安装并启动 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更新.env文件将 SQLite URL 替换为 PostgreSQLDATABASE_URLpostgresql://chatollama:your_passwordlocalhost:5432/chatollama运行数据库迁移pnpm prisma migrate deploy迁移现有 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_STOREchroma CHROMADB_URLhttp://localhost:8000 MILVUS_URLhttp://localhost:19530ChromaDB默认一行命令即可启动docker run -d -p 8000:8000 chromadb/chroma从依赖看项目通过chromadbnpm 包与zilliz/milvus2-sdk-node分别对接两类向量库因此只要切换VECTOR_STORE环境变量即可在两种存储之间选择。环境变量配置详解.env中的关键配置项如下完整定义同时体现在 nuxt.config.ts 的runtimeConfig与 docker-compose.yaml 中# 数据库 DATABASE_URLfile:../../chatollama.sqlite # 服务器 PORT3000 HOST # 向量数据库 VECTOR_STOREchroma CHROMADB_URLhttp://localhost:8000 # 可选商业模型的 API 密钥 OPENAI_API_KEYyour_openai_key ANTHROPIC_API_KEYyour_anthropic_key GOOGLE_API_KEYyour_gemini_key GROQ_API_KEYyour_groq_key MOONSHOT_API_KEYyour_moonshot_key # 可选代理设置 NUXT_PUBLIC_MODEL_PROXY_ENABLEDfalse NUXT_MODEL_PROXY_URLhttp://127.0.0.1:1080 # 可选Cohere 用于重排序 COHERE_API_KEYyour_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_MODELms-marco-MiniLM-L-6-v2与COHERE_BASE_URLhttp://peanutshell:8000/v1说明重排序默认使用本地 peanut-shell 服务承载的 Cohere 兼容模型而非直连云端生产环境强烈建议配置SECRETJWT 签名密钥必须为部署专用的随机值且长度至少 32 个字符可用openssl rand -base64 48生成未设置或使用已知公开占位值时应用会拒绝启动修改该值会使现有登录令牌全部失效。功能开关Docker 与 .env 的运行时控制ChatOllama 提供 4 个可开关的产品模块它们可在构建时通过.env设置也可在 Docker 运行时通过带NUXT_前缀的变量覆盖功能控制的模块运行时配置键FlagMCP模型上下文协议「设置 → MCP」模块mcpEnabled知识库知识库菜单与页面knowledgeBaseEnabled实时聊天/realtime语音聊天页面realtimeChatEnabled模型管理「模型」菜单与/models页面modelsManagementEnabledDocker部署环境推荐在docker-compose.yaml中通过NUXT_变量做运行时覆盖services: chatollama: environment: - NUXT_MCP_ENABLEDtrue - NUXT_KNOWLEDGE_BASE_ENABLEDtrue - NUXT_REALTIME_CHAT_ENABLEDtrue - NUXT_MODELS_MANAGEMENT_ENABLEDtrue.env构建时生效本地构建非 Docker或自定义镜像时在.env中设置MCP_ENABLEDtrue KNOWLEDGE_BASE_ENABLEDtrue REALTIME_CHAT_ENABLEDtrue MODELS_MANAGEMENT_ENABLEDtrue优先级与底层实现NUXT_变量在运行时直接映射到runtimeConfig键在容器环境中优先级更高在 Compose 中使用MCP_ENABLEDtrue不能覆盖预构建镜像的runtimeConfig必须使用NUXT_MCP_ENABLEDtrue从 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 通过 MCPModel Context Protocol接入外部工具与数据源来扩展 AI 能力服务器全部通过设置中的用户友好界面管理。底层由 server/utils/mcp.ts 中的McpService实现启用状态的服务器通过langchain/mcp-adapters的MultiServerMCPClient动态加载为 LangChain 结构化工具供聊天中的 AI 模型自动调用。MCP 服务器管理权限ACL为兼顾开发与生产环境ChatOllama 提供灵活的访问控制ACL_ENABLEDfalse默认开放访问——所有用户都可以管理 MCP 服务器ACL_ENABLEDtrue限制访问——只有管理员/超级管理员用户可以管理 MCP 服务器。开发与个人使用推荐ACL_ENABLEDfalse# .env 文件 ACL_ENABLEDfalse按角色划分的用户体验用户类型ACL_ENABLEDfalseACL_ENABLEDtrue未认证用户✅ 完整 MCP 访问❌ 需要管理员权限普通用户✅ 完整 MCP 访问❌ 需要管理员权限管理员✅ 完整 MCP 访问✅ 完整 MCP 访问超级管理员✅ 完整 MCP 访问✅ 完整 MCP 访问重要说明MCP 工具使用无论 ACL 设置如何所有用户都可以在聊天中使用已配置的 MCP 工具向后兼容性现有安装无需任何改动即可继续工作安全迁移可以随时通过设置ACL_ENABLEDtrue启用 ACL。从源码看ACL 逻辑集中在 server/utils/auth.tsisAclEnabled()读取环境变量判断开关requireAdminIfAclEnabled()在 ACL 关闭时允许匿名访问仅解析已登录用户不强制认证开启时则调用requireAdmin()强制要求admin或superadmin角色否则抛出 403。MCP 的增删改查接口如 server/api/mcp-servers/index.post.ts统一先做功能开关与 ACL 双重校验。支持的传输类型STDIO命令行工具最常用服务器发送事件SSE基于 HTTP 的流式传输流式 HTTP基于 HTTP 的通信。通过设置界面配置导航到设置 → MCP点击“添加服务器”创建新的 MCP 服务器配置服务器详情名称描述性服务器名称传输类型选择 STDIO、SSE 或流式 HTTP命令/参数STDIO可执行文件路径与参数URLSSE/HTTP服务器端点 URL环境变量API 密钥与配置启用/禁用切换服务器状态。STDIO 服务器示例名称: 文件系统工具 传输类型: stdio 命令: uvx 参数: mcp-server-filesystem 环境变量: PATH: ${PATH}从旧配置迁移如果存在旧的.mcp-servers.json文件可运行迁移脚本见 scripts/migrate-mcp-servers.tspnpm 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 权限故障排除出现“需要管理员权限”消息原因ACL_ENABLEDtrue且用户缺少管理员权限解决方案禁用 ACL 或将用户提升为管理员。# 选项 1禁用 ACL开发环境 ACL_ENABLEDfalse # 选项 2将用户提升为管理员联系超级管理员启用 ACL 后无法访问 MCP 设置原因系统中不存在管理员账户解决方案创建超级管理员账户在首次用户注册前设置SUPER_ADMIN_NAMEadmin-usernameMCP 工具在聊天中不工作原因MCP 功能被禁用或服务器配置错误解决方案检查 MCP 功能开关与服务器状态# 启用 MCP 功能 NUXT_MCP_ENABLEDtrue # Docker MCP_ENABLEDtrue # .env权限更改未生效原因浏览器缓存或会话问题解决方案退出登录后重新登录或重启应用程序。用户管理与管理员设置创建超级管理员账户超级管理员的创建规则由SUPER_ADMIN_NAME决定设置SUPER_ADMIN_NAME之前第一个注册的用户自动成为超级管理员设置SUPER_ADMIN_NAME之后只有指定用户名的用户在注册时才会成为超级管理员。在.env文件中设置SUPER_ADMIN_NAMEyour-admin-username或在 Docker 中将其加入环境变量。管理现有用户脚本见 scripts/promote-super-admin.ts内部通过 Prisma 按用户名或邮箱查找并更新role字段# 将现有用户提升为超级管理员 pnpm promote-super-admin username_or_email # 列出当前的超级管理员 pnpm promote-super-admin --list该脚本还支持--help查看用法用户按用户名或邮箱匹配目标已是超级管理员时会给出提示成功/失败均有明确日志输出。管理用户角色角色能力超级管理员将普通用户提升为管理员管理所有 MCP 服务器启用 ACL 时访问用户管理界面配置系统范围的设置管理员管理 MCP 服务器启用 ACL 时无法提升其他用户普通用户使用所有聊天功能与 MCP 工具管理 MCP 服务器仅当 ACL 禁用时从 server/utils/auth.ts 的源码可以印证这套角色体系Role枚举定义USER 0、ADMIN 1、SUPERADMIN 2并提供requireAdmin、requireSuperAdmin、isAdmin、isSuperAdmin等校验函数。生产环境安全建议# 推荐的生产环境设置 ACL_ENABLEDtrue # 仅允许管理员管理 MCP SUPER_ADMIN_NAMEadmin # 设置超级管理员用户名 SECRET # 设置为以下命令的输出openssl rand -base64 48SECRET必须是部署专用的随机值长度至少 32 个字符未设置或使用已知的公开占位值时应用将拒绝启动修改该值会使现有登录令牌全部失效。高级功能使用指南实时语音聊天启用与 Gemini 2.0 Flash 的语音对话在设置中配置 Google API 密钥在设置中启用“实时聊天”点击麦克风图标开始语音对话通过/realtime页面访问。前端页面为 pages/realtime/index.vue相关客户端实现可参考 utils/MultimodalLiveClient.ts 与 utils/multimodal-live.ts服务端会话接口位于 server/api/audio/session.post.ts。知识库RAG创建知识库进行 RAG 对话创建知识库命名并配置分块参数如父/子块大小与重叠、检索的 K 值等参数定义见 prisma/schema.prisma 中的 KnowledgeBase 模型与迁移脚本上传文档支持 PDF、DOCX、TXT 文件依赖pdf-parse、mammoth等解析库与知识聊天在对话中引用您的文档。支持的向量数据库ChromaDB默认轻量级易于设置Milvus生产级向量数据库。数据存储Docker 部署向量数据存储在 Docker 卷中chromadb_volume关系数据SQLite 数据库位于~/.chatollama/chatollama.sqlite通过~/.chatollama:/app/data挂载新版本主库为 PostgreSQLRedis会话与缓存数据。开发环境数据库本地 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-postgresSQLite 数据迁移以及面向 agent 子包的构建、测试与演示脚本例如agent:cli、agent:tool-loop-demo、test:agent等。贡献约定保持依赖项更新每次git pull后运行pnpm install运行迁移当 schema 更改时运行pnpm prisma-migrate遵循约定使用 TypeScript、Vue 3 Composition API 与 Tailwind CSS彻底测试验证 Docker 与开发环境两套部署。技术栈前端Nuxt 3、Vue 3、Nuxt UI、Tailwind CSS后端NitroNuxt 服务器、Prisma ORM数据库SQLite开发、PostgreSQL生产就绪向量数据库ChromaDB、MilvusAI/MLLangChain、Ollama、OpenAI、Anthropic、Google AI部署Docker、Docker Compose扩展阅读本仓库还包含大量与 README 相呼应的实现资料可进一步深入部署编排与启动逻辑docker-compose.yaml、scripts/startup.sh数据库模型与迁移prisma/schema.prisma、scripts/migrate-sqlite-to-postgres-simple.tsMCP 服务与 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考