一、Chatbot UI 是什么

入门

Chatbot UI 是一个开源的 AI 聊天界面，你可以把它理解成一个“万能对话窗口”。它本身不生产 AI 答案，而是负责把你输入的每一句话，转发给不同的 AI 模型（比如 OpenAI 的 GPT 系列，或者你自己电脑上运行的 Ollama 模型），再把模型的回复显示出来。

它解决的核心痛点是：很多 AI 模型只提供 API 接口，没有友好的聊天界面。Chatbot UI 提供了类似 ChatGPT 的交互体验，但你可以自由选择想用的模型、自由配置自己的 API 密钥，数据可以存在你自己的服务器上。

这个项目在 GitHub 上有超过 33k Star，是同类开源项目里热度较高的一款。官方也提供了托管版本（chatbotui.com），你不用自己部署就能直接使用；但本教程的重点是教你把它跑在自己的机器上。

二、快速部署：在本地把 Chatbot UI 跑起来

入门

这一节会带你完成本地运行。整个过程需要你有一台能联网的电脑（Windows、macOS 或 Linux 均可），并且具备一些基本的命令行操作能力。如果命令不会用，可以先搜索“如何使用终端”。

在开始之前，你需要准备两样东西：

1. Node.js 18 或更高版本：Node.js 是一种 JavaScript 运行环境，Chatbot UI 是基于 TypeScript 构建的，必须要有它才能启动。你可以在 Node.js 官网下载安装包，安装后打开终端输入 node -v 能显示版本号就说明安装成功。

2. git：git 是一个版本控制工具，用来把 GitHub 上的代码下载到本地。如果你已经会用 GitHub Desktop，也可以用它代替命令行。

准备好之后，按下面的步骤操作。

第 1 步：克隆代码仓库

打开终端，进入你想存放项目的文件夹，运行：

git clone https://github.com/mckaywrigley/chatbot-ui.git

这会把项目的所有代码下载到一个叫 chatbot-ui 的文件夹里。

第 2 步：进入项目目录并安装依赖

cd chatbot-ui
npm install

npm install 会根据项目里的依赖清单，自动下载所有需要的第三方库。这一步可能需要几分钟，网络不好时可以换成国内镜像源，例如 npm config set registry https://registry.npmmirror.com。

第 3 步：配置 Supabase（关键步骤）

Chatbot UI 需要 Supabase 来存储聊天记录和用户信息。Supabase 是一个开源的后端服务平台，你可以把它理解成“现成的数据库 + 用户登录系统”。你可以使用 Supabase 云服务（免费套餐够用），也可以在自己电脑上本地运行 Supabase。

具体配置方法会在下一节详细讲解。简单来说，你需要拿到 Supabase 的 project_url 和 service_role_key，然后替换项目 supabase/migrations/20240108234540_setup.sql 文件中的两个值。

第 4 步：启动应用

在项目根目录运行：

npm run chat

如果一切正常，终端会提示应用已启动。打开浏览器访问 http://localhost:3000，就能看到 Chatbot UI 的界面了。

注意：localhost 表示“本机”，3000 是默认端口号。如果启动时提示端口被占用，可以先检查是否有其他程序占用了 3000 端口，关闭后再重新启动。

三、配置详解：连接 Supabase 和 Ollama

进阶 · 推荐细读

上一节里的“配置 Supabase”是很多人卡住的地方，这里展开说明。

3.1 获取 Supabase 的 project_url 和 service_role_key

如果你使用 Supabase 云服务，注册并创建一个新项目后，在项目的 Settings → API 页面可以找到项目 URL 和密钥。其中：

• project_url 是你的 Supabase 项目地址，形如 https://xxxx.supabase.co
• service_role_key 是服务端密钥，权限很高，绝对不能公开

如果你在本地运行 Supabase（通过 Docker 或 CLI），可以执行 supabase status 命令，它会输出本地的 project_url 和 service_role_key。

3.2 修改迁移文件

在项目的 supabase/migrations/20240108234540_setup.sql 文件里，找到下面两处并替换成你拿到的值：

• 第 53 行附近的 http://supabase_kong_chatbotui:8000：如果你没有改过 config.toml 中的 project_id，这个值保持默认即可；否则需要替换成你的实际项目 URL。
• 第 54 行附近的 service_role_key：替换成你上一步获取到的服务端密钥。

这样做的目的是让数据库在存储文件时，能正确关联到你的 Supabase 项目，避免存储文件无法正常删除的问题。

3.3 （可选）安装 Ollama 连接本地模型

Ollama 是一个可以在自己电脑上运行大语言模型的工具。如果你想免费使用本地模型、不依赖云端 API，可以安装 Ollama。

安装完成后，在 Chatbot UI 的模型设置里选择 Ollama 作为提供方，并填写 Ollama 的 API 地址。Ollama 默认监听 http://localhost:11434，如果你的 Ollama 运行在同一台电脑上，直接使用这个地址即可。

提示：Ollama 对电脑配置有一定要求，尤其是内存。如果电脑配置较低，建议先使用云端模型，等熟悉后再尝试本地模型。

3.4 环境变量说明

Chatbot UI 的敏感配置通常放在项目根目录下的 .env.local 文件里。这个文件不会被 git 跟踪，适合存放 Supabase 密钥、API 密钥等。

虽然 README 没有列出完整的变量清单，但常见的做法是：在 .env.local 中填入 Supabase 的 URL 和 anon key（公开密钥），而 service_role_key 只用于服务端操作，不会暴露给浏览器。

请务必不要把 .env.local 提交到公开仓库，否则任何人都能看到你的密钥。

四、功能导览：日常使用与模型切换

入门

启动成功后，你会看到一个简洁的聊天界面。它的基本用法和主流聊天软件类似：在输入框输入问题，按回车发送，AI 会在下方给出回复。

Chatbot UI 的核心特色是“模型自由”。你可以在设置里添加多个模型提供商，比如 OpenAI、Anthropic、Ollama 等，并在对话时随时切换。每个提供商需要你填入对应的 API 密钥，这些密钥只保存在你的本地环境里，不会上传到第三方服务器。

聊天记录默认会保存到 Supabase 数据库中。如果你用的是本地 Supabase，所有数据都留在你自己电脑上；如果用云服务，数据存在你的 Supabase 项目里。

由于本项目不带内置模型，你只有在配置好至少一个模型提供商并填入有效密钥后，才能真正开始对话。如果某个模型没有响应，先检查密钥是否正确、账户是否有额度。

五、常见问题：端口冲突、依赖和数据库

进阶 · 推荐细读

下面列出几个新手容易遇到的问题。

问题 1：启动时提示 3000 端口被占用

3000 端口是很多开发工具的默认端口。如果被其他程序占用，可以尝试关闭占用程序，或者换一个端口。具体修改方式可以查看项目文档或搜索“修改 Next.js 端口”。

问题 2：npm install 报错或下载缓慢

这通常与网络环境有关。可以尝试切换到国内 npm 镜像源，或者使用代理。如果出现权限错误，避免使用 sudo npm install，而是检查目录权限。

问题 3：数据库迁移失败或应用无法连接 Supabase

最常见的原因是 .env.local 中的 Supabase URL 和密钥填错了。请仔细核对 project_url 和 service_role_key 是否与 Supabase 后台一致，并且迁移文件中的值已经替换。

问题 4：Ollama 连接不上

请确认 Ollama 已经启动（可以在终端运行 ollama list 查看已安装的模型），并且 Chatbot UI 填写的地址是 http://localhost:11434。如果 Ollama 安装在另一台机器上，需要把 localhost 换成那台机器的 IP 地址并确保防火墙放行。

问题 5：更新后页面报错

如果你经常更新项目，更新后需要执行数据库迁移，否则可能出现数据库结构不匹配。具体命令见下一节。

六、运维进阶：更新、备份与反向代理

深入 · 老手可选

6.1 更新项目

当 Chatbot UI 发布新版本时，你可以在项目根目录运行：

npm run update

这个命令会拉取最新的代码并安装新依赖。如果你的实例使用了数据库，还需要额外执行：

npm run db-push

这会应用最新的数据库迁移，保证数据库表和新增功能匹配。建议每次更新后都执行这两个命令，顺序不要颠倒。

6.2 数据备份

如果你把聊天记录存在 Supabase 云服务里，备份相对简单：定期在 Supabase 后台导出数据库快照即可。如果你使用本地 Supabase，可以备份整个 Supabase 数据目录，同时别忘了备份项目根目录下的 .env.local 文件。

6.3 反向代理与 HTTPS

本地运行只用 localhost 访问，但如果你想把 Chatbot UI 部署到公网，建议使用反向代理工具（如 Caddy 或 Nginx）来提供 HTTPS 加密连接。

Caddy 是一个可以自动申请免费 HTTPS 证书的服务器软件，配置非常简洁。以下是一个示例 Caddyfile：

chat.example.com {
    reverse_proxy localhost:3000
}

把 chat.example.com 换成你自己的域名，然后运行 Caddy，它就会自动申请证书并把外部请求转发到本机的 3000 端口。这样别人就能通过 https://chat.example.com 安全地访问你的 Chatbot UI 了。

注意：如果你部署到公网，请务必配置好防火墙，只开放 80 和 443 端口，不要直接暴露 3000 端口。

至此，你已经完成了从零开始部署和配置 Chatbot UI 的主要流程。这个项目本身迭代较快，遇到问题时可以优先查看 GitHub 仓库的 Discussions 板块，那里通常有和你遇到相同问题的用户以及解决方案。

项目信息

参考链接

• GitHub 仓库
• 项目主页

延伸阅读

想继续探索？这些同领域的教程可能也适合你：

• 「Python」中文使用教程
• 「AI_NovelGenerator」中文使用教程
• 「snipe-it」中文使用教程