← 返回

Rosydawn：一个极简但是完整的 Astro 博客框架

#Astro

介绍 Rosydawn 博客框架的架构设计、核心特性与自动化部署能力，包括基于 Cron 的 Git 自动部署和 HTTPS 证书管理。

这是 Rosydawn 博客框架的介绍文档。 一句话概括 Rosydawn： 一个基于 Astro 进行构建，完全由 AI 设计和开发实现的博客框架，集成了一键部署、自动化部署、https 集成等等能力。

核心特性

特性描述
静态生成基于 Astro SSG，无需服务器
内容管理使用 Astro Content Collections 管理博客文章，能够通过文件夹的方式组织和管理内容
Markdown/MDX支持标准 Markdown 和 MDX 扩展语法
代码高亮集成 Shiki（使用 one-light 主题）
图表支持集成 PlantUML、Drawio 绘图能力
响应式设计移动端友好，自适应布局
自动部署基于 Cron 的 Git 监控与自动构建
HTTPSLet’s Encrypt 证书自动申请与续期

技术栈

框架: Astro 5.17.x
语言: TypeScript
样式: Scoped CSS (无预处理器)
代码高亮: Shiki (内置于 Astro)
图表: astro-plantuml
部署: Nginx + Let's Encrypt (自动化脚本)

目录结构

rosydawn/
├── public/                     # 静态资源
│   ├── favicon.ico
│   └── favicon.svg
│
├── src/
│   ├── content/                # 内容目录
│   │   └── posts/              # 博客文章
│   │       └── {year}/{month}/{slug}/
│   │           ├── index.md    # 文章内容
│   │           ├── cover.jpg   # 封面图片 (可选)
│   │           └── assets/     # 文章资源 (可选)
│   │
│   ├── layouts/
│   │   └── Layout.astro        # 全局布局组件
│   │
│   ├── pages/                  # 页面路由
│   │   ├── index.astro         # 首页
│   │   ├── about.astro         # 关于页面
│   │   ├── blog/               # 博客相关
│   │   └── tags/               # 标签相关
│   │
│   └── content.config.ts       # 内容集合配置
│
├── scripts/
│   ├── deploy.mjs              # 部署脚本入口
│   └── lib/                    # 部署脚本模块
│
├── logs/                       # 日志目录
└── README.md                   # 项目文档

文章编写规范

文件结构

每篇文章存放在独立目录中，按年月组织：

src/content/posts/2026/02/my-article/
├── index.md          # 文章内容
├── cover.jpg         # 封面图（可选）
└── assets/           # 文章资源目录（可选）
    ├── diagram.png
    └── screenshot.jpg

Frontmatter 格式

---
title: "文章标题"
date: 2026-02-08
description: "一句话描述，会显示在列表页"
tags: ["标签1", "标签2"]
coverImage: ./cover.jpg  # 可选
---

图表内嵌

PlantUML内嵌：

语法如下，指定代码块的语言为 plantuml，并使用 @startuml 和 @enduml 标记代码块。

PlantUML Diagram

Drawio内嵌：

Drawio 是通过 svg 内嵌实现的，如果你要使用 drawio，需要按照下列步骤进行：

1、文档需要指定格式为 MDX，即文件命名为xxx.mdx

2、在本地将 drawio 导出为 svg 格式，并将 svg 文件命名为 xxx.drawio.svg

3、在文档中使用 ?raw 内嵌 svg：

import deploySvg from './assets/deploy-flow.svg?raw';

<div class="drawio-container" set:html={deploySvg} />
Astro 博客自动化部署流程
Astro 博客自动化部署流程
System Cron
定时任务 (每 N 分钟触发)
System Cron...
Git 状态检查
Hash 是否变化?
Git 状态检查...
自动拉取
git pull origin main
自动拉取 git pull origin main
构建部署
pnpm build & Nginx reload
构建部署 pnpm build & Nginx reload
邮件通知 (待实现)
推送部署报告
邮件通知 (待实现)...
保持现状
(无更新)
保持现状 (无更新)有差异一致Text is not SVG - cannot display

部署系统

Rosydawn 提供了完整的自动化部署能力，基于 Node.js 实现。

基础命令

# 一键构建部署（HTTP）
npm run deploy

# 启用 HTTPS
# 更改配置文件中的 `SSL_EMAIL` 变量，并运行以下命令即可完成 SSL 配置
npm run deploy:ssl

# 查看部署状态
npm run deploy:status

自动部署 (Cron)

脚本支持基于系统 Cron 的自动部署，定时检查 Git 仓库更新并自动构建部署：

# 安装 Cron 任务
# 定时任务配置在 scripts/deploy.mjs 文件中
npm run deploy:cron:install

# 查看状态
npm run deploy:cron:status

# 查看实时日志
tail -f logs/deploy.log

工作原理

  1. Cron 定时触发 - 系统 Cron 每 N 分钟调用脚本
  2. Git 检查 - 比较本地和远程 commit hash
  3. 自动拉取 - 检测到更新后执行 git pull
  4. 构建部署 - 自动执行构建和部署流程
  5. 邮件通知 - 部署完成后发送邮件通知（待实现）

Cron 环境兼容性

脚本针对 Cron 的特殊环境做了以下适配：

问题解决方案
PATH 环境变量精简脚本启动时自动将当前 Node.js 的 bin 目录添加到 PATH
USER 环境变量缺失使用 id -un 系统命令获取用户名
SSH Agent 不可用自动检测 SSH key 并通过 GIT_SSH_COMMAND 注入
日志目录不存在写入日志前自动创建 logs/ 目录

SSL 证书管理

# 首次安装证书
# 更改配置文件中的 `SSL_EMAIL` 变量， 用于接收 Let-Encrypt 的信息，运行以下命令即可完成 SSL 配置
npm run deploy:ssl
# 手动续期
npm run deploy:renew

# 查看证书状态
npm run deploy:status

Let’s Encrypt 证书有效期为 90 天，Certbot 会自动设置续期任务。

性能优化

前端优化

优化项实现方式效果
零字体请求使用系统原生字体栈首屏渲染无阻塞
单一 Favicon仅使用 SVG 格式减少网络请求
静态生成Astro SSG 预渲染无服务端渲染开销

Nginx 服务端优化

部署脚本自动配置以下性能优化：

# 零拷贝传输
sendfile on;
tcp_nopush on;
tcp_nodelay on;

# Gzip 压缩
gzip on;
gzip_comp_level 5;
gzip_types text/plain text/css application/json application/javascript;

# 静态资源长期缓存
location ~* \.(css|js|woff2)$ {
    expires 1y;
    add_header Cache-Control "public, immutable";
}

代码块增强

文章详情页对代码块做了以下增强：

  1. 语言标签显示 - 代码块右上角显示语言名称
  2. 行号显示 - 等宽对齐的行号
  3. 复制按钮 - 一键复制代码内容
  4. 展开/收起 - 超过 15 行时自动折叠
  5. 滚动位置补偿 - 防止展开/收起时页面跳动
// 展开/收起时的滚动补偿
const rectBefore = wrapper.getBoundingClientRect();
const topBefore = rectBefore.top;

wrapper.classList.toggle('collapsed');

const rectAfter = wrapper.getBoundingClientRect();
const scrollDiff = rectAfter.top - topBefore;
if (scrollDiff !== 0) {
  window.scrollBy(0, scrollDiff);
}

开发注意事项

重要❗：开发前把这段提示词发给你的大模型工具：

这是 rosydawn 个人博客项目。

## 开始前
请阅读 README.md，其中包含：
- 项目架构与技术栈（Astro 5 + TypeScript + Tailwind）
- 开发规范与代码风格
- 部署流程（Git 驱动 + Cron 监控）
- AI 协作专属指南

## 限制
- 不要读取 src/content/**/*.md 文件（博客文章）
- 不要读取 public/images/ 下的资源文件

## 关注范围
- src/components/ - 组件开发
- src/layouts/ - 布局模板
- src/pages/ - 页面路由
- scripts/lib/ - 部署脚本
- astro.config.mjs - 构建配置

快速开始

# fork 本项目并 克隆项目到本地
cd rosydawn

# 安装依赖
npm install

# 开发模式
npm run dev

# 服务端部署
npm run deploy

# 查看部署帮助信息
npm run deploy:help

Rosydawn 是一个专注于内容展示的博客框架，通过极简设计和自动化部署，让创作者专注于写作本身。