# OpsPanel

**Repository Path**: ten-ken/OpsPanel

## Basic Information

- **Project Name**: OpsPanel
- **Description**: 一款基于C#12.0 dotnet8.0的运维web工具
- **Primary Language**: C#
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-01
- **Last Updated**: 2026-08-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OpsPanel — 轻量级单机运维面板

基于 **.NET 8.0 (LTS) + C# 12 + FreeSql + Vue 3** 的轻量级单机服务器运维面板，类似宝塔但更轻量、内存占用更低。

> **设计目标**：单机管理、轻量化部署、核心功能覆盖、常态内存比 ServerGC+RetainVM 下降约 35%

---

## 目录

- [技术栈](#技术栈)
- [功能清单](#功能清单)
- [项目结构](#项目结构)
- [快速开始](#快速开始)
- [后端开发](#后端开发)
- [前端开发](#前端开发)
- [API 文档](#api-文档)
- [架构设计](#架构设计)
- [安全设计](#安全设计)
- [内存优化](#内存优化)
- [许可证](#许可证)

---

## 技术栈

| 层级               | 技术                                                             | 说明                                                         |
| ------------------ | ---------------------------------------------------------------- | ------------------------------------------------------------ |
| **运行时**   | .NET 8.0 (LTS)                                                   | WorkstationGC + ConcurrentGC，低内存优先                      |
| **语言**     | C# 12                                                            | 主构造函数、required 成员、集合表达式、file-scoped namespace |
| **Web 框架** | ASP.NET Core Minimal API                                         | 轻量、高性能                                                 |
| **ORM**      | FreeSql                                                          | CodeFirst 自动建表，SQLite/PostgreSQL 双适配                 |
| **实时通信** | SignalR                                                          | 仪表盘监控、终端、日志流推送                                 |
| **SSH 代理** | SSH.NET                                                          | Web Terminal 后端                                            |
| **容器管理** | Docker.DotNet                                                    | Unix Socket 直连                                             |
| **进程调用** | CliWrap                                                          | 类型安全的系统命令调用（systemctl/docker/certbot/ufw…）     |
| **日志**     | Serilog + JSON                                                   | 结构化日志，ELK/Loki 友好                                    |
| **认证**     | JWT + Refresh Token + TOTP 2FA                                   | 无状态认证                                                   |
| **调度**     | Cronos                                                           | 轻量 Cron 表达式解析                                         |
| **前端**     | Vue3.5 + Element Plus`2.8` + ECharts`5.5` + xterm.js`5.5` | SPA，Vite 构建                                               |

---

## 功能清单

### P0 — 核心基础

| # | 模块                 | 功能                                                                                                        |
| - | -------------------- | ----------------------------------------------------------------------------------------------------------- |
| 1 | **仪表盘**     | CPU/内存/磁盘/网络 IO 实时图表、系统负载、运行时间、OS 信息、关键服务状态卡片（Nginx/MySQL/Docker/Redis…） |
| 2 | **文件管理**   | 目录浏览、上传/下载、在线编辑、删除、权限修改、大文件分片上传（断点续传）、压缩/解压                        |
| 3 | **服务管理**   | systemd 服务启停/重启/日志查看、Docker 容器列表/启停/日志查看                                               |
| 4 | **用户与安全** | 管理员登录/登出、密码修改、2FA（TOTP）、操作审计日志、首次安装向导、安全入口                                |

### P1 — 网站与数据库

| #  | 模块                 | 功能                                                                                                                                                  |
| -- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| 5  | **网站管理**   | 站点创建/删除/暂停、Nginx 配置自动生成（静态/反向代理/PHP-FPM）、SSL 证书申请（Let's Encrypt ACME）与自动续期、反向代理可视化编辑、配置语法校验与重载 |
| 6  | **数据库管理** | MySQL/PostgreSQL/MariaDB 实例管理、库/用户 CRUD、手动/定时备份与恢复                                                                                  |
| 7  | **计划任务**   | Shell 脚本定时执行、日志切割预设、数据库自动备份预设、执行日志查看                                                                                    |
| 8  | **软件商店**   | 一键安装/卸载（Redis/Node.js/Java/Nginx/Docker…）、**本地离线包优先**、无则在线下载、SHA256 校验                                               |
| 9  | **防火墙**     | 端口开放/关闭、IP 黑白名单、自动适配 ufw/firewalld/iptables                                                                                           |
| 10 | **面板 SSL**   | 一键自签证书、Let's Encrypt 申请、自定义上传、HTTPS 开关                                                                                              |

---

## 项目结构

```
opspanel-skeleton/
├── OpsPanel.sln                      # 解决方案
├── README.md
├── .gitignore
│
├── OpsPanel.Web/                     # ASP.NET Core 主机（入口）
│   ├── Program.cs                    # 顶级语句 + Serilog + GC 优化
│   ├── Endpoints/                    # Minimal API 端点（10 个模块）
│   │   ├── AuthEndpoints.cs          #   登录/登出/密码修改/2FA/首次安装
│   │   ├── AuditEndpoints.cs         #   审计日志查询
│   │   ├── DashboardEndpoints.cs     #   仪表盘快照/系统信息/关键服务
│   │   ├── ServiceEndpoints.cs       #   systemd + Docker + 日志查看
│   │   ├── FileEndpoints.cs          #   文件管理（20 个端点）
│   │   ├── SiteEndpoints.cs          #   网站管理 + 反向代理 + SSL
│   │   ├── DatabaseEndpoints.cs      #   数据库管理 + 备份恢复
│   │   ├── CronJobEndpoints.cs       #   计划任务 + 预设
│   │   ├── SoftwareStoreEndpoints.cs #   软件商店
│   │   ├── FirewallEndpoints.cs     #   防火墙
│   │   ├── PanelSslEndpoints.cs     #   面板自身 SSL
│   │   └── EndpointRegistration.cs  #   统一注册
│   ├── Hubs/                         # SignalR Hub
│   │   ├── MonitorHub.cs             #   监控 + 终端 + 日志（JoinGroup/LeaveGroup）
│   │   ├── MonitorPushService.cs     #   IMonitorPushService 实现
│   │   └── LogPushService.cs         #   ILogPushService 实现
│   ├── Middleware/                   # 中间件
│   │   ├── SecurityEntryMiddleware.cs #  安全入口（隐藏登录 URL）
│   │   └── AuditMiddleware.cs        #   审计日志记录
│   ├── Extensions/                   # DI 扩展（JWT/限流/CORS/Swagger）
│   ├── Properties/
│   ├── appsettings.json             # 配置
│   ├── frontend/                     # Vue 3 前端源码
│   │   ├── src/
│   │   │   ├── api/                  #   Axios + SignalR 客户端
│   │   │   ├── views/                #   10 个页面
│   │   │   ├── layouts/              #   主布局
│   │   │   ├── router/              #   路由
│   │   │   └── assets/              #   样式
│   │   ├── package.json
│   │   ├── vite.config.js
│   │   └── tsconfig.json
│   └── wwwroot/                      # 前端构建产物（npm run build 输出）
│
├── OpsPanel.Core/                    # 领域模型 + 服务接口
│   ├── Entities/                     # 14 个 FreeSql 实体
│   │   ├── User.cs / Session.cs / AuditLog.cs
│   │   ├── Website.cs / WebsiteDomain.cs / SslCertificate.cs
│   │   ├── DatabaseInstance.cs / DatabaseBackup.cs
│   │   ├── CronJob.cs / CronLog.cs
│   │   ├── SoftwarePackage.cs / InstalledSoftware.cs
│   │   ├── FirewallGroup.cs / FirewallRule.cs
│   │   └── SystemSetting.cs
│   ├── Interfaces/                   # 11 个服务接口
│   │   ├── ISystemService.cs         #   系统指标 + systemd
│   │   ├── IFileService.cs           #   文件管理 + 分片上传
│   │   ├── ISiteService.cs           #   网站管理 + SSL
│   │   ├── IDatabaseService.cs       #   数据库管理
│   │   ├── ICronJobService.cs        #   计划任务
│   │   ├── ISoftwareStoreService.cs  #   软件商店
│   │   ├── IFirewallService.cs       #   防火墙
│   │   ├── IPanelSslService.cs       #   面板 SSL
│   │   ├── IJwtService.cs           #   JWT
│   │   ├── IAuditService.cs         #   审计
│   │   ├── IMonitorPushService.cs   #   监控推送
│   │   ├── ILogPushService.cs       #   日志推送
│   │   ├── IDockerService.cs        #   Docker
│   │   └── ISshService.cs           #   SSH
│   └── Enums/
│
├── OpsPanel.Infrastructure/          # 基础设施实现
│   ├── Data/                         # FreeSql 仓储 + CodeFirst
│   ├── OperatingSystem/              # SystemService + FileService
│   ├── Sites/                        # NginxConfigGenerator + SiteService
│   ├── Databases/                    # DatabaseService
│   ├── Scheduler/                    # CronJobService
│   ├── SoftwareStore/                # SoftwareStoreService
│   ├── Firewall/                     # FirewallService（ufw/firewalld/iptables）
│   ├── Ssl/                          # PanelSslService
│   ├── Auth/                         # JwtService
│   ├── Docker/                       # DockerService
│   ├── Ssh/                          # SshService
│   ├── Logging/                      # SerilogSetup
│   ├── Services/                     # AuditService
│   └── DependencyInjection.cs       # DI 注册入口
│
├── OpsPanel.BackgroundJobs/          # 后台任务
│   ├── Jobs/
│   │   ├── MetricsCollectorJob.cs    #   每 5s 采集指标推送 SignalR
│   │   ├── CronJobRunner.cs          #   每 30s 扫描到期任务
│   │   └── SslRenewalJob.cs          #   每 6h 检查证书续期
│   └── DependencyInjection.cs
│
├── OpsPanel.Contracts/              # API 契约（前后端共享 DTO）
│   ├── Requests/
│   └── Responses/
│
├── OpsPanel.Shared/                  # 工具类 + 常量
│   ├── Constants/AppConstants.cs
│   └── Utils/SecurityUtils.cs
│
└── tests/
    ├── OpsPanel.UnitTests/           # 35 个单元测试
    │   ├── Services/FileServiceTests.cs
    │   └── System/SystemServiceTests.cs
    └── OpsPanel.IntegrationTests/
```

---

## 快速开始

### 环境要求

- **.NET 8.0 SDK** ([下载](https://dotnet.microsoft.com/download/dotnet/8.0))
- **Node.js 18+** ([下载](https://nodejs.org/))
- **Linux 服务器**（Ubuntu 20.04+ / Debian 11+ / CentOS 8+）
- 可选：Docker、Nginx、MySQL/PostgreSQL、certbot、ufw

### 1. 克隆/解压

```bash
unzip opspanel-version.zip
cd opspanel-skeleton
```

### 2. 后端构建

```bash
# 还原依赖
dotnet restore OpsPanel.sln

# 构建（Release 模式）
dotnet build OpsPanel.sln -c Release

# 运行单元测试（35 个）
dotnet test tests/OpsPanel.UnitTests
```

### 3. 前端构建

```bash
cd OpsPanel.Web/frontend

# 安装依赖
npm install

# 开发模式（热重载，http://localhost:5173）
npm run dev

# 生产构建（输出到 ../wwwroot/）
npm run build
```

### 4. 运行

```bash
cd OpsPanel.Web

# 开发模式
dotnet run

# 生产发布
dotnet publish -c Release -o /opt/opspanel
dotnet publish -c Release -o D:\\desktop-data\\genCode\\opspanel
dotnet publish -c Release -r linux-x64 --self-contained -o D:\\desktop-data\\genCode\\opspanel
cd /opt/opspanel
./OpsPanel.Web
```

### 5. 首次访问

1. 浏览器打开 `http://服务器IP:8888`
2. 首次访问自动跳转到安装向导
3. 设置管理员用户名 + 密码 + 安全入口（可选）
4. 安装完成后使用安全入口登录（如 `http://ip:8888/admin_xxxx`）

---

## 后端开发

### 添加新端点

1. 在 `OpsPanel.Web/Endpoints/` 创建 `XxxEndpoints.cs`：

```csharp
public static class XxxEndpoints
{
    public static IEndpointRouteBuilder MapXxxEndpoints(this IEndpointRouteBuilder app)
    {
        var group = app.MapGroup("/api/v1/xxx").WithTags("Xxx").RequireAuthorization();

        group.MapGet("/", async (IXxxService svc, CancellationToken ct) =>
            Results.Ok(await svc.ListAsync(ct)));

        return app;
    }
}
```

2. 在 `EndpointRegistration.cs` 注册：

```csharp
app.MapXxxEndpoints();
```

### 添加新实体

1. 在 `OpsPanel.Core/Entities/` 创建实体类（继承 `EntityBase`）：

```csharp
public class MyEntity : EntityBase
{
    [MaxLength(128)]
    public required string Name { get; set; }

    public bool IsActive { get; set; } = true;
}
```

2. FreeSql 会自动建表（`UseAutoSyncStructure(true)`）
3. 在 `FreeSqlSetup.cs` 注册仓储：

```csharp
services.AddScoped<IRepository<MyEntity>, Repository<MyEntity>>();
```

### 添加后台任务

在 `OpsPanel.BackgroundJobs/Jobs/` 创建 `BackgroundService`：

```csharp
public class MyJob(IServiceScopeFactory scope) : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken ct)
    {
        using var timer = new PeriodicTimer(TimeSpan.FromMinutes(1));
        while (await timer.WaitForNextTickAsync(ct))
        {
            // 定时逻辑
        }
    }
}
```

在 `DependencyInjection.cs` 注册：`services.AddHostedService<MyJob>();`

---

## 前端开发

### 添加新页面

1. 在 `src/views/` 创建 `Xxx.vue`
2. 在 `src/router/index.ts` 添加路由：

```typescript
{
  path: 'xxx',
  name: 'Xxx',
  component: () => import('@/views/Xxx.vue'),
  meta: { title: 'Xxx', icon: 'XxxIcon' },
}
```

3. 在 `src/layouts/MainLayout.vue` 的 `menuItems` 添加菜单项

### 添加 API 调用

在 `src/api/index.ts` 添加：

```typescript
export const xxxApi = {
  list: () => http.get('/xxx/'),
  create: (data: any) => http.post('/xxx/', data),
}
```

---

## API 文档

启动后访问 Swagger：`http://localhost:8888/swagger`

### 主要 API 端点

| 模块     | 前缀                       | 端点数 | 说明                               |
| -------- | -------------------------- | ------ | ---------------------------------- |
| 认证     | `/api/v1/auth`           | 5      | 登录/登出/密码修改/2FA/首次安装    |
| 审计     | `/api/v1/audit`          | 1      | 日志查询（分页+过滤）              |
| 仪表盘   | `/api/v1/dashboard`      | 3      | 快照/系统信息/关键服务             |
| 服务管理 | `/api/v1/services`       | 6      | systemd + Docker + 日志            |
| 文件管理 | `/api/v1/files`          | 20     | 浏览/上传/下载/编辑/权限/分片/压缩 |
| 网站管理 | `/api/v1/sites`          | 12     | CRUD + Nginx 配置 + SSL + 反向代理 |
| 数据库   | `/api/v1/databases`      | 15     | 实例 + 库/用户 + 备份恢复          |
| 计划任务 | `/api/v1/cron-jobs`      | 12     | CRUD + 手动触发 + 日志 + 预设      |
| 软件商店 | `/api/v1/software-store` | 10     | 列表 + 安装/卸载 + 本地包          |
| 防火墙   | `/api/v1/firewall`       | 12     | 状态 + 端口 + IP + 分组            |
| 面板 SSL | `/api/v1/settings/ssl`   | 7      | 状态/自签/LE/上传/开关/续期        |

### SignalR Hub

| Hub         | 路径               | 事件                          | 说明                     |
| ----------- | ------------------ | ----------------------------- | ------------------------ |
| MonitorHub  | `/hubs/monitor`  | `metrics` / `keyServices` | 每 5s/30s 推送           |
| TerminalHub | `/hubs/terminal` | 双向                          | Web Terminal             |
| LogHub      | `/hubs/log`      | `log` / `logs`            | 日志流（JoinGroup 订阅） |

---

## 架构设计

```
┌─────────────────────────────────────────────────────────┐
│              前端 (Vue 3 SPA)                            │
│   Element Plus + xterm.js + ECharts + SignalR Client    │
└────────────────────────┬────────────────────────────────┘
                         │ HTTPS / WSS
┌────────────────────────▼────────────────────────────────┐
│           ASP.NET Core 8.0 Web API                       │
│  ┌──────────┐ ┌──────────┐ ┌────────────────────────┐  │
│  │ Auth     │ │ REST API │ │ SignalR Hub             │  │
│  │ JWT+2FA  │ │ 10 模块  │ │ Monitor/Terminal/Log    │  │
│  └──────────┘ └────┬─────┘ └───────┬────────────────┘  │
│                     │               │                    │
│  ┌──────────────────▼───────────────▼─────────────────┐ │
│  │            业务服务层 (Service Layer)               │ │
│  │ System | File | Site | Database | Cron | Software   │ │
│  │ Firewall | PanelSsl | Audit | Jwt                  │ │
│  └──────────────────┬─────────────────────────────────┘ │
│                     │                                   │
│  ┌──────────────────▼─────────────────────────────────┐ │
│  │           基础设施层 (Infrastructure)               │ │
│  │ FreeSql | CliWrap | SSH.NET | Docker.DotNet        │ │
│  │ Cronos | Serilog | OpenSSL/certbot                 │ │
│  └──────┬──────────┬──────────┬──────────────────────┘ │
└─────────┼──────────┼──────────┼────────────────────────┘
          │          │          │
    ┌─────▼───┐ ┌────▼────┐ ┌──▼──────────┐
    │ SQLite/ │ │ OS CLI  │ │ Systemd/    │
    │ PgSQL   │ │ Commands│ │ Docker API  │
    └─────────┘ └─────────┘ └─────────────┘
```

### 依赖倒置设计

BackgroundJobs 需要推送数据到 SignalR Hub（Web 层），但不能引用 Web 项目（会造成循环依赖）。

**解决方案**：在 Core 层定义抽象接口，Web 层实现：

```
OpsPanel.Core/Interfaces/IMonitorPushService   ← 抽象
OpsPanel.Core/Interfaces/ILogPushService       ← 抽象
        ↑                    ↑
        │                    │
BackgroundJobs 调用        Web 层实现 (MonitorPushService / LogPushService)
```

---

## 安全设计

| 设计                   | 说明                                                  |
| ---------------------- | ----------------------------------------------------- |
| **首次安装向导** | 未安装时仅暴露`/api/v1/auth/setup` 端点             |
| **安全入口**     | 登录 URL 隐藏（如`/admin_xxxx`），降低扫描风险      |
| **面板 SSL**     | 一键自签证书 / Let's Encrypt / 自定义上传             |
| **2FA**          | TOTP 二次验证（OtpNet）                               |
| **审计日志**     | 所有写操作记录，append-only                           |
| **路径白名单**   | Linux 文件管理默认允许整个文件系统（含 `/`、`/var`、`/usr`），实际访问受进程用户与 OS 权限限制 |
| **限流**         | 登录 5 次/分钟，API 100 次/分钟                       |
| **JWT**          | HMAC-SHA256，1h Access Token + 7d Refresh Token       |
| **密码哈希**     | PBKDF2-SHA256，100,000 次迭代                         |
| **AES 加密**     | 数据库密码等敏感配置加密存储                          |
| **特权分离**     | 文件管理访问系统目录需要 root；其他服务可保持降权运行并通过 sudoers 白名单执行特权命令 |

---

## 内存优化

| 措施                                 | 效果                                                 |
| ------------------------------------ | ---------------------------------------------------- |
| WorkstationGC + ConcurrentGC          | 低并发面板优先低内存，常态 RSS/私有内存更小            |
| Kestrel MaxConcurrentConnections=100 | 防止连接爆炸                                         |
| SignalR 消息大小 64KB 限制           | 防止大消息撑爆内存                                   |
| FreeSql 单例                         | 避免连接池泄漏                                       |
| Serilog 文件 50MB 滚动，14 天保留    | 日志不撑爆磁盘                                       |
| PeriodicTimer 替代 Task.Delay        | 减少定时器分配                                       |
| 后台任务间隔优化                     | 指标 5s / 关键服务 30s / Cron 扫描 30s / SSL 续期 6h |
| JWT 无状态认证                       | 内存零会话占用                                       |
| SQLite 单文件                        | 启动快，常态内存占用低                                 |

---

## 许可证

MIT License

Copyright (c) 2024 OpsPanel