# PerToolBox Server - 后端服务

> 个人工具箱后端 API，基于 FastAPI + MySQL + Redis

---

## 📄 版权信息

* **版权所有**: Sea Network Technology Studio
* **权利人**: Canglan
* **联系方式**: [admin@sea-studio.top](mailto:admin@sea-studio.top)
* **开源协议**: AGPL v3

---

## 🚀 功能特性

* ✅ 用户认证（手机 / 邮箱验证码登录）
* ✅ 待办事项管理
* ✅ 便签本
* ✅ 密码生成器
* ✅ 二维码生成
* ✅ 加密工具箱（哈希、Base64、URL、AES）
* ✅ JSON 校验与格式化
* ✅ 热度统计（页面访问次数）

---

## 🧰 环境要求

| 组件     | 版本要求 |
| ------ | ---- |
| Python | 3.12 |
| MySQL  | 5.7  |
| Redis  | 7.x  |

---

## ⚡ 快速开始

### 1️⃣ 克隆代码

```bash
git clone https://hz-gitea.sea-studio.top/yourname/PerToolBoxServer.git
cd PerToolBoxServer
```

### 2️⃣ 创建虚拟环境

```bash
python3.12 -m venv venv
source venv/bin/activate
```

### 3️⃣ 安装依赖

```bash
pip install -r requirements.txt
```

### 4️⃣ 配置环境变量

```bash
cp .env.example .env
```

编辑 `.env` 文件，填写数据库、Redis、短信等配置

### 5️⃣ 初始化数据库

```bash
mysql -u root -p < scripts/init_db.sql
```

### 6️⃣ 启动服务

```bash
uvicorn backend.main:app --host 0.0.0.0 --port 8000 --reload
```

### 7️⃣ 访问 API 文档

```
http://localhost:8000/api/v1/docs
```

---

## ⚙️ 部署（systemd）

### 创建服务文件

路径：`/etc/systemd/system/pertoolbox.service`

```ini
[Unit]
Description=PerToolBox Backend
After=network.target

[Service]
User=www-data
Group=www-data
WorkingDirectory=/opt/PerToolBoxServer
ExecStart=/opt/PerToolBoxServer/venv/bin/gunicorn backend.main:app \
    -w 4 \
    -k uvicorn.workers.UvicornWorker \
    --bind 127.0.0.1:8000
Restart=always

[Install]
WantedBy=multi-user.target
```

### 启动服务

```bash
sudo systemctl daemon-reexec
sudo systemctl daemon-reload
sudo systemctl enable pertoolbox
sudo systemctl start pertoolbox
```

### 查看状态

```bash
sudo systemctl status pertoolbox
```

---

## 📡 API 端点

| 模块 | 端点                          | 说明          |
| -- | --------------------------- | ----------- |
| 认证 | `/api/v1/auth/*`            | 注册、登录、发送验证码 |
| 用户 | `/api/v1/user/*`            | 个人信息        |
| 待办 | `/api/v1/todos/*`           | 待办事项 CRUD   |
| 便签 | `/api/v1/notes/*`           | 便签 CRUD     |
| 工具 | `/api/v1/password/generate` | 密码生成        |
| 工具 | `/api/v1/qrcode/generate`   | 二维码生成       |
| 工具 | `/api/v1/crypto/*`          | 加密工具        |
| 工具 | `/api/v1/json/validate`     | JSON 校验     |
| 统计 | `/api/v1/tool/stats`        | 热度统计        |

---

## 🔧 配置说明

详见 `.env.example` 文件。

---

## 📜 许可证

本项目基于 **AGPL v3** 开源协议发布。