# xiaozhi-bbs

**Repository Path**: shure/xiaozhi-bbs

## Basic Information

- **Project Name**: xiaozhi-bbs
- **Description**: 小治论坛，一个开放自由的匿名论坛系统 —— 无需登录即可发帖、跟帖、评论。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-11
- **Last Updated**: 2026-06-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: 论坛, 匿名, AI开发

## README

# 小治论坛 (xiaozhi-bbs)

匿名论坛系统 —— 无需登录即可发帖、跟帖、评论。PC + 移动端 H5 自适应。

## 技术栈

| 层级 | 技术 |
|------|------|
| **前端** | Vue 3 (Composition API + `<script setup>`) / TypeScript / Vite 6 |
| **样式** | Tailwind CSS 3（移动端优先，768px 断点） |
| **路由** | vue-router 4（hash 模式） |
| **状态管理** | Pinia 2 |
| **HTTP 客户端** | Axios |
| **后端** | Express 4 / TypeScript |
| **数据库** | MySQL 8+（Knex.js 查询构建器 + 迁移） |
| **安全** | Helmet, CORS, express-rate-limit |
| **包管理** | pnpm workspace（Monorepo） |

## 快速开始

### 前置条件

- Node.js >= 18
- pnpm（`npm i -g pnpm`）
- MySQL 8+

### 安装

```bash
# 克隆后进入项目根目录
pnpm install
```

### 数据库配置

创建 MySQL 数据库：

```sql
CREATE DATABASE xiaozhi_bbs CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```

复制环境变量模板并填写：

```bash
cp server/.env.example server/.env
```

编辑 `server/.env`，配置数据库连接信息：

```
DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASSWORD=your_password
DB_NAME=xiaozhi_bbs
```

### 数据库迁移

```bash
pnpm --filter server migrate
```

### 启动开发服务

```bash
# 同时启动前端 (5173) 和后端 (3000)
pnpm dev
```

前端开发服务器已配置代理，`/api` 请求自动转发到后端。

## 项目结构

```
xiaozhi-bbs/
├── client/                    # Vue 3 前端 SPA
│   ├── src/
│   │   ├── api/               # Axios 实例 + API 函数 + TypeScript 类型
│   │   ├── components/        # 通用组件
│   │   │   ├── CommentTree.vue   # 嵌套评论展示 / 回复
│   │   │   ├── NavBar.vue        # 顶部导航 + 分类标签
│   │   │   ├── PostCard.vue      # 帖子列表卡片
│   │   │   └── PostForm.vue      # 发帖表单
│   │   ├── router/            # vue-router（hash 模式）
│   │   ├── stores/            # Pinia 状态
│   │   │   ├── categories.ts    # 分类列表
│   │   │   └── session.ts       # session_id
│   │   ├── utils/             # 工具函数（session_id 生成）
│   │   ├── views/
│   │   │   ├── Home.vue         # 帖子列表（首页）
│   │   │   ├── PostDetail.vue   # 帖子详情 + 评论
│   │   │   └── CreatePost.vue   # 发布帖子
│   │   ├── App.vue
│   │   ├── main.ts
│   │   └── style.css
│   ├── index.html
│   ├── vite.config.ts
│   ├── tailwind.config.js
│   └── package.json
│
├── server/                    # Express REST API
│   ├── src/
│   │   ├── index.ts             # 入口，dotenv + listen
│   │   ├── app.ts               # Express 应用（中间件 + 路由）
│   │   ├── config/
│   │   │   └── database.ts      # Knex 配置
│   │   ├── controllers/
│   │   │   ├── categories.ts    # 分类列表
│   │   │   ├── posts.ts         # 帖子 CRUD（分页 / 排序 / 软删除）
│   │   │   ├── comments.ts      # 创建评论（含嵌套回复）
│   │   │   └── reports.ts       # 举报
│   │   ├── middleware/
│   │   │   ├── session.ts       # X-Session-Id 解析
│   │   │   ├── rateLimiter.ts   # 读写速率限制
│   │   │   └── errorHandler.ts  # 全局错误处理
│   │   └── routes/              # 路由定义
│   ├── migrations/              # Knex 数据库迁移
│   │   ├── 001_create_categories.ts
│   │   ├── 002_create_posts.ts
│   │   ├── 003_create_comments.ts
│   │   └── 004_create_reports.ts
│   └── .env.example
│
├── pnpm-workspace.yaml
├── AGENTS.md
└── package.json
```

## 功能特性

### 已完成

- **匿名身份系统**：首次访问自动生成 UUID（`session_id`），存入 `localStorage`，随每个请求通过 `X-Session-Id` 头发送
- **分类浏览**：4 个默认分类（综合讨论 / 技术交流 / 分享 / 问答），帖子可按分类筛选
- **帖子 CRUD**：创建、列表（分页 + 最新/热门排序）、详情、删除（仅作者）
- **嵌套评论**：支持两级线程式回复，自动递增帖子的评论计数
- **举报机制**：用户可举报帖子或评论
- **速率限制**：写接口 10 次/15 分钟，读接口 120 次/分钟（按 IP）
- **软删除**：帖子和评论通过 `deleted_at` 字段软删除
- **响应式布局**：同一套 SFC，768px 断点自适应移动端/桌面端
- **安全中间件**：Helmet（安全头）、CORS、请求日志（Morgan）

### 规划中

- Tripcode（`#密码` 格式昵称生成跨 session 身份标识）
- Cloudflare Turnstile 无感验证码
- 图片上传（Multer 已引入，路由待实现）
- 关键词过滤
- 管理后台（IP 封禁、帖子/评论软删除管理）
- 部署方案（Express 静态托管或 CDN 分离部署）

## API 接口

| 方法 | 路径 | 说明 | 速率限制 |
|------|------|------|----------|
| GET | `/api/health` | 健康检查 | 无 |
| GET | `/api/categories` | 分类列表 | 无 |
| GET | `/api/posts` | 帖子列表（分页） | 读限制 |
| GET | `/api/posts/:id` | 帖子详情（含评论） | 读限制 |
| POST | `/api/posts` | 创建帖子 | 写限制 |
| DELETE | `/api/posts/:id` | 删除帖子 | 无 |
| POST | `/api/comments/:postId` | 发表评论/回复 | 写限制 |
| POST | `/api/reports` | 举报 | 写限制 |

### 分页参数

`GET /api/posts` 支持：

- `page` — 页码（默认 1）
- `per_page` — 每页条数（默认 20，最大 50）
- `category` — 分类 ID（可选）
- `sort` — 排序：`latest`（最新）、`hot`（最热，按评论数）

响应格式：

```json
{
  "data": [...],
  "pagination": { "page": 1, "per_page": 20, "total": 42 }
}
```

## 数据库表

### `categories` — 分类

| 列 | 类型 | 说明 |
|----|------|------|
| id | int (PK) | 自增主键 |
| name | varchar(50) | 分类名称 |
| slug | varchar(50) | 唯一标识 |
| sort_order | int | 排序权重 |
| created_at / updated_at | timestamp | 时间戳 |

### `posts` — 帖子

| 列 | 类型 | 说明 |
|----|------|------|
| id | varchar(36) PK | UUID |
| category_id | int FK | 关联分类（SET NULL） |
| title | varchar(200) | 标题 |
| content | text | 内容 |
| session_id | varchar(36) | 作者标识（已索引） |
| comment_count | int | 评论数（冗余） |
| is_pinned | boolean | 是否置顶 |
| is_locked | boolean | 是否锁定 |
| deleted_at | timestamp | 软删除时间 |

### `comments` — 评论

| 列 | 类型 | 说明 |
|----|------|------|
| id | varchar(36) PK | UUID |
| post_id | varchar(36) FK | 所属帖子（CASCADE） |
| parent_id | varchar(36) FK | 父评论（自引用，CASCADE） |
| content | text | 内容 |
| session_id | varchar(36) | 作者标识（已索引） |
| deleted_at | timestamp | 软删除时间 |

### `reports` — 举报

| 列 | 类型 | 说明 |
|----|------|------|
| id | int (PK) | 自增主键 |
| target_type | enum('post','comment') | 举报类型 |
| target_id | varchar(36) | 目标 ID |
| reason | text | 举报原因 |
| created_at | timestamp | 举报时间 |

## 开发命令

```bash
pnpm dev                  # 同时启动前后端
pnpm build                # 构建（先编译后端，再构建前端）
pnpm lint                 # TypeScript 类型检查
pnpm --filter server migrate         # 执行迁移
pnpm --filter server migrate:rollback # 回滚迁移
pnpm start                # 生产启动（运行编译后的后端）
```

## 匿名身份设计

- 无用户注册。访客首次访问时通过 `crypto.randomUUID()` 生成 UUID 作为 `session_id`，存入 `localStorage`
- 服务端通过 `X-Session-Id` 请求头提取 session_id，格式校验后注入 `req.sessionId`
- 删除操作仅校验 `session_id` 匹配，无密码验证
- Tripcode（`#密码` 格式昵称哈希）是规划中的可选功能，用于跨 session 身份识别