# bun-project

**Repository Path**: learnfront/bun-project

## Basic Information

- **Project Name**: bun-project
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Bun + SQLite + JWT Server Project

## 项目介绍

这是一个基于 Bun 官方生态搭建的前后端分离服务端项目，核心技术栈为 Bun + SQLite + JWT，实现了用户认证、角色管理和日志记录等功能。

## 技术栈

- **运行环境**：Bun
- **数据库**：SQLite（持久化存储）
- **认证**：JWT（Access Token + Refresh Token 双令牌机制）
- **部署**：Podman

## 环境要求

- Bun 1.0.0 或更高版本
- Podman（用于容器化部署）

## 安装步骤

1. **克隆项目**
   ```bash
   git clone <repository-url>
   cd bun-sqlite-jwt-server
   ```

2. **安装依赖**
   ```bash
   bun install
   ```

## 开发环境

### 启动开发服务器（支持热更新）
```bash
npm run dev
```

服务器将在 `http://localhost:3000` 启动，支持原生热更新。

### 数据库初始化
开发环境启动时会自动初始化数据库表结构，无需单独执行。

## 生产环境

### 打包为单文件可执行程序
```bash
npm run build
```

打包后的可执行文件为 `server`，位于项目根目录。

### 启动生产服务器
```bash
npm start
```

或使用打包后的可执行文件：
```bash
./server
```

## Podman 容器化部署

### 构建镜像并启动容器
```bash
./deploy.sh
```

此脚本会：
1. 构建 Podman 镜像
2. 创建数据卷用于数据库持久化
3. 启动容器并映射到端口 8080

### 手动构建和运行

1. **构建镜像**
   ```bash
   podman build -t bun-sqlite-jwt-server -f Containerfile .
   ```

2. **创建数据卷**
   ```bash
   podman volume create bun-server-database
   ```

3. **运行容器**
   ```bash
   podman run -d \
     --name bun-server \
     --volume bun-server-database:/app/database \
     --publish 8080:8080 \
     bun-sqlite-jwt-server
   ```

## API 接口说明

### 认证接口

#### 注册
- **路径**：`/api/auth/register`
- **方法**：`POST`
- **请求体**：
  ```json
  {
    "username": "admin",
    "password": "123456",
    "email": "admin@example.com"
  }
  ```
- **响应**：返回用户信息

#### 登录
- **路径**：`/api/auth/login`
- **方法**：`POST`
- **请求体**：
  ```json
  {
    "username": "admin",
    "password": "123456"
  }
  ```
- **响应**：返回用户信息和令牌

#### 刷新令牌
- **路径**：`/api/auth/refresh`
- **方法**：`POST`
- **请求体**：
  ```json
  {
    "refreshToken": "<your-refresh-token>"
  }
  ```
- **响应**：返回新的令牌

### 用户接口

#### 获取用户信息
- **路径**：`/api/user/profile`
- **方法**：`GET`
- **认证**：需要 JWT Access Token
- **响应**：返回用户详细信息和角色

### 日志接口

#### 获取登录日志
- **路径**：`/api/log/login`
- **方法**：`GET`
- **认证**：需要 JWT Access Token
- **查询参数**：
  - `startDate`：开始日期
  - `endDate`：结束日期
  - `userId`：用户ID
  - `username`：用户名
  - `status`：状态（success/failed）
  - `limit`：每页条数
  - `offset`：偏移量
- **响应**：返回登录日志列表和分页信息

#### 获取异常日志
- **路径**：`/api/log/error`
- **方法**：`GET`
- **认证**：需要 JWT Access Token
- **查询参数**：
  - `startDate`：开始日期
  - `endDate`：结束日期
  - `userId`：用户ID
  - `username`：用户名
  - `limit`：每页条数
  - `offset`：偏移量
- **响应**：返回异常日志列表和分页信息

#### 获取请求日志
- **路径**：`/api/log/request`
- **方法**：`GET`
- **认证**：需要 JWT Access Token
- **查询参数**：
  - `startDate`：开始日期
  - `endDate`：结束日期
  - `userId`：用户ID
  - `username`：用户名
  - `limit`：每页条数
  - `offset`：偏移量
- **响应**：返回请求日志列表和分页信息

## 环境配置

项目使用环境变量区分开发/生产模式，配置文件如下：

- **开发环境**：`.env.development`
- **生产环境**：`.env.production`

主要配置项：
- `PORT`：服务器端口
- `NODE_ENV`：环境模式
- `JWT_ACCESS_SECRET`：Access Token 密钥
- `JWT_REFRESH_SECRET`：Refresh Token 密钥
- `JWT_ACCESS_EXPIRES_IN`：Access Token 过期时间
- `JWT_REFRESH_EXPIRES_IN`：Refresh Token 过期时间
- `DATABASE_PATH`：数据库文件路径

## 项目结构

```
bun-sqlite-jwt-server/
├── src/
│   ├── config/         # 配置文件
│   ├── db/             # 数据库封装
│   ├── middleware/     # 中间件
│   ├── routes/         # 路由
│   ├── utils/          # 工具函数
│   └── index.ts        # 主入口文件
├── database/           # 数据库文件目录
├── .env.development    # 开发环境配置
├── .env.production     # 生产环境配置
├── Containerfile       # Podman 构建文件
├── deploy.sh           # 部署脚本
├── package.json        # 项目配置
└── README.md           # 项目说明
```

## 注意事项

1. **数据库持久化**：生产环境使用 Podman 数据卷持久化数据库，确保容器重启后数据不丢失。
2. **安全配置**：生产环境请修改 `.env.production` 中的 JWT 密钥为强密钥。
3. **日志管理**：系统会自动记录登录日志、请求日志和异常日志，可通过 API 接口查询。
4. **性能优化**：SQLite 已配置为 WAL 模式，提高并发性能。

## 常见问题

### 端口被占用
- 修改环境变量文件中的 `PORT` 配置。

### 数据库连接失败
- 检查数据库文件路径是否正确，确保目录存在且有写入权限。

### JWT 令牌验证失败
- 检查环境变量中的 JWT 密钥是否正确，确保开发和生产环境使用不同的密钥。