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