# funlogin

**Repository Path**: farfarfun/funlogin

## Basic Information

- **Project Name**: funlogin
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-31
- **Last Updated**: 2026-10-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# funlogin

用户注册、登录（JWT）、QQ/微信/手机绑定的 FastAPI 公共包。

## 安装

标准流程使用 `uv`：

```bash
uv venv
uv sync
```

也可用 `pip` 作为兼容方式（非推荐）：

```bash
pip install -e .
```

核心依赖只包含 SQLite（`aiosqlite`）支持。按需追加 extras：

```bash
uv sync --extra postgres    # PostgreSQL（asyncpg）
uv sync --extra mysql       # MySQL（aiomysql）
uv sync --extra sms-aliyun  # 阿里云短信验证码
```

## 配置

通过环境变量（前缀 `FUNLOGIN_`）或 `.env` 配置：

| 变量 | 说明 | 默认 |
|------|------|------|
| `FUNLOGIN_DATABASE_URL` | 数据库连接 | `sqlite+aiosqlite:///./funlogin.db` |
| `FUNLOGIN_JWT_SECRET` | JWT 密钥，**必填，无默认值**，未配置启动即失败 | 无（出于安全考虑不提供固定默认值） |
| `FUNLOGIN_JWT_ALGORITHM` | JWT 算法 | `HS256` |
| `FUNLOGIN_JWT_ACCESS_EXPIRE` | Access Token 过期秒数 | `3600` |
| `FUNLOGIN_JWT_REFRESH_EXPIRE` | Refresh Token 过期秒数 | `604800` |
| `FUNLOGIN_QQ_APP_ID` | QQ 互联 AppID | |
| `FUNLOGIN_QQ_APP_KEY` | QQ 互联 AppKey | |
| `FUNLOGIN_WECHAT_APP_ID` | 微信开放平台 AppID | |
| `FUNLOGIN_WECHAT_APP_SECRET` | 微信开放平台 Secret | |
| `FUNLOGIN_ALIYUN_ACCESS_KEY` | 阿里云 AccessKey | |
| `FUNLOGIN_ALIYUN_SECRET` | 阿里云 Secret | |
| `FUNLOGIN_ALIYUN_SMS_SIGN` | 短信签名 | |
| `FUNLOGIN_ALIYUN_SMS_TEMPLATE` | 短信模板 | |
| `FUNLOGIN_SMS_LOCAL_MODE` | 仅开发/测试时允许本地保存验证码；生产环境必须保持关闭 | `false` |
| `FUNLOGIN_CORS_ORIGINS` | 允许跨域的来源，逗号分隔 | `http://127.0.0.1,http://localhost` |

启动开发服务前请显式设置 JWT 密钥；示例中的本地短信模式仅用于没有阿里云凭据时联调，不能用于生产：

```bash
export FUNLOGIN_JWT_SECRET="$(openssl rand -hex 32)"
export FUNLOGIN_SMS_LOCAL_MODE=true
```

生产环境须通过受控环境变量或 `funsecret` 提供唯一的 `FUNLOGIN_JWT_SECRET`，并配置
`FUNLOGIN_ALIYUN_ACCESS_KEY`、`FUNLOGIN_ALIYUN_SECRET`、`FUNLOGIN_ALIYUN_SMS_SIGN` 和
`FUNLOGIN_ALIYUN_SMS_TEMPLATE`；未配置短信凭据时，发码请求会失败。

## 快速集成

```python
from fastapi import FastAPI
from funlogin import router
from funlogin.core.response import setup_exception_handlers

app = FastAPI()
setup_exception_handlers(app)
app.include_router(router, prefix="/api")

# 运行: uvicorn your_app:app
```

## API 接口（三方调用参考）

挂载后基础路径为 `/api`，以下接口均已联调通过。

**统一响应格式：**

```json
{"code": 0, "data": {...}, "message": "ok"}
```

| code | 含义 |
|------|------|
| 0 | 成功 |
| 40001 | 业务错误（如用户名已存在） |
| 40101 | 未登录 / Token 无效 |
| 40301 | 禁止访问 |
| 50001 | 服务端内部错误 |

**需登录接口**：请求头加 `Authorization: Bearer <access_token>`。

---

### 认证 Auth

| 方法 | 路径 | 请求体 | 响应 data 示例 |
|------|------|--------|----------------|
| POST | `/api/auth/send-code` | `{"phone": "13800138000"}` | 无 |
| POST | `/api/auth/register` | `{"username": "alice", "password": "123456"}` 或 `{"email": "a@x.com", "password": "p"}` 或 `{"phone": "138...", "code": "123456"}` | `{"user_id": 1}` |
| POST | `/api/auth/login` | 同 register，二选一 | `{"access_token": "...", "refresh_token": "..."}` |
| GET | `/api/auth/me` | 无（需 JWT） | `{"user_id": 1, "role": 1, "username": "alice", "email": null, "phone": null, "created_at": "...", "updated_at": "..."}` |
| POST | `/api/auth/refresh` | `{"refresh_token": "..."}` | `{"access_token": "...", "refresh_token": "..."}` |
| PATCH | `/api/auth/role` | `{"role": 1}`（需 JWT） | `{"user_id": 1, "role": 1}` |

---

### 绑定 Bind（需 JWT）

| 方法 | 路径 | 请求体 / 参数 | 响应 data 示例 |
|------|------|---------------|----------------|
| POST | `/api/bind/phone/send-code` | `{"phone": "13800138000"}` | 无 |
| POST | `/api/bind/phone` | `{"phone": "138...", "code": "123456"}` | 无 |
| GET | `/api/bind/qq/authorize` | Query: `redirect_uri=https://...` | `{"url": "...", "state": "..."}` |
| POST | `/api/bind/qq/callback` | `{"code": "...", "redirect_uri": "..."}` | 无 |
| GET | `/api/bind/wechat/authorize` | Query: `redirect_uri=https://...` | `{"url": "...", "state": "..."}` |
| POST | `/api/bind/wechat/callback` | `{"code": "..."}` | 无 |
| GET | `/api/bind/list` | 无 | `{"phone": ["138..."], "qq": [...], "wechat": [...]}` |

---

完整 OpenAPI 3.1 描述见 [docs/openapi.json](docs/openapi.json)，可用于生成客户端或 Mock。

## 数据库

示例应用启动时会自动创建表。若自行集成，在应用启动时调用一次 `await funlogin.core.database.init_db()` 即可建表。

**User 表 `role` 字段**：`int` 类型，默认 1，由使用方定义枚举值（如 1=普通用户、2=管理员），用于权限控制。若升级前已有数据库，需删库重建或手动 `ALTER TABLE users ADD COLUMN role INTEGER DEFAULT 1`。

## 示例服务

`example/` 下提供一个可直接运行的演示后端 + 静态测试前端，通过
`scripts/setup.sh` 统一管理启停（用法见 [example/README.md](example/README.md)）：

```bash
./scripts/setup.sh run backend dev
./scripts/setup.sh run frontend dev
```

## 开发

```bash
uv sync --extra test
uv run pytest -v
```

也可用 `pip` 作为兼容方式（非推荐）：

```bash
pip install -e ".[test]"
pytest -v
```

---

## 关于 farfarfun

[farfarfun](https://github.com/farfarfun) 是一个专注于实用工具库的开源组织，
涵盖云存储、数据处理、AI、多媒体与开发工具链等方向。

- 🏠 组织主页：<https://github.com/farfarfun>
- 📦 PyPI：<https://pypi.org/user/niuliangtao/>
- 📧 联系：farfarfun@qq.com

本项目基于 [MIT](LICENSE) 协议开源。