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. 安装依赖

npm install

2. 配置环境变量

复制环境变量模板并配置：

cp .env.example .env

编辑 .env 文件配置数据库连接：

DATABASE_URL=postgresql://username:password@localhost:5432/accounts_db
PORT=3000
NODE_ENV=development
LOCK_TIMEOUT_MINUTES=5

3. 数据库设置

初始化数据库：

# 创建数据库（如果不存在）
npm run db:create

# 生成迁移文件
npm run db:generate

# 运行迁移
npm run db:migrate

# 或者一键设置（创建+迁移）
npm run db:setup

4. 启动服务

开发模式：

npm run dev

生产模式：

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

数据库命令

# 生成迁移文件
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文档 - 完整的API接口说明
• 设计文档 - 系统架构和设计理念