1. 為什么 Hermes Agent 的部署值得單獨(dú)寫一篇Hermes Agent 這個項(xiàng)目最近在圈子里討論度很高但真正動手部署過的人都知道它的環(huán)境配置比一般的工具類項(xiàng)目要復(fù)雜一些。原因不復(fù)雜它同時涉及本地開發(fā)環(huán)境、容器運(yùn)行時、網(wǎng)絡(luò)端口映射、服務(wù)?；畹榷鄠€環(huán)節(jié)任何一個環(huán)節(jié)出問題服務(wù)都起不來。我前后在 Windows 和 Linux 上部署過五六次踩過的坑包括 WSL2 網(wǎng)絡(luò)模式選錯導(dǎo)致端口不通、云服務(wù)器安全組沒放行、Docker 鏡像拉取超時、systemd 服務(wù)寫錯路徑導(dǎo)致反復(fù)重啟等等。這篇內(nèi)容就是把這些經(jīng)驗(yàn)整理出來給準(zhǔn)備上手 Hermes Agent 的人一條清晰的路徑。不管你是用 Windows WSL2 做本地開發(fā)調(diào)試還是直接買一臺云服務(wù)器做長期運(yùn)行都能找到對應(yīng)的操作步驟。文章會覆蓋 WSL2 安裝與配置、云服務(wù)器選型與初始化、Docker 環(huán)境搭建、Hermes Agent 服務(wù)啟動、狀態(tài)校驗(yàn)、常見故障排查這幾個核心環(huán)節(jié)。每個步驟我都會說明為什么這么做以及不做會出什么問題。適合的讀者有基本 Linux 命令行操作經(jīng)驗(yàn)了解 Docker 基本概念想在本地或云端跑起 Hermes Agent 服務(wù)的開發(fā)者。完全沒接觸過 WSL2 也沒關(guān)系安裝部分我會寫得足夠細(xì)。2. 本地環(huán)境方案選型為什么是 WSL2 而不是虛擬機(jī)或雙系統(tǒng)2.1 WSL2 與虛擬機(jī)、雙系統(tǒng)的對比在 Windows 上跑 Hermes Agent常見的選擇有三種VMware/VirtualBox 虛擬機(jī)、雙系統(tǒng)、WSL2。我三種都用過最終長期留在 WSL2 上原因如下。虛擬機(jī)方案的問題是資源占用高。你開一個 Ubuntu 虛擬機(jī)至少吃掉 2GB 內(nèi)存和 20GB 磁盤而且文件系統(tǒng)是隔離的想在 Windows 和 Linux 之間共享代碼需要配置共享文件夾性能損耗明顯。雙系統(tǒng)更麻煩切換要重啟開發(fā)效率極低。WSL2 的優(yōu)勢在于它是 Windows 內(nèi)核支持的輕量級虛擬化方案啟動速度快內(nèi)存按需分配文件系統(tǒng)可以直接通過/mnt/c/訪問 Windows 盤符。更重要的是WSL2 支持 systemd這意味著你可以在里面跑 Docker、配置服務(wù)自啟體驗(yàn)和原生 Linux 幾乎一致。注意WSL2 和 WSL1 有本質(zhì)區(qū)別。WSL1 是系統(tǒng)調(diào)用翻譯層很多 Docker 相關(guān)功能跑不起來。Hermes Agent 的部署必須用 WSL2不要用 WSL1。2.2 WSL2 的版本要求與前置檢查WSL2 對 Windows 版本有要求。Windows 10 需要 1903 及以上版本內(nèi)部版本 18362 以上Windows 11 全版本支持。檢查方法很簡單按Win R輸入winver看版本號。另外需要確認(rèn) CPU 虛擬化已開啟。任務(wù)管理器 → 性能 → CPU看右下角“虛擬化”是否顯示“已啟用”。如果顯示“已禁用”需要進(jìn) BIOS 開啟 Intel VT-x 或 AMD-V。這一步很多人會忽略結(jié)果 WSL2 裝完啟動報錯。還有一個容易踩的坑如果你的系統(tǒng)裝過 WSL1需要先卸載舊版本再裝 WSL2否則可能出現(xiàn)版本沖突。卸載命令是wsl --unregister 發(fā)行版名稱注意這會刪除該發(fā)行版內(nèi)的所有數(shù)據(jù)。2.3 安裝 WSL2 與 Ubuntu 22.04 的完整步驟我推薦用 Ubuntu 22.04 LTS原因是它的軟件源穩(wěn)定Docker 官方支持好社區(qū)資料多。Ubuntu 24.04 也可以但部分第三方工具的兼容性還在跟進(jìn)中。安裝步驟以管理員身份打開 PowerShell執(zhí)行wsl --install。這條命令會自動啟用虛擬機(jī)平臺和 WSL 功能并安裝默認(rèn)的 Ubuntu 發(fā)行版。如果只想裝 Ubuntu 22.04先執(zhí)行wsl --list --online查看可用發(fā)行版然后執(zhí)行wsl --install -d Ubuntu-22.04。安裝完成后重啟電腦。重啟后 Ubuntu 會自動啟動要求設(shè)置用戶名和密碼。這個密碼是 sudo 密碼記牢。驗(yàn)證版本執(zhí)行wsl -l -v確認(rèn) Ubuntu-22.04 的 VERSION 顯示為 2。如果顯示 1執(zhí)行wsl --set-version Ubuntu-22.04 2轉(zhuǎn)換。提示如果wsl --install報錯“請求的名稱有效但找不到請求的數(shù)據(jù)”通常是網(wǎng)絡(luò)問題導(dǎo)致無法從微軟服務(wù)器下載發(fā)行版?？梢試L試手動下載 Ubuntu 22.04 的 appx 包安裝或者換一個網(wǎng)絡(luò)環(huán)境重試。2.4 WSL2 網(wǎng)絡(luò)模式與端口映射的關(guān)鍵配置WSL2 默認(rèn)使用 NAT 網(wǎng)絡(luò)模式這意味著 WSL2 內(nèi)部的 IP 和 Windows 主機(jī)的 IP 不在同一網(wǎng)段。你在 WSL2 里跑一個服務(wù)監(jiān)聽 8080 端口Windows 主機(jī)上通過localhost:8080能訪問但局域網(wǎng)內(nèi)其他機(jī)器訪問不了。如果你需要局域網(wǎng)訪問比如用手機(jī)測試 Hermes Agent 的接口有兩個方案。方案一是在 Windows 上做端口轉(zhuǎn)發(fā)用netsh interface portproxy命令把 Windows 的端口轉(zhuǎn)發(fā)到 WSL2 的 IP。方案二是把 WSL2 的網(wǎng)絡(luò)模式改成 mirrored在.wslconfig文件里加networkingModemirrored這樣 WSL2 直接共享 Windows 的網(wǎng)絡(luò)接口。我一般用方案一因?yàn)?mirrored 模式在某些 Windows 版本上還有兼容性問題。端口轉(zhuǎn)發(fā)的命令示例netsh interface portproxy add v4tov4 listenport8080 listenaddress0.0.0.0 connectport8080 connectaddress$(wsl hostname -I | awk {print $1})注意 WSL2 的 IP 每次重啟會變所以這個命令需要寫進(jìn)腳本每次開機(jī)后重新執(zhí)行。或者用 mirrored 模式一勞永逸。2.5 WSL2 ?；钆c systemd 啟用WSL2 默認(rèn)在最后一個終端關(guān)閉后一段時間會自動掛起這會導(dǎo)致后臺服務(wù)中斷。解決辦法是在/etc/wsl.conf里配置[boot] systemdtrue [user] default你的用戶名然后在 Windows 的.wslconfig文件位于用戶目錄下里加[wsl2] vmIdleTimeout-1vmIdleTimeout-1表示永不超時掛起。改完執(zhí)行wsl --shutdown重啟 WSL2 生效。啟用 systemd 后你就可以用systemctl管理 Hermes Agent 服務(wù)了這是后面做服務(wù)保活的基礎(chǔ)。3. 云服務(wù)器方案選型、購買與初始化配置3.1 云服務(wù)器配置怎么選才不浪費(fèi)錢Hermes Agent 本身對資源的需求不算高但如果你要同時跑 Docker、數(shù)據(jù)庫、可能還有向量檢索組件配置就不能太低。我的建議是使用場景CPU內(nèi)存磁盤帶寬個人測試2核4GB40GB SSD3Mbps小團(tuán)隊(duì)使用4核8GB80GB SSD5Mbps生產(chǎn)環(huán)境8核16GB200GB SSD10Mbps很多人問“云服務(wù)器32核128G中的128G指的是什么”這里統(tǒng)一說一下128G 指的是內(nèi)存容量不是磁盤。云服務(wù)器配置里的“核”是 vCPU是虛擬核心和物理核心有區(qū)別。對于 Hermes Agent 來說4核8G 是性價比最高的起步配置。關(guān)于“購買云服務(wù)器大概多少錢”國內(nèi)主流云廠商的 2核4G 配置新用戶首年通常在 100-300 元區(qū)間4核8G 在 500-1000 元區(qū)間。具體價格波動大建議關(guān)注各家的新用戶活動。如果預(yù)算有限也可以看看免費(fèi)云服務(wù)器試用活動但通常有時長限制。注意不要為了省錢選 1核2G 的配置。Docker 本身就要占幾百 MB 內(nèi)存Hermes Agent 跑起來后內(nèi)存占用會上去1核2G 很容易 OOM內(nèi)存溢出導(dǎo)致服務(wù)被殺。3.2 操作系統(tǒng)選擇與安全組配置操作系統(tǒng)我推薦 Ubuntu 22.04 LTS 或 Ubuntu 24.04 LTS。如果你有國產(chǎn)化需求麒麟 V10 也可以但 Docker 安裝步驟會略有不同需要額外配置軟件源。安全組是云服務(wù)器最容易出問題的地方。Hermes Agent 默認(rèn)監(jiān)聽的端口假設(shè)是 8080必須在安全組里放行否則外網(wǎng)訪問不了。配置方法登錄云服務(wù)器控制臺找到安全組/防火墻設(shè)置。添加入站規(guī)則協(xié)議 TCP端口 8080來源 0.0.0.0/0如果只自己用可以限制為你的 IP。如果需要 SSH 管理確保 22 端口已放行。提示有些云廠商默認(rèn)只放行 22 和 3389其他端口全部關(guān)閉。部署完服務(wù)發(fā)現(xiàn)訪問不了先檢查安全組這是最高頻的排查點(diǎn)。3.3 服務(wù)器初始化用戶、SSH 與基礎(chǔ)工具拿到服務(wù)器后第一件事不是直接裝 Docker而是做基礎(chǔ)初始化。我習(xí)慣做這幾件事創(chuàng)建非 root 用戶并配置 sudo 權(quán)限。直接用 root 操作風(fēng)險高誤刪文件后果嚴(yán)重。配置 SSH 密鑰登錄禁用密碼登錄。密碼登錄容易被暴力破解看云服務(wù)器 TCP 連接數(shù)異常增高往往就是被掃了。更新系統(tǒng)軟件包apt update apt upgrade -y。安裝基礎(chǔ)工具apt install -y curl wget git vim htop net-tools。這些步驟看起來瑣碎但能避免后面很多麻煩。特別是 SSH 密鑰登錄配好之后管理起來安心很多。3.4 Docker 與 Docker Compose 安裝Hermes Agent 的部署方式以 Docker 為主所以 Docker 環(huán)境是必須的。安裝步驟# 卸載舊版本 apt remove -y docker docker-engine docker.io containerd runc # 安裝依賴 apt install -y ca-certificates curl gnupg lsb-release # 添加 Docker 官方 GPG 密鑰 mkdir -p /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | gpg --dearmor -o /etc/apt/keyrings/docker.gpg # 添加軟件源 echo deb [arch$(dpkg --print-architecture) signed-by/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable | tee /etc/apt/sources.list.d/docker.list /dev/null # 安裝 Docker apt update apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin # 驗(yàn)證 docker --version docker compose version如果拉取鏡像慢可以配置鏡像加速。在/etc/docker/daemon.json里加{ registry-mirrors: [https://your-mirror.example.com] }然后systemctl daemon-reload systemctl restart docker。鏡像加速地址各云廠商都有提供用自己服務(wù)器所在廠商的地址延遲最低。4. Hermes Agent 服務(wù)部署與啟動實(shí)操4.1 獲取部署文件與目錄規(guī)劃Hermes Agent 的部署文件通常包括 Docker Compose 配置、環(huán)境變量文件、數(shù)據(jù)卷目錄。我習(xí)慣把部署目錄放在/opt/hermes-agent結(jié)構(gòu)如下/opt/hermes-agent/ ├── docker-compose.yml ├── .env ├── data/ ├── logs/ └── config/這樣規(guī)劃的好處是數(shù)據(jù)、日志、配置分離備份和遷移都方便。.env文件存放敏感信息數(shù)據(jù)庫密碼、API Key 等不要提交到 Git。4.2 環(huán)境變量配置與參數(shù)說明.env文件是部署的核心幾個關(guān)鍵參數(shù)必須配對參數(shù)名說明示例值HERMES_PORT服務(wù)監(jiān)聽端口8080HERMES_DATA_DIR數(shù)據(jù)目錄/opt/hermes-agent/dataDB_PASSWORD數(shù)據(jù)庫密碼強(qiáng)密碼LOG_LEVEL日志級別infoTZ時區(qū)Asia/Shanghai時區(qū)這個參數(shù)容易被忽略但不配的話日志時間戳?xí)?UTC排查問題時對時間很麻煩。日志級別建議先用 info調(diào)試階段可以改 debug生產(chǎn)環(huán)境用 warn 減少日志量。4.3 啟動服務(wù)與首次運(yùn)行檢查啟動命令cd /opt/hermes-agent docker compose up -d-d表示后臺運(yùn)行。啟動后執(zhí)行docker compose ps查看容器狀態(tài)正常應(yīng)該是Up或running。如果顯示Restarting或Exited說明啟動失敗需要看日志docker compose logs -f --tail100首次啟動通常會做一些初始化工作比如建表、下載模型文件等可能需要幾分鐘。這時候不要急著判斷失敗先看日志有沒有在正常輸出。4.4 狀態(tài)校驗(yàn)接口、端口與日志三重確認(rèn)服務(wù)起來后怎么確認(rèn)它真的正常我一般做三重檢查第一端口監(jiān)聽檢查ss -tlnp | grep 8080確認(rèn)端口在監(jiān)聽。第二接口健康檢查curl -s http://localhost:8080/health看返回是否正常。Hermes Agent 通常有健康檢查接口返回{status:ok}之類的 JSON。第三日志檢查docker compose logs --tail50看有沒有 ERROR 級別的日志。三重都通過基本可以確認(rèn)服務(wù)正常。如果接口不通但端口在監(jiān)聽可能是服務(wù)內(nèi)部還在初始化等一會兒再試。4.5 配置 systemd 實(shí)現(xiàn)開機(jī)自啟與?；頓ocker Compose 啟動的容器默認(rèn)不會開機(jī)自啟服務(wù)器重啟后服務(wù)就沒了。解決辦法是寫一個 systemd 服務(wù)單元[Unit] DescriptionHermes Agent Requiresdocker.service Afterdocker.service [Service] Typeoneshot RemainAfterExityes WorkingDirectory/opt/hermes-agent ExecStart/usr/bin/docker compose up -d ExecStop/usr/bin/docker compose down TimeoutStartSec300 [Install] WantedBymulti-user.target保存到/etc/systemd/system/hermes-agent.service然后systemctl daemon-reload systemctl enable hermes-agent systemctl start hermes-agent這樣服務(wù)器重啟后 Hermes Agent 會自動拉起。TimeoutStartSec300是給初始化留足時間避免啟動超時被 systemd 判定為失敗。5. 環(huán)境調(diào)試與常見問題排查實(shí)錄5.1 服務(wù)起不來按這個順序排查服務(wù)啟動失敗是最常見的問題我總結(jié)了一個排查順序看容器狀態(tài)docker compose ps確認(rèn)是 Exited 還是 Restarting?？慈罩綿ocker compose logs --tail200找 ERROR 或 Exception?？炊丝谡加胹s -tlnp | grep 端口號確認(rèn)端口沒被其他程序占用?？创疟P空間df -h磁盤滿了會導(dǎo)致服務(wù)無法寫入數(shù)據(jù)。看內(nèi)存free -h內(nèi)存不足會觸發(fā) OOM Killer。這個順序覆蓋了 90% 的啟動失敗場景。我遇到過最隱蔽的一次是磁盤 inode 滿了df -h看空間還有但df -i顯示 inode 用盡清理日志文件后恢復(fù)。5.2 WSL2 環(huán)境下的典型問題WSL2 環(huán)境下有幾個高頻問題問題一端口在 WSL2 內(nèi)能訪問Windows 主機(jī)訪問不了。原因是 WSL2 的 NAT 網(wǎng)絡(luò)模式。解決辦法是配置端口轉(zhuǎn)發(fā)或者改用 mirrored 模式。問題二WSL2 重啟后 IP 變了之前的轉(zhuǎn)發(fā)規(guī)則失效。寫一個開機(jī)腳本每次啟動時重新獲取 IP 并更新轉(zhuǎn)發(fā)規(guī)則。問題三Docker 在 WSL2 里啟動報錯“could not safely verify the wsl2 environment”。這通常是 WSL2 版本過低或 systemd 沒啟用。執(zhí)行wsl --update更新到最新版并確認(rèn)/etc/wsl.conf里systemdtrue。問題四WSL2 里跑 CUDA 相關(guān)組件失敗。WSL2 支持 CUDA但需要安裝 Windows 端的 NVIDIA 驅(qū)動不是 Linux 驅(qū)動然后在 WSL2 內(nèi)安裝 CUDA Toolkit。驅(qū)動版本要匹配否則會報錯。5.3 云服務(wù)器網(wǎng)絡(luò)與安全組問題云服務(wù)器上最常見的問題是“服務(wù)起來了但外網(wǎng)訪問不了”。排查步驟服務(wù)器內(nèi)curl localhost:8080是否通通說明服務(wù)正常。安全組是否放行 8080 端口這是最高頻的原因。服務(wù)器防火墻ufw/iptables是否放行ufw status查看。服務(wù)是否監(jiān)聽在 0.0.0.0 而不是 127.0.0.1監(jiān)聽 127.0.0.1 的話外網(wǎng)訪問不了。這四個檢查點(diǎn)按順序過一遍基本能定位問題。5.4 常見問題速查表現(xiàn)象可能原因解決方法容器反復(fù)重啟配置錯誤/依賴缺失看日志定位具體報錯端口不通安全組/防火墻未放行檢查安全組和 ufw接口返回 502后端服務(wù)未就緒等待初始化完成或看后端日志磁盤滿日志/數(shù)據(jù)未清理配置日志輪轉(zhuǎn)清理舊數(shù)據(jù)內(nèi)存不足配置過低升級配置或限制容器內(nèi)存拉鏡像超時網(wǎng)絡(luò)問題配置鏡像加速時間戳不對時區(qū)未配置設(shè)置 TZ 環(huán)境變量開機(jī)不自啟未配 systemd配置 systemd 服務(wù)單元5.5 幾個我踩過的坑和獨(dú)家技巧坑一Docker Compose 版本不匹配。老版本的docker-compose帶橫杠和新版的docker compose帶空格命令不通用。Ubuntu 22.04 默認(rèn)源里的版本較老建議用 Docker 官方源安裝docker-compose-plugin?？佣?shù)據(jù)卷權(quán)限問題。Docker 容器內(nèi)以非 root 用戶運(yùn)行時掛載的宿主機(jī)目錄權(quán)限不對會導(dǎo)致寫入失敗。解決辦法是chown -R 1000:1000 /opt/hermes-agent/data具體 UID 看容器內(nèi)用戶?？尤罩疚募o限增長。Docker 默認(rèn)的 json-file 日志驅(qū)動不限制大小跑久了日志能占滿磁盤。在daemon.json里配置{ log-driver: json-file, log-opts: { max-size: 100m, max-file: 3 } }這樣每個容器最多保留 300MB 日志自動輪轉(zhuǎn)。技巧一用docker compose config校驗(yàn)配置文件。改完 compose 文件后先執(zhí)行這個命令能提前發(fā)現(xiàn)語法錯誤避免啟動時才發(fā)現(xiàn)。技巧二環(huán)境變量用docker compose config查看最終值。有時候.env文件沒被正確加載用這個命令能看到實(shí)際生效的值排查配置問題很快。技巧三WSL2 里開發(fā)Windows 上用 IDE 編輯代碼。把代碼放在/mnt/c/下用 Windows 的 IDE 編輯WSL2 里運(yùn)行。但注意/mnt/c/的文件 IO 性能比 WSL2 原生文件系統(tǒng)差很多如果項(xiàng)目大建議代碼放 WSL2 內(nèi)用 VS Code 的 Remote-WSL 插件編輯。6. 環(huán)境調(diào)試完成后的驗(yàn)證與日常維護(hù)6.1 完整驗(yàn)證清單部署完成后我建議按這個清單做一次完整驗(yàn)證服務(wù)進(jìn)程在運(yùn)行docker compose ps全部 Up端口在監(jiān)聽ss -tlnp能看到對應(yīng)端口健康接口正常curl localhost:端口/health返回正常外網(wǎng)可訪問從另一臺機(jī)器curl 服務(wù)器IP:端口/health日志無 ERRORdocker compose logs | grep -i error開機(jī)自啟生效systemctl is-enabled hermes-agent返回 enabled數(shù)據(jù)持久化正常重啟容器后數(shù)據(jù)還在這個清單過一遍基本可以確認(rèn)部署質(zhì)量。6.2 日常維護(hù)要點(diǎn)服務(wù)跑起來只是開始日常維護(hù)才是長期穩(wěn)定的關(guān)鍵。我一般做這幾件事定期看日志不用天天看但每周掃一眼有沒有異常。配置監(jiān)控告警CPU、內(nèi)存、磁盤超過閾值時通知。定期備份數(shù)據(jù)目錄特別是數(shù)據(jù)庫文件。關(guān)注鏡像更新有新版本時先在測試環(huán)境驗(yàn)證再升級。提示升級前一定要備份。我見過有人直接docker compose pull docker compose up -d結(jié)果新版本數(shù)據(jù)庫 schema 變了舊數(shù)據(jù)不兼容回滾都回不去。6.3 性能調(diào)優(yōu)的幾個方向如果服務(wù)跑起來后覺得慢可以從這幾個方向調(diào)優(yōu)數(shù)據(jù)庫連接池大小根據(jù)并發(fā)量調(diào)整。日志級別調(diào)高減少日志寫入開銷。容器資源限制給關(guān)鍵容器分配足夠的 CPU 和內(nèi)存。如果用了向量檢索索引參數(shù)和檢索參數(shù)對性能影響很大需要根據(jù)數(shù)據(jù)量調(diào)。這些調(diào)優(yōu)沒有萬能參數(shù)需要根據(jù)實(shí)際負(fù)載測試。建議先用默認(rèn)配置跑遇到瓶頸再針對性調(diào)整不要一上來就瞎調(diào)。6.4 從本地到云端的遷移思路本地 WSL2 調(diào)試好了想遷到云服務(wù)器步驟其實(shí)不復(fù)雜在云服務(wù)器上裝好 Docker 環(huán)境。把/opt/hermes-agent整個目錄打包傳過去或者用 Git 同步配置文件。數(shù)據(jù)目錄單獨(dú)遷移用rsync或scp。修改.env里的配置主要是 IP、端口、路徑。啟動服務(wù)按驗(yàn)證清單檢查。注意本地和云端的路徑可能不一樣.env里的路徑要改。還有時區(qū)、域名這些也要根據(jù)環(huán)境調(diào)整。我個人在實(shí)際操作中的體會是Hermes Agent 的部署難點(diǎn)不在某一步特別復(fù)雜而在于環(huán)節(jié)多、每個環(huán)節(jié)都有小坑。WSL2 的網(wǎng)絡(luò)模式、云服務(wù)器的安全組、Docker 的日志輪轉(zhuǎn)、systemd 的服務(wù)配置這些單獨(dú)看都不難但組合起來就容易顧此失彼。我的建議是第一次部署時嚴(yán)格按步驟來每步都驗(yàn)證通過再往下走不要跳步。部署完成后把整個流程寫成腳本或文檔下次遷移或重裝時能省很多時間。另外環(huán)境變量和敏感配置一定要和代碼分離用.env管理這樣換環(huán)境時只改配置不改代碼遷移成本最低。