代码目录与模块边界

本页帮助二次开发者快速定位代码。普通部署者可以只读“哪些目录会影响运行”。

仓库顶层

sub2api/
├── backend/       Go 服务、Ent、迁移和资源
├── frontend/      Vue 管理后台
├── deploy/        Compose、systemd、安装脚本和示例配置
├── docs/          支付、法律和集成文档
├── docs-101/      当前 VitePress 入门文档
├── .github/       CI、安全扫描和发布流程
├── Dockerfile     前端 + 后端多阶段构建
└── Makefile       常用构建与测试入口

后端入口

backend/cmd/server/
├── main.go        启动、首次设置、信号与优雅退出
├── wire.go        Wire 依赖声明
├── wire_gen.go    自动生成的依赖装配
└── VERSION        源码构建的版本回退值

修改构造函数依赖后，要运行：

cd backend
go generate ./cmd/server

internal/server

• router.go：Gin、全局中间件和路由组装。
• http.go：HTTP Server、body limit、H2C 和超时。
• routes/gateway.go：模型网关全部公开入口。
• routes/auth.go：注册、登录、OAuth 与密码流程。
• routes/user.go：用户侧后台 API。
• routes/admin.go：管理员模块路由。
• routes/payment.go：支付和 webhook 路由。

新增公开端点时，先判断它属于用户 JWT、管理员 JWT、API Key 还是公开 webhook，不要绕过已有中间件组。

internal/handler

Handler 直接面对 Gin Context：

• gateway_handler*.go：Anthropic/Gemini/Antigravity 兼容入口。
• openai_gateway_handler.go：Responses、Messages bridge、WebSocket 主链路。
• openai_chat_completions.go、openai_images.go：特定端点。
• failover_loop.go：通用故障切换状态。
• gateway_helper.go：并发槽位等待与释放。
• ops_error_logger.go：请求错误采样与归因。
• admin/：管理员页面对应的 API Handler。

如果代码需要读写 HTTP header、状态码或 SSE Writer，通常属于 Handler；纯业务规则应下沉 Service。

internal/service

这是代码量最大的目录，按领域可分为：

领域	代表文件
网关与协议	gateway_*、openai_gateway_*、gemini_messages_compat_service.go
调度	gateway_scheduling.go、openai_account_scheduler.go
账号	account.go、account_service.go、account_test_service.go
计费与用量	billing_*、usage_*、pricing_service.go
身份	auth_*、oauth_*、totp_service.go
支付	payment_* 与 internal/payment/
运维	ops_*、dashboard_*、scheduled_test_*
后台任务	*_expiry_service.go、*_cleanup.go、*_worker.go

部分大 Service 已按同一接收者拆成多个文件。查找方法实现时应使用 rg 'func \(s \*TypeName\)'，不要只看与类型同名的文件。

internal/repository

Repository 同时包含 Ent、database/sql 和 Redis：

• *_repo.go：PostgreSQL 持久化。
• *_cache.go：Redis 缓存、限流、锁和队列。
• concurrency_cache.go：并发槽位 Lua 脚本。
• scheduler_cache.go：调度快照与运行时状态。
• usage_log_repo*.go：用量查询和统计。
• ops_repo*.go：运维指标、聚合和错误日志。

命名为 cache 的组件不一定只是可丢失缓存。例如 concurrency、leader lock 和 batch queue 是运行时协调状态。

internal/pkg

可复用的协议与基础能力：

• apicompat：Anthropic/OpenAI 等协议转换。
• openai、gemini、geminicli、antigravity、xai：平台协议与客户端。
• httpclient、proxyutil、tlsfingerprint：网络栈。
• logger、response、errors：通用基础设施。
• websearch：Brave/Tavily 等搜索模拟。

与单一业务实体无关、可以独立测试的协议函数适合放这里。

Ent 与迁移

backend/ent/schema/     手写 schema
backend/ent/            自动生成实体、查询和 mutation
backend/migrations/     生产数据库向前迁移

修改 Schema 时需要同时考虑：

1. 新安装数据库如何创建字段。
2. 现有数据库如何迁移。
3. 回填是否会锁表或长时间运行。
4. 索引能否在线创建。
5. 旧程序是否还能读取新结构。

不要手改 backend/ent 生成文件。

前端

frontend/src/
├── api/           HTTP API 封装
├── components/    复用组件与领域组件
├── composables/   Vue 组合逻辑
├── stores/        Pinia 状态
├── router/        路由与守卫
├── views/user/    用户页面
├── views/admin/   管理员页面
├── i18n/          多语言
└── utils/         纯工具函数

管理页面与后端 DTO 经常同步演进。修改 API 返回结构时，应同时搜索：

rg "字段名" backend/internal frontend/src

部署文件

• deploy/docker-compose.local.yml：本地目录持久化，推荐生产使用。
• deploy/docker-compose.yml：命名卷版本。
• deploy/docker-compose.standalone.yml：外部 PostgreSQL/Redis。
• deploy/.env.example：Docker 环境变量全集。
• deploy/config.example.yaml：YAML 配置全集。
• deploy/install.sh：Linux Release 安装、升级和回退。
• deploy/Caddyfile：反向代理示例。

测试入口

# 后端 unit / integration
make -C backend test-unit
make -C backend test-integration

# 后端 lint
cd backend && golangci-lint run ./...

# 前端基础门禁
make test-frontend

# 全量前端 Vitest
pnpm --dir frontend test:run

CI 中前端默认只运行一组关键 Vitest 文件；涉及非关键页面时，开发者应主动运行对应 spec 或全量测试。