# Express-Server-API

**Repository Path**: qeyser/express-server-api

## Basic Information

- **Project Name**: Express-Server-API
- **Description**: Express、MongoDB、Redis实现的常用后端服务接口
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-06-26
- **Last Updated**: 2025-06-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

### 项目部署

#### 1. Docker 部署

- 请先安装 Node.js 18+
- 请先安装 Docker 和 Docker Compose
- 复制一份 `.env.example` 文件，命名为 `.env` 并根据情况配置环境变量
- 根据 `.env` 设置的环境变量，视情况修改 `docker-compose.yml` 文件中的端口映射、数据库连接等配置
- `docker compose up -d` 命令，启动服务

#### 2. 手动部署

- 请先安装 Node.js 18+
- 请先安装 MongoDB 8.0+
- 请先安装 Redis 7.4+
- 执行 `npm install` 命令，安装依赖
- 复制一份 `.env.example` 文件，命名为 `.env` 并根据情况配置环境变量
- 执行 `npm run start` 或者 `npm run dev` 命令，启动服务

### 项目介绍

采用 Express、Mongoose、Redis 等技术，实现博客、聊天应用、用户管理、后台管理等常见后端服务，项目采用 MVC（Model-View-Controller） 架构进行设计。励志以 JavaScript 打遍天下无敌手。

### 实现功能

- 用户管理：
  - 账号登录、注册、注销、修改密码、修改个人信息等等
  - 邮箱验证码发送和验证
  - accessToken 和 refreshToken 双 token 机制：accessToken 黑名单机制防止 token 泄露滥用；refreshToken 设备指纹、ip 地址监测防止滥用；httpOnly cookie 存储 refreshToken 保障安全；refreshToken 自动续期
- 博客：
  - 文章
  - 分类
  - 标签
  - 评论
  - XSS 攻击防御
- 后台管理：
  - 系统信息
- 聊天：
  - 私聊
  - 私聊消息
  - 设备指纹
  - 添加好友
  - 处理好友请求
  - 好友列表
- 文件系统：
  - 上传文件
  - 大文件分片上传
  - 合并分片
  - 秒传
  - 断点续传
  - 文件记录
- 日志记录：
  - HTTP 请求日志
  - 系统应用层错误日志

### 访问地址

- 服务地址：http://localhost/api/
- socket.io 服务：ws://localhost:3000 或者 wss://localhost:3000
- swagger 文档：http://localhost/api-docs

### 环境变量说明

- HTTP_PORT: HTTP 服务端口
- HTTPS: 是否启用 HTTPS
- HTTPS_PORT: HTTPS 服务端口
- SOCKET: 是否启用 socket.io 服务
- SOCKET_PORT: socket.io 服务端口
- ALLOWED_ORIGIN: 允许跨域访问的域名
- SSL_KEY_PATH: SSL 私钥文件路径
- SSL_CERT_PATH: SSL 证书文件路径

### 注意事项

- 线上环境必须使用 `HTTPS` 协议，否则无法将 `refreshToken` 存储在 `httpOnly cookie` 中，导致登录失败
- 用户登录功能，需要传入 `visitorId` 到请求头 `x-visitor-id` 中，visitorId 是一个浏览器的唯一标识符，由前端生成。它可以是 `uuid` 但是必须存储本地因为很多接口请求的认证需要这个参数；也可以是 `fingerprintjs2`、`ClientJS` 等库生成的访问者 ID，visitorId 最好使用访问者 ID，因为访问者 ID 是根据浏览器特征生成的唯一 ID
- 大文件分片在合并的时候要计算 hash 验证文件是否被篡改，为了避免文件认证出错，后端需要和前端使用同一种算法去计算文件 hash ，目前采用的是 md5 算法，前端也需要使用 md5 算法去计算
- socketIO 使用的中间件是 express 中间件进行的兼容，客户端需要将认证请求头传入 `extraHeaders` 而不是 `auth`，因为它能获取到完整的 HTTP 请求信息。客户端连接：

```js
const socket = io("http://localhost:3000/chat", {
  extraHeaders: {
    "x-visitor-id": "visitorId",
    Authorization: `Bearer ${token}`,
  },
});
```