weibo_signin/LOCAL_SETUP.md

# 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