# xu

**Repository Path**: chenzhanxu/xu

## Basic Information

- **Project Name**: xu
- **Description**: 🖋️ 个人博客系统：Go + Gin 模块化后端（SQLite/MySQL 可切换）+ Vue3 PC 端 + Vant 手机端，支持文章/分类/标签/图库/链接分类/项目(含 Gitee README 导入)/评论审核/归档，Docker 一键部署
- **Primary Language**: Go
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-22
- **Last Updated**: 2026-09-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<div align="center">

# 🖋️ xu · 个人博客系统

**前后端分离 · 模块化设计 · 三端一体（PC 博客 / 手机端 / 管理后台）**

[![Go](https://img.shields.io/badge/Go-1.27+-00ADD8?style=for-the-badge&logo=go&logoColor=white)](https://go.dev)
[![Gin](https://img.shields.io/badge/Gin-Web_Framework-009688?style=for-the-badge&logo=gin&logoColor=white)](https://gin-gonic.com)
[![GORM](https://img.shields.io/badge/GORM-ORM-00ADD8?style=for-the-badge&logo=go&logoColor=white)](https://gorm.io)
[![Vue3](https://img.shields.io/badge/Vue_3-Composition-42b883?style=for-the-badge&logo=vue.js&logoColor=white)](https://cn.vuejs.org)
[![Vite](https://img.shields.io/badge/Vite-6-646cff?style=for-the-badge&logo=vite&logoColor=white)](https://vitejs.dev)
[![Element Plus](https://img.shields.io/badge/Element_Plus-UI-409eff?style=for-the-badge&logo=element&logoColor=white)](https://element-plus.org)
[![Vant](https://img.shields.io/badge/Vant-Mobile_UI-1989fa?style=for-the-badge&logo=vant&logoColor=white)](https://vant-ui.github.io)
[![Docker](https://img.shields.io/badge/Docker-Compose-2496ed?style=for-the-badge&logo=docker&logoColor=white)](https://www.docker.com)
[![License](https://img.shields.io/badge/License-MIT-22c55e?style=for-the-badge&logo=open-source-initiative&logoColor=white)](LICENSE)

</div>

---

## ✨ 功能特性

### 🏠 博客前台

| 模块 | 说明 |
|---|---|
| 📝 **文章系统** | Markdown 写作/渲染、代码高亮、多关键词搜索（标题/摘要/正文）、阅读时长/字数、阅读进度条 |
| ❤️ **点赞 / 收藏 / 分享** | 计数真实持久化、粒子爆裂动画、玻璃分享面板（复制 / 系统分享 / 微博 / QQ / 微信 / X）、点击外部关闭 |
| 💬 **评论系统** | 读者评论 → 后台审核 → 通过后展示 |
| 📂 **分类 / 🏷️ 标签** | 默认分类（技术文章 / 随笔记 / 生活圈），分类/标签带文章数统计 |
| 🗂️ **归档** | 按 年 → 月 归档 + 发布热力图 |
| 🖼️ **图库** | 图片分类管理、点击大图预览 |
| 🔗 **链接** | 分类化管理（AI / 视频 / 知识 / 图库 / 好友博客…），后台可自建分类 |
| 🚀 **项目合集** | 旗舰卡片展示、在线演示内嵌预览、**一键导入 Gitee 仓库 README 作为项目介绍** |
| 👤 **关于我** | 个人简介（头像 / 昵称 / 所在地）+ Markdown 主页 |
| 📡 **RSS / Sitemap** | 订阅源 + SEO 站点地图 |
| 📧 **邮箱订阅** | 页脚订阅表单，后台查看订阅增长 |
| ⏱️ **博客运行时间** | 持久化上线时间，跨重启累计 |
| 🔌 **插件渲染** | 已启用插件（如天气 / 名言卡片）动态渲染到侧边栏，独立插件仓库管理 |

### 🛠️ 管理后台

| 模块 | 说明 |
|---|---|
| 📊 **仪表盘** | 全站统计卡片 + 热门文章 / 最新文章 / 最新评论 + 访问趋势 |
| 📝 **文章管理** | 三态发布（草稿 / 已发布 / **未发布**，可取消发布/重新发布）、Markdown 编辑器 |
| 🗂️ **分类 / 标签** | 增删改查 + 文章数统计 |
| 🔗 **链接管理** | 链接与链接分类合并管理，分类筛选 |
| 🚀 **项目管理** | CRUD + Gitee README 导入 |
| 🖼️ **图库管理** | 图片分类 + 上传（自动生成 400px 缩略图） |
| 💬 **评论管理** | 审核 / 通过 / 拒绝，折叠列表 + 单行截断 |
| 🔌 **插件管理** | 插件列表 / 市场（扫描 Gitee 插件仓库，图标直链）/ 安装 / 卸载 / 启用 / 禁用 / 配置弹窗（schema 驱动） |
| 🔐 **安全设置** | 安全事件日志（分类/级别筛选）、IP 封禁/解封/白名单、风险评分、安全态势时间线、策略配置 |
| 📈 **访问管理** | PV / UV / IP / 实时在线 / 趋势曲线 |
| 🧭 **访问行为** | 来源渠道 / 搜索关键词 / 地域分布 / 设备浏览器 / 停留时长 / 跳出率 / **点击热图** |
| 🖥️ **系统监控** | 运行记录、操作审计、CPU / 内存 / 磁盘、月度流量、服务状态、日志监控（访问/错误） |
| 🌐 **SEO 管理** | 收录率 / 爬虫访问 / 关键词排名 / 外链 / 站内死链检测 |
| 🗃️ **数据管理** | 数据库状态 / 一键切换（SQLite·MySQL·PostgreSQL）/ 迁移 / 重启 / 连通性测试 |
| ⚡ **资源管理** | 页面静态资源加载监控（图片 / CSS / JS / 字体耗时与大小） |
| 👤 **个人中心 / 账户** | 账户安全评分（5 项加权）、设备管理（单会话/单踢/全踢）、登录历史（失败标红/新设备角标）、修改密码（强度校验+生成器+历史复用检测）、TOTP 两步验证 |

### 🛡️ 安全体系

| 能力 | 说明 |
|---|---|
| 🔑 **JWT 鉴权** | token 版本号 + jti 会话双重校验，改密/踢出即时失效 |
| 🚦 **复合登录限流** | IP 维度 + 账号维度（防代理池换 IP 绕过 X-Forwarded-For 伪造） |
| 🔐 **TOTP 两步验证** | AES-GCM 加密存储密钥（防 DB 泄露绕过）、绑定/启用/禁用 |
| 💻 **单会话策略** | 管理员仅一台设备在线，新登录自动顶掉其他设备 |
| 🕵️ **攻击检测中间件** | 目录遍历 / SQL 注入 / 漏洞扫描等恶意请求自动拦截并记录日志 |
| ⛔ **IP 封禁 / 白名单** | 手动封禁（可设时长）、封禁历史、白名单放行、风险评分自动封禁 |
| 📋 **安全审计** | 登录 / 扫描 / 垃圾评论 / 完整性 / 流量五类事件全量留痕 |
| 🔁 **密码策略** | 三类强度校验 + 近 5 次密码历史防复用 + 180 天更新提醒 |
| 🧹 **会话自动清理** | 启动 + 每 24h 清理过期/已撤销会话，防表膨胀 |

## 🧱 技术栈

| 端 | 技术 |
|---|---|
| **后端** | Go 1.27 + [Gin](https://gin-gonic.com) + [GORM](https://gorm.io) + JWT + bcrypt + goldmark |
| **数据库** | SQLite（零配置）· MySQL · PostgreSQL（改配置即切） |
| **PC 前端** | Vue 3 + Vite + TypeScript + Element Plus + Pinia |
| **手机端** | Vue 3 + Vite + Vant（独立项目，移动端专属布局） |
| **部署** | Docker Compose 一键启动（三容器 + 数据持久化） |

## 📁 目录结构

```
xu/
├── backend/                     # 🐹 Go + Gin API 服务（按业务域模块化）
│   ├── main.go                  # 入口：配置 → 数据库 → 模块装配
│   ├── config/                  # config.yaml（数据库/端口/JWT/上传/安全策略）
│   ├── pkg/                     # 🧰 基础设施（database / jwt / middleware / ratelimit / response）
│   ├── modules/                 # 🧩 18 个业务模块（model / dto / service / handler / router）
│   │   ├── modules.go           # 模块装配中心（新模块登记一行即可挂载）
│   │   ├── auth/                # 🔐 登录/JWT/单会话/TOTP 加密/设备管理/安全评分
│   │   ├── post/ category/ tag/ # 📝 文章 / 📂 分类 / 🏷️ 标签
│   │   ├── links/ projects/ gallery/ comments/   # 🔗 🚀 🖼️ 💬
│   │   ├── site/ feed/ upload/  # 👤 站点信息 / 📡 RSS·Sitemap / 📤 上传（缩略图）
│   │   ├── engagement/          # ❤️ 点赞/收藏/分享（每日每 IP 去重）+ 📧 订阅
│   │   ├── dashboard/           # 📊 后台仪表盘统计
│   │   ├── monitor/             # 📈 访问统计/行为分析/热图 + 🖥️ 系统监控
│   │   ├── seo/                 # 🌐 收录/关键词/外链/死链
│   │   ├── security/            # 🛡️ 攻击检测/封禁/白名单/安全日志
│   │   ├── plugin/              # 🔌 插件管理（submodule → plugin_-manager 仓库）
│   │   └── dbmanage/            # 🗃️ 数据库切换/迁移/重启
│   ├── run_supervisor.sh        # 🔁 进程守护（异常退出自动拉起）
│   └── xu-blog-server           # 编译产物
│
├── frontend/                    # 💻 PC 端（app / shared / modules 三层）
│   └── src/
│       ├── app/                 # 应用壳：入口、路由汇总、全局样式（玻璃拟态设计语言）
│       ├── shared/              # 共享：axios 封装、类型、Markdown/高亮工具、缩略图工具
│       └── modules/
│           ├── blog/            # 博客前台（11 个页面）
│           └── admin/           # 管理后台（仪表盘/内容/数据/安全/账户五大分区）
│
├── plugins/                     # 🔌 运行时插件目录（gitignore，从 plugin_-manager 自动恢复）
├── mobile/                      # 📱 手机端（独立 Vant 项目，12 个页面）
├── deploy/                      # 🚀 部署：1Panel 编排 / CDN 接入指南
├── docs/                        # 📚 开发文档（用户模块等）
├── docker-compose.yml           # 🐳 一键部署编排
└── scripts/
    ├── backup.sh                # 💾 数据备份（SQLite + 上传图片，默认保留 7 份）
    └── smoke.sh                 # 🔥 端到端冒烟测试
```

## 🔌 API 约定

- `/api/*` —— 公开接口（文章、分类、评论、互动、RSS 等，挂**恶意请求检测中间件**）
- `/api/admin/*` —— 管理端接口（统一 **JWT + token 版本号 + 会话 jti** 鉴权）

```
公开：/api/posts /api/posts/:id /api/categories /api/tags /api/archive
      /api/links /api/projects /api/gallery /api/comments
      /api/auth/login /api/auth/totp /api/feed /api/sitemap.xml /api/about /api/uptime
      /api/posts/:id/like|favorite|share /api/posts/:id/engagement /api/subscribe
      /api/track /api/click /api/plugins/enabled /api/plugin-file/<id>/<path>（访问/热图/插件）
管理：/api/admin/stats /api/admin/posts... /api/admin/monitor/* /api/admin/security/*
      /api/admin/seo/* /api/admin/db/* /api/admin/plugins/* /api/admin/engagement/stats
      /api/admin/sessions* /api/admin/account/security-overview /api/admin/totp* ...
```

## 🚀 快速开始

> 环境要求：Go 1.27+ · Node.js 20+

```bash
# 1️⃣ 启动后端（首次自动建库 + 创建默认管理员 + 种子数据）
cd backend && go run .            # http://localhost:8080

# 2️⃣ 启动 PC 前端
cd frontend && npm install && npm run dev    # http://localhost:5173

# 3️⃣ 启动手机端（可选）
cd mobile && npm install && npm run dev      # http://localhost:5174
```

> 🔑 默认管理员：`admin / admin123`（登录后请立即在「账户设置」修改密码）

### 🗄️ 切换数据库

编辑 `backend/config/config.yaml`，基于 GORM 无需改动代码：

```yaml
database:
  driver: mysql   # sqlite | mysql | postgres
  dsn: root:password@tcp(127.0.0.1:3306)/blog?charset=utf8mb4&parseTime=True&loc=Local
```

> 也可在后台「数据管理」页面可视化切换 / 迁移 / 重启，切换后自动保存配置。

## 🌐 前台站点导航

| 导航 | 路由 | 说明 |
|---|---|---|
| 🏠 首页 | `/` | 最新文章 + 分类/标签筛选 |
| 📖 文章 | `/articles` | 技术文章 / 随笔记 / 生活圈 |
| 📄 文章详情 | `/post/:id` | Markdown 渲染 + 阅读进度条 + 点赞/收藏/分享 + 评论 |
| 🖼️ 图库 | `/gallery` | 分类图片墙 |
| 🔗 链接 | `/links` | 分类化友链 |
| 🗂️ 归档 | `/archive` | 年/月归档 + 热力图 |
| 🚀 项目合集 | `/projects` | 项目展示 + 在线演示 + README |
| 👤 关于我 | `/about` | 个人档案 + 介绍 |
| 🔍 搜索 | `/search` | 多关键词高亮搜索 |
| 📡 RSS | `/feed` | 订阅源 |

## 🛠️ 管理后台导航（`/admin`）

| 分组 | 页面 |
|---|---|
| 概览 | 仪表盘 `/admin/dashboard` |
| 内容 | 文章 `/admin/posts` · 分类 · 标签 · 链接 · 项目 · 图库 · 评论 |
| 数据 | 访问管理 `/admin/traffic` · 访问行为 · 系统监控 `/admin/monitor` · SEO · 资源管理 |
| 安全 | 安全设置 `/admin/security` · 数据管理 `/admin/db` |
| 账户 | 个人中心 `/admin/profile` · 账户设置 `/admin/account` |

## 🐳 Docker 部署

```bash
docker compose up -d --build
```

| 服务 | 地址 |
|---|---|
| PC 博客 | http://localhost:3000 |
| 手机端 | http://localhost:3001 |
| 后端 API | http://localhost:8080 |

数据（SQLite + 上传图片）通过 volume 持久化，重建容器不丢数据。

### 🖥️ 1Panel 面板部署

内置 **1Panel 面板编排**（MySQL + 后端 + PC 前端 + 手机端 四容器，配置全变量化）：

- 编排文件：`deploy/1panel/docker-compose.yml`
- 变量清单：`deploy/1panel/.env.example`
- 部署指南与容器信息：见 [`deploy/1panel/README.md`](deploy/1panel/README.md)

> 后端支持 `XU_` 前缀环境变量覆盖配置（端口/数据库/JWT/管理员等），容器化部署无需改代码。

### 🌐 HTTPS + 域名 + CDN

- **HTTPS 兼容已内置**：访客 cookie 自动加 `Secure`、真实 IP 信任反代 `X-Real-IP`、天气插件浏览器定位可用；部署步骤见 1Panel 指南「HTTPS + 域名部署」章节
- **CDN 接入**：静态资源 30 天缓存、图片 7 天缓存、gzip、CORS 头已就绪；接入指南见 [`deploy/cdn/README.md`](deploy/cdn/README.md)

## 🧪 测试与运维

```bash
cd backend && go test ./...      # 单元测试（内存 SQLite，覆盖全部核心模块）
./scripts/smoke.sh               # 端到端冒烟测试（核心接口全绿）
./scripts/backup.sh              # 数据备份（默认保留 7 份）
```

## 📜 贡献者

- 🧑‍💻 陈占旭 · <1542776628@qq.com>

<div align="center">

**Made with ❤️ by [陈占旭](https://gitee.com/chenzhanxu)**

</div>