# web_site

**Repository Path**: makerhao/web_site

## Basic Information

- **Project Name**: web_site
- **Description**: FastAPI搭建的web独立站
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 2
- **Created**: 2025-07-24
- **Last Updated**: 2025-12-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# FastAPI + Vue3 全栈项目

## 📋 项目概述

这是一个基于 FastAPI 和 Vue3 的现代化全栈 Web 应用项目，集成了用户认证、消息管理和智能图像识别功能。项目采用微服务架构，支持 Docker 容器化部署，具备高可用性和可扩展性。

## 🎯 主要特性

- 🔐 **完整的用户认证系统** - JWT Token认证，角色权限管理
- 💬 **实时消息管理** - 用户与管理员双向通信，支持消息回复
- 🖼️ **智能图像识别** - 基于腾讯云TIIA的图像识别和以图搜图功能
- 🐳 **容器化部署** - Docker + Docker Compose 一键部署
- 📊 **RESTful API** - 标准化API设计，完整的Swagger文档
- 🚀 **高性能架构** - FastAPI异步框架 + Redis缓存

## 🛠️ 技术栈

### 后端技术栈

| 技术 | 版本 | 用途 |
|------|------|------|
| FastAPI | 0.104.1 | Web框架 |
| SQLAlchemy | 2.0.23 | ORM框架 |
| MySQL | 8.0 | 主数据库 |
| Redis | 7.0 | 缓存数据库 |
| Alembic | 1.16.1 | 数据库迁移 |
| Pydantic | 2.5.1 | 数据验证 |
| python-jose | 3.5.0 | JWT处理 |
| bcrypt | 4.1.2 | 密码加密 |
| Pillow | 9.5.0 | 图像处理 |
| 腾讯云SDK | - | 云服务集成 |

### 前端技术栈

| 技术 | 版本 | 用途 |
|------|------|------|
| Vue.js | 3.x | 前端框架 |
| Node.js | 18 | 运行环境 |
| Nginx | Alpine | Web服务器 |

### 基础设施

| 技术 | 版本 | 用途 |
|------|------|------|
| Docker | 20.0+ | 容器化 |
| Docker Compose | 2.0+ | 容器编排 |
| 腾讯云COS | - | 对象存储 |
| 腾讯云TIIA | - | 图像识别 |

## 📁 项目结构
plaintext

web_site/├── app/                          # 后端应用代码│   ├── api/                      # API路由层│   │   ├── deps.py              # 依赖注入│   │   └── endpoints/           # API端点│   │       ├── auth.py          # 用户认证API│   │       ├── message.py       # 消息管理API│   │       └── image.py         # 图像识别API│   ├── core/                    # 核心配置│   │   ├── config.py           # 应用配置│   │   ├── database.py         # 数据库配置│   │   └── security.py         # 安全相关│   ├── crud/                    # 数据库操作层│   │   ├── user.py             # 用户CRUD│   │   ├── message.py          # 消息CRUD│   │   └── image.py            # 图像CRUD│   ├── models/                  # 数据模型│   │   ├── user.py             # 用户模型│   │   ├── message.py          # 消息模型│   │   └── image.py            # 图像模型│   ├── schemas/                 # Pydantic模式│   │   ├── user.py             # 用户模式│   │   ├── message.py          # 消息模式│   │   └── image.py            # 图像模式│   ├── services/                # 业务服务层│   │   ├── image/              # 图像处理服务│   │   └── tencent/            # 腾讯云服务│   └── main.py                 # 应用入口├── alembic/                     # 数据库迁移├── .env                        # 环境变量配置├── docker-compose.yml          # Docker编排配置├── Dockerfile                  # 后端Docker配置├── requirements.txt            # Python依赖├── deploy.sh                   # 部署脚本└── restart.sh                  # 重启脚本
🚀 后端项目搭建详细流程
1. 环境准备
1.1 系统要求
操作系统: Linux/macOS/Windows
Python: 3.9+
Docker: 20.0+
Docker Compose: 2.0+
Git: 最新版本
1.2 安装Docker和Docker Compose
macOS (推荐使用Homebrew):

bash
运行
# 安装Docker Desktopbrew install --cask docker# 启动Docker Desktopopen /Applications/Docker.app
Ubuntu/Debian:

bash
运行
# 更新包索引sudo apt update# 安装Dockercurl -fsSL https://get.docker.com -o get-docker.shsudo sh get-docker.sh# 安装Docker Composesudo curl -L "https://github.com/docker/compose/releases/download/v2.20.0/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-composesudo chmod +x /usr/local/bin/docker-compose# 将用户添加到docker组sudo usermod -aG docker $USER
验证安装:

bash
运行
docker --versiondocker-compose --version
2. 项目初始化
2.1 克隆项目
bash
运行
# 克隆项目到本地git clone <your-repository-url>cd web_site# 查看项目结构ls -la
2.2 环境变量配置
bash
运行
# 复制环境变量模板cp .env.example .env# 编辑环境变量文件vim .env
环境变量配置详解 (.env):

bash
运行
# ===========================================# 数据库配置# ===========================================DATABASE_URL=mysql+pymysql://root:your_password@mysql:3306/fastapi_authMYSQL_ROOT_PASSWORD=your_passwordMYSQL_DATABASE=fastapi_auth# ===========================================# Redis配置# ===========================================REDIS_URL=redis://redis:6379/0# ===========================================# JWT安全配置# ===========================================SECRET_KEY=your-super-secret-key-here-change-in-productionALGORITHM=HS256ACCESS_TOKEN_EXPIRE_MINUTES=30# ===========================================# 应用配置# ===========================================APP_NAME=FastAPI认证系统DEBUG=true# ===========================================# 腾讯云配置 (图像识别功能)# ===========================================TENCENT_SECRET_ID=your_tencent_secret_idTENCENT_SECRET_KEY=your_tencent_secret_keyTENCENT_REGION=ap-beijingTENCENT_TIIA_ENDPOINT=tiia.tencentcloudapi.com# ===========================================# 腾讯云COS配置 (对象存储)# ===========================================TENCENT_COS_BUCKET=your-bucket-nameTENCENT_COS_REGION=ap-beijing
3. 本地开发环境搭建
3.1 Python虚拟环境设置
bash
运行
# 创建Python虚拟环境python3 -m venv venv# 激活虚拟环境# macOS/Linux:source venv/bin/activate# Windows:# venv\Scripts\activate# 升级pippip install --upgrade pip# 安装项目依赖pip install -r requirements.txt
3.2 数据库服务启动
bash
运行
# 启动MySQL和Redis服务docker-compose up mysql redis -d# 验证服务状态docker-compose ps# 查看服务日志docker-compose logs mysqldocker-compose logs redis
3.3 数据库初始化
bash
运行
# 等待MySQL完全启动 (约30秒)sleep 30# 运行数据库迁移alembic upgrade head# 验证数据库表创建docker exec -it fastapi_mysql mysql -uroot -p$MYSQL_ROOT_PASSWORD -e "USE fastapi_auth; SHOW TABLES;"
3.4 启动后端服务
bash
运行
# 启动FastAPI开发服务器uvicorn app.main:app --reload --host 0.0.0.0 --port 8000# 或者使用Python模块方式启动python -m uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
4. 服务验证
4.1 API服务验证
bash
运行
# 健康检查curl http://localhost:8000/health# 查看API文档open http://localhost:8000/docs# 查看ReDoc文档open http://localhost:8000/redoc
4.2 数据库连接验证
bash
运行
# 连接MySQL数据库docker exec -it fastapi_mysql mysql -uroot -p$MYSQL_ROOT_PASSWORD# 在MySQL中执行USE fastapi_auth;SHOW TABLES;DESCRIBE users;
4.3 Redis连接验证
bash
运行
# 连接Redisdocker exec -it fastapi_redis redis-cli# 在Redis中执行pinginfo
5. 数据库管理
5.1 创建数据库迁移
bash
运行
# 当修改模型后，创建新的迁移文件alembic revision --autogenerate -m "描述你的更改"# 查看迁移历史alembic history# 查看当前版本alembic current
5.2 执行数据库迁移
bash
运行
# 升级到最新版本alembic upgrade head# 升级到特定版本alembic upgrade <revision_id># 回滚到上一个版本alembic downgrade -1# 回滚到特定版本alembic downgrade <revision_id>
5.3 数据库备份与恢复
bash
运行
# 数据备份./export_to_sql.sh# 数据恢复./import_from_sql.sh# 手动备份docker exec fastapi_mysql mysqldump -uroot -p$MYSQL_ROOT_PASSWORD fastapi_auth > backup_$(date +%Y%m%d_%H%M%S).sql# 手动恢复docker exec -i fastapi_mysql mysql -uroot -p$MYSQL_ROOT_PASSWORD fastapi_auth < backup_file.sql
6. 容器化部署
6.1 完整部署
bash
运行
# 停止本地开发服务# Ctrl+C 停止uvicorn服务# 使用Docker Compose部署所有服务./deploy.sh# 或者手动执行docker-compose downdocker-compose up --build -d
6.2 服务管理
bash
运行
# 查看所有服务状态docker-compose ps# 查看服务日志docker-compose logs -f backenddocker-compose logs -f mysqldocker-compose logs -f redis# 重启特定服务docker-compose restart backend# 快速重启所有服务./restart.sh
6.3 服务访问地址
后端API: http://localhost:9000
API文档: http://localhost:9000/docs
ReDoc文档: http://localhost:9000/redoc
MySQL: localhost:9306
Redis: localhost:9379
7. 开发调试
7.1 日志查看
bash
运行
# 实时查看后端日志docker-compose logs -f backend# 查看最近100行日志docker-compose logs --tail=100 backend# 查看特定时间段日志docker-compose logs --since="2024-01-01T00:00:00" backend
7.2 进入容器调试
bash
运行
# 进入后端容器docker exec -it fastapi_backend bash# 进入MySQL容器docker exec -it fastapi_mysql bash# 进入Redis容器docker exec -it fastapi_redis sh
7.3 性能监控
bash
运行
# 查看容器资源使用情况docker stats# 查看特定容器资源使用docker stats fastapi_backend# 查看容器详细信息docker inspect fastapi_backend
8. 测试
8.1 API测试
bash
运行
# 用户注册测试curl -X POST "http://localhost:9000/api/auth/register" \     -H "Content-Type: application/json" \     -d '{       "username": "testuser",       "email": "test@example.com",       "password": "testpassword123"     }'# 用户登录测试curl -X POST "http://localhost:9000/api/auth/login" \     -H "Content-Type: application/json" \     -d '{       "username": "testuser",       "password": "testpassword123"     }'
8.2 数据库测试
bash
运行
# 检查用户表数据docker exec -it fastapi_mysql mysql -uroot -p$MYSQL_ROOT_PASSWORD -e "SELECT * FROM fastapi_auth.users;"# 检查消息表数据docker exec -it fastapi_mysql mysql -uroot -p$MYSQL_ROOT_PASSWORD -e "SELECT * FROM fastapi_auth.messages;"
9. 故障排除
9.1 常见问题
问题1: 数据库连接失败

bash
运行
# 检查MySQL容器状态docker-compose ps mysql# 查看MySQL日志docker-compose logs mysql# 重启MySQL服务docker-compose restart mysql# 检查端口占用lsof -i :9306
问题2: 后端服务启动失败

bash
运行
# 查看后端日志docker-compose logs backend# 检查Python依赖docker exec -it fastapi_backend pip list# 重新构建镜像docker-compose build backend
问题3: 数据库迁移失败

bash
运行
# 检查迁移状态alembic current# 查看迁移历史alembic history# 强制标记迁移版本alembic stamp head
9.2 清理和重置
bash
运行
# 停止所有服务docker-compose down# 清理所有容器和网络docker-compose down --volumes --remove-orphans# 清理Docker镜像docker system prune -a# 重新开始./deploy.sh
10. 生产环境部署注意事项
10.1 安全配置
bash
运行
# 生产环境必须修改的配置# 1. 修改数据库密码# 2. 修改JWT密钥# 3. 关闭DEBUG模式# 4. 配置HTTPS# 5. 设置防火墙规则
10.2 性能优化
bash
运行
# 1. 配置数据库连接池# 2. 启用Redis持久化# 3. 配置Nginx负载均衡# 4. 设置日志轮转# 5. 监控系统资源
10.3 备份策略
bash
运行
# 设置定时备份crontab -e# 添加以下行 (每天凌晨2点备份)0 2 * * * /path/to/your/project/export_to_sql.sh
📚 API文档
项目启动后，可以通过以下地址访问完整的API文档：

Swagger UI: http://localhost:9000/docs
ReDoc: http://localhost:9000/redoc
🔧 开发工具推荐
IDE: PyCharm Professional / VS Code
API测试: Postman / Insomnia
数据库管理: DBeaver / MySQL Workbench
Redis管理: RedisInsight
容器管理: Docker Desktop
📞 技术支持
如果在搭建过程中遇到问题，请：

查看项目日志: docker-compose logs
检查环境配置: 确认 .env 文件配置正确
参考故障排除章节
提交Issue到项目仓库