forked from Eeveid/lightOps
236 lines
12 KiB
Markdown
236 lines
12 KiB
Markdown
# 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 主机。
|
||
|
||
## 一条命令安装 Server
|
||
|
||
推荐生产环境使用“发布包安装”。目标服务器只需要下载发布包、解压并注册 systemd 服务，不需要安装 Rust、Node.js，也不需要现场编译。
|
||
|
||
## 自动发布 Release
|
||
|
||
仓库已内置 Gitea Actions 工作流：推送 `v*` 标签后，Linux runner 会自动构建 `x86_64-unknown-linux-gnu` 发布包，并上传到 Gitea Release。
|
||
|
||
首次使用前，在 Gitea 仓库设置中添加 Actions Secret：
|
||
|
||
```text
|
||
GITEA_TOKEN=<具备当前仓库 Release 写入权限的访问令牌>
|
||
```
|
||
|
||
发布新版本：
|
||
|
||
```bash
|
||
git tag -a v0.1.0 -m "LightOps v0.1.0"
|
||
git push origin v0.1.0
|
||
```
|
||
|
||
如果不使用 Gitea Actions，也可以在任意构建机手动构建并上传：
|
||
|
||
```bash
|
||
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 手动上传：
|
||
|
||
```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
|
||
bash scripts/build-release.sh --target x86_64-unknown-linux-gnu
|
||
```
|
||
|
||
生成的文件在 `target/releases/`，把 `lightops-*.tar.gz` 上传到 Gitea Release、对象存储或任意可访问的下载地址。然后在目标 Linux 服务器上执行：
|
||
|
||
```bash
|
||
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：
|
||
|
||
```bash
|
||
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 执行：
|
||
|
||
```bash
|
||
curl -fsSL https://gitea.kmux.cn/Eeveid/lightOps/raw/branch/main/scripts/install-server.sh | bash
|
||
```
|
||
|
||
指定面板访问地址：
|
||
|
||
```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`，请登录面板后立即修改密码。
|
||
|
||
常用参数：
|
||
|
||
```bash
|
||
--repo <url> Git 仓库地址
|
||
--branch <name> Git 分支，默认 main
|
||
--install-dir <path> 安装目录，默认 /opt/lightops
|
||
--bind <addr> 监听地址，默认随机选择未占用端口
|
||
--public-url <url> 面板外部访问地址
|
||
--skip-deps 跳过依赖安装检查
|
||
```
|
||
|
||
构建前端：
|
||
|
||
```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 接口。
|