技术架构

Think Site Manager 采用前后端分离架构，后端基于 Spring Boot 提供 REST API，前端基于 UmiJS Max 构建管理界面。

总体架构

┌─────────────────────────────────────────────────────────────┐
│                      用户浏览器                              │
│  ┌──────────────────────┐    ┌──────────────────────────┐  │
│  │  管理平台 (UmiJS Max) │    │ 文档站点 (VitePress)      │  │
│  │  React + Ant Design  │    │  + 认证插件               │  │
│  └──────────┬───────────┘    └────────────┬─────────────┘  │
└─────────────┼──────────────────────────────┼────────────────┘
              │ HTTP/REST                    │ HTTP/REST
              ▼                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    Spring Boot (Port 8300)                   │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐  │
│  │ JWT 认证  │ │ License  │ │ 业务逻辑  │ │ 插件生成器    │  │
│  │ Filter   │ │ Filter   │ │ Services │ │ Plugin Gen   │  │
│  └──────────┘ └──────────┘ └────┬─────┘ └──────────────┘  │
│                                 │                            │
│                          ┌──────▼──────┐                    │
│                          │  MyBatis-Plus│                    │
│                          └──────┬──────┘                    │
└─────────────────────────────────┼───────────────────────────┘
                                  │
                                  ▼
                    ┌─────────────────────┐
                    │    MySQL 8.x        │
                    │ think_site_management│
                    └─────────────────────┘

技术栈

后端

技术	版本	用途
JDK	17	运行环境
Spring Boot	3.3.2	应用框架
Spring Security	6.3.1	安全认证
MyBatis-Plus	3.5.7	ORM 框架
Knife4j	4.4.0	API 文档 (OpenAPI 3)
jjwt / java-jwt	0.9.1 / 3.11.0	JWT Token 处理
Hutool	5.7.0	工具库
Maven	3.x	构建工具

前端

技术	版本	用途
Node.js	18+	运行环境
UmiJS Max	^4.6.57	React 应用框架
React	18.x	UI 框架
Ant Design	^5.4.0	UI 组件库
ProComponents	^2.4.4	高级业务组件
@ant-design/charts	^2.6.7	数据可视化
pnpm	latest	包管理器

中间件

技术	版本	用途
MySQL	8.x	关系数据库

后端项目结构

backend/
├── pom.xml                    # 父 POM，统一依赖管理
├── admin/                     # 主应用模块
│   ├── pom.xml
│   └── src/main/java/cool/webstudy/admin/
│       ├── AdminApplication.java          # Spring Boot 启动类
│       ├── configuration/                 # 配置类 (Knife4j, Security, MyBatis-Plus)
│       ├── controller/                    # REST Controller
│       │   ├── auth/                      # 认证接口
│       │   ├── dashboard/                 # 数据看板接口
│       │   ├── invite/                    # 邀请码接口
│       │   ├── site/                      # 站点/文章/绑定/插件接口
│       │   ├── system/                    # License 接口
│       │   └── user/                      # 用户接口
│       ├── filter/security/               # JWT + License + SiteToken 过滤器
│       ├── mapper/                        # MyBatis-Plus Mapper 接口
│       ├── model/
│       │   ├── dto/                       # 请求 DTO
│       │   ├── po/                        # 持久化对象 (PO)
│       │   └── vo/                        # 响应 VO
│       ├── service/                       # 业务服务接口 + 实现
│       └── utils/                         # 工具类 (JWT, AES, License)
├── common/                     # 共享模块
│   └── src/main/java/cool/webstudy/common/
│       ├── constant/enums/                # 通用枚举
│       ├── model/                         # 共享 PO/DTO
│       └── utils/                         # 通用工具 (UUID)
└── license-gen/                # License 生成 CLI 工具

Maven 多模块设计

common 模块不依赖 Spring，可独立被其他 Java 项目引用。admin 模块依赖 common，包含全部业务逻辑。license-gen 是独立 JAR，用于离线生成 .lic 授权文件。

前端项目结构

frontend/
├── .umirc.ts                  # UmiJS 配置 (路由、代理、插件)
├── package.json
├── src/
│   ├── app.tsx                # 运行时配置 (初始化、Layout、请求拦截)
│   ├── access.ts              # 权限定义
│   ├── pages/                 # 页面组件
│   │   ├── Home/              # 首页数据看板
│   │   ├── Site/              # 站点管理 (含 Detail)
│   │   ├── Article/           # 文章管理
│   │   ├── User/              # 人员管理
│   │   ├── InviteCode/        # 邀请码管理
│   │   ├── Profile/           # 个人信息
│   │   ├── Login/             # 登录页
│   │   ├── Register/          # 注册页
│   │   └── Activate/          # License 激活页
│   ├── components/            # 共享组件
│   ├── services/site/         # API 请求服务层
│   ├── models/                # 全局状态 (Umi plugin-model)
│   └── constants/             # 常量定义
└── mock/                      # 开发 Mock 数据

页面路由

路由	组件	权限	说明
`/home`	Home	已登录	数据看板
`/site`	Site	站点管理权限	站点列表
`/site/:unCode`	Site/Detail	站点管理权限	站点详情
`/article`	Article	站点管理权限	文章管理
`/user`	User	用户管理权限	人员管理
`/invite-code`	InviteCode	站点管理权限	邀请码管理
`/profile`	Profile	已登录	个人信息
`/login`	Login	公开	登录页
`/register`	Register	公开	注册页
`/activate`	Activate	公开	License 激活

数据库设计

数据库名称：think_site_management，共 5 张业务表。

mermaid

erDiagram
    user ||--o{ user_site_binding : "绑定"
    site ||--o{ user_site_binding : "被绑定"
    site ||--o{ article : "包含"
    invite_code ||--o{ user : "注册时使用"

    user {
        bigint id PK "自增主键"
        char un_code "业务主键 (UUID)"
        varchar account "账号"
        varchar username "用户名称"
        varchar password "密码 (BCrypt)"
        varchar role "角色: SYSTEM/ADMIN/SITE_ADMIN/USER"
        varchar status_flag "状态: ENABLED/DISABLED"
        datetime create_time "创建时间"
    }

    site {
        bigint id PK "自增主键"
        varchar un_code "业务主键 (UUID)"
        varchar name "站点名称"
        varchar description "站点描述"
        varchar url "站点地址"
        varchar site_token "API Token"
        varchar status_flag "状态: ONLINE/OFFLINE/ENABLED/DISABLED"
    }

    article {
        bigint id PK "自增主键"
        varchar un_code "业务主键 (UUID)"
        varchar site_un_code "所属站点"
        varchar path "文章路径"
        varchar title "文章标题"
        tinyint is_paid "付费标记: 0免费/1付费"
    }

    user_site_binding {
        bigint id PK "自增主键"
        varchar un_code "业务主键 (UUID)"
        varchar user_un_code "用户"
        varchar site_un_code "站点"
        varchar role "角色: ADMIN/MEMBER"
    }

    invite_code {
        bigint id PK "自增主键"
        char un_code "业务主键 (UUID)"
        varchar code "邀请码 (8位)"
        int max_uses "最大使用次数"
        int used_count "已使用次数"
        varchar status_flag "状态: ENABLED/DISABLED"
        datetime expire_time "过期时间"
    }

设计特点

🔑 业务主键 + 自增主键：un_code (UUID) 作为对外暴露的业务标识，id 作为内部自增主键
♻️ 逻辑删除：所有表通过 del_flag 字段标记删除（0=正常，1=已删），数据不可逆
🔒 密码加密：用户密码使用 BCrypt 加密存储
🔗 软关联：表之间通过 un_code 字段关联，而非数据库外键

安全体系

多层过滤链

请求 → LicenseFilter → SiteTokenFilter → JWTAuthenticationFilter → Controller

过滤器	优先级	职责
`LicenseFilter`	最高	拦截所有请求，验证 License 有效性，无效则返回激活提示
`SiteTokenAuthenticationFilter`	中	通过 `X-Site-Token` 头校验第三方站点身份
`JWTAuthenticationFilter`	最低	校验 Bearer Token，解析用户身份写入 SecurityContext

JWT 认证流程

用户通过 /api/user/login 登录，返回加密 JWT Token
前端存储 Token 到 localStorage
后续请求通过 Authorization: Bearer <token> 头携带
JWTAuthenticationFilter 解析 Token，获取用户信息注入 Spring Security Context
JWT Payload 中的用户标识通过 AES 加密保护

License 授权系统

🔑 RSA 签名：License 文件包含 RSA 数字签名，防止伪造
💻 硬件绑定：支持绑定服务器 MAC 地址和 IP 地址
⏰ 定时校验：每小时自动重新验证 License 有效期
⛔ 过期保护：License 失效后所有接口返回 LICENSE_INVALID

API 设计规范

统一响应格式

所有 API 返回统一格式：

json

{
  "success": true,
  "code": "00000",
  "message": "操作成功",
  "data": { }
}

分页响应

json

{
  "success": true,
  "data": {
    "records": [],
    "current": 1,
    "pages": 10,
    "size": 20,
    "total": 200
  }
}

API 文档

开发环境启动后端后，可通过 Knife4j 访问在线 API 文档：

Swagger UI：http://localhost:8300/api/doc.html
OpenAPI JSON：http://localhost:8300/api/v3/api-docs

代码规范体系

项目目录 rules/ 下包含完整的开发规范文档：

规范	覆盖范围
`project-structure.md`	总体架构、模块划分、目录结构
`naming-conventions.md`	类名、方法名、变量名、包名规范
`database-design.md`	表设计、字段类型、索引、逻辑删除
`backend-standards.md`	Controller/Service/Mapper 分层规范
`frontend-standards.md`	组件、服务、路由、状态管理规范
`api-design.md`	REST 风格、请求/响应格式、错误码

下一步

了解了技术架构后，可以继续阅读部署说明开始部署平台。

技术架构 ​

总体架构 ​

技术栈 ​

后端 ​

前端 ​

中间件 ​

后端项目结构 ​

前端项目结构 ​

页面路由 ​

数据库设计 ​

设计特点 ​

安全体系 ​

多层过滤链 ​

JWT 认证流程 ​

License 授权系统 ​

API 设计规范 ​

统一响应格式 ​

分页响应 ​

API 文档 ​

代码规范体系 ​