New API 高级定制版开发文档

这个项目是什么

New API 高级定制版（仓库 jinghui/new-api）是基于 QuantumNous/new-api v1.0.0-rc.36 的深度定制 Fork——一个 Go 实现的 AI API 网关：聚合多家大模型供应商，对内提供统一的 OpenAI 兼容接口、令牌管理、多渠道分发、用量统计与成本核算。定制版在上游能力之上重点改造了计费与运营：人民币原生计费、充值赠送、每日签到、订阅套餐、免费模型筛选与官方价格自动同步。线上实例为 https://ai.88531.cn 。

技术栈与架构

后端：Go（go.mod 声明模块 github.com/QuantumNous/new-api，要求 Go 1.25.1+），VERSION 文件标记版本 v1.0.0-rc.36-custom。
前端：web/ 目录下的 React SPA（Vite 构建，构建工具链用 bun），版本号由 VERSION 文件注入（VITE_REACT_APP_VERSION）。
存储：PostgreSQL / MySQL / SQLite 任选（SQL_DSN 环境变量切换），Redis 做缓存与会话（REDIS_CONN_STRING）；日志库可独立（LOG_SQL_DSN 支持单独 PostgreSQL 或 ClickHouse）。
分层（目录即分层）：controller/（HTTP 处理器）→ service/（业务）→ model/（GORM 数据模型）→ relay/（对上游供应商的中继转发）→ middleware/（鉴权/限流等）→ router/（路由注册）→ setting/ + constant/ + dto/（配置与类型）。
多语言：i18n/ 内置 en / zh / zh-TW / fr / ja / ru / vi 七语种。

仓库结构

顶层真实目录及职责：

路径	说明
`main.go` / `makefile`	程序入口与构建命令
`common/` `constant/` `controller/` `dto/` `logger/` `middleware/` `model/` `relay/` `relaykit/` `router/` `service/` `setting/` `types/` `oauth/` `pkg/` `plugins/`	Go 后端各分层模块
`web/`	React 前端（`web/public/logo.png` 等静态资源）
`i18n/`	七语种翻译
`docs/`	文档资源（站内 `/docs` 新手指南相关）
`e2e/`	端到端测试
`electron/`	桌面端打包工程
`bin/`	构建产物目录
`Dockerfile` / `Dockerfile.dev` / `docker-compose.yml` / `docker-compose.dev.yml`	生产与开发编排
`.env.example`	环境变量示例（PORT、FRONTEND_BASE_URL、DEBUG、pprof/Pyroscope 等）
`CHANGELOG.md` / `RELEASE_NOTES.md` / `VERSION`	版本与变更记录
`AGENTS.md` / `CLAUDE.md` / `.agents/`	AI 辅助开发的项目说明

本地开发环境

后端（Go）与前端（bun）分离开发：

# 前端：构建（版本号取自 VERSION 文件）
cd web
bun install --frozen-lockfile
DISABLE_ESLINT_PLUGIN='true' VITE_REACT_APP_VERSION=$(cat ../VERSION) bun run build

# 前端：开发服务器（默认 5173 端口）
bun run dev -- --host 0.0.0.0 --port 5173

# 后端：直接跑
go run main.go

# 或用 makefile 一键（组合上述流程）
make all            # 构建前端 + 启动 API
make dev            # dev-api（docker compose -f docker-compose.dev.yml 起 postgres 等）+ dev-web
make dev-api-rebuild

开发编排 docker-compose.dev.yml 默认拉起 postgres 服务（库名 new-api，用户 root），SQLite 路径默认 one-api.db。

配置项说明

docker-compose.yml 与 .env.example 中真实存在的配置：

配置键	含义	示例/默认
`SQL_DSN`	主数据库连接串（PostgreSQL/MySQL/SQLite）	`postgresql://root:***@postgres:5432/new-api`
`LOG_SQL_DSN`	可选：日志独立库（PostgreSQL 或 ClickHouse）	未启用
`LOG_SQL_CLICKHOUSE_TTL_DAYS`	ClickHouse 日志保留天数，0/未设为不自动清理	0
`REDIS_CONN_STRING`	Redis 连接串	`redis://:123456@redis:6379`
`TZ`	时区	`Asia/Shanghai`
`ERROR_LOG_ENABLED`	是否启用错误日志记录	`true`
`BATCH_UPDATE_ENABLED`	是否启用批量更新	`true`
`NODE_NAME`	节点名（审计日志标识，多节点部署建议设置）	`new-api-node-1`
`STREAMING_TIMEOUT`	流模式无响应超时（秒），默认 120	300（可选）
`RELAY_IDLE_CONN_TIMEOUT`	中继 HTTP 客户端空闲连接超时（秒）	90（可选）
`SESSION_SECRET`	多机部署必须改的随机串	未设
`SESSION_COOKIE_SECURE`	启用 Secure Cookie 与严格 OriginGuard	未设（本地 HTTP）
`SESSION_COOKIE_TRUSTED_URL`	Secure=true 时必填的精确 HTTPS Origin 列表	未设
`PORT`	端口	`3000`（.env.example 中注释形式）
`DEBUG` / `ENABLE_PPROF` / `PYROSCOPE_*`	调试与性能剖析	关闭

构建与发布

# 生产镜像（上游默认 compose 引用官方镜像名，定制部署使用自建 tag）
docker compose up -d
# 访问 http://localhost:3000

# 开发模式重建 API 容器
make dev-api-rebuild

线上定制版部署镜像为 new-api-custom:rc45（内嵌新前端与同版本 Go 网关，见 CHANGELOG 2026-09-30 条目）。多机部署时务必设置 SESSION_SECRET，并按官方建议修改 compose 内所有默认密码。

定制改造点（相对官方版）

人民币原生计费：额度与账单全部按人民币展示，充值多少人民币到账等额额度，钱包环节不做汇率换算；易支付、Waffo 等全部充值渠道适配（controller/topup.go、model/topup.go）。
充值赠送：统一赠送比例 payment_setting.amount_bonus = 1.0（充多少送多少、上不封顶），到账额度在 topupQuotaFromAmount / getTopUpQuota 统一乘 (1 + bonus)，覆盖易支付/Waffo/Pancake/管理员补单全部到账路径；改回 0 即关闭。
充值页优惠展示：优惠横幅、金额档「到账 ¥x」「已省 ¥x」、自定义金额到账预估、支付确认弹窗到账金额行。
每日签到：新增 checkin_setting 配置与前端 CheckinButton 组件（支持 Turnstile 人机验证），匿名访客引导注册、每日签到领额度。
订阅套餐 /subscribe：公开套餐页（未登录读 plans.json 快照、登录后走系统 API），支持支付宝/余额/免费领取，购买后自动升级分组、周期性额度重置、到期自动降级。
模型广场：定价类型新增「免费」筛选（绿色标签 + 实时计数）、「今日免费模型」流光横幅；官方价格每日凌晨自动同步（scripts/sync-zen-prices.py，数据源为 models.dev 镜像），限免恢复收费与价格涨跌自动生效。
模型云：模型元数据目录（vendors / models 表）、上下架策略、上游模型巡检与自动同步。
前端体验：站点语言默认中文（不再跟随浏览器）、/docs 12 节新手图文指南（带吸顶锚点导航）、首页霓虹促销横幅、七语种文案同步。

二次开发要点

上游兼容是底线：官方能力请对照上游文档，本 Fork 只做加法式定制，合并上游更新时重点回归 controller/topup.go、model/topup.go 与充值/签到/订阅相关前端组件。
计费路径回归：任何涉及到账逻辑的改动必须覆盖全部到账路径（易支付/Waffo/Pancake/管理员补单），RC42 已附回归测试，二开时沿用。
前端构建注意 VITE_REACT_APP_VERSION 从 VERSION 文件注入，忘记设置会导致页面版本号错误。
使用合规：本项目仅用于合法且经授权的 AI API 网关、组织鉴权、多模型管理、用量统计与私有化部署场景；面向公众提供生成式 AI 服务需自行履行备案、内容安全、实名、日志留存等义务。

New API 高级定制版 开发文档