254 lines
5.4 KiB
Markdown
254 lines
5.4 KiB
Markdown
# Weibo-HotSign 本地开发环境配置指南
|
||
|
||
## 快速开始
|
||
|
||
### 1. 环境要求
|
||
|
||
- Python 3.8+
|
||
- Windows 操作系统
|
||
- （可选）Redis（如果需要完整功能）
|
||
|
||
### 2. 一键启动
|
||
|
||
```bash
|
||
# 双击运行或在命令行执行
|
||
start_all.bat
|
||
```
|
||
|
||
这个脚本会自动：
|
||
- 检查 Python 环境
|
||
- 创建 SQLite 数据库（包含测试用户）
|
||
- 安装所有依赖
|
||
- 启动所有服务
|
||
|
||
### 3. 访问应用
|
||
|
||
启动成功后，浏览器会自动打开：
|
||
- **前端界面**: http://localhost:5000
|
||
- **API Service**: http://localhost:8000
|
||
- **Auth Service**: http://localhost:8001
|
||
|
||
### 4. 测试账号
|
||
|
||
数据库初始化时会自动创建一个测试用户：
|
||
|
||
```
|
||
用户名: admin
|
||
邮箱: admin@example.com
|
||
密码: Admin123!
|
||
```
|
||
|
||
你也可以通过注册页面创建新用户。
|
||
|
||
### 5. 停止服务
|
||
|
||
```bash
|
||
# 双击运行或在命令行执行
|
||
stop_all.bat
|
||
```
|
||
|
||
## 配置说明
|
||
|
||
### 数据库配置
|
||
|
||
默认使用 SQLite 数据库，无需额外配置。数据库文件位于项目根目录：
|
||
```
|
||
weibo_hotsign.db
|
||
```
|
||
|
||
如需使用 MySQL，修改 `backend/.env.local`：
|
||
```env
|
||
DATABASE_URL=mysql+aiomysql://user:password@localhost/weibo_hotsign
|
||
```
|
||
|
||
### Redis 配置（可选）
|
||
|
||
本地开发默认**不需要 Redis**，系统会使用内存存储。
|
||
|
||
如需启用 Redis（用于生产环境或测试分布式功能），修改 `backend/.env.local`：
|
||
```env
|
||
USE_REDIS=true
|
||
REDIS_URL=redis://localhost:6379
|
||
```
|
||
|
||
### 环境变量
|
||
|
||
#### 后端配置 (`backend/.env.local`)
|
||
|
||
```env
|
||
# 数据库
|
||
DATABASE_URL=sqlite+aiosqlite:///./weibo_hotsign.db
|
||
|
||
# Redis（可选）
|
||
USE_REDIS=false
|
||
# REDIS_URL=redis://localhost:6379
|
||
|
||
# JWT 配置
|
||
JWT_SECRET_KEY=dev-secret-key-change-in-production
|
||
JWT_ALGORITHM=HS256
|
||
JWT_ACCESS_TOKEN_EXPIRE_MINUTES=60
|
||
|
||
# Cookie 加密密钥
|
||
COOKIE_ENCRYPTION_KEY=dev-cookie-encryption-key-32b
|
||
|
||
# 服务端口
|
||
AUTH_SERVICE_PORT=8001
|
||
API_SERVICE_PORT=8000
|
||
|
||
# 环境
|
||
ENVIRONMENT=development
|
||
```
|
||
|
||
#### 前端配置 (`frontend/.env`)
|
||
|
||
```env
|
||
FLASK_ENV=development
|
||
FLASK_DEBUG=True
|
||
SECRET_KEY=dev-flask-secret-key-change-in-production
|
||
|
||
# 后端服务地址
|
||
API_BASE_URL=http://localhost:8000
|
||
AUTH_BASE_URL=http://localhost:8001
|
||
|
||
# Session 配置
|
||
SESSION_TYPE=filesystem
|
||
```
|
||
|
||
## 手动启动（高级）
|
||
|
||
如果需要单独启动某个服务：
|
||
|
||
### 1. 创建数据库
|
||
|
||
```bash
|
||
python create_sqlite_db.py
|
||
```
|
||
|
||
### 2. 安装后端依赖
|
||
|
||
```bash
|
||
cd backend
|
||
python -m venv venv
|
||
venv\Scripts\activate
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
### 3. 启动 Auth Service
|
||
|
||
```bash
|
||
cd backend
|
||
venv\Scripts\activate
|
||
set PYTHONPATH=%CD%
|
||
python -m uvicorn auth_service.app.main:app --host 0.0.0.0 --port 8001 --reload
|
||
```
|
||
|
||
### 4. 启动 API Service
|
||
|
||
```bash
|
||
cd backend
|
||
venv\Scripts\activate
|
||
set PYTHONPATH=%CD%
|
||
python -m uvicorn api_service.app.main:app --host 0.0.0.0 --port 8000 --reload
|
||
```
|
||
|
||
### 5. 启动 Frontend
|
||
|
||
```bash
|
||
cd frontend
|
||
python -m venv venv
|
||
venv\Scripts\activate
|
||
pip install -r requirements.txt
|
||
python app.py
|
||
```
|
||
|
||
## 常见问题
|
||
|
||
### Q: 启动失败，提示找不到模块
|
||
|
||
A: 确保设置了 PYTHONPATH：
|
||
```bash
|
||
set PYTHONPATH=%CD%
|
||
```
|
||
|
||
### Q: 数据库连接失败
|
||
|
||
A: 检查 `backend/.env.local` 中的 `DATABASE_URL` 配置是否正确。
|
||
|
||
### Q: 端口被占用
|
||
|
||
A: 修改 `.env` 文件中的端口配置，或关闭占用端口的程序。
|
||
|
||
### Q: Redis 连接失败
|
||
|
||
A: 本地开发不需要 Redis。如果看到 Redis 警告，可以忽略，系统会自动使用内存存储。
|
||
|
||
### Q: 如何重置数据库
|
||
|
||
A: 删除 `weibo_hotsign.db` 文件，然后重新运行 `python create_sqlite_db.py`。
|
||
|
||
## 开发建议
|
||
|
||
### 1. 使用虚拟环境
|
||
|
||
每个服务都应该在独立的虚拟环境中运行，避免依赖冲突。
|
||
|
||
### 2. 查看日志
|
||
|
||
每个服务启动时会打开独立的命令行窗口，可以在窗口中查看实时日志。
|
||
|
||
### 3. 热重载
|
||
|
||
开发模式下，修改代码后服务会自动重启（`--reload` 参数）。
|
||
|
||
### 4. API 文档
|
||
|
||
- Auth Service: http://localhost:8001/docs
|
||
- API Service: http://localhost:8000/docs
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
weibo-hotsign/
|
||
├── backend/ # 后端服务
|
||
│ ├── shared/ # 共享模块
|
||
│ ├── auth_service/ # 认证服务
|
||
│ ├── api_service/ # API 服务
|
||
│ ├── task_scheduler/ # 任务调度（需要 Celery）
|
||
│ ├── signin_executor/ # 签到执行（需要 Celery）
|
||
│ └── requirements.txt # 后端依赖
|
||
├── frontend/ # Flask 前端
|
||
│ ├── templates/ # HTML 模板
|
||
│ ├── app.py # Flask 应用
|
||
│ └── requirements.txt # 前端依赖
|
||
├── weibo_hotsign.db # SQLite 数据库（自动生成）
|
||
├── create_sqlite_db.py # 数据库初始化脚本
|
||
├── init-db-sqlite.sql # SQLite 建表脚本
|
||
├── start_all.bat # 一键启动脚本
|
||
├── stop_all.bat # 停止所有服务
|
||
└── LOCAL_SETUP.md # 本文档
|
||
```
|
||
|
||
## 生产环境部署
|
||
|
||
生产环境建议：
|
||
- 使用 MySQL 数据库
|
||
- 启用 Redis
|
||
- 使用 Nginx 反向代理
|
||
- 使用 Docker Compose 部署
|
||
- 配置 HTTPS
|
||
- 修改所有默认密钥
|
||
|
||
参考 `docker-compose.yml` 进行容器化部署。
|
||
|
||
## 技术栈
|
||
|
||
- **后端**: Python 3.11 + FastAPI + SQLAlchemy (async)
|
||
- **前端**: Flask + Jinja2 + 原生 CSS
|
||
- **数据库**: SQLite (开发) / MySQL (生产)
|
||
- **缓存**: 内存 (开发) / Redis (生产)
|
||
- **任务队列**: Celery + Redis (可选)
|
||
|
||
## 许可证
|
||
|
||
MIT
|