MDBlog

✨ 核心特性

📸 界面预览

首页展示

文章详情

🚀 快速开始

环境要求

本地开发

# 1. 克隆项目
git clone https://github.com/broqiang/mdblog.git
cd mdblog
# 2. 安装依赖
go mod tidy
# 3. 本地运行
make dev
# 或者
go run main.go
# 4. 访问应用
# http://localhost:8091

创建文章

---
title: "文章标题"
author: "BroQiang"
github_url: "https://github.com/broqiang/mdblog"
created_at: "2024年01月01日T10:00:00Z"
updated_at: "2024年01月15日T15:30:00Z"
description: "文章描述"
---
# 文章内容
这里是文章的具体内容...

📁 项目结构

mdblog/
├── main.go # 主程序入口
├── embed.go # 静态资源嵌入
├── go.mod # Go 依赖管理
├── go.sum # Go 依赖校验
├── Makefile # 构建脚本
├── posts/ # Markdown 文章目录
├── internal/ # 内部模块
│ ├── config/ # 配置管理
│ ├── data/ # 数据管理和缓存
│ ├── markdown/ # Markdown 解析器
│ ├── server/ # Web 服务器
│ └── assets/ # 内部静态资源
├── web/ # 前端资源
│ ├── static/ # 静态文件(CSS/JS/图片等)
│ └── templates/ # HTML 模板
├── cmd/ # 命令行工具
├── deploy/ # 部署配置
└── docs/ # 文档

📝 文章格式说明

Front Matter 字段

---
title: "文章标题" # 必填
author: "作者名" # 可选,默认 "BroQiang"
github_url: "GitHub链接" # 可选
created_at: "2024年01月01日T10:00:00Z" # 可选
updated_at: "2024年01月01日T12:00:00Z" # 可选
description: "文章描述" # 可选
---

分类规则

支持的 Markdown 语法

🛠️ 生产部署

1. 创建用户和目录

# 创建专用用户(/bro 为家目录,可根据实际情况修改)
sudo useradd -m -d /bro -s /bin/bash bro
sudo mkdir -p /bro/mdblog/{posts,logs}
sudo chown -R bro:bro /bro/mdblog

2. 安装 systemd 服务

# 上传服务配置文件
scp deploy/mdblog.service user@server:/tmp/
# 安装服务
sudo cp /tmp/mdblog.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable mdblog

3. 配置文章仓库

# 用 bro 用户克隆文章仓库
sudo -u bro git clone git@gitee.com:your-username/posts.git /bro/mdblog/posts
# 确保目录权限
sudo chown -R bro:bro /bro/mdblog/posts

4. 部署应用

SERVER_HOST=your-server-ip
SERVER_USER=root
SERVER_PATH=/bro/mdblog
SSH_PORT=22
APP_PORT=8091

# 编译并部署
make build
make scp

🔄 Webhook 自动同步

配置 SSH 密钥

# 在服务器上生成密钥
sudo -u bro ssh-keygen -t rsa -b 4096 -C "bro@your-server"
# 查看公钥并添加到 Gitee
sudo -u bro cat /bro/.ssh/id_rsa.pub

配置 Gitee Webhook

const (
 WebhookSecret = "your-webhook-secret"
 WebhookBranch = "main"
 WebhookDevMode = false // 生产环境设为 false
)

make scp

测试 Webhook

# 本地测试推送
cd posts
echo "# 测试文章" > test.md
git add . && git commit -m "测试" && git push origin main
# 检查同步状态
curl https://your-domain.com/health
sudo tail -f /bro/mdblog/logs/mdblog.log | grep -i webhook

📊 服务管理

常用命令

# 服务控制
sudo systemctl start mdblog # 启动
sudo systemctl stop mdblog # 停止
sudo systemctl restart mdblog # 重启
sudo systemctl status mdblog # 状态
# 日志查看
sudo tail -f /bro/mdblog/logs/mdblog.log # 应用日志
sudo journalctl -u mdblog -f # 系统日志
# 健康检查
curl http://localhost:8091/health
netstat -tlnp | grep 8091

日志轮转

/bro/mdblog/logs/*.log {
 daily
 missingok
 rotate 30
 compress
 delaycompress
 notifempty
 sharedscripts
 postrotate
 systemctl reload mdblog
 endscript
}

性能监控

# 资源使用
ps aux | grep mdblog
du -sh /bro/mdblog/
# 文章统计
find /bro/mdblog/posts -name "*.md" | wc -l

🚨 故障排查

服务启动问题

# 检查服务状态
sudo systemctl status mdblog
sudo journalctl -u mdblog --no-pager
# 检查端口占用
sudo netstat -tlnp | grep 8091

Webhook 同步问题

# 检查 Git 配置
cd /bro/mdblog/posts
sudo -u bro git status
sudo -u bro git remote -v
# 测试 SSH 连接
sudo -u bro ssh -T git@gitee.com
# 检查文件权限
ls -la /bro/mdblog/posts/

权限问题解决

# 重置权限
sudo chown -R bro:bro /bro/mdblog
sudo chmod 755 /bro/mdblog
sudo chmod 755 /bro/mdblog/posts/
sudo chmod 644 /bro/mdblog/posts/*.md

🔧 配置选项

命令行参数

# 默认配置
./mdblog
# 自定义 posts 目录
./mdblog -posts /path/to/posts

应用配置

const (
 DefaultPort = 8091
 DefaultHost = "0.0.0.0"
 SummaryLines = 3
 PageSize = 10
 WebhookSecret = "secret"
 WebhookBranch = "main"
 WebhookDevMode = false
)

📡 API 接口

文章接口

GET /api/posts?page=1&size=10 # 获取文章列表
GET /api/posts/{id} # 获取单篇文章
GET /api/categories # 获取分类列表
GET /api/search?q=关键词&page=1&size=10 # 搜索文章

系统接口

GET /health # 健康检查
POST /webhook/gitee # Gitee Webhook

🎨 功能特性

搜索功能

响应式设计

🔒 安全建议

📄 许可证

🔗 相关链接