Content
# Data Proxy
[](https://github.com/normojs/data-proxy/actions/workflows/ci.yml)
[](https://github.com/normojs/data-proxy/actions/workflows/data-proxy-docker.yml)
[](./LICENSE)
Data Proxy is an AI API gateway and quota management platform for enterprise governance scenarios, developed based on the open-source project [new-api](https://github.com/QuantumNous/new-api).
It inherits new-api's multi-model access, OpenAI compatible protocol, channel routing, user and token management, quota and usage statistics capabilities, and adds enterprise organization, policy quota, approval notification, audit visibility, SSO synchronization, and compliance publishing links.
> [!IMPORTANT]
> This project is a secondary development version based on new-api. Please retain [LICENSE](./LICENSE), [NOTICE](./NOTICE), [THIRD-PARTY-LICENSES.md](./THIRD-PARTY-LICENSES.md), original project links, and NOTICE required visible attribution. Data Proxy continues to follow AGPLv3 and NOTICE Section 7 additional requirements.
## Project Positioning
Data Proxy is suitable for teams that need to centrally manage large model API assets:
- Manage OpenAI compatible, Claude, Gemini, Responses, Realtime, Rerank and other model protocols and channels in the same entry point.
- Set request number or quota policies for enterprises, departments, policy groups, and users.
- Gradually roll out enterprise governance rules through dry-run, hard limit, usage attribution, and audit logs.
- Form a trackable closed loop for temporary quota applications, approval results, expiration reminders, and external notifications.
- Ensure release traceability with GitHub CI, Docker publishing evidence, and licensing file distribution requirements.
## Current Capabilities
### Inherited from new-api
- OpenAI compatible API gateway, supporting multi-model, multi-channel, and automatic retry.
- User, token, group, model permission, quota, billing, and statistical dashboard.
- Multiple login and OAuth/OIDC access capabilities.
- Compatibility migration foundation with One API data structure.
- Docker, Compose, environment variables, and initialization wizard deployment paths.
For more upstream capabilities, refer to [new-api official documentation](https://docs.newapi.pro/) and [new-api repository](https://github.com/QuantumNous/new-api).
### Data Proxy Enhanced Capabilities
- Enterprise governance model: enterprise, organization department, member, policy group, quota policy, usage attribution, and audit log.
- Quota policy: supports `request_count` and `quota`, can be hit by enterprise, department, group, or user, supports dry-run and hard reject.
- Temporary quota approval: user submission, administrator approval, rejection, withdrawal, expiration, and expiration reminders.
- Notification closed loop: in-site notification, enterprise audit event, email/webhook outbox, notification preference, delivery result query, failure retry, and worker indicators.
- HStation OAuth: login, registration, binding, unbinding, administrator configuration, and automated testing coverage.
- SSO organization synchronization: supports payload preview, dry-run, conflict list, transaction apply, and synchronization audit.
- Enterprise quota Redis counting: optional Redis atomic reserve/settle/refund, DB downgrade, and DB/Redis reconciliation and repair.
- Advanced governance actions: support model downgrade, enterprise queuing, shared pool, exception protection, and queue replay; queuing requests can record audit lifecycle, and support inline JSON, large payload DB or local/S3 object storage persistence, payload TTL cleanup, multipart/audio upload replay, and queue payload visibility desensitization.
- fusion-benchmark: offline dataset, configuration verification, fixture, self-inspection, and CI inspection script.
## Quick Start
### Using Docker Compose
```bash
git clone https://github.com/normojs/data-proxy.git
cd data-proxy
docker compose up -d data-proxy
```
Access after startup:
```text
http://localhost:3000
```
For the first installation, please use the initialization wizard to configure the database and Redis, and then create the first administrator account. Explicit environment variables are still supported, but more suitable for advanced operation and maintenance coverage.
### Using Local Dependencies
If you want to start PostgreSQL and Redis with Compose:
```bash
docker compose --profile local-deps up -d
```
Use in the initialization wizard:
- PostgreSQL host: `postgres`
- Redis host: `redis`
These local dependencies are only visible within the Compose network by default and will not occupy the host's `5432` or `6379` port.
### Using Published Images
```bash
docker pull ghcr.io/normojs/data-proxy:latest
```
Stable version example:
```bash
docker pull ghcr.io/normojs/data-proxy:v1.3.0
```
Release, tag, image summary, and rollback process see [Data Proxy Release Runbook](./docs/data-proxy-release-runbook.md).
## Common Configuration
It is recommended to write runtime config through the web initialization wizard for the first installation. Advanced scenarios can use environment variables in `.env.example` to override.
Common variables:
| Variable | Description |
| --- | --- |
| `SQL_DSN` | Database connection string, advanced override item. |
| `REDIS_CONN_STRING` | Redis connection string, advanced override item. |
| `SESSION_SECRET` | Session key that must be set for multi-node deployment. |
| `NODE_TYPE` | The main node can be set to `master` for periodic tasks. |
| `NODE_NAME` | Node name will enter audit and operation and maintenance troubleshooting links. |
| `DATA_PROXY_SETUP_AUTO_RESTART` | Controls whether the initialization wizard saves configuration and automatically triggers container restart. |
| `ENTERPRISE_QUEUE_PAYLOAD_TTL_SECONDS` | Queue replay payload retention seconds, default 7 days; only clean up released old payload and old orphan payload. |
| `ENTERPRISE_QUEUE_PAYLOAD_OBJECT_PROVIDER` | Queue replay large payload external object storage provider; use DB by default, support `local` or `s3`. |
| `ENTERPRISE_QUEUE_PAYLOAD_OBJECT_DIR` | `local` provider object directory; use system temporary directory by default. |
| `ENTERPRISE_QUEUE_PAYLOAD_OBJECT_S3_ENDPOINT` / `ENTERPRISE_QUEUE_PAYLOAD_OBJECT_S3_BUCKET` | `s3` provider S3 or S3-compatible endpoint and bucket. |
For complete deployment instructions, see [Data Proxy Operator Guide](./docs/data-proxy-operator-guide.md).
## Management and Verification
### Enterprise Governance Entry
- Management entrance: `Admin` -> `Enterprise Governance`
- Routing: `/enterprise`
- Permission: Administrator and above
Recommended online order:
1. Keep enterprise governance closed and confirm that the existing gateway and billing link are not affected.
2. Enable dry-run, observe policy hit, would reject audit, and usage attribution.
3. Open a small range of hard limits for test users or test groups.
4. Expand to real department or enterprise-level strategy.
For detailed operations, see [Enterprise Governance Admin Guide](./docs/enterprise-governance-admin-guide.md).
### Local Verification
Common verification commands:
```bash
git diff --check
go test ./model ./controller ./service ./router ./oauth
cd web/default && bun run typecheck
cd web/default && bun run smoke:approval-notification-links
cd web/default && NODE_OPTIONS=--max-old-space-size=4096 bun run build
scripts/fusion-benchmark-check.sh
```
Run complete pre-check before release:
```bash
make deployment-preflight
```
Optional Docker build pre-check:
```bash
DEPLOYMENT_PREFLIGHT_DOCKER_BUILD=1 make deployment-preflight
```
## Document Index
| Document | Purpose |
| --- | --- |
| [Data Proxy Operator Guide](./docs/data-proxy-operator-guide.md) | Operation, initialization, dependency, and deployment handover. |
| [Data Proxy Release Runbook](./docs/data-proxy-release-runbook.md) | Tag, image, publishing evidence, rollback, and compliance inspection. |
| [Deployment Readiness](./docs/deployment-readiness.md) | Pre-release inspection commands and current machine status record. |
| [Enterprise Governance Admin Guide](./docs/enterprise-governance-admin-guide.md) | Enterprise governance administrator operation manual. |
| [Post V1.3 TODO](./docs/data-proxy-post-v1.3-todo.md) | Development sequence and remaining tasks after V1.3. |
| [Branding and Release Policy](./docs/branding-and-release-policy.md) | Data Proxy brand boundary and new-api attribution rules. |
The `README.en.md`, `README.zh_CN.md`, `README.zh_TW.md`, `README.fr.md`, `README.ja.md` in the repository still retain upstream new-api information and historical attribution reference. Data Proxy's operation and release entrance take this README and `docs/data-proxy-*` documents as the standard.
## Open Source License and Compliance
Data Proxy is developed based on [new-api](https://github.com/QuantumNous/new-api) and continues to adopt [GNU Affero General Public License v3.0](./LICENSE).
Please note:
- When distributing source code, images, binaries, front-end bundles, or desktop installation packages, you must retain `LICENSE`, `NOTICE`, and `THIRD-PARTY-LICENSES.md`.
- Modified versions cannot mislead software sources and need to clearly mark Data Proxy's change source.
- Modified versions with UI must retain NOTICE required visible attribution text and original project links.
- Docker image publishing links should continue to carry `/licenses/LICENSE`, `/licenses/NOTICE`, and `/licenses/THIRD-PARTY-LICENSES.md`.
If your organization cannot accept AGPLv3 or NOTICE Section 7 obligations, please complete internal legal assessment before deployment, distribution, or providing network services.
## Legal Use
This project is only applicable to legal, authorized AI API gateway, enterprise organization authentication, multi-model management, usage analysis, cost accounting, and privatized deployment scenarios.
Users need to legally obtain upstream API keys, accounts, model services, and interface authorization and comply with upstream service terms and applicable laws and regulations. If providing generative AI services or API resale services to the public, you should complete the required registration, licensing, content security, real-name, log retention, tax, payment, and upstream authorization obligations in your location.
