企业官网建设流程全解析

HaloWebUI 是一款基于 Open WebUI 深度定制的自托管 AI 平台，核心能力是多模型路由：OpenAI、Anthropic Claude、Google Gemini、xAI Grok 与本地 Ollama 模型全部在一个界面中接入、切换和管理，并内置模型计费与用量统计，中文界面让上手成本更低。如果你受够了多个 API 后台来回切换、密钥散落各处的状态，这篇指南会用最短路径带你把它跑起来。

为什么需要 HaloWebUI 这样的统一模型入口

🎯 多模型使用者的常见痛点：

• 入口分散：OpenAI 用一个网页、Gemini 用一个网页、Ollama 又一个端口，上下文和历史无法互通；
• 密钥难管：不同服务商的 API Key 存在不同的地方，换模型等于换工作流；
• 成本不透明：不知道哪个模型、哪次对话消耗了多少 Token，更无法估算费用。

HaloWebUI 的思路是把所有模型"路由"到一个 FastAPI 后端（AnyRouter），前端只需认识一个统一的模型列表。技术架构可以在 README.md 的「技术架构」一节查看，Claude 与 Gemini 走原生适配层（routers/anthropic.py、routers/gemini.py），OpenAI 走兼容层，Ollama 走本地服务，最终都汇入同一个聊天界面。

快速上手：三步完成 HaloWebUI 部署

✅第一步：Docker 一行命令启动（推荐）

docker run -d -p 3000:8080 \ --add-host=host.docker.internal:host-gateway \ -v open-webui:/app/backend/data \ --name halowebui --restart always \ ghcr.io/ztx888/halowebui:main

也可以用 Docker Compose：docker compose up -d，Compose 配置见 docker-compose.yaml。

✅第二步：访问并注册

打开http://localhost:3000，首次注册的用户自动成为管理员，可以配置全局模型与计费统计。数据库与上传文件会持久化在open-webui卷中。

✅第三步：填写模型密钥

在环境变量或设置页填入对应服务商的 Key（如OPENAI_API_KEY、ANTHROPIC_API_KEY、GEMINI_API_KEY），模型列表随即出现在下拉框里。

💡 也可以先克隆源码再本地运行：git clone https://gitcode.com/gh_mirrors/ha/HaloWebUI，开发流程参考 INSTALLATION.md。

四类模型源接入步骤：OpenAI、Claude、Gemini 与 Ollama

OpenAI 及 OpenAI 兼容的第三方模型

只需OPENAI_API_KEY一个变量即可接入 OpenAI 官方服务。更强大的是它的兼容层：任何遵循 OpenAI 协议的第三方服务（智谱 GLM、DeepSeek、月之暗面等），把OPENAI_API_BASE_URL指向对方地址就能直接接入，无需改一行代码。

Anthropic Claude 原生接入

设置ANTHROPIC_API_KEY后，Claude 系列模型由原生适配层接管，流式输出、工具调用等能力与 OpenAI 模型在同一列表中并列展示，切换只需在下拉框点一下。

Google Gemini 原生接入

配置GEMINI_API_KEY后，Gemini 模型通过原生通道接入。像 Google 的 nano banana（Gemini 图像生成）这类模型在模型列表中都有独立图标，方便快速识别。

Ollama 本地模型私有部署

OLLAMA_BASE_URL默认指向http://host.docker.internal:11434，即宿主机上的 Ollama。拉好本地模型后，云端模型与本地模型就能在同一个聊天框里自由混用——敏感数据可以只走本地，复杂任务交给云端，路由完全由你决定。

模型管理与 API 密钥池：自动轮换与限流重试

🔁 HaloWebUI 的路由不止于"能看到多个模型"，还处理了真实生产里的两个高频问题：

• API 密钥池：同一个连接下可配置多个 Key，按round_robin（轮询）、random（随机）、priority（优先级）三种模式自动轮换，实现限流分摊与负载均衡。逻辑见 utils/api_key_pool.py；
• 自动重试：遇到429 / 500 / 502 / 503 / 504等状态码，或响应中出现 "rate limit"、"quota"、"限流"、"超时"等关键字时，自动切换到池内下一个 Key 重试，用户几乎无感知。

配置入口分两层，避免管理员和普通用户互相干扰：

用户个人连接的底层结构定义在 utils/directConnections.ts，模型 ID 会带上连接前缀，从根本上避免不同服务商同名模型冲突——这正是"多模型路由"里"路由"二字的含义。

模型计费与用量统计：花了多少一目了然

📊 这是 HaloWebUI 相对原版 Open WebUI 的重点增强之一：

• Token 用量采集：管理员分析接口（routers/analytics.py）会解析每次请求的prompt_tokens/completion_tokens，按模型维度聚合；
• 按用户、按模型查看：结合分组（Groups）可以定位到具体团队或个人的消耗；
• 历史清理：支持按模型和时间范围清理统计历史（最长可回溯 365 天），dry_run参数可先预演再执行；
• 开关控制：分析功能由ENABLE_ADMIN_ANALYTICS环境变量控制，前端口径见 settings/analytics/settings/analytics/+page.svelte)。

再叠加各服务商的单价，你就能回答最实际的问题："这个月团队在哪个模型上花得最多？"

小结：一张表看懂 HaloWebUI 多模型路由

从docker run到第一个模型出现在下拉框，整个过程不超过 5 分钟。当你不再需要记住"这个模型去哪个网页、密钥填在哪个后台"时，多模型路由才算真正落地。更多移动端接入方式（PWA 安装等）可参阅 docs/mobile-access.md。