用過 Hermes Agent 的朋友應(yīng)該都知道，它的命令行操作對(duì)新手不太友好，很多簡(jiǎn)單的操作都需要記復(fù)雜指令，上手門檻不低。好在現(xiàn)在有了 Hermes WebUI，通過可視化界面就能輕松操作 Hermes Agent，極大降低了使用難度。今天就給大家詳細(xì)講解，如何在 Windows（PowerShell）和 Linux 環(huán)境下，用 Docker 快速部署 Hermes WebUI，實(shí)現(xiàn)本地 AI Web 界面的快速運(yùn)行與訪問。

前置準(zhǔn)備：Docker 環(huán)境一鍵搞定

部署 Hermes WebUI 之前，必須先搭好 Docker 環(huán)境。這里給大家準(zhǔn)備了適配全場(chǎng)景的一鍵安裝方案，Linux 系統(tǒng)（包括國(guó)產(chǎn)系統(tǒng)如銀河麒麟、歐拉）可直接使用，Windows 和 Mac 用戶操作也很簡(jiǎn)單。

1. Linux 系統(tǒng) Docker 一鍵安裝

直接執(zhí)行一條命令，就能自動(dòng)安裝 Docker、Docker Compose，省去手動(dòng)配置的麻煩：

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

2. Windows / Mac 用戶

直接前往 Docker 官網(wǎng)下載 Docker Desktop，按照安裝向?qū)б徊讲讲僮骷纯?。安裝完成后啟動(dòng) Docker，圖形化界面操作簡(jiǎn)單，無需復(fù)雜配置，等待啟動(dòng)完成就可以使用了。

一、環(huán)境準(zhǔn)備

Windows 環(huán)境

• 操作系統(tǒng)：Windows 10 / 11（64位，需開啟 WSL 2，Docker Desktop 安裝時(shí)可自動(dòng)開啟）
• 已安裝：Docker Desktop（啟動(dòng)狀態(tài)）
• 終端工具：PowerShell（系統(tǒng)自帶，管理員身份運(yùn)行更佳）
• 可用端口：推薦 3001（若被占用可更換）

Linux 環(huán)境

• 操作系統(tǒng)：CentOS、Ubuntu、銀河麒麟、歐拉等主流 Linux 發(fā)行版
• 已安裝：Docker、Docker Compose（通過上面的一鍵腳本已完成安裝）
• 終端工具：任意 Linux 終端（Xshell、Putty 或系統(tǒng)自帶終端均可）
• 可用端口：推薦 3001（若被占用可更換）

二、拉取 Hermes WebUI 鏡像

無論是 Windows 還是 Linux 環(huán)境，拉取鏡像的命令基本一致，區(qū)別僅在于終端工具（PowerShell / Linux 終端），直接執(zhí)行以下命令即可（使用軒轅鏡像，請(qǐng)將 ***-ghcr.xuanyuan.run 替換為你自己的軒轅鏡像專屬域名）：

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

等待鏡像拉取完成，若拉取速度較慢，可檢查 Docker 鏡像加速是否配置成功（一鍵腳本已自動(dòng)配置軒轅鏡像，無需額外操作）。

三、創(chuàng)建本地?cái)?shù)據(jù)目錄（用于持久化）

為了避免容器重啟后數(shù)據(jù)丟失（如會(huì)話記錄、配置信息等），需要?jiǎng)?chuàng)建本地目錄并掛載到容器中，雙系統(tǒng)操作如下：

Windows（PowerShell）

mkdir C:\docker\hermes

Linux 終端

mkdir -p /root/docker/hermes

說明：Linux 目錄可自定義，比如 /home/docker/hermes，后續(xù)部署命令對(duì)應(yīng)修改路徑即可。

四、標(biāo)準(zhǔn)部署方式

部署核心是通過 docker run 命令啟動(dòng)容器，配置端口映射、環(huán)境變量和目錄掛載，確保服務(wù)穩(wěn)定運(yùn)行，雙系統(tǒng)命令分別如下：

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：后臺(tái)運(yùn)行容器，不占用終端
• --name hermes-webui：給容器命名為 hermes-webui，方便后續(xù)管理（如停止、刪除容器）
• -p 3001:8787：端口映射，將宿主機(jī) 3001 端口映射到容器 8787 端口（容器內(nèi)部默認(rèn)端口為 8787）
• -e HERMES_WEBUI_STATE_DIR=/app/data：必須設(shè)置的環(huán)境變量，指定容器內(nèi)數(shù)據(jù)存儲(chǔ)目錄，否則容器會(huì)反復(fù)重啟
• -v 本地目錄:/app/data：將本地創(chuàng)建的目錄掛載到容器 /app/data 目錄，實(shí)現(xiàn)數(shù)據(jù)持久化
• --restart unless-stopped：容器異常停止時(shí)自動(dòng)重啟，保證服務(wù)穩(wěn)定性

五、訪問 Hermes WebUI

容器啟動(dòng)成功后，無需額外配置，直接通過瀏覽器訪問即可，雙系統(tǒng)訪問地址一致：

http://localhost:3001

若在遠(yuǎn)程服務(wù)器部署（Linux 服務(wù)器），則訪問：http://服務(wù)器IP:3001（需確保服務(wù)器 3001 端口已開放）。

訪問成功后，即可看到 Hermes WebUI 的可視化界面，后續(xù)操作都可以在界面上完成，比命令行簡(jiǎn)單太多。

六、運(yùn)行架構(gòu)說明

為了讓大家更清楚服務(wù)的運(yùn)行邏輯，整理了核心配置信息，一目了然：

七、常見問題排查

部署過程中難免遇到問題，整理了 4 個(gè)最常見的問題及解決方法，新手可直接對(duì)照排查：

1?? 端口被占用

現(xiàn)象：執(zhí)行部署命令后，提示 “ports are not available”，無法啟動(dòng)容器。

解決方法：更換宿主機(jī)映射端口，比如將 3001 改為 3002，修改命令中的 -p 3002:8787 即可。

2?? 頁面無法訪問（ERR_CONNECTION_REFUSED）

原因：大概率是容器未正常啟動(dòng)，可能是環(huán)境變量或目錄掛載配置錯(cuò)誤。

排查步驟：執(zhí)行以下命令，查看正在運(yùn)行的容器，確認(rèn) hermes-webui 容器是否在列。

docker ps

若未在列，執(zhí)行 docker ps -a 查看容器狀態(tài)，進(jìn)一步排查錯(cuò)誤原因。

3?? 容器反復(fù)重啟

現(xiàn)象：容器啟動(dòng)后，很快自動(dòng)停止，反復(fù)循環(huán)，無法穩(wěn)定運(yùn)行。

排查方法：查看容器日志，定位錯(cuò)誤原因。

docker logs hermes-webui

常見原因：未設(shè)置 HERMES_WEBUI_STATE_DIR 環(huán)境變量，或環(huán)境變量路徑與掛載路徑不一致。

解決方法：確保部署命令中包含 -e HERMES_WEBUI_STATE_DIR=/app/data，且掛載路徑正確。

4?? 容器已存在沖突

現(xiàn)象：執(zhí)行部署命令時(shí)，提示 “container name already in use”。

原因：之前已部署過 hermes-webui 容器，容器名稱重復(fù)。

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

docker rm -f hermes-webui

八、AI 模型接入說明

Hermes WebUI 支持多種模型后端，無需復(fù)雜配置，可以部署后，在網(wǎng)頁接入，也可以通過環(huán)境變量即可接入，常用的有 3 種：OpenAI、OpenRouter、Ollama。

以 OpenAI 為例，部署時(shí)添加 OpenAI API Key 環(huán)境變量即可，修改后的部署命令（以 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

九、推薦進(jìn)階部署方式

如果是企業(yè)或正式使用，不推薦用單條 docker run 命令部署，建議采用以下方式，更易管理和維護(hù)：

• 用 docker-compose 管理容器，將所有配置（端口、環(huán)境變量、掛載目錄）寫入 docker-compose.yml 文件，一鍵啟動(dòng)、停止。
• 堅(jiān)持?jǐn)?shù)據(jù)卷持久化，避免容器刪除后數(shù)據(jù)丟失，可根據(jù)需求備份本地掛載目錄。
• 統(tǒng)一管理 API KEY 等敏感信息，避免直接暴露在命令中，可通過 .env 文件管理環(huán)境變量。
• 使用獨(dú)立的 AI 模型提供商（如 Ollama 本地部署模型），減少對(duì)外部網(wǎng)絡(luò)的依賴，提升訪問速度。

十、總結(jié)

其實(shí) Hermes WebUI 的 Docker 部署并不復(fù)雜，核心就 3 點(diǎn)，只要滿足這 3 點(diǎn)，無論是 Windows 還是 Linux 環(huán)境，都能穩(wěn)定運(yùn)行：

1. 正確配置端口映射（容器 8787 端口映射到宿主機(jī)任意可用端口）；
2. 必須設(shè)置 HERMES_WEBUI_STATE_DIR 環(huán)境變量，指定容器內(nèi)數(shù)據(jù)存儲(chǔ)目錄；
3. 必須掛載本地目錄到容器 /app/data，實(shí)現(xiàn)數(shù)據(jù)持久化。

Hermes Agent 鏡像中文地址：https://xuanyuan.cloud/zh/r/nousresearch/hermes-agent，以及 Hermes WebUI 鏡像中文地址：https://xuanyuan.cloud/ghcr.io/nesquena/hermes-webui?tag=latest，有需要的可以收藏。

對(duì)于新手來說，無需深入理解 Docker 原理，跟著教程一步步執(zhí)行命令，就能快速部署成功。有了 Hermes WebUI，再也不用記復(fù)雜的 Hermes Agent 命令行，可視化操作更簡(jiǎn)單、更高效。如果部署過程中遇到其他問題，歡迎在評(píng)論區(qū)留言交流～

以上就是Docker一鍵部署Hermes WebUI完整教程(Windows\+Linux)的詳細(xì)內(nèi)容，更多關(guān)于Docker部署Hermes WebUI的資料請(qǐng)關(guān)注腳本之家其它相關(guān)文章！

最新評(píng)論