chaos
188 lines
7.4 KiB
Markdown
188 lines
7.4 KiB
Markdown
# AGENTS.md — Project Conventions for new-api
|
|
|
|
## Overview
|
|
|
|
AI API gateway/proxy (Go) aggregating 40+ upstream AI providers behind a unified API, with user management, billing, rate limiting, and a React admin dashboard.
|
|
|
|
- **Backend**: Go 1.25+, Gin, GORM v2, testify
|
|
- **Frontend**: Two themes — `web/default/` (React 19, Rsbuild, Base UI, Tailwind CSS 4, TanStack Router) and `web/classic/` (React 18, Vite, Semi Design). Default is the primary.
|
|
- **Databases**: SQLite, MySQL >= 5.7.8, PostgreSQL >= 9.6 (all three supported simultaneously)
|
|
- **Cache**: Redis (go-redis) + in-memory
|
|
- **Auth**: JWT, WebAuthn/Passkeys, OAuth (GitHub, Discord, OIDC)
|
|
- **Desktop**: Electron app at `electron/`
|
|
|
|
## Architecture
|
|
|
|
Layered: `router/` → `controller/` → `service/` → `model/`
|
|
|
|
```
|
|
router/ — HTTP routing (api, relay, dashboard, web)
|
|
controller/ — Request handlers
|
|
service/ — Business logic
|
|
model/ — Data models and DB access (GORM), auto-migrations
|
|
relay/ — AI relay/proxy with 40+ provider adapters in relay/channel/
|
|
middleware/ — Auth, rate limiting, CORS, logging, distribution
|
|
setting/ — Config management (ratio, model, operation, system, performance)
|
|
common/ — Shared utilities (JSON, crypto, Redis, env, rate-limit, etc.)
|
|
dto/ — Request/response DTOs
|
|
constant/ — API types, channel types, context keys
|
|
types/ — Relay format types, file sources, errors
|
|
i18n/ — Backend i18n (go-i18n, 3 locales: en, zh-CN, zh-TW)
|
|
oauth/ — OAuth provider implementations
|
|
pkg/ — Internal packages: cachex, ionet, billingexpr, perf_metrics
|
|
web/ — Frontend themes: web/default/, web/classic/
|
|
```
|
|
|
|
## Key Conventions
|
|
|
|
### 1. JSON — Use `common/json.go` wrappers
|
|
|
|
All marshal/unmarshal MUST use `common.Marshal`, `common.Unmarshal`, etc. Do NOT call `encoding/json` directly in business code. Type definitions from `encoding/json` (e.g. `json.RawMessage`) are still fine to reference.
|
|
|
|
### 2. Cross-DB Compatibility (SQLite, MySQL, PostgreSQL)
|
|
|
|
- Prefer GORM methods over raw SQL.
|
|
- Use `commonGroupCol`, `commonKeyCol`, `commonTrueVal`, `commonFalseVal` from `model/main.go` for reserved words and boolean literals.
|
|
- Branch DB-specific logic with `common.UsingPostgreSQL`, `common.UsingSQLite`, `common.UsingMySQL`.
|
|
- Forbidden without cross-DB fallback: MySQL-only `GROUP_CONCAT`, PostgreSQL `@>`/`JSONB` operators, `ALTER COLUMN` on SQLite, DB-specific column types (use `TEXT` for JSON).
|
|
- Migrations must pass on all three DBs.
|
|
|
|
### 3. Frontend — Bun required
|
|
|
|
Use `bun` (not npm/yarn/pnpm) for `web/default/`:
|
|
- `bun install` / `bun run dev` / `bun run build`
|
|
- See `web/default/AGENTS.md` for detailed frontend conventions (i18n, components, forms, routing, etc.)
|
|
|
|
### 4. New Channel — StreamOptions
|
|
|
|
When adding a channel, check if the provider supports `StreamOptions`. If so, add the channel type to `streamSupportedChannels` in `relay/common/relay_info.go:320`.
|
|
|
|
### 5. Protected Identity — DO NOT Modify
|
|
|
|
Do NOT remove, rename, or replace any reference to **new-api** (project) or **QuantumNous** (organization). This includes README, HTML titles, Go module paths, Docker images, package metadata, comments, and deployment configs.
|
|
|
|
### 6. Upstream DTOs — Pointer Types for Zero Values
|
|
|
|
Optional scalar fields in request structs that are parsed from client JSON and re-marshaled to upstream providers MUST use pointer types (`*int`, `*float64`, `*bool`, etc.) with `omitempty`. Non-`nil` pointer = preserve zero value. Non-pointer scalars with `omitempty` silently drop zeros.
|
|
|
|
### 7. Billing Expressions — Read `pkg/billingexpr/expr.md`
|
|
|
|
When working on tiered/dynamic billing, read `pkg/billingexpr/expr.md` first. It documents the expression language, system architecture, token normalization, and settlement rules.
|
|
|
|
## Development
|
|
|
|
### Run Backend
|
|
```sh
|
|
cp .env.example .env # edit as needed
|
|
go run main.go # starts on :3000
|
|
```
|
|
|
|
### Build (matches CI/Docker)
|
|
The VERSION file is created by CI (from git tag). For a manual build:
|
|
```sh
|
|
echo "dev" > VERSION
|
|
(cd web/default && bun install && DISABLE_ESLINT_PLUGIN='true' bun run build)
|
|
go build -ldflags "-s -w -X 'github.com/QuantumNous/new-api/common.Version=$(cat VERSION)'" -o new-api
|
|
```
|
|
|
|
### Run Backend Tests
|
|
```sh
|
|
go test ./... # all packages
|
|
go test ./pkg/billingexpr/... # single package
|
|
```
|
|
|
|
### Run Frontend Dev
|
|
```sh
|
|
cd web/default && bun install && bun run dev
|
|
# proxies /api, /mj, /pg -> http://localhost:3000 (configurable via VITE_REACT_APP_SERVER_URL)
|
|
```
|
|
|
|
### Other Scripts
|
|
```sh
|
|
cd web/default && bun run typecheck # tsc -b
|
|
cd web/default && bun run lint # eslint
|
|
cd web/default && bun run format # prettier --write
|
|
cd web/default && bun run i18n:sync # sync translation key structure
|
|
cd web/default && bun run knip # dead code detection
|
|
cd web/default && bun run build:check # typecheck + build
|
|
```
|
|
|
|
### Frontend Dev Server Management
|
|
|
|
Background dev server (stays alive after tool invocation):
|
|
```sh
|
|
# Start (background, log to /tmp/frontend.log)
|
|
cd web/default && setsid bun run dev > /tmp/frontend.log 2>&1 &
|
|
|
|
# Stop
|
|
pkill -f "bun run dev"
|
|
|
|
# Restart
|
|
pkill -f "bun run dev" && cd web/default && setsid bun run dev > /tmp/frontend.log 2>&1 &
|
|
|
|
# Check status
|
|
ps aux | grep -E "rsbuild|bun" | grep -v grep
|
|
|
|
# View logs
|
|
tail -f /tmp/frontend.log
|
|
```
|
|
|
|
### OpenAPI Specs
|
|
- Admin API: `docs/openapi/api.json` (131 endpoints)
|
|
- Relay API: `docs/openapi/relay.json` (30+ endpoints)
|
|
|
|
### CI/Docker
|
|
- Docker image: `calciumion/new-api`. Multi-arch (amd64 + arm64). Multi-stage build: bun builds frontend, then Go builds the binary with embedded `//go:embed web/default/dist`.
|
|
- PRs are checked by `peakoss/anti-slop` (requires PR template, description, no AI-generated markers).
|
|
- Tags trigger Docker pushes.
|
|
|
|
## Local Dev + Production Deployment
|
|
|
|
### Environment Layout
|
|
|
|
| Item | Dev (chaos user) | Prod (www user) |
|
|
|------|------------------|-----------------|
|
|
| Directory | `/home/chaos/new-api/` | `/home/www/new-api-prod/` |
|
|
| Port | `localhost:3000` (API) / `localhost:5173` (frontend hot-reload) | `localhost:3001` |
|
|
| Config | `docker-compose.dev.yml` | `/home/www/new-api-prod/docker-compose.prod.yml` |
|
|
| Data | Docker volume `dev_data` | `/home/www/new-api-prod/data/` |
|
|
|
|
### Git Remotes
|
|
|
|
- `origin` → `https://git.nomsg.cn/chaos/chaos-api.git` (fork, push here)
|
|
- `upstream` → `https://github.com/QuantumNous/new-api.git` (official, pull from here)
|
|
|
|
### Daily Workflow
|
|
|
|
```sh
|
|
# Sync upstream (auto-triggers deploy via post-merge hook)
|
|
git fetch upstream && git merge upstream/main
|
|
|
|
# Manual deploy
|
|
./deploy.sh
|
|
```
|
|
|
|
### Deploy Script (`deploy.sh`)
|
|
|
|
Located at project root. Does three things:
|
|
1. Builds frontend (`web/default/`) with bun
|
|
2. Builds Docker image `my-new-api:latest`
|
|
3. Restarts production containers as `www` user via `sudo -u www docker compose ...`
|
|
|
|
### Git Hook
|
|
|
|
`.git/hooks/post-merge` automatically runs `./deploy.sh` after `git merge`.
|
|
|
|
### Permission Isolation
|
|
|
|
- **chaos**: owns code, builds images, triggers deploy via sudoers whitelist
|
|
- **www**: owns production data dir, runs production containers
|
|
- sudoers rule: `/etc/sudoers.d/chaos-deploy` — chaos can only run `docker compose -f /home/www/new-api-prod/docker-compose.prod.yml *` as www
|
|
|
|
### Production Secrets
|
|
|
|
Stored in `/home/www/new-api-prod/.env` (owned by www, mode 600). Contains:
|
|
- `DB_PASS` — PostgreSQL password
|
|
- `REDIS_PASS` — Redis password
|
|
- `SESSION_SECRET` — multi-node session secret
|