# 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-06-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 逸刻时光 (kimi-demo)

个人作品集与博客站点，基于 Next.js 16 构建。作者：Mr 焦

## 技术栈

| 层级 | 技术 |
|------|------|
| 框架 | Next.js 16.2.4 + React 19.2.4 + TypeScript 5 (strict) |
| 样式 | Tailwind CSS v4 + CSS 变量主题系统（明暗模式） |
| 数据库 | Drizzle ORM + mysql2 |
| 校验 | Zod 4.x |
| 认证 | JWT + HttpOnly Cookie（bcrypt 密码加密） |
| API 文档 | `@asteasolutions/zod-to-openapi` + `@scalar/api-reference-react` |
| Markdown | `react-markdown` + `remark-gfm` + `rehype-highlight` |
| 其他 | lucide-react（图标）、Playwright（测试） |

## 快速开始

```bash
# 1. 安装依赖
npm install

# 2. 配置环境变量（编辑现有 .env.local，填入 DATABASE_URL 和 AUTH_SECRET）

# 3. 初始化数据库（幂等，已有表不动）
npm run db:init

# 4. 启动开发服务器（http://localhost:13001）
npm run dev

# 5. 生产构建
npm run build
npm run start    # 生产端口 13001
```

其他命令：`npm run lint`（ESLint）、`npm run db:init`（初始化数据库）、`npm run deploy`（部署脚本）

## 项目结构

```
src/
├── app/
│   ├── (site)/              # 前台站点路由组
│   │   ├── page.tsx         # 首页（聚合展示）
│   │   ├── about/           # 关于/个人介绍
│   │   ├── gallery/[id]/    # 图库详情
│   │   ├── guestbook/       # 留言墙
│   │   ├── notes/           # 随记/碎片内容
│   │   ├── posts/[id]/      # 文章详情
│   │   ├── tetris/          # 俄罗斯方块小游戏
│   │   ├── wiki/[id]/       # Wiki 笔记详情
│   │   └── yike-design/     # 设计展示
│   ├── (tools)/
│   │   └── tools/           # 工具箱页面
│   ├── (bookmarks)/
│   │   └── bookmarks/       # 收藏网址（独立路由组）
│   ├── (admin)/             # 管理端路由组
│   │   ├── login/           # 登录页
│   │   ├── register/        # 注册页
│   │   └── admin/
│   │       ├── page.tsx     # Dashboard
│   │       ├── posts/       # 文章管理
│   │       ├── messages/    # 留言管理
│   │       ├── bookmarks/   # 书签管理
│   │       ├── gallery/     # 图库管理
│   │       ├── notes/       # 随记管理
│   │       ├── wiki/        # Wiki 管理
│   │       ├── categories/          # 分类管理
│   │       ├── bookmark-categories/ # 书签分类管理
│   │       └── settings/    # 系统设置（站点设置 + 安全设置）
│   ├── api/
│   │   ├── auth/            # 认证 API（login/logout/register/me）
│   │   ├── admin/           # 管理端 CRUD API
│   │   ├── messages/        # 公开留言 API
│   │   ├── notes/           # 公开随记 API
│   │   ├── gallery/         # 公开图库 API
│   │   ├── wiki/            # 公开 Wiki API
│   │   ├── bookmarks/       # 公开书签 API
│   │   ├── categories/      # 公开分类 API
│   │   ├── site-settings/   # 公开站点设置 API
│   │   └── doc/             # OpenAPI JSON 文档
│   ├── doc/                 # Scalar API 文档页面
│   ├── layout.tsx           # 根布局
│   ├── globals.css          # 全局样式 + Tailwind + CSS 变量
│   └── robots.ts            # SEO 控制
├── components/
│   ├── features/            # 页面级功能组件
│   │   ├── home/            # 首页各区块
│   │   ├── posts/           # 文章列表/详情
│   │   ├── notes/           # 随记列表
│   │   ├── gallery/         # 图库列表/专辑
│   │   ├── wiki/            # Wiki 列表/文章
│   │   ├── bookmarks/       # 书签列表
│   │   ├── guestbook/       # 留言墙
│   │   ├── tools/           # 工具箱
│   │   └── tetris/          # 俄罗斯方块
│   ├── layout/              # 布局组件（Navbar、Footer、ThemeProvider）
│   ├── admin/               # 管理端组件（Header、Sidebar、EditorForm 等）
│   └── shared/              # 共享组件（MarkdownRenderer、DetailArticleLayout 等）
├── config/
│   └── site.ts              # 站点配置
├── data/
│   ├── wiki.ts              # Wiki 静态数据
│   └── tools.ts             # 工具箱静态数据
├── lib/
│   ├── db/                  # 数据库（schema、连接、初始化）
│   ├── api-response.ts      # 统一 API 响应
│   ├── auth-server.ts       # 服务端认证工具
│   ├── auth-client.ts       # 客户端认证工具
│   ├── jwt.ts               # JWT 创建/验证
│   ├── admin-api.ts         # 管理端 API 客户端
│   ├── markdown.ts          # Markdown 工具
│   ├── openapi.ts           # OpenAPI 注册
│   ├── image.ts             # 图片工具
│   ├── search-params.ts     # URL 参数解析
│   └── site-settings-client.ts  # 客户端站点设置
├── server/
│   ├── services/            # 业务服务层（auth、post、note、wiki、gallery 等）
│   └── validators/          # Zod 校验 + OpenAPI Schema
├── types/
│   ├── index.ts             # 业务类型（Post、Note、WikiArticle 等）
│   └── api-response.ts      # API 响应类型
└── proxy.ts                 # Next.js 16 路由守卫（登录认证）
```

## 路由地图

### 前台页面

| 路径 | 说明 |
|------|------|
| `/` | 首页（聚合展示） |
| `/posts` | 文章列表 |
| `/posts/[id]` | 文章详情 |
| `/notes` | 随记列表 |
| `/gallery` | 图库列表 |
| `/gallery/[id]` | 相册详情 |
| `/wiki` | Wiki 笔记列表 |
| `/wiki/[id]` | Wiki 详情 |
| `/bookmarks` | 收藏网址 |
| `/about` | 关于 |
| `/guestbook` | 留言墙 |
| `/tetris` | 俄罗斯方块 |
| `/yike-design` | 设计展示 |
| `/tools` | 工具箱 |

### 管理端页面

| 路径 | 说明 |
|------|------|
| `/login` | 登录 |
| `/register` | 注册 |
| `/admin` | Dashboard |
| `/admin/posts` | 文章管理 |
| `/admin/messages` | 留言管理 |
| `/admin/bookmarks` | 书签管理 |
| `/admin/gallery` | 图库管理 |
| `/admin/notes` | 随记管理 |
| `/admin/wiki` | Wiki 管理 |
| `/admin/categories` | 分类管理 |
| `/admin/bookmark-categories` | 书签分类管理 |
| `/admin/settings` | 系统设置 |

### API 接口

| 分组 | 路径 | 说明 |
|------|------|------|
| 认证 | `/api/auth/*` | 登录/登出/注册/当前用户 |
| 管理端 | `/api/admin/*` | 全量 CRUD + 上传 + 密码修改 + 个人资料 |
| 公开 | `/api/messages` | 留言（GET/POST） |
| 公开 | `/api/notes` | 随记（GET） |
| 公开 | `/api/gallery` | 图库（GET） |
| 公开 | `/api/wiki` | Wiki（GET） |
| 公开 | `/api/bookmarks` | 书签（GET） |
| 公开 | `/api/categories` | 分类（GET） |
| 公开 | `/api/site-settings` | 站点设置（GET） |

## 数据库

| 表名 | 说明 |
|------|------|
| `messages` | 留言墙 |
| `posts` | 博客文章 |
| `categories` | 分类（文章/图库/Wiki） |
| `gallery_albums` | 图库相册 |
| `notes` | 随记/日记 |
| `wiki_articles` | Wiki 编程笔记 |
| `bookmark_categories` | 书签分类 |
| `bookmarks` | 收藏网址 |
| `users` | 用户（管理员） |
| `site_settings` | 站点配置（键值对） |

## 环境变量

```bash
DATABASE_URL=mysql://用户名:密码@主机:端口/数据库名
AUTH_SECRET=your-super-secret-key    # JWT 密钥，至少 32 位
```

## 架构分层

```
Route Handler (app/api/*/route.ts)
    -> Service (server/services/*.service.ts)
        -> Validator (server/validators/*.schema.ts)
            -> Schema (lib/db/schema.ts)
```

- **前台 SSR**（SEO 友好），**管理端 SPA**（交互友好）
- 认证使用 JWT + HttpOnly Cookie，逻辑在 `auth.service.ts`
- API 响应统一使用 `@/lib/api-response`

## 相关文档

- [API 接口响应标准文档](./doc/API%20接口响应标准文档.md) — 统一接口响应结构规范
- [管理端登录认证方案](./doc/管理端登录认证方案.md) — 登录认证设计文档
- [Zod 生成 OpenAPI 文档方案](./doc/Zod%20生成%20OpenAPI%20文档方案.md) — OpenAPI 自动生成方案
- [Drizzle ORM](./doc/Drizzle%20ORM.md) — 数据库 ORM 使用说明
- [Zod 校验](./doc/Zod%20校验.md) — 表单校验与类型安全
- [Docker 部署与运维手册](./doc/Docker部署与运维手册.md) — 部署指南
- [Next.js 入门指南](./doc/Next.js%20入门指南.md) — Next.js 16 基础用法

> **注意：** Next.js 16 存在破坏性变化，编写代码前请查阅 `node_modules/next/dist/docs/` 的最新文档。