SnowAPI

基于 New API 深度定制的多模型 API 网关、运营控制台与用量管理平台

SnowAPI 是运行中 SnowAPI 服务的完整源码快照，对应内部构建版本 r33。仓库保留了定制后端、前端、主题资产、国际化文本、Docker 构建文件及一份脱敏的站点设置参考。

本项目基于 QuantumNous/new-api 开发。原项目名称、作者归属、许可证与附加声明均予以保留；上游原始 README 归档在 docs/UPSTREAM_README.md。

定制内容

界面与交互

• SnowAPI 黑白视觉体系、浅色默认主题、衬线字体和浮动式布局。
• 定制首页，包括动态文字、线程背景、卡片切换和响应式内容区。
• 桌面端与移动端统一的底部导航 Dock。
• 登录和注册页的金属流体背景、精简认证表单及 LinuxDO 登录入口。
• 独立的外置主题样式和站点图标，位于 deploy/theme/。
• 可配置的顶部导航、管理侧栏和前端主题默认值。

运营与认证

• LinuxDO OAuth 登录。
• 邀请码创建、管理、核销和邀请注册限制。
• 可关闭密码登录与密码注册，同时允许受控 OAuth 注册。
• 签到日历、兑换码卡片和钱包页面调整。

监控与统计

• 模型健康状态、成功率、延迟与小时级聚合。
• 后台模型健康测试任务和模型健康控制台。
• 全局 Token 用量面板和用户用量图表。
• 模型请求速率限制与成功请求阈值设置。

上游能力

• 兼容 OpenAI Chat Completions、Responses、Realtime、Embeddings、Images、Audio 等接口。
• 支持 Claude、Gemini、Azure OpenAI、AWS Bedrock、OpenRouter、Ollama、Mistral、DeepSeek 等多种渠道。
• 提供用户、令牌、渠道、模型、额度、日志、订阅、支付和权限管理。
• 支持 SQLite、MySQL、PostgreSQL，日志还可使用 ClickHouse。
• 支持 Redis 缓存、多节点部署、限流和任务调度。

开源内容与数据边界

内容	仓库状态
Go 后端完整源码	已包含
React 默认前端与 Classic 前端	已包含
SnowAPI 首页、认证页、导航、邀请码、模型健康和用量统计定制	已包含
黑白主题 CSS、站点图标和 Nginx 示例	已包含
Dockerfile、Compose 示例、依赖锁文件	已包含
非敏感站点设置参考	已包含
用户、管理员、令牌、签到和兑换记录	未包含
渠道地址、渠道密钥和渠道运行状态	未包含
模型、模型定价、倍率和模型健康历史数据	未包含
请求日志、用量流水和性能指标	未包含
OAuth 密钥、会话密钥、加密密钥和服务器凭据	未包含
生产数据库、备份和运行日志	未包含

仓库不包含任何生产数据库文件。config/snowapi-settings.example.json 仅保存经过人工白名单筛选的非敏感配置，不是数据库导出。

快速开始

环境要求

• Docker Engine 24 或更高版本
• Docker Compose v2
• 至少 2 GB 可用内存
• 用于生产环境的域名、HTTPS 证书和反向代理

使用 Docker Compose

git clone https://github.com/Ooxygen7/SnowAPI.git
cd SnowAPI

cp deploy/.env.example deploy/.env

生成两个独立随机密钥并写入 deploy/.env：

openssl rand -hex 32
openssl rand -hex 32

编辑完成后构建并启动：

docker compose --env-file deploy/.env -f deploy/compose.yaml up -d --build

查看服务状态：

docker compose --env-file deploy/.env -f deploy/compose.yaml ps
curl http://127.0.0.1:3000/api/status

默认只绑定到 127.0.0.1:3000。首次访问时按页面向导创建管理员账户并完成数据库初始化。

停止与更新

docker compose --env-file deploy/.env -f deploy/compose.yaml down

git pull
docker compose --env-file deploy/.env -f deploy/compose.yaml up -d --build

Compose 使用命名卷 snowapi_data 保存运行数据。普通的 down 不会删除该卷；不要在未备份时执行 down -v。

还原 SnowAPI 主题

应用内的 SnowAPI UI 已经编译在源码中。线上版本还使用 Nginx 注入一层黑白主题并替换站点图标，相关文件位于：

deploy/
  nginx/
    api.unsnow.org.conf
  theme/
    monochrome.css
    unsnow-favicon.png

使用示例配置前，请根据自己的部署修改域名和证书路径，并把主题文件复制到 /var/www/snowapi-theme/：

sudo install -d -m 0755 /var/www/snowapi-theme
sudo install -m 0644 deploy/theme/monochrome.css /var/www/snowapi-theme/
sudo install -m 0644 deploy/theme/unsnow-favicon.png /var/www/snowapi-theme/

然后安装 Nginx 配置、检查语法并平滑重载：

sudo cp deploy/nginx/api.unsnow.org.conf /etc/nginx/sites-available/api.unsnow.org
sudo ln -sfn /etc/nginx/sites-available/api.unsnow.org /etc/nginx/sites-enabled/api.unsnow.org
sudo nginx -t
sudo systemctl reload nginx

站点设置参考

config/snowapi-settings.example.json 保留以下非敏感站点行为：

• SnowAPI 名称、页脚、Logo 路径和首页导航开关。
• 控制台与管理侧栏模块开关。
• LinuxDO OAuth、邀请码要求、密码登录和注册策略。
• 新用户额度、预消费额度、签到额度和 Token 数量限制。
• 模型请求速率限制、缓存和前端主题选择。
• 公告、文档入口和公开模块开关。

该文件有意排除了 OAuth Client Secret、生产密钥、支付信息、用户标识、IP 地址、渠道配置、模型列表、模型价格和倍率。请在首次启动后的管理后台中按需录入；不要把生产数据库复制到公开仓库。

LinuxDO OAuth

在管理后台的认证设置中填写：

• LinuxDO Client ID
• LinuxDO Client Secret
• 最低信任等级
• 是否要求邀请码

回调地址使用：

https://your-domain.example/oauth/linuxdo

如需保持本仓库参考策略：

• RegisterEnabled 设为 true
• PasswordRegisterEnabled 设为 false
• PasswordLoginEnabled 设为 false
• LinuxDOOAuthEnabled 设为 true
• LinuxDOOAuthInvitationRequired 设为 true

这会允许符合条件的 LinuxDO OAuth 用户完成受控注册，同时关闭普通密码注册和密码登录。

从源码开发

后端

go mod download
go test ./...
go run .

后端使用 Go、Gin 和 GORM。数据库访问必须同时兼容 SQLite、MySQL 与 PostgreSQL。

前端

cd web
bun install --frozen-lockfile

cd default
bun run typecheck
bun run lint
bun run build

开发服务器：

cd web/default
bun run dev

默认前端使用 React 19、TypeScript、Rsbuild、Tailwind CSS、TanStack Router、TanStack Query、Zustand 和 i18next。Classic 前端保留在 web/classic/。

完整镜像

docker build -t snowapi:local .
docker run --rm -p 127.0.0.1:3000:3000 \
  -e SESSION_SECRET="$(openssl rand -hex 32)" \
  -e CRYPTO_SECRET="$(openssl rand -hex 32)" \
  -v snowapi_data:/data \
  snowapi:local

数据库

未配置 SQL_DSN 时默认使用 SQLite。生产环境可使用 MySQL 或 PostgreSQL：

SQLite:
  SQLITE_PATH=/data/one-api.db

MySQL:
  SQL_DSN=user:password@tcp(mysql:3306)/snowapi?charset=utf8mb4&parseTime=True&loc=Local

PostgreSQL:
  SQL_DSN=postgresql://user:password@postgres:5432/snowapi

Redis:
  REDIS_CONN_STRING=redis://:password@redis:6379/0

不要把数据库连接串、数据库文件、Redis 密码或备份提交到 Git。

主要目录

controller/             HTTP 控制器
model/                  GORM 模型、迁移与数据访问
service/                业务逻辑、计费与任务
relay/                  协议转换和渠道适配器
router/                 API、控制台和中继路由
middleware/             认证、限流、日志和安全中间件
setting/                系统、模型、性能和计费设置
common/                 公共工具、缓存、数据库和配额计算
web/default/            SnowAPI 默认前端
web/classic/            Classic 前端
config/                 脱敏设置参考
deploy/                 Compose、Nginx 和主题资产
docs/                   上游文档和接口说明

安全建议

• 首次部署前更换所有示例密码并生成独立的 SESSION_SECRET 与 CRYPTO_SECRET。
• 只通过 HTTPS 暴露管理界面和 API。
• 不要直接向公网暴露数据库、Redis 或容器管理端口。
• 定期备份 /data，并在升级前验证备份可恢复。
• 将 OAuth、支付和上游渠道密钥放入密钥管理系统或受限环境变量。
• 生产环境启用防火墙、请求大小限制、速率限制和日志轮转。
• 发布前检查 Git 历史，而不仅是当前工作树，避免已删除密钥仍留在提交中。

安全问题请按 SECURITY.md 中的方式私下报告。

上游与许可

SnowAPI 是 New API 的修改版本：

• 上游项目：QuantumNous/new-api
• 上游作者：QuantumNous 及 New API contributors
• 上游基线提交：a63364d156cf2a64f1c3d1ee4923d73d5f3222a1
• 本仓库许可证：GNU Affero General Public License v3.0
• 附加声明：NOTICE
• 第三方许可：THIRD-PARTY-LICENSES.md

使用、修改或通过网络提供本软件时，必须遵守 AGPL-3.0、NOTICE 中的附加条款和第三方许可证要求。修改版本不得歪曲软件来源，并应保留 New API 与 QuantumNous 的归属信息和原项目链接。

贡献

提交变更前至少运行与改动相关的 Go 测试、TypeScript 类型检查、前端 lint 和生产构建。请保持数据库兼容性、国际化、计费安全和敏感信息边界。

本仓库的目标是公开并持续维护 SnowAPI 定制版本，同时清晰保留其 New API 上游来源。