面板没有 root:我给自己写了一个 VPS 管理面板

xfmpanel v1.0.0:零依赖的轻量主机面板 —— 环境一键装、站点全生命周期、证书自动续期,而面板进程从头到尾碰不到 root

仓库:**github.com/xfm0797/xfmpanel(MIT,v1.0.0 已发布)|技术栈:Node.js 22,零第三方依赖**


一、初衷:不敢把 root 交给面板

服务器上跑着几个站点,装环境、建站、签证书这些事每月都要来一遍。市面上的方案很成熟——宝塔们把这件事做到了「一键」,但代价是:面板进程持有 root,面板被攻破的那一秒,服务器整个沦陷。

我不是说它们不安全,而是说这个模型让我睡不着觉。一个 Web 进程 + root 权限,攻击面是整台机器;而我需要的功能,其实只有四件事:

  1. 装环境(nginx / PHP / MariaDB / Redis)
  2. 建站、改站、删站
  3. 证书申请和续期
  4. 看看服务器还活着没

于是有了 xfmpanel 的第一条设计准则,写在所有代码之前:

面板进程不持有 root。所有特权操作,经由签名校验的本地 agent 执行,且 agent 只认识白名单里的操作。

「不是又一个宝塔」——是我给自己的定位:不求功能多,求权限边界清晰、可审计、可维护的最小可用实现。

二、核心设计:三层边界

整个安全模型一句话:任何一层被攻破,都不直接等于 root。

1
2
3
4
5
6
7
浏览器 ──HTTPS──> nginx ──> 面板进程(xfmpanel 用户,无 root)
│ unix socket + HMAC-SHA256 签名
▼
agent 进程(root,op 白名单)
│ execFile,永不经过 shell
▼
systemd / nginx / php-fpm / certbot / apt

几个关键点,全部实测落实:

措施 实现
特权分离 面板与 agent 仅通过 /run/xfmpanel/agent.sock 通信,socket 权限 0660 root:xfmpanel
请求签名 每请求 HMAC-SHA256 签名,±30s 时间窗 + nonce 防重放
操作白名单 agent 注册表里只登记了 21 个 op,超出的一律拒绝,每个 op 独立参数校验
命令注入防护 全部 spawn(cmd, argv),代码里不存在拼接 shell 字符串的地方
路径越界防护 站点目录必须严格等于 /www/xfm/<slug>,写入前做前缀 + realpath 复核
配置原子性 渲染 → 原子写 → nginx -t → 失败自动回滚上一版 → 才 reload
站点隔离 每站点独立系统用户(nologin)+ 独立 FPM pool + open_basedir + 禁用危险函数

这 21 个 op 就是 agent 的全部能力:system.info、system.metrics、runtime.install、service.action、site.provision、site.apply、cert.issue、cert.renew……数得过来,审得过来。

三、技术选型:零依赖是认真的

选型 理由
Node.js 22,零第三方依赖 VPS 上不用 npm install、不用编译原生模块;供应链攻击面最小化
SQLite(node:sqlite,WAL) 面板并发就几十 QPS 量级,单文件库免运维,备份即拷贝
原生 HTML/CSS/JS 前端 无构建步骤,改完刷新生效,方便二次开发和排障
任务队列落库 装环境、签证书动辄几分钟,必须异步化;重启后状态可恢复
systemd + nginx 与 VPS 运维习惯一致,不引入 Docker

零依赖不是口号,是数字:整个项目 package.json 的 dependencies 是空的,部署机上一行 npm install 都不需要。

四、进展:v1.0.0 的数字盘点

2026-11-17 打了 v1.0.0 的 tag。写这篇之前我把代码量重新量了一遍,数字如下:

项 数值
后端代码 7,631 行(panel 4,742 + agent 2,213 + shared 676)
前端代码 2,824 行(9 个视图模块,无框架无构建)
agent op 白名单 21 个
路由模块 11 个(auth / sites / certs / runtimes / tasks / logs / alerts / settings / users / system / index)
服务层模块 13 个
端到端断言 37 项(npm test)
安装脚本 709 行单文件自举(无需先克隆仓库)
第三方依赖 0

37 项端到端断言覆盖的正是最容易出事的链路:登录限流、CSRF 拒绝、环境安装、建站含自动签发、启停、证书续期、坏配置失败落 lastError、指标接口、审计、删除。开发模式内置 stub agent,Win / macOS / Linux 都能本地联调,不碰真实系统。

五、功能覆盖

网站环境:Nginx / PHP(多版本独立 FPM pool)/ MariaDB / Redis / Node.js 一键安装,基于 apt 幂等可重入,安装过程 SSE 实时输出。安装源自适应——Debian 走系统源,Ubuntu 走 ondrej/sury,不支持的发行版明确报错而不是静默失败。

站点管理:PHP、静态、反向代理三种类型;创建 / 修改 / 启停 / 删除;伪静态预设(WordPress / Laravel / ThinkPHP 等);nginx 配置在线预览且预览与落盘同源;域名冲突检测。

SSL 证书:Let’s Encrypt 自动申请(HTTP-01 webroot,不停服务)、自动续期、到期巡检告警、商业证书手动上传、吊销。

监控与日志:首页 CPU / 内存 / 磁盘 / 网络四张实时曲线——agent 侧每秒采样,面板 15 分钟环形缓冲,不落库(监控数据不值得持久化);站点 access / error / php-error 日志按行数尾部读取;任务实时日志 SSE 带断线续传。

告警中心:证书临期 / 过期、站点配置失败、agent 离线、任务失败统一进入告警,按 dedupe key 去重,可逐条确认。

六、踩过的坑

写这类「和系统打交道」的项目,坑和纯 Web 项目完全不同:

  • Windows 下开发、Linux 上运行,路径和权限语义差一层,所以 shared 层专门做了路径校验与配置渲染器,两端共用同一份逻辑;
  • 坏配置回滚是最花时间的一块——nginx vhost 写坏了不能 reload,必须 nginx -t 先验,失败回滚上一版,这套流程现在跑在 site.apply 的固定序列里;
  • node:sqlite 在 Node 22 还是 experimental,API 本身稳定,systemd 单元里关掉了警告,等它转正就行;
  • 审计日志不能是可选的——面板所有写操作落审计表,这在第一天就定死了,后来加功能时确实救过我几次排查。

七、已知限制与下一步

诚实地说清楚边界:

  • 自动安装仅覆盖 Debian 12 / Ubuntu 22.04+,RHEL 系会明确报错;
  • 单机面板,不做集群、不做多节点编排——那是另一类产品的事。

下一步想做的两件事:计划任务(cron 管理 + 备份策略)和防火墙端口管理(仍走 op 白名单,不开放任意 iptables)。原则不变:每加一个能力,先问「它值得换 agent 注册表里多一行吗」。

仓库在这里,欢迎 star / issue / PR:**github.com/xfm0797/xfmpanel**