post_waver

系统架构

版本: v1.0 最后更新: 2026-04-03 受众: 开发者、架构师 阅读时间: 15 分钟

📋 目录

概述
设计原则
系统架构
技术栈
数据流
包架构
扩展点

🎯 概述

PostWaver 是一个本地优先的内容管理系统，采用模块化 Monorepo 架构，支持将 Markdown 内容发布到多个平台。

核心目标

本地优先: 内容存储在本地 Markdown 文件中
多平台支持: 一键发布到多个平台（掘金、微信、CSDN、知乎、HTML）
格式转换: 自动转换为各平台兼容的格式
博客同步: 自动同步到 Hexo 博客
可扩展性: 易于添加新平台和功能

系统特点

✅ 模块化设计: 各包职责清晰，耦合度低
✅ 类型安全: 全面使用 TypeScript
✅ 可测试: 单元测试和集成测试
✅ 文档完善: 用户文档和开发者文档齐全
✅ 渐进式: 可以使用部分功能，无需全部

🎨 设计原则

1. 关注点分离（Separation of Concerns）

各包专注于单一职责：

core: 内容解析和处理
transformer: 平台格式转换
database: 数据持久化
engine: 工作流编排

2. 依赖倒置（Dependency Inversion）

高层模块不依赖低层模块，都依赖抽象：

各包通过接口通信
使用依赖注入
易于测试和替换

3. 单一数据源（Single Source of Truth）

Markdown 文件是内容的唯一来源
数据库仅存储元数据和状态
避免数据同步问题

4. 可扩展性（Extensibility）

插件化平台: 添加新平台无需修改核心代码
配置驱动: 通过配置文件控制行为
钩子系统: 在关键点提供扩展点

5. 本地优先（Local-First）

用户拥有数据完全控制权
可以离线工作
易于备份和迁移

🏗️ 系统架构

分层架构

┌─────────────────────────────────────────────────────────┐
│                     应用层 (Application)                  │
│  ┌──────────────┐           ┌──────────────┐            │
│  │   Web UI     │           │ Converter Web │            │
│  │  (React)     │           │   (React)     │            │
│  └──────────────┘           └──────────────┘            │
└─────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────┐
│                      引擎层 (Engine)                      │
│  ┌────────────────────────────────────────────────┐     │
│  │  Engine (Hono.js)                              │     │
│  │  - API 服务器                                   │     │
│  │  - 工作流编排                                   │     │
│  │  - 预览系统                                     │     │
│  └────────────────────────────────────────────────┘     │
└─────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────┐
│                      业务层 (Business)                     │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐              │
│  │  Core    │  │ Linker   │  │Transform │              │
│  │ 解析/扫描 │  │ 关系生成 │  │ 平台转换 │              │
│  └──────────┘  └──────────┘  └──────────┘              │
└─────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────┐
│                      数据层 (Data)                        │
│  ┌──────────┐           ┌──────────┐                    │
│  │ Database │           │  Config  │                    │
│  │(Prisma)  │           │ Manager  │                    │
│  └──────────┘           └──────────┘                    │
└─────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────┐
│                   存储层 (Storage)                        │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐              │
│  │  SQLite  │  │ Markdown │  │   Hexo   │              │
│  │ (元数据)  │  │ (内容)    │  │  (博客)  │              │
│  └──────────┘  └──────────┘  └──────────┘              │
└─────────────────────────────────────────────────────────┘

层次说明

1. 应用层（Application Layer）

职责: 用户界面和交互

组件:

Web UI: React 网页界面，提供内容管理、发布工作台
Converter Web: 独立的转换工具，提供在线转换功能

技术:

React 18
React Router
Vite

2. 引擎层（Engine Layer）

职责: 工作流编排和 API 服务

组件:

Engine Package: API 服务器（Hono.js）
- RESTful API
- 发布工作流
- 预览系统

技术:

Hono.js（轻量级 Web 框架）
Node.js

3. 业务层（Business Layer）

职责: 核心业务逻辑

组件:

Core Package: 内容解析和处理
- Markdown 解析（unified/remark）
- Frontmatter 生成
- 图片路径解析
- 链接注入
Linker Package: 内容关系生成
- 相关文章推荐
- 前后篇计算
- 标签匹配
Transformer Package: 平台格式转换
- Juejin 转换器
- WeChat 转换器
- CSDN 转换器
- Zhihu 转换器
- HTML 转换器
Adapter Package: 平台 API 适配器
- 平台 API 接口定义
- 各平台适配器实现

4. 数据层（Data Layer）

职责: 数据持久化和配置管理

组件:

Database Package: 数据库访问层
- Prisma ORM
- SQLite 数据库
- 数据访问对象（DAL）
Config Package: 配置管理
- 主题配置
- 图片上传配置
- Hexo 同步配置
- 平台 ID 管理

5. 存储层（Storage Layer）

职责: 底层存储

组件:

SQLite: 存储元数据、发布记录、平台映射
Markdown 文件: 存储实际内容
Hexo 博客: 博客生成和部署

🛠️ 技术栈

前端

技术	版本	用途
React	18.2.0	UI 框架
React Router	6.21.0	路由管理
Vite	5.0.11	构建工具
TypeScript	5.3.3	类型系统

后端

技术	版本	用途
Node.js	18+	运行时
Hono.js	Latest	Web 框架
Prisma	5.22.0	ORM
SQLite	3.x	数据库

内容处理

技术	版本	用途
unified	11.0.5	统一处理接口
remark	15.0.1	Markdown 解析
gray-matter	4.0.3	Frontmatter 解析
juice	-	CSS 内联化（WeChat）

开发工具

工具	版本	用途
pnpm	8+	包管理器
ESLint	Latest	代码检查
Prettier	Latest	代码格式化
Vitest	Latest	测试框架
TypeScript	5.3.3	类型检查

部署

工具	用途
GitHub Actions	CI/CD
GitHub Pages	Web UI 部署
Git	版本控制

🌊 数据流

内容发布流程

┌─────────────┐
│ 用户写作     │
│ Markdown    │
└──────┬──────┘
       ↓
┌─────────────┐
│ 扫描内容     │  ← core/scanner
│ 生成 frontmatter │
└──────┬──────┘
       ↓
┌─────────────┐
│ 解析内容     │  ← core/parser
│ 提取图片     │
└──────┬──────┘
       ↓
┌─────────────┐
│ 生成关系     │  ← linker
│ 相关文章     │
│ 前后篇       │
└──────┬──────┘
       ↓
┌─────────────┐
│ 存储元数据   │  ← database
│ SQLite DB   │
└──────┬──────┘
       ↓
┌─────────────┐
│ 平台转换     │  ← transformer
│ 格式适配     │
└──────┬──────┘
       ↓
┌─────────────┐
│ 上传图片     │  ← adapter
│ (如果需要)   │
└──────┬──────┘
       ↓
┌─────────────┐
│ 发布到平台   │  ← adapter/engine
│ 或同步博客   │
└─────────────┘

关键数据流

内容扫描

Markdown 文件 → Scanner → Frontmatter 生成 → 数据库存储

内容解析

Markdown → Parser → AST → 提取内容/图片

关系生成

数据库查询 → Linker → 关系计算 → 相关文章列表

平台转换

通用内容 → Transformer → 平台特定格式

Hexo 同步

转换后内容 → 模板注入 → Hexo 博客 → Git 提交

📦 包架构

包依赖关系

                    ┌─────────────┐
                    │   web-ui    │
                    │ converter-web│
                    └──────┬──────┘
                           │
                    ┌──────▼──────┐
                    │   engine    │
                    └──────┬──────┘
                           │
        ┌──────────────────┼──────────────────┐
        │                  │                  │
┌───────▼────────┐ ┌───────▼────────┐ ┌──────▼─────┐
│     core       │ │    linker      │ │transformer │
└───────┬────────┘ └───────┬────────┘ └──────┬─────┘
        │                  │                  │
        └──────────────────┼──────────────────┘
                           │
                    ┌──────▼──────┐
                    │   config    │
                    └──────┬──────┘
                           │
                    ┌──────▼──────┐
                    │  database   │
                    └─────────────┘

包职责

包	职责	主要依赖
core	内容解析、扫描、注入	database, linker
linker	内容关系生成	database
transformer	平台格式转换	无
adapter	平台 API 适配	无
database	数据持久化	无
config	配置管理	无
engine	工作流编排、API	core, transformer, adapter, database, config
web-ui	React 界面	engine
converter-web	独立转换工具	transformer

🔌 扩展点

1. 添加新平台

步骤:

在 transformer/src/ 中创建新转换器
实现 Transformer 接口
在 adapter/src/ 中实现平台 API（如需要）
更新配置文件

示例:

// transformer/src/to-newplatform.ts
export function transformToNewPlatform(content: string): string {
  // 实现转换逻辑
}

2. 添加新的内容注入器

步骤:

在 core/src/ 中创建新的注入器
实现 Injector 接口
在扫描流程中调用

示例:

// core/src/custom-injector.ts
export function injectCustom(content: string, data: any): string {
  // 实现注入逻辑
}

3. 添加新的数据库模型

步骤:

在 database/prisma/schema.prisma 中定义模型
运行 prisma migrate
在 database/src/dal/ 中创建 DAL 方法

4. 添加新的 API 端点

步骤:

在 engine/src/ 中添加路由
实现处理函数
添加类型定义

📚 相关文档

🤝 贡献

想要贡献代码？请阅读贡献指南。

最后更新: 2026-04-03 维护者: PostWaver Team 反馈: GitHub Issues

This site is open source. Improve this page.