# happy_html_puter

**Repository Path**: xkx1029/happy_html_puter

## Basic Information

- **Project Name**: happy_html_puter
- **Description**: 一个轻量级的 HTML 应用托管平台，让您轻松部署和管理多个独立的 HTML 应用。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Happy HTML Puter

一个轻量级的 HTML 应用托管平台，让您轻松部署和管理多个独立的 HTML 应用。

## ✨ 功能特性

- **一键部署**：上传 HTML 文件或直接输入代码即可创建应用
- **容器化运行**：每个应用运行在独立的 Docker 容器中，互相隔离
- **资源监控**：实时查看 CPU、内存、存储使用情况
- **数据库支持**：自动检测并部署 SQLite 数据库文件
- **主题切换**：支持亮色/暗色主题，设置自动保存
- **日志查看**：实时查看应用容器日志，支持日志级别高亮
- **代码编辑**：在线编辑应用代码，即时保存
- **反向代理**：所有应用通过统一入口访问
- **环境变量**：支持为应用配置运行时环境变量，修改后自动重启
- **应用导入/导出**：支持将应用打包为 ZIP 文件导出，或从 ZIP 文件导入
- **批量操作**：支持批量启动、停止、重启、删除应用
- **健康检查**：系统每60秒自动执行健康检查，检测异常应用并自动恢复
- **系统监控**：健康检查历史记录与日志中心，便于问题排查

## 🛠️ 技术栈

| 层次 | 技术 | 版本 |
|------|------|------|
| 后端 | FastAPI | 0.115.6 |
| 后端 | Uvicorn | 0.34.0 |
| 后端 | Docker SDK | 7.1.0 |
| 前端 | React | 18.3.1 |
| 前端 | TypeScript | 5.6.2 |
| 前端 | Tailwind CSS | 3.4.16 |
| 前端 | Vite | 6.0.1 |
| 容器 | nginx:alpine | latest |
| 数据库 | nouchka/sqlite3 | latest |

## 📁 项目结构

```
happy_html_puter/
├── backend/
│   ├── main.py              # FastAPI 主入口与 API 路由
│   ├── docker_manager.py    # Docker 容器管理核心逻辑
│   ├── requirements.txt     # Python 依赖
│   └── data/
│       ├── apps/            # 应用数据存储目录
│       └── health_history.json  # 健康检查历史记录
├── frontend/
│   ├── src/
│   │   ├── components/
│   │   │   ├── Dashboard.tsx          # 仪表盘主界面
│   │   │   ├── AppCard.tsx            # 应用卡片组件
│   │   │   ├── AppDetail.tsx          # 应用详情页
│   │   │   ├── CreateAppModal.tsx     # 创建应用弹窗
│   │   │   ├── CodeEditor.tsx         # 代码编辑器
│   │   │   ├── LogViewer.tsx          # 日志查看器
│   │   │   ├── Layout.tsx             # 布局组件
│   │   │   ├── MouseGlow.tsx          # 鼠标光晕特效
│   │   │   ├── EnvVarsEditor.tsx      # 环境变量编辑器
│   │   │   ├── ImportAppModal.tsx     # 导入应用弹窗
│   │   │   └── HealthHistoryModal.tsx # 系统监控弹窗
│   │   ├── api/client.ts              # API 客户端
│   │   ├── types/index.ts             # TypeScript 类型定义
│   │   └── contexts/
│   │       ├── ThemeContext.tsx       # 主题上下文
│   │       └── AppContext.tsx         # 应用数据上下文
│   ├── dist/                          # 前端构建产物
│   └── package.json                   # 前端依赖
├── BUGS.md                 # Bug 记录与修复文档
├── docker-compose.yml       # Docker Compose 配置
├── Dockerfile               # 项目 Docker 镜像构建配置
├── start.sh                 # Linux/macOS 启动脚本
└── start.bat                # Windows 启动脚本
```

## 🚀 快速开始

### 环境要求

- **Docker**：必须安装 Docker Desktop（Windows/macOS）或 Docker Engine（Linux）
- **Python**：3.8+（仅本地开发需要）
- **Node.js**：18+（仅本地开发需要）

### 方法一：使用 Docker Compose（推荐）

```bash
# 克隆项目（GitHub）
git clone https://github.com/xkx121029/happy_html_puter.git
cd happy_html_puter

# 或者从 Gitee 克隆
git clone https://gitee.com/xkx1029/happy_html_puter.git
cd happy_html_puter

# 启动服务
docker-compose up -d

# 访问应用
# 浏览器打开 http://localhost:8002
```

### 方法二：本地开发运行

```bash
# 克隆项目（GitHub）
git clone https://github.com/xkx121029/happy_html_puter.git
cd happy_html_puter

# 或者从 Gitee 克隆
git clone https://gitee.com/xkx1029/happy_html_puter.git
cd happy_html_puter

# 安装后端依赖
cd backend
pip install -r requirements.txt

# 启动后端服务
python main.py

# 在另一个终端启动前端
cd ../frontend
npm install
npm run dev

# 访问应用
# 浏览器打开 http://localhost:5173
```

## 📖 使用说明

### 创建应用

1. 在仪表盘点击「创建应用」按钮
2. 输入应用名称
3. 选择上传文件或输入 HTML 代码
4. 点击「创建」按钮

### 管理应用

- **启动/停止**：点击应用卡片上的启动/停止按钮
- **重启**：点击重启按钮重新启动应用
- **删除**：点击删除按钮删除应用（不可恢复）
- **查看详情**：点击应用卡片查看详细信息和日志
- **批量操作**：选择多个应用后，可批量执行启动、停止、重启、删除操作

### 预览应用

应用启动后，点击「预览」按钮即可在浏览器中查看应用效果。

### 编辑代码

在应用详情页点击「编辑文件」按钮，可以在线编辑应用的 HTML 文件。

### 环境变量

在应用详情页点击「环境变量」按钮，可以配置应用运行时的环境变量。修改后应用会自动重启。

### 导入/导出应用

- **导出**：在应用详情页点击「导出」按钮，将应用打包为 ZIP 文件下载
- **导入**：在仪表盘点击「导入应用」按钮，选择 ZIP 文件导入

### 系统监控

点击顶部导航栏的「系统监控」按钮，可查看：
- **健康检查**：自动检测应用状态并记录历史
- **日志中心**：查看所有运行中应用的日志，支持日志级别高亮

## ⚙️ 配置说明

### Docker 网络

应用使用 `happy_puter_network` 专用网络进行容器间通信，无需暴露主机端口。

### 数据持久化

应用数据存储在 `backend/data/apps/` 目录下，每个应用有独立的文件夹：

```
apps/
└── {app_id}/
    ├── html/          # HTML 文件
    ├── database/      # 数据库文件（如 SQLite）
    ├── meta.json      # 应用元信息
    └── docker-compose.yml  # 容器配置
```

### 环境变量

| 变量 | 说明 | 默认值 |
|------|------|--------|
| APPS_DIR | 应用数据存储目录 | backend/data/apps |
| PYTHONUNBUFFERED | Python 输出缓冲 | 1 |

## 📝 更新日志

### v1.1.0 (2026-07-18)

**新增功能**
- ✅ 环境变量配置：支持为应用设置运行时环境变量，修改后自动重启
- ✅ 应用导入/导出：支持将应用打包为 ZIP 文件导出，或从 ZIP 文件导入
- ✅ 批量操作：支持批量启动、停止、重启、删除多个应用
- ✅ 健康检查：系统每60秒自动执行健康检查，检测异常应用并自动恢复
- ✅ 系统监控：健康检查历史记录与日志中心，支持日志级别高亮
- ✅ AppContext：新增 React Context 管理应用数据，减少重复请求

**Bug 修复**
- ✅ 修复 AppDetail.tsx 中 app.db_port 可能为 undefined 的问题
- ✅ 修复 AppCard.tsx 中 app.port 和 total_size 可能为 undefined 的问题
- ✅ 修复 LogViewer.tsx 中 logs 可能为 null/undefined 的问题
- ✅ 修复 CodeEditor.tsx 中文件名无扩展名时的 lastIndexOf bug

**安全改进**
- ✅ 加强文件路径安全检查，防止路径遍历攻击
- ✅ 添加 ALLOWED_ORIGINS 环境变量配置
- ✅ 使用 DaoCloud 镜像加速，提高国内访问速度

### v1.0.0 (2026-07-07)

- ✅ 项目初始化
- ✅ 基础应用管理功能（创建、启动、停止、删除）
- ✅ 资源监控（CPU、内存、存储）
- ✅ SQLite 数据库支持
- ✅ 主题切换（亮色/暗色）
- ✅ 代码在线编辑

## 🤝 贡献指南

欢迎贡献代码！请遵循以下步骤：

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

## 📄 许可证

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

## 📞 联系方式

如有问题或建议，欢迎提交 Issue 或发送邮件。

---

**Happy HTML Puter** - 让 HTML 应用部署更简单 🎉