LightOps

LightOps 是一个基于 Rust 的极轻量探针式运维面板。它只需要部署一个主控端 Server，每台被管理 Linux 主机只安装一个轻量 Agent。Agent 主动通过 WebSocket 连接 Server，因此被管理节点不需要暴露 Web 面板，也不需要本地数据库。

架构

浏览器 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。

目录结构

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 主机。

一条命令安装 Server

推荐生产环境使用“发布包安装”。目标服务器只需要下载发布包、解压并注册 systemd 服务，不需要安装 Rust、Node.js，也不需要现场编译。

自动发布 Release

仓库已内置 Gitea Actions 工作流：推送 v* 标签后，Linux runner 会自动构建 x86_64-unknown-linux-gnu 发布包，并上传到 Gitea Release。

首次使用前，在 Gitea 仓库设置中添加 Actions Secret：

GITEA_TOKEN=<具备当前仓库 Release 写入权限的访问令牌>

发布新版本：

git tag -a v0.1.0 -m "LightOps v0.1.0"
git push origin v0.1.0

如果不使用 Gitea Actions，也可以在任意构建机手动构建并上传：

bash scripts/build-release.sh --version 0.1.0 --target x86_64-unknown-linux-gnu
GITEA_TOKEN=<token> bash scripts/publish-gitea-release.sh --tag v0.1.0 --package target/releases/lightops-0.1.0-x86_64-unknown-linux-gnu.tar.gz --package target/releases/lightops-0.1.0-x86_64-unknown-linux-gnu.tar.gz.sha256

Windows PowerShell 手动上传：

$env:GITEA_TOKEN="<token>"
pwsh -File scripts\publish-gitea-release.ps1 -Tag v0.1.0 -Package target\releases\lightops-0.1.0-x86_64-pc-windows-gnu.zip,target\releases\lightops-0.1.0-x86_64-pc-windows-gnu.zip.sha256

先在构建机或 CI 上生成发布包：

bash scripts/build-release.sh --target x86_64-unknown-linux-gnu

生成的文件在 target/releases/，把 lightops-*.tar.gz 上传到 Gitea Release、对象存储或任意可访问的下载地址。然后在目标 Linux 服务器上执行：

curl -fsSL https://gitea.kmux.cn/Eeveid/lightOps/raw/branch/main/scripts/install-server-release.sh | bash -s -- --url https://example.com/lightops.tar.gz

如果同时提供 SHA256：

curl -fsSL https://gitea.kmux.cn/Eeveid/lightOps/raw/branch/main/scripts/install-server-release.sh | bash -s -- --url https://example.com/lightops.tar.gz --sha256 <sha256>

发布包安装脚本会随机选择未占用端口，生成随机管理员账号和密码，并输出内网地址、本机地址、公网地址、端口、用户名和密码。首次凭据会保存到 /etc/lightops/initial-admin.txt。

源码安装适合开发环境或没有发布包时使用，会在目标服务器现场安装 Rust、Node.js 并编译。

在目标 Linux 服务器上使用 root 执行：

curl -fsSL https://gitea.kmux.cn/Eeveid/lightOps/raw/branch/main/scripts/install-server.sh | bash

指定面板访问地址：

curl -fsSL https://gitea.kmux.cn/Eeveid/lightOps/raw/branch/main/scripts/install-server.sh | bash -s -- --public-url https://panel.example.com

安装脚本会自动安装基础依赖、Rust、Node.js，随机选择未占用端口，拉取远程仓库，构建前端和 Rust 二进制，写入 /etc/lightops/server.toml，注册并启动 lightops-server systemd 服务。首次安装会自动生成随机管理员账号和密码，并在安装完成后输出内网地址、本机地址、公网地址、端口、用户名和密码。首次凭据会保存到 /etc/lightops/initial-admin.txt，请登录面板后立即修改密码。

常用参数：

--repo <url>          Git 仓库地址
--branch <name>       Git 分支，默认 main
--install-dir <path>  安装目录，默认 /opt/lightops
--bind <addr>         监听地址，默认随机选择未占用端口
--public-url <url>    面板外部访问地址
--skip-deps           跳过依赖安装检查

构建前端：

cd web
npm install
npm run build

运行 Server：

cp config/server.toml.example config/server.toml
cargo run -p lightops-server -- --config config/server.toml

本地运行 Agent：

cargo run -p lightops-agent -- --server http://127.0.0.1:8080 --token <registration-token>

如果希望页面生成的一键安装命令能自动下载 Agent 二进制文件，请把构建好的 Agent 放到 Server 静态目录，例如：

web/dist/downloads/lightops-agent-linux-x86_64

主机列表和单机详情会展示 Agent 版本状态，落后版本可复制升级命令。安装/升级脚本支持 --sha256 校验下载的 Agent 二进制。

安装 Agent：

curl -fsSL https://panel.example.com/install-agent.sh | sh -s -- --server https://panel.example.com --token <registration-token>

升级 Agent：

curl -fsSL https://panel.example.com/upgrade-agent.sh | sh -s -- --server https://panel.example.com

卸载 Agent：

curl -fsSL https://panel.example.com/uninstall-agent.sh | sh

在线更新要求 Server 运行目录是 Git 仓库，例如 /opt/lightops，并在设置页保持：

仓库目录：/opt/lightops
更新分支：main
更新脚本：scripts/update-from-git.sh

当你从 Windows、macOS 或 Linux 任意客户端向远程仓库 push 新代码后，在设置页点击“检查更新”，确认有远程提交后点击“立即更新并重启”。提交端不需要安装触发脚本，也不参与部署；服务器会执行 scripts/update-from-git.sh，更新日志默认写入 /var/log/lightops/update.log。

完全清理 Agent 配置：

curl -fsSL https://panel.example.com/uninstall-agent.sh | sh -s -- --purge

打开初始化页面：

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 接口。