# LobsterAPI

**Repository Path**: kakake/lobsterapi

## Basic Information

- **Project Name**: LobsterAPI
- **Description**: 提供给Skill调用的API
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-30
- **Last Updated**: 2026-04-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🦞 LobsterAPI

> 提供给 Skill 调用的 API 服务，基于 **FastAPI** + **uv** 构建。

---

## 技术栈

| 技术 | 说明 |
|------|------|
| [FastAPI](https://fastapi.tiangolo.com/) | 高性能 Web 框架 |
| [uv](https://docs.astral.sh/uv/) | 极速 Python 包管理器 |
| [Pydantic v2](https://docs.pydantic.dev/) | 数据验证 & 设置管理 |
| [Uvicorn](https://www.uvicorn.org/) | ASGI 服务器 |
| [Loguru](https://loguru.readthedocs.io/) | 日志库 |
| [python-jose](https://python-jose.readthedocs.io/) | JWT 认证 |

---

## 项目结构

```
lobsterapi/
├── app/
│   ├── api/
│   │   └── v1/
│   │       ├── endpoints/
│   │       │   ├── auth.py        # 认证路由
│   │       │   └── health.py      # 健康检查路由
│   │       └── router.py          # v1 路由聚合
│   ├── core/
│   │   ├── config.py              # 配置（pydantic-settings）
│   │   ├── deps.py                # FastAPI 依赖注入
│   │   ├── exceptions.py          # 全局异常处理器
│   │   ├── logging.py             # 日志配置（loguru）
│   │   ├── middleware.py          # 请求日志中间件
│   │   └── security.py            # JWT / API Key 工具
│   ├── models/                    # 数据库 ORM 模型（按需扩展）
│   ├── schemas/
│   │   └── response.py            # 统一响应格式
│   ├── services/                  # 业务逻辑层
│   ├── utils/                     # 通用工具函数
│   └── main.py                    # FastAPI 应用工厂
├── tests/
│   ├── api/                       # API 集成测试
│   └── unit/                      # 单元测试
├── main.py                        # 入口脚本
├── pyproject.toml                 # 项目配置 & 依赖
├── .env.example                   # 环境变量示例
└── .gitignore
```

---

## 快速开始

### 前置要求

- [uv](https://docs.astral.sh/uv/getting-started/installation/) — 安装：`curl -LsSf https://astral.sh/uv/install.sh | sh`

### 安装依赖

```bash
# 创建虚拟环境并安装所有依赖
uv sync

# 安装含 dev 依赖
uv sync --extra dev
```

### 配置环境变量

```bash
cp .env.example .env
# 编辑 .env 按需修改配置
```

### 启动服务

```bash
# 方式一：直接运行（开发模式，自动热重载）
uv run python main.py

# 方式二：通过 uvicorn 启动
uv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# 方式三：通过项目脚本启动
uv run serve
```

服务启动后访问：
- API 文档：http://localhost:8000/docs
- ReDoc：http://localhost:8000/redoc
- 健康检查：http://localhost:8000/api/v1/health

---

## API 接口

### 健康检查

```http
GET /api/v1/health
```

### 获取访问令牌

```http
POST /api/v1/auth/token
Content-Type: application/json

{"api_key": "your-api-key"}
```

### 统一响应格式

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

| 字段 | 类型 | 说明 |
|------|------|------|
| `code` | int | `0` 表示成功，非 0 表示失败 |
| `message` | str | 提示信息 |
| `data` | any | 响应数据 |

---

## Docker 部署

### 前置要求

- [Docker](https://docs.docker.com/get-docker/) >= 24.0
- [Docker Compose](https://docs.docker.com/compose/) >= 2.20（已内置于 Docker Desktop）

### 快速部署

```bash
# 1. 配置环境变量
cp .env.example .env
# 编辑 .env，修改 SECRET_KEY、数据库连接等生产配置

# 2. 准备 API Key 配置文件
cp api_keys.example.json api_keys.json
# 编辑 api_keys.json，填写实际的 API Key

# 3. 构建并启动
docker compose up -d --build

# 4. 查看日志
docker compose logs -f api
```

服务启动后访问：
- API 文档：http://localhost:8000/docs
- 健康检查：http://localhost:8000/api/v1/health

### 常用命令

```bash
# 停止服务
docker compose down

# 重启服务
docker compose restart api

# 查看运行状态
docker compose ps

# 进入容器
docker compose exec api bash

# 重新构建并启动（代码更新后）
docker compose up -d --build
```

### 目录挂载说明

| 宿主机路径 | 容器内路径 | 说明 |
|-----------|-----------|------|
| `./logs/` | `/app/logs/` | 应用日志，持久化保存 |
| `./api_keys.json` | `/app/api_keys.json` | API Key 配置，只读挂载 |

### 生产环境注意事项

1. **Secret Key**：务必将 `.env` 中的 `SECRET_KEY` 替换为强随机字符串：
   ```bash
   openssl rand -hex 32
   ```

2. **端口暴露**：默认暴露 `8000` 端口，建议在前端配置 Nginx 反代并启用 HTTPS。

3. **日志**：容器日志写入 `./logs/` 目录，并在容器重启后保留。

---

## 开发

### 运行测试

```bash
uv run pytest
uv run pytest -v --tb=short   # 详细输出
```

### 代码格式化 & Lint

```bash
uv run ruff check .
uv run ruff format .
```

### 添加新依赖

```bash
uv add <package>           # 生产依赖
uv add --dev <package>     # 开发依赖
```

---

## 扩展业务路由

1. 在 `app/api/v1/endpoints/` 下新建路由文件，例如 `items.py`
2. 在 `app/api/v1/router.py` 中引入并注册
3. 在 `app/schemas/` 中定义请求/响应模型
4. 在 `app/services/` 中实现业务逻辑

---

## 环境变量说明

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `ENV` | `development` | 运行环境 |
| `DEBUG` | `true` | 是否开启调试模式 |
| `HOST` | `0.0.0.0` | 监听地址 |
| `PORT` | `8000` | 监听端口 |
| `SECRET_KEY` | *(需修改)* | JWT 签名密钥 |
| `API_KEYS` | `[]` | 允许的 API Key 列表，空则不校验 |
| `LOG_LEVEL` | `INFO` | 日志级别 |
| `LOG_FORMAT` | `json` | 日志格式（`json`/`text`）|