1.1 项目背景#

当前 Firefly 主题博客系统采用 SSG（静态站点生成）模式，文章内容在构建时生成静态 HTML 文件。Django 作为后端博客管理系统，通过以下方式与 Firefly 集成：

• Django Admin 管理文章
• 同步脚本将 Django 文章生成 Markdown 文件到 Firefly
• Firefly 构建时读取本地 Markdown 文件生成静态页面

1.2 存在的问题#

开发模式下使用 pnpm dev（热加载），文章更新可以实时同步。但上线后存在以下问题：

1. 更新延迟：修改文章后需要重新 build 才能生效
2. 部署复杂：需要手动 trigger 或配置 Webhook 自动部署
3. 用户体验：无法实现真正的”即改即见”

1.3 目标#

实现 Firefly 的 SSR（服务器端渲染）模式，使得：

• 文章更新无需重新 build
• 用户访问时实时获取最新内容
• 保留静态博客的高性能优势（可选 hybrid 模式）

2.1 当前技术栈#

2.2 当前数据流#

1
Django Admin 保存文章
2
    ↓
3
同步脚本生成 django-{id}.md
4
    ↓
5
Astro 构建时读取 Markdown
6
    ↓
7
生成静态 HTML
8
    ↓
9
用户访问静态页面

3.1 SSG vs SSR vs Hybrid#

3.2 推荐方案：Hybrid 模式#

推荐使用 output: 'hybrid' 模式，理由：

1. 保留静态性能：大部分页面（如首页、关于页、友链）保持静态
2. 动态文章内容：文章页面实时从 API 获取
3. 平滑过渡：可以逐步迁移，无需完全重构

4.1 环境准备#

1
# 进入 Firefly 目录
2
cd /home/bahua/blog/Firefly
3

4
# 安装 SSR 适配器
5
pnpm add @astrojs/node

4.2 配置 Astro#

修改 astro.config.mjs：

1
import { defineConfig } from 'astro/config';
2
import node from '@astrojs/node';
3

4
export default defineConfig({
5
  output: 'hybrid',
6
  adapter: node({
7
    mode: 'standalone'
8
  }),
9
});

4.3 修改文章页面逻辑#

文件：src/pages/posts/[...slug].astro

需要修改的部分：

1. 移除 getStaticPaths - SSR 模式下不再需要在构建时生成所有路径
2. 动态获取文章数据 - 根据 slug 判断来源，从本地文件或 Django API 获取

4.4 运行 SSR 模式#

1
# 开发模式（推荐）
2
pnpm dev
3

4
# 或构建后运行
5
pnpm build
6
node dist/server/entry.mjs

5.1 本地部署#

1
cd /home/bahua/blog/Firefly
2
pnpm dev

服务运行在 http://localhost:4321

5.2 服务器部署#

1
# 构建
2
pnpm build
3

4
# 运行 SSR 服务器
5
node dist/server/entry.mjs

可以使用 PM2 管理进程：

1
pm2 start dist/server/entry.mjs --name firefly

实施方案#

1. 安装依赖：pnpm add @astrojs/node
2. 修改配置：astro.config.mjs 设置为 hybrid 模式
3. 调整代码：修改 [...slug].astro 动态获取文章
4. 测试验证：确保本地运行正常
5. 部署上线：选择合适的部署方式

预期效果#

• ✅ Django Admin 修改文章后，Firefly 立即可见
• ✅ 无需手动 rebuild 或 Webhook 触发
• ✅ 保留静态页面性能优势（Hybrid 模式）
• ✅ 开发体验与上线后一致

报告生成时间：2026-03-09
作者：bahua