mirror of
https://github.com/Cccc-owo/CheckInApp.git
synced 2026-06-17 14:06:28 +00:00
260 lines
7.1 KiB
Markdown
260 lines
7.1 KiB
Markdown
# 接龙自动打卡系统 - 后端 API
|
||
|
||
FastAPI 后端服务，提供用户管理、QQ 扫码登录、自动打卡等功能。
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 1. 安装依赖
|
||
|
||
```bash
|
||
cd backend
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
### 2. 配置环境
|
||
|
||
创建 `.env` 文件（可选）：
|
||
|
||
```env
|
||
# 邮件通知配置（可选）
|
||
SMTP_SERVER=smtp.example.com
|
||
SMTP_PORT=465
|
||
SMTP_SENDER_EMAIL=your-email@example.com
|
||
SMTP_SENDER_PASSWORD=your-password-here
|
||
|
||
# Chrome 浏览器配置（可选）
|
||
CHROME_BINARY_PATH=
|
||
CHROMEDRIVER_PATH=
|
||
```
|
||
|
||
### 3. 初始化数据库
|
||
|
||
数据库会在首次启动时自动初始化。
|
||
|
||
### 4. 创建管理员用户
|
||
|
||
```bash
|
||
python backend/scripts/create_admin.py
|
||
```
|
||
|
||
按照提示输入管理员信息：
|
||
- Signature: 管理员标识（唯一）
|
||
- ThreadId: 接龙 ID
|
||
- 邮箱: 接收通知的邮箱
|
||
|
||
### 5. 启动服务
|
||
|
||
```bash
|
||
# 开发模式（支持热重载）
|
||
cd backend
|
||
python main.py
|
||
|
||
# 或者使用 uvicorn
|
||
uvicorn backend.main:app --reload --host 0.0.0.0 --port 8000
|
||
|
||
# 生产模式
|
||
uvicorn backend.main:app --host 0.0.0.0 --port 8000 --workers 4
|
||
```
|
||
|
||
### 6. 访问 API 文档
|
||
|
||
启动后访问: http://localhost:8000/docs
|
||
|
||
## 📁 项目结构
|
||
|
||
```
|
||
backend/
|
||
├── main.py # FastAPI 应用入口
|
||
├── config.py # 配置管理
|
||
├── dependencies.py # 认证中间件
|
||
├── requirements.txt # Python 依赖
|
||
├── models/ # 数据库模型
|
||
│ ├── database.py # 数据库配置
|
||
│ ├── user.py # User 模型
|
||
│ └── check_in_record.py # CheckInRecord 模型
|
||
├── schemas/ # Pydantic Schema
|
||
│ ├── user.py # 用户相关 Schema
|
||
│ ├── auth.py # 认证相关 Schema
|
||
│ └── check_in.py # 打卡相关 Schema
|
||
├── api/ # API 路由
|
||
│ ├── auth.py # 认证 API
|
||
│ ├── users.py # 用户管理 API
|
||
│ ├── check_in.py # 打卡 API
|
||
│ └── admin.py # 管理员 API
|
||
├── services/ # 业务逻辑层
|
||
│ ├── auth_service.py # 认证服务
|
||
│ ├── user_service.py # 用户服务
|
||
│ ├── check_in_service.py # 打卡服务
|
||
│ └── scheduler_service.py # 调度服务
|
||
├── workers/ # Selenium 工作模块
|
||
│ ├── token_refresher.py # Token 刷新（QQ 扫码）
|
||
│ ├── check_in_worker.py # 打卡执行
|
||
│ └── email_notifier.py # 邮件通知
|
||
└── scripts/ # 工具脚本
|
||
└── create_admin.py # 创建管理员用户
|
||
```
|
||
|
||
## 🔌 API 端点
|
||
|
||
### 认证 API (`/api/auth`)
|
||
|
||
- `POST /api/auth/request_qrcode` - 请求 QQ 扫码二维码
|
||
- `GET /api/auth/qrcode_status/{session_id}` - 检查扫码状态
|
||
- `POST /api/auth/verify_token` - 验证 Token 有效性
|
||
|
||
### 用户 API (`/api/users`)
|
||
|
||
- `POST /api/users` - 创建用户（管理员）
|
||
- `GET /api/users/me` - 获取当前用户信息
|
||
- `GET /api/users/me/token_status` - 获取 Token 状态
|
||
- `GET /api/users` - 获取所有用户（管理员）
|
||
- `GET /api/users/{user_id}` - 获取指定用户
|
||
- `PUT /api/users/{user_id}` - 更新用户信息
|
||
- `DELETE /api/users/{user_id}` - 删除用户（管理员）
|
||
|
||
### 打卡 API (`/api/check_in`)
|
||
|
||
- `POST /api/check_in/manual` - 手动触发打卡
|
||
- `GET /api/check_in/my_records` - 查看自己的打卡记录
|
||
- `GET /api/check_in/records` - 查看所有打卡记录（管理员）
|
||
- `GET /api/check_in/records/count` - 获取打卡记录统计（管理员）
|
||
|
||
### 管理员 API (`/api/admin`)
|
||
|
||
- `POST /api/admin/batch_toggle_active` - 批量启用/禁用用户
|
||
- `POST /api/admin/batch_check_in` - 批量触发打卡
|
||
- `GET /api/admin/logs` - 获取系统日志
|
||
- `GET /api/admin/stats` - 获取系统统计
|
||
|
||
## ⚙️ 配置说明
|
||
|
||
### 邮件配置 (`config.ini`)
|
||
|
||
在项目根目录创建 `config.ini`：
|
||
|
||
```ini
|
||
[Email]
|
||
smtpserver = smtp.example.com
|
||
smtpport = 465
|
||
senderemail = your-email@example.com
|
||
senderpassword = your-password
|
||
```
|
||
|
||
### 定时任务配置
|
||
|
||
在 `backend/config.py` 中配置：
|
||
|
||
- `CHECKIN_SCHEDULE_HOUR`: 定时打卡小时（默认 20）
|
||
- `CHECKIN_SCHEDULE_MINUTE`: 定时打卡分钟（默认 0）
|
||
- `TOKEN_CHECK_INTERVAL_MINUTES`: Token 检查间隔（默认 30 分钟）
|
||
- `SESSION_CLEANUP_INTERVAL_HOURS`: 会话清理间隔（默认 24 小时）
|
||
|
||
## 🔐 认证流程
|
||
|
||
1. 用户输入 Signature 并请求二维码
|
||
2. 后端启动 Selenium 获取 QQ 登录二维码
|
||
3. 前端轮询检查扫码状态
|
||
4. 用户使用手机 QQ 扫码
|
||
5. 后端获取 Token 并解析 JWT
|
||
6. 用户后续请求使用 `Authorization: Bearer <token>` header
|
||
|
||
## 📊 定时任务
|
||
|
||
系统会自动执行以下定时任务：
|
||
|
||
1. **定时打卡**: 每天 20:00 为所有启用的用户执行打卡
|
||
2. **Token 过期检查**: 每 30 分钟检查一次，Token 在 30 分钟内过期时发送邮件提醒
|
||
3. **会话文件清理**: 每 24 小时清理超过 24 小时的旧会话文件
|
||
|
||
## 🛠️ 开发说明
|
||
|
||
### 添加新的 API 端点
|
||
|
||
1. 在 `backend/schemas/` 中定义请求/响应 Schema
|
||
2. 在 `backend/services/` 中实现业务逻辑
|
||
3. 在 `backend/api/` 中创建 API 路由
|
||
4. 在 `backend/main.py` 中注册路由
|
||
|
||
### 数据库迁移
|
||
|
||
如果修改了模型，删除 `data/checkin.db` 并重启服务即可重新创建数据库。
|
||
|
||
⚠️ 注意：生产环境建议使用 Alembic 进行数据库迁移。
|
||
|
||
## 🐛 故障排查
|
||
|
||
### 问题：无法启动 Selenium
|
||
|
||
确保已安装 Chrome 和 ChromeDriver：
|
||
|
||
```bash
|
||
# 检查路径配置
|
||
ls chrome-linux64/chrome
|
||
ls chromedriver
|
||
```
|
||
|
||
### 问题：Token 验证失败
|
||
|
||
检查数据库中用户的 `authorization` 字段是否有值。
|
||
|
||
### 问题：定时任务未执行
|
||
|
||
检查日志文件 `logs/CheckIn.log`，确认调度器是否成功启动。
|
||
|
||
### 问题：邮件发送失败
|
||
|
||
检查 `config.ini` 配置是否正确，SMTP 服务器是否可访问。
|
||
|
||
## 📝 环境变量
|
||
|
||
可选的环境变量：
|
||
|
||
- `DATABASE_URL`: 数据库 URL（默认使用 SQLite）
|
||
- `CORS_ORIGINS`: 允许的前端域名（默认 localhost:5173 和 localhost:3000）
|
||
- `SMTP_SERVER`: 邮件服务器地址（用于邮件通知，可选）
|
||
- `SMTP_SENDER_EMAIL`: 发件人邮箱（用于邮件通知，可选）
|
||
- `CHROME_BINARY_PATH`: Chrome 浏览器路径（可选，留空自动检测）
|
||
- `CHROMEDRIVER_PATH`: ChromeDriver 路径（可选，留空自动下载）
|
||
|
||
## 🚀 部署建议
|
||
|
||
### 使用 Gunicorn
|
||
|
||
```bash
|
||
pip install gunicorn
|
||
gunicorn backend.main:app -w 4 -k uvicorn.workers.UvicornWorker -b 0.0.0.0:8000
|
||
```
|
||
|
||
### 使用 Systemd
|
||
|
||
创建 `/etc/systemd/system/checkin-api.service`：
|
||
|
||
```ini
|
||
[Unit]
|
||
Description=CheckIn API Service
|
||
After=network.target
|
||
|
||
[Service]
|
||
Type=simple
|
||
User=your-user
|
||
WorkingDirectory=/path/to/CheckInApp
|
||
Environment="PATH=/path/to/venv/bin"
|
||
ExecStart=/path/to/venv/bin/gunicorn backend.main:app -w 4 -k uvicorn.workers.UvicornWorker -b 0.0.0.0:8000
|
||
Restart=always
|
||
|
||
[Install]
|
||
WantedBy=multi-user.target
|
||
```
|
||
|
||
启动服务：
|
||
|
||
```bash
|
||
sudo systemctl enable checkin-api
|
||
sudo systemctl start checkin-api
|
||
sudo systemctl status checkin-api
|
||
```
|
||
|
||
## 📄 许可证
|
||
|
||
本项目仅供学习和研究使用。
|