serenade

KO | EN

gitlite — search

#javascript #python #hacktoberfest #llm #golang #android #linux #nodejs #windows #awesome #awesome-list #vue #pytorch #ios

(★ 11)

Serenade - 动静结合的Nuxt4博客+AI写作助手

serenade 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Serenade · 动静结合的 Markdown 博客与 AI 写作助手

Serenade 是一个基于 Nuxt 的博客 / 知识库 / 朋友圈系统：内容用 Markdown（与少量 JSON）保存，页面可以静态导出，也可以用 Node 运行；同时也提供一套可选的 AI 写作脚手架，用来生成 URL slug 与封面图。

## 动静结合：把「内容」与「发布」分开

很多争论其实都混在一起：要不要服务器、要不要数据库、要不要反复编译。

Serenade 的选择很明确：

- **静**：内容永远是文件（`content/`），不依赖数据库
- **动**：在 Node 运行时读取这些文件，SSR 渲染页面，并提供搜索、RSS 等能力
- **合**：同一套内容结构，既能 `build` 跑服务，也能 `generate` 导出静态

## 两种部署方式

| 你在乎的事 | 静态导出（`nuxt generate`） | Node 运行（`nuxt build`） |
| ---------- | --------------------------- | ------------------------- |
| 服务器     | 不需要（静态托管即可）      | 需要（Node 进程）         |
| 数据库     | 不需要                      | 不需要                    |
| 内容更新   | 重新 generate               | 同步 `content/` 即可      |
| 运行时能力 | 受限                        | 完整                      |
| 适合场景   | 低维护、纯静态              | 频繁更新、需要动态能力    |

你可以把它理解成一句宣传语：

> 内容是静的，发布是自由的。

## 可以主打的亮点

- **构建一次，内容常新（Node 模式）**：文章/友链/项目更新只需要同步 `content/`
- **0 数据库**：Markdown 天然适合 Git 管理，迁移与备份都轻
- **博客 + 知识库 + 朋友圈**：文章、VuePress 风格专栏、友链与 RSS 订阅聚合、项目展示
- **AI 写作脚手架（可选）**：生成 URL slug、生成文章封面，把重复劳动交给机器
- **同构体验**：既可静态托管，也可 SSR 运行

## 功能概览

- 文章系统：`content/posts/<slug>/README.md`
- 专栏/知识库：`content/columns/<slug>/`
- 标签聚合：从 front-matter 统计
- 全文搜索：服务端搜索 API
- 友链 / 朋友圈：`content/friends.json` + RSS 拉取
- 项目展示：`content/projects.json`
- 数学公式：KaTeX
- UI：TailwindCSS、暗黑模式、响应式布局

## 快速开始

```bash
pnpm install
pnpm dev
```

访问：`http://localhost:3000`

## 部署

### 1) Docker 部署（推荐）

#### 方式 A：官方镜像（推荐）

每次 push 到 main 分支会自动构建并推送镜像到 GHCR。

```bash
# 创建 content 目录并放入你的内容
mkdir -p content

# 启动
docker compose up -d
```

更新镜像：

```bash
docker compose pull && docker compose up -d
```

- 默认监听 `3000`，可用 `SERENADE_PORT=8080 docker compose up -d` 映射到其它端口
- `docker-compose.yml` 把宿主机 `./content` 挂载进容器，内容更新后刷新即可生效
- 站点信息通过 `.env` 中的 `SITE_*` 环境变量配置，不再把个人站点配置写死到预构建镜像

#### 方式 B：本地构建镜像

如果你 fork 了项目或做了自定义修改，可以本地构建：

```bash
docker build -t serenade:local .
docker run -d -p 3000:3000 -v ./content:/app/content --name serenade serenade:local
```

#### 方式 C：裸机（不使用 Docker）

```bash
pnpm build
# 上传 .output/ 与 content/ 到服务器
node .output/server/index.mjs
```

后续更新内容：只同步 `content/`，无需重新 `build`。

项目内置 `npm run sync`（Windows 使用 `scp`，Linux/Mac 使用 `rsync`）同步 `content/`。

### 2) 静态导出（推荐：0 服务器）

```bash
pnpm generate
# 部署 .output/public 到任意静态托管
```

本地静态调试：

```bash
py -m http.server 4173 --directory .output/public
```

访问：`http://localhost:4173/feed`

- 更新内容需要重新 `generate`（可交给 CI 自动化）

## 内容结构

```
content/
  posts/
    <post-slug>/
      README.md
      cover.png (可选)
  columns/
    <column-slug>/
      README.md
      <chapter>.md
  friends.json
  projects.json
```

## 脚本工具

- `npm run new:post`：创建文章（可选 AI 生成 URL / 配图）
- `npm run new:column`：创建专栏
- `npm run sync`：同步到服务器（支持同步 `content/`、`.output/`、指定文章/专栏）

AI 与同步相关配置见 `.env.example`：

- 生成 URL slug：配置 `OPENAI_API_KEY`
- 生成封面图：配置 `IMAGE_API_KEY`

## 站点配置

站点信息通过 `.env` 中的 `SITE_*` 环境变量覆盖。

- 没有 `.env` 时，直接使用 [nuxt.config.ts](./nuxt.config.ts) 里的内置默认值
- `.env.example` 只是示例，不会被自动加载；需要复制为 `.env` 才会生效

```env
SITE_TITLE=染念的笔记
SITE_AUTHOR=染念
SITE_URL=https://dyedd.cn
SITE_EMAIL=1176996982@qq.com
SITE_PROFILE_AVATAR=/logo.jpg
SITE_PROFILE_INTRO=第一句|第二句
SITE_PROFILE_MOTTO=第一句|第二句
SITE_PROFILE_TECH_STACK=Python::https://img.shields.io/...|Vue::https://img.shields.io/...
```

常用可配置项：

- 站点基础信息：`SITE_TITLE`、`SITE_AUTHOR`、`SITE_DESCRIPTION`、`SITE_KEYWORDS`、`SITE_URL`、`SITE_EMAIL`、`SITE_LANG`、`SITE_START_TIME`
- 个人资料：`SITE_PROFILE_AVATAR`、`SITE_PROFILE_BADGE`、`SITE_PROFILE_INTRO`、`SITE_PROFILE_MOTTO`、`SITE_PROFILE_STATEMENT`、`SITE_PROFILE_GITHUB_CHART`、`SITE_PROFILE_TECH_STACK`
- 社交与统计：`SITE_GITHUB_URL`、`SITE_QQ_URL`、`SITE_ANALYTICS_SCRIPT`、`SITE_ANALYTICS_WEBSITE_ID`
- 备案信息：`SITE_FOOTER_ICP_LABEL`

其中一些值会自动复用，不需要重复配置：

- `profile.name` 复用 `SITE_AUTHOR`
- 邮箱链接自动由 `SITE_EMAIL` 生成
- 页脚版权名复用 `SITE_AUTHOR`
- `poweredBy` 固定为 `Powered by serenade` 和项目仓库地址
- QQ 图标提示文案固定为 `QQ`
- 友链申请联系文案固定为 `邮箱`
- 友链申请模板默认复用 `SITE_AUTHOR`、`SITE_URL`、`SITE_DESCRIPTION`、`SITE_PROFILE_AVATAR`
- `SITE_PROFILE_INTRO`、`SITE_PROFILE_MOTTO` 用 `|` 分隔多行
- `SITE_PROFILE_TECH_STACK` 用 `标签::图标URL|标签::图标URL` 配置

默认值直接定义在 `nuxt.config.ts` 中：

```ts
export const siteConfig = {
  author: "染念",
  title: "染念的笔记",
  description: "Writing code, painful and happy",
  keywords: "染念,染念的笔记,染念の笔记,染念的博客,博客,blog",
  url: "https://dyedd.cn",
  email: "1...2@qq.com",
  lang: "zh-CN",
  startTime: "2017-02-11",
};
```

## API

接口位于 `server/api/`，常用如下：

- `GET /api/posts?page=&pageSize=`：文章列表（按日期倒序）
- `GET /api/posts/<path>`：单篇文章（meta + html + prev/next）
- `GET /api/posts/search?keyword=&page=&pageSize=`：全文搜索
- `GET /api/columns` / `GET /api/columns/<path>`：专栏与章节
- `GET /api/tags` / `GET /api/tags/<tag>`：标签统计 / 标签文章
- `GET /api/projects` / `GET /api/projects/categories`：项目
- `GET /api/friends`：友链 / RSS 朋友圈（需联网）

## 贡献

欢迎提交 Issue 和 Pull Request。

## License

MIT

serenade

serenade 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

serenade

serenade 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README