统一公开 API 为 /api/v1 前缀 #21

2026-07-22T08:49:33+08:00

easyai commented

2026-07-22 08:49:33 +08:00

背景

公开调用此前同时暴露 /gateway-api、/v1、无版本路径、/kling、/upload 和 /api/v3 等多种入口，接入方无法只替换 Base URL。

变更

将公开健康检查、OpenAPI、通用生成、Gemini、可灵 V1/V2、火山兼容和任务接口统一发布在 /api/v1/...。
历史入口继续作为兼容别名运行，但不再进入 OpenAPI 和新接入文档。
/api/v1 通用生成默认返回兼容同步结果，X-Async: true 继续显式启用异步，不要求修改原请求体。
增加完整公开接口清单，并让清单与 OpenAPI 71 个方法机器比对一致。
更新容器和宿主 Nginx 规则、健康检查、Web 文档与接入手册。
修复未配置 SSF 时类型化 nil 导致的 panic；未启用端点明确返回 404。
将 fast-uri 升级到 3.1.4，消除发布门禁中的高危漏洞。

兼容性与风险

旧路径不删除，现有调用无需立即迁移。
/api/admin、/api/workspace、/api/playground 仍是管理端或 BFF，不纳入公开 API Base URL。
/metrics 与 /static 不属于公开 API。
宿主 Nginx 发布时需先备份配置并执行 nginx -t，失败则不 reload。

验证

cd apps/api && go vet ./... && go test ./... && govulncheck ./...
pnpm install --frozen-lockfile、pnpm openapi、pnpm lint、pnpm test、pnpm build
pnpm audit --audit-level high：高危 0
Compose、镜像构建脚本、迁移安全、流水线和 SemVer 门禁通过
一次性本地 PostgreSQL + 当前 API 二进制真实 HTTP 冒烟：公开 OpenAPI 71 个方法路由失败 0；注册、登录、API Key 创建与鉴权成功；Chat、图片同步/异步、视频、Gemini 与可灵兼容模拟链路通过。

## 背景公开调用此前同时暴露 `/gateway-api`、`/v1`、无版本路径、`/kling`、`/upload` 和 `/api/v3` 等多种入口，接入方无法只替换 Base URL。 ## 变更 - 将公开健康检查、OpenAPI、通用生成、Gemini、可灵 V1/V2、火山兼容和任务接口统一发布在 `/api/v1/...`。 - 历史入口继续作为兼容别名运行，但不再进入 OpenAPI 和新接入文档。 - `/api/v1` 通用生成默认返回兼容同步结果，`X-Async: true` 继续显式启用异步，不要求修改原请求体。 - 增加完整公开接口清单，并让清单与 OpenAPI 71 个方法机器比对一致。 - 更新容器和宿主 Nginx 规则、健康检查、Web 文档与接入手册。 - 修复未配置 SSF 时类型化 nil 导致的 panic；未启用端点明确返回 404。 - 将 `fast-uri` 升级到 3.1.4，消除发布门禁中的高危漏洞。 ## 兼容性与风险 - 旧路径不删除，现有调用无需立即迁移。 - `/api/admin`、`/api/workspace`、`/api/playground` 仍是管理端或 BFF，不纳入公开 API Base URL。 - `/metrics` 与 `/static` 不属于公开 API。 - 宿主 Nginx 发布时需先备份配置并执行 `nginx -t`，失败则不 reload。 ## 验证 - `cd apps/api && go vet ./... && go test ./... && govulncheck ./...` - `pnpm install --frozen-lockfile`、`pnpm openapi`、`pnpm lint`、`pnpm test`、`pnpm build` - `pnpm audit --audit-level high`：高危 0 - Compose、镜像构建脚本、迁移安全、流水线和 SemVer 门禁通过 - 一次性本地 PostgreSQL + 当前 API 二进制真实 HTTP 冒烟：公开 OpenAPI 71 个方法路由失败 0；注册、登录、API Key 创建与鉴权成功；Chat、图片同步/异步、视频、Gemini 与可灵兼容模拟链路通过。

easyai added 3 commits 2026-07-22 08:49:33 +08:00

feat(api): 统一公开接口为 /api/v1 前缀 7c5a999e32

将通用生成、Gemini、可灵、火山、健康检查与 OpenAPI 的推荐入口统一到 /api/v1，并保留历史路径作为兼容别名。同步更新代理配置、接入文档、接口清单和前缀回归测试。\n\n验证：go vet ./...；go test ./...；pnpm openapi；pnpm lint；pnpm test；pnpm build；公开 OpenAPI 71 个方法与接口清单机器比对一致。

fix(identity): 避免未配置 SSF 时触发空指针 5432760cf7

SecurityEventReceiver 不再把空 ConnectionManager 包装为非空接口；未启用 SSF 时公开端点明确返回 404。补充运行时和 HTTP 回归测试。\n\n验证：go test ./internal/identityruntime ./internal/httpapi。

chore(deps): 升级 fast-uri 修复高危漏洞

ci / verify (pull_request) Failing after 3m45s

a8d1c550ef

将构建链路中的 fast-uri 锁定到 3.1.4，修复 host confusion 高危公告，不改变应用运行时依赖。\n\n验证：pnpm install --frozen-lockfile；pnpm audit --audit-level high；pnpm lint；pnpm test；pnpm build。

easyai added 1 commit 2026-07-22 08:50:58 +08:00

fix(deploy): 使用 /api/v1 执行发布健康检查

ci / verify (pull_request) Failing after 3m41s

eb37b568ae

将 Compose 发布脚本的 API、就绪和 Web 反代探针切换到统一公开前缀，避免发布完成后仍只验证旧兼容入口。\n\n验证：bash -n；ShellCheck；ci-build-images-test.sh；pipeline-test.sh。

easyai added 1 commit 2026-07-22 08:56:38 +08:00

test(api): 等待异步任务完成后校验结果

ci / verify (pull_request) Successful in 12m38s

a23b28c27d

真实队列环境中 X-Async 请求会先返回 queued。集成测试改为轮询任务完成并重新读取详情，避免把正确的异步受理状态误判为失败。

easyai merged commit 9872068596 into main

2026-07-22 09:10:10 +08:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: BCAI/easyai-ai-gateway#21