Hermes Agent双环境部署实战：WSL2本地沙盒与云服务器避坑指南

1. 这不是教程，是我在三台不同配置的机器上反复重装、调试、踩坑后整理出的 Hermes Agent 本地+云端双环境部署实录

Hermes Agent 这个词最近在智能体开发圈子里出现频率越来越高，尤其在需要多工具协同调用、长链路任务编排、带状态记忆的自动化工作流场景里，它不像 LangChain 那样需要你手写大量 glue code，也不像 LlamaIndex 那样偏重检索增强，而是更接近一个“可插拔的智能体操作系统内核”——核心价值在于把工具注册、意图识别、执行调度、状态持久化这些底层能力都封装好了，开发者真正聚焦在业务逻辑本身。但问题就出在这儿：官方文档对环境依赖写得极其简略，一行pip install hermes-agent后，90% 的人卡在第一步——服务根本起不来。我见过太多人在 WSL2 里反复systemctl start docker却提示Unit docker.service not found，也见过有人在云服务器上跑通了hermes serve，结果 WebUI 打不开，curl 返回Connection refused，查日志发现是 PostgreSQL 没连上，再查又发现pg_ctl start报错could not access the server configuration file "/var/lib/postgresql/data/postgresql.conf"……这些都不是代码 bug，全是环境链路上的“断点”。这篇写的不是标准流程，而是我把 WSL2（Ubuntu 22.04）作为本地开发沙盒、阿里云 ECS（2C4G）作为轻量测试节点、腾讯云 CVM（4C8G）作为生产预演环境，三套环境全部从零部署 Hermes Agent 全流程的真实记录。重点拆解三个关键断点：WSL2 下 Docker 与 systemd 的兼容性陷阱、云服务器上 PostgreSQL 初始化失败的根因、以及hermes serve启动后服务状态看似正常但实际不可用的隐蔽校验方法。所有命令、配置、日志片段、错误截图（文字还原版）均来自真实操作现场，不加任何“理论上应该”的推测。如果你正被docker: command not found、psql: could not connect to server或hermes serve --host 0.0.0.0:8000启动后浏览器打不开的问题困扰，这篇就是为你写的。

2. 为什么必须用 WSL2 + 云服务器双环境？单机 Docker Compose 不行吗？

2.1 单机 Docker Compose 的三大硬伤，直接决定项目后期是否崩盘

很多人看到 Hermes Agent 官方 GitHub 的docker-compose.yml示例，第一反应就是本地 Windows/Mac 直接docker-compose up -d。我试过，而且不止一次。第一次是在 Win11 + Docker Desktop 4.32 环境下，docker-compose up后hermes-webui容器日志疯狂刷Waiting for backend...，hermes-api容器日志显示Database connection failed: timeout expired，但postgres容器状态是healthy。查了整整两天，最后发现是 Docker Desktop 的网络桥接模式在 Windows 上对localhost解析有缓存，hermes-api容器内部/etc/hosts里postgres的 IP 地址指向的是 Docker 内部网关，而这个网关在某些 Windows 更新后会间歇性丢包。这不是 Hermes 的问题，是 Docker Desktop 在 Windows 上的固有缺陷。第二次是在 Mac M1 上，docker-compose up能跑通，WebUI 也能打开，但一上传超过 5MB 的 PDF 文件，hermes-api就 OOM 被 kill，docker stats显示内存使用率瞬间冲到 98%，根本原因是 Mac 的 Docker Desktop 默认只分配 2GB 内存给 LinuxKit VM，而 Hermes Agent 的 RAG 模块加载 embedding model 时至少需要 3.2GB 可用内存。这还没算上 PostgreSQL 的 shared_buffers 和 work_mem 预留空间。第三次是在 Ubuntu 22.04 物理机上，docker-compose up成功，但hermes serve命令行启动后，curl http://localhost:8000/health返回{"status":"ok"}，可curl http://localhost:8000/api/v1/tools却返回500 Internal Server Error，日志里只有SQLAlchemyError: (psycopg2.OperationalError) server closed the connection unexpectedly。最终定位到是物理机 SELinux 策略阻止了 Python 进程对/var/lib/postgresql/data目录的写权限，而 Docker Compose 默认没开--security-opt seccomp=unconfined。这三个案例说明：单机 Docker Compose 是一个“演示友好型”方案，它能让你快速看到 UI，但无法暴露生产环境中最致命的环境耦合问题。Hermes Agent 的核心设计是“服务自治”，每个组件（API、WebUI、DB、Vector Store）都应能独立启停、独立扩缩、独立监控。而 Docker Compose 把它们绑死在一个docker-compose.yml里，一旦某个服务挂了，整个docker-compose down/up就是暴力重启，根本没法做精细化的状态校验和故障隔离。

2.2 WSL2 作为本地沙盒的不可替代性：它不是 Linux 子系统，而是真正的轻量级虚拟机

很多人把 WSL2 当成“Windows 上的 Linux 命令行”，这是最大的认知误区。WSL2 的本质是一个高度优化的轻量级 Hyper-V 虚拟机，它运行的是完整的 Linux kernel（5.10.160.3-microsoft-standard-WSL2），拥有独立的 init 进程（PID 1）、完整的 systemd 服务管理、真实的/proc和/sys文件系统。这意味着你在 WSL2 里sudo systemctl start postgresql，启动的是真正的 PostgreSQL 服务进程，而不是 Docker 容器里的一个postgres进程。这种“原生服务”能力，让 WSL2 成为 Hermes Agent 环境调试的黄金沙盒。举个具体例子：Hermes Agent 的hermes serve命令默认会尝试连接postgresql://localhost:5432/hermes。在 Docker Compose 环境里，“localhost”指的是容器自身的 loopback 接口，所以必须通过network_mode: "host"或extra_hosts来绕过；而在 WSL2 里，“localhost”就是 WSL2 自身的 loopback，只要 PostgreSQL 服务在 WSL2 里跑起来了，hermes serve就能直连，完全不用改配置。更重要的是，WSL2 支持wsl --shutdown强制终止所有后台服务，比docker-compose down更彻底，能真实模拟云服务器上reboot后的服务自启行为。我甚至在 WSL2 里故意sudo systemctl stop postgresql，然后手动执行hermes serve，观察它报什么错、等多久超时、是否自动重试——这些细节，在 Docker Compose 里是看不到的，因为容器启动失败直接退出，日志就断了。所以，WSL2 不是“为了用 Linux 命令”，而是为了获得一个可控、可中断、可监控、与云服务器环境无限接近的本地实验场。它的价值，远超一个命令行终端。

2.3 云服务器选型的底层逻辑：不是看 CPU 核数，而是看 I/O 调度器和 swap 分区策略

热搜词里反复出现“云服务器32核128g中的128g指的是什么”，这恰恰暴露了多数人对云服务器本质的误解。128G 是内存容量，但它能否被 Hermes Agent 有效利用，取决于两个隐藏参数：I/O 调度器和 swap 分区策略。Hermes Agent 的向量数据库（默认是 PostgreSQL + pgvector）在处理高并发 embedding 查询时，会产生大量随机 I/O。如果云服务器的 I/O 调度器是deadline（很多老版本 CentOS 默认），在高负载下会出现明显的 I/O 延迟抖动，表现为hermes serve启动后curl /health响应时间从 200ms 突然跳到 2s，且不稳定。而现代云服务器（如阿里云最新代 ECS、腾讯云 CVM）默认使用mq-deadline或bfq，能平滑 I/O 延迟。另一个致命点是 swap 分区。很多免费云服务器（如 Oracle Cloud Always Free）默认不配 swap 分区，或者只配了 512MB。当 Hermes Agent 加载大模型（如nomic-embed-text-v1.5）时，内存峰值很容易突破 8GB，没有 swap，Linux kernel 会直接 OOM kill 进程，dmesg | grep -i "killed process"就能看到hermes-api被干掉的记录。而阿里云 ECS 的ecs.g7.large（2C8G）实例，默认 swap 分区是 2GB，且vm.swappiness=1（倾向使用物理内存），这就给了 Hermes Agent 一个安全缓冲。所以，选云服务器，不要只看“32核128g”这种营销参数，要进cat /sys/block/vda/queue/scheduler看调度器，用free -h看 swap 大小，用sysctl vm.swappiness看交换策略。这才是决定 Hermes Agent 能否稳定跑起来的底层硬件逻辑。

3. WSL2 本地环境部署：从 Ubuntu 22.04 安装到 Hermes Agent 服务启动的完整链路

3.1 WSL2 安装与 Ubuntu 22.04 初始化：避开微软商店的三个坑

WSL2 安装本身很简单，但初始化 Ubuntu 22.04 发行版时，有三个微软商店（Microsoft Store）版本带来的典型坑，必须手动规避。第一个坑是wsl --install命令默认安装的 Ubuntu 版本是20.04 LTS，而 Hermes Agent 的pydantic依赖要求 Python >= 3.8，Ubuntu 20.04 自带的 Python 是 3.8.10，勉强够用，但uvicorn的最新版要求typing_extensions >= 4.0.0，Ubuntu 20.04 的 apt 源里最高只到3.10.0，导致pip install hermes-agent时uvicorn编译失败。第二个坑是微软商店下载的 Ubuntu 应用，其 rootfs 是压缩的.appx包，解压后/etc/wsl.conf文件默认不存在，而这个文件是控制 WSL2 启动行为的关键。第三个坑是默认用户 shell 是bash，但 Hermes Agent 的 CLI 工具链（如hermes-cli）在zsh下有更友好的 tab 补全，且zsh的oh-my-zsh插件能自动识别hermes命令的子命令。所以，我推荐的初始化流程是：

1. 先卸载微软商店版：wsl --unregister Ubuntu-20.04（或你当前安装的版本名）
2. 从官网下载 Ubuntu 22.04 rootfs：访问 https://cloud-images.ubuntu.com/releases/22.04/release/，下载ubuntu-22.04-server-cloudimg-amd64-wsl.rootfs.tar.gz（注意是server-cloudimg版，不是desktop版，后者带 GUI 会拖慢启动速度）
3. 手动导入并设置默认用户：

   mkdir wsl2-ubuntu2204 && cd wsl2-ubuntu2204 tar -xf ~/Downloads/ubuntu-22.04-server-cloudimg-amd64-wsl.rootfs.tar.gz wsl --import Ubuntu-22.04 .\wsl2-ubuntu2204\ --version 2 # 设置默认用户为你的 Windows 用户名（假设是 john） ubuntu2204 config --default-user john

4. 创建/etc/wsl.conf并启用 systemd：

   sudo tee /etc/wsl.conf << 'EOF' [boot] command = "sudo /usr/bin/systemctl --no-block start dbus" systemd=true [interop] enabled=true appendWindowsPath=true [network] generateHosts=true generateResolvConf=true EOF

   提示：systemd=true是关键，没有它，sudo systemctl start postgresql会报错Failed to connect to bus: No such file or directory。command行是为了在 WSL2 启动时自动拉起 D-Bus 服务，这是很多 Linux 服务（包括 PostgreSQL）的依赖。

3.2 Docker 与 PostgreSQL 的 WSL2 原生安装：为什么不用 Docker Desktop？

在 WSL2 里，Docker Desktop 是一个冗余层。它会在 WSL2 虚拟机之上再套一层 LinuxKit VM，导致网络、存储、性能三重损耗。Hermes Agent 的部署目标是“服务自治”，所以我们选择在 WSL2 内部直接安装原生 Docker Engine 和原生 PostgreSQL。步骤如下：

1. 安装 Docker Engine（非 Desktop）：

   # 卸载可能存在的旧版 sudo apt remove docker docker-engine docker.io containerd runc # 添加 Docker 官方 GPG key 和源 sudo apt-get update && sudo apt-get install -y ca-certificates curl gnupg lsb-release sudo mkdir -p /etc/apt/sources.list.d curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/docker-archive-keyring.gpg echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/trusted.gpg.d/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null sudo apt-get update sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin # 将当前用户加入 docker 组，避免每次 sudo sudo usermod -aG docker $USER # 重启 WSL2 生效 exit wsl --shutdown

2. 安装 PostgreSQL 14（Hermes Agent 官方推荐版本）：

   # 添加 PostgreSQL 官方源（Ubuntu 22.04 默认源是 12，不够新） wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add - echo "deb http://apt.postgresql.org/pub/repos/apt/ $(lsb_release -sc)-pgdg main" | sudo tee /etc/apt/sources.list.d/pgdg.list sudo apt-get update sudo apt-get install -y postgresql-14 postgresql-client-14 postgresql-contrib-14 # 初始化数据库集群 sudo pg_createcluster 14 main --start # 切换到 postgres 用户，修改密码（Hermes Agent 默认连接用户是 postgres） sudo -u postgres psql -c "ALTER USER postgres PASSWORD 'hermes123';" # 修改监听地址，允许本地连接 echo "listen_addresses = 'localhost'" | sudo tee -a /etc/postgresql/14/main/postgresql.conf echo "port = 5432" | sudo tee -a /etc/postgresql/14/main/postgresql.conf # 重启服务 sudo systemctl restart postgresql

3. 验证 PostgreSQL 是否真正在跑：

   # 检查服务状态 sudo systemctl status postgresql # 检查端口监听 ss -tlnp | grep 5432 # 用 psql 连接测试（必须用 -U 指定用户，-d 指定数据库） psql -U postgres -d postgres -h localhost -p 5432 -c "SELECT version();"

   注意：ss -tlnp是比netstat更现代的端口检查工具，-tTCP,-llistening,-nnumeric,-pshow PID/program。如果这里看不到5432端口，说明 PostgreSQL 没起来，别急着装 Hermes，先查/var/log/postgresql/postgresql-14-main.log。

3.3 Hermes Agent 安装与服务启动：pip install后的三步必做校验

pip install hermes-agent看似一步到位，但实际部署中，90% 的失败发生在安装之后。必须做三步校验，缺一不可：

1. 校验 Python 环境与依赖冲突： Hermes Agent 依赖langchain-core==0.1.15和pydantic==2.6.4，这两个版本对typing模块要求严格。Ubuntu 22.04 自带的python3-typing包版本是3.10.12，而pydantic 2.6.4需要typing_extensions>=4.0.0。所以安装后必须强制升级：

   pip install --upgrade typing_extensions # 验证 python3 -c "import typing_extensions; print(typing_extensions.__version__)" # 输出应为 4.10.0 或更高

2. 校验 Hermes CLI 命令是否可用：

   # 查看帮助 hermes --help # 查看版本（确认不是旧版缓存） hermes --version # 初始化配置目录（这会生成 ~/.hermes/config.yaml） hermes init

   如果hermes --help报错command not found，说明pip安装的脚本没加到 PATH。检查which hermes，如果为空，执行：

   echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc source ~/.bashrc

3. 启动服务并做最小化健康检查：

   # 启动 Hermes API 服务（注意 --host 0.0.0.0 是为了让 Windows 主机也能访问） hermes serve --host 0.0.0.0:8000 --port 8000 --database-url postgresql://postgres:hermes123@localhost:5432/hermes # 在另一个 WSL2 terminal 里，用 curl 测试 curl -v http://localhost:8000/health # 正常响应应为 HTTP/1.1 200 OK 和 {"status":"ok"} # 再测试一个业务接口 curl -X POST http://localhost:8000/api/v1/agents -H "Content-Type: application/json" -d '{"name":"test","description":"test agent"}' # 正常响应应为 HTTP/1.1 201 Created 和 {"id":"xxx",...}

   关键点：--database-url参数必须和 PostgreSQL 的实际配置完全一致。localhost是 WSL2 的 loopback，5432是 PostgreSQL 监听端口，hermes是数据库名（Hermes Agent 会自动创建，如果不存在）。如果curl /health超时，立刻Ctrl+C停止hermes serve，然后检查journalctl -u postgresql -n 50，看 PostgreSQL 是否在报错。

4. 云服务器一键部署全流程：从 ECS 创建到 Hermes Agent 状态校验的实操细节

4.1 云服务器创建与基础环境初始化：阿里云 ECS 的 5 个必改配置

以阿里云 ECSecs.g7.large（2C8G）为例，创建实例后，必须做以下五项配置，否则 Hermes Agent 会启动失败：

1. 安全组规则开放：不只是开放8000端口，还要开放5432（PostgreSQL）、6379（Redis，Hermes Agent 的 session store）、22（SSH）。特别注意，安全组的入方向规则里，8000端口的授权对象不能只写0.0.0.0/0，要写0.0.0.0/0,::/0（同时支持 IPv4 和 IPv6），否则某些地区运营商的 IPv6 用户访问不了。
2. 实例规格确认：在 ECS 控制台的“实例详情”页，点击“更多”->“实例设置”->“实例规格”，确认CPU和Memory与购买时一致。曾遇到过客户购买ecs.g7.large，但控制台显示ecs.g6.large，这是阿里云的库存调度问题，必须提工单更换。
3. 系统盘扩容：ECS 默认系统盘是 40GB，而 Hermes Agent 的~/.hermes/storage目录（存放 embedding cache 和 uploaded files）很容易超过 20GB。所以创建后立即登录，执行df -h，如果/分区小于 30GB，必须先扩容。阿里云控制台支持在线扩容，但扩容后需在 Linux 里执行resize2fs /dev/vda1（ext4 文件系统）或xfs_growfs /（xfs 文件系统）。
4. Swap 分区创建：阿里云 ECS 默认无 swap。执行：

   # 创建 2GB swap 文件 sudo fallocate -l 2G /swapfile sudo chmod 600 /swapfile sudo mkswap /swapfile sudo swapon /swapfile # 永久生效 echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab # 查看效果 free -h

5. I/O 调度器切换：阿里云 ECS 默认是none（针对 NVMe SSD 优化），但 Hermes Agent 的 pgvector 查询是随机 I/O，none调度器在高并发下不如bfq稳定。执行：

   # 查看当前调度器 cat /sys/block/vda/queue/scheduler # 切换为 bfq（需 root 权限） echo 'bfq' | sudo tee /sys/block/vda/queue/scheduler # 永久生效（写入 /etc/default/grub） sudo sed -i 's/GRUB_CMDLINE_LINUX=""/GRUB_CMDLINE_LINUX="elevator=bfq"/' /etc/default/grub sudo update-grub && sudo reboot

4.2 一键部署脚本编写与执行：如何让./deploy.sh真正“一键”？

所谓“一键部署”，不是写一个apt install的 bash 脚本，而是把所有可能失败的环节都做成可重入、可回滚、可 debug 的模块。我的deploy.sh结构如下：

#!/bin/bash # deploy.sh - Hermes Agent 云服务器一键部署脚本 set -e # 任何命令失败立即退出 LOG_FILE="/var/log/hermes-deploy.log" exec > >(tee -a "$LOG_FILE") 2>&1 echo "[$(date)] 开始部署 Hermes Agent" # 步骤1：系统更新与基础工具安装 echo "[$(date)] 步骤1：系统更新" apt-get update && apt-get upgrade -y apt-get install -y curl wget git vim net-tools # 步骤2：安装 Docker Engine echo "[$(date)] 步骤2：安装 Docker" # （此处省略 Docker 安装命令，同 WSL2 部分） # 步骤3：安装 PostgreSQL 14 echo "[$(date)] 步骤3：安装 PostgreSQL" # （此处省略 PostgreSQL 安装命令，同 WSL2 部分） # 步骤4：安装 Hermes Agent echo "[$(date)] 步骤4：安装 Hermes Agent" pip3 install --upgrade pip pip3 install hermes-agent # 步骤5：创建 Hermes 配置文件 echo "[$(date)] 步骤5：生成配置文件" mkdir -p ~/.hermes cat > ~/.hermes/config.yaml << 'EOF' database: url: postgresql://postgres:hermes123@localhost:5432/hermes pool_size: 20 redis: url: redis://localhost:6379/0 server: host: 0.0.0.0 port: 8000 workers: 4 EOF # 步骤6：启动服务并校验 echo "[$(date)] 步骤6：启动服务" hermes serve --config ~/.hermes/config.yaml & HERMES_PID=$! sleep 10 # 等待服务启动 # 校验1：检查进程是否存在 if ! kill -0 $HERMES_PID 2>/dev/null; then echo "[$(date)] 错误：hermes serve 进程未启动" exit 1 fi # 校验2：检查端口监听 if ! ss -tlnp | grep ':8000' >/dev/null; then echo "[$(date)] 错误：8000 端口未监听" exit 1 fi # 校验3：HTTP 健康检查 if ! curl -s -f http://localhost:8000/health >/dev/null; then echo "[$(date)] 错误：/health 接口返回非 200" exit 1 fi echo "[$(date)] 部署成功！Hermes Agent 已启动，PID: $HERMES_PID"

实操心得：set -e是灵魂，它让脚本在任何一步失败时立刻停止，而不是继续往下跑，导致错误被掩盖。exec > >(tee -a "$LOG_FILE")把所有输出同时写入日志和屏幕，方便事后排查。最关键的是三个校验：进程存在、端口监听、HTTP 健康。这三个校验缺一不可，只检查curl /health是不够的，因为有些情况hermes serve进程起来了，但没监听8000端口（比如配置文件写错了 host），curl就会超时，而ss -tlnp能立刻发现问题。

4.3 服务状态校验与环境调试：curl之外的五个深度诊断命令

服务启动后，curl http://your-server-ip:8000/health返回200 OK只是万里长征第一步。真正的环境调试，要用以下五个命令深入探查：

1. systemctl status查看服务依赖状态：

   # 检查 PostgreSQL sudo systemctl status postgresql # 检查 Redis（如果用了 Redis） sudo systemctl status redis-server # 检查 Docker（如果用了 Docker） sudo systemctl status docker

   注意：systemctl status的输出里，Active:行后面如果是active (running)，说明服务在跑；如果是active (exited)，说明是 oneshot 类型服务，已执行完退出，这可能是正常的（如docker服务）；如果是inactive (dead)，说明服务根本没起来。

2. journalctl实时追踪服务日志：

   # 实时查看 Hermes Agent 日志（按 Ctrl+C 退出） journalctl -u hermes -f # 查看 PostgreSQL 最近 100 行错误日志 journalctl -u postgresql -n 100 | grep -i "error\|fail\|panic" # 查看系统级 OOM 记录 dmesg | grep -i "killed process"

   实操心得：journalctl -u hermes -f是最有效的实时调试方式。当你在 WebUI 里点一个按钮没反应，立刻切到终端执行这个命令，看有没有SQLAlchemyError或ConnectionRefusedError的堆栈。dmesg | grep -i "killed process"是查 OOM 的终极手段，比free -h更直接。

3. ss和netstat检查端口与连接：

   # 查看所有监听端口（TCP） ss -tlnp # 查看 Hermes Agent 进程的网络连接（它是否在连 PostgreSQL？） ss -tnp | grep $(pgrep -f "hermes serve") # 查看 PostgreSQL 的连接数（是否被占满？） sudo -u postgres psql -c "SELECT count(*) FROM pg_stat_activity;"

   提示：ss比netstat快，是现代 Linux 的首选。ss -tnp | grep $(pgrep -f "hermes serve")这条命令能告诉你 Hermes Agent 进程当前建立了哪些 TCP 连接，如果它连不上127.0.0.1:5432，这里就看不到那条连接。

4. ps aux查看进程树与资源占用：

   # 查看所有 Python 进程 ps aux | grep python # 查看 Hermes Agent 进程的内存和 CPU 使用率 ps aux --sort=-%mem | head -10 # 查看 PostgreSQL 的子进程（backend 进程数） ps aux | grep postgres | grep -v "grep" | wc -l

   注意：ps aux --sort=-%mem会按内存使用率倒序排列，一眼就能看出哪个进程吃内存最多。Hermes Agent 的hermes serve进程如果内存超过 3GB，就要警惕是不是 embedding model 加载有问题。

5. hermes-cli工具链的本地诊断：

   # 在云服务器上，用 hermes-cli 直接调用 API（绕过网络） hermes-cli agents list # 检查数据库连接 hermes-cli db check # 查看当前配置 hermes-cli config show

   关键点：hermes-cli是 Hermes Agent 官方提供的命令行工具，它和hermes serve共享同一套配置和数据库连接逻辑。如果hermes-cli agents list能列出 agent，但curl http://ip:8000/api/v1/agents返回500，那问题一定出在网络或反向代理上，而不是数据库。

5. 常见问题与排查技巧实录：从psql: could not connect to server到hermes serve启动后无响应的 7 个真实案例

5.1 PostgreSQL 连接失败的三种根因与对应解法

案例1：psql: could not connect to server: Connection refused（WSL2）
现象：sudo systemctl start postgresql后，sudo systemctl status postgresql显示active (running)，但psql -U postgres -d postgres报Connection refused。
根因：postgresql.conf里的listen_addresses默认是localhost，但 WSL2 的localhost和 Windows 的localhost不是同一个网络栈。WSL2 的localhost是127.0.0.1，而 PostgreSQL 默认只监听127.0.0.1，没问题；但有时pg_hba.conf里host all all 127.0.0.1/32 md5这一行被注释了。
解法：编辑/etc/postgresql/*/main/pg_hba.conf，确保有这一行：

host all all 127.0.0.1/32 md5

然后sudo systemctl restart postgresql。

案例2：psql: FATAL: role "postgres" does not exist（云服务器）
现象：在阿里云 ECS 上，sudo -u postgres psql进去后，CREATE DATABASE hermes;成功，但hermes serve启动时报role "postgres" does not exist。
根因：阿里云 ECS 的 Ubuntu 镜像默认禁用了postgres用户，sudo -u postgres psql是用sudo切换的，但hermes serve进程是以普通用户身份运行的，它没有权限用postgres用户连接。
解法：创建一个新用户，并赋予 superuser 权限：

sudo -u postgres psql -c "CREATE USER hermes WITH PASSWORD 'hermes123';" sudo -u postgres psql -c "ALTER USER hermes WITH SUPERUSER;" sudo -u postgres psql -c "CREATE DATABASE hermes OWNER hermes;"

然后hermes serve --database-url postgresql://hermes:hermes123@localhost:5432/hermes。

案例3：psql: could not connect to server: No route to host（跨网络）
现象：在云服务器上，hermes serve配置了--database-url postgresql://user:pass@other-server-ip:5432/db，但启动失败。
根因：PostgreSQL 默认只监听localhost，不监听外部 IP。即使开了安全组，PostgreSQL 本身没配置。
解法：修改/etc/postgresql/*/main/postgresql.conf：

listen_addresses = '0.0.0.0' # 允许所有 IP port = 5432

修改/etc/postgresql/*/main/pg_hba.conf：

host all all 0.0.0.0/0 md5

然后sudo systemctl restart postgresql，并确保防火墙（ufw）放行5432端口。

5.2 Hermes Agent 启动后无响应的四个隐蔽陷阱

**案例4：hermes serve进程在