Key-IP Sentinel is a FastAPI-based reverse proxy that enforces first-use IP binding for model API keys before traffic reaches a downstream New API service.
## Features
- First-use bind with HMAC-SHA256 token hashing, Redis cache-aside, and PostgreSQL CIDR matching.
- Streaming reverse proxy built on `httpx.AsyncClient` and FastAPI `StreamingResponse`.
- Trusted proxy IP extraction that only accepts `X-Real-IP` from configured upstream networks.
- Redis-backed intercept alert counters with webhook delivery and PostgreSQL audit logs.
- Admin API protected by JWT and Redis-backed login lockout.
- Vue 3 + Element Plus admin console for dashboarding, binding operations, audit logs, and live runtime settings.
- Docker Compose deployment with Nginx, app, Redis, and PostgreSQL.
- PostgreSQL stores authoritative token bindings and intercept logs.
- Archive retention removes inactive bindings from the active table after `ARCHIVE_DAYS`. A later request from the same token will bind again on first use.
-`SENTINEL_FAILSAFE_MODE=closed` rejects requests when both Redis and PostgreSQL are unavailable. `open` allows traffic through.
## Local Development
### Backend
1. Install `uv` and ensure Python 3.13 is available.
2. Create the environment and sync dependencies:
```bash
uv sync
```
3. Copy `.env.example` to `.env` and update secrets plus addresses.
4. Start PostgreSQL and Redis.
5. Run the API:
```bash
uv run uvicorn app.main:app --reload --host 0.0.0.0 --port 7000
```
### Frontend
1. Install dependencies:
```bash
cd frontend
npm install
```
2. Start Vite dev server:
```bash
npm run dev
```
The Vite config proxies `/admin/api/*` to `http://127.0.0.1:7000`.
- Local Python development uses `uv` via [`pyproject.toml`](/d:/project/sentinel/pyproject.toml).
- Container builds still use [`requirements.txt`](/d:/project/sentinel/requirements.txt) because the Dockerfile is intentionally minimal and matches the delivery requirements.
## Production Deployment
### 1. Prepare environment
1. Copy `.env.example` to `.env`.
2. Replace `SENTINEL_HMAC_SECRET`, `ADMIN_PASSWORD`, and `ADMIN_JWT_SECRET`.
3. Verify `DOWNSTREAM_URL` points to the internal New API service.
4. Keep `PG_DSN` aligned with the fixed PostgreSQL container password in `docker-compose.yml`, or update both together.
### 2. Build the frontend bundle
```bash
cd frontend
npm install
npm run build
cd ..
```
This produces `frontend/dist`, which Nginx serves at `/admin/ui/`.
