1pm · 1Panel 多机网关
1Panel 社区版虽然好用，但存在一个长期痛点：多机管理是专业版 / 企业版的专属功能。如果你有多台机器（如家庭 NAS、机房 VPS），每台都需要记住独立端口并打开新标签页，切换体验非常繁琐；而仅为了“统一入口”购买许可证又显得性价比极低。
因此开发了 1pm。其目标非常明确：
由一台 Master 节点作为统一入口，多台 Agent 节点在后端通过反向隧道连接；浏览器只需访问一个入口，即可在侧栏一键切换不同面板。
Note
本项目与 1Panel / FIT2CLOUD 无官方关联。本项目基于 MIT 协议开源，属于社区驱动的独立实现。请勿将其与官方「节点管理」的完整产品能力进行对标。
核心解决的问题
官方节点管理采用主节点 入站 连接子节点的模式（依赖 SSH + Agent 端口）。然而，对于位于 NAT 或防火墙后的家庭宽带、公司内网机器，主节点往往无法直接建立连接。
1pm 采用了相反的思路：Agent 主动出站连接 Master。通信基于 WebSocket + smux 多路复用技术，逻辑与 FRP 类似。只要子机能访问 Master 的面板端口即可，无需为子机开放入站端口。
适合谁
- 坚持使用社区版，不愿购买专业版
- 子机位于 NAT / 防火墙之后
- 仅需「统一入口 + 面板切换」功能
- 能接受轻量级方案：单个二进制文件 + systemd 服务
不适合谁
- 需要配置同步、文件互传、节点分组等功能
- 需要完整的监控体系、批量更新、数据库集群支持
- 需要官方深度集成的企业级运维平台
与官方节点管理的对比
| 特性 | 1pm | 官方节点管理 |
|---|---|---|
| 授权模式 | MIT，社区版可用 | 专业版 / 企业版 |
| 连接方向 | Agent 出站 连接 Master | 主节点 入站 连接子节点 |
| NAT / 家庭宽带 | 友好，无需公网 IP | 主节点需能 SSH 到子机 |
| 安装方式 | Master 一键脚本；Agent 复制签名命令 | 面板内填写 SSH 信息添加节点 |
| 面板切换 | Cookie 选节点 + 根路径反代 | 原生节点切换界面 |
| 资源监控 | CPU / 内存 / 版本轮询 | 完整监控指标 |
| 配置同步 / 文件互传 / 分组 | ❌ | ✅ |
| 部署复杂度 | 单一二进制文件 | 官方完整产品套件 |
一句话总结：官方提供的是「多机运维平台」；1pm 提供的是「统一入口切面板」，尤其适用于子机处于网络限制场景的情况。
界面预览
管理页面位于 /__mp/：展示在线 Agent 列表、签名安装命令、CPU / 内存 / 版本概况。
侧栏底部会注入节点切换组件：支持在主节点 / 子节点间一键切换，也可进入「管理节点…」界面。
架构原理
Master 启动时会执行一项关键操作：接管本机 1Panel 原有的公网端口。它将真实的面板服务迁移至内部端口，对外仍保留熟悉的入口地址。浏览器认为自己正在访问 1Panel，实际上请求先经过 1pm 处理。
Master
负责占用原端口、身份鉴权、节点注册、根路径反代及侧栏脚本注入。
Agent
负责出站注册、探测本机面板、自动登录认证及采集主机状态。
协议
单条 WebSocket 不足以承载多路 HTTP 流量；上层叠加 smux 多路复用，由 Master 主动 OpenStream。
关键设计选择
- 根路径反代，不使用路径前缀：1Panel 前端大量使用绝对路径（如
/assets/...），若使用前缀反代会导致资源加载失败。本方案通过mp_nodeCookie 选择节点，使绝对路径正常工作。 - 会话分边持有：切换到子节点时，本机
psession暂存于 Master 内存；隧道中不转发面板 Cookie，由 Agent 自行登录后通过Set-Cookie覆盖浏览器 Cookie。Master 不存储子机密码。 - 不读取 core.db：端口、用户、版本等信息一律通过
1panel/1pctlCLI 获取，避免跨版本 SQLite 兼容性问题。 - 同机禁止双角色：Takeover 和 Agent 会争夺同一面板端口，二者互斥，同一台机器只能安装其中一种角色。
核心能力
端口接管
Master 读取当前面板端口，将其迁移至 原端口 + 10000，自身监听原端口。卸载时尝试恢复原配置。
HMAC 安装命令
管理页生成的 curl | bash 命令包含 timestamp + sign 签名，有效期约 5 分钟；每次复制都会重新签发。
一键进子机面板
切换时暂存本机会话 → Agent 自动登录 → 覆盖浏览器 Cookie；切回时从 Master 内存恢复会话。
侧栏注入
对本机 HTML 注入节点切换 Hook，通过轮询 /__mp/api/agents 获取列表，选中节点后整页跳转（规避 Vue SPA 路由问题）。
快速上手
Note
环境要求：Linux（systemd）、amd64 / arm64 架构；本机已安装并初始化 1Panel；Master 与 Agent 各占一台机器。
安装 Master
推荐通过 Release 附件下载（经代理），避免使用 jsDelivr 的
@main分支——它可能会永久缓存首次内容：curl -fsSL https://gh-proxy.com/https://github.com/AnkioTomas/1panel-agent/releases/latest/download/install.sh | sudo bash打开管理页
首先登录 本机 1Panel（安全入口照常），然后访问：
http://<master>:<面板端口>/__mp/或通过侧栏点击「管理节点…」。
安装 Agent
在管理页点击「复制命令」，在 另一台 机器上执行（需提供本机 1Panel 密码，用于远程自动登录）：
curl -fsSL "http://<master>:<port>/agent.sh?timestamp=...&sign=..." | sudo bash切换节点
在管理页点击「进入面板」，或在侧栏选择子节点；切回主节点时选择「主节点」即可。
卸载程序可自动识别本机角色：
sudo 1pm uninstall限制与注意事项
Warning
- 非官方专业版替代品：不支持配置同步、文件互传、批量升级、节点分组。
- Takeover 操作会修改本机
ServerPort并重启1panel-core；卸载时虽会尝试恢复，但建议提前备份。 - Token 轮换后旧 Agent 将全部失效，需重新执行安装命令。
- 建议部署在可信网络或 VPN 环境中；Agent 下载与 WebSocket 通信依赖共享 Token 的 HMAC 验证。
| 场景 | 存储位置 | 说明 |
|---|---|---|
| 当前面板会话 | 浏览器 psession 等 | 本机或子节点会话 |
| 本机暂存 | Master 内存 | 切换至子节点时保存，切换回时写回；不落盘 |
| 当前节点标识 | mp_node | Agent ID；为空表示本机 |
| 管理页鉴权 | mp_auth | 内存中的 sessionSecret |
| 项 | 路径 |
|---|---|
| Master 状态 | /var/lib/1pm/master.json |
| Agent 配置 | /root/.1panel-agent/agent.json |
| Agent 密码 | AES-GCM 加密；密钥位于同目录 secret.key |
go build -o bin/1pm ./cmd/1panel-agentgo test ./...推送版本 Tag 后，GitHub Actions 会自动构建 linux/darwin × amd64/arm64 的 Release 包。