1. 项目概述RuleAppV2是什么为什么值得关注这段时间我把 RuleApp 做了一次大版本重写RuleAppV2 正式发布了前后端代码全部开源。简单说这是一套面向“多功能综合内容社区”场景的整站解决方案你拿过去就能跑起来一个社区也可以按自己的业务需求去改而不是像很多开源项目那样改了前端还得重写后端或者反过来。先说清楚它到底解决什么问题。如果你做独立开发或者运营一个垂直领域的站点大概率会遇到一个尴尬现成的建站系统要么太重功能堆了一堆你根本用不上后台卡得不行要么太轻连最基本的会员体系、内容分类、搜索都要自己写。RuleAppV2 的定位正好卡在这两者之间——核心功能完整内容发布、多栏目管理、用户体系、评论互动、搜索标签、后台管理但代码结构不绕二次开发成本可控。适合谁来参考也很明确一是想快速搭一个内容社区/资源站/产品官网社区混合型站点的人二是想学完整前后端分离项目怎么组织代码、怎么设计权限、怎么处理部署的中高级开发者三是正在找可商用合规开源协议的项目做业务基座的小团队。我一直强调一个观点看开源项目不要只看功能列表要看它的“设计决策”和“边界感”。RuleAppV2 这次重构核心就是把“内容模型”做得足够通用同时把“业务插件”做了隔离。这篇文章我会从设计思路、前端实现、后端架构、部署实战、踩坑记录几个角度展开把我这次重构过程中比较关键的决策和代码细节都讲一遍你可以直接照着复现。2. 整体设计思路为什么这样拆功能边界怎么划2.1 从“单一内容类型”到“多内容形态”的转变RuleApp 第一版其实只支持单一的文章类型就是一个普通的博客系统加了个会员登录。但实际用下来我发现社区类站点的内容形态是很多样的有人发长文有人发短动态有人传资源文件还有人只是发起一个提问。如果所有内容都塞进一张 articles 表加上一个 type 字段去区分前期能用后期查询、列表、权限控制会越写越别扭。RuleAppV2 在数据模型层做了比较大的调整内容表拆成了两类——主内容表和内容扩展表。主内容表记录所有内容公共的属性作者、栏目、状态、发布时间、置顶权重等扩展表按内容形态去存差异化字段比如资源的下载链接、问答的悬赏积分、短动态的纯文本内容。这种“公共核心 按类型扩展”的设计在业界叫做单表继承的变体好处是列表页只需要查主表不需要连一堆 JOIN性能开销小同时每种内容形态又能保留自己的独有字段。这样设计的直接收益是添加一种新内容形态时不需要改主表结构只需要新增一张扩展表再在代码里注册一下类型映射即可。我这次做活动公告、资源分享、问答讨论三个模块都是这种模式整体开发周期比第一版缩短了大概三分之一。2.2 前端后端分离但不过度微服务化选型的时候我考虑过两个方向一个是传统的服务端渲染比如用模板引擎直接输出页面另一个是前后端完全分离前端 SPA 后端 API。RuleAppV2 最后选了后者。原因很直接内容社区的前端交互形态太复杂了。列表滚动加载、评论实时回复、编辑器状态管理、用户面板的动态更新如果用服务端渲染每交互一次都要刷新页面或者写大量 jQuery维护成本会很高。前后端分离后前端专注于交互状态后端只做数据和服务职责非常清晰。但我要特别说一下前后端分离不等于微服务。RuleAppV2 后端仍然是一个单体应用只是按模块分包管理。我见过很多项目规模不大一上来就上微服务注册中心、网关、配置中心一套搞下来部署和 debug 成本直接翻倍最后业务的迭代速度反而被架构拖累。对于大多数中小型内容社区来说单体 清晰模块边界是性价比最高的方案。真要到了需要拆服务的阶段按模块边界切分也是顺水推舟的事。2.3 系统角色与权限模型的设计重点内容社区最麻烦的不是写内容功能而是权限控制。RuleAppV2 的权限模型我参考了 RBAC基于角色的访问控制的主流实现但做了简化。系统定义了四种内置角色超级管理员、栏目管理员、认证作者、普通会员。超级管理员管全站配置和所有内容栏目管理员只能管理自己负责的栏目的内容和评论认证作者可以发布内容到有权限的栏目普通会员默认只能浏览和评论发布内容需要申请认证。操作权限精确到按钮级别。比如“审核通过”这个按钮后端接口会同时校验“当前用户是否有该栏目的管理权限”和“该内容的状态是否为待审核”两者缺一不可。前端只是做显示控制后端才是真正的安全边界这一点在开发时必须刻到骨子里一切前端限制都是用户体验后端校验才是安全底线。3. 前端核心实现技术栈选型与关键模块拆解3.1 技术栈选择Vue3 TypeScript Pinia前端技术栈最终定为 Vue3 TypeScript Pinia ViteUI 库用的是 Naive UI。这套组合在这两年基本可以算是 Vue 生态的“标准答案”了但选择它们并不只是因为流行。Vue3 的组合式 API 对复杂状态逻辑的复用非常友好。比如内容编辑器里涉及的草稿自动保存、图片上传进度、Tag 动态输入如果用选项式 API 写这些逻辑会在 data/methods/watch 之间来回跳可读性很差。用组合式函数Composable可以把这些逻辑全部封装到独立的文件里组件内只负责任务编排代码结构会干净很多。TypeScript 是这次重构的一个重要决定。内容社区的数据结构相对复杂一个内容对象可能有作者信息、栏目信息、扩展字段、标签数组如果没有类型约束前后端联调时 bug 率会明显上升。TypeScript 的 interface 可以直接和后端返回的 JSON 结构对齐编辑器里就能发现字段拼写错误、类型不匹配这类低级问题这比运行时才发现错误要省力得多。Pinia 相比 Vuex 最大的优势是对 TypeScript 的天然支持和简化的 API。Vuex 写起来要定义 state/mutations/actions/getters 四件套修改状态的唯一途径是 commit这在大型团队协作中确实是规范但中小型项目的开发效率会被拖慢。Pinia 允许直接修改 state同时保留了 devtools 追踪能力对个人开发和几个人的小团队都更友好。3.2 页面架构与路由组织RuleAppV2 的前端页面分为三大块用户端前台、用户中心、管理后台。这三块虽然在一个项目里但路由和布局是完全分开的。用户端前台是访客和普通用户看到的部分包括首页、栏目列表、内容详情、搜索页、登录注册页。布局上顶部是导航栏和搜索框中间是内容区域底部是页脚右侧有侧边栏展示热门内容和推荐用户。用户中心是登录后用户管理自己资产的区域包括个人资料、我的发布、我的评论、我的收藏、消息通知。这一块的布局是左侧菜单 右内容区的经典结构。管理后台只对管理员和栏目管理员开放包含仪表盘、内容管理、评论管理、用户管理、栏目管理、站点配置。路由层面通过导航守卫做权限过滤没有对应角色的用户访问会跳转到 404 页面。一个要注意的细节是前端路由守卫只是减少无效请求真正能不能访问数据是后端接口在控制的这个我再强调一次前后端分离的项目权限主要靠后端守。3.3 多功能内容的列表与详情设计现在的首页信息流是 RuleAppV2 比较有辨识度的模块。它把文章、资源、问答、动态四种形态的内容混在一个时间流里卡片会根据内容类型展示不同的附加信息文章卡片显示阅读量和分类标签资源卡片显示下载量和文件大小问答卡片显示回答数和悬赏积分动态卡片则直接展示纯文本内容。这种混合信息流实现的难点在于不同的内容类型在列表里展示的信息不同且需要支持点击跳转到对应的详情页。我的方案是主内容表查询完毕后前端拿到统一的 ContentItem 结构其中包含 type 字段和一个可选的 extension 字段前端根据 type 去动态渲染不同的卡片组件。组件注册表是一个 Recordstring, Component 的映射新加内容形态时只需要添加一个组件并注册到这个映射表里其他部分不用动。详情页的思路类似不过更重要的是 SEO 的处理。因为前台是 SPA搜索引擎默认爬取到的只有空壳 HTML对内容收录很不友好。我的做法是对前台页面启用预渲染Prerendering构建时把内容详情的静态 HTML 生成出来这样搜索引擎拿到的就是完整页面内容。这个在部署部分我会讲具体怎么配置。3.4 状态管理与用户会话保持用户登录态用的是 JWT 刷新令牌的双令牌方案。访问令牌有效期设置得比较短2小时刷新令牌有效期 14 天。前端 axios 实例统一封装了请求拦截器和响应拦截器。请求拦截器负责把当前用户的访问令牌加到请求头 Authorization: Bearer xxx。响应拦截器检查返回的状态码如果遇到 401说明访问令牌过期了此时会用刷新令牌去请求 /auth/refresh 接口换取新令牌然后自动重放刚才失败的请求。如果刷新令牌也过期了就清除本地登录态跳转到登录页。这里有一个小坑要提醒多个接口几乎同时返回 401 时如果每个接口都触发一次 refresh 请求会浪费大量请求。正确的做法是做一个“正在进行刷新”的全局状态标记在刷新过程中其他 401 请求排队等待刷新成功后统一重放。这个模式在社区里俗称“单例刷新”实际开发中很常见。4. 后端架构解析数据库设计、权限校验与内容服务4.1 后端技术栈与模块划分后端我用的 Spring Boot 3 MyBatis-Plus MySQL Redis。Spring Boot 就不多解释了这个生态的成熟度和第三方库覆盖基本是 Java 服务端的首选。MyBatis-Plus 对单表 CRUD 的简化程度很高配合自定义 SQL 处理复杂查询比全自动 ORM比如 JPA在复杂查询场景下要可控得多。模块分包上我按业务域拆成了几个核心模块用户模块注册、登录、资料、关注、内容模块发布、编辑、审核、列表、评论模块评论、回复、点赞、搜索模块ES 与 MySQL 的同步策略、消息模块站内通知、系统消息、统计模块PV/UV、内容热度计算。这里重点说内容模块。内容发布是社区产品最核心的链路一旦内容量上来查询性能、敏感词过滤、图片处理、缓存更新都是要提前考虑的问题。RuleAppV2 的内容服务里我做了几个设计内容状态机草稿 - 待审核 - 已发布 / 已驳回 / 已下架。状态流转由代码控制流转方法不允许直接改状态字段。双写一致性发布内容时先写 MySQL 落库再异步刷新 Redis 缓存。列表接口优先读缓存缓存未命中再回源数据库同时回填缓存。内容热度计算热度分 阅读量0.4 评论数0.3 点赞数0.2 新鲜度衰减0.1。热度分在服务端定时计算排序时直接取用避免每次请求都实时计算。4.2 数据库表设计的关键决策数据库表设计是这次重构中最费力的一部分。我直接贴出几张核心表的核心结构省略了通用审计字段-- 用户主表 CREATE TABLE user ( id bigint PRIMARY KEY AUTO_INCREMENT, username varchar(50) NOT NULL UNIQUE, password_hash varchar(255) NOT NULL, avatar_url varchar(500), bio varchar(500), role varchar(20) NOT NULL DEFAULT USER, status tinyint NOT NULL DEFAULT 1, points int NOT NULL DEFAULT 0, created_at datetime NOT NULL, updated_at datetime NOT NULL ); -- 栏目表 CREATE TABLE category ( id bigint PRIMARY KEY AUTO_INCREMENT, name varchar(50) NOT NULL, slug varchar(80) NOT NULL UNIQUE, parent_id bigint DEFAULT 0, sort_order int NOT NULL DEFAULT 0, status tinyint NOT NULL DEFAULT 1 ); -- 主内容表 CREATE TABLE content ( id bigint PRIMARY KEY AUTO_INCREMENT, user_id bigint NOT NULL, category_id bigint NOT NULL, type varchar(20) NOT NULL, title varchar(200), summary varchar(500), status varchar(20) NOT NULL DEFAULT DRAFT, view_count int NOT NULL DEFAULT 0, like_count int NOT NULL DEFAULT 0, comment_count int NOT NULL DEFAULT 0, heat_score decimal(10,4) NOT NULL DEFAULT 0, sticky_weight int NOT NULL DEFAULT 0, published_at datetime, created_at datetime NOT NULL, updated_at datetime NOT NULL, KEY idx_category_status (category_id, status), KEY idx_user_id (user_id), KEY idx_published_at (published_at), KEY idx_heat_score (heat_score) ); -- 内容扩展表文章 CREATE TABLE content_article ( id bigint PRIMARY KEY AUTO_INCREMENT, content_id bigint NOT NULL UNIQUE, content_md longtext, content_html longtext, cover_image varchar(500) ); -- 内容扩展表资源 CREATE TABLE content_resource ( id bigint PRIMARY KEY AUTO_INCREMENT, content_id bigint NOT NULL UNIQUE, file_url varchar(500) NOT NULL, file_size bigint NOT NULL DEFAULT 0, download_count int NOT NULL DEFAULT 0, extract_code varchar(20) ); -- 评论表 CREATE TABLE comment ( id bigint PRIMARY KEY AUTO_INCREMENT, content_id bigint NOT NULL, user_id bigint NOT NULL, parent_id bigint DEFAULT 0, content text NOT NULL, status tinyint NOT NULL DEFAULT 1, like_count int NOT NULL DEFAULT 0, created_at datetime NOT NULL, KEY idx_content_id (content_id), KEY idx_user_id (user_id) );几个关键设计的意图说一下主表不存具体正文只存公共属性。这样列表查询只要标题、摘要、作者、时间不会去读正文大字段IO 开销大幅下降。这是很多内容系统性能问题的根源——列表页查了全表的大文本字段。article 的正文同时存 Markdown 原文和渲染后的 HTML。这是为了编辑时回显原文展示时直接用 HTML避免每次请求都做一次 Markdown 渲染。你可以选择在编辑保存时就渲染并持久化也可以在读取时按需渲染前者多占存储后者多占 CPU这里我选的是前者。content 表加了 published_at 字段而不用 created_at。因为草稿、定时发布的存在内容的“发布时间”和“创建时间”是两个概念不能用错了。4.3 认证与授权的实现细节用户密码存储用的是 BCrypt 算法这个不需要自己实现Spring Security 自带 BCryptPasswordEncoder。使用 BCrypt 的一个好处是每次哈希都会自动加盐而且同一个密码每次算出来的哈希值都不同如果要再加一层保险可以在用户表中再存一个随机盐值字段。登录成功后签发 JWT密钥存在配置文件中生产环境必须通过环境变量注入不要硬编码到代码或提交到 Git。JWT 的 payload 里只放用户 id 和角色不放其他敏感信息。权限校验我的实现方式是自定义 Spring MVC 的 HandlerInterceptor在拦截器中读取用户的角色用注解RequireRole(ADMIN)标记接口需要的权限拦截器通过反射拿到注解后做比对。这样比在业务代码里写 if 判断要集中、优雅得多新增接口时只需要加一行注解权限逻辑不会散落在各个 Controller 里。还有一个容易被忽略的点数据权限。比如栏目管理员调“删除内容”接口如果只校验了角色是“栏目管理员”那他可以删除任何栏目的内容。正确做法是先查出这条内容的 category_id再去判断这个管理员有没有该栏目的管理权。这种按数据归属的权限校验我是在 service 层做的拦截器里做不了因为涉及具体业务数据。4.4 敏感词过滤与内容审核内容社区的合规要求必须重点说。RuleAppV2 的敏感词过滤我实现了两层第一层是发布时的异步检测配合第三方API做文本审核第二层是人工审核队列管理员可以在后台对已发布内容进行复核。自建的敏感词库用 DFA确定性有限自动机算法实现把敏感词列表构造成一颗 Trie 树匹配时一趟扫描就能找出文本中的命中的词。这套算法在 GitHub 上有不少现成实现可以借鉴我基于彼方的思路做了一个修改版核心逻辑是把敏感词按长度分组再用哈希表加速查找实测在几万词库下单条文本匹配耗时在毫秒级。这个异步检测流程是这样的用户在编辑器点击发布 - 内容先保存为待审核状态 - 写一条审核任务到 MQ - 消费者收到后调用第三方文本审核接口 - 如果含有违规内容状态自动变为已驳回并通知用户 - 如果通过状态变为已发布。整个流程对用户是无感知的提交后 1~2 秒内状态自动更新。5. 部署实战从源码下载到线上可访问5.1 环境准备与依赖安装RuleAppV2 的部署依赖以下环境软件版本要求用途JDK17后端运行环境Maven3.8后端构建Node.js16.20前端构建MySQL8.0主数据库Redis6.0缓存与会话Nginx1.20静态资源与反向代理服务器我建议至少 2 核 4G 内存硬盘 40G 起步。1 核 2G 的小鸡也能跑但 MySQL Redis Java 应用同时跑会比较紧张搜索服务如果后续要上会比较吃力。建议部署顺序先装 MySQL 和 Redis再初始化数据库再启动后端最后构建前端部署到 Nginx。5.2 后端部署数据库初始化、配置修改与启动克隆代码后后端工程里有一个sql/init.sql文件里面是建库建表语句和初始数据默认栏目、管理员账号。建议在 MySQL 中先创建数据库CREATE DATABASE ruleapp CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;然后导入 init.sql。这里有几个重要配置要改在application-prod.yml里spring: datasource: url: jdbc:mysql://127.0.0.1:3306/ruleapp?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/Shanghai username: your_mysql_user password: your_mysql_password redis: host: 127.0.0.1 port: 6379 password: your_redis_password jwt: secret: your-random-64-char-secret-key expire-hours: 2 refresh-expire-days: 14JWT secret 这里一定要改掉默认值并且长度不小于 32 个字符。用默认值意味着任何人都可以用你公开的密钥签发有效的 JWT等于登录接口暴露了。生产环境建议用环境变量注入这些配置不要让真实密码出现在配置文件中。初始化完成后执行构建mvn clean package -DskipTests生成的 jar 包在target/ruleapp-server.jar用 systemd 守护进程管理启动还是直接用 nohup 都行我习惯于用 systemd 服务的方式方便崩溃后自动拉起、开机自启、日志统一管理。5.3 前端部署构建产物与 Nginx 配置前端构建之前需要修改 API 地址配置。在.env.production文件中配置VITE_API_BASE_URL/api我建议前端开发时走代理生产环境走 Nginx 反向代理也就是前端只配置/api这种相对路径由 Nginx 把 /api 的请求转发到后端的 8080 端口。这样有几个好处前后端部署在同一域名下不涉及跨域以后就算换后端地址前端不需要重新构建。执行构建npm install npm run build构建产物在dist/目录把它放到 Nginx 的 web 目录比如/var/www/ruleapp。然后配置 Nginxserver { listen 80; server_name your-domain.com; root /var/www/ruleapp; index index.html; # 前端路由history 模式下所有路径都回退到 index.html location / { try_files $uri $uri/ /index.html; } # API 反向代理 location /api/ { proxy_pass http://127.0.0.1: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 /uploads/ { alias /var/www/ruleapp/uploads/; expires 30d; add_header Cache-Control public; } }注意proxy_pass http://127.0.0.1:8080/;末尾这个斜杠很重要它表示把/api前缀去掉后转发。比如请求/api/content/list最终后端收到的是/content/list。如果后端接口本身带/api前缀那这里就不要加斜杠这个细节设错了会导致 404。5.4 预渲染配置与 SEO 优化前面提到前台 SPA 对 SEO 不友好我的解决方案是用 vite-plugin-prerender 做构建时的预渲染。这个插件会在构建完成后启动一个无头浏览器访问配置的路由列表把渲染出的 HTML 保存到对应的 dist 路径下。预渲染的路由配置// vite.config.ts prerenderer: { routes: [/, /category/article, /category/resource, /about], renderer: new Prerenderer({ headless: true, renderAfterTime: 500, postProcess(context) { // 在这里可以注入 meta 描述、og 标签等 return context; } }) }需要注意预渲染只是在构建时把静态页面生成出来动态内容比如最新文章列表有可能在生成时是空的。所以预渲染更适用于内容不经常变的页面或者只预渲染首页框架、活动页这类半静态页面。对于内容详情页这种高频动态页面更好的方案是用 Nginx 的 SSI 技术做服务端包含或者在内容发布时同步生成静态 HTML。我目前是把内容详情页发布时同步生成静态页策略上更可控。5.5 Docker Compose 一键部署为了方便不想折腾环境的用户我还提供了 Docker Compose 编排文件。一条命令就能启动 MySQL、Redis、后端、前端四个服务docker compose up -d编排文件的思路是MySQL 和 Redis 用官方镜像挂载数据卷持久化后端镜像用多阶段构建第一阶段 Maven 编译第二阶段用 JRE 运行前端镜像用 Nginx 官方镜像把构建产物 COPY 进去再覆盖默认配置。整个编排文件的核心部分services: mysql: image: mysql:8.0 environment: MYSQL_ROOT_PASSWORD: rootpass MYSQL_DATABASE: ruleapp MYSQL_USER: ruleapp MYSQL_PASSWORD: ruleapppass volumes: - mysql_data:/var/lib/mysql ports: - 3306:3306 redis: image: redis:7-alpine command: redis-server --requirepass redispass volumes: - redis_data:/data backend: build: ./server depends_on: - mysql - redis environment: SPRING_PROFILES_ACTIVE: prod DB_HOST: mysql DB_PASSWORD: ruleapppass REDIS_PASSWORD: redispass JWT_SECRET: change-me-in-production ports: - 8080:8080 frontend: build: ./web depends_on: - backend ports: - 80:80Docker 部署的一个坑是容器间的网络通信。容器里访问 MySQL 不能用127.0.0.1要使用服务名比如mysql这是 Docker 内置 DNS 解析的规则。所以后端配置里要把数据库地址改成jdbc:mysql://mysql:3306/ruleapp而不是127.0.0.1。我一度在这上面卡了半小时排查了半天才发现是配置写错了。6. 常见问题与排查技巧实录6.1 问题速查表症状可能原因解决办法前端请求接口 404Nginx proxy_pass 末尾斜杠配置不对检查location /api/的 proxy_pass 是否带斜杠登录后很快失效前后端服务器时间不同步统一用 NTP 同步时间检查 JWT 签发时间和验证时间的时区图片上传本地路径无法访问Nginx 没有配置 /uploads/ 的 alias在 Nginx 中添加静态文件映射内存占用过高JVM 堆内存配置过小或过大调整 JVM 参数-Xms和-Xmx建议设置为物理内存的 1/4列表接口响应慢缓存未生效或索引缺失检查 Redis 是否连通查询 EXPLAIN 看 SQL 是否走索引静态资源加载慢未开启 Gzip 和缓存Nginx 开启 gzip on静态资源配置 expires定时任务重复执行多实例部署但没有分布式锁单实例部署或引入分布式锁保证同时只有一个实例执行6.2 部署环境问题8080 端口被占用上线时候遇到的一个问题后端 jar 启动后8080 端口一直提示被占用启动失败。查了下服务器原来是一个残留的 Java 进程占用了端口。排查命令lsof -i :8080找到占用进程 PID 后确认是废弃进程直接kill -9 PID然后重新启动 spring boot 服务。生产环境部署时如果有多套服务都在监听端口建议把每个服务的端口、进程 PID、启动命令都记录在运维文档里不然问题出现时排查确实费事。6.3 开发调试问题跨域请求被拦截本地开发时前端是 Vite 的 5173 端口后端是 8080跨域是不可避免的。我的做法是前端所有请求走 Vite 代理不启用后端的 CORS 配置。Vite 配置文件中的代理设置// vite.config.ts server: { proxy: { /api: { target: http://127.0.0.1:8080, changeOrigin: true, rewrite: (path) path.replace(/^\/api/, ) } } }把跨域问题留到 Nginx 层处理而不是在后端开启 CORS主要原因是上线后前后端是同域部署后端开 CORS 没有意义且可能带来安全隐患。开发时用代理生产时用 Nginx 反向代理统一在网关层解决跨域后端代码可以保持纯净。6.4 内容发布问题富文本图片插入失败还有一个比较隐蔽的坑就是富文本编辑器里插入图片时图片文件传到后端的大小超出了 Spring 的默认限制。Spring Boot 默认上传文件大小上限是 1MB超出会被拦截并报错。修改配置spring: servlet: multipart: max-file-size: 10MB max-request-size: 10MB但如果图片是 base64 编码后直接塞进 JSON 提交的这个限制对 JSON 体不生效需要另行检查云服务器的请求体大小限制比如 Nginx 的client_max_body_size。我建议图片一律走独立的上传接口返回 URL 后再把 URL 插入编辑器而不是 base64 内嵌既不占请求体体积也方便以后接入 CDN。7. 开源协议与后续规划RuleAppV2 采用 MIT 协议开源意味着你可以自由使用、修改、商用只需要保留版权声明。我选择 MIT 而不是 GPL 的考虑是内容社区在很多场景下是商业产品的一部分如果后续有人基于它做商业项目GPL 会让闭源集成变得麻烦。MIT 协议在开源和商业之间做了最好的平衡。当然这也意味着开源项目无法强制要求使用者回馈代码所以项目的生命力很大程度上依赖社区的自发贡献。后续的迭代方向我列了几个第一个是搜索模块升级当前是基于 MySQL 的模糊匹配数据量上来后打算迁移到独立搜索引擎会涉及构建索引、同步策略、中文分词。第二个是消息通知系统目前只是站内信和邮件后续要支持 webhook 和可选的小程序推送方便社区运营方接入自己的通知渠道。第三个是主题系统标准化目前前端主题是硬编码的我计划做成可配置的主题包让非技术用户也能在后台切换风格。如果你感兴趣的话可以 clone 仓库跑起来看看从 README 开始按文档走一遍部署流程有任何问题可以直接提 issue 或者进交流群反馈。开源项目最怕的是作者写完了就扔在那里不维护我这边至少会保持月度迭代节奏社区提的合理需求会排期处理。这也是我开源这个项目的初衷一个人用这个东西价值有限一套系统被很多人用在各种不同场景里才算真正有了生命力。8. 关于开源项目的维护心得个人体会这次把 RuleAppV2 完整重构并开源整个过程收获很大。写业务代码其实不难难的是做取舍哪些功能必须进核心哪些应该做成插件哪些模块要做得抽象哪些可以直接写死哪些依赖可以引入哪些必须自己造轮子。这些决策贯穿了整个开发周期每一处都在考验对项目的整体把控能力。踩过几次坑之后我的体会是开源项目最忌讳闭门造车。第一版的时候我就是按照自己的想象去设计功能结果用户提的需求跟我的设计有比较大的出入。V2 在设计阶段我参考了不少同类社区产品的反馈区把高频需求列出来逐个判断哪些必须做进核心、哪些可以做扩展。这类信息价值很高因为它反映的是真实用户的实际使用场景不是自己拍脑袋想出来的需求。最后再分享一个小技巧对于开源项目的文档不只是 README 要写清楚最好在项目里附带一个docs/deploy-guide.md把部署步骤、常见错误、截图、视频链接全部整理进去。很多用户第一次接触项目时最先打开的就是部署文档如果这一步不顺畅基本就劝退了。文档写得好项目的接受度和 star 增长速度会有非常明显的区别。 RuleAppV2开源：前后端分离多功能内容社区整站方案
1. 项目概述RuleAppV2是什么为什么值得关注这段时间我把 RuleApp 做了一次大版本重写RuleAppV2 正式发布了前后端代码全部开源。简单说这是一套面向“多功能综合内容社区”场景的整站解决方案你拿过去就能跑起来一个社区也可以按自己的业务需求去改而不是像很多开源项目那样改了前端还得重写后端或者反过来。先说清楚它到底解决什么问题。如果你做独立开发或者运营一个垂直领域的站点大概率会遇到一个尴尬现成的建站系统要么太重功能堆了一堆你根本用不上后台卡得不行要么太轻连最基本的会员体系、内容分类、搜索都要自己写。RuleAppV2 的定位正好卡在这两者之间——核心功能完整内容发布、多栏目管理、用户体系、评论互动、搜索标签、后台管理但代码结构不绕二次开发成本可控。适合谁来参考也很明确一是想快速搭一个内容社区/资源站/产品官网社区混合型站点的人二是想学完整前后端分离项目怎么组织代码、怎么设计权限、怎么处理部署的中高级开发者三是正在找可商用合规开源协议的项目做业务基座的小团队。我一直强调一个观点看开源项目不要只看功能列表要看它的“设计决策”和“边界感”。RuleAppV2 这次重构核心就是把“内容模型”做得足够通用同时把“业务插件”做了隔离。这篇文章我会从设计思路、前端实现、后端架构、部署实战、踩坑记录几个角度展开把我这次重构过程中比较关键的决策和代码细节都讲一遍你可以直接照着复现。2. 整体设计思路为什么这样拆功能边界怎么划2.1 从“单一内容类型”到“多内容形态”的转变RuleApp 第一版其实只支持单一的文章类型就是一个普通的博客系统加了个会员登录。但实际用下来我发现社区类站点的内容形态是很多样的有人发长文有人发短动态有人传资源文件还有人只是发起一个提问。如果所有内容都塞进一张 articles 表加上一个 type 字段去区分前期能用后期查询、列表、权限控制会越写越别扭。RuleAppV2 在数据模型层做了比较大的调整内容表拆成了两类——主内容表和内容扩展表。主内容表记录所有内容公共的属性作者、栏目、状态、发布时间、置顶权重等扩展表按内容形态去存差异化字段比如资源的下载链接、问答的悬赏积分、短动态的纯文本内容。这种“公共核心 按类型扩展”的设计在业界叫做单表继承的变体好处是列表页只需要查主表不需要连一堆 JOIN性能开销小同时每种内容形态又能保留自己的独有字段。这样设计的直接收益是添加一种新内容形态时不需要改主表结构只需要新增一张扩展表再在代码里注册一下类型映射即可。我这次做活动公告、资源分享、问答讨论三个模块都是这种模式整体开发周期比第一版缩短了大概三分之一。2.2 前端后端分离但不过度微服务化选型的时候我考虑过两个方向一个是传统的服务端渲染比如用模板引擎直接输出页面另一个是前后端完全分离前端 SPA 后端 API。RuleAppV2 最后选了后者。原因很直接内容社区的前端交互形态太复杂了。列表滚动加载、评论实时回复、编辑器状态管理、用户面板的动态更新如果用服务端渲染每交互一次都要刷新页面或者写大量 jQuery维护成本会很高。前后端分离后前端专注于交互状态后端只做数据和服务职责非常清晰。但我要特别说一下前后端分离不等于微服务。RuleAppV2 后端仍然是一个单体应用只是按模块分包管理。我见过很多项目规模不大一上来就上微服务注册中心、网关、配置中心一套搞下来部署和 debug 成本直接翻倍最后业务的迭代速度反而被架构拖累。对于大多数中小型内容社区来说单体 清晰模块边界是性价比最高的方案。真要到了需要拆服务的阶段按模块边界切分也是顺水推舟的事。2.3 系统角色与权限模型的设计重点内容社区最麻烦的不是写内容功能而是权限控制。RuleAppV2 的权限模型我参考了 RBAC基于角色的访问控制的主流实现但做了简化。系统定义了四种内置角色超级管理员、栏目管理员、认证作者、普通会员。超级管理员管全站配置和所有内容栏目管理员只能管理自己负责的栏目的内容和评论认证作者可以发布内容到有权限的栏目普通会员默认只能浏览和评论发布内容需要申请认证。操作权限精确到按钮级别。比如“审核通过”这个按钮后端接口会同时校验“当前用户是否有该栏目的管理权限”和“该内容的状态是否为待审核”两者缺一不可。前端只是做显示控制后端才是真正的安全边界这一点在开发时必须刻到骨子里一切前端限制都是用户体验后端校验才是安全底线。3. 前端核心实现技术栈选型与关键模块拆解3.1 技术栈选择Vue3 TypeScript Pinia前端技术栈最终定为 Vue3 TypeScript Pinia ViteUI 库用的是 Naive UI。这套组合在这两年基本可以算是 Vue 生态的“标准答案”了但选择它们并不只是因为流行。Vue3 的组合式 API 对复杂状态逻辑的复用非常友好。比如内容编辑器里涉及的草稿自动保存、图片上传进度、Tag 动态输入如果用选项式 API 写这些逻辑会在 data/methods/watch 之间来回跳可读性很差。用组合式函数Composable可以把这些逻辑全部封装到独立的文件里组件内只负责任务编排代码结构会干净很多。TypeScript 是这次重构的一个重要决定。内容社区的数据结构相对复杂一个内容对象可能有作者信息、栏目信息、扩展字段、标签数组如果没有类型约束前后端联调时 bug 率会明显上升。TypeScript 的 interface 可以直接和后端返回的 JSON 结构对齐编辑器里就能发现字段拼写错误、类型不匹配这类低级问题这比运行时才发现错误要省力得多。Pinia 相比 Vuex 最大的优势是对 TypeScript 的天然支持和简化的 API。Vuex 写起来要定义 state/mutations/actions/getters 四件套修改状态的唯一途径是 commit这在大型团队协作中确实是规范但中小型项目的开发效率会被拖慢。Pinia 允许直接修改 state同时保留了 devtools 追踪能力对个人开发和几个人的小团队都更友好。3.2 页面架构与路由组织RuleAppV2 的前端页面分为三大块用户端前台、用户中心、管理后台。这三块虽然在一个项目里但路由和布局是完全分开的。用户端前台是访客和普通用户看到的部分包括首页、栏目列表、内容详情、搜索页、登录注册页。布局上顶部是导航栏和搜索框中间是内容区域底部是页脚右侧有侧边栏展示热门内容和推荐用户。用户中心是登录后用户管理自己资产的区域包括个人资料、我的发布、我的评论、我的收藏、消息通知。这一块的布局是左侧菜单 右内容区的经典结构。管理后台只对管理员和栏目管理员开放包含仪表盘、内容管理、评论管理、用户管理、栏目管理、站点配置。路由层面通过导航守卫做权限过滤没有对应角色的用户访问会跳转到 404 页面。一个要注意的细节是前端路由守卫只是减少无效请求真正能不能访问数据是后端接口在控制的这个我再强调一次前后端分离的项目权限主要靠后端守。3.3 多功能内容的列表与详情设计现在的首页信息流是 RuleAppV2 比较有辨识度的模块。它把文章、资源、问答、动态四种形态的内容混在一个时间流里卡片会根据内容类型展示不同的附加信息文章卡片显示阅读量和分类标签资源卡片显示下载量和文件大小问答卡片显示回答数和悬赏积分动态卡片则直接展示纯文本内容。这种混合信息流实现的难点在于不同的内容类型在列表里展示的信息不同且需要支持点击跳转到对应的详情页。我的方案是主内容表查询完毕后前端拿到统一的 ContentItem 结构其中包含 type 字段和一个可选的 extension 字段前端根据 type 去动态渲染不同的卡片组件。组件注册表是一个 Recordstring, Component 的映射新加内容形态时只需要添加一个组件并注册到这个映射表里其他部分不用动。详情页的思路类似不过更重要的是 SEO 的处理。因为前台是 SPA搜索引擎默认爬取到的只有空壳 HTML对内容收录很不友好。我的做法是对前台页面启用预渲染Prerendering构建时把内容详情的静态 HTML 生成出来这样搜索引擎拿到的就是完整页面内容。这个在部署部分我会讲具体怎么配置。3.4 状态管理与用户会话保持用户登录态用的是 JWT 刷新令牌的双令牌方案。访问令牌有效期设置得比较短2小时刷新令牌有效期 14 天。前端 axios 实例统一封装了请求拦截器和响应拦截器。请求拦截器负责把当前用户的访问令牌加到请求头 Authorization: Bearer xxx。响应拦截器检查返回的状态码如果遇到 401说明访问令牌过期了此时会用刷新令牌去请求 /auth/refresh 接口换取新令牌然后自动重放刚才失败的请求。如果刷新令牌也过期了就清除本地登录态跳转到登录页。这里有一个小坑要提醒多个接口几乎同时返回 401 时如果每个接口都触发一次 refresh 请求会浪费大量请求。正确的做法是做一个“正在进行刷新”的全局状态标记在刷新过程中其他 401 请求排队等待刷新成功后统一重放。这个模式在社区里俗称“单例刷新”实际开发中很常见。4. 后端架构解析数据库设计、权限校验与内容服务4.1 后端技术栈与模块划分后端我用的 Spring Boot 3 MyBatis-Plus MySQL Redis。Spring Boot 就不多解释了这个生态的成熟度和第三方库覆盖基本是 Java 服务端的首选。MyBatis-Plus 对单表 CRUD 的简化程度很高配合自定义 SQL 处理复杂查询比全自动 ORM比如 JPA在复杂查询场景下要可控得多。模块分包上我按业务域拆成了几个核心模块用户模块注册、登录、资料、关注、内容模块发布、编辑、审核、列表、评论模块评论、回复、点赞、搜索模块ES 与 MySQL 的同步策略、消息模块站内通知、系统消息、统计模块PV/UV、内容热度计算。这里重点说内容模块。内容发布是社区产品最核心的链路一旦内容量上来查询性能、敏感词过滤、图片处理、缓存更新都是要提前考虑的问题。RuleAppV2 的内容服务里我做了几个设计内容状态机草稿 - 待审核 - 已发布 / 已驳回 / 已下架。状态流转由代码控制流转方法不允许直接改状态字段。双写一致性发布内容时先写 MySQL 落库再异步刷新 Redis 缓存。列表接口优先读缓存缓存未命中再回源数据库同时回填缓存。内容热度计算热度分 阅读量0.4 评论数0.3 点赞数0.2 新鲜度衰减0.1。热度分在服务端定时计算排序时直接取用避免每次请求都实时计算。4.2 数据库表设计的关键决策数据库表设计是这次重构中最费力的一部分。我直接贴出几张核心表的核心结构省略了通用审计字段-- 用户主表 CREATE TABLE user ( id bigint PRIMARY KEY AUTO_INCREMENT, username varchar(50) NOT NULL UNIQUE, password_hash varchar(255) NOT NULL, avatar_url varchar(500), bio varchar(500), role varchar(20) NOT NULL DEFAULT USER, status tinyint NOT NULL DEFAULT 1, points int NOT NULL DEFAULT 0, created_at datetime NOT NULL, updated_at datetime NOT NULL ); -- 栏目表 CREATE TABLE category ( id bigint PRIMARY KEY AUTO_INCREMENT, name varchar(50) NOT NULL, slug varchar(80) NOT NULL UNIQUE, parent_id bigint DEFAULT 0, sort_order int NOT NULL DEFAULT 0, status tinyint NOT NULL DEFAULT 1 ); -- 主内容表 CREATE TABLE content ( id bigint PRIMARY KEY AUTO_INCREMENT, user_id bigint NOT NULL, category_id bigint NOT NULL, type varchar(20) NOT NULL, title varchar(200), summary varchar(500), status varchar(20) NOT NULL DEFAULT DRAFT, view_count int NOT NULL DEFAULT 0, like_count int NOT NULL DEFAULT 0, comment_count int NOT NULL DEFAULT 0, heat_score decimal(10,4) NOT NULL DEFAULT 0, sticky_weight int NOT NULL DEFAULT 0, published_at datetime, created_at datetime NOT NULL, updated_at datetime NOT NULL, KEY idx_category_status (category_id, status), KEY idx_user_id (user_id), KEY idx_published_at (published_at), KEY idx_heat_score (heat_score) ); -- 内容扩展表文章 CREATE TABLE content_article ( id bigint PRIMARY KEY AUTO_INCREMENT, content_id bigint NOT NULL UNIQUE, content_md longtext, content_html longtext, cover_image varchar(500) ); -- 内容扩展表资源 CREATE TABLE content_resource ( id bigint PRIMARY KEY AUTO_INCREMENT, content_id bigint NOT NULL UNIQUE, file_url varchar(500) NOT NULL, file_size bigint NOT NULL DEFAULT 0, download_count int NOT NULL DEFAULT 0, extract_code varchar(20) ); -- 评论表 CREATE TABLE comment ( id bigint PRIMARY KEY AUTO_INCREMENT, content_id bigint NOT NULL, user_id bigint NOT NULL, parent_id bigint DEFAULT 0, content text NOT NULL, status tinyint NOT NULL DEFAULT 1, like_count int NOT NULL DEFAULT 0, created_at datetime NOT NULL, KEY idx_content_id (content_id), KEY idx_user_id (user_id) );几个关键设计的意图说一下主表不存具体正文只存公共属性。这样列表查询只要标题、摘要、作者、时间不会去读正文大字段IO 开销大幅下降。这是很多内容系统性能问题的根源——列表页查了全表的大文本字段。article 的正文同时存 Markdown 原文和渲染后的 HTML。这是为了编辑时回显原文展示时直接用 HTML避免每次请求都做一次 Markdown 渲染。你可以选择在编辑保存时就渲染并持久化也可以在读取时按需渲染前者多占存储后者多占 CPU这里我选的是前者。content 表加了 published_at 字段而不用 created_at。因为草稿、定时发布的存在内容的“发布时间”和“创建时间”是两个概念不能用错了。4.3 认证与授权的实现细节用户密码存储用的是 BCrypt 算法这个不需要自己实现Spring Security 自带 BCryptPasswordEncoder。使用 BCrypt 的一个好处是每次哈希都会自动加盐而且同一个密码每次算出来的哈希值都不同如果要再加一层保险可以在用户表中再存一个随机盐值字段。登录成功后签发 JWT密钥存在配置文件中生产环境必须通过环境变量注入不要硬编码到代码或提交到 Git。JWT 的 payload 里只放用户 id 和角色不放其他敏感信息。权限校验我的实现方式是自定义 Spring MVC 的 HandlerInterceptor在拦截器中读取用户的角色用注解RequireRole(ADMIN)标记接口需要的权限拦截器通过反射拿到注解后做比对。这样比在业务代码里写 if 判断要集中、优雅得多新增接口时只需要加一行注解权限逻辑不会散落在各个 Controller 里。还有一个容易被忽略的点数据权限。比如栏目管理员调“删除内容”接口如果只校验了角色是“栏目管理员”那他可以删除任何栏目的内容。正确做法是先查出这条内容的 category_id再去判断这个管理员有没有该栏目的管理权。这种按数据归属的权限校验我是在 service 层做的拦截器里做不了因为涉及具体业务数据。4.4 敏感词过滤与内容审核内容社区的合规要求必须重点说。RuleAppV2 的敏感词过滤我实现了两层第一层是发布时的异步检测配合第三方API做文本审核第二层是人工审核队列管理员可以在后台对已发布内容进行复核。自建的敏感词库用 DFA确定性有限自动机算法实现把敏感词列表构造成一颗 Trie 树匹配时一趟扫描就能找出文本中的命中的词。这套算法在 GitHub 上有不少现成实现可以借鉴我基于彼方的思路做了一个修改版核心逻辑是把敏感词按长度分组再用哈希表加速查找实测在几万词库下单条文本匹配耗时在毫秒级。这个异步检测流程是这样的用户在编辑器点击发布 - 内容先保存为待审核状态 - 写一条审核任务到 MQ - 消费者收到后调用第三方文本审核接口 - 如果含有违规内容状态自动变为已驳回并通知用户 - 如果通过状态变为已发布。整个流程对用户是无感知的提交后 1~2 秒内状态自动更新。5. 部署实战从源码下载到线上可访问5.1 环境准备与依赖安装RuleAppV2 的部署依赖以下环境软件版本要求用途JDK17后端运行环境Maven3.8后端构建Node.js16.20前端构建MySQL8.0主数据库Redis6.0缓存与会话Nginx1.20静态资源与反向代理服务器我建议至少 2 核 4G 内存硬盘 40G 起步。1 核 2G 的小鸡也能跑但 MySQL Redis Java 应用同时跑会比较紧张搜索服务如果后续要上会比较吃力。建议部署顺序先装 MySQL 和 Redis再初始化数据库再启动后端最后构建前端部署到 Nginx。5.2 后端部署数据库初始化、配置修改与启动克隆代码后后端工程里有一个sql/init.sql文件里面是建库建表语句和初始数据默认栏目、管理员账号。建议在 MySQL 中先创建数据库CREATE DATABASE ruleapp CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;然后导入 init.sql。这里有几个重要配置要改在application-prod.yml里spring: datasource: url: jdbc:mysql://127.0.0.1:3306/ruleapp?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/Shanghai username: your_mysql_user password: your_mysql_password redis: host: 127.0.0.1 port: 6379 password: your_redis_password jwt: secret: your-random-64-char-secret-key expire-hours: 2 refresh-expire-days: 14JWT secret 这里一定要改掉默认值并且长度不小于 32 个字符。用默认值意味着任何人都可以用你公开的密钥签发有效的 JWT等于登录接口暴露了。生产环境建议用环境变量注入这些配置不要让真实密码出现在配置文件中。初始化完成后执行构建mvn clean package -DskipTests生成的 jar 包在target/ruleapp-server.jar用 systemd 守护进程管理启动还是直接用 nohup 都行我习惯于用 systemd 服务的方式方便崩溃后自动拉起、开机自启、日志统一管理。5.3 前端部署构建产物与 Nginx 配置前端构建之前需要修改 API 地址配置。在.env.production文件中配置VITE_API_BASE_URL/api我建议前端开发时走代理生产环境走 Nginx 反向代理也就是前端只配置/api这种相对路径由 Nginx 把 /api 的请求转发到后端的 8080 端口。这样有几个好处前后端部署在同一域名下不涉及跨域以后就算换后端地址前端不需要重新构建。执行构建npm install npm run build构建产物在dist/目录把它放到 Nginx 的 web 目录比如/var/www/ruleapp。然后配置 Nginxserver { listen 80; server_name your-domain.com; root /var/www/ruleapp; index index.html; # 前端路由history 模式下所有路径都回退到 index.html location / { try_files $uri $uri/ /index.html; } # API 反向代理 location /api/ { proxy_pass http://127.0.0.1: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 /uploads/ { alias /var/www/ruleapp/uploads/; expires 30d; add_header Cache-Control public; } }注意proxy_pass http://127.0.0.1:8080/;末尾这个斜杠很重要它表示把/api前缀去掉后转发。比如请求/api/content/list最终后端收到的是/content/list。如果后端接口本身带/api前缀那这里就不要加斜杠这个细节设错了会导致 404。5.4 预渲染配置与 SEO 优化前面提到前台 SPA 对 SEO 不友好我的解决方案是用 vite-plugin-prerender 做构建时的预渲染。这个插件会在构建完成后启动一个无头浏览器访问配置的路由列表把渲染出的 HTML 保存到对应的 dist 路径下。预渲染的路由配置// vite.config.ts prerenderer: { routes: [/, /category/article, /category/resource, /about], renderer: new Prerenderer({ headless: true, renderAfterTime: 500, postProcess(context) { // 在这里可以注入 meta 描述、og 标签等 return context; } }) }需要注意预渲染只是在构建时把静态页面生成出来动态内容比如最新文章列表有可能在生成时是空的。所以预渲染更适用于内容不经常变的页面或者只预渲染首页框架、活动页这类半静态页面。对于内容详情页这种高频动态页面更好的方案是用 Nginx 的 SSI 技术做服务端包含或者在内容发布时同步生成静态 HTML。我目前是把内容详情页发布时同步生成静态页策略上更可控。5.5 Docker Compose 一键部署为了方便不想折腾环境的用户我还提供了 Docker Compose 编排文件。一条命令就能启动 MySQL、Redis、后端、前端四个服务docker compose up -d编排文件的思路是MySQL 和 Redis 用官方镜像挂载数据卷持久化后端镜像用多阶段构建第一阶段 Maven 编译第二阶段用 JRE 运行前端镜像用 Nginx 官方镜像把构建产物 COPY 进去再覆盖默认配置。整个编排文件的核心部分services: mysql: image: mysql:8.0 environment: MYSQL_ROOT_PASSWORD: rootpass MYSQL_DATABASE: ruleapp MYSQL_USER: ruleapp MYSQL_PASSWORD: ruleapppass volumes: - mysql_data:/var/lib/mysql ports: - 3306:3306 redis: image: redis:7-alpine command: redis-server --requirepass redispass volumes: - redis_data:/data backend: build: ./server depends_on: - mysql - redis environment: SPRING_PROFILES_ACTIVE: prod DB_HOST: mysql DB_PASSWORD: ruleapppass REDIS_PASSWORD: redispass JWT_SECRET: change-me-in-production ports: - 8080:8080 frontend: build: ./web depends_on: - backend ports: - 80:80Docker 部署的一个坑是容器间的网络通信。容器里访问 MySQL 不能用127.0.0.1要使用服务名比如mysql这是 Docker 内置 DNS 解析的规则。所以后端配置里要把数据库地址改成jdbc:mysql://mysql:3306/ruleapp而不是127.0.0.1。我一度在这上面卡了半小时排查了半天才发现是配置写错了。6. 常见问题与排查技巧实录6.1 问题速查表症状可能原因解决办法前端请求接口 404Nginx proxy_pass 末尾斜杠配置不对检查location /api/的 proxy_pass 是否带斜杠登录后很快失效前后端服务器时间不同步统一用 NTP 同步时间检查 JWT 签发时间和验证时间的时区图片上传本地路径无法访问Nginx 没有配置 /uploads/ 的 alias在 Nginx 中添加静态文件映射内存占用过高JVM 堆内存配置过小或过大调整 JVM 参数-Xms和-Xmx建议设置为物理内存的 1/4列表接口响应慢缓存未生效或索引缺失检查 Redis 是否连通查询 EXPLAIN 看 SQL 是否走索引静态资源加载慢未开启 Gzip 和缓存Nginx 开启 gzip on静态资源配置 expires定时任务重复执行多实例部署但没有分布式锁单实例部署或引入分布式锁保证同时只有一个实例执行6.2 部署环境问题8080 端口被占用上线时候遇到的一个问题后端 jar 启动后8080 端口一直提示被占用启动失败。查了下服务器原来是一个残留的 Java 进程占用了端口。排查命令lsof -i :8080找到占用进程 PID 后确认是废弃进程直接kill -9 PID然后重新启动 spring boot 服务。生产环境部署时如果有多套服务都在监听端口建议把每个服务的端口、进程 PID、启动命令都记录在运维文档里不然问题出现时排查确实费事。6.3 开发调试问题跨域请求被拦截本地开发时前端是 Vite 的 5173 端口后端是 8080跨域是不可避免的。我的做法是前端所有请求走 Vite 代理不启用后端的 CORS 配置。Vite 配置文件中的代理设置// vite.config.ts server: { proxy: { /api: { target: http://127.0.0.1:8080, changeOrigin: true, rewrite: (path) path.replace(/^\/api/, ) } } }把跨域问题留到 Nginx 层处理而不是在后端开启 CORS主要原因是上线后前后端是同域部署后端开 CORS 没有意义且可能带来安全隐患。开发时用代理生产时用 Nginx 反向代理统一在网关层解决跨域后端代码可以保持纯净。6.4 内容发布问题富文本图片插入失败还有一个比较隐蔽的坑就是富文本编辑器里插入图片时图片文件传到后端的大小超出了 Spring 的默认限制。Spring Boot 默认上传文件大小上限是 1MB超出会被拦截并报错。修改配置spring: servlet: multipart: max-file-size: 10MB max-request-size: 10MB但如果图片是 base64 编码后直接塞进 JSON 提交的这个限制对 JSON 体不生效需要另行检查云服务器的请求体大小限制比如 Nginx 的client_max_body_size。我建议图片一律走独立的上传接口返回 URL 后再把 URL 插入编辑器而不是 base64 内嵌既不占请求体体积也方便以后接入 CDN。7. 开源协议与后续规划RuleAppV2 采用 MIT 协议开源意味着你可以自由使用、修改、商用只需要保留版权声明。我选择 MIT 而不是 GPL 的考虑是内容社区在很多场景下是商业产品的一部分如果后续有人基于它做商业项目GPL 会让闭源集成变得麻烦。MIT 协议在开源和商业之间做了最好的平衡。当然这也意味着开源项目无法强制要求使用者回馈代码所以项目的生命力很大程度上依赖社区的自发贡献。后续的迭代方向我列了几个第一个是搜索模块升级当前是基于 MySQL 的模糊匹配数据量上来后打算迁移到独立搜索引擎会涉及构建索引、同步策略、中文分词。第二个是消息通知系统目前只是站内信和邮件后续要支持 webhook 和可选的小程序推送方便社区运营方接入自己的通知渠道。第三个是主题系统标准化目前前端主题是硬编码的我计划做成可配置的主题包让非技术用户也能在后台切换风格。如果你感兴趣的话可以 clone 仓库跑起来看看从 README 开始按文档走一遍部署流程有任何问题可以直接提 issue 或者进交流群反馈。开源项目最怕的是作者写完了就扔在那里不维护我这边至少会保持月度迭代节奏社区提的合理需求会排期处理。这也是我开源这个项目的初衷一个人用这个东西价值有限一套系统被很多人用在各种不同场景里才算真正有了生命力。8. 关于开源项目的维护心得个人体会这次把 RuleAppV2 完整重构并开源整个过程收获很大。写业务代码其实不难难的是做取舍哪些功能必须进核心哪些应该做成插件哪些模块要做得抽象哪些可以直接写死哪些依赖可以引入哪些必须自己造轮子。这些决策贯穿了整个开发周期每一处都在考验对项目的整体把控能力。踩过几次坑之后我的体会是开源项目最忌讳闭门造车。第一版的时候我就是按照自己的想象去设计功能结果用户提的需求跟我的设计有比较大的出入。V2 在设计阶段我参考了不少同类社区产品的反馈区把高频需求列出来逐个判断哪些必须做进核心、哪些可以做扩展。这类信息价值很高因为它反映的是真实用户的实际使用场景不是自己拍脑袋想出来的需求。最后再分享一个小技巧对于开源项目的文档不只是 README 要写清楚最好在项目里附带一个docs/deploy-guide.md把部署步骤、常见错误、截图、视频链接全部整理进去。很多用户第一次接触项目时最先打开的就是部署文档如果这一步不顺畅基本就劝退了。文档写得好项目的接受度和 star 增长速度会有非常明显的区别。