# markdown-editor

**Repository Path**: cutecuteyu/markdown-editor

## Basic Information

- **Project Name**: markdown-editor
- **Description**: markdown-editor
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-08
- **Last Updated**: 2026-03-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Markdown 编辑器

一个功能完整、界面美观的基于 Web 的 Markdown 编辑器，支持实时预览和文件保存功能。

## 功能特性

### 核心功能
- **实时预览** - 在编辑时即时查看 Markdown 渲染效果
- **文件保存** - 将 Markdown 内容保存到服务器
- **文件加载** - 从服务器加载已保存的文件
- **代码高亮** - 支持多种编程语言的语法高亮
- **美观界面** - 深色主题设计，类似 VS Code 风格

### Markdown 语法支持
- 标题（H1-H6）
- 列表（有序和无序）
- 链接和图片
- 代码片段（行内和块级）
- 表格
- 粗体、斜体、粗斜体
- 引用块
- 水平分隔线

### 用户界面
- 左右分栏布局（编辑区 + 预览区）
- 响应式设计，适配不同屏幕尺寸
- 文件名输入和操作按钮
- 操作结果提示（成功/错误消息）

## 技术栈

### 后端
- **FastAPI** - 现代化的 Python Web 框架
- **Uvicorn** - ASGI 服务器
- **Pydantic** - 数据验证和序列化
- **Python 3.8+** - 编程语言

### 前端
- **Vue 3.5.29** - 渐进式 JavaScript 框架
- **Vue Router 5.0.3** - 官方路由管理器
- **Marked 17.0.4** - Markdown 解析库
- **Highlight.js 11.11.1** - 代码语法高亮
- **Vite 7.3.1** - 快速的前端构建工具
- **Node.js 20.19.0+** - JavaScript 运行环境

## 项目结构

```
NEWTEST/
├── backend/                 # 后端服务
│   ├── data/               # 文件存储目录
│   ├── __init__.py
│   └── main.py            # FastAPI 应用主文件
├── frontend/              # 前端应用
│   ├── public/            # 静态资源
│   ├── src/
│   │   ├── assets/        # 样式和资源
│   │   ├── components/    # Vue 组件
│   │   │   └── MarkdownEditor.vue
│   │   ├── router/        # 路由配置
│   │   ├── views/         # 页面视图
│   │   ├── App.vue        # 根组件
│   │   └── main.js       # 应用入口
│   ├── package.json       # 前端依赖配置
│   └── vite.config.js    # Vite 配置
├── pyproject.toml        # Python 项目配置
├── start_backend.ps1     # 后端启动脚本
└── README.md            # 项目文档
```

## 快速开始

### 环境要求
- Python 3.8 或更高版本
- Node.js 20.19.0 或更高版本
- uv（推荐）或 pip

### 安装步骤

#### 1. 克隆项目
```bash
git clone <repository-url>
cd NEWTEST
```

#### 2. 安装后端依赖

使用 uv（推荐）：
```bash
uv sync
```

或使用 pip：
```bash
pip install -r requirements.txt
```

#### 3. 安装前端依赖
```bash
cd frontend
npm install
```

#### 4. 配置环境变量

在 `frontend/` 目录下创建 `.env` 文件：

```bash
cd frontend
```

创建 `.env` 文件并添加以下内容：
```env
VITE_API_BASE_URL=http://localhost:8000
```

**环境变量说明：**
- `VITE_API_BASE_URL`: 后端 API 的基础 URL
  - 开发环境：`http://localhost:8000`
  - 生产环境：应配置为实际的后端服务器地址（如：`https://api.yourdomain.com`）

### 运行项目

#### 启动后端服务

方式一：使用启动脚本（Windows）
```powershell
.\start_backend.ps1
```

方式二：直接运行
```bash
uv run uvicorn backend.main:app --host 0.0.0.0 --port 8000
```

或使用 pip：
```bash
python -m uvicorn backend.main:app --host 0.0.0.0 --port 8000
```

后端服务将运行在：http://localhost:8000

#### 启动前端服务
```bash
cd frontend
npm run dev
```

前端服务将运行在：http://localhost:5173

#### 访问应用

在浏览器中打开：http://localhost:5173

## API 文档

后端 API 文档自动生成，可通过以下地址访问：

- **Swagger UI**: http://localhost:8000/docs
- **ReDoc**: http://localhost:8000/redoc

### API 端点

#### 1. 保存文件
**POST** `/api/save`

请求体：
```json
{
  "filename": "example.json",
  "content": "# Hello World",
  "metadata": {
    "timestamp": "2024-01-01T00:00:00Z",
    "size": 13
  }
}
```

响应：
```json
{
  "success": true,
  "message": "File saved successfully",
  "filename": "example.json"
}
```

#### 2. 加载文件
**GET** `/api/load/{filename}`

响应：
```json
{
  "success": true,
  "filename": "example.json",
  "content": "# Hello World",
  "message": "File loaded successfully"
}
```

#### 3. 列出所有文件
**GET** `/api/files`

响应：
```json
{
  "files": ["example1.json", "example2.json"]
}
```

#### 4. 删除文件
**DELETE** `/api/delete/{filename}`

响应：
```json
{
  "success": true,
  "message": "File 'example.json' deleted successfully"
}
```

## 使用说明

### 基本操作

1. **编辑 Markdown**
   - 在左侧编辑区输入 Markdown 内容
   - 右侧预览区会实时显示渲染结果

2. **保存文件**
   - 在文件名输入框中输入文件名
   - 点击"保存"按钮或按回车键
   - 系统会自动添加 `.json` 后缀

3. **加载文件**
   - 在文件名输入框中输入已保存的文件名
   - 点击"加载"按钮
   - 系统会自动添加 `.json` 后缀

### 支持的 Markdown 语法

#### 标题
```markdown
# 一级标题
## 二级标题
### 三级标题
```

#### 代码块
```markdown
\`\`\`javascript
function hello() {
  console.log('Hello, World!');
}
\`\`\`
```

#### 表格
```markdown
| 列1 | 列2 | 列3 |
|------|------|------|
| 数据1 | 数据2 | 数据3 |
```

#### 链接
```markdown
[Vue.js](https://vuejs.org)
```

#### 图片
```markdown
![alt text](image-url.jpg)
```

#### 列表
```markdown
- 无序列表项1
- 无序列表项2

1. 有序列表项1
2. 有序列表项2
```

## 开发指南

### 后端开发

#### 添加新的 API 端点
在 `backend/main.py` 中添加新的路由：

```python
@app.get("/api/your-endpoint")
async def your_endpoint() -> Dict[str, Any]:
    return {"message": "Your response"}
```

#### 修改 CORS 配置
在 `backend/main.py` 中修改 CORS 中间件：

**开发环境配置：**
```python
app.add_middleware(
    CORSMiddleware,
    allow_origins=["http://localhost:5173"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)
```

**生产环境配置：**
```python
app.add_middleware(
    CORSMiddleware,
    allow_origins=["https://yourdomain.com"],
    allow_credentials=True,
    allow_methods=["GET", "POST", "PUT", "DELETE"],
    allow_headers=["*"],
)
```

**CORS 配置说明：**
- `allow_origins`: 允许的源地址
  - 开发环境：使用 `http://localhost:5173`（前端开发服务器）
  - 生产环境：应配置为实际的域名（如：`https://yourdomain.com`）
  - 如需允许多个域名，使用列表：`["https://example1.com", "https://example2.com"]`
  - **安全警告**：不要在生产环境使用 `["*"]`，这会允许任何源访问你的 API
- `allow_credentials`: 是否允许携带 Cookie
- `allow_methods`: 允许的 HTTP 方法（建议明确指定，而非使用 `["*"]`）
- `allow_headers`: 允许的请求头

### 前端开发

#### 添加新组件
在 `frontend/src/components/` 中创建新的 Vue 组件：

```vue
<template>
  <div class="your-component">
    <!-- 组件内容 -->
  </div>
</template>

<script setup>
import { ref } from 'vue'

const data = ref('')
</script>

<style scoped>
.your-component {
  /* 组件样式 */
}
</style>
```

#### 添加新路由
在 `frontend/src/router/index.js` 中添加新路由：

```javascript
{
  path: '/your-page',
  name: 'YourPage',
  component: () => import('../views/YourPage.vue')
}
```

### 代码规范

#### Python 代码
- 所有函数参数和返回值必须有类型注解
- 使用 Pydantic 进行数据验证
- 遵循 PEP 8 代码风格

#### Vue/JavaScript 代码
- 使用 Composition API（`<script setup>`）
- 使用 TypeScript 类型（推荐）
- 遵循 Vue 3 最佳实践

## 常见问题

### Q: 前端无法连接到后端 API？
**A:** 确保：
1. 后端服务正在运行（http://localhost:8000）
2. 检查 `frontend/src/components/MarkdownEditor.vue` 中的 `API_BASE_URL` 配置
3. 检查浏览器控制台的网络请求错误

### Q: 代码高亮不显示？
**A:** 确保：
1. `highlight.js` 和 `highlight.js/styles/github-dark.css` 已正确导入
2. 浏览器控制台没有 JavaScript 错误
3. 代码块使用正确的语法（\`\`\`language）

### Q: 文件保存失败？
**A:** 检查：
1. 文件名是否为空
2. `backend/data/` 目录是否有写权限
3. 后端服务是否正常运行

### Q: 端口被占用？
**A:** 修改端口配置：
- 后端：修改启动命令中的 `--port` 参数
- 前端：修改 `frontend/vite.config.js` 中的端口配置

## 生产部署

### 后端部署

#### 使用 Gunicorn + Uvicorn
```bash
pip install gunicorn
gunicorn backend.main:app -w 4 -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:8000
```

#### 使用 Docker
创建 `Dockerfile`：
```dockerfile
FROM python:3.9-slim
WORKDIR /app
COPY backend/ ./backend/
COPY pyproject.toml ./
RUN pip install -e .
CMD ["uvicorn", "backend.main:app", "--host", "0.0.0.0", "--port", "8000"]
```

### 前端部署

#### 构建生产版本
```bash
cd frontend
npm run build
```

构建产物在 `frontend/dist/` 目录。

#### 使用 Nginx
```nginx
server {
    listen 80;
    server_name your-domain.com;

    location / {
        root /path/to/frontend/dist;
        try_files $uri $uri/ /index.html;
    }

    location /api/ {
        proxy_pass http://localhost:8000;
    }
}
```

## 贡献指南

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

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

## 安全最佳实践

### 1. XSS 防护

#### 前端防护
- **使用 Vue 的模板自动转义**：Vue 默认会转义 HTML 内容，防止 XSS 攻击
- **避免使用 `v-html`**：如需使用，确保内容经过严格的验证和过滤
- **使用 DOMPurify**：如果需要渲染用户提供的 HTML，使用 DOMPurify 进行清理

```javascript
import DOMPurify from 'dompurify'

// 安全地渲染用户提供的 HTML
const safeHTML = DOMPurify.sanitize(userProvidedHTML)
```

#### 后端防护
- **输入验证**：使用 Pydantic 验证所有输入数据
- **输出编码**：在返回数据时进行适当的编码
- **Content Security Policy (CSP)**：配置适当的 CSP 头部

### 2. CORS 配置安全

#### 开发环境
```python
app.add_middleware(
    CORSMiddleware,
    allow_origins=["http://localhost:5173"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)
```

#### 生产环境
```python
app.add_middleware(
    CORSMiddleware,
    allow_origins=["https://yourdomain.com"],
    allow_credentials=True,
    allow_methods=["GET", "POST", "PUT", "DELETE"],
    allow_headers=["*"],
)
```

**安全要点：**
- 生产环境务必使用具体的域名，不要使用 `["*"]`
- 明确指定允许的 HTTP 方法
- 定期审查并更新 CORS 配置

### 3. 输入验证

#### 后端验证（Pydantic）
```python
from pydantic import BaseModel, Field, validator

class FileSaveRequest(BaseModel):
    filename: str = Field(..., min_length=1, max_length=255, regex=r'^[a-zA-Z0-9._-]+$')
    content: str = Field(..., max_length=10485760)  # 限制为 10MB
    
    @validator('filename')
    def validate_filename(cls, v):
        # 防止路径遍历攻击
        if '..' in v or v.startswith('/'):
            raise ValueError('Invalid filename')
        return v
```

#### 前端验证
```javascript
const validateFilename = (filename) => {
  // 文件名验证
  const filenameRegex = /^[a-zA-Z0-9._-]{1,255}$/
  if (!filenameRegex.test(filename)) {
    throw new Error('Invalid filename')
  }
  
  // 防止路径遍历
  if (filename.includes('..') || filename.startsWith('/')) {
    throw new Error('Invalid filename')
  }
  
  return true
}
```

### 4. HTTPS 配置

#### 生产环境强制 HTTPS
- 在 Nginx/Apache 配置中强制使用 HTTPS
- 使用 Let's Encrypt 获取免费 SSL 证书
- 配置 HSTS（HTTP Strict Transport Security）

```nginx
server {
    listen 80;
    server_name yourdomain.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name yourdomain.com;
    
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
}
```

### 5. 敏感数据保护

#### 环境变量管理
- **不要将 `.env` 文件提交到版本控制**
- 使用 `.env.example` 作为模板
- 在生产环境使用安全的密钥管理系统（如 AWS Secrets Manager、Azure Key Vault）

#### .env.example 示例
```env
VITE_API_BASE_URL=http://localhost:8000
# 生产环境示例：
# VITE_API_BASE_URL=https://api.yourdomain.com
```

### 6. 依赖安全

#### 定期更新依赖
```bash
# 检查过时的依赖
npm outdated
pip list --outdated

# 更新依赖
npm update
pip install --upgrade package-name
```

#### 使用安全审计工具
```bash
# npm 审计
npm audit
npm audit fix

# Python 安全检查
pip install safety
safety check
```

### 7. 错误处理

#### 前端错误处理
```javascript
try {
  const response = await fetch(url, options)
  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`)
  }
  const data = await response.json()
} catch (error) {
  // 不要向用户显示详细的错误信息
  console.error('Error:', error)
  showError('操作失败，请稍后重试')
}
```

#### 后端错误处理
```python
from fastapi import HTTPException, status

@app.post("/api/save")
async def save_file(request: FileSaveRequest):
    try:
        # 处理逻辑
        pass
    except ValidationError as e:
        raise HTTPException(
            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
            detail="Invalid input data"
        )
    except Exception as e:
        # 记录完整的错误信息到日志
        logger.error(f"Error saving file: {str(e)}")
        # 向客户端返回通用错误信息
        raise HTTPException(
            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
            detail="An error occurred while processing your request"
        )
```

### 8. 安全部署检查清单

部署到生产环境前，请确认：

- [ ] 已更新 CORS 配置为生产域名
- [ ] 已配置 HTTPS 和 SSL 证书
- [ ] 已设置适当的安全头部（CSP, HSTS, X-Frame-Options 等）
- [ ] 已限制 API 的访问速率（Rate Limiting）
- [ ] 已配置日志记录和监控
- [ ] 已删除或禁用调试端点
- [ ] 已更新环境变量配置
- [ ] 已运行安全审计并修复发现的问题
- [ ] 已配置防火墙规则
- [ ] 已设置定期备份

### 9. 日志和监控

#### 敏感信息过滤
```python
import logging

class SensitiveDataFilter(logging.Filter):
    def filter(self, record):
        message = record.getMessage()
        # 过滤敏感信息（如密码、令牌等）
        record.msg = message.replace(r'password=\w+', 'password=***')
        return True

logging.getLogger().addFilter(SensitiveDataFilter())
```

## 许可证

本项目采用 MIT 许可证。

## 联系方式

如有问题或建议，请通过以下方式联系：
- 提交 Issue
- 发送邮件
- 加入讨论组

## 致谢

感谢以下开源项目：
- [FastAPI](https://fastapi.tiangolo.com/)
- [Vue.js](https://vuejs.org/)
- [Marked](https://marked.js.org/)
- [Highlight.js](https://highlightjs.org/)
- [Vite](https://vitejs.dev/)

## 更新日志

### v0.1.0 (2024-01-01)
- 初始版本发布
- 实现基本的 Markdown 编辑和预览功能
- 支持文件保存和加载
- 实现代码高亮
- 支持完整的 Markdown 语法