【开源项目】你们学校真的不需要一个自己的交流平台吗?

· · 科技·工程

:::error[使用前请注意!!!]{open}

本项目仅供学习、研究与交流。若计划在真实校园环境中部署、运营,请事先与学校沟通,取得相应许可,并按实际情况履行必要的备案等手续。

校园社区涉及用户隐私、内容管理和言论规范。实际部署者应自行承担相应的运营与管理责任。对于因违规使用、管理不当等产生的问题,作者不承担超出法律规定的责任。

:::

:::info[项目信息]{open}

:::

::::success[AI 信息]{open} 本文使用 GPT6 润色。

项目开发使用 Codex,Deepseek。

语文老师教的流水账叙事

初二的时候,我就一直有个想法:做一个属于自己学校的校园社区。

原因其实很简单——总感觉学校里缺少一个方便大家交流的地方。如果能有一个小站,让同学们分享日常、讨论话题,或者发布一些有意思的内容,应该会挺不错的。

于是,我开始尝试把这个想法变成现实。

最开始做出来的,只是一个比较简单的网页。后端数据库用的是 Appwrite,至于为什么选它……主要是因为当时还不知道 Cloudflare 有 D1 这个东西。

不过,最初的版本倒也能正常运行,使用体验还算不错。

直到有一天早上。

我打开网站,发现一大堆 API 突然不能用了。

排查了一番,才知道原来 Appwrite 的免费额度是按月计算的。由于同学们实在太热情,额度就这样被消耗掉了。

这显然不是长久之计。

后来,我开始寻找其他解决方案,意外发现 Cloudflare 居然还提供数据库服务。于是,经过一番折腾,使用 Cloudflare D1 的新版本终于诞生了。

但问题又来了。

最初的版本完全是围绕我们学校开发的。

无论是一些配置、业务逻辑,还是特定的功能设计,都带有很强的学校特色,甚至有不少内容是直接写死在代码里的。

这样的项目,即使开源,别人拿过去也很难直接使用。

所以,我又有了一个新的想法:

既然已经做出来了,为什么不把它改造成一个大家都能使用的校园社区系统呢?

于是,我开始逐步拆分原本写死的逻辑,整理配置项,完善功能,并尝试让整个项目具备一定的通用性。

最终,就有了现在的 Rippling。

你可以把它理解成一套校园社区模板,也可以把它看作一个可以自行部署的小型社区产品。

至于部署难度,我已经尽量降低了门槛,也准备了相应的新手文档。即使不太熟悉 Web 开发,也可以尝试按照文档一步步操作。

实在不行,现在不是还有 AI 嘛。

产品实现原理

以下内容参考了 AI 对项目代码的梳理,再由我进行整理和说明。

考虑到不是所有人都熟悉 Web 开发,下面会尽量使用比较容易理解的方式介绍项目架构,同时保留一些必要的技术细节。

总体架构

先放一张图,方便理解整个项目的组成与各部分之间的关系。

图片也是 GPT 画的。

整体采用前后端分离的设计思路,主要使用以下技术:

下面分别介绍。

前端

前端代码主要位于 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 存储结构化数据。

目前涉及的数据表比较多,大致可以分成以下几类:

通过这样的设计,可以将不同业务的数据分开管理,也方便后续扩展新的功能。

推荐流与缓存机制

既然是社区,当然少不了内容推荐。

项目的推荐流并不是完全按照发布时间排序,而是综合考虑了多个因素,包括:

通过这些因素综合计算,让推荐结果既能体现内容热度,也能兼顾用户的关注关系和内容的新鲜度。

此外,推荐流使用了游标分页(Cursor Pagination)。

相比传统的页码分页,游标分页能够更好地应对不断插入的新内容,降低翻页时出现内容重复或遗漏的概率。

为了减少不必要的数据库查询,项目还设计了边缘缓存中间件。

缓存仅针对明确允许缓存的 GET 请求,例如:

对于可能因用户身份而变化的推荐结果,缓存会利用用户会话的哈希值区分不同用户的数据,避免直接共用同一份个性化结果。

当然,缓存并不是越多越好。涉及用户隐私或权限变化的数据,必须谨慎处理,不能为了节省几次数据库请求就忽略数据隔离。

图片上传与存储

为了方便同学们分享图片,项目使用 Backblaze B2 作为图片存储服务。

大致流程如下:

  1. 用户在浏览器中选择需要上传的图片。
  2. 前端对图片进行压缩,并控制上传大小。
  3. 后端对文件类型、大小等信息进行检查。
  4. 通过 B2 提供的 S3 兼容接口上传图片。
  5. 数据库或页面中保存图片的 Key 或站内代理地址。
  6. 用户通过 /api/image 接口读取图片。

这样,图片文件不需要直接存放在 D1 数据库中,数据库只需要记录与图片相关的信息即可。

实物展示

光说不练假把式,下面看看实际效果。

以下截图来自项目的实际运行界面。

电脑端

手机端

以下截图通过浏览器 F12 开发者工具模拟移动设备获得,并非真实手机截图。

管理员面板

如何部署

目前推荐使用 Cloudflare Pages 进行部署。

项目已经准备了一份相对完整的新手部署文档,涵盖部署过程中需要进行的主要操作。

强烈建议先完整阅读文档,再开始实际部署。

部署文档由 AI 参考项目代码生成,并经过整理。因此,文档内容仍有可能与项目的最新版本存在差异。

如果遇到命令不适用、配置不一致或者其他问题,欢迎在评论区反馈,或者直接前往 GitHub 提交 Issue。

完整文档:

docs/beginner-deployment.md

为什么选择 Cloudflare?

可能有人会问:为什么整个项目的大部分服务都放在 Cloudflare 上?

其实原因很简单。

对于个人开发者来说,Cloudflare 的部署方式比较方便,而且轻量项目的使用成本相对较低。

具体而言:

当然,Cloudflare 也不是万能的。

如果项目面向国内校园用户长期运行,还需要考虑实际网络访问情况、服务稳定性、数据合规和运营管理等问题。

特别提醒:如果计划将本项目投入真实使用,务必事先与学校沟通,并根据实际部署方式和服务性质了解、履行相关备案及合规要求。

如果 Cloudflare 的网络访问情况不能满足需求,也可以考虑调整项目架构,将相关服务迁移到其他合适的平台。

写在最后

从最开始那个功能简单、甚至还会因为 API 额度耗尽而突然罢工的小网页,到如今逐渐整理成一个可以独立部署的开源项目,Rippling 其实经历了不少次修改。

它当然还不完美。

无论是功能设计、代码结构,还是一些边界情况的处理,都还有继续改进的空间。

不过,对我来说,这个项目不仅是一个校园社区,也算是一次比较完整的全栈开发实践。

从前端页面、后端 API,到数据库、认证、权限系统和部署,很多东西都是在实际遇到问题之后,一点点学习和完善的。

我也希望它不只是一个放在 GitHub 上的仓库,而是真正能够为有类似想法的人提供一些参考。

如果你也对校园社区、Cloudflare 全栈开发或者开源项目感兴趣,欢迎看看源码,提出建议,或者一起参与改进。

项目地址: https://github.com/bearthomas/rippling

如果觉得这个项目还不错,也欢迎点个 Star 支持一下!

最后——

都看到这里了,留个赞再走呗! ( ̄▽ ̄)/