MyBlog - 生产级博客系统

MyBlog - 生产级博客系统

一个基于 PHP 的现代化博客系统，支持 Markdown、数学公式、代码高亮和图表渲染。

<img src="https://img.shields.io/badge/PHP-8.3%2B-blue.svg" alt="PHP Version"> <img src="https://img.shields.io/badge/license-MIT-green.svg" alt="License"> <img src="https://img.shields.io/badge/tests-passing-brightgreen.svg" alt="Tests">

📋 目录

  • 项目简介
  • 核心功能
  • 技术栈
  • 快速开始

- 系统要求 - 安装步骤 - 配置说明

  • 使用指南

- 目录结构 - 编写文章 - 生成索引

  • 部署指南

- 生产环境部署 - Nginx 配置 - Apache 配置

  • 开发指南

- 项目结构 - 运行测试 - 代码风格 - 静态分析

  • 安全特性
  • 性能优化
  • 常见问题
  • 贡献指南
  • 更新日志
  • 许可证

项目简介

MyBlog 是一个轻量级、高性能的博客系统，专为技术博客和文档站点设计。它采用 Markdown 格式存储文章，支持数学公式、代码高亮、流程图等丰富的展示功能。

主要特点

  • ✅ Markdown 支持: 完整的 Markdown 语法支持，包括 GFM 扩展
  • ✅ 数学公式: 基于 KaTeX 的 LaTeX 数学公式渲染
  • ✅ 代码高亮: 支持 190+ 种编程语言的语法高亮
  • ✅ 图表支持: Mermaid 流程图、时序图等图表渲染
  • ✅ 安全性: XSS 防护、路径验证、CSRF 保护、输入验证
  • ✅ 响应式设计: 适配桌面、平板和移动设备
  • ✅ 目录导航: 自动生成文章目录（TOC）
  • ✅ 模块化架构: PSR-4 自动加载，易于扩展和维护

核心功能

内容管理

  • Markdown 渲染: 支持完整的 Markdown 语法（标题、列表、链接、图片、表格等）
  • YAML Front Matter: 支持文章元数据（标题、日期、标签等）
  • 自动索引生成: 自动扫描目录并生成索引页面
  • HTML 静态化: 支持将 Markdown 转换为静态 HTML 文件

渲染功能

  • 数学公式: 行内公式 $...$ 和块级公式 $$...$$
  • 代码高亮: 语法高亮，支持代码块和行内代码
  • Mermaid 图表: 流程图、时序图、甘特图等
  • 目录生成: 自动从标题生成文章目录
  • 面包屑导航: 自动生成面包屑导航路径

安全特性

  • XSS 防护: 自动转义 HTML 输出，防止跨站脚本攻击
  • 路径验证: 防止路径遍历攻击
  • 输入验证: 严格的输入验证和过滤
  • CSRF 保护: 表单 CSRF 令牌保护

技术栈

后端

  • PHP 8.3+: 现代 PHP 特性（类型声明、命名空间、PSR-4 自动加载）
  • Composer: 依赖管理和自动加载

前端

  • KaTeX 0.16.9: 数学公式渲染
  • highlight.js 11.9.0: 代码语法高亮
  • Mermaid 10.9.0: 图表渲染
  • 原生 CSS: 响应式设计，无 JavaScript 框架依赖

开发工具

  • PHPUnit 10.5: 单元测试框架
  • PHP CS Fixer: 代码格式化（PSR-12）
  • PHPStan: 静态代码分析
  • PHP CodeSniffer: 代码风格检查

快速开始

系统要求

  • PHP: >= 8.3
  • 扩展:

- mbstring - json - fileinfo

  • Web 服务器: Apache 2.4+ 或 Nginx 1.18+
  • 可选: Composer（用于开发依赖）

安装步骤

1. 克隆仓库

git clone https://github.com/yourusername/myblog.git
cd myblog

2. 配置 Web 服务器

确保 Web 服务器的文档根目录指向项目根目录。

3. 配置博客信息

编辑 _blog/config.php 文件，修改博客基本信息：

define('BLOG_TITLE', '我的博客');
define('BLOG_DESCRIPTION', '我的博客描述');
define('BLOG_AUTHOR', '作者名称');

4. 设置目录权限

确保 Web 服务器对以下目录有读写权限：

# Linux/Mac
chmod -R 755 .
chmod -R 777 _blog  # 如果需要生成 HTML 文件

# Windows
# 通常无需特殊设置

5. 访问博客

在浏览器中访问 http://localhost/myblog/ 即可查看博客首页。

配置说明

博客配置 (_blog/config.php)

// 博客基本信息
define('BLOG_TITLE', '我的博客');
define('BLOG_DESCRIPTION', '博客描述');
define('BLOG_AUTHOR', '作者名称');

// 路径配置
define('BLOG_ROOT', dirname(__DIR__));

目录名称映射

在 _blog/config.php 中的 $directoryNames 数组中可以配置目录显示名称：

$directoryNames = [
    'agi' => 'AGI & AI',
    'editor' => '编辑器',
    // ... 更多映射
];

使用指南

目录结构

myblog/
├── _blog/                    # 博客核心代码
│   ├── src/                  # 源代码
│   │   ├── Renderer/         # 渲染器类
│   │   ├── Parser/           # Markdown 解析器
│   │   └── Security/         # 安全相关类
│   ├── config.php            # 配置文件
│   └── style.css             # 样式文件
├── index.php                 # 首页入口
├── *.md                      # Markdown 文章文件
├── *.html                    # 生成的 HTML 文件（可选）
└── composer.json             # Composer 配置

编写文章

1. 创建 Markdown 文件

在项目根目录或任何子目录中创建 .md 文件，例如 hello-world.md：

# Hello World

这是我的第一篇文章。

## 章节 1

文章内容...

### 子章节

更多内容...

2. 使用 YAML Front Matter（可选）

在文件开头添加元数据：

---
title: 文章标题
date: 2026-01-10
tags: [标签1, 标签2]
---

# 文章标题

文章内容...

3. 支持的特殊语法

数学公式：

行内公式：$E = mc^2$

块级公式：
$$
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
$$

代码高亮：

````markdown

<?php
echo "Hello, World!";

````

Mermaid 图表：

````markdown

graph TD
    A[开始] --> B{判断}
    B -->|是| C[执行]
    B -->|否| D[结束]

````

生成索引

系统会自动扫描目录并生成索引页面。每个目录中的 index.php 文件会自动：

  1. 扫描当前目录下的 .md 文件
  2. 扫描子目录
  3. 生成索引页面，包含：

- 目录列表 - 文章列表 - 面包屑导航

部署指南

生产环境部署

1. 上传文件

将所有项目文件上传到服务器：

# 使用 SFTP 或 Git
git clone https://github.com/yourusername/myblog.git /var/www/myblog

2. 设置权限

chown -R www-data:www-data /var/www/myblog
chmod -R 755 /var/www/myblog

3. 配置 Web 服务器

Nginx 配置

在 /etc/nginx/sites-available/myblog 创建配置文件：

server {
    listen 80;
    server_name yourdomain.com;
    root /var/www/myblog;
    index index.php index.html;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.3-fpm.sock;
        fastcgi_index index.php;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    }

    location ~ /\. {
        deny all;
    }
}

启用站点：

ln -s /etc/nginx/sites-available/myblog /etc/nginx/sites-enabled/
nginx -t
systemctl reload nginx

Apache 配置

在 /etc/apache2/sites-available/myblog.conf 创建配置文件：

<VirtualHost *:80>
    ServerName yourdomain.com
    DocumentRoot /var/www/myblog

    <Directory /var/www/myblog>
        Options Indexes FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>

    ErrorLog ${APACHE_LOG_DIR}/myblog_error.log
    CustomLog ${APACHE_LOG_DIR}/myblog_access.log combined
</VirtualHost>

启用站点：

a2ensite myblog.conf
apache2ctl configtest
systemctl reload apache2

4. SSL 证书（推荐）

使用 Let's Encrypt 免费 SSL 证书：

certbot --nginx -d yourdomain.com
# 或
certbot --apache -d yourdomain.com

开发指南

项目结构

_blog/
├── src/
│   ├── Renderer/
│   │   ├── BlogRenderer.php          # 主渲染器
│   │   └── BlogContentProcessor.php  # 内容处理器
│   ├── Parser/
│   │   └── Parsedown.php             # Markdown 解析器
│   └── Security/
│       ├── SecurityFilter.php        # 安全过滤器
│       ├── PathValidator.php         # 路径验证器
│       ├── InputValidator.php        # 输入验证器
│       └── CSRFProtection.php        # CSRF 保护
├── helpers/
│   ├── FileHelper.php                # 文件辅助函数
│   └── PathHelper.php                # 路径辅助函数
└── config.php                         # 配置文件

tests/
├── Unit/                              # 单元测试
│   ├── SecurityFilterTest.php
│   ├── PathValidatorTest.php
│   ├── InputValidatorTest.php
│   ├── CSRFProtectionTest.php
│   └── Blog/
│       └── Renderer/
│           ├── BlogRendererTest.php
│           └── BlogContentProcessorTest.php
└── Integration/                       # 集成测试
    └── RenderFlowTest.php

运行测试

安装依赖

composer install

运行所有测试

# 使用 PHPUnit
vendor/bin/phpunit

# 或使用 Composer 脚本
composer test

生成测试覆盖率报告

# 需要安装 Xdebug
vendor/bin/phpunit --coverage-html coverage
# 或
composer test:coverage

查看报告：打开 coverage/index.html

代码风格

格式化代码

# 使用 PHP CS Fixer
vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.php

# 或使用 Composer 脚本
composer cs-fix

检查代码风格

# 检查但不修改
vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.php --dry-run

# 或使用 Composer 脚本
composer cs-check

静态分析

运行 PHPStan

# 分析代码
vendor/bin/phpstan analyse _blog/src tests --level=5

# 或使用 Composer 脚本
composer phpstan

运行 PHP CodeSniffer

# 检查代码风格
vendor/bin/phpcs --standard=PSR12 _blog/src tests

# 或使用 Composer 脚本
composer phpcs

安全特性

MyBlog 实现了多层安全防护：

XSS 防护

  • SecurityFilter 类: 自动转义 HTML 输出
  • Parsedown 安全模式: 禁止危险 HTML 标签
  • URL 验证: 防止恶意协议（javascript:, data: 等）

路径验证

  • PathValidator 类: 防止路径遍历攻击（../ 等）
  • 文件类型验证: 只允许 .md 文件访问
  • 目录权限检查: 验证目录是否在允许范围内

输入验证

  • InputValidator 类: 严格的输入验证和过滤
  • 类型检查: 字符串、整数、邮箱、URL 等
  • 长度限制: 防止过长的输入

CSRF 保护

  • CSRFProtection 类: 生成和验证 CSRF 令牌
  • 一次性令牌: 使用后自动失效
  • Session 管理: 安全的令牌存储

性能优化

静态 HTML 生成

系统支持将 Markdown 文件转换为静态 HTML，提高访问速度：

  • 自动检测文件变更
  • 仅在 Markdown 文件更新时重新生成 HTML
  • 优先使用静态 HTML 文件

CDN 资源

  • KaTeX、highlight.js、Mermaid 等资源使用 CDN
  • 减少服务器负载
  • 提高加载速度

缓存策略

（计划中）实现缓存机制：

  • 渲染结果缓存
  • 索引页面缓存
  • 支持 APCu 和文件缓存

常见问题

Q: 如何修改博客样式？

A: 编辑 _blog/style.css 文件，或创建自定义 CSS 文件并引用。

Q: 如何添加自定义功能？

A: 由于采用模块化架构，可以在 _blog/src/ 目录下创建新类，遵循 PSR-4 命名规范。

Q: 支持多语言吗？

A: 当前版本主要支持中文，但可以通过修改模板和配置支持其他语言。

Q: 如何备份博客内容？

A: 博客内容以 Markdown 文件形式存储，直接备份 .md 文件即可。建议使用 Git 进行版本控制。

Q: 数学公式不显示？

A: 检查网络连接，确保可以访问 CDN（jsdelivr.net）。如果无法访问，可以考虑自托管 KaTeX 资源。

Q: 代码高亮不工作？

A: 同样需要访问 CDN。确保 highlight.js 可以正常加载。

贡献指南

欢迎贡献代码、报告问题或提出建议！

贡献流程

  1. Fork 仓库
  2. 创建功能分支: git checkout -b feature/amazing-feature
  3. 提交更改: git commit -m 'Add some amazing feature'
  4. 推送分支: git push origin feature/amazing-feature
  5. 提交 Pull Request

代码规范

  • 遵循 PSR-12 代码风格
  • 添加适当的注释和文档
  • 编写单元测试
  • 确保所有测试通过

报告问题

在提交 Issue 时，请包含：

  • 问题描述
  • 复现步骤
  • 期望行为
  • 实际行为
  • 环境信息（PHP 版本、操作系统等）

更新日志

详细的更新日志请查看 CHANGELOG.md。

主要版本

  • v2.1.0 (2026-01-10): 安全增强、代码重构、测试基础设施
  • v2.0.0: 初始发布

许可证

本项目采用 MIT 许可证。详情请查看 LICENSE 文件。

联系方式

  • 项目主页: https://github.com/yourusername/myblog
  • 问题反馈: https://github.com/yourusername/myblog/issues
  • 作者: 步子哥 Steper

感谢使用 MyBlog！ 🎉

← 返回目录