# Pica Gateway

最小可用的 HTTP 服务：注册 / 登录 + 登录后生成可吊销的 API Key。

## 技术栈

- **FastAPI** + **Uvicorn**：Web 框架
- **SQLAlchemy** + **SQLite**：存储（单文件，零运维）
- **bcrypt**（passlib）：密码哈希
- **python-jose**：JWT 会话签发/校验

## 存储设计

| 数据 | 存储方式 | 说明 |
|---|---|---|
| 用户密码 | bcrypt 哈希 | 永不明文，自带 salt |
| 会话令牌 | JWT（短期，默认 1h） | 不入库；签名密钥在环境变量 |
| API Key 明文 | **只返回一次**给用户 | 库内不存明文 |
| API Key 哈希 | SHA-256，唯一索引 | 校验时 `明文→哈希→查库` |
| JWT 签名密钥 | 环境变量 `JWT_SECRET` | 不入库 |

## 目录结构

```
app/
  config.py     配置（读 .env）
  database.py   引擎 / session / 建表
  models.py     User / ApiKey 模型
  security.py   密码哈希、JWT、API Key 生成
  deps.py       会话鉴权、API Key 鉴权依赖
  schemas.py    Pydantic 请求/响应模型
  routers/
    auth.py     POST /api/auth/register, /login
    apikeys.py  POST /api/keys, GET /api/keys, POST /api/keys/{id}/revoke
  main.py       入口，挂载路由 + /api/me 示例 + 静态页面
static/index.html  单页前端
```

## API

| 方法 | 路径 | 鉴权 | 说明 |
|---|---|---|---|
| POST | `/api/auth/register` | 无 | 注册，返回 JWT |
| POST | `/api/auth/login` | 无 | 登录，返回 JWT |
| POST | `/api/keys` | Bearer JWT | 生成 API Key（明文仅返回一次）|
| GET | `/api/keys` | Bearer JWT | 列出自己的 key（只见前缀）|
| POST | `/api/keys/{id}/revoke` | Bearer JWT | 吊销 key |
| GET | `/api/me` | `X-API-Key` | 示例：用 key 访问的受保护接口 |

## 运行

```bash
python3 -m venv venv && . venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
# 编辑 .env，把 JWT_SECRET 改成随机长串：
python3 -c "import secrets;print(secrets.token_urlsafe(48))"
uvicorn app.main:app --host 0.0.0.0 --port 8000
```

浏览器打开 `http://localhost:8000` 即可注册/登录/生成 key。

## 调用示例

```bash
# 用 API Key 访问受保护接口
curl -H "X-API-Key: pica_xxxxxxxx" http://localhost:8000/api/me
```

## 后续可扩展

- API Key 加过期时间、速率限制
- JWT 刷新令牌（refresh token）
- 换 PostgreSQL（多实例时）
- 给注册加验证码 / 邮箱验证