# miniblog **Repository Path**: wxd-gaming/miniblog ## Basic Information - **Project Name**: miniblog - **Description**: mini博客 - **Primary Language**: Unknown - **License**: Apache-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-09-14 - **Last Updated**: 2026-11-03 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # minilog · 职场二三事 一个**零外部数据库**的微型博客:Spring Boot 4 + Java 25 + 嵌入式 RocksDB + 原生 HTML/CSS/JS 前端。 下载 jar,`java -jar` 起来,浏览器打开就是一个能发帖、回复、投票、搜索、群聊的站点——没有 MySQL,没有 Redis,没有 JPA,前端也没有框架和打包器。 ![最新时间线](docs/screenshots/01-home.png) --- ## 目录 - [它有什么特别的](#它有什么特别的) - [功能](#功能) - [界面一览](#界面一览) - [皮肤](#皮肤) - [快速开始](#快速开始) - [配置项](#配置项) - [架构](#架构) - [API 一览](#api-一览) - [前端路由](#前端路由) - [测试](#测试) - [已知边界](#已知边界) - [许可](#许可) --- ## 它有什么特别的 | 常见做法 | 本项目的做法 | | --- | --- | | MySQL / PostgreSQL + JPA | **嵌入式 RocksDB**,Key 布局全部手写,record 直接 Jackson 序列化成值 | | Redis 缓存计数 | `CounterStore` 内存热写 + 5 秒 `WriteBatch` 落盘,启动时从快照恢复 | | 点赞表一行一条记录 | **20 桶位图**:桶号 `uid % 20`、位 `bit(uid-1)`,惰性建桶、全零删桶 | | WebSocket 做实时聊天 | **SSE 单向推送** + 前端 `fetch + ReadableStream`(EventSource 带不了 Authorization 头) | | Vue/React + 构建流水线 | 原生 HTML/CSS/JS,样式全部走设计令牌,改皮肤只加一组 CSS 变量 | | 微服务拆分 | 单机单进程,一个可执行 jar 交付 | ## 功能 **社区** - 发帖:标题 + 正文 + 标签 + 图片/视频附件 - 回复:楼层序号、引用回复(引用链向上追溯,限深 10)、跨帖引用直接拒绝 - 投票:赞 / 踩互斥,重复投同一票幂等,取消用 `none` - 搜索:关键字交集匹配;推荐:按热度排序并随时间衰减 - 关注 / 取关,用户按用户名或昵称检索 - 删除:帖子删除级联清理索引;回复与聊天消息用**墓碑**(保留楼层,正文置空) **聊天** - 群聊与私聊统一抽象为会话(`GROUP` / `PRIVATE`),私聊对同一对人复用 - 入群两条路径:管理员邀请(两级审批:管理员批准 → 本人确认)与自主申请 - 成员角色(群主 / 管理员 / 成员)、任免、踢人、退出、解散 - 未读数 = `lastSeq - 我的已读游标`,标记已读幂等 - 消息 5 分钟内可编辑(原地替换并打「已编辑」)或撤回(墓碑) - 附件支持图片 / 视频 / 文档压缩包音频;`/upload/**` 与站点同源,因此**刻意拒绝 html/svg 等可执行标记** - SSE 事件:`ready` / `message` / `message_edited` / `message_recalled` / `invite*` / `conversation_*` / `kicked` **界面** - History API 路由:刷新、前进后退、复制链接都能回到同一屏(服务端 `forward` 回退到 `index.html`) - 五套皮肤 + 跟随系统,选择存 `localStorage`,`` 内联脚本防刷新白屏闪烁 - 骨架屏加载、视图淡入、卡片 hover 上浮,全部遵守 `prefers-reduced-motion` - 图片/视频点击进灯箱,单视频可直接内联播放 ## 界面一览 帖子详情:正文附件、投票、楼层与引用回复(#3 引用了 #2) ![帖子详情与引用回复](docs/screenshots/02-post-detail.png) 群聊:SSE 实时连接、成员与附件消息 ![群聊与附件](docs/screenshots/05-chat-group.png) 私聊与推荐 / 搜索 ![私聊](docs/screenshots/06-chat-private.png) ![热度推荐](docs/screenshots/03-recommend.png) ![关键字搜索](docs/screenshots/04-search.png) 发帖与登录注册 ![发布新帖](docs/screenshots/07-newpost.png) ![登录注册](docs/screenshots/09-auth-modal.png) > 截图中的数据由脚本伪造(职场主题的演示帖子与聊天),仅用于展示界面。仓库与 jar **都不包含任何数据**, > 首次启动是干净的,注册第一个账号即可开始发帖。 ## 皮肤 | `data-theme` | 名称 | 明暗 | 主色 | | --- | --- | --- | --- | | `light` | 清爽白 | 浅 | 蓝 `#2563eb` | | `dark` | 暗夜黑 | 深 | 亮蓝 `#4f8ef7` | | `green` | 护眼豆沙绿 | 浅 | 翡翠绿 `#178f63` | | `sand` | 暖沙杏色 | 浅 | 陶土橙 `#d0562a` | | `ginkgo` | 银杏黄 | 浅 | 金黄 `#d9a514` | | `auto` | 跟随系统 | — | 落到 `light` / `dark` | ![暗夜黑](docs/screenshots/10-theme-dark.png) ![护眼豆沙绿](docs/screenshots/11-theme-green.png) ![暖沙杏色](docs/screenshots/12-theme-sand.png) ![银杏黄](docs/screenshots/13-theme-ginkgo.png) ![皮肤切换菜单](docs/screenshots/08-theme-menu.png) 换一套皮肤 = 新增一组 `html[data-theme=xxx] { … }` 令牌覆盖 + `app.js` 的 `THEMES` 数组加一项,**组件样式一行都不用改**。 ## 快速开始 ### 环境要求 - **JDK 25**(必须)。用 JDK 21 构建会直接报 `错误: 不支持发行版本 25`。 - Maven 不必单独安装,仓库自带 Wrapper(`mvnw` / `mvnw.cmd`)。 ### 方式一:直接跑 jar(推荐) 从 [Releases](https://gitee.com/wxd-gaming/miniblog/releases) 下载 `minilog-1.0.0.jar`: ```bash java -jar minilog-1.0.0.jar # 浏览器打开 http://localhost:18080 ``` 数据自动落在 `./data/rocksdb`(结构化数据)与 `./data/upload`(附件)。删掉这两个目录就等于重置站点。 ### 方式二:从源码构建 ```powershell # Windows PowerShell $env:JAVA_HOME = "C:\java\jdk-25" $env:Path = "C:\java\jdk-25\bin;" + $env:Path .\mvnw.cmd -B -ntp package java -jar target\minilog-1.0.0.jar ``` ```bash # Linux / macOS JAVA_HOME=/path/to/jdk-25 ./mvnw -B -ntp package java -jar target/minilog-1.0.0.jar ``` 只想跑起来不打包:`.\mvnw.cmd spring-boot:run`。 ### 方式三:开发模式热改前端 前端是纯静态文件,`src/main/resources/static/` 下的改动重启即生效;改过 `css/js` 记得自增 `index.html` 里的 `?v=` 缓存版本号。 ## 配置项 `src/main/resources/application.yaml`,全部支持命令行覆盖: ```bash java -jar minilog-1.0.0.jar \ --server.port=8081 \ --minilog.rocksdb.path=/var/lib/minilog/rocksdb \ --minilog.media.path=/var/lib/minilog/upload \ --minilog.jwt.secret="请换成一串至少32字节的随机密钥" ``` | 配置 | 默认值 | 说明 | | --- | --- | --- | | `server.port` | `18080` | HTTP 端口 | | `minilog.rocksdb.path` | `./data/rocksdb` | RocksDB 数据目录,**同一目录不支持多实例打开** | | `minilog.media.path` | `./data/upload` | 附件存储目录 | | `minilog.media.url-prefix` | `/upload` | 附件访问前缀 | | `minilog.jwt.secret` | 内置演示值 | HS256 签名密钥,**生产必须替换** | | `minilog.jwt.expire-minutes` | `120` | 普通登录 token 有效期 | | `minilog.jwt.remember-expire-days` | `30` | 勾选「保持登录状态」后的有效期 | | `spring.servlet.multipart.max-file-size` | `20MB` | 单文件上限 | | `spring.servlet.multipart.max-request-size` | `100MB` | 单请求上限 | ## 架构 ``` controller → service → store → RocksDbStore 参数绑定 业务规则 数据读写 嵌入式 KV ``` ``` src/main/java/wxdgaming/minilog/ ├── common/ ApiException · AuthInterceptor · JwtService · 枚举 ├── config/ WebMvc 配置 · 全局异常处理 · RocksDB 打开与关闭 ├── controller/ Auth / Post / Reply / User / Chat / Media / Spa ├── service/ 业务规则层(投票互斥、入群审批、编辑撤回窗口…) ├── store/ RocksDB 数据访问层(Key 布局在这里) ├── record/ 持久化数据类(Jackson 序列化后作为 RocksDB 的 value) └── dto/ 请求 / 响应对象 src/main/resources/static/ ├── index.html 单页骨架 + 防闪烁内联脚本 ├── css/app.css 设计令牌 + 五套主题覆盖 + 组件样式 └── js/app.js 路由 / 帖子 / 投票 / 发帖 js/chat.js 会话 / 成员 / SSE / 附件 ``` **数据模型三层**:`User → Post → Reply`,外加索引(时间线、标签倒排、用户发帖、关注关系、投票位图、会话/成员/消息/邀请)。 **Key 编码约定**:统一走基座 `k(prefix, long…)`,数值段固定 8 字节大端——字典序等于数值序,因此前缀扫描天然有序。时间线倒序用 `revTs = Long.MAX_VALUE - 毫秒`,最新的一条排在最前面。 **投票位图**:`lk:{postId}` / `dk:{postId}` 各 20 个桶,桶号 `uid % 20`、位 `bit(uid-1)`;赞与踩的互斥由 Service 层「先撤旧再置新」保证。 完整的模块职责、Key 布局全表、聊天状态机与皮肤实现细节见 **[项目结构描述.md](项目结构描述.md)**。 ## API 一览 登录态用 `Authorization: Bearer `。除 `GET` 与 `/api/auth/**` 外均需登录;`GET` 对游客放行,因此需要身份的 `GET` 端点在方法内显式校验。 | 方法 | 路径 | 说明 | | --- | --- | --- | | POST | `/api/auth/register` | 注册(自动登录),201 | | POST | `/api/auth/login` | 登录,`remember` 控制有效期 | | POST | `/api/auth/logout` | 登出并吊销当前 token | | GET | `/api/auth/me` | 当前用户 | | POST | `/api/posts` | 发帖(标题 / 正文 / 标签 / 附件) | | GET | `/api/posts?page=&size=` | 最新时间线 | | GET | `/api/posts/recommend?n=` | 热度推荐 | | GET | `/api/posts/search?q=` | 关键字交集搜索 | | GET | `/api/posts/{id}` | 帖子详情(含 `myVote`) | | POST | `/api/posts/{id}/vote` | `{type: like\|dislike\|none}` | | DELETE | `/api/posts/{id}` | 删帖(仅作者,级联清索引) | | POST | `/api/posts/{postId}/replies` | 回复,`parentReplyId` 可选(引用) | | GET | `/api/posts/{postId}/replies` | 回复分页 | | GET | `/api/posts/{postId}/replies/{replyId}/thread` | 引用链(向上,限深 10) | | POST | `/api/users/{id}/follow` · DELETE | 关注 / 取关 | | GET | `/api/users/search?q=` | 按用户名或昵称找人 | | POST | `/api/upload` | 上传附件,返回 `urls` 与 `items(kind)` | | POST | `/api/chat/groups` · `/api/chat/private` | 建群 / 打开私聊 | | GET | `/api/chat/conversations` | 我的会话(按最近活跃,含未读) | | POST | `/api/chat/conversations/{id}/messages` | 发消息(正文与附件至少一个) | | GET | `/api/chat/conversations/{id}/messages?beforeSeq=&limit=` | 历史消息(游标向前翻) | | POST | `/api/chat/invites/{id}/approve\|accept\|reject\|decline\|cancel` | 两级审批 | | POST | `/api/chat/conversations/{id}/join-requests` | 申请入群 | | POST | `/api/chat/conversations/{id}/read` | 标记已读(幂等) | | POST | `/api/chat/conversations/{id}/messages/{seq}/edit\|recall` | 编辑 / 撤回(5 分钟内) | | GET | `/api/chat/events` | SSE 事件流 | 错误统一由 `GlobalExceptionHandler` 转成 `{code, message}`。 ## 前端路由 | URL | 视图 | | --- | --- | | `/` | 最新(`?page=n` 停在某一页) | | `/recommend` | 推荐 | | `/search?q=关键字` | 搜索结果 | | `/post/{id}` | 帖子详情(`?rpage=n` 停在回复某一页) | | `/chat` · `/chat/{convId}` | 聊天 / 直达某会话 | 新增视图必须**同时**改 `js/app.js` 的 `parseRoute()`/`applyRoute()` 和 `SpaController` 的路径清单,否则刷新就 404——`SpaRouteTests` 是这道契约的回归防线。 ## 测试 ```powershell $env:JAVA_HOME = "C:\java\jdk-25" .\mvnw.cmd -B -ntp test ``` 当前 **53 个测试全部通过**: | 套件 | 数量 | 覆盖 | | --- | --- | --- | | `MinilogFlowTests` | 16 | 注册登录、发帖、投票三态幂等、引用回复、墓碑、引用链、搜索、推荐、关注、越权、参数校验 | | `ChatFlowTests` | 19 | 建群与成员、私聊去重、两级审批全路径、申请入群、找群模糊匹配、消息编辑与撤回、已读未读、SSE 鉴权 | | `RocksDbKeyLayoutTests` | 11 | 纯单元测试:钉死 `k()` 编码与各类索引 key 的段序号 | | `RecordCompatTests` | 4 | record 新增字段后老数据仍可反序列化 | | `SpaRouteTests` | 2 | SPA 回退契约 | | `MinilogApplicationTests` | 1 | 上下文启动 | 测试用 RocksDB 目录每次 JVM 独立(`target/test-rocksdb-${random}`),断言只用相对值,避免历史数据把全局排名类断言带崩。 ## 已知边界 这些是**刻意的单机取舍**,不是待修的 bug: - 单机单进程:RocksDB 同一目录只有一个写实例,不做分布式与多进程共享。 - 回复 `seq` 与消息 `seq` 重启后续发,可能回退少量序号。 - 搜索是简单切词 + 交集,不做相关性打分与分词库。 - 计数走内存快照,进程被强杀最多丢 5 秒增量。 - 附件与站点同源,靠扩展名白名单而非独立域名隔离。 ## 许可 [Apache License 2.0](LICENSE)