# username-pool-api

**Repository Path**: northpinguin/username-pool-api

## Basic Information

- **Project Name**: username-pool-api
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 用户名池API服务

独立的用户名池管理API服务,用于提供用户名检查、随机生成和使用标记功能。

## 项目结构

```
username-pool-api/
├── src/
│   ├── app.js              # Express应用主文件
│   ├── routes/
│   │   └── username.js     # 用户名相关路由
│   ├── db/
│   │   └── database.js     # 数据库连接
│   └── middleware/
│       └── errorHandler.js # 错误处理中间件
├── package.json            # 项目依赖
├── Dockerfile             # Docker镜像配置
├── docker-compose.yml     # Docker编排配置
├── nginx.conf             # Nginx配置示例
├── frontend-integration.js # 前端集成脚本
├── deploy.sh              # 部署脚本
├── test.sh                # 测试脚本
├── init-usernames.sh      # 初始化用户名脚本
└── README.md              # 项目文档
```

## 快速开始

### 1. 上传到服务器

将整个 `username-pool-api` 目录上传到服务器:

```bash
# 在本地打包
cd /Users/gongchengtu/code/sql/name_test
tar -czf username-pool-api.tar.gz username-pool-api/

# 上传到服务器
scp username-pool-api.tar.gz ys-zhilian@your-server:/home/ys-zhilian/

# 在服务器上解压
ssh ys-zhilian@your-server
cd ~
tar -xzf username-pool-api.tar.gz
cd username-pool-api
```

### 2. 修改配置

编辑 `docker-compose.yml`,修改数据库路径:

```bash
nano docker-compose.yml
```

找到这一行并修改为实际路径:
```yaml
- /home/ys-zhilian/instance/cockes.sqlite:/data/cockes.sqlite
```

### 3. 部署服务

```bash
# 给脚本添加执行权限
chmod +x deploy.sh test.sh init-usernames.sh

# 执行部署
bash deploy.sh
```

### 4. 测试服务

```bash
# 运行测试
bash test.sh
```

### 5. 初始化用户名池

```bash
# 初始化用户名
bash init-usernames.sh
```

### 6. 配置Nginx

```bash
# 编辑Nginx配置
sudo nano /etc/nginx/sites-available/default
```

将 `nginx.conf` 中的配置添加到你的Nginx配置文件中,记得修改:
- `your-server-ip` 改为实际的IP或域名
- `原端口` 改为主项目的端口

重启Nginx:
```bash
sudo nginx -t
sudo systemctl reload nginx
```

### 7. 前端集成

有两种方式集成前端:

**方式1: 作为独立JS文件**
```html
<!-- 在 login.html 的 </body> 前添加 -->
<script src="/path/to/frontend-integration.js"></script>
```

**方式2: 直接嵌入HTML**
将 `frontend-integration.js` 的内容复制到 `<script>` 标签中。

## API接口说明

### 1. 健康检查
```
GET /health
```

### 2. 检查用户名
```
POST /api/username/check
Body: {"username": "testuser"}
```

### 3. 获取随机用户名
```
GET /api/username/random
```

### 4. 标记用户名已使用
```
POST /api/username/mark-used
Body: {"username": "testuser", "user_id": 123}
```

### 5. 批量添加用户名
```
POST /api/username/batch-add
Body: {"usernames": ["user1", "user2", "user3"]}
```

### 6. 获取统计信息
```
GET /api/username/stats
```

## 前端使用示例

```javascript
// 检查用户名
const result = await window.UsernamePoolAPI.checkUsername('testuser');
console.log(result); // {exists: false, available: true, username: "testuser"}

// 获取随机用户名 (会自动填充到输入框)
await window.UsernamePoolAPI.getRandomUsername();

// 注册成功后标记用户名
window.UsernamePoolAPI.onRegisterSuccess({
    id: userId,
    username: username
});
```

## 常用命令

```bash
# 查看日志
docker-compose logs -f

# 停止服务
docker-compose down

# 重启服务
docker-compose restart

# 查看服务状态
docker-compose ps

# 重新构建
docker-compose up -d --build

# 进入容器
docker-compose exec username-pool-api sh
```

## 故障排查

### 服务无法启动
1. 检查数据库路径是否正确
2. 检查端口5001是否被占用: `lsof -i :5001`
3. 查看日志: `docker-compose logs`

### 前端调用失败
1. 检查Nginx配置是否正确
2. 测试API是否可访问: `curl http://localhost:5001/health`
3. 检查浏览器控制台错误信息

### 数据库连接失败
1. 确认数据库文件存在
2. 检查Docker volume挂载是否正确
3. 确认文件权限: `ls -l /path/to/cockes.sqlite`

## 安全建议

1. 生产环境建议为 `/api/username/batch-add` 接口添加认证
2. 配置防火墙规则,限制5001端口访问(使用Nginx代理时)
3. 定期备份SQLite数据库
4. 监控API调用频率,防止滥用

## License

MIT