【开源项目】你们学校真的不需要一个自己的交流平台吗?
bearThomas · · 科技·工程
:::error[使用前请注意!!!]{open}
本项目仅供学习、研究与交流。若计划在真实校园环境中部署、运营,请事先与学校沟通,取得相应许可,并按实际情况履行必要的备案等手续。
校园社区涉及用户隐私、内容管理和言论规范。实际部署者应自行承担相应的运营与管理责任。对于因违规使用、管理不当等产生的问题,作者不承担超出法律规定的责任。
:::
:::info[项目信息]{open}
- 项目地址:GitHub - Rippling
- 部署文档:新手部署指南
- 开源协议:MIT
:::
::::success[AI 信息]{open} 本文使用 GPT6 润色。
| 项目开发使用 Codex,Deepseek。 |
|---|
语文老师教的流水账叙事
初二的时候,我就一直有个想法:做一个属于自己学校的校园社区。
原因其实很简单——总感觉学校里缺少一个方便大家交流的地方。如果能有一个小站,让同学们分享日常、讨论话题,或者发布一些有意思的内容,应该会挺不错的。
于是,我开始尝试把这个想法变成现实。
最开始做出来的,只是一个比较简单的网页。后端数据库用的是 Appwrite,至于为什么选它……主要是因为当时还不知道 Cloudflare 有 D1 这个东西。
不过,最初的版本倒也能正常运行,使用体验还算不错。
直到有一天早上。
我打开网站,发现一大堆 API 突然不能用了。
排查了一番,才知道原来 Appwrite 的免费额度是按月计算的。由于同学们实在太热情,额度就这样被消耗掉了。
这显然不是长久之计。
后来,我开始寻找其他解决方案,意外发现 Cloudflare 居然还提供数据库服务。于是,经过一番折腾,使用 Cloudflare D1 的新版本终于诞生了。
但问题又来了。
最初的版本完全是围绕我们学校开发的。
无论是一些配置、业务逻辑,还是特定的功能设计,都带有很强的学校特色,甚至有不少内容是直接写死在代码里的。
这样的项目,即使开源,别人拿过去也很难直接使用。
所以,我又有了一个新的想法:
既然已经做出来了,为什么不把它改造成一个大家都能使用的校园社区系统呢?
于是,我开始逐步拆分原本写死的逻辑,整理配置项,完善功能,并尝试让整个项目具备一定的通用性。
最终,就有了现在的 Rippling。
你可以把它理解成一套校园社区模板,也可以把它看作一个可以自行部署的小型社区产品。
至于部署难度,我已经尽量降低了门槛,也准备了相应的新手文档。即使不太熟悉 Web 开发,也可以尝试按照文档一步步操作。
实在不行,现在不是还有 AI 嘛。
产品实现原理
以下内容参考了 AI 对项目代码的梳理,再由我进行整理和说明。
考虑到不是所有人都熟悉 Web 开发,下面会尽量使用比较容易理解的方式介绍项目架构,同时保留一些必要的技术细节。
总体架构
先放一张图,方便理解整个项目的组成与各部分之间的关系。
图片也是 GPT 画的。
整体采用前后端分离的设计思路,主要使用以下技术:
- Vue 3:负责前端页面与用户交互。
- Cloudflare Pages / Pages Functions:负责页面部署及后端 API 运行。
- Hono:组织和管理后端 API 路由。
- Better Auth:处理用户注册、登录及会话认证。
- Cloudflare D1:存储用户、帖子、评论等结构化数据。
- Backblaze B2:存储用户上传的图片。
下面分别介绍。
前端
前端代码主要位于 src/frontend 目录下,按照不同页面和功能进行组织。
前端负责页面展示、交互处理、状态管理,以及向后端发送 API 请求。
这里有一点需要特别说明:
前端并不是项目的主要安全边界。
虽然前端会进行一些基础检查,例如限制未登录用户访问特定页面、验证输入内容等,但真正的权限校验主要由后端完成。
也就是说,即使有人绕过浏览器页面,尝试直接调用 API,也仍然需要通过服务端的身份认证与权限检查。
毕竟,总不能指望把按钮藏起来就能保证安全。
后端
后端入口位于:
src/functions/api/[[route]].ts
项目使用 Hono 组织 API 路由,并将不同功能拆分到相应模块中。
目前主要包括:
| API 路径 | 功能 |
|---|---|
/api/post |
帖子与评论 |
/api/like |
点赞 |
/api/confession |
表白墙 |
/api/timeline |
校园大事记 |
/api/vote |
投票 |
/api/recommend |
内容推荐流 |
/api/search |
搜索 |
/api/follow |
用户关注关系 |
/api/question |
提问箱 |
/api/block |
板块管理 |
/api/ticket |
举报、申诉与权限工单 |
/api/admin |
管理员功能 |
/api/upload、/api/image |
图片上传与读取 |
/api/user |
用户资料与账号设置 |
这种组织方式的好处是,各个功能模块之间相对独立,后续增加功能或者维护已有代码都会更加方便。
登录与身份认证
项目使用 Better Auth 作为用户认证系统。
考虑到校园环境的特殊性,系统支持以学号作为账号标识。
不过,Better Auth 的部分流程需要使用类似电子邮箱的标识格式,因此,项目会在注册时将学号拼接上 @rippling.local。
例如:
20260001 → [email protected]
这里的 @rippling.local 并不是真实邮箱地址,仅仅是内部使用的占位标识,不具备实际的邮件收发功能。
当用户发送 API 请求时,后端认证中间件会读取并验证当前会话,再将用户信息写入请求上下文。
这样,后续路由便可以根据用户身份,判断其是否已登录,以及是否拥有执行对应操作的权限。
用户权限系统
考虑到不同用户、不同板块之间可能存在比较复杂的权限关系,项目采用了二进制位掩码(Bitmask)来存储和管理权限。
简单来说,就是为每一种权限分配一个独立的二进制位,再通过位运算进行组合和判断。
由于权限位实在太多,这里就不全部贴出来了。
目前系统主要有两类权限:
1. 全站权限
例如发帖、评论、管理用户、访问管理面板等。
2. 板块权限
例如查看板块、管理板块成员、置顶帖子、转让板块等。
不同角色具有相应的初始权限组合,管理员也可以根据需要进行调整。
具体定义可以查看:
src/shared/permissions.ts
登录墙机制
校园社区与一般的公开论坛不同,某些内容可能只适合校内成员查看。
因此,项目设计了登录墙机制,用来控制未登录用户可以访问的内容。
目前支持三种模式:
| 模式 | 访问规则 |
|---|---|
| 无墙 | 游客可以访问允许公开的内容 |
| 软墙 | 游客可以进入网站,但部分功能需要登录 |
| 硬墙 | 除登录、注册等必要接口外,受保护内容必须登录后才能访问 |
值得注意的是,登录墙并不是简单地在前端隐藏几个页面。
它的核心逻辑位于后端 API 中间件。
当请求到达后端时,中间件会根据当前登录墙配置、用户会话及接口白名单,判断是否允许继续访问。
对于硬墙模式下需要认证、但用户尚未登录的受保护请求,服务端会返回 401 Unauthorized。
这样,即使用户直接访问 API,也不能仅通过绕过前端页面来突破登录限制。
数据库设计
项目使用 Cloudflare D1 存储结构化数据。
目前涉及的数据表比较多,大致可以分成以下几类:
- 身份认证:Better Auth 的用户、会话、账号及验证信息。
- 用户系统:用户资料、设备信息与用户日志。
- 社区内容:帖子、评论、点赞及内容可见性。
- 校园功能:表白墙、大事记与投票。
- 社交功能:关注关系、提问箱与提问记录。
- 板块管理:板块信息、成员、加入申请及黑名单。
- 管理功能:工单、通知、管理日志与归档索引。
通过这样的设计,可以将不同业务的数据分开管理,也方便后续扩展新的功能。
推荐流与缓存机制
既然是社区,当然少不了内容推荐。
项目的推荐流并不是完全按照发布时间排序,而是综合考虑了多个因素,包括:
- 点赞数量
- 评论数量
- 用户关注关系
- 板块关系
- 内容发布时间
- 一定的随机因素
通过这些因素综合计算,让推荐结果既能体现内容热度,也能兼顾用户的关注关系和内容的新鲜度。
此外,推荐流使用了游标分页(Cursor Pagination)。
相比传统的页码分页,游标分页能够更好地应对不断插入的新内容,降低翻页时出现内容重复或遗漏的概率。
为了减少不必要的数据库查询,项目还设计了边缘缓存中间件。
缓存仅针对明确允许缓存的 GET 请求,例如:
- 站点配置
- 初始化状态
- 推荐流
- 图片资源
对于可能因用户身份而变化的推荐结果,缓存会利用用户会话的哈希值区分不同用户的数据,避免直接共用同一份个性化结果。
当然,缓存并不是越多越好。涉及用户隐私或权限变化的数据,必须谨慎处理,不能为了节省几次数据库请求就忽略数据隔离。
图片上传与存储
为了方便同学们分享图片,项目使用 Backblaze B2 作为图片存储服务。
大致流程如下:
- 用户在浏览器中选择需要上传的图片。
- 前端对图片进行压缩,并控制上传大小。
- 后端对文件类型、大小等信息进行检查。
- 通过 B2 提供的 S3 兼容接口上传图片。
- 数据库或页面中保存图片的 Key 或站内代理地址。
- 用户通过
/api/image接口读取图片。
这样,图片文件不需要直接存放在 D1 数据库中,数据库只需要记录与图片相关的信息即可。
实物展示
光说不练假把式,下面看看实际效果。
以下截图来自项目的实际运行界面。
电脑端
手机端
以下截图通过浏览器 F12 开发者工具模拟移动设备获得,并非真实手机截图。
管理员面板
如何部署
目前推荐使用 Cloudflare Pages 进行部署。
项目已经准备了一份相对完整的新手部署文档,涵盖部署过程中需要进行的主要操作。
强烈建议先完整阅读文档,再开始实际部署。
部署文档由 AI 参考项目代码生成,并经过整理。因此,文档内容仍有可能与项目的最新版本存在差异。
如果遇到命令不适用、配置不一致或者其他问题,欢迎在评论区反馈,或者直接前往 GitHub 提交 Issue。
完整文档:
docs/beginner-deployment.md
为什么选择 Cloudflare?
可能有人会问:为什么整个项目的大部分服务都放在 Cloudflare 上?
其实原因很简单。
对于个人开发者来说,Cloudflare 的部署方式比较方便,而且轻量项目的使用成本相对较低。
具体而言:
- Pages 可以直接连接 GitHub,方便持续部署。
- D1 提供数据库服务,比较适合轻量级社区应用。
- Pages Functions / Workers 可以运行后端 API,不需要单独购买传统服务器。
- 统一部署:前端静态资源和后端 API 可以在同一个平台上运行。
- 成本可控:对于规模较小的个人项目,免费额度具有一定吸引力。
- 维护简单:不需要自己管理操作系统、服务器环境和基础设施。
当然,Cloudflare 也不是万能的。
如果项目面向国内校园用户长期运行,还需要考虑实际网络访问情况、服务稳定性、数据合规和运营管理等问题。
特别提醒:如果计划将本项目投入真实使用,务必事先与学校沟通,并根据实际部署方式和服务性质了解、履行相关备案及合规要求。
如果 Cloudflare 的网络访问情况不能满足需求,也可以考虑调整项目架构,将相关服务迁移到其他合适的平台。
写在最后
从最开始那个功能简单、甚至还会因为 API 额度耗尽而突然罢工的小网页,到如今逐渐整理成一个可以独立部署的开源项目,Rippling 其实经历了不少次修改。
它当然还不完美。
无论是功能设计、代码结构,还是一些边界情况的处理,都还有继续改进的空间。
不过,对我来说,这个项目不仅是一个校园社区,也算是一次比较完整的全栈开发实践。
从前端页面、后端 API,到数据库、认证、权限系统和部署,很多东西都是在实际遇到问题之后,一点点学习和完善的。
我也希望它不只是一个放在 GitHub 上的仓库,而是真正能够为有类似想法的人提供一些参考。
如果你也对校园社区、Cloudflare 全栈开发或者开源项目感兴趣,欢迎看看源码,提出建议,或者一起参与改进。
项目地址: https://github.com/bearthomas/rippling
如果觉得这个项目还不错,也欢迎点个 Star 支持一下!
最后——
都看到这里了,留个赞再走呗! ( ̄▽ ̄)/