Xiaoxia AI
2f55b26bb2
- Create main.py with CORS and GZip middleware - Add Settings class with all configuration options - Support .env file for environment variables - Add health check and root endpoints - Create comprehensive README with quick start guide - Add .env.example template - Include API usage examples and troubleshooting Phase 4 Task 30/68 completed
214 lines
3.9 KiB
Markdown
214 lines
3.9 KiB
Markdown
# 小虾 SaaS - 快速开始指南
|
|
|
|
## 🚀 快速启动
|
|
|
|
### 1. 克隆仓库
|
|
|
|
```bash
|
|
git clone https://gitea.your-server.com/xiaoxia/xiaoxia-saas.git
|
|
cd xiaoxia-saas
|
|
```
|
|
|
|
### 2. 安装依赖
|
|
|
|
```bash
|
|
# Python 依赖
|
|
pip install -r requirements.txt
|
|
|
|
# 或使用虚拟环境
|
|
python -m venv venv
|
|
source venv/bin/activate # Linux/Mac
|
|
# venv\Scripts\activate # Windows
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
### 3. 配置环境变量
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
# 编辑 .env 文件，填写实际配置
|
|
```
|
|
|
|
**必须配置的项：**
|
|
- `DATABASE_URL` - PostgreSQL 连接字符串
|
|
- `JWT_SECRET_KEY` - JWT 密钥（生产环境必须修改）
|
|
- `SMTP_*` - 邮件服务配置（用于发送验证邮件）
|
|
|
|
### 4. 初始化数据库
|
|
|
|
```bash
|
|
# 创建数据库
|
|
psql -U postgres -c "CREATE DATABASE xiaoxia_saas;"
|
|
|
|
# 执行迁移
|
|
psql $DATABASE_URL -f migrations/001_initial_schema.sql
|
|
```
|
|
|
|
### 5. 启动服务
|
|
|
|
```bash
|
|
# 开发环境
|
|
uvicorn apps.api.main:app --reload --host 0.0.0.0 --port 8000
|
|
|
|
# 生产环境
|
|
uvicorn apps.api.main:app --host 0.0.0.0 --port 8000 --workers 4
|
|
```
|
|
|
|
### 6. 访问 API 文档
|
|
|
|
打开浏览器访问：
|
|
- Swagger UI: http://localhost:8000/docs
|
|
- ReDoc: http://localhost:8000/redoc
|
|
|
|
---
|
|
|
|
## 📖 API 使用示例
|
|
|
|
### 注册用户
|
|
|
|
```bash
|
|
curl -X POST http://localhost:8000/api/v1/auth/register \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"email": "user@example.com",
|
|
"password": "SecurePass123",
|
|
"username": "myusername",
|
|
"display_name": "My Name"
|
|
}'
|
|
```
|
|
|
|
### 登录
|
|
|
|
```bash
|
|
curl -X POST http://localhost:8000/api/v1/auth/login \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"email": "user@example.com",
|
|
"password": "SecurePass123"
|
|
}'
|
|
```
|
|
|
|
返回：
|
|
```json
|
|
{
|
|
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
|
|
"refresh_token": "abc123...",
|
|
"token_type": "bearer",
|
|
"user_id": "...",
|
|
"expires_in": 1800
|
|
}
|
|
```
|
|
|
|
### 创建工作空间
|
|
|
|
```bash
|
|
curl -X POST http://localhost:8000/api/v1/workspaces \
|
|
-H "Content-Type: application/json" \
|
|
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
|
|
-d '{
|
|
"name": "我的工作空间",
|
|
"subscription_plan": "free"
|
|
}'
|
|
```
|
|
|
|
---
|
|
|
|
## 🧪 运行测试
|
|
|
|
```bash
|
|
# 运行所有单元测试
|
|
pytest tests/unit -v
|
|
|
|
# 运行集成测试
|
|
pytest tests/integration -v
|
|
|
|
# 生成覆盖率报告
|
|
pytest --cov=packages --cov-report=html
|
|
```
|
|
|
|
---
|
|
|
|
## 📁 项目结构
|
|
|
|
```
|
|
xiaoxia-saas/
|
|
├── apps/
|
|
│ └── api/ # FastAPI 应用
|
|
│ ├── main.py # 应用入口
|
|
│ └── app/
|
|
│ ├── api/routes/ # API 路由
|
|
│ ├── middleware/ # 中间件
|
|
│ └── dependencies.py # 依赖注入
|
|
├── packages/
|
|
│ ├── domain/ # 领域模型
|
|
│ ├── application/ # 用例层
|
|
│ ├── ports/ # 接口定义
|
|
│ └── adapters/ # 适配器实现
|
|
├── migrations/ # 数据库迁移
|
|
├── tests/ # 测试
|
|
└── docs/ # 文档
|
|
```
|
|
|
|
---
|
|
|
|
## 🔧 开发工具
|
|
|
|
### 代码格式化
|
|
|
|
```bash
|
|
# 安装工具
|
|
pip install black isort
|
|
|
|
# 格式化代码
|
|
black packages/ apps/ tests/
|
|
isort packages/ apps/ tests/
|
|
```
|
|
|
|
### 类型检查
|
|
|
|
```bash
|
|
pip install mypy
|
|
mypy packages/ apps/
|
|
```
|
|
|
|
---
|
|
|
|
## 🐳 Docker 部署
|
|
|
|
```bash
|
|
# 构建镜像
|
|
docker build -t xiaoxia-saas:latest .
|
|
|
|
# 运行容器
|
|
docker run -d \
|
|
--name xiaoxia-saas \
|
|
-p 8000:8000 \
|
|
--env-file .env \
|
|
xiaoxia-saas:latest
|
|
```
|
|
|
|
---
|
|
|
|
## 📚 更多文档
|
|
|
|
- [Phase 4 完成总结](docs/PHASE4-COMPLETE.md)
|
|
- [数据库迁移指南](migrations/README.md)
|
|
- [API 设计文档](docs/PHASE4-DESIGN.md)
|
|
|
|
---
|
|
|
|
## 🆘 常见问题
|
|
|
|
### Q: 邮件发送失败？
|
|
A: 检查 SMTP 配置，Gmail 需要使用应用专用密码。
|
|
|
|
### Q: 数据库连接失败？
|
|
A: 确认 PostgreSQL 正在运行，DATABASE_URL 配置正确。
|
|
|
|
### Q: JWT token 无效？
|
|
A: 检查 JWT_SECRET_KEY 是否配置，access_token 是否过期。
|
|
|
|
---
|
|
|
|
**支持联系:** xiaoxia@example.com
|