实现 LightOps 运维面板基础功能

2026-05-25 01:13:03 +08:00
commit d3bb9f45a6
84 changed files with 23505 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,153 @@
+# LightOps
+
+LightOps 是一个基于 Rust 的极轻量探针式运维面板。它只需要部署一个主控端 Server，每台被管理 Linux 主机只安装一个轻量 Agent。Agent 主动通过 WebSocket 连接 Server，因此被管理节点不需要暴露 Web 面板，也不需要本地数据库。
+
+## 架构
+
+```text
+浏览器 Web 界面
+  -> Axum Server REST/WS
+  -> SQLite + 内存连接注册表
+  -> Agent WebSocket
+  -> 本机能力：文件、PTY 终端、systemd、Nginx、Docker、日志、应用发现
+```
+
+核心设计：
+
+- Server：使用 Axum、Tokio、SQLx SQLite，负责 JWT 认证、注册 Token、任务调度、审计日志和静态 Web 托管。
+- Agent：Rust 守护进程，不提供 Web UI，不使用本地数据库，支持断线重连、30 秒心跳/指标上报和白名单任务执行。
+- 协议：共享协议类型放在 `lightops-common`，通过 serde JSON 序列化。
+- 前端：Svelte + Vite + TypeScript，使用轻量 CSS，终端使用 xterm.js。
+
+## 目录结构
+
+```text
+lightops/
+├── crates/
+│   ├── lightops-server/
+│   ├── lightops-agent/
+│   ├── lightops-common/
+│   └── lightops-cli/
+├── web/
+├── scripts/
+├── deploy/
+├── migrations/
+├── docs/
+└── README.md
+```
+
+## 已实现的 MVP
+
+- 管理员初始化和登录，密码使用 Argon2 哈希，接口使用 JWT 鉴权。
+- 权限支持模块级和动作级授权；已有模块级权限继续兼容，动作级权限可细分到文件读取/写入/危险操作、Docker 查看/变更/危险操作、Nginx 查看/修改/危险操作等。
+- 一次性 Agent 注册 Token。
+- Agent WebSocket 注册、长期 Secret、断线重连、协议级 Ping/Pong、静默超时检测、重复连接替换保护、心跳和指标上报。
+- 主机列表和最新 CPU/内存/磁盘指标。
+- 通用 `task.request` / `task.response` 任务下发和超时控制。
+- 文件列表、读取、写入、新建目录、删除、递归删除、重命名、chmod，以及大文件分片上传/下载。
+- 浏览器 xterm.js 到 Server WebSocket，再到 Agent PTY 的远程终端链路。
+- systemd 服务列表、启动、停止和重启。
+- Nginx 状态、站点列表、新建静态/SPA/反代/负载均衡/PHP-FastCGI 站点、配置在线编辑、启用、禁用、测试和重载，带备份列表与一键恢复；反代模板支持 WebSocket、gzip、静态资源缓存、强制 HTTPS 和上传大小限制。
+- 免费 HTTPS 证书管理：通过 certbot 申请/续期证书，展示证书到期时间，并支持启用自动续期。优先使用系统 `certbot.timer`，缺失时创建 `lightops-certbot-renew.timer`。证书 30 天内到期会联动告警中心。
+- Docker 状态、容器/镜像/数据卷列表、拉取镜像、从镜像创建容器、容器详情/资源占用、容器 exec 终端和基础生命周期管理，当前通过 `DockerCliProvider` 实现。
+- Docker Compose 项目识别、启动、停止、重启、日志查看和 YAML 部署，基于容器 `com.docker.compose.project` 标签聚合，不强依赖 compose 文件路径。
+- 软件商店：支持 `store/catalog/*.toml` 配置化应用目录，默认提供 Alist、Uptime Kuma、Gitea、Redis、Nginx 示例站；应用模板可声明安装参数字段，并在 Compose 模板中使用 `{{field.xxx}}` 替换，敏感字段会在安装记录和审计日志中脱敏；基于 Docker Compose 一键部署到指定 Agent，安装前会检测 Docker/Compose、端口占用、项目名冲突和目录风险；安装后支持启动、停止、重启、查看日志、拉取镜像更新和卸载 Compose 项目，默认不删除数据目录，并会刷新应用管理缓存。
+- 任务历史页面，可查看任务动作、状态、参数摘要、结果和错误。
+- 任务中心增强：提供任务统计、任务详情、自动刷新、失败重试和运行中任务取消；支持任务事件日志，记录任务创建、下发、Agent 执行、stdout/stderr 摘要、失败原因和完成状态；普通用户只能查看自己授权主机的任务。
+- 应用管理：应用发现、应用列表、应用详情、systemd/Docker 应用启停重启、应用日志、手动和自动应用健康检查、文件级应用备份、Nginx 站点应用、APT 允许清单识别和自定义应用纳管。
+- 单机详情补强：支持查看 Agent 实时系统快照，包括高占用进程、监听端口、磁盘分区和网络接口。
+- 告警中心支持 CPU、内存、磁盘、SSL 到期和应用健康规则，支持按主机、状态、级别筛选；支持规则静默、恢复通知、Webhook 测试发送和通知投递历史。
+- 主控端 SQLite 备份/恢复：支持在线创建一致性备份、下载备份、删除备份和从备份恢复；恢复后服务会退出并由 systemd 重启。
+- 主控端在线更新：设置页支持检查 Git 远程分支更新，并可一键触发服务器本机更新脚本，自动拉取代码、构建前端和 Rust 二进制、替换程序并重启 systemd 服务。
+- 审计日志 API 和页面。
+
+## 开发
+
+前置要求：
+
+- Rust 稳定版工具链。
+- Node.js 20 或更高版本。
+- Agent 运行能力优先面向 Linux 主机。
+
+构建前端：
+
+```bash
+cd web
+npm install
+npm run build
+```
+
+运行 Server：
+
+```bash
+cp config/server.toml.example config/server.toml
+cargo run -p lightops-server -- --config config/server.toml
+```
+
+本地运行 Agent：
+
+```bash
+cargo run -p lightops-agent -- --server http://127.0.0.1:8080 --token <registration-token>
+```
+
+如果希望页面生成的一键安装命令能自动下载 Agent 二进制文件，请把构建好的 Agent 放到 Server 静态目录，例如：
+
+```text
+web/dist/downloads/lightops-agent-linux-x86_64
+```
+
+主机列表和单机详情会展示 Agent 版本状态，落后版本可复制升级命令。安装/升级脚本支持 `--sha256` 校验下载的 Agent 二进制。
+
+安装 Agent：
+
+```bash
+curl -fsSL https://panel.example.com/install-agent.sh | sh -s -- --server https://panel.example.com --token <registration-token>
+```
+
+升级 Agent：
+
+```bash
+curl -fsSL https://panel.example.com/upgrade-agent.sh | sh -s -- --server https://panel.example.com
+```
+
+卸载 Agent：
+
+```bash
+curl -fsSL https://panel.example.com/uninstall-agent.sh | sh
+```
+
+在线更新要求 Server 运行目录是 Git 仓库，例如 `/opt/lightops`，并在设置页保持：
+
+```text
+仓库目录：/opt/lightops
+更新分支：main
+更新脚本：scripts/update-from-git.sh
+```
+
+当你从 Windows、macOS 或 Linux 任意客户端向远程仓库 push 新代码后，在设置页点击“检查更新”，确认有远程提交后点击“立即更新并重启”。提交端不需要安装触发脚本，也不参与部署；服务器会执行 `scripts/update-from-git.sh`，更新日志默认写入 `/var/log/lightops/update.log`。
+
+完全清理 Agent 配置：
+
+```bash
+curl -fsSL https://panel.example.com/uninstall-agent.sh | sh -s -- --purge
+```
+
+打开初始化页面：
+
+```text
+http://127.0.0.1:8080/init
+```
+
+## 生产部署注意事项
+
+- 生产环境建议将 Server 放在 Caddy、Nginx 或其他 TLS 反向代理后，只暴露 HTTPS/WSS。
+- 反向代理需要关闭过短的 WebSocket 空闲超时，建议不低于 120 秒。
+- Agent 连接具备 30 秒心跳、30 秒 Server Ping、约 100 秒静默超时和退避重连；如果链路中间设备强制断开，Agent 会自动重连。
+- 请将 `jwt_secret` 替换为足够长的随机值。
+- SQLite 数据库需要放在持久化存储上，并定期备份。
+- 主控备份默认保存在 SQLite 数据库同级目录的 `backups/` 子目录；恢复前会额外生成 `pre-restore-*.db` 回滚副本。
+- Agent 通常需要 root 权限，才能管理 systemd、Nginx、Docker 和完整文件系统。
+- SSL 证书功能依赖被控主机已安装 `certbot` 和对应 Nginx 插件；自动续期会定期执行 `certbot renew`，证书变更后尝试重载 Nginx。
+- Webhook 告警通知依赖 Server 运行环境存在 `curl` 命令。
+- Docker 控制权限风险很高，基本等价于 root 权限，请只在可信主机上部署 Agent。
+- 生产环境不要在无 TLS 的情况下暴露 Agent WebSocket 接口。