cloud370
26d1d391b7
- Add detailed project description and core features - Update quick start guide with db:setup command - Enhance project structure documentation - Add core functionality sections - Link to comprehensive API and design docs - Improve formatting and organization 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
185 lines
4.6 KiB
Markdown
185 lines
4.6 KiB
Markdown
# Accounts Manager
|
|
|
|
轻量化账号管理平台 - 专为自动化脚本和Web管理设计的高性能账号管理系统
|
|
|
|
## 概述
|
|
|
|
Accounts Manager 是一个基于 TypeScript 和 Fastify 构建的轻量级账号管理平台，采用单表设计理念，为自动化脚本和管理后台提供独立优化的 API 接口。系统支持账号的获取、锁定、状态更新、批量管理等功能，并提供完善的统计分析能力。
|
|
|
|
## 核心特性
|
|
|
|
- 🚀 **高性能**: 基于 Fastify 框架，提供极快的 API 响应速度
|
|
- 🔒 **并发安全**: 支持账号锁定机制，防止并发获取同一账号
|
|
- 📊 **统计分析**: 提供详细的账号使用统计和概览数据
|
|
- 🔄 **自动化**: 支持后台任务自动清理超时锁定
|
|
- 🎯 **双API设计**: 为脚本和Web端提供专门优化的API接口
|
|
- 💾 **简化设计**: 单表架构，降低系统复杂性
|
|
- 🛡️ **类型安全**: 完整的 TypeScript 支持和 Zod 数据校验
|
|
|
|
## 技术栈
|
|
|
|
- **运行时**: Node.js (v18+)
|
|
- **语言**: TypeScript
|
|
- **Web框架**: Fastify
|
|
- **数据库**: PostgreSQL (v14+)
|
|
- **ORM**: Drizzle ORM
|
|
- **数据校验**: Zod
|
|
|
|
## 快速开始
|
|
|
|
### 1. 安装依赖
|
|
|
|
```bash
|
|
npm install
|
|
```
|
|
|
|
### 2. 配置环境变量
|
|
|
|
复制环境变量模板并配置：
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
|
|
编辑 `.env` 文件配置数据库连接：
|
|
|
|
```env
|
|
DATABASE_URL=postgresql://username:password@localhost:5432/accounts_db
|
|
PORT=3000
|
|
NODE_ENV=development
|
|
LOCK_TIMEOUT_MINUTES=5
|
|
```
|
|
|
|
### 3. 数据库设置
|
|
|
|
初始化数据库：
|
|
|
|
```bash
|
|
# 创建数据库（如果不存在）
|
|
npm run db:create
|
|
|
|
# 生成迁移文件
|
|
npm run db:generate
|
|
|
|
# 运行迁移
|
|
npm run db:migrate
|
|
|
|
# 或者一键设置（创建+迁移）
|
|
npm run db:setup
|
|
```
|
|
|
|
### 4. 启动服务
|
|
|
|
开发模式：
|
|
```bash
|
|
npm run dev
|
|
```
|
|
|
|
生产模式：
|
|
```bash
|
|
npm run build
|
|
npm start
|
|
```
|
|
|
|
## API 文档
|
|
|
|
### 脚本专用 API
|
|
|
|
**Base URL**: `/s/v1/{ownerId}`
|
|
|
|
#### 1. 获取账号
|
|
- **GET** `/s/v1/{ownerId}/acquire?platform={platform}&count={count}`
|
|
- 获取可用账号并锁定
|
|
|
|
#### 2. 更新账号状态
|
|
- **GET** `/s/v1/{ownerId}/update/{accountId}/{newStatus}?notes={notes}`
|
|
- 更新指定账号状态
|
|
|
|
#### 3. 上传账号
|
|
- **POST** `/s/v1/{ownerId}/upload`
|
|
- 批量创建或更新账号
|
|
|
|
### 前端管理 API
|
|
|
|
**Base URL**: `/web/v1`
|
|
|
|
#### 1. 获取账号列表
|
|
- **POST** `/web/v1/accounts/list`
|
|
- 支持复杂查询、分页、排序
|
|
|
|
#### 2. 批量删除账号
|
|
- **POST** `/web/v1/accounts/delete-batch`
|
|
|
|
#### 3. 批量更新账号
|
|
- **POST** `/web/v1/accounts/update-batch`
|
|
|
|
#### 4. 统计概览
|
|
- **GET** `/web/v1/stats/overview`
|
|
|
|
### 健康检查
|
|
- **GET** `/health`
|
|
|
|
## 数据库命令
|
|
|
|
```bash
|
|
# 生成迁移文件
|
|
npm run db:generate
|
|
|
|
# 运行迁移
|
|
npm run db:migrate
|
|
|
|
# 打开数据库管理界面
|
|
npm run db:studio
|
|
```
|
|
|
|
## 项目结构
|
|
|
|
```
|
|
src/
|
|
├── api/v1/ # API 路由
|
|
│ ├── script/ # 脚本专用API
|
|
│ │ └── actions.ts # 获取、更新、上传账号
|
|
│ └── web/ # Web管理API
|
|
│ ├── accounts.ts # 账号CRUD操作
|
|
│ └── stats.ts # 统计数据
|
|
├── core/ # 核心业务逻辑
|
|
│ └── AccountService.ts # 账号服务
|
|
├── db/ # 数据库相关
|
|
│ ├── index.ts # 数据库连接
|
|
│ └── schema.ts # 表结构定义
|
|
├── jobs/ # 后台任务
|
|
│ └── staleLockCleanup.ts # 锁定清理任务
|
|
├── lib/ # 工具库
|
|
│ └── apiResponse.ts # 统一响应格式
|
|
├── types/ # 类型定义
|
|
│ ├── api.ts # API类型
|
|
│ └── index.ts # 核心类型
|
|
├── scripts/ # 脚本工具
|
|
│ └── createDatabase.ts # 数据库创建
|
|
├── config.ts # 应用配置
|
|
└── index.ts # 应用入口
|
|
```
|
|
|
|
## 核心功能
|
|
|
|
### 账号管理
|
|
- **自动锁定**: 防止并发访问同一账号
|
|
- **状态追踪**: 支持自定义账号状态管理
|
|
- **批量操作**: 支持批量创建、更新、删除账号
|
|
- **智能清理**: 自动释放超时锁定的账号
|
|
|
|
### API 接口
|
|
- **脚本API**: 专为自动化脚本优化的轻量级接口
|
|
- **管理API**: 功能完整的Web管理界面API
|
|
- **统一响应**: 标准化的API响应格式
|
|
- **类型安全**: 完整的TypeScript类型定义
|
|
|
|
### 数据统计
|
|
- **实时概览**: 账号总数、平台分布、状态统计
|
|
- **详细分析**: 多维度数据统计和分析
|
|
- **可视化友好**: 支持前端图表展示
|
|
|
|
## 详细文档
|
|
|
|
- [API文档](./docs/API文档.md) - 完整的API接口说明
|
|
- [设计文档](./docs/设计.md) - 系统架构和设计理念 |