Agent 是什么
一句话总结
Press 派到每台 VPS 上的常驻工人。Press 下指令（“创建站点”、“更新 nginx”、“构建镜像”），Agent 在机器上执行，执行完汇报结果。
🤔 为什么会有它 / 解决了什么问题
Press 需要管理多台 VPS（n、f、m），每台要做不同的事：n 更新 nginx 路由，f 跑 bench 容器，m 管理数据库。没有 Agent，Press 只能 SSH 到每台机器手动操作——一台两台还行，十台百台不可能。
Agent 让 Press 可以通过推送 Job 的方式远程操控任意数量的 VPS。Press 不用知道每台机器的具体 SSH 方式，只需要知道”这台机器上有个 Agent 在监听，把 Job 扔给它就行”。
🔍 具体原理 / 运作逻辑
Agent 启动后通过 WebSocket 连接到 Press（press_url）。连接建立后：
- Agent 告诉 Press：“我在线，我叫 f1，我能做这些事”
- Press 创建 Agent Job（如 “New Site”、“Add Site to Upstream”），放到队列
- Agent 拉取分配给自己的 Job，逐步执行（每个 step 完成后汇报状态）
- Job 全部成功 → Press 更新记录状态为 Active
Agent 本身是一个 Python 程序，通过 supervisor 管理。每台 VPS 上跑一个 Agent 进程。
更硬核的技术细节（点击展开）
Agent 和 Press 之间是 WebSocket 长连接（不是轮询）。Press 通过 HMAC 签名验证 Agent 身份（
agent_password）。我们 fork 了frappe/agent到miao-Q777/agent，包含 6 个永久修复（详见 维护）。Agent 的 nginx.conf 是 Agent 自己生成的——它既是 nginx 后面的应用，也管理着 nginx 配置。
🧭 什么情况下会用到 / 什么场景会遇到它
- Press UI 创建新站点 → Press 生成 Agent Job “New Site” → Agent 在 f 上建站
- 站点建完后 → Press 生成 Agent Job “Add Site to Upstream” → Agent 在 n 上更新 nginx
- Build 镜像时 → Agent 在 f 上 docker build + 推送到 Registry
- 查 Agent 在线状态 →
ping_agent()返回 pong
⚖️ 副作用 / 代价 / 取舍
- Agent 是单点依赖——如果 Agent 挂了，那台机器上的所有 Press 操作都卡住（Undelivered Job）
- Agent 的
press_url写死frappecloud.com默认值，不传就连接失败 - Agent nginx 的
server_name只包含机器自己的名字，n+f 合并时要手动加 - 上游
frappe/agent的 bug（如proxy.py缺@step装饰器）需要 fork 修复
🕰️ 来历
- Frappe 团队为 Frappe Cloud 开发的内部组件
- GitHub 上开源（
frappe/agent，MIT 协议） - 我们 fork 到
miao-Q777/agent（develop 分支），加了 6 个永久修复
🔗 关联 / 经常一起出现的概念
- Ansible：Agent 是”住房子的人”，Ansible 是”装修队”。Ansible 先把机器装好（装 Docker、装 Agent），Agent 才入住并开始接收指令
- Agent Job：Press 给 Agent 下的任务单。有 Pending → Running → Success/Failure 状态流转
- press_url：Agent 连接 Press 的地址。写错 → Agent 失联 → 所有 Job Undelivered
- supervisor：管理 Agent 进程的看门狗。Agent 挂了自动重启
⚠️ 注意事项 / 常见误区
- Agent 和 Ansible 容易搞混：Ansible 是配机器的（一次性），Agent 是跑任务的（常驻）
- n+f 合并架构下，一台机器只有一个 Agent，但 Press 以为有 n1 和 f1 两个 Agent——密码对齐和 server_name 问题是这么来的
ping_agent()返回 pong 只说明 Agent 在线，不代表所有 Job 类型都能正常执行
🕳️ 踩坑案例
当时的现象：demo1 创建后永远 Pending。Agent Job “Add Site to Upstream” 状态 Undelivered。
排查过程：看 Job 目标是 n1 → 查 Press 推送 → 发现 401 → 查 Agent 密码 → n1 和 f1 密码不一致
最后发现：n+f 合并架构，Ansible 为 n1 和 f1 各自生成随机密码。Press 推 n1 的 Job 用 n1 密码签名，但机器上 Agent 用的是 f1 密码验证 → 不匹配
这件事之后我记住了什么：n+f 合并架构下，两边的 agent_password 要手动对齐
📎 记忆锚点
Agent = 每家 VPS 派驻的管家。Press 一声令下，管家在自己管的那台机器上干活，干完汇报。
📝 更新日志
| 日期 | 改动 | 原因 |
|---|---|---|
| 2026-07-08 | 首次创建 | 名词科普 |