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