likebocai-java · 3.0.0.260708_Likebocai

门户网站后端服务 — 主站、博客、游戏、时光邮箱、管理后台的统一 API 层。

上一版：2.0.0.231224_Likebocai · 前端：Nuxt 4（独立项目）

---

技术栈

分类	选型	说明
JDK	21 LTS	虚拟线程
框架	Spring Boot 3.5.16	Spring Security 6.x
ORM	MyBatis 3 + PageHelper	纯 MyBatis，非 Plus
数据库	PostgreSQL 17	已部署
缓存	Redis 单机	已部署
MQ	RabbitMQ	延迟消息 + 异步解耦
搜索	Meilisearch	REST API，100-300MB
文档	SpringDoc + Knife4j 4.5	GroupedOpenApi 分组 + OAuth2
文件	腾讯云 COS
邮件	腾讯云 SMTP
CI/CD	Forgejo Actions	自托管
部署	物理机单体 JAR	8GB 内存

---

项目结构（12 个 Maven 子模块）

likebocai-parent (3.0.0.260708_Likebocai)
│
├── 🔹 基础层
│   ├── likebocai-common            纯工具 — Result、异常、常量 ✅
│   └── likebocai-module-shared     公用实体+枚举 — User、Comment... ✅
│
├── 🔸 基础设施层
│   ├── likebocai-module-storage    腾讯云 COS 📁
│   └── likebocai-module-mail       腾讯云 SMTP 📁
│
├── 🟢 业务层
│   ├── likebocai-module-auth       认证（JWT+Security 已写完，DTO/Mapper 待写）
│   ├── likebocai-module-blog       博客 📁
│   ├── likebocai-module-game       游戏（依赖 storage + meilisearch + pac4j）📁
│   ├── likebocai-module-mailbox    时光邮箱（RabbitMQ 延迟投递）📁
│   ├── likebocai-module-admin      管理后台 📁
│   └── likebocai-module-www        主站聚合（依赖 blog+game+mailbox+Redis）📁
│
├── 🔧 消费层
│   └── likebocai-module-worker     RabbitMQ 消费者（可独立部署）📁
│
└── 🚀 启动层
    └── likebocai-app               聚合全部 + Knife4j + SwaggerConfig ✅

✅ = 代码已实现 · 📁 = 目录就绪待开发

依赖矩阵速查

模块	Web	Security	OAuth2	MyBatis	AMQP	Redis	Meili	其他
auth	✅	✅	✅	✅	—	—	—	jjwt, mail
blog	✅	—	—	✅	—	—	—	storage
game	✅	—	—	✅	—	—	✅	storage, pac4j
mailbox	✅	—	—	✅	✅	—	✅	storage, mail
admin	✅	✅	—	✅	—	—	—	—
www	✅	—	—	—	—	✅	—	blog+game+mailbox
worker	—	—	—	✅	✅	—	✅	mail
app（聚合）	✅	✅	✅	✅	✅	✅	✅	Knife4j

模块职责与依赖

模块	做什么	依赖谁
common	工具层：Result、异常、常量	无
shared	公用实体：User、Comment、Tag...	common
storage	COS 文件服务	common
mail	SMTP 邮件服务	common
auth	登录注册 + JWT + OAuth2 SSO	common + shared + mail + mybatis
blog	文章·随手拍·友链·朋友圈	common + shared + storage + mybatis
game	游戏百科·论坛·成就·平台同步	common + shared + storage + mybatis + meilisearch + pac4j
mailbox	时光邮箱·延迟投递	common + shared + storage + mail + mybatis + amqp + meilisearch
admin	管理后台·数据看板·审核	common + shared + mybatis
www	首页聚合（依赖 blog+game+mailbox）	common + shared + redis + blog + game + mailbox
worker	MQ 消费者（可独立部署）	common + shared + mail + mybatis + amqp + meilisearch
app	启动层，聚合所有打 fat JAR	以上全部 + Knife4j

设计原则

• 谁用谁引：blog 不需要 AMQP，就不引入
• 基础设施复用：storage 和 mail 作为独立模块，谁需要谁依赖
• 单体/微服务双模：app 聚合所有模块打 fat JAR；Worker 加启动类即可独立部署
• Knife4j 只在 app：统一在启动层配置，按包名扫描各模块 Controller
• common 不碰框架：只放纯 Java 工具，换了项目也能用

依赖链： app（聚合全部）→ 业务模块（auth/blog/game/...）→ 基础设施（storage/mail）→ shared → common

---

快速开始

环境

• JDK 21
• Maven 3.8+
• PostgreSQL 17 / Redis / RabbitMQ / Meilisearch（需已启动）

构建

cd likebocai-java
mvn clean package -pl likebocai-app -am -DskipTests

产物：likebocai-app/target/likebocai-3.0.0.260708_Likebocai.jar

运行

# 开发环境
java -jar likebocai-app/target/likebocai-3.0.0.260708_Likebocai.jar --spring.profiles.active=dev

# 生产环境
java -jar likebocai-app/target/likebocai-3.0.0.260708_Likebocai.jar --spring.profiles.active=prod

API 文档

启动后访问：http://localhost:8080/doc.html

右上角 "Authorize" 按钮 → 输入账号密码获取 Token → 可在线测试所有接口。

---

配置

敏感信息走环境变量，不写死在配置文件里：

变量	说明	默认值
DB_USERNAME	PG 用户名	postgres
DB_PASSWORD	PG 密码	postgres
REDIS_HOST	Redis 地址	localhost
REDIS_PASSWORD	Redis 密码	—
RABBITMQ_HOST	RabbitMQ 地址	localhost
RABBITMQ_USERNAME	RabbitMQ 用户	guest
RABBITMQ_PASSWORD	RabbitMQ 密码	guest
MEILISEARCH_HOST	Meilisearch 地址	http://localhost:7700
MEILISEARCH_API_KEY	Meilisearch Key	—
COS_SECRET_ID	腾讯云 COS ID	—
COS_SECRET_KEY	腾讯云 COS Key	—
MAIL_USERNAME	SMTP 用户名	—
MAIL_PASSWORD	SMTP 密码	—

---

版本号规则

大版本.功能更新.Bug修复.日期_代号
3.0.0.260708_Likebocai

更新版本号时用 Maven 命令一键同步所有子模块：

mvn versions:set -DnewVersion=X.X.X.YYMMDD_Likebocai
mvn versions:commit

---

业务模块

模块	子域名	功能
www	主站	首页聚合各模块内容
admin	管理	内容审核、用户管理、数据看板
game	游戏	游戏百科、教程、论坛、Steam/PS/Xbox/NS 数据同步、成就系统、游戏墙
blog	博客	文章发布、随手拍、友链、朋友圈
时光邮箱	时光	写信给未来、三种可见性、定时邮件投递

时光邮箱

• 用户写信设定未来发送时间
• 三种可见性：公开新建 / 到达再公开 / 匿名
• RabbitMQ 延迟消息触发腾讯云 SMTP 投递
• 每封信有评论区

游戏数据同步

平台	认证方式	可获取数据
Steam	OpenID 2.0 + Web API Key	游戏列表、时长、成就
Xbox	OAuth2 (Microsoft)	成就、游戏列表、Gamerscore
Nintendo	OAuth 2.0（非标准）	游戏列表、游玩时长
PSN	逆向 OAuth	奖杯、游戏列表

---

API 规范

• 前缀：/api/v3/
• 统一响应：Result<T> { code, message, data }
• 分页响应：PageResult<T> { list, total, pageNum, pageSize, totalPages }
• 认证：JWT Bearer Token（Header: Authorization: Bearer <token>）

---

搜索架构

公开内容：  Nuxt 4 → Meilisearch 直连（Tenant Token）
私有内容：  Nuxt 4 → Java 后端 → Meilisearch（Session 校验）
数据同步：  业务模块 → RabbitMQ → 消费者 → Meilisearch 写入

---

服务拆分指南

项目设计为 单体 / 微服务双模，可按需拆分。

拆分 Worker 到闲置机器

# 1. Worker 模块加启动类 WorkerApplication
# 2. Worker pom.xml 加 spring-boot-maven-plugin
# 3. 配置 application-worker.yml（web-application-type: none）

# 构建
mvn clean package -pl likebocai-module-worker -am -DskipTests

# 部署到闲置机器
scp likebocai-module-worker/target/likebocai-worker-*.jar user@闲置:/opt/likebocai/
ssh user@闲置 "java -jar /opt/likebocai/likebocai-worker-*.jar --spring.profiles.active=worker"

拆分通用步骤

步骤	操作
1	目标模块加 Spring Boot 启动类
2	pom.xml 加 spring-boot-maven-plugin
3	配置独立 YML（web-application-type: none）
4	主服务 pom 注释掉该模块依赖
5	分别构建，通过 RabbitMQ 通信

详见 claude/CLAUDE.md 完整拆分指南

---

后续规划

• 游戏数据抓取服务独立部署（MQ 解耦）
• 邮件发送服务独立部署
• Meilisearch 内存观察，必要时换 ZincSearch
• PSN 数据同步调研