飞牛 NAS 部署 Headroom 压缩代理：给 CowAgent 省 Token 的完整指南

飞牛 NAS 部署 Headroom 压缩代理：给 CowAgent 省 Token 的完整指南

环境：飞牛 NAS（主机名 fnnas，aarch64，Python 3.11.2，无 uv）
CowAgent 源码位于 /root/CowAgent/，当前 bot_type: zhipu，模型 glm-5-turbo，智谱 key 已配置
所有命令在 NAS 上以 root 运行（sudo -i）

链路

1
CowAgent (zhipu/OpenAI 格式) → headroom (:8787/v1, 压缩上下文) → https://open.bigmodel.cn/api/paas/v4 → GLM

Headroom 是一个透明代理，CowAgent 发的智谱 key 会原样透传到上游，不用装 cc-switch。CowAgent 的 bot_type、model、zhipu_ai_api_key 都不动，只改 zhipu_ai_api_base 指向 headroom。

如果你还没部署 CowAgent，先看 飞牛 NAS 部署 CowAgent 并开放局域网访问，本文假设 CowAgent 已经跑起来并且能用智谱 GLM 正常回复。

先知道这些

  1. 安装包很大：headroom-ai 会拖 torch / transformers / opencv / scipy / sentence-transformers / pandas 等一堆 ML 依赖，aarch64 上约 3–5 GB，装十几分钟正常。若某个包没有 aarch64 wheel 会尝试源码编译（可能失败，届时单独处理）。
  2. **压缩可能让机器人”忘事”**：headroom token 模式会改写/压缩历史轮次以省 token。CowAgent 自己已截断到 agent_max_context_tokens: 50000 / 20 轮，再压一层，长对话里可能丢细节。微信/飞书聊天场景要留意体验。
  3. 会改 CowAgent 配置：先备份 config.json，出问题能秒回滚。

1. 装 headroom

1
2
3
4
5
6
7
8
9
# 建 venv
python3 -m venv ~/.headroom-venv
~/.headroom-venv/bin/pip install -U pip

# 装 headroom-ai（这一步很慢，耐心等）
~/.headroom-venv/bin/pip install headroom-ai

# 验证
~/.headroom-venv/bin/headroom --version

看到 headroom, version 0.28.0（或更高）即成功。

如果 pip 报 Python 版本不满足（headroom 可能要求 3.10+，3.11 一般够），改用 uv 装 Python 3.12：

1
2
3
4
curl -LsSf https://astral.sh/uv/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"
uv venv ~/.headroom-venv --python 3.12
~/.headroom-venv/bin/pip install headroom-ai

2. 写启动脚本

1
2
3
4
5
6
7
8
9
10
11
12
13
14
cat > ~/.headroom-start.sh << 'EOF'
#!/bin/bash
# 上游：智谱 paas/v4（OpenAI 格式）
export OPENAI_TARGET_API_URL=https://open.bigmodel.cn/api/paas/v4
# 跳过上游健康检查（避免误判启动失败）
export HEADROOM_SKIP_UPSTREAM_CHECK=1
# CowAgent 是普通 OpenAI 客户端，不注入 headroom_retrieve 工具，跑纯压缩
export HEADROOM_NO_CCR_INJECT_TOOL=1
# 不注入 memory 工具/上下文（进一步省 token，避免干扰聊天）
export HEADROOM_NO_MEMORY_TOOLS=1
export HEADROOM_NO_MEMORY_CONTEXT=1
exec ~/.headroom-venv/bin/headroom proxy --port 8787 --host 127.0.0.1
EOF
chmod +x ~/.headroom-start.sh

参数说明：

  • --host 127.0.0.1：只本机监听，不暴露到局域网（CowAgent 在同一台 NAS，够用）
  • OPENAI_TARGET_API_URL：headroom 把 OpenAI 格式请求转发到智谱
  • HEADROOM_NO_CCR_INJECT_TOOL：关键，否则 CowAgent 收到陌生的 headroom_retrieve 工具会报错
  • 默认 --mode token（压缩优先），想更激进可加 --target-ratio 0.5（保留约 50% token）

3. 先手跑一次，验证能通

1
~/.headroom-start.sh

另开一个终端（或先 Ctrl+C，用下面命令测），跑 curl 验证 OpenAI 入口 + 智谱转发：

1
2
3
4
curl -s http://127.0.0.1:8787/v1/chat/completions \
  -H "Authorization: Bearer $(python3 -c 'import json;print(json.load(open("/root/CowAgent/config.json"))["zhipu_ai_api_key"])')" \
  -H "content-type: application/json" \
  -d '{"model":"glm-5-turbo","max_tokens":16,"messages":[{"role":"user","content":"说声ok"}]}'

看到正常的 GLM 回复（"content":"ok"... 之类）就说明链路通了。Ctrl+C 停掉手跑的进程，下一步交给 systemd 托管。

如果 curl 报错，看 /tmp/headroom-proxy.log（手跑时是终端输出）排查。常见是 key 没透传或模型名不对。

4. 设开机自启（systemd）

fnOS 是 Debian 系，systemd 可用：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
cat > /etc/systemd/system/headroom.service << 'EOF'
[Unit]
Description=Headroom compression proxy
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
ExecStart=/root/.headroom-start.sh
Restart=always
RestartSec=10
StandardOutput=append:/var/log/headroom.log
StandardError=append:/var/log/headroom.log

[Install]
WantedBy=multi-user.target
EOF

systemctl daemon-reload
systemctl enable --now headroom
systemctl status headroom --no-pager

看到 active (running) 即成功。日志在 /var/log/headroom.log。

5. 改 CowAgent 配置指向 headroom

先备份：

1
cp /root/CowAgent/config.json /root/CowAgent/config.json.bak.$(date +%s)

只改 zhipu_ai_api_base，其它不动：

1
sed -i 's#"zhipu_ai_api_base": "https://open.bigmodel.cn/api/paas/v4"#"zhipu_ai_api_base": "http://127.0.0.1:8787/v1"#' /root/CowAgent/config.json

验证：

1
grep zhipu_ai_api_base /root/CowAgent/config.json

应为 "zhipu_ai_api_base": "http://127.0.0.1:8787/v1"。

6. 重启 CowAgent

改完 zhipu_ai_api_base 后必须重启 CowAgent 才能生效。CowAgent 的重启方式取决于它是怎么跑起来的：

如果用 systemd 托管（推荐）

1
2
systemctl restart cowagent
systemctl status cowagent --no-pager

看到 active (running) 即已重启。日志在 /var/log/cowagent.log：

1
tail -f /var/log/cowagent.log

如果还没给 CowAgent 配 systemd，参考 CowAgent 部署指南 第 4 节。

如果用 screen / nohup 跑的

1
2
3
4
5
6
7
8
9
# screen 方式
screen -r cowagent       # 进入会话
# Ctrl+C 停掉旧进程
cd /root/CowAgent && source venv/bin/activate && python3 app.py
# Ctrl+A 再按 D 脱离会话

# nohup 方式
kill $(pgrep -f cowagent)
nohup /root/CowAgent/venv/bin/python3 app.py > /var/log/cowagent.log 2>&1 &

验证链路

重启后在 Web 控制台或微信/飞书发一条消息，能正常回复就说明整条链路通了——headroom 压缩 + GLM 转发没有断。如果报错，先看两头日志定位：

1
2
3
4
5
# headroom 日志
tail -f /var/log/headroom.log

# CowAgent 日志
tail -f /var/log/cowagent.log

7. 确认压缩在生效

看 headroom 日志：

1
tail -f /var/log/headroom.log

请求经过时会有 tokens_before / tokens_after / latency_ms 之类的记录，tokens_after < tokens_before 就说明在省 token。

出问题怎么回滚

CowAgent 不正常就立刻切回直连智谱：

1
2
cp /root/CowAgent/config.json.bak.* /root/CowAgent/config.json
# 重启 CowAgent

Headroom 本身停掉不影响 CowAgent（只是没了压缩，CowAgent 直连 headroom 会连不上，所以回滚 config 必须做）。要彻底卸载 headroom：

1
2
3
4
systemctl disable --now headroom
rm /etc/systemd/system/headroom.service
systemctl daemon-reload
rm -rf ~/.headroom-venv ~/.headroom-start.sh

备选：如果 zhipu SDK 不兼容代理

CowAgent 的 zhipu bot 用的是智谱 SDK，极少数情况下可能跟代理相处不好。若第 6 步报错，改用标准 OpenAI 通道（更可预测）：

1
2
3
4
5
6
7
8
9
10
11
python3 - << 'EOF'
import json
p = "/root/CowAgent/config.json"
c = json.load(open(p))
c["bot_type"] = "openai"
c["open_ai_api_base"] = "http://127.0.0.1:8787/v1"
c["open_ai_api_key"] = c["zhipu_ai_api_key"]
c["model"] = "glm-5-turbo"
json.dump(c, open(p, "w"), indent=4, ensure_ascii=False)
print("done")
EOF

然后重启 CowAgent。

文件清单

路径 作用
~/.headroom-venv/ Headroom 专用 Python 虚拟环境
~/.headroom-start.sh Headroom 启动脚本（含环境变量配置）
/etc/systemd/system/headroom.service systemd 服务文件
/var/log/headroom.log Headroom 运行日志
/root/CowAgent/config.json CowAgent 主配置（zhipu_ai_api_base 改成了 headroom）
/root/CowAgent/config.json.bak.* 改配置前的备份（回滚用）