diff --git a/README.md b/README.md index 764ca52..cf663f6 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,155 @@ -# PerToolBoxServer +# 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** 开源协议发布。 diff --git a/backend/main.py b/backend/main.py new file mode 100644 index 0000000..2e24c00 --- /dev/null +++ b/backend/main.py @@ -0,0 +1,146 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +""" +PerToolBox Server - FastAPI 主程序 +Copyright (C) 2024 Sea Network Technology Studio +Author: Canglan +License: AGPL v3 + +API 文档: /api/v1/docs +健康检查: /health +""" + +from contextlib import asynccontextmanager +from fastapi import FastAPI, Depends +from fastapi.middleware.cors import CORSMiddleware +from fastapi.openapi.utils import get_openapi +from sqlalchemy.orm import Session + +from .config import settings +from .database import engine, Base, get_db +from .middleware.logging import log_requests +from .middleware.rate_limit import setup_rate_limit +from .utils.logger import logger +from .routers.v1 import ( + auth_router, user_router, todos_router, + notes_router, tools_router, stats_router +) + + +@asynccontextmanager +async def lifespan(app: FastAPI): + """应用生命周期管理""" + logger.info(f"启动 {settings.APP_NAME} v1.0.0") + logger.info(f"环境: {settings.ENVIRONMENT}") + logger.info(f"调试模式: {settings.DEBUG}") + + # 创建数据库表 + Base.metadata.create_all(bind=engine) + logger.info("数据库表初始化完成") + + yield + + logger.info("应用关闭") + + +app = FastAPI( + title=settings.APP_NAME, + description=""" + ## PerToolBox 个人工具箱 API v1 + + 提供以下功能： + - ✅ 用户认证（手机/邮箱验证码登录） + - ✅ 待办事项管理 + - ✅ 便签本 + - ✅ 密码生成器 + - ✅ 二维码生成 + - ✅ 加密工具箱（哈希、Base64、URL、AES） + - ✅ JSON 校验与格式化 + - ✅ 热度统计（页面访问次数） + + ### 版权信息 + - © 2024 Sea Network Technology Studio + - Author: Canglan + - License: AGPL v3 + """, + version="1.0.0", + docs_url="/api/v1/docs", + redoc_url="/api/v1/redoc", + openapi_url="/api/v1/openapi.json", + lifespan=lifespan +) + +# CORS 配置 +app.add_middleware( + CORSMiddleware, + allow_origins=settings.ALLOWED_ORIGINS, + allow_credentials=True, + allow_methods=["*"], + allow_headers=["*"], +) + +# 限流配置 +setup_rate_limit(app) + +# 日志中间件 +app.middleware("http")(log_requests) + + +# 健康检查 +@app.get("/health") +async def health_check(db: Session = Depends(get_db)): + try: + db.execute("SELECT 1") + return { + "status": "healthy", + "database": "connected", + "version": "1.0.0" + } + except Exception as e: + logger.error(f"健康检查失败: {e}") + return { + "status": "unhealthy", + "database": str(e) + } + + +# 注册路由 +app.include_router(auth_router) +app.include_router(user_router) +app.include_router(todos_router) +app.include_router(notes_router) +app.include_router(tools_router) +app.include_router(stats_router) + + +# 自定义 OpenAPI +def custom_openapi(): + if app.openapi_schema: + return app.openapi_schema + + openapi_schema = get_openapi( + title=settings.APP_NAME, + version="1.0.0", + description=app.description, + routes=app.routes, + ) + + openapi_schema["info"]["x-copyright"] = "Sea Network Technology Studio" + openapi_schema["info"]["x-author"] = "Canglan " + openapi_schema["info"]["x-license"] = "AGPL v3" + + app.openapi_schema = openapi_schema + return app.openapi_schema + + +app.openapi = custom_openapi + + +if __name__ == "__main__": + import uvicorn + uvicorn.run( + "backend.main:app", + host="0.0.0.0", + port=8000, + reload=settings.DEBUG + ) \ No newline at end of file