# luminest

**Repository Path**: yu---rain/luminest

## Basic Information

- **Project Name**: luminest
- **Description**: 一个从 0 到 1 独立设计并开发的个人开发者成长平台：记录生活、沉淀技术、分享知识，并将 AI 能力深度整合进内容的生产与消费全链路。

不是"又一个博客系统"——AI 不做闲聊，而是围绕站内内容提供 RAG 问答、智能审核、语义搜图、写作辅助等 12 项有明确场景的能力。
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: http://175.24.182.104/home
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-25
- **Last Updated**: 2026-08-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Luminest · 点亮成长的栖息地

> 一个**从 0 到 1 独立设计并开发**的个人开发者成长平台：记录生活、沉淀技术、分享知识，并将 AI 能力深度整合进内容的生产与消费全链路。
>
> 不是"又一个博客系统"——AI 不做闲聊，而是围绕站内内容提供 RAG 问答、智能审核、语义搜图、写作辅助等 **12 项有明确场景的能力**。

## ✨ 项目亮点

### AI 深度整合（核心竞争力）

| 能力 | 说明 |
| --- | --- |
| 🤖 会话式 RAG 问答 | 多轮记忆 + SSE 流式输出 + 引用溯源 + Function Calling 站内工具调用 |
| 🔍 混合检索 | MySQL 全文检索 + pgvector 向量检索双路召回，RRF 融合，gte-rerank-v2 精排 |
| ⚡ 语义缓存 | 相似问题命中缓存直接秒回，实测显著降低 token 成本与响应延迟 |
| 🛡️ 评论三级审核 | 本地敏感词 DFA → LLM 异步审核（事务提交后触发）→ 人工终审 |
| 💬 评论 AI 回复 | 评论 @AI 自动回复，异步执行不阻塞主流程 |
| 🖼️ 照片语义搜索 | 上传时视觉模型（qwen-vl-plus）自动打标 + 向量入库，支持"海边的日落"式自然语言搜图 |
| ✍️ AI 写作助手 | 一键生成摘要 / 标题 / 标签 / 润色，JSON 结构化输出 + 解析兜底 |
| 📊 AI 观测面板 | 全链路埋点：tokens / 耗时 / 成功率 / 缓存命中率 / 场景分布 |
| 🧪 RAG 离线评测 | 自建评测用例集，命中率 / MRR 指标量化检索质量，调优有据可依 |
| 📝 文章 AI 摘要 | Redis + 数据库二级缓存，同文仅生成一次 |
| 🔗 相关文章推荐 | 基于向量相似度而非简单标签匹配 |
| ⏰ 向量索引重建 | 动态定时任务全量重建文章向量 |

### 工程能力

- **鉴权**：Spring Security + JWT + Redis 双校验（支持服务端主动踢下线），RBAC 动态权限（用户-角色-菜单五表 + `@PreAuthorize` 权限点）
- **双库架构**：MySQL 业务主库 + PostgreSQL/pgvector 独立向量库，检索与业务隔离，仍保持单体应用
- **多厂商 AI 接入**：OpenAI 兼容协议，小米 MiMo（对话）/ 阿里百炼（Embedding、视觉、Rerank）按场景选型，配置化切换
- **存储策略模式**：MinIO / 阿里云 OSS 一行配置切换
- **事务与异步的正确姿势**：AI 异步任务在事务提交后（afterCommit）触发；LLM 调用不跨事务，落库走 TransactionTemplate 短事务
- **安全基线**：DOMPurify 防存储型 XSS、敏感配置全环境变量注入、游客限流基于真实 IP、越权统一 403 兜底
- **可观测性**：AI 调用全链路日志落库 + 后台观测面板，业务日志按天滚动

## 🏗️ 技术栈

**后端**

| 技术 | 版本 | 用途 |
| --- | --- | --- |
| Spring Boot | 3.3.5 (JDK 21) | 基础框架 |
| Spring AI | 1.0.0 | LLM / Embedding / 多模态接入 |
| Spring Security + JWT | — | 认证授权（Redis 双校验 + RBAC） |
| MyBatis-Plus | 3.5.7 | ORM（动态 SQL 全部 XML 化） |
| MySQL 8 / Redis 7 | — | 业务主库 / 缓存、登录态、限流 |
| PostgreSQL + pgvector | pg16 | 向量库（HNSW 索引，余弦距离） |
| MinIO / 阿里云 OSS | — | 对象存储（策略模式切换） |
| Knife4j (OpenAPI 3) | — | 在线接口文档 |

**前端**

Vue 3.5 + TypeScript 5.6 + Vite 5 + Pinia + Element Plus + Vditor（所见即所得 Markdown 编辑器）+ ECharts 6 + marked / DOMPurify

**部署**

Docker Compose（多阶段构建）+ Nginx（SSE 长连接 / 真实 IP 透传）

## 📦 功能模块

```
前台（游客）                     后台（RBAC 权限控制）
├── 博客：文章 / 分类 / 标签      ├── 仪表盘：KPI / 趋势 / 分布
├── AI 问答：流式对话 / 会话管理   ├── 内容：文章（Vditor 全屏编辑 + AI 辅助）/ 分类 / 标签
├── 生活：相册(语义搜图) / 游记    ├── 互动：评论（AI 审核结果可视化）/ 留言
│         / 随笔 / 记录 / 点滴    ├── AI：观测面板 / 调用日志 / RAG 评测 / 写作助手
├── 互动：评论(@AI) / 留言板      ├── 系统：用户 / 角色 / 菜单 / 配置 / 文件 / 日志
└── 百宝箱：网址导航              └── 任务：动态定时任务（cron 可视化管理）
```

## 📷 效果预览

| | |
| --- | --- |
| ![登录](image/登录效果图.png) | ![相册](image/相册效果图.png) |
| ![游记](image/游记效果图.png) | ![随笔](image/随笔效果图.png) |
| ![留言](image/留言效果图.png) | |

## 🚀 快速开始

```bash
# 1. 启动中间件（MySQL / Redis / MinIO / pgvector）
docker compose up -d mysql redis minio pgvector

# 2. 初始化数据库（新库：init.sql 建库时自动执行；存量库：手动执行增量升级脚本）
docker exec -i luminest-mysql mysql -uroot -proot luminest < luminest-server/sql/upgrade-v2.0-to-v2.1.sql

# 3. 配置 AI 密钥（环境变量）
export XIAOMI_API_KEY=xxx   # 小米 MiMo（对话）
export ALI_API_KEY=xxx      # 阿里百炼（Embedding / 视觉 / Rerank）

# 4. 启动后端（JDK 21）
cd luminest-server && mvn spring-boot:run

# 5. 启动前端
cd luminest-web && npm install && npm run dev
```

- 前台：`http://localhost:5173` ｜ 后台：登录后自动跳转 ｜ 接口文档：`http://localhost:8080/doc.html`

## 📚 项目文档（0 → 1 全过程）

| 文档 | 说明 |
| --- | --- |
| [PRD.md](docs/PRD.md) | 产品需求文档：v1.0 规划原貌 + 附录《规划 → 落地对照》（记录技术选型决策变更与理由） |
| [API.md](docs/API.md) | 接口文档 v2.0：与代码完全对齐的接口契约、鉴权机制、RAG 链路 |
| [DATABASE.md](docs/DATABASE.md) | 数据库设计 v2.0：32 张表演进对照、pgvector 向量库、Redis 键设计 |
| [DEPLOY.md](docs/DEPLOY.md) | 上线部署手册：2核2G 云服务器 Docker 全栈部署全流程 + 真实踩坑记录，已实机验证 |
| [sql/init.sql](luminest-server/sql/init.sql) | v2.0 生产环境全量基线（建表 + 种子数据），MySQL 容器首次启动自动执行 |
| [sql/upgrade-v2.0-to-v2.1.sql](luminest-server/sql/upgrade-v2.0-to-v2.1.sql) | 幂等增量升级脚本：v2.0 基线之后的变更，后续迭代按 upgrade-vX.Y-to-vX.Z.sql 命名逐个追加 |

> 文档与代码同步演进是本项目的硬性要求：PRD 保留规划期原貌并如实记录"哪些按规划落地、哪些被推翻重选及原因"，这正是真实 0 → 1 过程的印记。

## 📄 License

本项目仅供学习交流。