H3 Admin

企业级后端服务解决方案

基于 H3 v2 构建的现代化后端服务，提供完整的用户认证、授权和用户管理功能。

快速开始 • 文档 • API 参考 • 贡献

项目简介

H3 Admin 是一个轻量级、高性能的企业级后端服务，采用现代化的技术栈和最佳实践构建。项目专注于提供可靠、安全、可扩展的用户认证和管理解决方案，适用于各类 Web 应用程序和移动应用的后端服务。

设计理念

简洁性: 最小化依赖，专注于核心功能
安全性: 内置多层安全防护机制
可扩展性: 模块化设计，易于扩展和维护
类型安全: 完整的 TypeScript 类型定义
标准化: 遵循 RESTful API 设计规范

核心特性

认证与授权

✅ 用户注册与登录
✅ 基于 Session 的会话管理
✅ 密码加密存储（SHA-256 + Salt）
✅ 自动会话过期处理
✅ 安全登出机制

用户管理

✅ 用户资料查询
✅ 用户资料更新
✅ 密码修改
✅ 账户删除
✅ 用户角色管理

系统功能

✅ 统一响应格式
✅ 全局错误处理
✅ 请求日志记录
✅ CORS 跨域支持
✅ 请求限流保护
✅ 健康检查接口

开发体验

✅ TypeScript 类型安全
✅ 热重载开发模式
✅ 代码格式化（Prettier）
✅ 模块化架构设计

技术架构

技术栈

技术	版本	说明
H3	v2.0.1-rc.8	Web 框架
TypeScript	5.9.3	编程语言
Zod	3.22.4	数据验证
Node.js	18+	运行环境
pnpm	-	包管理器

架构设计

┌─────────────────────────────────────────────────────────────┐
│                      Client Layer                       │
│              (Web / Mobile / Third-party)               │
└──────────────────────┬──────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│                    Middleware Layer                      │
│  ┌─────────┐ ┌──────────┐ ┌──────────┐ ┌─────────┐│
│  │   CORS  │ │  Logger  │ │Rate Limit│ │ Session ││
│  └─────────┘ └──────────┘ └──────────┘ └─────────┘│
└──────────────────────┬──────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│                     Route Layer                         │
│  ┌──────────────┐  ┌──────────────┐               │
│  │ Auth Routes   │  │ User Routes   │               │
│  └──────────────┘  └──────────────┘               │
└──────────────────────┬──────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│                   Service Layer                         │
│  ┌──────────────┐  ┌──────────────┐               │
│  │ Auth Service  │  │ User Service  │               │
│  └──────────────┘  └──────────────┘               │
└──────────────────────┬──────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│                Repository Layer                          │
│  ┌──────────────┐  ┌──────────────┐               │
│  │ User Repo     │  │ Session Repo  │               │
│  └──────────────┘  └──────────────┘               │
└──────────────────────┬──────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│                   Data Layer                           │
│              (In-Memory Storage)                        │
└─────────────────────────────────────────────────────────────┘

分层说明

中间件层: 处理跨域、日志、限流、会话等横切关注点
路由层: 定义 API 端点和请求路由
服务层: 实现业务逻辑和数据处理
仓储层: 封装数据访问操作
数据层: 提供数据持久化能力

快速开始

环境要求

Node.js >= 18.0.0
pnpm >= 8.0.0
Git >= 2.0.0

安装步骤

克隆仓库

git clone https://github.com/FuntrySun/h3-admin.git
cd h3-admin

安装依赖

pnpm install

配置环境变量

cp .env.example .env

编辑 .env 文件，配置必要的环境变量：

PORT=3001
NODE_ENV=development
SESSION_SECRET=your-secret-key-here

启动开发服务器

pnpm run dev

服务器将在 http://localhost:3001 启动。

验证安装

访问健康检查接口：

curl http://localhost:3001/health

预期响应：

{
  "code": 200,
  "success": true,
  "timestamp": 1768562822218,
  "data": {
    "status": "healthy",
    "timestamp": 1768562822218,
    "uptime": 5.317492375
  }
}

配置说明

环境变量

变量名	类型	默认值	说明
`PORT`	Number	3001	服务器监听端口
`NODE_ENV`	String	development	运行环境（development/production）
`SESSION_SECRET`	String	-	Session 加密密钥（必填）
`SESSION_NAME`	String	h3-session	Cookie 名称
`SESSION_MAX_AGE`	Number	604800	Session 有效期（秒）
`CORS_ORIGIN`	String	*	CORS 允许的源
`CORS_METHODS`	String	GET,POST,PUT,DELETE,PATCH,OPTIONS	CORS 允许的方法
`RATE_LIMIT_WINDOW`	Number	60000	限流时间窗口（毫秒）
`RATE_LIMIT_MAX`	Number	100	限流最大请求数
`LOG_LEVEL`	String	info	日志级别（debug/info/warn/error）

配置文件

项目支持通过环境变量进行配置，所有配置项均在 .env 文件中定义。生产环境建议使用环境变量管理工具（如 dotenv-vault）来管理敏感信息。

API 参考

基础信息

Base URL: http://localhost:3001
Content-Type: application/json
认证方式: Cookie-based Session

响应格式

所有 API 响应遵循统一格式：

interface ApiResponse<T> {
  code: number;
  success: boolean;
  msg?: string;
  timestamp: number;
  data?: T;
}

健康检查

获取服务状态

GET /health

响应示例：

{
  "code": 200,
  "success": true,
  "timestamp": 1768562822218,
  "data": {
    "status": "healthy",
    "timestamp": 1768562822218,
    "uptime": 5.317492375
  }
}

认证接口

用户注册

POST /api/auth/register
Content-Type: application/json

{
  "username": "string",
  "email": "string",
  "password": "string",
  "confirmPassword": "string"
}

请求参数：

参数	类型	必填	说明
username	String	是	用户名（3-20 字符）
email	String	是	邮箱地址
password	String	是	密码（至少 6 字符）
confirmPassword	String	是	确认密码

响应示例：

{
  "code": 201,
  "success": true,
  "msg": "User registered successfully",
  "timestamp": 1768562903137,
  "data": {
    "id": "1768562903137-2t6n1yy",
    "username": "testuser",
    "email": "test@example.com",
    "role": "user"
  }
}

用户登录

POST /api/auth/login
Content-Type: application/json

{
  "username": "string",
  "password": "string"
}

请求参数：

参数	类型	必填	说明
username	String	是	用户名或邮箱
password	String	是	密码

响应示例：

{
  "code": 200,
  "success": true,
  "msg": "Login successful",
  "timestamp": 1768562910265,
  "data": {
    "id": "1768562903137-2t6n1yy",
    "username": "testuser",
    "email": "test@example.com",
    "role": "user",
    "createdAt": 1768562910265
  }
}

用户登出

POST /api/auth/logout
Cookie: h3-session=<session-token>

响应示例：

{
  "code": 200,
  "success": true,
  "msg": "Logout successful",
  "timestamp": 1768562910265
}

获取当前用户

GET /api/auth/me
Cookie: h3-session=<session-token>

响应示例：

{
  "code": 200,
  "success": true,
  "timestamp": 1768562910265,
  "data": {
    "id": "1768562903137-2t6n1yy",
    "username": "testuser",
    "email": "test@example.com",
    "role": "user",
    "createdAt": 1768562910265
  }
}

用户管理接口

获取用户资料

GET /api/user/profile
Cookie: h3-session=<session-token>

响应示例：

{
  "code": 200,
  "success": true,
  "timestamp": 1768562910265,
  "data": {
    "id": "1768562903137-2t6n1yy",
    "username": "testuser",
    "email": "test@example.com",
    "role": "user"
  }
}

更新用户资料

PATCH /api/user/profile
Content-Type: application/json
Cookie: h3-session=<session-token>

{
  "username": "string",
  "email": "string"
}

请求参数：

参数	类型	必填	说明
username	String	否	新用户名
email	String	否	新邮箱

响应示例：

{
  "code": 200,
  "success": true,
  "msg": "Profile updated successfully",
  "timestamp": 1768562910265,
  "data": {
    "id": "1768562903137-2t6n1yy",
    "username": "newusername",
    "email": "newemail@example.com",
    "role": "user"
  }
}

修改密码

POST /api/user/change-password
Content-Type: application/json
Cookie: h3-session=<session-token>

{
  "currentPassword": "string",
  "newPassword": "string",
  "confirmPassword": "string"
}

请求参数：

参数	类型	必填	说明
currentPassword	String	是	当前密码
newPassword	String	是	新密码（至少 6 字符）
confirmPassword	String	是	确认新密码

响应示例：

{
  "code": 200,
  "success": true,
  "msg": "Password changed successfully",
  "timestamp": 1768562910265
}

删除账户

DELETE /api/user/account
Cookie: h3-session=<session-token>

响应示例：

{
  "code": 200,
  "success": true,
  "msg": "Account deleted successfully",
  "timestamp": 1768562910265
}

项目结构

h3-admin/
├── src/
│   ├── config/              # 配置管理
│   │   ├── constants.ts     # 常量定义
│   │   ├── env.ts          # 环境变量
│   │   └── index.ts       # 配置导出
│   ├── middleware/          # 中间件
│   │   ├── auth.ts         # 认证中间件
│   │   ├── cors.ts         # CORS 中间件
│   │   ├── error.ts        # 错误处理中间件
│   │   ├── logger.ts       # 日志中间件
│   │   ├── rate-limit.ts   # 限流中间件
│   │   ├── session.ts      # 会话中间件
│   │   └── index.ts       # 中间件导出
│   ├── models/             # 数据模型
│   │   ├── session.model.ts # 会话模型
│   │   ├── user.model.ts   # 用户模型
│   │   └── index.ts       # 模型导出
│   ├── repositories/       # 数据访问层
│   │   ├── base.repository.ts  # 基础仓储
│   │   ├── session.repository.ts # 会话仓储
│   │   ├── user.repository.ts   # 用户仓储
│   │   └── index.ts           # 仓储导出
│   ├── routes/             # 路由
│   │   ├── api/
│   │   │   ├── auth/       # 认证路由
│   │   │   ├── user/       # 用户路由
│   │   │   ├── health.ts   # 健康检查
│   │   │   └── index.ts   # 路由聚合
│   │   ├── static.ts       # 静态资源
│   │   └── index.ts       # 路由配置
│   ├── schemas/            # 验证模式
│   │   ├── auth.schema.ts  # 认证验证
│   │   ├── user.schema.ts  # 用户验证
│   │   └── index.ts      # 模式导出
│   ├── services/           # 业务逻辑层
│   │   ├── auth.service.ts # 认证服务
│   │   ├── user.service.ts # 用户服务
│   │   └── index.ts      # 服务导出
│   ├── types/             # 类型定义
│   │   ├── api.ts         # API 类型
│   │   ├── h3.d.ts       # H3 扩展类型
│   │   ├── session.ts     # 会话类型
│   │   └── index.ts      # 类型导出
│   ├── utils/             # 工具函数
│   │   ├── crypto.ts      # 加密工具
│   │   ├── date.ts        # 日期工具
│   │   ├── response.ts    # 响应工具
│   │   └── index.ts      # 工具导出
│   ├── app.ts             # 应用入口
│   └── server.ts         # 服务器启动
├── public/                # 静态资源
│   └── index.html         # 首页
├── docs/                  # 文档
│   └── h3.md            # H3 文档
├── tests/                 # 测试
├── .env.example          # 环境变量示例
├── .gitignore           # Git 忽略配置
├── .prettierrc         # Prettier 配置
├── tsconfig.json        # TypeScript 配置
├── package.json         # 项目配置
├── pnpm-lock.yaml      # 依赖锁定
└── README.md           # 项目文档

开发指南

可用命令

# 启动开发服务器（带热重载）
pnpm run dev

# 启动生产服务器
pnpm run start

# 构建项目
pnpm run build

# 代码格式化
pnpm run format

# 格式检查
pnpm run format:check

# 类型检查
pnpm run typecheck

代码规范

项目遵循以下代码规范：

TypeScript: 严格模式，禁止使用 any 类型
命名规范: 驼峰命名（camelCase）
文件命名: 短横线命名（kebab-case）
注释: JSDoc 风格注释
格式化: Prettier 自动格式化

调试指南

开发模式下，服务器会自动监听文件变化并重新加载。可以通过以下方式调试：

日志输出: 查看控制台日志
断点调试: 使用 VS Code 调试器
API 测试: 使用 Postman 或 curl

部署指南

生产环境准备

环境变量配置

确保在生产环境中设置所有必要的环境变量：

export NODE_ENV=production
export PORT=3001
export SESSION_SECRET=your-production-secret-key

构建项目

pnpm run build

启动服务

pnpm run start

Docker 部署

创建 Dockerfile：

FROM node:18-alpine

WORKDIR /app

COPY package.json pnpm-lock.yaml ./
RUN npm install -g pnpm && pnpm install --frozen-lockfile

COPY . .
RUN pnpm run build

EXPOSE 3001

CMD ["pnpm", "run", "start"]

构建并运行：

docker build -t h3-admin .
docker run -p 3001:3001 --env-file .env h3-admin

云平台部署

项目可以部署到以下平台：

Vercel: 支持无服务器部署
Railway: 支持容器化部署
Render: 支持 Docker 和原生部署
AWS/Azure/GCP: 支持容器和函数部署

最佳实践

安全性

HTTPS: 生产环境必须使用 HTTPS
密钥管理: 使用安全的密钥管理服务
输入验证: 所有输入必须经过验证
密码安全: 使用强密码策略
会话管理: 设置合理的会话过期时间

性能优化

缓存策略: 对频繁访问的数据进行缓存
数据库优化: 使用索引和查询优化
限流保护: 防止 DDoS 攻击
日志管理: 避免过度日志记录

监控告警

健康检查: 定期检查服务状态
错误追踪: 集成错误追踪工具（如 Sentry）
性能监控: 监控响应时间和资源使用
日志聚合: 集中式日志管理

常见问题

Q: 如何更换数据库？

A: 当前使用内存存储，可以通过修改 repositories 层的实现来集成其他数据库（如 MongoDB、PostgreSQL）。

Q: 如何添加新的 API 端点？

A: 在 src/routes/api/ 目录下创建新的路由文件，并在 src/routes/api/index.ts 中注册。

Q: 如何自定义中间件？

A: 在 src/middleware/ 目录下创建新的中间件文件，并在 src/app.ts 中使用。

Q: 生产环境如何配置？

A: 参考部署指南部分，确保设置正确的环境变量和安全配置。

贡献指南

我们欢迎所有形式的贡献！

贡献方式

报告问题: 在 Issues 中提交 Bug 或功能请求
提交代码: Fork 项目并提交 Pull Request
改进文档: 帮助完善文档和示例
分享经验: 在社区分享使用经验

开发流程

Fork 本仓库
创建特性分支 (git checkout -b feature/AmazingFeature)
提交更改 (git commit -m 'Add some AmazingFeature')
推送到分支 (git push origin feature/AmazingFeature)
开启 Pull Request

代码规范

遵循项目的代码风格
添加必要的测试
更新相关文档
确保所有测试通过

许可证

本项目采用 MIT 许可证开源。

联系方式

项目地址: https://github.com/FuntrySun/h3-admin
问题反馈: Issues
讨论交流: Discussions

如果这个项目对你有帮助，请给一个 ⭐️ Star

Made with ❤️ by FuntrySun

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
docs		docs
public		public
src		src
.env.example		.env.example
.gitignore		.gitignore
.prettierrc		.prettierrc
README.md		README.md
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

H3 Admin

目录

项目简介

设计理念

核心特性

认证与授权

用户管理

系统功能

开发体验

技术架构

技术栈

架构设计

分层说明

快速开始

环境要求

安装步骤

配置说明

环境变量

配置文件

API 参考

基础信息

响应格式

健康检查

获取服务状态

认证接口

用户注册

用户登录

用户登出

获取当前用户

用户管理接口

获取用户资料

更新用户资料

修改密码

删除账户

项目结构

开发指南

可用命令

代码规范

调试指南

部署指南

生产环境准备

Docker 部署

云平台部署

最佳实践

安全性

性能优化

监控告警

常见问题

Q: 如何更换数据库？

Q: 如何添加新的 API 端点？

Q: 如何自定义中间件？

Q: 生产环境如何配置？

贡献指南

贡献方式

开发流程

代码规范

许可证

联系方式

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages