阈界事务所 · Backend

一个用于记录、归档和探索异常事件的微服务平台

项目简介

阈界事务所（YJSWS）是一个社区驱动的平台，用于收集、整理和探索各类异常与未解事件的记录。本仓库为项目后端，基于 Spring Boot 3 / Spring Cloud 微服务架构，提供用户认证、档案管理、评论互动、图片上传等核心能力。

核心功能

• 用户体系 — 手机号 + 密码注册、微信小程序登录、个人资料管理、收藏与浏览历史追踪
• 档案管理 — 丰富的档案 CRUD，支持结构化元数据（时间线、人物关系图、证据链、参考链接、标签）
• 评论系统 — 档案评论，通过服务间调用丰富用户信息
• 图片上传 — 基于 Cloudflare R2 对象存储，通过 AWS S3 SDK 访问
• 新闻模块 — 异常事件新闻，支持草稿/发布/下线生命周期（基础设施已就绪，服务开发中）
• API 网关 — 统一 JWT 鉴权、路由级访问控制、CORS 处理
• 服务发现与配置 — 基于 Nacos 的服务注册发现和集中配置管理

系统架构

                        ┌─────────────┐
                        │   客户端     │
                        └──────┬──────┘
                               │
                        ┌──────▼──────┐
                        │    网关      │  :10891
                        │  JWT 鉴权   │
                        └──────┬──────┘
                               │
              ┌────────────────┼────────────────┐
              │                │                │
       ┌──────▼──────┐ ┌──────▼──────┐ ┌───────▼─────┐
       │   认证服务   │ │  用户服务    │ │  档案服务    │
       │    Auth     │ │User Service │ │  Archive    │
       │   :10890    │ │   :10889    │ │   :10888    │
       └──────┬──────┘ └──────┬──────┘ └──────┬──────┘
              │                │                │
              └────────────────┼────────────────┘
                               │
                    ┌──────────▼──────────┐
                    │       Nacos         │
                    │  服务发现 + 配置中心  │
                    │      :8848          │
                    └─────────────────────┘

请求认证流程

1. 所有请求经由 Gateway 网关，AuthGlobalFilter 校验 JWT Authorization 请求头
2. 白名单路径（登录、注册、公开读取）免认证放行
3. JWT 校验通过后，网关提取 userId 并注入 X-User-Id 请求头
4. 下游服务通过 UserInterceptor → UserContext（ThreadLocal<Long>）获取当前用户

服务间通信

服务间通过 OpenFeign 进行 RPC 调用，客户端接口定义在 api 模块中：

模块说明

技术栈

快速开始

环境要求

• Java 17+（推荐 Eclipse Temurin）
• Maven 3.9+（或使用项目内置的 Maven Wrapper ./mvnw）
• PostgreSQL 13+（需启用 PostGIS 扩展）
• Redis
• Nacos 2.3.0（单机模式）

构建

# 构建所有模块
./mvnw package -DskipTests

# 构建单个模块
./mvnw package -DskipTests -pl archive-service

运行测试

# 运行全部测试
./mvnw test

# 运行单个模块测试
./mvnw test -pl archive-service -Dtest=StorageServiceImplTest

启动服务

构建完成后可逐个启动：

java -jar gateway/target/gateway-0.0.1-SNAPSHOT.jar
java -jar auth/target/auth-0.0.1-SNAPSHOT.jar
java -jar user-service/target/user-service-0.0.1-SNAPSHOT.jar
java -jar archive-service/target/archive-service-0.0.1-SNAPSHOT.jar

环境配置

通过 -Dspring.profiles.active=dev 切换，或直接编辑各服务的 bootstrap.yml。

Docker 部署

Docker Compose 一键启动

项目内置 dockercompose.yml，可一键拉起完整基础设施：

# 先构建所有模块
./mvnw package -DskipTests

# 启动所有服务
docker compose -f dockercompose.yml up -d

启动的容器：

所有服务运行在 lia-net 桥接网络中，JVM 参数为 -Xms256m -Xmx512m。

构建单个服务的 Docker 镜像

docker build --build-arg MODULE=archive-service -t yjsws-archive .

配置管理

配置集中托管在 Nacos 中，各服务的 bootstrap.yml 声明需要拉取的共享配置：

各服务通过 lia.jdbc.database 设置自己的数据库名（如 lia_archive、lia_user、lia_auth）。

API 概览

所有接口统一返回 Result<T> 格式：

{
  "code": 200,
  "message": "success",
  "data": { ... }
}

分页接口返回 PageResult<T>：

{
  "code": 200,
  "message": "success",
  "data": {
    "list": [ ... ],
    "total": 42
  }
}

网关路由

主要接口

认证（/auth）

档案（/archives）

用户（/user）

上传（/upload）

完整 API 文档请参阅 doc/API.md。各服务同时提供 SpringDoc OpenAPI 在线文档，访问 /swagger-ui.html。

项目结构

yjsws_backend/
├── api/ # OpenFeign 客户端接口
│ └── src/main/java/
│ └── asia.liminality.api.client/
│ ├── ArchiveClient.java
│ ├── UserClient.java
│ └── NewsClient.java
├── archive-service/ # 档案服务：CRUD、评论、R2 上传
│ └── src/main/java/
│ └── asia.liminality.archive/
│ ├── config/ # R2Config、OpenApiConfig、MybatisPlusConfig
│ ├── controller/ # ArchiveController、CommentController、UploadController
│ ├── domain/ # DTO、VO、PO
│ ├── mapper/ # ArchiveMapper、CommentMapper
│ └── service/ # IArchiveService、ICommentService、StorageService
├── auth/ # 认证服务：登录与 JWT 签发
│ └── src/main/java/
│ └── asia.liminality.auth/
│ ├── config/ # SecurityConfig、WechatMiniappProperties
│ ├── controller/ # AuthController
│ ├── entity/ # DTO、VO
│ ├── service/ # AuthService
│ └── util/ # JwtUtil
├── common/ # 公共库
│ └── src/main/java/
│ └── asia.liminality.common/
│ ├── config/ # WebConfig、MybatisPlusConfig
│ ├── constant/ # InterceptorsConstants、ArchiveConstants
│ ├── context/ # UserContext（ThreadLocal）
│ ├── domain/ # 共享 PO、DTO、VO、枚举
│ ├── exceptionHandler/ # GlobalExceptionHandler
│ ├── interceptor/ # UserInterceptor
│ └── utils/ # AuthUtils
├── gateway/ # API 网关
│ └── src/main/java/
│ └── asia.liminality.gateway/
│ ├── filter/ # AuthGlobalFilter
│ └── util/ # JwtUtil
├── user-service/ # 用户服务
│ └── src/main/java/
│ └── asia.liminality.user/
│ ├── config/ # OpenApiConfig
│ ├── controller/ # UserController、UserCollectController 等
│ ├── domain/ # DTO、VO、PO
│ ├── mapper/ # UserMapper、UserCollectMapper 等
│ └── service/ # IUserService、IAdviceService 等
├── doc/ # 文档
│ ├── API.md # 完整 API 参考
│ └── ROADMAP.md # 功能路线图
├── dockercompose.yml # Docker Compose 编排
├── Dockerfile # 多服务 Docker 镜像
└── pom.xml # 父 POM（聚合器）

数据库表结构

认证与授权

• JWT 认证：由 auth 服务签发 Token，gateway 网关统一校验
• 密码加密：使用 BCryptPasswordEncoder 进行哈希存储
• 微信登录：小程序 jscode2session 流程，支持自动注册
• 访问控制：AuthGlobalFilter 中配置路由级白名单
  • 免认证（公开）：登录、注册、微信登录、档案统计、搜索、公开读取（GET）
  • 需认证：所有写操作、个人资料访问

路线图

进行中

• 更精细的档案筛选过滤
• 后端缓存优化
• 游标分页（修复无限滚动重复问题）
• 举报功能
• 等级 / 经验系统
• 分享功能
• 外部来源链接展示 & Bilibili 视频嵌入

规划中

• 有声书支持（档案超过 1000 字自动生成）
• 地图页面（在地图上查看历史异常事件）
• 社交动态 / 时间线
• 多级嵌套评论与回复通知
• 关注用户间私信
• 专题案件页面（一个案件关联多份档案）
• 用户投稿异常视频专区
• 侦探专区（协作破解悬案）
• AI 驱动的全球案件趋势分析

完整路线图请参阅 doc/ROADMAP.md。

待办事项

• 统一 auth 与 gateway 的 JWT 密钥至 Nacos（shared-jwt.yaml）
• 集成 Sentinel 实现限流 / 熔断
• 将 OpenFeign 迁移至 Dubbo
• 修复批量查询性能问题
• 解耦 Controller / Service 返回值与 Result 的耦合
• 优化 CORS 配置
• 解耦 auth 对 user-service 的直接 Maven 依赖
• 实现 news-service 模块

许可证

本项目为私有项目，保留所有权利。