一台裸奔的海外 VPS，跑着 new-api、x-ui、Hermes Agent 三个服务，端口审计发现 3000 + 50404 公网监听——我是怎么一步步把它变成铁桶的。

背景：一台裸奔的 VPS

上个月整理 GCP 免费赠金 VPS，发现上面跑着：

• new-api（端口 3000）— AI API 代理网关
• x-ui（端口 50404）— 代理面板
• Hermes Agent（内部端口）— 个人 AI 助理

三个服务全部 0.0.0.0 绑定，直接暴露在公网。用 nmap 扫了一下自己的 IP：

$ nmap -Pn <my-ip>
PORT      STATE SERVICE
3000/tcp  open  ppp
50404/tcp open  unknown

更要命的是，new-api 后台后来审计发现了 7 个陌生 bot 账号，说明已经被扫到了。ROOT_PASSWORD 还是默认的弱密码。

这篇文章记录我从"裸奔"到"三层防御"的完整过程，每一步都是真实踩坑后的总结。

第一层：GCP Firewall — 在流量进主机前挡住

核心思路：在 GCP 层面直接拒绝，流量根本不到你的主机。

GCP Firewall 支持按 instance tag 匹配规则。我先创建了一个 tag secure-server，然后写规则：

# 拒绝所有入站，只允许特定端口
gcloud compute firewall-rules create deny-all-ingress \
  --direction=INGRESS \
  --priority=65534 \
  --network=default \
  --action=DENY \
  --rules=all \
  --target-tags=secure-server \
  --source-ranges=0.0.0.0/0

踩坑：规则创建后测试 nc -zv <ip> 3000，发现还是通的。排查半小时发现——instance 没打 tag。规则存在但没 target，等于没配。

人类 chatbot 最尴尬的瞬间：第二次见面完全不认识你。Agent 的记忆系统怎么同时做到持久化、低成本、不丢上下文？我深入 Hermes-Lite 源码写了一个月，拆解出 5 层架构。

从「鱼的难题」开始

用过 ChatGPT 的人都知道一个痛：下次打开，它完全不记得你了。

对一次性聊天这没问题。但对个人助理——帮你管理 200 条知识库、追踪几个项目的进度、记住你的偏好——这等于每次都要把整段友情重来。

我做 QPC（个人知识库）时就被这个问题卡过。后来折腾 Hermes-Lite、nanobot，逐步摸到一条可行的路。这篇文章从 Hermes-Lite 的实际源码出发，拆解它的 5 层记忆架构，看看一个 Agent 是怎么解决「鱼的难题」的。

总览：5 层架构

┌─────────────────────────────────────────────┐
│  Layer 1: 持久记忆 (MEMORY.md / USER.md)     │  ← 跨会话，纯文本
├─────────────────────────────────────────────�
│  Layer 2: 会话压缩 (ContextCompressor)       │  ← 长对话不爆
├─────────────────────────────────────────────┤
│  Layer 3: 会话检索 (session_search + FTS5)   │  ← 历史不丢
├─────────────────────────────────────────────�
│  Layer 4: 增量写入门控 (Nudge 机制)           │  ← 该记就记
├─────────────────────────────────────────────�
│  Layer 5: 原子性保障 (fcntl + 临时文件)       │  ← 不丢不坏
└─────────────────────────────────────────────┘

每一层解决一个独立问题，层与层之间不耦合。下面逐层拆解。

为什么要写这篇？

最近在给 Hermes-lite 接入 Gemini 3.x 模型时，踩了不少 google-genai SDK 的坑——尤其是多轮 tool call 时 thought_signature 丢失导致 400、streaming 模式下 function_call args 是片段、response.text 莫名其妙打 stderr Warning 等问题。

查了一圈官方文档和社区资料，发现这些坑分散在各处，所以整理了一篇一站式指南，把从安装到上线的完整路径、所有踩坑点都写清楚。

一、SDK 概览

包名：google-genai（PyPI） 仓库：googleapis/python-genai 当前版本：v2.10.0（2026-06-24） Python：3.9+ License：Apache-2.0

google-genai 统一封装了两条后端：

• Gemini Developer API：api_key 认证，适合快速开发
• Vertex AI：project + location，gcloud ADC 认证，VPC 上最方便

通过 Client 的一个接口切换，代码几乎零改动。

二、Google Cloud VPS 上全流程配置

2.1 环境准备

# 创建 venv（推荐 Python 3.12+）
python3 -m venv /opt/genai-env
source /opt/genai-env/bin/activate

# 安装 SDK
pip install google-genai

# 验证
python3 -c "from google import genai; print('OK', google.genai.__version__)"

2.2 认证：Vertex AI 模式（gcloud ADC）

VPC 上最方便——Application Default Credentials，无需手动管理密钥。

上一篇文章介绍了 Hermes-lite 的整体裁剪思路。这篇深入每一类实际踩过的坑， 把"为什么会遇到"和"怎么解"都说清楚。

一、路径迁移坑

从 .hermes/ 迁到 .hermes-lite/ 后，不是只改 HERMES_HOME 就完事。

踩到的点

• .skills_prompt_snapshot.json 里残留旧 .hermes/ 路径
• web_search/SKILL.md 硬编码了旧路径
• 技能、工具、memory、config、sessions、workspace 各自缓存旧路径
• systemd 环境变量、进程环境、配置文件、技能正文需要一起排查

经验

1. 迁移后 grep 全目录旧路径：

grep -r "\.hermes/" /home/user/.hermes-lite/ --include="*.json" --include="*.md" --include="*.yaml" -l

2. 技能快照要清理重建，不能复用旧缓存
3. systemd 重启不是可选项 — 长进程内缓存会保留旧状态

systemctl restart hermes-lite
systemctl status hermes-lite  # 确认新 PID

二、技能裁剪坑

一开始容易只看磁盘上有多少 SKILL.md，但真正可用数量要看运行时过滤后的结果。

踩到的点

• 磁盘上 67 个 SKILL.md，实际 gateway/slash 可见 65 个
• kanban-orchestrator/worker 因为 environments: [kanban] 被过滤，这是预期不是坏了
• _find_all_skills(skip_disabled=True) 这个参数名容易误读，实际是返回全部技能，默认才过滤 disabled
• web_search 技能存在，但 Tavily key 缺失，会变成"看得到但用不了"

经验

判断技能可用性要看三层：

为什么要裁剪

完整版 Hermes Agent（Nous Research）功能丰富：多平台网关、浏览器自动化、语音 TTS/STT、多 Agent 协作、Kanban 看板等。但这些功能对资源要求不低——在我的测试里，完整配置更适合至少 2GB 内存的机器。

我有一台 GCP e2-micro（2 vCPU / 954MB RAM），想用它跑一个 24/7 在线的 AI Agent 接入飞书。完整版装不下，于是有了这个裁剪实践。

三阶段渐进式裁剪

裁剪不是一步完成的，而是三阶段递进：

第一阶段：本地 Codex 完成初期核心裁剪

在本地电脑上，利用 Codex（OpenAI） 作为辅助分析工具，对完整版 Hermes 进行全面"解剖"：

• 逐一扫描 ~/.hermes/ 目录结构，识别每个模块的职责
• 分析 67 个技能的依赖关系，标记哪些是核心链路的、哪些是边缘功能
• 梳理 config.yaml 中每个配置项的实际作用，搞清楚"关掉会怎样"
• 输出一份裁剪清单：哪些 toolset 可以禁、哪些 skill 可以删、哪些配置可以收紧

这一阶段的核心价值：把"能不能关"这个判断做对。Codex 帮助理解了代码间的依赖关系，避免直接关某个功能导致连锁崩溃。

第二阶段：大 VPS 上跑完整版 + 压测验证

在一台大内存 VPS 上安装完整版 Hermes，作为"对照基准"：

• 记录完整版的实际内存占用（idle / 高负载两种状态）
• 逐个关闭非核心功能，观察内存变化和稳定性
• 跑压测：模拟长时间运行、多轮对话、工具调用密集场景
• 确认裁剪后系统在资源充足环境下依然稳定

这一阶段的目的：建立性能基线 + 验证裁剪组合的安全性。在大 VPS 上翻车无所谓，在小 VPS 上翻车就是服务宕机。

什么是静态网站生成器？

在深入探讨具体框架之前，我们首先需要理解什么是“静态网站生成器”（Static Site Generator, SSG）。

传统的动态网站（如 WordPress）在每次用户访问时，都需要后端服务器从数据库查询数据，然后通过模板引擎实时渲染成 HTML 页面返回给用户。这个过程涉及数据库、服务器端语言（如 PHP），相对复杂且速度较慢。

而静态网站则完全不同。它遵循一个简单的哲学：提前生成所有页面。

工作流程如下：

1. 编写内容：你使用简单的 Markdown 格式编写文章。
2. 构建网站：运行一个命令，SSG 会读取你所有的 Markdown 文件、应用你选择的模板主题。
3. 生成成品：最终输出一整个文件夹的、纯粹的 HTML、CSS 和 JavaScript 文件。
4. 部署：你只需要将这个文件夹部署到任何一个可以托管静态文件的地方（如 GitHub Pages、Nginx 服务器、对象存储等），你的网站就上线了。

静态网站的优势显而易见：

• 极速（Fast）: 用户访问的是预先生成好的 HTML 文件，无需任何服务器端处理，加载速度极快。
• 安全（Secure）: 没有数据库，没有复杂的后端逻辑，大大减少了被攻击的风险。
• 简单（Simple）: 部署和迁移都非常方便，只需要复制文件即可。版本控制也极其容易（可以直接用 Git）。
• 便宜（Cheap）: 托管静态文件的成本极低，甚至有大量免费的平台（如 GitHub Pages, Netlify, Vercel）。

正是因为这些优势，静态博客在全球技术社区中蔚然成风。

主流框架概览：群星璀璨

SSG 领域有很多优秀的选择，每个都有自己的特点和技术栈：

• Hugo: 基于 Go 语言，以“快”闻名于世。
• Jekyll: 基于 Ruby 语言，是 SSG 的鼻祖，与 GitHub Pages 深度集成。
• Hexo: 基于 Node.js，在亚洲尤其流行，插件生态丰富。
• Gatsby / Next.js: 基于 React (JavaScript)，功能强大，更像是一个“网站应用”的构建框架，而不仅仅是博客。对于简单的个人博客来说可能有些“杀鸡用牛刀”。

深入Hugo的世界：为何选择它？

在众多框架中，Hugo 脱颖而出，成为越来越多人的首选。它的核心优势可以总结为以下几点：

这篇 SOP 记录当前博客的真实发布流程。早期我曾经用过 public 子模块和部署仓库分离的方案，但当前仓库已经改成更简单的方式：Markdown 源码、Hugo 模板和 GitHub Actions workflow 都在 caozuohua.github.io 仓库内，push 到 main 后由 Actions 构建并部署 GitHub Pages。

当前仓库结构

caozuohua.github.io/
├── content/posts/        # Markdown 文章源码
├── layouts/              # 站点模板覆盖
├── themes/ananke/        # Hugo 主题
├── hugo.toml             # 站点配置
└── .github/workflows/    # GitHub Pages 部署流程

当前生产地址是 https://caozuohua.github.io/。本地构建产物会生成到 public/，但它只是验证结果，不再作为单独部署仓库提交。

第一阶段：内容创作

新文章统一放在 content/posts/ 下。推荐使用 page bundle 结构：

hugo new content/posts/YYYY-MM-DD-kebab-case-slug/index.md

Front matter 至少包含：

---
title: "文章标题"
date: 2026-06-30
publishDate: 2026-06-30
description: "一句话 SEO 摘要"
tags: ["标签1", "标签2"]
categories: ["分类"]
draft: false
---

写作完成后先做三项检查：

问题起源：一次失败的博客发布

一切始于一个简单的 blog_publish 命令，但它却意外地失败了。以此为起点，我们开始了一次深入的、涉及 DevOps、Git 和 Hugo 多个方面的技术探险。

探险之旅：层层剥茧

第一层：源码与成品的混淆

我最初的诊断发现，本地仓库 /var/www/blog 关联的远程仓库 caozuohua/caozuohua.github.io 存放的并非我们预期的 Markdown 源码，而是 Hugo 构建后的 HTML 静态文件。这是所有问题的根源。

解决方案：我们决定采用“双仓库”策略。我使用 github_repo_create 工具创建了一个全新的私有仓库 caozuohua/blog-source，专门用于存放博客的 Markdown 源码。

第二层：权限的迷宫

当我尝试将本地仓库指向这个新的 blog-source 仓库时，遭遇了 Permission denied 错误。这意味着我（luckclaw 用户）没有操作 /var/www/blog 目录的权限。

解决方案：您作为管理员，果断出手，通过 chown 命令将目录所有权授予了我，为我扫清了障碍。

第三层：消失的 Hugo 与特殊的版本

解决了权限问题后，我们发现系统上根本没有安装 Hugo。而直接安装并不能解决问题，因为您的 Ananke 主题需要一个非常特殊的 Hugo 版本。

解决方案：

1. 您从 PyPI 找到了一个 0.161.1 的特殊版本。
2. 我通过 wget, tar, mv 等一系列 run_shell 操作，成功将这个特殊版本的 Hugo 安装到了我的个人 bin 目录中。

第四层：主题模板的兼容性危机

即便版本正确，构建依然失败。错误指向了主题模板中的语言字段兼容性问题。需要注意：Hugo 版本变化后，languageCode / .Site.LanguageCode 与 locale / .Site.Language.Locale 的推荐方向会变，不能机械照抄旧修复。

当前 AI 助手在复杂场景下暴露出的种种局限，促使我们思考：如何让 Agent 从"工具调用者"进化为"自适应系统"？

痛点全景

1. 工具编排僵化

大部分 Agent 的工具列表在启动时就固定了。面对"下载一个 ZIP 并提取其中 CSV 做分析"这种需要多步骤组合的任务，它无法临时组合出解压→解析→汇总的新流水线，只能止步于"我有 run_shell 但没有 unzip 工具"。

2. 跨会话无记忆

每次对话结束，Agent 的"记忆"归零。上次犯的错、用户的偏好、环境配置——全部遗忘。下次对话从头来，效率极低。

3. 单 Agent 能力天花板

一个 Agent 同时负责信息收集、决策判断、代码执行、结果格式化——角色过载导致质量下降。缺少分工协作机制。

进化方向

从"固定工具"到"动态进化"

Agent 应该能在运行时识别能力缺口，自主编写并注册新工具。这不是插件系统，而是自我扩展。

从"无状态"到"持久记忆"

需要跨会话保留的三层记忆：

• 用户层：偏好、沟通风格、项目上下文
• 环境层：系统配置、工具路径、API 端点
• 经验层：踩过的坑、解决方案、最佳实践

从"单兵"到"协作"

主 Agent 负责决策，子 Agent 各司其职：搜索 Agent、编码 Agent、验证 Agent。通过明确的接口契约协作。

实践起点

本系列接下来的三篇日记，将分别深入主控制器调度、动态工具创建、持久化记忆系统三个方向，拆解具体实现方案。

进化不是加功能，是改范式。

Agent 没有记忆，就是"金鱼脑"——每次对话从头开始，重复犯错、忘记偏好。持久化记忆系统要解决的是：跨会话保留什么、怎么存、怎么取。

记忆分层

第一层：身份记忆（User Profile）

永久不变或极少变的信息：

• 用户姓名、时区、语言偏好
• 项目路径、技术栈、常用工具
• 沟通风格偏好（简洁/详细、中文/英文）

存储方式：纯文本文件，每轮注入系统提示。

第二层：经验记忆（Lessons Learned）

踩过的坑和解决方案：

• “NewAPI Groq 70B 只有 8K 上下文，不适合做压缩”
• “Hugo 0.161.1 需要覆盖 baseof.html 修复 locale 问题”
• “Hermes-lite 的 memory 上限 2200 字，要 replace 而非 add”

存储方式：结构化条目，带时间戳和标签。

第三层：会话上下文（Session State）

当前对话的实时状态：

• 最近 10 轮对话
• 当前任务进度
• 待办事项

存储方式：对话历史 buffer，压缩后丢弃细节。

存储方案对比

实际实现：文件 + 索引

对于单 VPS 个人 Agent，最实用的是文件 + 索引方案：