# xpanel

**Repository Path**: xywhsoft/xpanel

## Basic Information

- **Project Name**: xpanel
- **Description**: linux 服务器面板，使用 xserver 开发
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-31
- **Last Updated**: 2025-12-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# xPanel - 轻量级服务器管理面板

[English](README.en.md) | 简体中文

## 项目简介

xPanel 是一个基于 C 语言开发的轻量级 Linux 服务器管理面板，采用现代化的 Web 界面，提供高性能、低资源占用的服务器管理解决方案。

### 核心特性

- 🚀 **高性能**：C 语言实现，TCC JIT 编译，极低内存占用
- 🔒 **安全可靠**：RBAC 权限模型，MD5 密码加密，SQL 预编译防注入
- 💡 **轻量级**：单文件部署，无复杂依赖，开箱即用
- 🎨 **现代化 UI**：基于 Pear Admin (Layui) 框架，响应式设计
- ⚡ **即时编译**：TCC 支持，代码修改即时生效，无需重新编译

## 技术架构

### 后端技术栈

- **开发语言**：C 语言
- **编译器**：TCC (Tiny C Compiler) - JIT 编译
- **Web 服务器**：Mongoose 嵌入式 HTTP/HTTPS 服务器
- **数据库**：SQLite3 + XDO 对象关系映射
- **加密算法**：MD5 (Mongoose 实现)

### 前端技术栈

- **UI 框架**：Pear Admin (基于 Layui 2.x)
- **样式**：CSS3 + 自定义主题
- **JavaScript**：原生 JS + Fetch API
- **图标**：Layui Icon

### 系统要求

- **操作系统**：Linux (推荐 Ubuntu 18.04+, CentOS 7+)
- **架构**：x86_64 或 ARM64
- **运行环境**：systemd (可选)
- **端口**：80 (HTTP), 443 (HTTPS)

## 快速开始

### 安装部署

1. **下载项目**
```bash
git clone https://github.com/your-org/xpanel.git
cd xpanel
```

2. **安装服务**
```bash
cd service
chmod +x install.sh
sudo ./install.sh
```

3. **启动服务**
```bash
sudo ./start.sh
```

4. **访问面板**
```
浏览器访问: http://your-server-ip
默认账户: admin
默认密码: admin123
```

### 服务管理

```bash
# 启动服务
sudo ./service/start.sh

# 停止服务
sudo ./service/stop.sh

# 重启服务
sudo ./service/restart.sh

# 查看状态
sudo systemctl status xpanel
```

### 手动运行（开发模式）

**Windows (测试环境)**
```batch
test.bat
```

**Linux**
```bash
./xs
```

## 功能模块

### ✅ 已实现功能

#### 1. 用户认证系统
- ✅ 用户登录（MD5 密码加密）
- ✅ 注销登录（清除 Session 和 Cookie）
- ✅ 记住登录状态（7 天有效期）
- ✅ 暴力破解防护

#### 2. 权限管理系统 (RBAC)
- ✅ **用户管理**：增删改查、密码重置、角色分配
- ✅ **角色管理**：角色创建、权限分配、用户关联检查
- ✅ **权限分类**：分组管理、排序、关联检查
- ✅ **权限管理**：权限组配置、URI 绑定
- ✅ **接口管理**：URI 自动扫描、权限绑定、路由同步

#### 3. 系统设置
- ✅ 面板标题配置
- ✅ 菜单标题配置
- ✅ 安全入口配置
- ✅ 配置持久化到 JSON 文件

### 🚧 规划功能

- 📁 **文件管理**：浏览、上传、下载、编辑、权限管理
- 🔥 **防火墙**：端口管理、IP 白名单/黑名单
- 📊 **性能监控**：CPU、内存、磁盘、网络实时监控
- 📝 **日志管理**：系统日志、应用日志查看与搜索
- ⏰ **计划任务**：Cron 任务管理、执行记录
- 💻 **Web 终端**：SSH 终端、命令执行
- 📦 **应用管理**：软件安装、启停、配置
- 🔐 **证书管理**：SSL 证书申请、续期、部署
- 🚨 **告警系统**：监控告警、邮件/Webhook 通知

## 项目结构

```
xpanel/
├── host/xpanel/              # 主应用目录
│   ├── data/                 # 数据目录
│   │   ├── db/              # SQLite 数据库文件
│   │   ├── options/         # 配置文件（JSON）
│   │   └── page/            # 前端页面
│   │       ├── auth/        # 权限管理页面
│   │       └── option.html  # 设置页面
│   ├── script/              # C 源码目录
│   │   ├── main.c          # 程序入口
│   │   ├── route.h         # 路由配置
│   │   ├── module/         # 功能模块
│   │   │   └── auth.h      # 权限模块
│   │   └── route_http/     # HTTP 接口
│   │       ├── login.h     # 登录/注销
│   │       ├── auth.h      # 权限管理接口
│   │       └── option.h    # 设置接口
│   └── wwwroot/            # 静态资源目录
│       └── res/            # CSS/JS/图片资源
├── service/                # 服务脚本
│   ├── install.sh         # 安装脚本
│   ├── start.sh           # 启动脚本
│   ├── stop.sh            # 停止脚本
│   └── restart.sh         # 重启脚本
├── tcc/                   # TCC 编译器相关文件
├── docs/                  # 文档目录
│   └── 需求报告.md         # 需求文档
├── xs / xs.exe           # 可执行文件
├── xs.json               # 主配置文件
└── readme.md             # 本文件
```

## API 接口

### 认证接口

| 接口 | 方法 | 说明 |
|------|------|------|
| `/login` | GET | 登录页面 |
| `/login` | POST | 用户登录 |
| `/logout` | GET/POST | 注销登录 |

### 权限管理接口

| 接口 | 方法 | 说明 |
|------|------|------|
| `/auth/user` | GET | 获取用户列表 |
| `/auth/user` | POST | 添加用户 |
| `/auth/user` | PUT | 更新用户 |
| `/auth/user` | DELETE | 删除用户 |
| `/auth/user/repwd` | POST | 重置密码 |
| `/auth/role` | GET/POST/PUT/DELETE | 角色管理 |
| `/auth/group` | GET/POST/PUT/DELETE | 权限分类管理 |
| `/auth/auth` | GET/POST/PUT/DELETE | 权限管理 |
| `/auth/uris` | GET/PUT | URI 权限管理 |

### 系统设置接口

| 接口 | 方法 | 说明 |
|------|------|------|
| `/option` | GET | 获取系统设置 |
| `/option` | POST/PUT | 保存系统设置 |

## 数据库设计

### RBAC 权限模型

```
authGroup (权限分类)
    ↓ 1:N
auth (权限组)
    ↓ 1:N
uris (URI 权限)

role (角色) ← 1:N → user (用户)
```

### 主要数据表

- `user` - 用户表（用户名、密码、角色、时间戳）
- `role` - 角色表（角色名、权限列表 JSON、时间戳）
- `authGroup` - 权限分类表（名称、描述、排序）
- `auth` - 权限组表（名称、所属分类、排序）
- `uris` - URI 权限表（URI、所属权限组、排序）

所有表支持软删除（`isDelete` 字段）

## 安全特性

### 认证安全
- MD5 密码加密：`MD5(username + "_xPanel_" + password)`
- HttpOnly Cookie 防止 XSS
- Session 服务器端管理
- 暴力破解防护机制

### 数据安全
- SQL 预编译语句防止注入
- 参数绑定验证
- 用户名唯一性检查
- 级联删除保护

### 传输安全
- 支持 HTTPS/TLS 加密
- 证书管理（TLS CA/Cert/Key）

## 配置说明

### 主配置文件 (xs.json)

```json
{
  "enabled": true,
  "class": "http",
  "name": "xywhsoft Server",
  "addr": "http://0.0.0.0:80",
  "tls": true,
  "addr_tls": "https://0.0.0.0:443",
  "host_default": {
    "name": "xPanel",
    "path": "host/xpanel/wwwroot",
    "tls_ca": "host/xpanel/tls/ca.pem",
    "tls_cert": "host/xpanel/tls/cert.pem",
    "tls_key": "host/xpanel/tls/key.pem",
    "devlang": "c",
    "devfile": "host/xpanel/script/main.c",
    "session": "xpanel$"
  }
}
```

### 系统设置 (data/options/global.json)

```json
{
  "Title": "xPanel",
  "MenuTitle": "服务器管理面板",
  "SafeEntry": ""
}
```

## 开发指南

### 添加新路由

1. 在 `route_http/` 目录创建接口文件
2. 在 `route.h` 中注册路由
3. 在 `module/auth.h` 中添加 SQL 预编译语句（如需要）

### 添加新页面

1. 在 `data/page/` 目录创建 HTML 文件
2. 使用 Layui 框架和 Fetch API
3. 遵循现有页面的设计模式

### 代码规范

- C 语言函数：`Request_XXX`, `Module_Init`
- JavaScript 函数：驼峰命名 `fetchData`, `renderTable`
- SQL 预编译：`stmt_xxx_add/put/del`

## 性能优化

- SQL 预编译语句（减少编译开销）
- 内存缓存（URI 映射表、Session 表）
- 软删除机制（避免物理删除）
- TCC JIT 编译（代码即时生效）

## 故障排除

### 无法启动服务
```bash
# 检查端口占用
sudo netstat -tlnp | grep :80

# 查看日志
sudo journalctl -u xpanel -f

# 检查权限
sudo chmod +x xs
```

### 登录失败
- 检查数据库文件是否存在
- 确认密码加密算法正确
- 查看防火墙日志

### 路由 404
- 确认路由已在 `route.h` 注册
- 检查 `uris` 表是否同步
- 重启服务刷新路由表

## 贡献指南

欢迎提交 Issue 和 Pull Request！

1. Fork 本项目
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 提交 Pull Request

## 许可证

本项目采用 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件

## 联系方式

- **项目主页**：https://github.com/your-org/xpanel
- **开发团队**：星月软件 (xywhsoft)
- **问题反馈**：https://github.com/your-org/xpanel/issues

## 致谢

- [Mongoose](https://github.com/cesanta/mongoose) - 嵌入式 Web 服务器
- [Layui](https://layui.dev/) - 前端 UI 框架
- [Pear Admin](https://www.pearadmin.com/) - 管理模板
- [TCC](https://bellard.org/tcc/) - Tiny C Compiler

---

**xPanel** - 让服务器管理更简单 🚀