在实际 AI 应用开发中很多开发者希望拥有一个类似 ChatGPT 的私有化对话界面用于集成自己的大模型实现可控、可定制且能分享的 AI 服务。Open WebUI原名 Ollama WebUI正是一个可以满足这一需求的开源项目它提供了美观的 Web 界面并能轻松对接多种大模型 API。而 DeepSeek 作为近期备受关注的国产高性能大模型其 API 服务为开发者提供了强大的推理能力。将两者结合你就能快速搭建一个功能完备、支持用户注册和对话分享的私有 AI 网站。本文将带你从零开始完成 Open WebUI 的部署并接入 DeepSeek API。整个过程不涉及复杂的模型本地部署你只需要一个能运行 Docker 的环境和有效的 DeepSeek API Key。我们将重点关注环境准备、关键配置、用户认证体系的调整以及最终的功能验证确保你搭建的站点不仅能用还能安全地分享给他人使用。1. 理解 Open WebUI 与 DeepSeek 的集成架构在动手部署之前理解整个系统的组件和交互流程至关重要。这能帮助你在配置时做出正确决策并在出现问题时快速定位。1.1 Open WebUI 的核心角色Open WebUI 本质上是一个前后端分离的 Web 应用。它不直接提供模型推理能力而是作为一个“中间人”或“客户端”负责用户交互提供聊天界面、会话管理、消息历史、Markdown 渲染等。模型路由将用户输入的消息按照配置转发到对应的后端模型 API如 DeepSeek、OpenAI、Ollama 等。会话与上下文管理维护多轮对话的上下文并将其组装成符合后端 API 要求的格式。扩展功能支持插件、RAG检索增强生成、用户系统、分享功能等。它的工作模式类似于一个高度定制化的 ChatGPT 前端但后端连接的是你自己控制或选择的模型服务。1.2 DeepSeek API 作为推理后端DeepSeek 通过其开放的 API 提供服务。这意味着无需本地算力你不需要昂贵的 GPU 来运行模型推理发生在 DeepSeek 的服务器上。按需付费通常根据 Token 使用量进行计费成本可控。稳定可靠由官方维护保证了服务的可用性和性能。标准接口DeepSeek API 兼容 OpenAI API 格式这使得像 Open WebUI 这样的客户端能够几乎无缝接入。集成后数据流向为用户浏览器 - Open WebUI 服务器 - DeepSeek API 服务器。你的 Open WebUI 服务器需要能够访问公网以调用 DeepSeek API。1.3 用户系统与分享功能的意义默认的 Open WebUI 可能只支持简单的密码保护或无认证。为了实现“可注册、可分享”我们需要启用并正确配置其内置的用户系统。这套系统包括注册与登录允许新用户创建账户。会话隔离不同用户的聊天历史和模型配置相互独立。分享链接用户可以将某个对话会话生成一个唯一的、可分享的只读链接他人无需登录即可查看。管理员权限可以管理用户、查看系统状态。理解了这个架构你就知道我们的配置将围绕三个核心启动 Open WebUI 容器、配置 DeepSeek API 连接、设置用户认证。2. 环境准备与部署 Open WebUI我们将使用 Docker 进行部署这是最简洁、依赖问题最少的方式。请确保你的服务器或本地开发环境已安装 Docker 和 Docker Compose。2.1 基础环境检查首先通过命令行检查 Docker 环境是否就绪。# 检查 Docker 版本 docker --version # 检查 Docker Compose 版本 (如果你使用 compose v2 插件) docker compose version # 拉取一个测试镜像验证 Docker 服务运行正常 docker run hello-world如果上述命令都能成功执行说明 Docker 环境准备完毕。2.2 使用 Docker Compose 部署 Open WebUI创建项目目录并编写docker-compose.yml文件是推荐的做法便于管理和持久化配置。创建项目目录mkdir openwebui-deepseek cd openwebui-deepseek创建docker-compose.yml文件 使用文本编辑器如vim、nano或 VSCode创建该文件。version: 3.8 services: open-webui: image: ghcr.io/open-webui/open-webui:main container_name: open-webui restart: unless-stopped ports: - 3000:8080 # 将宿主机的3000端口映射到容器的8080端口 volumes: - ./data:/app/backend/data # 持久化数据用户、会话、设置等 # - ./custom:/app/backend/custom # 可选挂载自定义前端文件 environment: - OLLAMA_BASE_URLhttp://host.docker.internal:11434 # 如果同时运行Ollama可配置 - WEBUI_SECRET_KEY${WEBUI_SECRET_KEY:-your-very-secret-key-change-me} # 用于加密的密钥务必修改 - WEBUI_NAMEMy DeepSeek AI - WEBUI_URLhttp://localhost:3000 # 你的公开访问地址用于分享链接生成 # 用户认证相关配置 - ENABLE_SIGNUPtrue # 启用用户注册功能 - USER_DEFAULT_MODELS[deepseek-chat] # 新用户默认拥有的模型 - DEFAULT_MODELdeepseek-chat # 默认聊天模型 extra_hosts: - host.docker.internal:host-gateway # 使容器能访问宿主机服务 networks: - webui-network networks: webui-network: driver: bridge关键配置解释ports: “3000:8080”Open WebUI 服务运行在容器内的 8080 端口我们通过宿主机的 3000 端口访问。volumes: ./data:/app/backend/data将本地./data目录挂载到容器内用于保存所有数据。这是最重要的持久化配置务必设置。WEBUI_SECRET_KEY用于加密会话和令牌的密钥。在生产环境中必须将其修改为强随机字符串并通过外部环境变量或.env文件注入切勿使用默认值。WEBUI_URL这个地址用于生成可分享的对话链接。如果你通过域名访问例如https://ai.yourdomain.com这里就需要改为对应的域名。ENABLE_SIGNUPtrue这是实现“可注册”功能的关键开关。USER_DEFAULT_MODELS和DEFAULT_MODEL我们预先配置一个名为deepseek-chat的模型后续步骤会在 Open WebUI 界面中添加它。启动服务 在docker-compose.yml同级目录下运行docker compose up -d-d参数表示在后台运行。首次运行会从镜像仓库拉取 Open WebUI 镜像可能需要一些时间。验证服务运行# 查看容器状态 docker compose ps # 查看容器日志 docker compose logs -f open-webui当在日志中看到类似Application startup complete或Uvicorn running on的信息时说明服务已启动成功。访问 Web 界面 打开浏览器访问http://你的服务器IP:3000或http://localhost:3000。你应该能看到 Open WebUI 的登录/注册页面。3. 配置 Open WebUI 接入 DeepSeek API服务启动后我们需要在 Open WebUI 的管理界面中添加 DeepSeek 作为可用的模型提供商。3.1 获取 DeepSeek API Key访问 DeepSeek 开放平台 。注册并登录账号。在控制台界面找到 “API Keys” 或类似菜单。点击 “Create new API key”为其命名例如 “openwebui-key”并复制生成的密钥字符串。此密钥只会显示一次请妥善保存。3.2 在 Open WebUI 中添加 DeepSeek 模型连接初始登录首次访问 Open WebUI你需要创建一个管理员账户。点击 “Sign Up” 进行注册然后登录。进入模型设置登录后点击左下角的你的用户名或设置图标进入 “Settings”。在设置侧边栏选择 “Model”。添加新模型点击 “Add Model” 或 “Connect Model” 按钮。填写模型配置选择模型提供商类型。由于 DeepSeek API 兼容 OpenAI我们通常选择“OpenAI”或“OpenAI Compatible”。Model Name: 输入一个你喜欢的显示名称例如deepseek-chat。这个名称需要与docker-compose.yml中USER_DEFAULT_MODELS和DEFAULT_MODEL的值对应。Model ID: 对于 DeepSeek此处应填写其官方的模型名称例如deepseek-chat。你可以在 DeepSeek API 文档中确认最新的模型名称。Base URL: 填写 DeepSeek 的 API 端点https://api.deepseek.com。API Key: 粘贴你刚才复制的 DeepSeek API Key。其他参数保持默认即可如context_length可以设置为16384根据 DeepSeek 模型的实际上下文长度调整。一个完整的配置示例如下具体字段名称可能因 Open WebUI 版本略有不同注意请务必根据 DeepSeek 官方文档确认最新的 API 地址和模型名称。保存并测试保存配置后该模型应该会出现在模型列表中。你可以返回主聊天界面在模型选择下拉框中看到deepseek-chat。选择它发送一条测试消息如“你好”如果收到 DeepSeek 的回复说明连接成功。3.3 配置用户默认模型可选但推荐为了让新注册的用户自动拥有使用 DeepSeek 的权限我们已经在docker-compose.yml中通过USER_DEFAULT_MODELS环境变量进行了预配置。如果你在界面中添加的模型名称不是deepseek-chat则需要同步修改环境变量中的值。你也可以在 Open WebUI 的Admin Panel管理员面板通常只有第一个注册的用户是管理员中对用户或用户组进行更精细的模型权限管理。4. 实现用户注册与分享功能我们已经通过环境变量ENABLE_SIGNUPtrue开启了注册功能。现在来深入配置和测试用户系统。4.1 自定义认证方式邮箱 vs 用户名Open WebUI 默认可能使用邮箱作为登录凭证。如果你想改为“用户名登录”这通常需要修改前端或配置。更常见的需求是同时允许用户名和邮箱登录。目前 Open WebUI 的较新版本在注册表单中可能同时提供了用户名和邮箱字段。如果默认界面只有邮箱你可以尝试通过以下方式寻找配置或修改方案检查环境变量查阅 Open WebUI 的官方文档看是否有如AUTH_PROVIDER、LOGIN_FIELD等环境变量。修改前端文件高级如果环境变量不支持可以尝试挂载自定义前端文件如前面docker-compose.yml中注释掉的custom卷覆盖登录/注册组件。但这需要前端开发知识。对于大多数场景使用邮箱注册和登录已经足够。分享功能不依赖于登录方式是邮箱还是用户名。4.2 测试用户注册流程在浏览器中打开 Open WebUI 的登录页面http://你的地址:3000。点击 “Sign Up” 链接。填写注册表单邮箱、用户名、密码等。提交后系统应自动登录并进入聊天主界面。新注册的用户应该能看到并选择deepseek-chat模型。使用另一个浏览器或隐身窗口重复上述步骤注册第二个用户。验证两个用户的聊天会话是否完全独立。4.3 使用对话分享功能分享功能是 Open WebUI 的内置特性无需额外配置。生成分享链接在一个用户中进行一段对话。在对话历史侧边栏找到该会话。点击会话旁边的菜单通常是三个点…或一个分享图标。选择 “Share” 或 “Get share link”。系统会生成一个唯一的 URL 链接并复制到剪贴板。访问分享链接在未登录的浏览器或另一个用户的会话中打开此链接。你将能够以只读方式查看该对话的全部内容但不能进行回复或修改。页面通常不会有登录入口纯粹是对话内容的展示。这个功能非常适合将有趣的对话结果分享给同事、朋友或社区而无需透露你的 API Key 或让他们登录你的系统。5. 关键配置详解与生产环境建议为了让你的 AI 网站更稳定、安全以下是一些关键配置的深入解释和生产环境部署建议。5.1 安全相关配置配置项学习/测试环境值生产环境建议作用与风险WEBUI_SECRET_KEYyour-very-secret-key-change-me使用强随机字符串通过.env文件或服务器环境变量管理用于加密会话和 JWT 令牌。泄露会导致用户会话被伪造。ENABLE_SIGNUPtrue初期可设为true吸引用户后期可设为false并手动创建用户控制是否开放公开注册。开放注册需做好防垃圾账号和滥用准备。WEBUI_URLhttp://localhost:3000必须设置为真实的公网访问地址如https://ai.yourdomain.com分享链接和某些回调地址的基础。错误设置会导致分享链接无法访问。端口映射 (ports)3000:8080建议使用反向代理如 Nginx监听 80/443 端口代理到内部3000或8080直接暴露端口安全性较低。使用反向代理可以方便地配置 SSL、域名、限流等。创建.env文件管理密钥 在docker-compose.yml同级目录创建.env文件# .env 文件 WEBUI_SECRET_KEY你的强随机密钥_这里是一长串无规律的字符然后修改docker-compose.yml引用这个变量environment: - WEBUI_SECRET_KEY${WEBUI_SECRET_KEY}启动时Docker Compose 会自动读取.env文件。务必确保.env文件不被提交到 Git 等版本控制系统应将其加入.gitignore。5.2 性能与资源管理API 调用限流与费用控制DeepSeek API 按 Token 计费。Open WebUI 本身不提供用量限制功能。你需要在 DeepSeek 平台设置 API Key 的用量限制或预算告警。或者考虑在反向代理层如 Nginx对 IP 或用户进行速率限制。告知用户合理使用避免高频、无意义的请求。数据持久化确保./data卷挂载正确并定期备份此目录。这里面包含了所有用户数据、设置和对话历史如果本地保存了历史。容器资源限制可以在docker-compose.yml中为open-webui服务添加资源限制防止其占用过多宿主机资源。services: open-webui: # ... 其他配置 ... deploy: resources: limits: memory: 1G cpus: 0.55.3 使用 Nginx 反向代理与 SSL生产环境强烈建议使用 Nginx 或 Caddy 等反向代理并配置 SSL 证书如 Let‘s Encrypt 的免费证书。一个简单的 Nginx 配置示例 (/etc/nginx/sites-available/openwebui)server { listen 80; server_name ai.yourdomain.com; # 你的域名 return 301 https://$server_name$request_uri; } server { listen 443 ssl http2; server_name ai.yourdomain.com; ssl_certificate /path/to/your/fullchain.pem; ssl_certificate_key /path/to/your/privkey.pem; # 其他 SSL 优化配置... location / { proxy_pass http://localhost:3000; # 指向 Docker 映射的端口 proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_read_timeout 300s; # 长连接超时设置适应流式响应 proxy_send_timeout 300s; } }配置后用户将通过https://ai.yourdomain.com安全地访问你的 AI 网站。6. 常见问题排查在部署和使用过程中你可能会遇到以下问题。这里提供排查思路。6.1 模型连接失败或报错 “Invalid API Key”现象可能原因检查与解决步骤聊天界面显示“连接错误”、“模型不可用”或“Invalid API Key”1. DeepSeek API Key 错误或失效2. Base URL 填写错误3. 网络问题导致无法访问 DeepSeek API4. 账户欠费或额度用尽1.检查 API Key在 DeepSeek 平台确认 Key 状态尝试重新生成一个。2.检查 Base URL确认是https://api.deepseek.com。3.测试网络连通性在运行 Open WebUI 的服务器上执行curl https://api.deepseek.com/v1/models -H “Authorization: Bearer YOUR_API_KEY”看是否能返回模型列表。4.检查余额登录 DeepSeek 平台查看账户余额和用量。6.2 用户注册功能不显示或报错现象可能原因检查与解决步骤登录页面没有 “Sign Up” 按钮ENABLE_SIGNUP环境变量未生效或设置为false1. 检查docker-compose.yml中ENABLE_SIGNUP的值是否为true。2. 重启容器docker compose down docker compose up -d。3. 查看容器日志确认环境变量被正确加载docker compose logs open-webui | grep ENABLE_SIGNUP。注册时提示“邮箱已存在”等错误数据卷 (./data) 中已存在该用户1. 如果是测试可以停止容器后删除本地的./data目录注意这会清空所有数据然后重启。2. 生产环境请通过管理员面板查看和管理用户。6.3 分享链接无法访问或显示错误现象可能原因检查与解决步骤打开分享链接显示空白、404 或 “Invalid session”WEBUI_URL环境变量配置错误1.确认WEBUI_URL它必须与用户浏览器访问网站的地址一致。如果你通过http://ip:3000访问WEBUI_URL就不能是http://localhost:3000。2.生产环境必须设置为带域名的 HTTPS 地址如https://ai.yourdomain.com。3. 修改后重启容器。分享链接内容加载不全网络或反向代理超时设置过短1. 如果使用了 Nginx确保proxy_read_timeout和proxy_send_timeout设置得足够大例如 300 秒。2. 检查服务器防火墙是否放行了相关端口。6.4 容器启动失败或端口冲突端口被占用如果宿主机 3000 端口已被其他程序占用Docker Compose 会启动失败。可以修改docker-compose.yml中的端口映射例如改为“3001:8080”。权限问题如果挂载的./data目录宿主机权限不足可能导致容器内应用无法写入。确保该目录对 Docker 进程可写通常chmod 777 ./data可以临时解决生产环境应配置更严格的权限。镜像拉取失败检查网络确认能访问ghcr.io。可以尝试手动拉取docker pull ghcr.io/open-webui/open-webui:main。7. 扩展方向与最佳实践成功搭建基础服务后你可以考虑以下方向进行深化和优化。7.1 集成更多模型与多模型路由Open WebUI 支持同时连接多个模型提供商。你可以在 “Settings” - “Model” 中添加 OpenAI、Google Gemini、Anthropic Claude如果支持或本地部署的 Ollama 模型。用户可以在聊天时自由切换实现“一站式”比较不同模型的效果。7.2 启用 RAG检索增强生成功能Open WebUI 内置了 RAG 支持。你可以在设置中启用 “Document Upload” 功能。用户可以将 PDF、TXT、Word 等文档上传到知识库。在聊天时选择“使用上下文”或“搜索知识库”模型在回答时会优先参考你上传的文档内容。 这对于构建基于私有知识的问答机器人非常有用。7.3 实施监控与日志应用日志定期查看 Open WebUI 容器日志docker compose logs --tail100 open-webui关注错误和警告。API 用量监控密切关注 DeepSeek 平台提供的用量统计和费用仪表盘设置预算告警。服务器监控监控服务器的 CPU、内存、磁盘和网络流量确保服务稳定。7.4 制定用户管理策略关闭公开注册当用户量达到预期后可以将ENABLE_SIGNUP设为false转为邀请制或手动创建用户。角色与权限利用管理员面板可以为不同用户分配不同的模型访问权限例如只允许部分用户使用高成本的模型。会话管理提醒用户及时清理无用的对话历史以减轻数据存储压力如果历史保存在本地。通过以上步骤你不仅快速搭建了一个可用的 AI 网站更建立了一个可扩展、易维护的基础架构。核心在于理解 Open WebUI 作为前端聚合器的定位以及通过环境变量和配置文件对其行为进行精细化控制。后续的优化都应围绕安全、成本、用户体验和可维护性展开。