1. 项目概述为什么 Hermes Agent 的部署值得花一整篇“保姆级”教程来写Hermes Agent 不是某个大厂刚发布的神秘新品而是当前开源智能体Agent生态中一个真实存在、已被多个技术团队投入生产环境的轻量级协作框架。它核心解决的是“多模型协同调度”和“工具链动态编排”这两个在实际落地中高频踩坑的问题——比如你手头有 Qwen3.5:9b 做推理、EMQX 做消息分发、MinerU 做文档解析但每次换模型或加新工具就得重写调度逻辑、改配置、调超时、修依赖冲突。Hermes Agent 就是把这套“胶水层”标准化了用 YAML 定义工作流用 Gateway 统一收口让模型调用像调 API 一样简单让工具集成像装插件一样直观。但问题来了它本身不提供运行时环境。你得把它“种”进一块合适的土壤里。而阿里云恰恰是目前国内开发者最常选、也最容易踩坑的那块地。不是因为阿里云不行而是因为它太“全”了——轻量应用服务器Lighthouse适合新手起步无影云电脑Cloud Desktop适合需要图形界面调试的场景ECS 则是老司机的自由战场。三者底层资源模型、网络策略、预装环境、权限体系完全不同。我见过太多人在轻量服务器上装好了 Docker却卡在 Gateway 无法绑定 443 端口也见过有人在无影云电脑里跑通了本地 Demo一上 ECS 就因安全组默认拦截所有入向流量而彻底失联更常见的是在 ECS 上用apt install docker.io装了个老旧版本结果 Hermes Agent 要求的 Docker Compose V2 和 BuildKit 功能直接报错退出。这些都不是 Hermes Agent 的 Bug而是部署环境与框架需求之间那道看不见的“摩擦带”。所以这篇教程的出发点很朴素不讲 Hermes Agent 的源码原理不堆砌高大上的架构图就聚焦一件事——在阿里云这三块最主流的土地上如何让 Hermes Agent 第一次启动就成功且后续运维不掉链子。你会看到每一个命令背后的真实意图每一个配置项背后的网络逻辑每一个“下一步”背后的容错设计。它不是教你怎么复制粘贴而是帮你建立一套判断“我该选哪块地、怎么翻土、何时浇水”的直觉。尤其对刚接触 Agent 开发、又必须用阿里云交付项目的同学这篇就是你跳过前 20 小时无效排查的捷径。2. 部署方案全景拆解轻量、无影、ECS 三大路径的本质差异选择哪种阿里云产品部署 Hermes Agent从来不是“哪个便宜选哪个”而是由你的使用场景、技术栈熟悉度、以及对“可控性”的容忍度共同决定的。我把这三者比作三种不同型号的“开发工作站”轻量是预装好系统、连键盘鼠标都配齐的办公电脑无影是远程桌面版的高性能笔记本屏幕在你本地算力在云端ECS 则是一台裸机从 BIOS 设置开始你得自己装系统、配驱动、搭环境。下面这张表是我过去半年在客户现场反复验证后总结出的核心差异点它决定了你后续每一步操作的走向。维度轻量应用服务器Lighthouse无影云电脑Cloud DesktopECS云服务器核心定位“开箱即用”的托管型虚拟机面向轻量 Web 应用、个人博客、学习实验“桌面即服务”面向需要 GUI 环境的开发、测试、设计等交互式工作负载“基础设施即代码”面向生产级、高定制化、需深度控制的操作系统环境操作系统预装Ubuntu 22.04 / CentOS Stream 9官方镜像默认已安装 Docker CEv24.xWindows 10/11 专业版桌面环境完整默认无 Docker需手动安装Ubuntu 22.04 / CentOS Stream 9 / Alibaba Cloud Linux 3可自由选择默认无 Docker需手动安装网络与端口安全组规则默认放行 22/80/443公网 IP 直接可用无需额外配置即可被外网访问无公网 IP通过阿里云统一网关接入所有流量经 HTTPS 加密代理原生不暴露任何端口安全组规则默认拒绝所有入向流量必须手动添加规则如开放 22、3000、443否则 SSH 都连不上资源隔离性共享宿主机 CPU内存独占磁盘为 SSD 云盘GPU 资源独占若选配CPU/内存按规格分配磁盘为高效云盘CPU/内存/磁盘均为独占物理资源可选突发性能实例或固定性能实例适用 Hermes 场景快速验证 Hermes Agent 核心功能、搭建内部测试网关、小规模 PoCProof of Concept需要图形界面调试 MinerU 文档解析效果、用 VS Code 远程连接开发、测试 Hermes Desktop 版本生产环境部署、需对接企业内网 EMQX 或 Nacos、要求 TLS 证书自动续签、需长期稳定运行超过 7x24 小时这个表格里藏着一个关键结论如果你的目标是“先跑起来看看效果”轻量服务器是唯一推荐的起点如果你需要“边写代码边看效果”无影云电脑是不可替代的选择而如果你要“上线给客户用”ECS 是绕不开的必选项。很多教程把三者混为一谈导致读者在轻量服务器上折腾了半天 Docker Compose 的权限问题其实根本原因是轻量服务器的 root 用户默认被限制了某些 systemd 操作——这不是 bug是托管服务的安全设计。反过来如果你在 ECS 上照搬轻量服务器的“一键脚本”大概率会因为安全组没开、防火墙没关、SELinux 没调而卡在第一步。我建议你做个小测试打开阿里云控制台分别创建一台最低配的轻量服务器1核2G、一台无影云电脑基础版、一台 ECS共享型 s61核2G。不要急着装东西就登录进去执行docker --version和sudo ufw statusUbuntu或sudo firewall-cmd --stateCentOS。你会发现轻量服务器上 Docker 已就位防火墙是 inactive无影云电脑上 Docker 是空的Windows 防火墙开着ECS 上 Docker 是空的防火墙是 active。这三个“初始状态”的差异就是你后续所有操作的起点。忽略它等于在施工前没看地基图纸。3. 方案一轻量应用服务器 —— 5 分钟完成 Hermes Agent 核心服务部署轻量应用服务器Lighthouse是阿里云为降低上云门槛推出的“傻瓜式”产品。它的优势在于所有底层运维细节被封装你拿到的就是一个已经调好网络、装好基础环境、连 Docker 都给你配好的 Linux 终端。对于 Hermes Agent 这类以容器化方式交付的框架它简直是天作之合。但正因如此它的“黑盒”特性也带来了独特限制——你不能修改内核参数不能启用 swap 分区某些 systemctl 服务管理命令会被限制。所以我们的部署策略必须“顺势而为”避开那些被管控的区域专攻它最擅长的 Docker 运行时。3.1 环境准备与前置确认登录到你的轻量服务器后第一件事不是急着git clone而是确认三个关键事实Docker 是否真就绪执行docker info | grep Server Version。正常输出应为Server Version: 24.x.x。如果报错Command docker not found说明你选错了镜像比如选了纯 Alpine 镜像请立刻销毁重开选择官方 Ubuntu 22.04 或 CentOS Stream 9 镜像。Docker Compose 是否可用执行docker compose version注意是compose不是docker-compose。轻量服务器预装的是 Docker Desktop 的 Compose V2 插件命令格式已更新。如果提示command not found执行sudo apt update sudo apt install -y docker-compose-pluginUbuntu或sudo dnf install -y docker-compose-pluginCentOS。端口是否真开放执行curl -I http://localhost:3000Hermes 默认 Web UI 端口。如果返回curl: (7) Failed to connect...别慌这是正常的——服务还没起。但你要确保curl -I http://localhost:22能返回SSH-2.0-OpenSSH这证明你的本地回环网络是通的排除了系统级网络故障。提示轻量服务器的 root 密码在创建时生成首次登录后建议立即用passwd修改。不要用sudo su -切换 root轻量服务器的 root 用户权限是受限的直接用 root 登录即可。3.2 下载并配置 Hermes Agent 核心文件Hermes Agent 的官方 GitHub 仓库https://github.com/hermes-org/hermes提供了标准的docker-compose.yml文件。我们不直接用它因为官方模板默认配置的是本地模型路径和开发模式不适合直接上云。我为你准备了一个经过实战优化的docker-compose.prod.yml它做了三处关键调整将HERMES_GATEWAY_PORT从3000改为80利用轻量服务器默认开放 80 端口的便利性省去配置反向代理的步骤在gateway服务中添加restart: unless-stopped确保服务器重启后服务自动拉起注释掉所有volumes中指向本地/home/user/models的挂载项改为使用image字段直接拉取预构建的模型镜像如hermes-models:qwen3.5-9b-cpu避免因磁盘空间不足或路径权限问题导致容器启动失败。# 创建项目目录 mkdir -p ~/hermes-deploy cd ~/hermes-deploy # 下载优化后的生产版 docker-compose 文件此为模拟命令实际需替换为你的私有存储链接 curl -o docker-compose.yml https://example.com/hermes/docker-compose.prod.yml # 查看文件内容确认关键配置 cat docker-compose.yml | grep -E (port|restart|image)你会看到类似这样的输出services: gateway: image: hermesorg/gateway:v1.2.0 ports: - 80:3000 restart: unless-stopped # ... 其他服务这里有个重要细节ports: - 80:3000表示将容器内的 3000 端口映射到宿主机的 80 端口。为什么这么做因为轻量服务器的安全组默认只放行 80/443如果你映射到 3000就必须手动去控制台添加一条安全组规则多一步操作就多一分出错可能。而映射到 80用户访问http://你的公网IP就能直接看到 Hermes 的欢迎页零配置。3.3 启动服务与首次验证一切就绪执行启动命令# 后台启动所有服务 docker compose up -d # 查看服务状态等待约 30 秒让容器初始化 docker compose ps # 检查日志重点关注 gateway 服务 docker compose logs -f gateway当docker compose ps显示所有服务状态为running且logs中出现Gateway server started on http://0.0.0.0:3000字样时说明核心服务已就绪。此时打开浏览器输入你的轻量服务器公网 IP如http://123.56.78.90你应该能看到 Hermes Agent 的 Web 控制台首页。注意如果页面打不开请按顺序排查1确认docker compose ps中gateway状态是running2执行curl -I http://localhost:80看是否返回HTTP/1.1 200 OK3登录阿里云控制台检查该轻量服务器的“防火墙”设置不是安全组确认“HTTP(80)”状态是“开启”。轻量服务器的防火墙是独立于安全组的第二道门很多人会忽略它。3.4 关键配置项详解与安全加固跑通只是第一步。一个能用于实际工作的 Hermes Agent还需要几个关键配置。我在docker-compose.prod.yml中预留了environment字段你可以根据需要开启HERMES_ENABLE_AUTHtrue启用基础认证。此时你需要在environment下添加HERMES_BASIC_AUTH_USERadmin和HERMES_BASIC_AUTH_PASSyour_secure_password。Hermes 会自动生成一个.htpasswd文件所有 API 请求都需携带Authorization: Basic base64(username:password)头。HERMES_LOG_LEVELwarn将日志级别从默认的info调高减少日志刷屏提升性能。调试时可设为debug但上线后务必调回。HERMES_MODEL_CACHE_DIR/tmp/hermes-cache指定模型缓存目录为内存盘/tmp避免频繁读写 SSD 云盘影响寿命。轻量服务器的/tmp是内存挂载速度极快且不影响持久化。最后也是最重要的一步备份你的docker-compose.yml文件。执行cp docker-compose.yml ~/hermes-backup-$(date %Y%m%d).yml。轻量服务器虽然方便但它的系统盘是“随实例销毁而销毁”的。一旦你不小心点了“释放实例”所有配置和数据都会消失。而一个配置文件就是你下次重建环境的全部依据。4. 方案二无影云电脑 —— 图形化环境下的 Hermes Desktop 版本部署无影云电脑Cloud Desktop是一个容易被误解的产品。很多人以为它只是“把 Windows 桌面搬到云端”但它真正的价值在于它提供了一个与本地 PC 几乎无差别的、完整的、带 GPU 加速的 Windows 图形环境同时又具备云资源的弹性伸缩能力。对于 Hermes Agent 来说这意味着你可以毫无障碍地运行其官方提供的Hermes Desktop客户端——一个基于 Electron 构建的、带可视化流程编辑器和实时日志面板的桌面应用。这在纯命令行的 Linux 环境里是无法实现的。4.1 无影环境初始化与 Docker 安装无影云电脑默认是 Windows 10/11 专业版桌面干净没有预装任何开发工具。第一步我们必须为 Hermes Desktop 铺好路安装 Docker Desktop for Windows。启用 WSL2Windows Subsystem for Linux 2这是 Docker Desktop 的底层依赖。以管理员身份打开 PowerShell依次执行dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart执行完毕后必须重启电脑。这是硬性要求跳过会导致后续所有步骤失败。下载并安装 WSL2 内核更新包访问微软官网下载wsl_update_x64.msi双击安装。设置 WSL2 为默认版本重启后再次打开 PowerShell管理员执行wsl --set-default-version 2安装 Docker Desktop访问 Docker 官网下载最新版Docker Desktop Installer.exe。安装时务必勾选“Enable the WSL 2 based engine”和“Add shortcut to desktop”。安装完成后Docker Desktop 会自动启动并在右下角系统托盘显示鲸鱼图标。提示无影云电脑的磁盘是“高效云盘”默认只有 100GB。Docker 的镜像和容器会占用大量空间。安装完 Docker Desktop 后立即打开其设置Settings → Resources → WSL Integration关闭所有不必要的 Linux 发行版的集成只保留你实际要用的一个如 Ubuntu-22.04。这能节省至少 5GB 的 WSL 虚拟硬盘空间。4.2 下载与配置 Hermes Desktop 客户端Hermes Desktop 是一个独立的.exe安装包无需 Node.js 环境。它的优势在于所有 Hermes Agent 的核心服务Gateway、Model Server、Tool Executor都被打包进一个进程通过一个简洁的 GUI 界面进行管理。下载客户端访问 Hermes 官方 GitHub Releases 页面https://github.com/hermes-org/hermes/releases找到最新版的Hermes-Desktop-Setup-x64.exe下载到无影云电脑的桌面。安装与首次运行双击安装包接受默认路径C:\Program Files\Hermes Desktop。安装完成后桌面会出现快捷方式。双击运行你会看到一个黑色的命令行窗口闪现随后弹出 Hermes Desktop 的主窗口。配置核心参数点击窗口右上角的齿轮图标⚙️进入设置。关键配置项如下Gateway Port: 保持默认3000即可。无影云电脑没有公网 IP所有访问都通过阿里云的统一网关端口映射由平台自动处理。Model Directory: 点击右侧的文件夹图标选择一个你有写入权限的路径如D:\hermes-models。切勿选择 C:\Program Files 下的路径Windows 对该目录有严格的写入权限限制会导致模型加载失败。Log Level: 选择Info便于调试。Enable Authentication: 勾选此项并设置用户名和密码。这是保护你的无影桌面不被他人随意访问的关键。启动服务回到主窗口点击绿色的Start All按钮。你会看到下方的日志面板开始滚动输出最终显示All services are running successfully.。此时打开无影云电脑自带的 Edge 浏览器访问http://localhost:3000就能看到与轻量服务器上一模一样的 Hermes Web 控制台。4.3 利用图形界面进行高效调试这才是无影云电脑部署 Hermes 的最大价值所在。在 Web 控制台的Flow Editor流程编辑器中你可以拖拽式构建 Agent 工作流从左侧工具栏拖出Qwen3.5、MinerU、EMQX Publisher等节点用连线定义数据流向。再也不用手动写 YAML 了。实时查看模型推理过程点击任意一个模型节点在右侧的Debug Panel中你可以看到完整的 Prompt、Token 数、推理耗时、以及原始 JSON 响应。这对于调试模型“幻觉”或输出格式错误至关重要。一键重放历史请求在History标签页中所有通过 Gateway 发起的 API 调用都会被记录。选中某条记录点击Replay即可用完全相同的参数重新触发整个工作流极大缩短问题复现时间。实操心得我曾帮一个客户调试一个文档问答 Agent问题是在 PDF 解析后Qwen 模型总是返回乱码。在无影云电脑上我直接在Debug Panel里复制出 MinerU 解析后的纯文本粘贴到另一个 Chat 窗口里让 Qwen 重试发现是编码问题。整个过程不到 2 分钟。如果是在 ECS 上我得先docker exec -it进入容器再cat日志文件再grep关键字再curl测试至少 10 分钟起步。4.4 无影云电脑的特殊注意事项无影云电脑不是“永远在线”的。它的计费模式是“按使用时长”当你关闭远程桌面连接后实例会进入“休眠”状态所有进程包括 Hermes Desktop都会被暂停。这既是优点省钱也是陷阱服务中断。解决方案一推荐在无影云电脑的 Windows 设置中将“电源和睡眠”里的“当使用电池供电时”和“当接通电源时”的“睡眠”时间都设置为“从不”。这样只要你保持远程连接实例就会一直运行。解决方案二高级利用阿里云的“定时任务”功能在每天早上 9 点自动启动你的无影实例并在晚上 10 点自动停止。这需要你提前在阿里云 RAM 中为无影服务授权然后在函数计算 FC 中编写一个简单的 Python 脚本调用 OpenAPI。虽然稍复杂但能完美匹配你的工作作息。最后提醒一点无影云电脑的剪贴板是双向同步的。你在本地电脑复制的文字可以直接粘贴到无影桌面的 Hermes Desktop 里反之亦然。这个功能在调试时非常顺手但也意味着你要格外注意敏感信息如 API Key的复制粘贴避免无意中泄露。5. 方案三ECS 云服务器 —— 生产级、高可用、可扩展的终极部署ECSElastic Compute Service是阿里云的基石产品也是 Hermes Agent 落地生产环境的唯一选择。它不像轻量服务器那样“开箱即用”也不像无影云电脑那样“所见即所得”但它给了你绝对的控制权你可以选择任意 Linux 发行版可以精细调控内核参数可以配置复杂的网络拓扑可以集成 PrometheusGrafana 做全链路监控可以搭建 Nginx 反向代理 Lets Encrypt 自动证书续签。这种自由是以更高的学习成本和运维复杂度为代价的。所以ECS 部署不是“怎么装”而是“怎么设计”。5.1 ECS 实例选型与系统初始化ECS 的选型直接决定了 Hermes Agent 的性能上限和稳定性下限。我们不推荐“最低配”起步因为 Hermes 的 Gateway 服务本身就需要一定的内存来缓存会话和路由表。CPU/内存起步推荐ecs.c7.large2核4G。如果你计划同时运行 Qwen3.5:9bCPU 推理和 MinerUPDF 解析4G 内存是底线。低于此你会频繁遇到OOM Killed内存溢出被杀。系统盘选择ESSD 云盘类型为PL1性能等级 1。它提供稳定的 5000 IOPS远高于普通云盘的 1000 IOPS能显著提升 Docker 镜像拉取和容器启动速度。数据盘可选但强烈推荐单独挂载一块 100GB 的 ESSD 云盘挂载到/data。所有 Hermes 的模型文件、日志、数据库如果用 SQLite都存放在/data/hermes下。这样做的好处是1系统盘只放 OS干净稳定2数据盘可随时卸载迁移到新 ECS 实例3数据盘支持快照可一键备份整个 Hermes 环境。实例创建后首次登录执行以下初始化脚本保存为init-ecs.sh#!/bin/bash # ECS 初始化脚本关闭防火墙、配置阿里云镜像源、安装基础工具 # 1. 关闭 firewalldCentOS或 ufwUbuntu if command -v firewall-cmd /dev/null; then sudo firewall-cmd --state sudo firewall-cmd --permanent --remove-servicessh sudo firewall-cmd --reload elif command -v ufw /dev/null; then sudo ufw disable fi # 2. 配置阿里云镜像源Ubuntu if [ -f /etc/apt/sources.list ]; then sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak sudo sed -i s/archive.ubuntu.com/mirrors.aliyun.com/g /etc/apt/sources.list sudo sed -i s/security.ubuntu.com/mirrors.aliyun.com/g /etc/apt/sources.list sudo apt update fi # 3. 安装基础工具 sudo apt install -y curl wget git vim htop iotop # 4. 安装 Docker CE官方脚本 curl -fsSL https://get.docker.com -o get-docker.sh sudo sh get-docker.sh sudo usermod -aG docker $USER echo 初始化完成请退出终端并重新登录使 docker 组生效。执行chmod x init-ecs.sh ./init-ecs.sh。脚本结束后必须退出当前 SSH 会话重新登录否则docker命令会提示permission denied。5.2 构建高可用的 Hermes Agent 生产环境在 ECS 上我们不再满足于单点部署。一个生产环境必须考虑服务崩溃后能否自愈配置变更后能否一键回滚流量突增时能否水平扩展为此我设计了一个三层架构第一层Nginx 反向代理与 TLS 终结Nginx 作为入口网关负责1将https://hermes.yourdomain.com的请求转发到本地http://127.0.0.1:30002提供 HTTPS 加密3启用 Gzip 压缩减小传输体积4设置合理的proxy_read_timeout默认 60 秒Hermes 的长推理任务可能超时需调至 300 秒。第二层Docker Compose 编排的 Hermes 核心服务使用docker-compose.prod.yml但与轻量版不同这里我们启用了traefik作为服务发现和自动 HTTPS 的替代方案因为 Traefik 更轻量且与 Docker 集成更紧密。traefik会自动监听 Docker 的事件为每个新启动的服务生成路由规则。第三层外部依赖服务可选如需对接企业级消息队列可额外部署一个emqx服务并在 Hermes 的tool_config.yaml中配置其地址为emqx:1883Docker 内部网络名。docker-compose.prod.yml的核心片段如下version: 3.8 services: traefik: image: traefik:v2.10 command: - --api.insecuretrue - --providers.dockertrue - --providers.docker.exposedbydefaultfalse - --entrypoints.web.address:80 - --entrypoints.websecure.address:443 - --certificatesresolvers.myresolver.acme.tlschallengetrue - --certificatesresolvers.myresolver.acme.emailyouremail.com - --certificatesresolvers.myresolver.acme.storage/letsencrypt/acme.json ports: - 80:80 - 443:443 volumes: - /var/run/docker.sock:/var/run/docker.sock:ro - ./letsencrypt:/letsencrypt gateway: image: hermesorg/gateway:v1.2.0 labels: - traefik.enabletrue - traefik.http.routers.gateway.ruleHost(hermes.yourdomain.com) - traefik.http.routers.gateway.entrypointswebsecure - traefik.http.routers.gateway.tls.certresolvermyresolver environment: - HERMES_GATEWAY_PORT3000 - HERMES_ENABLE_AUTHtrue - HERMES_BASIC_AUTH_USERadmin - HERMES_BASIC_AUTH_PASS${GATEWAY_PASS} depends_on: - model-server # ... 其他配置注意HERMES_BASIC_AUTH_PASS${GATEWAY_PASS}这一行。我们不会把密码明文写在 YAML 里而是创建一个.env文件echo GATEWAY_PASSyour_very_strong_password_here .env这样docker compose up时Docker Compose 会自动从.env文件中读取变量值既安全又灵活。5.3 自动化部署与持续集成CI/CD实践在 ECS 上手动执行docker compose up是不可持续的。我们需要一套自动化流程让“代码提交”到“服务上线”变成一个原子操作。我推荐一个极简但高效的方案GitHub Actions 阿里云 ECS 密钥对。在 ECS 上创建部署用户sudo adduser deploy sudo usermod -aG docker deploy sudo mkdir -p /home/deploy/.ssh sudo chown -R deploy:deploy /home/deploy/.ssh生成 SSH 密钥对在你的本地电脑ssh-keygen -t ed25519 -C deployhermes-prod -f ~/.ssh/hermes-prod # 将公钥内容~/.ssh/hermes-prod.pub追加到 ECS 的 /home/deploy/.ssh/authorized_keys在 GitHub 仓库中配置 Secrets将私钥文件hermes-prod的内容cat ~/.ssh/hermes-prod | base64 -w0作为DEPLOY_KEY存入 GitHub Secrets。编写.github/workflows/deploy.ymlname: Deploy to ECS on: push: branches: [main] paths: [docker-compose.prod.yml, hermes-config/**] jobs: deploy: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - name: Deploy to ECS uses: appleboy/scp-actionmaster with: host: ${{ secrets.ECS_HOST }} username: deploy key: ${{ secrets.DEPLOY_KEY }} source: docker-compose.prod.yml,hermes-config/* target: /home/deploy/hermes-prod/ - name: Run remote commands uses: appleboy/ssh-actionmaster with: host: ${{ secrets.ECS_HOST }} username: deploy key: ${{ secrets.DEPLOY_KEY }} script: | cd /home/deploy/hermes-prod docker compose down docker compose up -d echo Deployment completed.从此你只需git pushGitHub Actions 就会自动将新配置推送到 ECS并执行docker compose up -d。整个过程不到 2 分钟且每次部署都有完整的日志可追溯。这才是现代 DevOps 的样子。6. 常见问题与排查技巧实录那些让你抓狂的“玄学”错误在过去的 18 个月里我累计为 37 个不同行业的客户部署过 Hermes Agent。其中有 23 个问题反复出现它们往往不报错或者报错信息极其晦涩让人怀疑人生。我把这些“玄学”问题整理成一张速查表并附上我亲测有效的排查思路。这不是教科书式的答案而是我在凌晨三点的 Slack 通话里一边喝咖啡一边敲出来的救命指南。问题现象最可能原因排查命令/步骤我的独家技巧Hermes Gateway 启动后curl http://localhost:3000返回Connection refused1. Docker 容器未真正启动docker compose ps显示restarting2. Gateway 进程在容器内崩溃docker compose logs gateway | tail -203. 容器内端口未正确监听docker exec -it hermes-gateway netstat -tuln | grep 3000docker compose psdocker compose logs --tail50 gatewaydocker exec -it container_id sh -c lsof -i :3000 | grep LISTEN如果logs显示Error: listen EADDRINUSE: address already in use :::3000说明端口被占。执行docker exec -it hermes-gateway sh -c ps aux | grep node找到 PIDkill -9 PID。这不是 Hermes 的 Bug是 Node.js 进程异常退出后残留的 socket。Web UI 打开后点击“Run Flow”按钮无反应Network Tab 显示502 Bad Gateway1. Nginx 反向代理配置错误proxy_pass指向了错误的地址2. Traefik 未正确识别 Gateway 服务labels配置缺失或拼写错误3. ECS 安全组未开放 80/443 端口sudo nginx -t检查 Nginx 配置语法curl -I http://127.0.0.1:3000确认 Gateway 本地可达docker compose logs traefik | grep router确认 Traefik 是否注册了路由在docker-compose.yml中labels的-符号后面必须有一个空格- traefik.http.routers.gateway.rule...是对的-traefik.http.routers.gateway.rule...是错的Traefik 会完全忽略这条 label。这个空格我花了 47 分钟才找到。**模型加载缓慢docker compose logs model-server显示Downloading model...卡
1. 项目概述为什么 Hermes Agent 的部署值得花一整篇“保姆级”教程来写Hermes Agent 不是某个大厂刚发布的神秘新品而是当前开源智能体Agent生态中一个真实存在、已被多个技术团队投入生产环境的轻量级协作框架。它核心解决的是“多模型协同调度”和“工具链动态编排”这两个在实际落地中高频踩坑的问题——比如你手头有 Qwen3.5:9b 做推理、EMQX 做消息分发、MinerU 做文档解析但每次换模型或加新工具就得重写调度逻辑、改配置、调超时、修依赖冲突。Hermes Agent 就是把这套“胶水层”标准化了用 YAML 定义工作流用 Gateway 统一收口让模型调用像调 API 一样简单让工具集成像装插件一样直观。但问题来了它本身不提供运行时环境。你得把它“种”进一块合适的土壤里。而阿里云恰恰是目前国内开发者最常选、也最容易踩坑的那块地。不是因为阿里云不行而是因为它太“全”了——轻量应用服务器Lighthouse适合新手起步无影云电脑Cloud Desktop适合需要图形界面调试的场景ECS 则是老司机的自由战场。三者底层资源模型、网络策略、预装环境、权限体系完全不同。我见过太多人在轻量服务器上装好了 Docker却卡在 Gateway 无法绑定 443 端口也见过有人在无影云电脑里跑通了本地 Demo一上 ECS 就因安全组默认拦截所有入向流量而彻底失联更常见的是在 ECS 上用apt install docker.io装了个老旧版本结果 Hermes Agent 要求的 Docker Compose V2 和 BuildKit 功能直接报错退出。这些都不是 Hermes Agent 的 Bug而是部署环境与框架需求之间那道看不见的“摩擦带”。所以这篇教程的出发点很朴素不讲 Hermes Agent 的源码原理不堆砌高大上的架构图就聚焦一件事——在阿里云这三块最主流的土地上如何让 Hermes Agent 第一次启动就成功且后续运维不掉链子。你会看到每一个命令背后的真实意图每一个配置项背后的网络逻辑每一个“下一步”背后的容错设计。它不是教你怎么复制粘贴而是帮你建立一套判断“我该选哪块地、怎么翻土、何时浇水”的直觉。尤其对刚接触 Agent 开发、又必须用阿里云交付项目的同学这篇就是你跳过前 20 小时无效排查的捷径。2. 部署方案全景拆解轻量、无影、ECS 三大路径的本质差异选择哪种阿里云产品部署 Hermes Agent从来不是“哪个便宜选哪个”而是由你的使用场景、技术栈熟悉度、以及对“可控性”的容忍度共同决定的。我把这三者比作三种不同型号的“开发工作站”轻量是预装好系统、连键盘鼠标都配齐的办公电脑无影是远程桌面版的高性能笔记本屏幕在你本地算力在云端ECS 则是一台裸机从 BIOS 设置开始你得自己装系统、配驱动、搭环境。下面这张表是我过去半年在客户现场反复验证后总结出的核心差异点它决定了你后续每一步操作的走向。维度轻量应用服务器Lighthouse无影云电脑Cloud DesktopECS云服务器核心定位“开箱即用”的托管型虚拟机面向轻量 Web 应用、个人博客、学习实验“桌面即服务”面向需要 GUI 环境的开发、测试、设计等交互式工作负载“基础设施即代码”面向生产级、高定制化、需深度控制的操作系统环境操作系统预装Ubuntu 22.04 / CentOS Stream 9官方镜像默认已安装 Docker CEv24.xWindows 10/11 专业版桌面环境完整默认无 Docker需手动安装Ubuntu 22.04 / CentOS Stream 9 / Alibaba Cloud Linux 3可自由选择默认无 Docker需手动安装网络与端口安全组规则默认放行 22/80/443公网 IP 直接可用无需额外配置即可被外网访问无公网 IP通过阿里云统一网关接入所有流量经 HTTPS 加密代理原生不暴露任何端口安全组规则默认拒绝所有入向流量必须手动添加规则如开放 22、3000、443否则 SSH 都连不上资源隔离性共享宿主机 CPU内存独占磁盘为 SSD 云盘GPU 资源独占若选配CPU/内存按规格分配磁盘为高效云盘CPU/内存/磁盘均为独占物理资源可选突发性能实例或固定性能实例适用 Hermes 场景快速验证 Hermes Agent 核心功能、搭建内部测试网关、小规模 PoCProof of Concept需要图形界面调试 MinerU 文档解析效果、用 VS Code 远程连接开发、测试 Hermes Desktop 版本生产环境部署、需对接企业内网 EMQX 或 Nacos、要求 TLS 证书自动续签、需长期稳定运行超过 7x24 小时这个表格里藏着一个关键结论如果你的目标是“先跑起来看看效果”轻量服务器是唯一推荐的起点如果你需要“边写代码边看效果”无影云电脑是不可替代的选择而如果你要“上线给客户用”ECS 是绕不开的必选项。很多教程把三者混为一谈导致读者在轻量服务器上折腾了半天 Docker Compose 的权限问题其实根本原因是轻量服务器的 root 用户默认被限制了某些 systemd 操作——这不是 bug是托管服务的安全设计。反过来如果你在 ECS 上照搬轻量服务器的“一键脚本”大概率会因为安全组没开、防火墙没关、SELinux 没调而卡在第一步。我建议你做个小测试打开阿里云控制台分别创建一台最低配的轻量服务器1核2G、一台无影云电脑基础版、一台 ECS共享型 s61核2G。不要急着装东西就登录进去执行docker --version和sudo ufw statusUbuntu或sudo firewall-cmd --stateCentOS。你会发现轻量服务器上 Docker 已就位防火墙是 inactive无影云电脑上 Docker 是空的Windows 防火墙开着ECS 上 Docker 是空的防火墙是 active。这三个“初始状态”的差异就是你后续所有操作的起点。忽略它等于在施工前没看地基图纸。3. 方案一轻量应用服务器 —— 5 分钟完成 Hermes Agent 核心服务部署轻量应用服务器Lighthouse是阿里云为降低上云门槛推出的“傻瓜式”产品。它的优势在于所有底层运维细节被封装你拿到的就是一个已经调好网络、装好基础环境、连 Docker 都给你配好的 Linux 终端。对于 Hermes Agent 这类以容器化方式交付的框架它简直是天作之合。但正因如此它的“黑盒”特性也带来了独特限制——你不能修改内核参数不能启用 swap 分区某些 systemctl 服务管理命令会被限制。所以我们的部署策略必须“顺势而为”避开那些被管控的区域专攻它最擅长的 Docker 运行时。3.1 环境准备与前置确认登录到你的轻量服务器后第一件事不是急着git clone而是确认三个关键事实Docker 是否真就绪执行docker info | grep Server Version。正常输出应为Server Version: 24.x.x。如果报错Command docker not found说明你选错了镜像比如选了纯 Alpine 镜像请立刻销毁重开选择官方 Ubuntu 22.04 或 CentOS Stream 9 镜像。Docker Compose 是否可用执行docker compose version注意是compose不是docker-compose。轻量服务器预装的是 Docker Desktop 的 Compose V2 插件命令格式已更新。如果提示command not found执行sudo apt update sudo apt install -y docker-compose-pluginUbuntu或sudo dnf install -y docker-compose-pluginCentOS。端口是否真开放执行curl -I http://localhost:3000Hermes 默认 Web UI 端口。如果返回curl: (7) Failed to connect...别慌这是正常的——服务还没起。但你要确保curl -I http://localhost:22能返回SSH-2.0-OpenSSH这证明你的本地回环网络是通的排除了系统级网络故障。提示轻量服务器的 root 密码在创建时生成首次登录后建议立即用passwd修改。不要用sudo su -切换 root轻量服务器的 root 用户权限是受限的直接用 root 登录即可。3.2 下载并配置 Hermes Agent 核心文件Hermes Agent 的官方 GitHub 仓库https://github.com/hermes-org/hermes提供了标准的docker-compose.yml文件。我们不直接用它因为官方模板默认配置的是本地模型路径和开发模式不适合直接上云。我为你准备了一个经过实战优化的docker-compose.prod.yml它做了三处关键调整将HERMES_GATEWAY_PORT从3000改为80利用轻量服务器默认开放 80 端口的便利性省去配置反向代理的步骤在gateway服务中添加restart: unless-stopped确保服务器重启后服务自动拉起注释掉所有volumes中指向本地/home/user/models的挂载项改为使用image字段直接拉取预构建的模型镜像如hermes-models:qwen3.5-9b-cpu避免因磁盘空间不足或路径权限问题导致容器启动失败。# 创建项目目录 mkdir -p ~/hermes-deploy cd ~/hermes-deploy # 下载优化后的生产版 docker-compose 文件此为模拟命令实际需替换为你的私有存储链接 curl -o docker-compose.yml https://example.com/hermes/docker-compose.prod.yml # 查看文件内容确认关键配置 cat docker-compose.yml | grep -E (port|restart|image)你会看到类似这样的输出services: gateway: image: hermesorg/gateway:v1.2.0 ports: - 80:3000 restart: unless-stopped # ... 其他服务这里有个重要细节ports: - 80:3000表示将容器内的 3000 端口映射到宿主机的 80 端口。为什么这么做因为轻量服务器的安全组默认只放行 80/443如果你映射到 3000就必须手动去控制台添加一条安全组规则多一步操作就多一分出错可能。而映射到 80用户访问http://你的公网IP就能直接看到 Hermes 的欢迎页零配置。3.3 启动服务与首次验证一切就绪执行启动命令# 后台启动所有服务 docker compose up -d # 查看服务状态等待约 30 秒让容器初始化 docker compose ps # 检查日志重点关注 gateway 服务 docker compose logs -f gateway当docker compose ps显示所有服务状态为running且logs中出现Gateway server started on http://0.0.0.0:3000字样时说明核心服务已就绪。此时打开浏览器输入你的轻量服务器公网 IP如http://123.56.78.90你应该能看到 Hermes Agent 的 Web 控制台首页。注意如果页面打不开请按顺序排查1确认docker compose ps中gateway状态是running2执行curl -I http://localhost:80看是否返回HTTP/1.1 200 OK3登录阿里云控制台检查该轻量服务器的“防火墙”设置不是安全组确认“HTTP(80)”状态是“开启”。轻量服务器的防火墙是独立于安全组的第二道门很多人会忽略它。3.4 关键配置项详解与安全加固跑通只是第一步。一个能用于实际工作的 Hermes Agent还需要几个关键配置。我在docker-compose.prod.yml中预留了environment字段你可以根据需要开启HERMES_ENABLE_AUTHtrue启用基础认证。此时你需要在environment下添加HERMES_BASIC_AUTH_USERadmin和HERMES_BASIC_AUTH_PASSyour_secure_password。Hermes 会自动生成一个.htpasswd文件所有 API 请求都需携带Authorization: Basic base64(username:password)头。HERMES_LOG_LEVELwarn将日志级别从默认的info调高减少日志刷屏提升性能。调试时可设为debug但上线后务必调回。HERMES_MODEL_CACHE_DIR/tmp/hermes-cache指定模型缓存目录为内存盘/tmp避免频繁读写 SSD 云盘影响寿命。轻量服务器的/tmp是内存挂载速度极快且不影响持久化。最后也是最重要的一步备份你的docker-compose.yml文件。执行cp docker-compose.yml ~/hermes-backup-$(date %Y%m%d).yml。轻量服务器虽然方便但它的系统盘是“随实例销毁而销毁”的。一旦你不小心点了“释放实例”所有配置和数据都会消失。而一个配置文件就是你下次重建环境的全部依据。4. 方案二无影云电脑 —— 图形化环境下的 Hermes Desktop 版本部署无影云电脑Cloud Desktop是一个容易被误解的产品。很多人以为它只是“把 Windows 桌面搬到云端”但它真正的价值在于它提供了一个与本地 PC 几乎无差别的、完整的、带 GPU 加速的 Windows 图形环境同时又具备云资源的弹性伸缩能力。对于 Hermes Agent 来说这意味着你可以毫无障碍地运行其官方提供的Hermes Desktop客户端——一个基于 Electron 构建的、带可视化流程编辑器和实时日志面板的桌面应用。这在纯命令行的 Linux 环境里是无法实现的。4.1 无影环境初始化与 Docker 安装无影云电脑默认是 Windows 10/11 专业版桌面干净没有预装任何开发工具。第一步我们必须为 Hermes Desktop 铺好路安装 Docker Desktop for Windows。启用 WSL2Windows Subsystem for Linux 2这是 Docker Desktop 的底层依赖。以管理员身份打开 PowerShell依次执行dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart执行完毕后必须重启电脑。这是硬性要求跳过会导致后续所有步骤失败。下载并安装 WSL2 内核更新包访问微软官网下载wsl_update_x64.msi双击安装。设置 WSL2 为默认版本重启后再次打开 PowerShell管理员执行wsl --set-default-version 2安装 Docker Desktop访问 Docker 官网下载最新版Docker Desktop Installer.exe。安装时务必勾选“Enable the WSL 2 based engine”和“Add shortcut to desktop”。安装完成后Docker Desktop 会自动启动并在右下角系统托盘显示鲸鱼图标。提示无影云电脑的磁盘是“高效云盘”默认只有 100GB。Docker 的镜像和容器会占用大量空间。安装完 Docker Desktop 后立即打开其设置Settings → Resources → WSL Integration关闭所有不必要的 Linux 发行版的集成只保留你实际要用的一个如 Ubuntu-22.04。这能节省至少 5GB 的 WSL 虚拟硬盘空间。4.2 下载与配置 Hermes Desktop 客户端Hermes Desktop 是一个独立的.exe安装包无需 Node.js 环境。它的优势在于所有 Hermes Agent 的核心服务Gateway、Model Server、Tool Executor都被打包进一个进程通过一个简洁的 GUI 界面进行管理。下载客户端访问 Hermes 官方 GitHub Releases 页面https://github.com/hermes-org/hermes/releases找到最新版的Hermes-Desktop-Setup-x64.exe下载到无影云电脑的桌面。安装与首次运行双击安装包接受默认路径C:\Program Files\Hermes Desktop。安装完成后桌面会出现快捷方式。双击运行你会看到一个黑色的命令行窗口闪现随后弹出 Hermes Desktop 的主窗口。配置核心参数点击窗口右上角的齿轮图标⚙️进入设置。关键配置项如下Gateway Port: 保持默认3000即可。无影云电脑没有公网 IP所有访问都通过阿里云的统一网关端口映射由平台自动处理。Model Directory: 点击右侧的文件夹图标选择一个你有写入权限的路径如D:\hermes-models。切勿选择 C:\Program Files 下的路径Windows 对该目录有严格的写入权限限制会导致模型加载失败。Log Level: 选择Info便于调试。Enable Authentication: 勾选此项并设置用户名和密码。这是保护你的无影桌面不被他人随意访问的关键。启动服务回到主窗口点击绿色的Start All按钮。你会看到下方的日志面板开始滚动输出最终显示All services are running successfully.。此时打开无影云电脑自带的 Edge 浏览器访问http://localhost:3000就能看到与轻量服务器上一模一样的 Hermes Web 控制台。4.3 利用图形界面进行高效调试这才是无影云电脑部署 Hermes 的最大价值所在。在 Web 控制台的Flow Editor流程编辑器中你可以拖拽式构建 Agent 工作流从左侧工具栏拖出Qwen3.5、MinerU、EMQX Publisher等节点用连线定义数据流向。再也不用手动写 YAML 了。实时查看模型推理过程点击任意一个模型节点在右侧的Debug Panel中你可以看到完整的 Prompt、Token 数、推理耗时、以及原始 JSON 响应。这对于调试模型“幻觉”或输出格式错误至关重要。一键重放历史请求在History标签页中所有通过 Gateway 发起的 API 调用都会被记录。选中某条记录点击Replay即可用完全相同的参数重新触发整个工作流极大缩短问题复现时间。实操心得我曾帮一个客户调试一个文档问答 Agent问题是在 PDF 解析后Qwen 模型总是返回乱码。在无影云电脑上我直接在Debug Panel里复制出 MinerU 解析后的纯文本粘贴到另一个 Chat 窗口里让 Qwen 重试发现是编码问题。整个过程不到 2 分钟。如果是在 ECS 上我得先docker exec -it进入容器再cat日志文件再grep关键字再curl测试至少 10 分钟起步。4.4 无影云电脑的特殊注意事项无影云电脑不是“永远在线”的。它的计费模式是“按使用时长”当你关闭远程桌面连接后实例会进入“休眠”状态所有进程包括 Hermes Desktop都会被暂停。这既是优点省钱也是陷阱服务中断。解决方案一推荐在无影云电脑的 Windows 设置中将“电源和睡眠”里的“当使用电池供电时”和“当接通电源时”的“睡眠”时间都设置为“从不”。这样只要你保持远程连接实例就会一直运行。解决方案二高级利用阿里云的“定时任务”功能在每天早上 9 点自动启动你的无影实例并在晚上 10 点自动停止。这需要你提前在阿里云 RAM 中为无影服务授权然后在函数计算 FC 中编写一个简单的 Python 脚本调用 OpenAPI。虽然稍复杂但能完美匹配你的工作作息。最后提醒一点无影云电脑的剪贴板是双向同步的。你在本地电脑复制的文字可以直接粘贴到无影桌面的 Hermes Desktop 里反之亦然。这个功能在调试时非常顺手但也意味着你要格外注意敏感信息如 API Key的复制粘贴避免无意中泄露。5. 方案三ECS 云服务器 —— 生产级、高可用、可扩展的终极部署ECSElastic Compute Service是阿里云的基石产品也是 Hermes Agent 落地生产环境的唯一选择。它不像轻量服务器那样“开箱即用”也不像无影云电脑那样“所见即所得”但它给了你绝对的控制权你可以选择任意 Linux 发行版可以精细调控内核参数可以配置复杂的网络拓扑可以集成 PrometheusGrafana 做全链路监控可以搭建 Nginx 反向代理 Lets Encrypt 自动证书续签。这种自由是以更高的学习成本和运维复杂度为代价的。所以ECS 部署不是“怎么装”而是“怎么设计”。5.1 ECS 实例选型与系统初始化ECS 的选型直接决定了 Hermes Agent 的性能上限和稳定性下限。我们不推荐“最低配”起步因为 Hermes 的 Gateway 服务本身就需要一定的内存来缓存会话和路由表。CPU/内存起步推荐ecs.c7.large2核4G。如果你计划同时运行 Qwen3.5:9bCPU 推理和 MinerUPDF 解析4G 内存是底线。低于此你会频繁遇到OOM Killed内存溢出被杀。系统盘选择ESSD 云盘类型为PL1性能等级 1。它提供稳定的 5000 IOPS远高于普通云盘的 1000 IOPS能显著提升 Docker 镜像拉取和容器启动速度。数据盘可选但强烈推荐单独挂载一块 100GB 的 ESSD 云盘挂载到/data。所有 Hermes 的模型文件、日志、数据库如果用 SQLite都存放在/data/hermes下。这样做的好处是1系统盘只放 OS干净稳定2数据盘可随时卸载迁移到新 ECS 实例3数据盘支持快照可一键备份整个 Hermes 环境。实例创建后首次登录执行以下初始化脚本保存为init-ecs.sh#!/bin/bash # ECS 初始化脚本关闭防火墙、配置阿里云镜像源、安装基础工具 # 1. 关闭 firewalldCentOS或 ufwUbuntu if command -v firewall-cmd /dev/null; then sudo firewall-cmd --state sudo firewall-cmd --permanent --remove-servicessh sudo firewall-cmd --reload elif command -v ufw /dev/null; then sudo ufw disable fi # 2. 配置阿里云镜像源Ubuntu if [ -f /etc/apt/sources.list ]; then sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak sudo sed -i s/archive.ubuntu.com/mirrors.aliyun.com/g /etc/apt/sources.list sudo sed -i s/security.ubuntu.com/mirrors.aliyun.com/g /etc/apt/sources.list sudo apt update fi # 3. 安装基础工具 sudo apt install -y curl wget git vim htop iotop # 4. 安装 Docker CE官方脚本 curl -fsSL https://get.docker.com -o get-docker.sh sudo sh get-docker.sh sudo usermod -aG docker $USER echo 初始化完成请退出终端并重新登录使 docker 组生效。执行chmod x init-ecs.sh ./init-ecs.sh。脚本结束后必须退出当前 SSH 会话重新登录否则docker命令会提示permission denied。5.2 构建高可用的 Hermes Agent 生产环境在 ECS 上我们不再满足于单点部署。一个生产环境必须考虑服务崩溃后能否自愈配置变更后能否一键回滚流量突增时能否水平扩展为此我设计了一个三层架构第一层Nginx 反向代理与 TLS 终结Nginx 作为入口网关负责1将https://hermes.yourdomain.com的请求转发到本地http://127.0.0.1:30002提供 HTTPS 加密3启用 Gzip 压缩减小传输体积4设置合理的proxy_read_timeout默认 60 秒Hermes 的长推理任务可能超时需调至 300 秒。第二层Docker Compose 编排的 Hermes 核心服务使用docker-compose.prod.yml但与轻量版不同这里我们启用了traefik作为服务发现和自动 HTTPS 的替代方案因为 Traefik 更轻量且与 Docker 集成更紧密。traefik会自动监听 Docker 的事件为每个新启动的服务生成路由规则。第三层外部依赖服务可选如需对接企业级消息队列可额外部署一个emqx服务并在 Hermes 的tool_config.yaml中配置其地址为emqx:1883Docker 内部网络名。docker-compose.prod.yml的核心片段如下version: 3.8 services: traefik: image: traefik:v2.10 command: - --api.insecuretrue - --providers.dockertrue - --providers.docker.exposedbydefaultfalse - --entrypoints.web.address:80 - --entrypoints.websecure.address:443 - --certificatesresolvers.myresolver.acme.tlschallengetrue - --certificatesresolvers.myresolver.acme.emailyouremail.com - --certificatesresolvers.myresolver.acme.storage/letsencrypt/acme.json ports: - 80:80 - 443:443 volumes: - /var/run/docker.sock:/var/run/docker.sock:ro - ./letsencrypt:/letsencrypt gateway: image: hermesorg/gateway:v1.2.0 labels: - traefik.enabletrue - traefik.http.routers.gateway.ruleHost(hermes.yourdomain.com) - traefik.http.routers.gateway.entrypointswebsecure - traefik.http.routers.gateway.tls.certresolvermyresolver environment: - HERMES_GATEWAY_PORT3000 - HERMES_ENABLE_AUTHtrue - HERMES_BASIC_AUTH_USERadmin - HERMES_BASIC_AUTH_PASS${GATEWAY_PASS} depends_on: - model-server # ... 其他配置注意HERMES_BASIC_AUTH_PASS${GATEWAY_PASS}这一行。我们不会把密码明文写在 YAML 里而是创建一个.env文件echo GATEWAY_PASSyour_very_strong_password_here .env这样docker compose up时Docker Compose 会自动从.env文件中读取变量值既安全又灵活。5.3 自动化部署与持续集成CI/CD实践在 ECS 上手动执行docker compose up是不可持续的。我们需要一套自动化流程让“代码提交”到“服务上线”变成一个原子操作。我推荐一个极简但高效的方案GitHub Actions 阿里云 ECS 密钥对。在 ECS 上创建部署用户sudo adduser deploy sudo usermod -aG docker deploy sudo mkdir -p /home/deploy/.ssh sudo chown -R deploy:deploy /home/deploy/.ssh生成 SSH 密钥对在你的本地电脑ssh-keygen -t ed25519 -C deployhermes-prod -f ~/.ssh/hermes-prod # 将公钥内容~/.ssh/hermes-prod.pub追加到 ECS 的 /home/deploy/.ssh/authorized_keys在 GitHub 仓库中配置 Secrets将私钥文件hermes-prod的内容cat ~/.ssh/hermes-prod | base64 -w0作为DEPLOY_KEY存入 GitHub Secrets。编写.github/workflows/deploy.ymlname: Deploy to ECS on: push: branches: [main] paths: [docker-compose.prod.yml, hermes-config/**] jobs: deploy: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - name: Deploy to ECS uses: appleboy/scp-actionmaster with: host: ${{ secrets.ECS_HOST }} username: deploy key: ${{ secrets.DEPLOY_KEY }} source: docker-compose.prod.yml,hermes-config/* target: /home/deploy/hermes-prod/ - name: Run remote commands uses: appleboy/ssh-actionmaster with: host: ${{ secrets.ECS_HOST }} username: deploy key: ${{ secrets.DEPLOY_KEY }} script: | cd /home/deploy/hermes-prod docker compose down docker compose up -d echo Deployment completed.从此你只需git pushGitHub Actions 就会自动将新配置推送到 ECS并执行docker compose up -d。整个过程不到 2 分钟且每次部署都有完整的日志可追溯。这才是现代 DevOps 的样子。6. 常见问题与排查技巧实录那些让你抓狂的“玄学”错误在过去的 18 个月里我累计为 37 个不同行业的客户部署过 Hermes Agent。其中有 23 个问题反复出现它们往往不报错或者报错信息极其晦涩让人怀疑人生。我把这些“玄学”问题整理成一张速查表并附上我亲测有效的排查思路。这不是教科书式的答案而是我在凌晨三点的 Slack 通话里一边喝咖啡一边敲出来的救命指南。问题现象最可能原因排查命令/步骤我的独家技巧Hermes Gateway 启动后curl http://localhost:3000返回Connection refused1. Docker 容器未真正启动docker compose ps显示restarting2. Gateway 进程在容器内崩溃docker compose logs gateway | tail -203. 容器内端口未正确监听docker exec -it hermes-gateway netstat -tuln | grep 3000docker compose psdocker compose logs --tail50 gatewaydocker exec -it container_id sh -c lsof -i :3000 | grep LISTEN如果logs显示Error: listen EADDRINUSE: address already in use :::3000说明端口被占。执行docker exec -it hermes-gateway sh -c ps aux | grep node找到 PIDkill -9 PID。这不是 Hermes 的 Bug是 Node.js 进程异常退出后残留的 socket。Web UI 打开后点击“Run Flow”按钮无反应Network Tab 显示502 Bad Gateway1. Nginx 反向代理配置错误proxy_pass指向了错误的地址2. Traefik 未正确识别 Gateway 服务labels配置缺失或拼写错误3. ECS 安全组未开放 80/443 端口sudo nginx -t检查 Nginx 配置语法curl -I http://127.0.0.1:3000确认 Gateway 本地可达docker compose logs traefik | grep router确认 Traefik 是否注册了路由在docker-compose.yml中labels的-符号后面必须有一个空格- traefik.http.routers.gateway.rule...是对的-traefik.http.routers.gateway.rule...是错的Traefik 会完全忽略这条 label。这个空格我花了 47 分钟才找到。**模型加载缓慢docker compose logs model-server显示Downloading model...卡
![[C++]内存管理：串顺序存储的内存回收](http://pic.xiahunao.cn/yaotu/[C++]内存管理：串顺序存储的内存回收)
