🐻 Hermes Agent 实战部署全记录

WSL2 + DeepSeek + Cloudflare Tunnel + 熊.online 完整部署 | v0.13.0 | 2026-05-14

1. 环境准备与 WSL2 踩坑

1.1 初始环境

1.2 执行步骤

# 启用 WSL（需管理员权限）
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

# 重启电脑后
wsl --install -d Ubuntu    # 安装 Ubuntu
wsl --set-default-version 2  # 设 WSL2 为默认

1.3 最终环境

2. Hermes 安装与命令行配置

2.1 安装路径选择

cd ~ && git clone https://github.com/NousResearch/hermes-agent.git
cd hermes-agent && uv sync && uv pip install -e ".[web]"

2.2 全局命令配置

2.3 CRLF 换行噩梦

整个部署过程中反复遇到 \$'\r': command not found 错误。根源是 PowerShell 写入文件默认用 CRLF，WSL 需要 LF。

# PowerShell 侧统一使用这个模式
(Get-Content "file.sh" -Raw).Replace("`r`n","`n") | Set-Content "file_lf.sh" -NoNewline
wsl.exe cp /mnt/c/.../file_lf.sh /path/in/wsl/

3. DeepSeek API 接入

3.1 模型选择

3.2 配置方式

# ~/.hermes/config.yaml
model:
  provider: deepseek
  default: deepseek-chat

# ~/.hermes/.env
DEEPSEEK_API_KEY=sk-xxxxx
DEEPSEEK_BASE_URL=https://api.deepseek.com

3.3 API Key 泄露事件

4. 微信集成实战

4.1 三种方案对比

4.2 扫码流程

# 终端运行
hermes gateway setup
# 选择 Weixin / WeChat → Y 开始扫码
# 终端会输出二维码链接，复制到浏览器打开
# 微信扫码 → 确认登录

4.3 DM 策略建议

WEIXIN_DM_POLICY=allowlist           # 白名单模式（推荐）
WEIXIN_GROUP_POLICY=disabled          # 禁用群聊

5. Dashboard 中文可视化

5.1 启动命令

hermes dashboard --port 9119 --host 0.0.0.0 --no-open --insecure

5.2 中文切换

左下角 Switch to Chinese → 选择 简体中文。所有导航、配置页面立即中文化。

5.3 Dashboard 依赖

# 必须先安装 Web 依赖
uv pip install -e ".[web]"   # 安装 fastapi + uvicorn

6. SOUL 人格与工具优化

6.1 SOUL.md 人格配置

6.2 优化的工具

6.3 配置优化建议

agent.max_turns: 90        # 工具调用上限（探索场景可设 150+）
compression_threshold: 0.5 # 上下文压缩阈值
tool_progress_mode: all    # 工具进度显示模式

7. 外网访问：Cloudflare Tunnel 血泪史

7.1 尝试过的方法

7.2 最终可行的方案

# API Key 格式（不是 Bearer Token）
curl -H "X-Auth-Email: [email protected]" -H "X-Auth-Key: cfk_xxxxx" \
  -X PUT ".../cfd_tunnel/TUNNEL_ID/configurations" \
  -d '{"config":{"ingress":[{"hostname":"hermes.熊.online","service":"http://localhost:8888"},...]}}'

7.3 架构决策

/           → http://127.0.0.1:9119  (Dashboard)
/chat       → /var/www/chat          (聊天页面)
info子域名   → port 8889              (信息页)

8. DNS + API 配置关键步骤

8.1 Cloudflare API 认证差异

8.2 关键 ID 获取

# Zone ID
curl "https://api.cloudflare.com/client/v4/zones?name=熊.online" \
  -H "X-Auth-Email: ..." -H "X-Auth-Key: ..."

# DNS 记录管理
curl "...zones/$ZONE/dns_records" -X POST -d '{"type":"CNAME","name":"hermes",...}'

# Tunnel ingress 配置
curl "...accounts/$ACCOUNT/cfd_tunnel/$TUNNEL/configurations" -X PUT -d '{...}'

8.3 Hermes API Server 启用

# ~/.hermes/.env
API_SERVER_ENABLED=true
API_SERVER_KEY=***REDACTED***
API_SERVER_HOST=0.0.0.0
API_SERVER_PORT=8642
# 重启网关
hermes gateway restart

9. 网页聊天界面搭建

9.1 架构

纯前端 HTML 页面，直接调用 Hermes API Server 的 OpenAI 兼容接口。不需要后端服务器。

浏览器 → https://hermes.熊.online/chat (静态 HTML)
       → fetch('https://api.熊.online/v1/chat/completions', {
           headers: { 'Authorization': 'Bearer ***REDACTED***' },
           body: JSON.stringify({model:'deepseek-chat', messages:[...]})
         })

9.2 功能特性

• 模型切换：deepseek-chat / reasoner / v4-flash
• 暗色主题、响应式布局
• Enter 发送、Shift+Enter 换行
• 流式加载指示器

9.3 接入其他前端

10. 短链服务 (Shlink)

10.1 选型变化

10.2 部署命令

docker run -d --name shlink -p 8080:8080 \
  -e DEFAULT_DOMAIN=s.熊.online \
  -e INITIAL_API_KEY=abc123def456 \
  shlinkio/shlink:latest

10.3 API 使用

# 创建短链
curl -X POST https://s.熊.online/rest/v3/short-urls \
  -H "X-Api-Key: abc123def456" \
  -H "Content-Type: application/json" \
  -d '{"longUrl":"https://github.com/NousResearch/hermes-agent"}'

# 健康检查
curl https://s.熊.online/rest/v3/health

11. 最终架构与经验总结

11.1 完整架构图

                          ┌─────────────────────────┐
                          │     Cloudflare CDN       │
                          │  (DNS + Tunnel + HTTPS)  │
                          └───────────┬─────────────┘
                                      │
              ┌───────────────────────┼───────────────────────┐
              │                       │                       │
      hermes.熊.online          api.熊.online           s.熊.online
              │                       │                       │
      ┌───────┴───────┐       ┌───────┴───────┐       ┌───────┴───────┐
      │  Nginx :8888   │       │ Hermes :8642  │       │ Shlink :8080   │
      │  /     → :9119 │       │ (API Server)  │       │ (Docker)       │
      │  /chat → html  │       └───────┬───────┘       └───────────────┘
      └───────┬───────┘               │
              │               ┌───────┴───────┐
      ┌───────┴───────┐       │   DeepSeek    │
      │Dashboard :9119│       │   API (外部)   │
      │ info.熊.online│       └───────────────┘
      │   :8889       │
      └───────────────┘

11.2 子域名完整列表

11.3 服务自启动状态

11.4 核心经验教训

12. 网站优化：认证、API、短链修复 (2026-05-15)

12.1 问题背景

12.2 移除 HTTP Basic Auth

排查过程

# 查看 HTTP 响应头确认认证类型
curl -I https://exp.熊.online
# → WWW-Authenticate: Basic realm="Password"

# 查看 nginx 配置
grep -r auth_basic /etc/nginx/sites-enabled/

auth_basic "Password";
auth_basic_user_file /etc/nginx/.htpasswd;

sed -i 's/^[[:space:]]*auth_basic/#auth_basic/' /etc/nginx/sites-enabled/exp
sed -i 's/^[[:space:]]*auth_basic_user_file/#auth_basic_user_file/' /etc/nginx/sites-enabled/exp
# info 同理
nginx -t && nginx -s reload

12.3 API 站点修复与文档页

架构发现

# 查看运行模式
ps aux | grep cloudflared
# → --token xxx  ← token 模式！

API 页面方案

# /etc/nginx/sites-enabled/api (port 8092)
server {
    listen 8092;
    root /var/www/api;
    index index.html;
    location /v1/ {
        proxy_pass http://127.0.0.1:8642;
        proxy_set_header Host $host;
        proxy_buffering off;
        proxy_read_timeout 120s;
    }
    location = / {
        try_files /index.html =404;
    }
}

API 免认证决策

# ~/.hermes/.env
API_SERVER_KEY=          # 清空 = 允许无认证
API_SERVER_HOST=127.0.0.1 # 仅监听本地

12.4 短链服务 (s.熊.online) 修复

Nginx 配置（位置优先级！）

server {
    listen 8091;
    location /rest/ { proxy_pass http://127.0.0.1:8080; }  # API
    location = /   { try_files /index.html =404; }          # 网页
    location /     { proxy_pass http://127.0.0.1:8080; }    # 跳转
}

Shlink 重建

docker stop shlink && docker rm shlink
docker run -d --name shlink --restart unless-stopped -p 8080:8080 \
  -e DEFAULT_DOMAIN=s.熊.online -e IS_HTTPS_ENABLED=true \
  shlinkio/shlink:latest
docker exec shlink shlink api-key:generate  # 重建后旧 Key 失效

12.5 最终服务映射

12.6 新增经验教训