Docker一键部署Hermes WebUI实践教程(Windows\+Linux)实用指南

平时做技术实践时，很多问题不是概念不会，而是细节没串起来。拿“Docker一键部署Hermes WebUI实践教程(Windows\+……”来说，它看着像小点，放到项目里常会牵出环境、配置、兼容性和维护成本。下面按实际采用顺序，把思路、关键写法和容易踩坑的地方讲清楚，便于大家直接对照操作。

落到代码里，用过 Hermes Agent 的朋友应该都知道，它的命令行操作对新手不太友好，很多轻松的操作都需记复杂指令，上手门槛不低。好在现在有了 Hermes WebUI，借助可视化界面就能轻松操作 Hermes Agent，极大降低了采用难度。今天就给大家细致说明，如何在 Windows（PowerShell）和 Linux 环境下，用 Docker 更快部署 Hermes WebUI，实现本地 AI Web 界面的更快运行与访问。

前置准备：Docker 环境一键搞定

在这个场景下，部署 Hermes WebUI 之前，必须先搭好 Docker 环境。这里给大家准备了适配全场景的一键安装方案，Linux 系统（包括国产系统如银河麒麟、欧拉）可直接采用，Windows 和 Mac 用户操作也很轻松。

1. Linux 系统 Docker 一键安装

从实现思路看，直接执行一条命令，就能自动安装 Docker、Docker Compose，省去手动设置的麻烦：

bash <(wget -qO- https://xuanyuan.cloud/docker.sh)

2. Windows / Mac 用户

落到代码里，直接前往 Docker 官网下载 Docker Desktop，按照安装向导一步步操作即可。安装完成后启动 Docker，图形化界面操作轻松，无需复杂设置，等待启动完成就能够采用了。

一、环境准备

Windows 环境

• 操作系统：Windows 10 / 11（64位，需开启 WSL 2，Docker Desktop 安装时可自动开启）
• 已安装：Docker Desktop（启动状态）
• 终端工具：PowerShell（系统自带，管理员身份运行更佳）
• 可用端口：建议 3001（若被占用可更换）

Linux 环境

• 操作系统：CentOS、Ubuntu、银河麒麟、欧拉等主流 Linux 发行版
• 已安装：Docker、Docker Compose（借助上面的一键脚本已完成安装）
• 终端工具：任意 Linux 终端（Xshell、Putty 或系统自带终端均可）
• 可用端口：建议 3001（若被占用可更换）

二、拉取 Hermes WebUI 镜像

在这个场景下，无论是 Windows 还是 Linux 环境，拉取镜像的命令基本一致，区别仅在于终端工具（PowerShell / Linux 终端），直接执行以下命令即可（采用轩辕镜像，请将 ***-ghcr.xuanyuan.run 替换为你自己的轩辕镜像专属域名）：

docker pull ***-ghcr.xuanyuan.run/nesquena/hermes-webui:latest

实际处理时，等待镜像拉取完成，若拉取速度较慢，可检查 Docker 镜像加速是否设置成功（一键脚本已自动设置轩辕镜像，无需额外操作）。

三、新建本地数据目录（用来持久化）

理解这一步时，为便于避免容器重启后数据丢失（如会话记录、设置信息等），需新建本地目录并挂载到容器中，双系统操作如下所示：

Windows（PowerShell）

mkdir C:\docker\hermes

Linux 终端

mkdir -p /root/docker/hermes

说明：Linux 目录可自定义，比如 /home/docker/hermes，后续部署命令对应修改路径即可。

四、标准部署方式

结合项目来看，部署核心是借助 docker run 命令启动容器，设置端口映射、环境变量和目录挂载，确保服务稳定运行，双系统命令分别如下所示：

Windows（PowerShell）

docker run -d --name hermes-webui -p 3001:8787 `
-e HERMES_WEBUI_STATE_DIR=/app/data `
-v C:\docker\hermes:/app/data `
--restart unless-stopped `
***-ghcr.xuanyuan.run/nesquena/hermes-webui:latest

Linux 终端

docker run -d --name hermes-webui -p 3001:8787 \
-e HERMES_WEBUI_STATE_DIR=/app/data \
-v /root/docker/hermes:/app/data \
--restart unless-stopped \
***-ghcr.xuanyuan.run/nesquena/hermes-webui:latest

命令说明：

• -d：后台运行容器，不占用终端
• 在这个场景下，--name hermes-webui：给容器命名为 hermes-webui，便于后续管理（如停止、删除容器）
• 从实现思路看，-p 3001:8787：端口映射，将宿主机 3001 端口映射到容器 8787 端口（容器内部默认端口为 8787）
• 理解这一步时，-e HERMES_WEBUI_STATE_DIR=/app/data：必须设置的环境变量，指定容器内数据存储目录，否则容器会反复重启
• 实际处理时，-v 本地目录:/app/data：将本地新建的目录挂载到容器 /app/data 目录，实现数据持久化
• 实际处理时，--restart unless-stopped：容器异常停止时自动重启，保证服务稳定性

五、访问 Hermes WebUI

实际处理时，容器启动成功后，无需额外设置，直接借助浏览器访问即可，双系统访问地址一致：

（链接已移除）

从实现思路看，若在远程服务器部署（Linux 服务器），则访问：（链接已移除）（需确保服务器 3001 端口已开放）。

从实现思路看，访问成功后，即可看到 Hermes WebUI 的可视化界面，后续操作都能够在界面上完成，比命令行轻松太多。

六、运行架构说明

为便于让大家更清楚服务的运行逻辑，整理了核心设置信息，一目了然：

七、常用问题排查

结合项目来看，部署过程中难免遇到问题，整理了 4 个最常用的问题及解决方法，新手可直接对照排查：

1 端口被占用

现象：执行部署命令后，提示 “ports are not available”，无法启动容器。

解决方法：更换宿主机映射端口，比如将 3001 改为 3002，修改命令中的 -p 3002:8787 即可。

2 页面无法访问（ERR_CONNECTION_REFUSED）

原因：大概率是容器未正常启动，可能是环境变量或目录挂载设置错误。

排查步骤：执行以下命令，查看正在运行的容器，确认 hermes-webui 容器是否在列。

docker ps

落到代码里，若未在列，执行 docker ps -a 查看容器状态，进一步排查错误原因。

3 容器反复重启

现象：容器启动后，很快自动停止，反复循环，无法稳定运行。

排查方法：查看容器日志，定位错误原因。

docker logs hermes-webui

常用原因：未设置 HERMES_WEBUI_STATE_DIR 环境变量，或环境变量路径与挂载路径不一致。

解决方法：确保部署命令中包含 -e HERMES_WEBUI_STATE_DIR=/app/data，且挂载路径正确。

4 容器已存在冲突

现象：执行部署命令时，提示 “container name already in use”。

原因：之前已部署过 hermes-webui 容器，容器名称重复。

解决方法：删除已存在的容器，再重新部署。

docker rm -f hermes-webui

八、AI 模型接入说明

实际处理时，Hermes WebUI 兼容多种模型后端，无需复杂设置，能够部署后，在网页接入，也能够借助环境变量即可接入，常用的有 3 种：OpenAI、OpenRouter、Ollama。

结合项目来看，以 OpenAI 为例，部署时添加 OpenAI API Key 环境变量即可，修改后的部署命令（以 Linux 为例，Windows 仅需将 \ 改为 `）：

docker run -d --name hermes-webui -p 3001:8787 \
-e HERMES_WEBUI_STATE_DIR=/app/data \
-e OPENAI_API_KEY=sk-xxxxxxx（替换为你的API Key） \
-v /root/docker/hermes:/app/data \
--restart unless-stopped \
***-ghcr.xuanyuan.run/nesquena/hermes-webui:latest

九、建议进阶部署方式

实际处理时，若是企业或正式采用，不建议用单条 docker run 命令部署，建议采用以下方式，更易管理和维护：

• 理解这一步时，用 docker-compose 管理容器，将所有设置（端口、环境变量、挂载目录）写入 docker-compose.yml 文件，一键启动、停止。
• 坚持数据卷持久化，避免容器删除后数据丢失，可根据需求备份本地挂载目录。
• 落到代码里，统一管理 API KEY 等敏感信息，避免直接暴露在命令中，可借助 .env 文件管理环境变量。
• 落到代码里，采用独立的 AI 模型提供商（如 Ollama 本地部署模型），减少对外部网络的依赖，提升访问速度。

十、总结

理解这一步时，其实 Hermes WebUI 的 Docker 部署同时不复杂，核心就 3 点，只要满足这 3 点，无论是 Windows 还是 Linux 环境，都能稳定运行：

1. 正确设置端口映射（容器 8787 端口映射到宿主机任意可用端口）；
2. 在这个场景下，必须设置 HERMES_WEBUI_STATE_DIR 环境变量，指定容器内数据存储目录；
3. 必须挂载本地目录到容器 /app/data，实现数据持久化。

结合项目来看，Hermes Agent 镜像中文地址：（链接已移除），以及 Hermes WebUI 镜像中文地址：（链接已移除），有需的能够收藏。

结合项目来看，对于新手来说，无需深入理解 Docker 原理，跟着教程一步步执行命令，就能更快部署成功。有了 Hermes WebUI，再也不用记复杂的 Hermes Agent 命令行，可视化操作更轻松、更高效。如果部署过程中遇到其他问题，欢迎在评论区留言交流～

结合项目来看，以上就是Docker一键部署Hermes WebUI完整教程(Windows\+Linux)的详细内容，更多关于Docker部署Hermes WebUI的资料请关注脚本之家其它相关文章！