佛系程序员_ 国内服务器部署 Hermes Agent 全流程踩坑记录（从 clone 到可运行）

学习笔记

网站开发

发布日期: 2026-05-03 17:28:21

喜欢量: 6 个

阅读次数: 44

# 国内服务器部署 Hermes Agent 全流程踩坑记录（从 clone 到...

# 国内服务器部署 Hermes Agent 全流程踩坑记录（从 clone 到可运行）

这篇记录的是在国内 阿里云 Linux 服务器上部署 Hermes Agent 的完整过程，包括环境准备、虚拟环境、依赖安装失败、以及最终成功运行的关键修复点。

整体结论先说在前面：

* install.sh 可以用，但不推荐
* venv 必须手动控制
* 国内源必须配置
* 最大坑是 wheel / 构建隔离 / GitHub 依赖

---

# 一、克隆项目

首先从 GitHub 拉取源码：

```bash
git clone https://github.com/NousResearch/hermes-agent.git
cd hermes-agent
```

这一步通常没问题，但后续依赖安装才是核心难点。

---

# 二、创建 Python 虚拟环境（必须手动）

项目推荐使用 Python 3.11：

```bash
python3.11 -m venv venv
```

激活环境：

```bash
source venv/bin/activate
```

如果这里报错，一般是：

* venv 未安装
* Python 环境不完整

---

# 三、最关键的一步：不要直接用 install.sh

很多人第一步就踩坑：

```bash
chmod +x install.sh && ./install.sh
```

问题是：

* 无法控制 pip 源
* 可能使用 uv（更快但国内更容易卡死）
* 日志不透明
* 出错无法定位

结论：

👉 install.sh 在国内环境不推荐使用

---

# 四、正确做法：手动安装依赖（核心）

## 4.1 升级基础工具

```bash
pip install -U pip setuptools wheel -i https://pypi.tuna.tsinghua.edu.cn/simple
```

这里非常关键，否则会出现：

```
error: invalid command 'bdist_wheel'
```

---

## 4.2 使用国内镜像安装项目

这是最稳定方式：

```bash
pip install . --no-build-isolation -i https://pypi.tuna.tsinghua.edu.cn/simple
```

参数说明：

* --no-build-isolation：关闭隔离构建（避免重复下载依赖）
* -i 清华源：解决国内 PyPI 速度问题

---

# 五、绕过 install.sh（正确做法总结）

整个核心原则是：

✔ 不依赖脚本
✔ 手动控制 pip
✔ 关闭构建隔离
✔ 使用国内源

最终安装路径变成：

```bash
pip install .
```

而不是：

```bash
./install.sh
```

---

# 六、使用 venv（必须标准化）

完整标准流程：

```bash
python3.11 -m venv venv
source venv/bin/activate
pip install -U pip setuptools wheel
```

这是整个安装的“基础地基”。

---

# 七、国内源配置（必须做）

永久配置：

```bash
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
```

否则会出现：

* 下载慢
* 卡在 collecting
* GitHub 依赖超时

---

# 八、GitHub 依赖加速（隐藏关键点）

如果依赖中有 git clone：

```bash
git config --global url."https://ghproxy.com/https://github.com/".insteadOf "https://github.com/"
```

否则国内服务器会卡死在：

* cloning repository
* fetching submodules

---

# 九、最终运行

安装成功后执行：

```bash
hermes
```

首次运行会提示：

```
no API keys or providers found
```

然后执行：

```bash
hermes setup
```

配置模型即可运行。

---

# 十、完整总结（最重要）

整个 Hermes 在国内服务器的正确流程是：

1. git clone 项目
2. python3.11 -m venv venv
3. source venv/bin/activate
4. pip install -U pip setuptools wheel
5. pip install . --no-build-isolation -i 国内源
6. hermes setup
7. hermes or hermes gateway

---

# 十一、核心经验总结

这次部署踩坑后的结论非常明确：

* install.sh 在国内环境不可靠
* venv 必须手动管理
* wheel 是隐藏关键依赖
* GitHub + PyPI 是双重瓶颈
* pip 构建隔离是最大隐形坑

yyii

https://www.amtb.info/show/Mzkz

本博客所有文章除特別声明外,转载请注明来源佛系程序员 !