MCCSJS 博客系统使用指南

简介

欢迎使用 MCCSJS 博客系统！这是一个基于 Go + Vue 3 开发的现代化全功能博客平台，采用前后端分离架构，支持 SSR 服务端渲染、PWA 渐进式 Web 应用、AI 摘要生成等特性。

技术栈

层级 技术
后端 Go 1.25 + Gin + GORM + PostgreSQL
前台 Nuxt 4.3 + Vue 3 + TypeScript + SSR
管理后台 Vue 3 + Vite 7 + Element Plus + CodeMirror 6
认证 JWT + OAuth 2.0（GitHub / Google / QQ / Microsoft / OIDC / 微信）
存储 本地文件系统 / S3 兼容对象存储（COS / OSS / Kodo / MinIO）
通知 站内消息 + 邮件 SMTP + 飞书机器人
AI OpenAI 兼容接口（文章摘要 / 标题建议）
部署 Docker 多阶段构建

核心功能

✅ 内容管理

  • 文章管理：Markdown 编辑器，支持 KaTeX 数学公式、Mermaid 图表、代码高亮、任务列表
  • AI 摘要：自动生成文章摘要和标题建议
  • 分类和标签：基于 slug 的 URL，支持多级分类
  • 动态发布：类朋友圈的动态功能，支持文字、图片、视频、音频、音乐、链接
  • 番剧推荐：动漫/番剧推荐展示
  • 自定义菜单：聚合菜单、顶部导航、页脚菜单三级结构

✅ 用户系统

  • 邮箱密码注册/登录
  • 6 种 OAuth 第三方登录（GitHub、Google、QQ、Microsoft、OIDC、微信小程序）
  • 多种登录方式绑定/解绑
  • 用户徽章（自定义标签）
  • 个人资料管理与头像上传
  • 账号注销
  • 四级角色权限控制（super_admin / admin / user / guest）

✅ 评论系统

  • 多目标评论（文章、页面、动态）
  • 楼中楼回复（父级/根级/平铺结构）
  • 表情选择器（自定义表情包）
  • 管理员置顶与状态切换
  • IP / 地区 / 浏览器 / 操作系统追踪
  • 从 Artalk 导入评论

✅ 社区功能

  • 友链管理：分组展示、截图预览、头像、可用性状态检测、延迟监控
  • 朋友圈：聚合友链博客的 RSS 订阅源
  • 友链申请：前台申请 + 后台审核
  • RSS 订阅：RSS 2.0 + Atom 输出，每日推送新文章给邮件订阅者

✅ 通知系统

  • 站内通知中心（已读/未读状态）
  • 邮件通知（SMTP，带 HTML 模板）
  • 飞书机器人通知（交互式卡片）
  • 邮件订阅系统（支持退订令牌）

✅ 数据分析

  • 访问追踪（PV / UV、页面停留时长、文章级追踪）
  • 数据仪表盘（ECharts 图表、词云）
  • 流量趋势、分类/标签统计
  • 贡献热力图
  • 公开统计页面

✅ SEO 与 PWA

  • 服务端渲染（SSR）
  • 动态 Sitemap 生成
  • RSS 2.0 和 Atom 订阅源
  • Schema.org 结构化数据
  • Open Graph 和 Twitter Cards
  • PWA 支持（安装提示、自动更新）
  • Robots.txt 配置

✅ 存储

  • 本地文件系统或 S3 兼容对象存储（S3、COS、OSS、Kodo、MinIO）
  • 文件使用追踪与未使用文件自动清理

✅ 自定义

  • 暗色/亮色主题自动切换（基于时间或系统偏好）
  • 自定义字体、Favicon、背景图片
  • 自定义 head / body 代码注入
  • 可配置的关于页面（个性、座右铭、社交链接、版本信息）
  • 打赏方式配置
  • 微信公众号二维码集成

✅ 安全

  • JWT 认证 + 令牌黑名单
  • IP 限流（500 请求/分钟）
  • RBAC 角色权限中间件
  • CORS 跨域配置
  • 密码加密（bcrypt）
  • 邮箱验证码（带过期和失败次数追踪）

快速开始

1. 环境要求

依赖 版本要求
Go >= 1.25
Node.js >= 22
PostgreSQL >= 15
pnpm 推荐

2. 配置环境变量

项目根目录和各子目录都有 .env 文件，复制 .env.example 并填写：

根目录 .env

ENV
DB_PASSWORD=your_db_password
JWT_SECRET=your_jwt_secret
API_URL=http://localhost:8080/api/v1

server/.env

ENV
SERVER_PORT=8080
SERVER_ALLOW_ORIGINS=*
DB_HOST=localhost
DB_PORT=5432
DB_NAME=mccsjs
DB_USER=postgres
DB_PASSWORD=your_db_password
JWT_SECRET=your_jwt_secret

blog/.env

ENV
API_URL=http://localhost:8080/api/v1

admin/.env

ENV
VITE_API_URL=http://localhost:8080/api/v1

3. 启动后端

BASH
cd server
go run cmd/main.go

后端启动后会自动执行数据库迁移，首次启动会初始化所有表结构。

4. 启动前台博客

BASH
cd blog
pnpm install
pnpm dev

默认运行在 http://localhost:3000。

5. 启动管理后台

BASH
cd admin
pnpm install
pnpm dev

默认运行在 http://localhost:4000。

默认管理员账号

字段 值
邮箱 admin@example.com
密码 123456

⚠️ 重要：请在首次登录后立即修改密码！

管理后台功能

仪表盘

登录后首页为数据仪表盘，展示：

  • 文章数、评论数、浏览量、访客数等核心指标
  • 流量趋势折线图
  • 分类/标签词云
  • 贡献热力图

内容管理

模块 功能
文章管理 创建/编辑/删除文章，Markdown 编辑器带实时预览，支持封面制作、分类标签管理、AI 摘要生成
评论管理 查看/审核/置顶/删除评论，支持从 Artalk 导入
动态管理 发布/编辑/删除动态
友链管理 管理友链和友链分组，审核友链申请
番剧管理 管理动漫推荐
文件管理 上传/删除文件，查看文件使用状态
菜单管理 配置聚合菜单、顶部导航、页脚菜单
反馈管理 查看/回复用户反馈
RSS 管理 管理 RSS 订阅源，刷新/标记已读

用户管理

  • 用户列表查看
  • 角色分配（super_admin / admin / user / guest）
  • 用户状态管理

系统设置

系统设置分为 7 个标签页：

1. 基础设置

  • 作者信息（姓名、邮箱、简介、头像、照片）
  • ICP 备案号、公安备案
  • 管理后台 URL、博客 URL、首页 URL

2. 博客设置

  • 站点标题、副标题、标语、描述、关键词
  • 建站日期、Favicon、背景图片（桌面端 + 移动端）
  • 站点截图、公告内容
  • 打字机效果文字
  • 微信公众号二维码/名称
  • 侧边栏社交链接
  • 页脚社交链接/友情链接
  • 主题自动切换时间
  • 首页布局（瀑布流/单列）
  • 动态页分页大小
  • 关于页面内容（简介、个性 MBTI、座右铭、社交、创作平台、版本、联合、故事）
  • 自定义 head / body 代码
  • 表情配置、字体配置
  • Meting API、Cravatar URL、IP API URL、封面制作 API
  • 打赏方式

3. 通知设置

  • SMTP 邮件配置（主机、端口、加密方式、用户名、发件人、密码）
  • 飞书机器人配置（App ID、Secret、Chat ID）

4. 上传设置

  • 存储类型（本地 / S3 / COS / OSS / Kodo / MinIO）
  • 最大文件大小、路径模式
  • S3 凭证、区域、存储桶、端点、域名、SSL 开关

5. AI 设置

  • OpenAI 兼容 Base URL、API Key、模型
  • 摘要 / AI 摘要 / 标题生成的提示词
  • MCP 密钥

6. OAuth 设置

  • GitHub、Google、QQ、Microsoft、OIDC、微信小程序
  • 每个平台：启用开关、Client ID / Secret、回调地址
  • Worker 代理 URL

7. 导入/导出

  • 数据导入/导出功能

系统信息

  • 查看系统静态/动态信息
  • 版本更新检测

定时任务

系统内置以下定时任务，自动运行：

时间 任务
每天 02:00 清理过期邮箱验证码
每天 03:00 清理未使用的文件
每天 04:00 清理过期 JWT 令牌黑名单
每小时 刷新所有 RSS 订阅源
每天 05:00 清理孤立的 RSS 文章
每天 09:00 向邮件订阅者推送每日新文章
每天 00:00 友链可用性检测

前台页面说明

路径 页面 说明
/ 首页 文章列表，支持瀑布流/单列布局，置顶/精选标记
/posts/:slug 文章详情 AI 摘要、过时提醒、正文、版权信息、标签、上下篇导航、评论
/archive 归档 按年月归档的文章
/categories 分类 分类列表
/category/:slug 分类详情 某分类下的文章
/tags 标签 标签云/列表
/tag/:slug 标签详情 某标签下的文章
/moment 动态 朋友圈式动态流（文字、图片画廊、视频、音频、音乐播放器）
/link 友链 友链卡片分组展示，可用性状态，友链申请表单
/fc 朋友圈 聚合友链博客的 RSS 文章
/about 关于 作者信息、联系方式、站点统计、版本、MBTI 性格卡、番剧推荐
/feedback 反馈 反馈/投诉提交表单，工单追踪
/subscribe 订阅 三种订阅方式：微信公众号、邮件、RSS
/comments 评论 全局评论列表
/statistics 统计 公开统计数据：字数、浏览量、访客、文章、分类、标签、动态、友链、评论
/profile 个人资料 编辑信息、徽章、密码、OAuth 绑定/解绑、账号注销
/notifications 通知 通知中心，已读/未读状态
/search 搜索 全文搜索（通过搜索弹窗触发）
/cookies Cookies Cookie / 本地存储说明
/copyright 版权 CC BY-NC-ND 4.0 协议
/privacy 隐私 隐私政策

Docker 部署

每个组件都有独立的 Dockerfile：

后端

BASH
cd server
docker build -t mccsjs-server .
docker run -p 8080:8080 --env-file .env mccsjs-server

前台博客

BASH
cd blog
docker build -t mccsjs-blog .
docker run -p 3000:3000 mccsjs-blog

管理后台

BASH
cd admin
docker build -t mccsjs-admin .
docker run -p 4000:80 mccsjs-admin

API 文档

后端启动后访问 Swagger 文档：

TEXT
http://localhost:8080/swagger/index.html

MCP（Model Context Protocol）

系统内置 MCP 服务端点，AI 工具可通过 /mcp 接口访问博客数据：

  • 文章管理
  • 评论管理
  • 友链管理
  • 动态管理
  • RSS 订阅
  • 统计数据
  • 分类/标签
  • 用户管理

在 AI 设置中配置 MCP 密钥即可启用。

使用建议

  1. 首次登录后立即修改默认密码
  2. 完善个人资料：设置作者信息、头像、简介
  3. 创建分类和标签：先建立内容分类体系
  4. 配置通知：设置 SMTP 邮箱，开启飞书机器人，及时收到评论和反馈通知
  5. 配置 OAuth：启用第三方登录，降低用户注册门槛
  6. 配置存储：生产环境建议使用 S3 兼容对象存储
  7. 配置 AI：接入 OpenAI 兼容接口，开启文章自动摘要
  8. 开启 PWA：让用户可以将博客安装到桌面
  9. 定期检查友链：系统会自动检测友链可用性

技术亮点

数据库优化

  • CHECK 约束保证数据完整性
  • 外键级联操作
  • 部分索引减少存储空间
  • 复合索引优化查询性能
  • PostgreSQL GIN 索引加速全文搜索

前端优化

  • SSR 服务端渲染，首屏加载更快
  • PWA 支持，离线可用
  • 代码分割（vue-core、vue-router、dayjs、markdown-renderer、katex、highlight 等独立 chunk）
  • 图片懒加载与响应式处理
  • 关键 CSS 内联（@nuxtjs/critters）
  • 平滑滚动（Lenis）

安全设计

  • JWT + 令牌黑名单机制
  • RBAC 四级角色权限
  • IP 限流防护
  • 密码 bcrypt 加密
  • CORS 跨域配置
  • 邮箱验证码防刷

许可证

本项目基于 MIT License 开源。

祝您使用愉快！🎉

MCCSJS 博客系统使用指南
https://blog.seln.cn/posts/a7k9m2x5
作者mccsjs
发布时间2026-06-07
更新时间2026-06-11
许可协议 CC BY-NC-SA 4.0
Go语言PostgreSQL

评论