# kimi-blog

**Repository Path**: NativeBase/kimi-blog

## Basic Information

- **Project Name**: kimi-blog
- **Description**: 基于kimi-code 开发的博客
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-26
- **Last Updated**: 2026-05-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# kimi-demo

个人作品集/博客站点，基于 Next.js 构建。

## 🎯 项目定位

一个面向个人展示的内容型网站，涵盖博客文章、随记、图库、关于页和留言墙等模块，属于典型的"创作者主页"或"个人品牌站点"。

## 🛠️ 技术栈

| 层级 | 技术 |
|------|------|
| 框架 | Next.js 16.2.4 + React 19.2.4 + TypeScript |
| 样式 | Tailwind CSS v4 |
| 数据库 | Drizzle ORM + MySQL2 |
| 校验 | Zod |
| 文档生成 | `@asteasolutions/zod-to-openapi` + `@scalar/api-reference-react` |
| 其他 | Lucide React（图标）、Playwright（测试） |

## 📁 项目结构

```
src/
├── app/
│   ├── (site)/              # 前台站点路由组
│   │   ├── page.tsx         # 首页（聚合展示）
│   │   ├── about/           # 关于/个人介绍
│   │   ├── gallery/         # 图库/摄影作品
│   │   ├── guestbook/       # 留言墙
│   │   ├── notes/           # 随记/碎片内容
│   │   └── posts/           # 文章/博客列表
│   ├── (admin)/             # 管理端路由组
│   │   ├── login/           # 登录页（未登录跳转至此）
│   │   ├── admin/           # Dashboard 概览
│   │   ├── admin/posts/     # 文章管理
│   │   └── admin/messages/  # 留言管理
│   ├── api/
│   │   ├── messages/        # 留言 API（前台）
│   │   ├── admin/           # 管理端 API
│   │   └── doc/             # OpenAPI JSON 文档输出
│   ├── doc/                 # Scalar API 文档页面
│   ├── robots.ts            # SEO：禁止爬虫收录管理端
│   └── layout.tsx           # 根布局
├── components/
│   ├── features/            # 业务组件（首页各区块、文章、留言）
│   ├── layout/              # 布局组件（导航、页脚、主题）
│   ├── admin/               # 管理端组件（侧边栏、顶部栏）
│   └── ui/                  # 基础 UI 组件
├── config/
│   └── site.ts              # 站点配置
├── lib/
│   ├── api-response.ts      # 统一 API 响应结构工厂函数
│   └── db/
│       ├── index.ts         # 数据库连接（含自动初始化）
│       ├── init.ts          # 智能建表：缺表时创建，有表不动
│       └── schema.ts        # Drizzle Schema 定义
├── server/
│   ├── services/            # 业务服务层
│   ├── validators/          # Zod 校验 + OpenAPI Schema
│   └── actions/             # Server Actions
├── scripts/
│   └── init-db.ts           # 数据库初始化 CLI 脚本
├── types/
│   ├── api-response.ts      # API 响应标准类型定义
│   └── index.ts             # 业务类型定义（Message、Post）
├── middleware.ts            # 路由守卫（登录认证）
└── next.config.ts           # Next.js 配置
```

## 🗺️ 路由地图

### 前端页面

| 路径 | 说明 |
|------|------|
| `/` | 首页：聚合展示入口 |
| `/posts` | 文章/博客列表 |
| `/notes` | 随记/碎片内容 |
| `/gallery` | 图库/摄影展示 |
| `/about` | 关于/个人介绍 |
| `/guestbook` | 留言墙（用户互动） |

### 管理端页面

| 路径 | 说明 |
|------|------|
| `/login` | 管理端登录页（未认证跳转至此） |
| `/admin` | 管理后台：Dashboard 概览 |
| `/admin/posts` | 文章管理 |
| `/admin/messages` | 留言管理 |

### 接口地址

| 路径 | 说明 |
|------|------|
| `/api/messages` | 留言数据接口（前台：GET/POST） |
| `/api/admin/posts` | 文章数据接口（管理端：GET） |
| `/api/admin/messages` | 留言数据接口（管理端：GET） |
| `/api/doc` | **OpenAPI 3.1 JSON 文档**（由 Zod Schema 自动生成） |

### 文档页面

| 路径 | 说明 |
|------|------|
| `/doc` | **Scalar API 文档** — 交互式 API 文档，基于 Zod Schema 自动生成 |

> 所有接口统一遵循 `doc/API 接口响应标准文档.md` 的响应结构：`{ code, message, data, timestamp }`。

## 🚀 快速开始

### 1. 环境准备

复制环境变量模板并配置：

```bash
cp .env.local.example .env.local
# 编辑 .env.local，填入你的 DATABASE_URL 和 AUTH_SECRET
```

`.env.local` 必需配置：

```bash
# MySQL 数据库连接串
DATABASE_URL=mysql://用户名:密码@主机:端口/数据库名

# JWT 密钥（用于管理端登录认证，至少 32 位随机字符串）
AUTH_SECRET=your-super-secret-key
```

### 2. 安装依赖

```bash
npm install
```

### 3. 初始化数据库

```bash
npm run db:init
```

> 该命令会检查并自动创建缺失的数据表（`messages`、`posts`），已有表完全不动，不会修改字段或丢失数据。  
> 不手动执行也没关系——应用首次访问时会在后台自动初始化。

### 4. 运行开发服务器

```bash
npm run dev
```

打开 [http://localhost:3000](http://localhost:3000) 访问前台站点。  
管理后台地址：[http://localhost:3000/admin](http://localhost:3000/admin)  
接口文档（Scalar API 文档）：[http://localhost:3000/doc](http://localhost:3000/doc)

### 5. 构建

```bash
npm run build
```

## 🗄️ 数据表

| 表名 | 说明 | 字段 |
|------|------|------|
| `messages` | 留言墙数据 | id, name, email, content, created_at |
| `posts` | 博客文章 | id, title, slug, excerpt, content, cover_image, tag, views, created_at |

## ⚠️ 开发须知

> **Next.js 16 存在 API 破坏性变化**
>
> 本项目使用的 Next.js 版本与常见的 14/15 版本在 API、约定和文件结构上可能存在差异。在编写代码前，请先查阅 `node_modules/next/dist/docs/` 中的最新文档，并注意其中的弃用（deprecation）提示。

## 📄 相关文档

- [Next.js 入门指南](./doc/Next.js%20入门指南.md) — Next.js 16 基础用法与配置
- [网站结构梳理](./doc/网站结构梳理.md) — 站点架构、模块拆解与开发优先级
- [API 接口响应标准文档](./doc/API%20接口响应标准文档.md) — 统一接口响应结构规范
- [API 文档](./doc/api.md) — 接口说明（含前台与管理端）
- [管理端登录认证方案](./doc/管理端登录认证方案.md) — 登录认证设计文档
- [Zod 生成 OpenAPI 文档方案](./doc/Zod%20生成%20OpenAPI%20文档方案.md) — Zod 自动生成 OpenAPI 文档
- [Drizzle ORM 指南](./doc/Drizzle%20ORM.md) — 数据库 ORM 使用说明
- [Zod 校验指南](./doc/Zod%20校验.md) — 表单校验与类型安全
- [开发计划](./doc/plan.md) — 功能规划与迭代路线