先交代一下背景这个项目不是我一时兴起写着玩的而是我前后花了大概三个月业余时间从零搭建并最终开源的一套个人博客系统。仓库在 GitHub 上同步维护核心代码 1 万多行覆盖文章发布、评论、标签聚合、全文搜索、后台管理这些常见功能。之所以把它拿出来开源一方面是因为市面上的博客框架虽然多但真正能让人舒服地二改、加功能、跑在自己服务器上的完整开源方案并没有那么多另一方面是想给准备接触开源项目的同学一个结构简单、文档齐全、可以真正跑起来的参考案例。如果你正在纠结“博客系统到底该用现成的还是自己写”或者想找一个入门级完整开源项目来读源码、提 issue、练 PR这篇文章应该能一次性把你的疑问都聊透。1. 项目定位与技术选型复盘1.1 为什么自己写一套博客系统而不是直接用 Hexo 或 WordPress很多朋友上来就会问这个问题。Hexo 写文章确实快WordPress 功能也确实全但我的需求有点特殊我希望博客系统本身就是一个完整的前后端分离应用有管理后台、有动态评论、有标签体系和站内搜索而不仅仅是一个把 Markdown 渲染成静态页面的工具。换句话说我在意的不是“怎么把文章发出去”而是“博客系统的代码结构长什么样、改一个功能要动哪些模块、多人一起开发时怎么协作”。自己做还有一个好处就是能完全掌控技术栈。每次看到网上有人抱怨“WordPress 插件装多了速度就崩”“Hexo 换台电脑就得重装环境”我就觉得自建系统的可移植性和可控性是很值钱的。当然代价也很明显评论系统要自己做防垃圾评论要自己写搜索得自己建索引部署要自己维护。这些活看起来很杂但正是这些“杂活”构成了一个好的学习项目。1.2 技术选型后端、数据库、前端分别怎么定这个项目的技术栈是一个很主流的组合我做选型时没有走偏门路线原因只有一个开源项目要想让更多人参与就必须用大家熟悉的工具。模块选型理由后端框架Spring Boot 3.2生态成熟、做 CRUD 和权限控制都有现成方案适合结构化展示数据库MySQL 8.0博客数据是典型的关系型数据文章、分类、评论、标签都需要关联查询缓存Redis 7热点文章和标签聚合的响应速度靠它拉起来前端Vue 3 Vite TypeScript组件化开发适合博客后台这种表单密集场景TS 类型约束能让代码更可控富文本/Markdownmarkdown-it highlight.jsMarkdown 解析生态成熟配合代码高亮开箱即用全文搜索Elasticsearch可选初期用 MySQL LIKE 查询文章量大后再接 ES保持入口简单我特别想说明一下为什么没选更轻量的方案比如 Flask 或者 Express。不是说它们不行而是如果一个博客系统的核心卖点是“帮初学者理解完整应用是怎么分层、怎么组织模块的”那么一个结构严谨、官方文档丰富且周边资料多的框架能减少很多沟通成本。Spring Boot 的自动配置和 starter 机制也让我能把更多精力放在业务逻辑而不是环境搭建上。1.3 开源许可证怎么选MIT、Apache 还是 GPL这个问题的热度非常高我在开源之前专门研究了一遍。许可证本质上是“你给使用者的权利清单”。MIT 最宽松基本上拿到源码想怎么用都行Apache 2.0 比 MIT 多加了对专利的保护条款GPL 则要求衍生作品也必须开源。做个人博客系统这种工具型项目我选了 MIT因为希望它能被最大范围地用到各种场景里包括商业用途也希望后人在改我的代码时没有心理负担。如果你做的是某个核心算法库或者希望同道中人必须回馈改进那 Apache 或者 GPL 更合适。我建议后来的开源项目在LICENSE文件之外最好再写一段简单的CONTRIBUTING说明明确告诉别人“你用我的代码时需要保留版权声明”“提交 PR 前请先跑测试”。这点很多人会漏掉但真正做起来才发现它比许可证本身更能减少后期沟通麻烦。2. 整体架构与功能清单拆解2.1 核心功能设计和优先级排序博客看起来简单真正梳理过需求后才发现这个系统至少可以拆成两块前台阅读和后台管理。前台重点是内容展示包括文章列表、文章详情、标签页、分类页、关于页、站内搜索和评论展示。后台重点则是内容生产包括登录认证、文章编辑与发布、草稿管理、标签与分类维护、评论审核和基础设置。我没有在第一版就把所有功能全部做出来而是先保证主链路通畅注册管理员账号 → 写文章 → 发布 → 前台可看 → 用户可评论。整个链路跑通之后再补搜索、标签聚合、评论审核这些增强体验的功能。如果一开始就想着把“定时发布”“文章置顶”“读者排行”这些可有可无的功能都做上很容易陷入功能蔓延的泥潭项目迟迟没法收尾。2.2 后端如何分层Controller、Service、Repository 到底怎么划分这个项目里我把后端代码分成四层controller、service、mapper/repository、entity。Controller 负责接收 HTTP 请求、参数校验和统一返回结构Service 负责业务逻辑比如“发布文章”这个动作除了写数据库还要更新缓存、刷新搜索索引Repository 层只用来做数据访问不写业务判断Entity 就是数据库表结构的映射。拿“发布文章”举例整个链路是这样的前端提交摘要、Markdown 内容、标签列表和分类 ID 到/api/articleController 校验参数后转给 ArticleServiceArticleService 先把内容写入文章表再刷新 Redis 里的文章列表缓存同时把标题和正文塞进搜索索引最后返回文章 ID。分层清晰以后出了问题能很快定位是参数问题、业务逻辑问题还是数据访问问题而不是在一个几百行的大方法里来回翻。2.3 前端路由组织与后台管理界面设计前端我用 Vue Router 做了两级路由。一级路由是/、/article/:id、/tag/:name、/search和/admin这些对应页面级的组件。二级路由主要出现在/admin下面比如/admin/dashboard、/admin/article/list、/admin/article/edit/:id、/admin/comment。后台管理界面我没有用现成的 admin 模板而是自己画了一个极简侧边栏布局。原因是开源项目如果套一个厚重的 admin 模板代码体积会很大新手理解起来也费劲。侧边栏放“文章管理”“评论管理”“标签管理”“系统设置”四个入口顶部是当前管理员的信息和退出按钮。前台则重点强化阅读体验没有多余的元素文章的排版用 CSS 做了比较精细的优化比如行高保持 1.8代码块单独用深色背景图片统一圆角。3. 核心模块的实操实现与细节解析3.1 Markdown 解析与代码高亮这是整个博客系统最核心的模块没有之一。我踩了不少 Markdown 解析的坑先说结论不要自己手写解析器直接用markdown-it。import MarkdownIt from markdown-it import hljs from highlight.js const md new MarkdownIt({ html: true, linkify: true, typographer: true, highlight(str, lang) { if (lang hljs.getLanguage(lang)) { try { return hljs.highlight(str, { language: lang }).value } catch (__) {} } return // 使用默认转义 } })这段代码里最容易被忽略的是linkify: true。开了它以后用户粘贴的裸链接https://example.com会自动变成可点击的链接这点非常影响文章阅读体验。另一个坑是html: true如果允许文章里写 HTML就必须在后端做防 XSS 过滤否则任何能发文章的人都能往页面里注入脚本。我的方案是在后端统一接了一个cleanHtml库只有从白名单里放行的标签和属性才会保留。代码高亮这块我建议把highlight.js的样式文件按需引入而不是全量引入所有语言。我一开始图省事引了全量包构建后 CSS 文件直接多出了 200KB首屏加载肉眼可见地变慢。后来改成只引入常见语言java、javascript、typescript、python、go、bash、sql、json、xml、markdown体积瞬间降下来了。3.2 评论系统的防滥用设计评论是动态功能的代表也是垃圾内容的重灾区。我没有用第三方的评论服务而是自己做了三件事来保证评论区的干净。第一件事是后端校验频率同一个 IP 一分钟内最多评论 3 条超出直接返回“操作太频繁”。这个用 Redis 的INCREXPIRE就可以实现代码也很简单。第二件事是昵称和邮箱的字段校验昵称不能含有链接特征字符邮箱必须格式正确防止有人把联系方式伪装成昵称刷进来。第三件事是人工审核开关后台可以设置“评论是否需要审核”默认是关闭但一旦发现有人乱发打开这个开关就能让所有新评论先进入待审核队列。第二点和第三点合在一起基本能挡住大部分垃圾评论。真正要防的是那些模仿正常用户发的推广内容那只能靠人工定期后台清理没有十全十美的自动方案。3.3 标签聚合与站内搜索的落地方案标签和分类是两个容易混淆的概念。我做的分类是单级树形结构一篇文章只能选一个分类适合做内容的顶层划分标签则是多对多关系一篇文章可以打多个标签强调内容之间的横向关联。数据库里建了article_tag关联表文章与标签的绑定关系都存这张表里。站内搜索的第一版用的是 MySQL 的LIKE %keyword%文章数量在几百篇时毫无压力。但我提前预留了搜索服务的接口定义好SearchService后续想切成 Elasticsearch 时只需要提供一个新实现。这也是我在架构设计里比较得意的一点先定义接口再决定实现。当项目真的跑了大半年文章超过一千篇中文分词和高亮检索变得越来越需要时我只要扩展一个基于 IK 分词器的 ES 实现替换应用里的 SearchService 即可。3.4 发布全链路的状态机设计文章状态我用了一个简单的状态机草稿、已发布、已下线、已删除。这是我在实际编码中反复体会出来的设计。状态的流转必须受控不能出现“已删除的文章还能通过接口被编辑”的诡异情况。我做了下面的约定草稿可以转为已发布已发布可以转为已下线也可以直接转为已删除已下线可以重新转为已发布已删除是终态只能通过管理员软删除恢复。这样一个状态机模型让前后端的每个按钮都对应一个明确的动作后端只暴露少数几个状态转换接口有效避免了“状态被改乱了”的问题。4. 部署上线、性能优化与运维经验4.1 用 Docker Compose 实现一键部署为了降低部署门槛我把整个项目的运行环境都容器化了。发布前只需在服务器上执行一条docker-compose up -d就能把 MySQL、Redis、后端、前端四个服务全部跑起来。这是我项目里一个非常关键的配置文件简化后如下version: 3.8 services: mysql: image: mysql:8.0 container_name: blog-mysql environment: MYSQL_ROOT_PASSWORD: your_root_password MYSQL_DATABASE: blog volumes: - ./mysql-data:/var/lib/mysql ports: - 3306:3306 restart: always redis: image: redis:7-alpine container_name: blog-redis ports: - 6379:6379 restart: always backend: build: ./backend container_name: blog-backend depends_on: - mysql - redis environment: SPRING_DATASOURCE_URL: jdbc:mysql://mysql:3306/blog?useUnicodetruecharacterEncodingutf8 SPRING_DATA_REDIS_HOST: redis ports: - 8080:8080 restart: always frontend: build: ./frontend container_name: blog-frontend depends_on: - backend ports: - 80:80 restart: always有几个细节值得注意。restart: always保证了服务挂掉后能自动拉起我现在的服务器稳定运行了一年多靠的就是它。depends_on只保证依赖容器创建顺序不保证依赖服务已经就绪所以我把后端代码里加了一个简单的重试机制连接数据库时如果失败每隔 3 秒重试一次最多重试 5 次。这个“容器依赖陷阱”很多人第一次部署都会踩最后发现后端一直连不上数据库就是因为没做连接重试。4.2 Nginx 反向代理与 HTTPS 配置前端构建后的产物是一个纯静态文件包运行在 Nginx 容器里。我通过 Nginx 把/api路径下的请求代理到后端的 8080 端口同时开启 gzip 压缩和 HTTP/2 协议。server { listen 80; server_name your-domain.com; location /api/ { proxy_pass http://backend:8080; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } location / { root /usr/share/nginx/html; index index.html; try_files $uri $uri/ /index.html; } gzip on; gzip_types text/plain text/css application/json application/javascript; }try_files $uri $uri/ /index.html;这行是前端路由能不能正常刷新页面的关键。Vue Router 的 history 模式在用户直接访问/article/123这个地址时服务端是没有这个文件的如果没配try_files刷新就 404。加上这句话之后所有不存在的路径都会回退到index.html再由前端路由接管。4.3 数据备份、日志监控和基本安全加固数据是无价的所以我把数据库备份做成了每天的定时任务。用crontab每天凌晨三点执行一次mysqldump只保留最近 7 天的备份文件同时把备份文件通过rsync同步到另一台机器上。日志监控我采用的是最省事的方案后端使用 Spring Boot Actuator 暴露健康检查端点用一个外部监控服务每 5 分钟探一次/actuator/health如果连续三次失败就发告警邮件。日志文件则统一输出到挂载目录配合 logrotate 按天切割避免单个日志文件无限膨胀。安全加固方面我做了五件事数据库不使用默认端口Redis 开启密码认证并绑定内网 IPNginx 层面对管理后台路径/admin增加 IP 白名单限制后端对上传接口限制文件类型和大小所有网站请求强制跳转到 HTTPS。前四件事成本都很低但对防护效果提升明显。最后一件事用 Certbot 申请免费证书后在 Nginx 里加一个 80 端口的 301 跳转即可。5. 开源全过程从首个 Release 到社区维护5.1 开源前的准备文档、Demo、Code of Conduct我把代码拉到一个公开仓库之前先花了整整一周的时间做文档。很多开源项目的文档写得像天书README 里只有一个项目名字和一张截图让人完全没有参与的欲望。我的 README 里包含这么几个部分项目介绍、核心功能清单、技术栈说明、目录结构、快速开始本地启动 Docker 部署两种方式、截图预览、常见问题解答、贡献指南和许可证声明。特别要说的是目录结构这一块因为很多新手拿到源码最困惑的不是代码逻辑而是“文件太多了我该从哪里看起”。我在 README 里专门画了一棵树标清楚backend、frontend、docs、scripts各是什么然后建议新人从后端controller包开始读起因为那是用户请求的入口。尽可能降低别人阅读源码的门槛才更有可能获得真实反馈和贡献。我还写了一个CONTRIBUTING.md里面说明了两件事提交 issue 时请提供完整的环境信息和复现步骤提交 PR 前请先拉最新的 main 分支并补充对应的单元测试。这两条规定看着简单实际执行下来确实过滤掉了很多没有价值的 issue 和半成品 PR。5.2 第一个 Release 与版本号规划发布开源项目版本号不是随便写的。我遵循 SemVer 语义化版本规范主版本号表示不兼容的 API 变更次版本号表示向后兼容的功能新增补丁版本号表示向后兼容的问题修复。第一版是1.0.0然后按功能迭代正常推进。版本发布前我做了三件事更新CHANGELOG.md记录新增和修复在 Git 仓库打上v1.0.0标签写一份 release notes 重点说明“这个版本能干什么”“和上一版比改了什么”“怎么升级”。一开始我也觉得维护 changelog 很麻烦但后来有一个用户提了一个 issue说他从0.9.0升到1.0.0后文章页面变成空白我很快意识到是因为我改了返回数据结构的字段名而这个变更在 changelog 里没有写清楚。从那以后我把 changelog 当作和代码一样重要的交付物。5.3 维护社区Issue 模板、PR 合入和 Roadmap 公开开源项目不是把代码扔上去就结束了维护社区才是最消耗精力的部分。我给仓库配置了 issue 模板分“Bug 反馈”和“功能建议”两种把用户最容易漏掉的信息强制结构化。这样拿到的问题描述普遍很清晰不会出现“我的博客打不开了”这种让人无从下手的话。PR 合入方面我坚持三个原则必须通过 CI 检查、必须有测试覆盖、必须描述改动动机和影响范围。如果 PR 只是改了几个文件没有任何说明我会礼貌地打回去请他补充内容。这看起来有点严格但经历过一次“合入一个 PR 导致整站打不开”的事故之后我宁愿多花时间在流程上也不愿用线上事故换所谓的高效。Roadmap 这块我直接在 README 里公开了未来的计划计划支持的主题系统、计划支持的图床集成、计划支持的多语言国际化。公开 Roadmap 的最大好处是社区成员不会重复提你已经规划过的需求也会把你没考虑到但是大家都需要的功能补充进来。整个过程很像是在做一个公共产品而不仅仅是一份代码。6. 高频踩坑与问题排查速查6.1 中文乱码、时区问题、Markdown 异常这几个老大难中文乱码是博客项目最容易遇到的问题而且出现的时机总让人抓狂。根因一般是三处没有对齐数据库连接串没写characterEncodingutf8、数据库表默认字符集不是utf8mb4、后端返回数据时响应头没声明 UTF-8。只要这三处统一了乱码问题基本能根除。时区问题也常见。Spring Boot 默认时区是 UTCMySQL 默认时区是系统时区两者不一致会导致文章发布时间和实际时间相差 8 小时。我建议统一采用Asia/Shanghai时区在数据库连接串里加serverTimezoneAsia/Shanghai然后在后端全局配置里强制指定时区。这样不管部署在哪台服务器上时间显示都不会出错。Markdown 解析出问题大多集中在三种场景代码块里包含 Markdown 特殊字符、嵌套列表渲染异常、表格语法兼容性差异。我用markdown-it解决了一大半问题剩下的是靠测试用例来覆盖的。我在项目里放了一个test-markdown.md文件里面全是最容易出错的语法每次升级解析库都拿它做回归测试。6.2 常用问题速查表我自己整理了一份问题速查表放到项目文档里现在已经成了仓库里阅读量最高的文件之一。现象可能原因解决方案文章列表是空的数据库表没初始化检查schema.sql是否执行成功发布文章后前台看不到缓存未刷新清理 Redis 中article:list缓存键评论提交报 429频率限制触发等待 1 分钟或调整限流阈值图片上传失败上传目录权限不足确认upload目录对容器用户可写博客页面刷新 404Nginx 未配置try_files按示例补全 location 配置后台登录无效JWT 密钥不一致统一前后端与后端环境变量中的密钥搜索无结果搜索索引未构建调用管理端“重建索引”接口这张表的价值在于它把所有验证过的解决方案集中成一个入口节省了用户反复提问的时间也让项目的维护成本下降了一个层级。6.3 兜底精神日志、测试、回滚最后聊一个我在整个开发和开源过程中体会最深的东西就是“兜底”。写日志是为了能回看现场写测试是为了敢改代码做备份是为了能回滚服务。这三件事在博客这种小项目里看起来不是刚需但只要你想把项目持续做下去它们就是把不确定性降到最低的筹码。我现在的习惯是任何新功能提交前先把日志加好把核心接口的单元测试补上把升级和回滚步骤写进CHANGELOG。这套流程看起来增加了工作量但长远来看省下的时间绝对物超所值。开源一个个人博客系统技术上并不复杂但它带来的收获远超我的预期。你会慢慢理解一个项目从“能跑”到“好用”再到“别人愿意贡献”分别意味着什么也会在维护社区的过程中学到很多编程之外的东西。如果这篇文章能让你对自建博客或开源维护少一些焦虑多一些下场的动力那它就没有白写。
