# html-editor-service

**Repository Path**: devqiaoyu/html-editor-service

## Basic Information

- **Project Name**: html-editor-service
- **Description**: 一个基于Next.js的Docker服务，提供简洁的HTML文件实时编辑功能。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-24
- **Last Updated**: 2026-01-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# HTML Editor Service

一个基于 Next.js 的现代化 HTML 编辑器服务，提供安全、直观的可视化编辑体验。

## ✨ 功能特性

### 🎯 核心功能
- 📁 **智能文件管理** - 自动扫描并列出指定目录中的HTML文件
- 🗑️ **可视化元素删除** - 点击任意HTML元素即可删除
- 🔄 **实时刷新机制** - 支持手动刷新和自动检测新文件
- 💾 **一键保存** - 修改后立即保存到原始文件
- 🎨 **现代化UI** - 响应式设计，流畅动画效果

### 🔒 安全特性
- 🛡️ **路径遍历防护** - 严格的文件路径验证，防止目录穿越攻击
- 🔐 **XSS攻击防护** - CSP策略和安全头保护，禁用脚本执行
- 🚫 **危险元素过滤** - 自动隐藏或禁用script、iframe等危险标签

### 🛠️ 技术特性
- 🏗️ **模块化架构** - 组件化设计，代码清晰可维护
- ⚡ **性能优化** - 事件委托，减少内存占用
- 🎭 **智能状态管理** - 完善的错误处理和用户反馈
- 🐳 **多架构部署** - 支持 AMD64、ARM64、ARMv7 等架构
- 🌐 **云原生** - 完整的容器化和 CI/CD 支持

## 🚀 快速开始

### 🐳 多架构 Docker 部署（推荐）

#### 快速启动
```bash
# 1. 克隆项目
git clone <repository-url>
cd html-editor-service

# 2. 使用预构建镜像
docker run -d \
  --name html-editor-service \
  -p 3000:3000 \
  -v $(pwd)/html-files:/app/html-files \
  registry.cn-hangzhou.aliyuncs.com/devqiaoyu/html-editor-service:v1.0.0

# 3. 访问应用
open http://localhost:3000
```

#### Docker Compose 多架构部署
```bash
# 1. 使用多架构配置
docker-compose -f docker-compose.multi-arch.yml up -d

# 2. 带 Nginx 反向代理
docker-compose -f docker-compose.multi-arch.yml --profile with-nginx up -d
```

#### 支持的架构
- **linux/amd64** - x86_64 服务器 (Intel/AMD)
- **linux/arm64** - ARM64 服务器 (Apple Silicon, AWS Graviton)
- **linux/arm/v7** - ARM32 设备 (Raspberry Pi 3/4)

### 本地开发

```bash
# 1. 安装依赖
npm install

# 2. 启动开发服务器
npm run dev

# 3. 访问应用
open http://localhost:3000
```

### 🔨 构建多架构镜像

```bash
# 1. 构建并推送所有架构
./build-multi-arch.sh

# 2. 构建不使用缓存
./build-multi-arch.sh --no-cache

# 3. 测试多架构镜像
./test-multi-arch.sh
```

## 📖 使用指南

### 基础操作

1. **选择文件** 📂
   - 在左侧文件列表中选择要编辑的HTML文件
   - 支持文件名搜索和排序
   - 实时显示文件修改时间

2. **编辑元素** 🎯
   - 在右侧编辑区域点击任意HTML元素
   - 选中元素会显示红色高亮边框
   - 删除按钮自动出现在元素附近

3. **删除元素** 🗑️
   - 点击红色删除按钮移除选中元素
   - 支持删除文本、图片、容器等所有HTML元素
   - 删除操作立即生效，支持连续删除

4. **保存文件** 💾
   - 点击右上角"保存"按钮
   - 修改会实时保存到原始HTML文件
   - 保存后文件列表会自动刷新

### 高级功能

#### 🔄 文件刷新
- **手动刷新**：点击侧边栏顶部刷新按钮
- **自动检测**：新文件添加时会显示"新文件"提示
- **定时更新**：每30秒自动检查文件变化

#### ⚡ 性能优化
- **事件委托**：使用单一事件监听器处理所有元素点击
- **智能高亮**：高效的DOM操作和样式管理
- **内存管理**：自动清理事件监听器和定时器

## ⚙️ 配置选项

### 环境变量

| 变量名 | 默认值 | 说明 |
|---------|--------|------|
| `HTML_DIR` | `./html-files` | HTML文件存储目录 |
| `PORT` | `3000` | 服务监听端口 |
| `NODE_ENV` | `development` | 运行环境 |

### Docker 配置

```yaml
version: '3.8'
services:
  html-editor:
    build: .
    ports:
      - "3000:3000"
    volumes:
      - ./html-files:/app/html-files
    environment:
      - HTML_DIR=/app/html-files
    restart: unless-stopped
```

## 🏗️ 项目架构

### 目录结构

```
html-editor-service/
├── 📁 html-files/                 # HTML文件存储
│   ├── 📄 sample.html             # 示例文件
│   └── 📄 test.html              # 测试文件
├── 📁 src/
│   ├── 📁 app/                   # Next.js App Router
│   │   ├── 📁 api/              # API 路由
│   │   │   ├── 📄 html-files/route.ts   # 文件列表API
│   │   │   ├── 📄 html-file/route.ts    # 文件读取API
│   │   │   └── 📄 save-file/route.ts    # 文件保存API
│   │   ├── 📄 layout.tsx        # 应用布局
│   │   └── 📄 page.tsx          # 主页面组件
│   ├── 📁 components/           # React 组件
│   │   ├── 📄 FileSidebar.tsx   # 文件侧边栏
│   │   ├── 📄 HTMLEditor.tsx    # HTML 编辑器
│   │   └── 📄 DeleteButton.tsx  # 删除按钮
│   └── 📁 types/               # TypeScript 类型
│       └── 📄 index.ts          # 类型定义
├── 🐳 Dockerfile               # Docker 构建文件
├── 📦 docker-compose.yml       # Docker Compose 配置
├── ⚙️ next.config.ts          # Next.js 配置
├── 📦 package.json            # 项目依赖
└── 📖 README.md               # 项目文档
```

### 组件架构

```
📱 App (page.tsx)
├── 📂 FileSidebar
│   ├── 🔄 刷新按钮
│   ├── 🆕 新文件提示
│   └── 📋 文件列表
├── 🖥️ HTMLEditor
│   ├── 📝 编辑器界面
│   └── 🎯 交互处理
└── 🗑️ DeleteButton
    └── 🎯 删除操作
```

## 🔐 安全措施

### 路径验证
```typescript
// 严格的路径验证，防止目录遍历攻击
function validateFilePath(filePath: string) {
  const resolvedPath = path.resolve(filePath);
  const allowedDir = path.resolve(htmlDir);
  
  // 检查路径是否在允许目录内
  if (!resolvedPath.startsWith(allowedDir)) {
    return { isValid: false, error: 'Access denied' };
  }
  
  // 检查文件扩展名
  if (!filePath.endsWith('.html')) {
    return { isValid: false, error: 'Only HTML files allowed' };
  }
  
  return { isValid: true, resolvedPath };
}
```

### XSS 防护
```html
<!-- CSP 策略防止脚本执行 -->
<meta http-equiv="Content-Security-Policy" content="script-src 'none'; object-src 'none';">
<meta http-equiv="X-Content-Type-Options" content="nosniff">
<meta http-equiv="X-Frame-Options" content="SAMEORIGIN">
```

## 🛠️ API 接口

### 文件管理 API

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/api/html-files` | 获取HTML文件列表 |
| `POST` | `/api/html-file` | 读取指定HTML文件内容 |
| `POST` | `/api/save-file` | 保存HTML文件内容 |

### 请求示例

**获取文件列表**
```bash
curl -X GET http://localhost:3000/api/html-files
```

**读取文件内容**
```bash
curl -X POST http://localhost:3000/api/html-file \
  -H "Content-Type: application/json" \
  -d '{"filePath": "/app/html-files/example.html"}'
```

**保存文件**
```bash
curl -X POST http://localhost:3000/api/save-file \
  -H "Content-Type: application/json" \
  -d '{
    "filePath": "/app/html-files/example.html",
    "content": "<html><body><h1>Updated</h1></body></html>"
  }'
```

## 🧪 测试

### 自动化测试
```bash
# 运行类型检查
npm run type-check

# 运行代码规范检查
npm run lint

# 构建测试
npm run build
```

### 功能测试
```bash
# 创建测试文件
npm run test:create-files

# 清理测试文件
npm run test:cleanup

# 测试自动刷新功能
bash test-auto-refresh.sh
```

## 🎯 使用场景

### 1. 网页内容清理
- 移除广告横幅
- 清理侧边栏元素
- 删除多余的装饰性内容

### 2. 页面原型制作
- 快速删除不需要的部分
- 简化复杂页面结构
- 创建最小化版本

### 3. 内容提取
- 保留核心内容
- 移除导航和页脚
- 提取主要文本信息

## 🔧 开发指南

### 本地开发环境
```bash
# 1. 克隆项目
git clone <repository-url>
cd html-editor-service

# 2. 安装依赖
npm install

# 3. 启动开发服务器
npm run dev

# 4. 访问应用
open http://localhost:3000
```

### 构建生产版本
```bash
# 构建优化版本
npm run build

# 启动生产服务器
npm start
```

### 多架构 Docker 部署

#### 生产环境推荐配置
```bash
# 1. 使用预构建的多架构镜像
docker run -d \
  --name html-editor-service \
  -p 3000:3000 \
  -v $(pwd)/html-files:/app/html-files \
  -e NODE_ENV=production \
  --restart unless-stopped \
  registry.cn-hangzhou.aliyuncs.com/devqiaoyu/html-editor-service:v1.0.0

# 2. 健康检查
docker ps
curl http://localhost:3000/api/html-files
```

#### Docker Compose 生产部署
```bash
# 基础部署
docker-compose -f docker-compose.multi-arch.yml up -d

# 带 Nginx 反向代理
docker-compose -f docker-compose.multi-arch.yml --profile with-nginx up -d
```

#### 架构特定部署
```bash
# AMD64 服务器
docker run -d --platform linux/amd64 registry.cn-hangzhou.aliyuncs.com/devqiaoyu/html-editor-service:v1.0.0

# ARM64 服务器 (Apple Silicon, AWS Graviton)
docker run -d --platform linux/arm64 registry.cn-hangzhou.aliyuncs.com/devqiaoyu/html-editor-service:v1.0.0

# ARM32 设备 (Raspberry Pi)
docker run -d --platform linux/arm/v7 registry.cn-hangzhou.aliyuncs.com/devqiaoyu/html-editor-service:v1.0.0
```

## 📊 性能优化

### 前端优化
- **事件委托**：减少事件监听器数量
- **懒加载**：按需加载文件内容
- **内存管理**：自动清理定时器和事件监听

### 后端优化
- **路径缓存**：缓存已解析的文件路径
- **并发控制**：限制同时操作的文件数量
- **错误处理**：完善的异常捕获和恢复机制

## 🐛 故障排除

### 常见问题

**Q: 文件列表为空？**
A: 检查 `html-files` 目录是否存在，确保有 `.html` 文件。

**Q: 删除元素没有反应？**
A: 确保点击的是HTML元素，不是空白区域。

**Q: 保存失败？**
A: 检查文件权限和磁盘空间，查看控制台错误信息。

**Q: 刷新按钮不工作？**
A: 检查网络连接和API服务状态。

### 调试模式
```bash
# 启用详细日志
DEBUG=1 npm run dev

# 查看网络请求
# 打开浏览器开发者工具 -> Network 标签
```

## 🤝 贡献指南

1. Fork 项目
2. 创建功能分支 (`git checkout -b feature/amazing-feature`)
3. 提交更改 (`git commit -m 'feat: add amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 创建 Pull Request

### 代码规范
- 使用 TypeScript 严格模式
- 遵循 ESLint 规则
- 编写清晰的 commit message
- 添加必要的类型定义

## 📄 许可证

MIT License - 详见 [LICENSE](LICENSE) 文件

## 🔗 相关链接

- [Next.js 文档](https://nextjs.org/docs)
- [Tailwind CSS](https://tailwindcss.com)
- [Lucide Icons](https://lucide.dev)
- [Docker 文档](https://docs.docker.com)

---

<div align="center">
  <p>⭐ 如果这个项目对你有帮助，请给个 Star！</p>
  <p>🐛 发现问题？欢迎提交 Issue</p>
</div>