BCAI/easyai-ai-gateway
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(merge): 整合最新 main 与统一认证变更
All checks were successful
ci / verify (pull_request) Successful in 12m18s
Details

Browse Source 
合并远端生产 CI、依赖与 API 文档改动，保留统一认证和 SSF 能力。由于远端生产基线已占用 0062，将尚未发布的身份迁移整理为 0063 至 0068 的最终增量 Schema，移除仅用于开发期草稿升级的破坏性迁移步骤。

验证：go test ./...。其余生产门禁在合并提交后继续执行。
This commit is contained in:
chengcheng 2026-07-17 19:06:37 +08:00
commit 4426eeccf7
100 changed files with 9673 additions and 1799 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

109
.gitea/workflows/ci.yml Normal file
View File

@ -0,0 +1,109 @@
name: ci
on:
push:
branches: [main]
pull_request:
branches: [main]
jobs:
verify:
runs-on: easyai-gateway-ci-unprivileged-v2
env:
TRIVY_DB_REPOSITORY: ghcr.m.daocloud.io/aquasecurity/trivy-db:2
steps:
- name: Checkout without external Actions
env:
CI_REPOSITORY: ${{ github.repository }}
CI_SERVER_URL: ${{ github.server_url }}
CI_SHA: ${{ github.sha }}
CI_JOB_TOKEN: ${{ github.token }}
CI_EVENT_BEFORE: ${{ github.event.before }}
CI_PR_BASE_SHA: ${{ github.event.pull_request.base.sha }}
run: |
set -eu
test -n "$CI_JOB_TOKEN"
authorization=$(printf 'x-access-token:%s' "$CI_JOB_TOKEN" | base64 | tr -d '\n')
git init .
git -c "http.extraHeader=AUTHORIZATION: basic $authorization" \
fetch --no-tags "$CI_SERVER_URL/$CI_REPOSITORY.git" "$CI_SHA"
for comparison_sha in "$CI_EVENT_BEFORE" "$CI_PR_BASE_SHA"; do
case "$comparison_sha" in
[0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f]*)
if test "${#comparison_sha}" -eq 40 && \
test "$comparison_sha" != 0000000000000000000000000000000000000000; then
git -c "http.extraHeader=AUTHORIZATION: basic $authorization" \
fetch --no-tags "$CI_SERVER_URL/$CI_REPOSITORY.git" "$comparison_sha"
fi
;;
esac
done
unset authorization CI_JOB_TOKEN
test ! -f .git/shallow
git checkout --detach "$CI_SHA"
test "$(git rev-parse HEAD)" = "$CI_SHA"
- name: Verify pinned host toolchains
run: |
go version
node --version
pnpm --version
docker-compose version
shellcheck --version
trivy --version
govulncheck -version
- name: Verify production migration safety
env:
CI_EVENT_NAME: ${{ github.event_name }}
CI_EVENT_BEFORE: ${{ github.event.before }}
CI_PR_BASE_SHA: ${{ github.event.pull_request.base.sha }}
run: |
production_base=$(cat deploy/ci/production-migration-base)
immutable_base=$CI_EVENT_BEFORE
if test "$CI_EVENT_NAME" = pull_request; then
immutable_base=$CI_PR_BASE_SHA
fi
case "$immutable_base" in
[0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f]*)
test "${#immutable_base}" -eq 40
test "$immutable_base" != 0000000000000000000000000000000000000000
;;
*) exit 1 ;;
esac
git merge-base --is-ancestor "$immutable_base" HEAD
node ./scripts/ci-validate-migrations.mjs \
"$production_base" "$immutable_base"
- name: Verify Go formatting
run: |
unformatted=$(gofmt -l apps/api)
test -z "$unformatted" || {
printf 'Go files require gofmt:\n%s\n' "$unformatted" >&2
exit 1
}
- name: Verify Go code
working-directory: apps/api
run: |
go vet ./...
go test ./...
govulncheck ./...
- run: pnpm install --frozen-lockfile
- run: pnpm lint
- run: pnpm test
- run: pnpm build
- name: Audit JavaScript dependencies
run: pnpm audit --audit-level high
- name: Validate deployment configuration
run: |
docker-compose -f docker-compose.yml config --quiet
shellcheck scripts/ci-build-images.sh scripts/ci-validate-semver.sh \
scripts/provision-ci-runner.sh tests/ci/ci-build-images-test.sh \
tests/ci/migrations-test.sh tests/ci/pipeline-test.sh \
tests/ci/semver-test.sh
./tests/ci/ci-build-images-test.sh
./tests/ci/migrations-test.sh
./tests/ci/pipeline-test.sh
./tests/ci/semver-test.sh
- name: Scan repository
run: |
trivy fs --scanners vuln,secret,misconfig --severity HIGH,CRITICAL \
--ignore-unfixed --exit-code 1 --timeout 15m --skip-dirs .git \
--skip-dirs node_modules .

94
.gitea/workflows/release-ci.yml Normal file
View File

@ -0,0 +1,94 @@
name: release-ci
on:
push:
tags: ['v*']
jobs:
verify-tag:
runs-on: easyai-gateway-ci-unprivileged-v2
env:
TRIVY_DB_REPOSITORY: ghcr.m.daocloud.io/aquasecurity/trivy-db:2
steps:
- name: Checkout without external Actions
env:
CI_REPOSITORY: ${{ github.repository }}
CI_SERVER_URL: ${{ github.server_url }}
CI_SHA: ${{ github.sha }}
CI_JOB_TOKEN: ${{ github.token }}
run: |
set -eu
test -n "$CI_JOB_TOKEN"
authorization=$(printf 'x-access-token:%s' "$CI_JOB_TOKEN" | base64 | tr -d '\n')
git init .
git -c "http.extraHeader=AUTHORIZATION: basic $authorization" \
fetch --no-tags "$CI_SERVER_URL/$CI_REPOSITORY.git" "$CI_SHA"
unset authorization CI_JOB_TOKEN
test ! -f .git/shallow
git checkout --detach FETCH_HEAD
- name: Verify pinned host toolchains
run: |
go version
node --version
pnpm --version
docker-compose version
shellcheck --version
trivy --version
govulncheck -version
- name: Verify release tag ancestry
env:
CI_REPOSITORY: ${{ github.repository }}
CI_SERVER_URL: ${{ github.server_url }}
CI_SHA: ${{ github.sha }}
CI_JOB_TOKEN: ${{ github.token }}
run: |
set -eu
tag_name=${GITHUB_REF#refs/tags/}
./scripts/ci-validate-semver.sh "$tag_name"
authorization=$(printf 'x-access-token:%s' "$CI_JOB_TOKEN" | base64 | tr -d '\n')
git -c "http.extraHeader=AUTHORIZATION: basic $authorization" \
fetch --no-tags "$CI_SERVER_URL/$CI_REPOSITORY.git" \
+refs/heads/main:refs/remotes/origin/main
unset authorization CI_JOB_TOKEN
test ! -f .git/shallow
test "$(git rev-parse HEAD)" = "$CI_SHA"
git merge-base --is-ancestor "$CI_SHA" refs/remotes/origin/main
- name: Verify production migration safety
run: |
production_base=$(cat deploy/ci/production-migration-base)
node ./scripts/ci-validate-migrations.mjs "$production_base"
- name: Verify Go formatting
run: |
unformatted=$(gofmt -l apps/api)
test -z "$unformatted" || {
printf 'Go files require gofmt:\n%s\n' "$unformatted" >&2
exit 1
}
- name: Verify Go code
working-directory: apps/api
run: |
go vet ./...
go test ./...
govulncheck ./...
- run: pnpm install --frozen-lockfile
- run: pnpm lint
- run: pnpm test
- run: pnpm build
- name: Audit JavaScript dependencies
run: pnpm audit --audit-level high
- name: Validate deployment configuration
run: |
docker-compose -f docker-compose.yml config --quiet
shellcheck scripts/ci-build-images.sh scripts/ci-validate-semver.sh \
scripts/provision-ci-runner.sh tests/ci/ci-build-images-test.sh \
tests/ci/migrations-test.sh tests/ci/pipeline-test.sh \
tests/ci/semver-test.sh
./tests/ci/ci-build-images-test.sh
./tests/ci/migrations-test.sh
./tests/ci/pipeline-test.sh
./tests/ci/semver-test.sh
- name: Scan repository
run: |
trivy fs --scanners vuln,secret,misconfig --severity HIGH,CRITICAL \
--ignore-unfixed --exit-code 1 --timeout 15m --skip-dirs .git \
--skip-dirs node_modules .

1
.gitignore vendored
View File

@ -10,6 +10,7 @@ node_modules/
*.log
apps/api/bin/
apps/api/gateway
apps/api/tmp/
apps/api/data/

48
AGENTS.md Normal file
View File

@ -0,0 +1,48 @@
# EasyAI AI Gateway 智能体协作规则
本文件是本仓库内 AI 编码智能体的项目级执行约束。开始工作前必须先阅读本文件，并以实际代码、测试和运行结果作为结论依据。
## 协作语言
1. 面向用户的回复、进度更新、验收报告、代码审查意见、Issue、PR 标题和 PR 描述默认使用中文。
2. Git 提交信息使用 `<type>(<scope>): <中文摘要>` 格式，`scope` 可省略。
3. `type` 使用小写英文，可选值为 `feat`、`fix`、`docs`、`test`、`refactor`、`perf`、`build`、`ci`、`chore`、`revert`。
4. 提交摘要和正文必须使用中文；专有名词、协议名称、命令、路径、代码标识符和第三方原始错误可保留原文。
5. 摘要应简洁明确，末尾不加句号，不得使用“更新代码”“修复问题”等无法说明意图的模糊描述。
6. 非简单变更应在提交正文或 PR 描述中用中文说明原因、影响、风险和验证结果。
## 仓库边界
1. 后端位于 `apps/api`，前端位于 `apps/web`，共享 TypeScript 契约位于 `packages/contracts`。
2. 修改 HTTP 接口、请求或响应类型后，必须执行 `pnpm openapi` 并提交匹配的 OpenAPI 产物。
3. 数据库迁移只能新增，禁止修改已经进入生产基线的历史迁移；迁移必须通过生产迁移安全检查。
4. 不得把 `.env`、密码、Secret、Token、授权码、私钥或生产凭据提交到 Git、日志、测试输出或验收证据中。
5. 当前工作区存在用户改动时必须保留，不得覆盖、清理、重置或混入当前任务提交；需要隔离时使用独立分支、克隆或 worktree。
## 验证要求
根据改动范围执行最小充分验证；准备合并或发布时执行完整门禁：
```bash
cd apps/api && go vet ./... && go test ./... && govulncheck ./...
pnpm install --frozen-lockfile
pnpm lint
pnpm test
pnpm build
pnpm audit --audit-level high
docker compose -f docker-compose.yml config --quiet
./tests/ci/ci-build-images-test.sh
./tests/ci/migrations-test.sh
./tests/ci/pipeline-test.sh
./tests/ci/semver-test.sh
```
修改 Shell 脚本后还必须执行 `bash -n` 和 ShellCheck。修改 Go 文件后必须确认 `gofmt -l` 没有输出。
## Git 与 CI/CD
1. 一个提交只包含一个逻辑变更，提交前检查暂存差异并确认不含敏感信息。
2. `main` 只能通过短生命周期分支和 PR 合并，禁止直接推送或强制推送。
3. PR 必须通过精确的 `ci / verify (pull_request)` 状态后才能合并；合并后还要确认同一 SHA 的 `ci / verify (push)` 成功。
4. 生产版本仅使用稳定 SemVer `vMAJOR.MINOR.PATCH` 标签，并同时要求 `release-ci / verify-tag (push)` 成功。
5. 未验证 protected tag、发布账本、数据库备份、健康检查和回滚路径时，不得声称 CI/CD 或生产发布已经完成。

4
README.md
View File

@ -105,6 +105,10 @@ Web 容器的 Nginx 配置通过 bind mount 挂载自仓库文件 [docker/nginx.
docker compose -f docker-compose.yml restart web
```
## 生产 CI/CD
Gitea Actions 会在隔离的 rootless DinD Runner 中对 Pull Request、`main` Push 和版本 Tag 执行完整质量门禁；Tag 使用独立的 `release-ci / verify-tag (push)` context，不能复用旧的 `main` 成功状态。源码 Job 没有宿主 Docker、`sudo` 或生产部署权限。部署仓的 root-owned dispatcher 只在相同 SHA 的 `main` 与 Tag context 都成功后，用固定命令构建并扫描镜像，再以 Registry digest 发布 `ai.51easyai.com`。安装 Runner、Fork PR 审批、发布验证和回滚步骤见 [生产 CI/CD 运行手册](docs/runbooks/production-ci-cd.md)，信任边界见 [ADR-001](docs/decisions/001-production-cicd.md)。
Compose 默认使用独立容器数据库 `postgres:18-alpine`，数据卷会保留在 `postgres_data` 和 `api_data`。为避免本地开发 `.env` 中的 `localhost` 数据库地址污染容器部署，compose 使用 `AI_GATEWAY_COMPOSE_*` 变量作为容器部署专用覆盖，例如：
```bash

210
apps/api/cmd/migrate/identity_pairing_start_reservation_migration_integration_test.go
View File

@ -10,149 +10,45 @@ import (
"github.com/google/uuid"
"github.com/jackc/pgx/v5/pgconn"
"github.com/jackc/pgx/v5/pgxpool"
)
const identityPairingStartReservationUpgradeMigration = "../../migrations/0073_identity_pairing_start_reservation_upgrade.sql"
const identityPairingStartReservationMigration = "../../migrations/0068_identity_pairing_start_reservation.sql"
func TestIdentityPairingStartReservationUpgradeMigrationDefinesCurrentLifecycle(t *testing.T) {
payload, err := os.ReadFile(identityPairingStartReservationUpgradeMigration)
func TestIdentityPairingStartReservationMigrationDefinesCurrentLifecycle(t *testing.T) {
payload, err := os.ReadFile(identityPairingStartReservationMigration)
if err != nil {
t.Fatal(err)
}
content := strings.ToLower(string(payload))
for _, required := range []string{
"add column if not exists state text",
"add column if not exists revision_id uuid",
"add column if not exists updated_at timestamptz",
"alter column state set not null",
"state text not null default 'starting'",
"revision_id uuid unique references gateway_identity_configuration_revisions",
"updated_at timestamptz not null default now()",
"gateway_identity_pairing_start_state_check",
"foreign key (revision_id)",
"idx_gateway_identity_pairing_start_revision_unique",
"idx_gateway_identity_pairing_start_expiry",
"canonical_pairing",
"on conflict (singleton) do update",
"on conflict do nothing",
} {
if !strings.Contains(content, required) {
t.Fatalf("identity pairing start reservation upgrade migration is missing %q", required)
t.Fatalf("identity pairing start reservation migration is missing %q", required)
}
}
for _, forbidden := range []string{"exchange_token text", "client_secret", "machine_secret", "secret_value"} {
for _, forbidden := range []string{"exchange_token text", "client_secret", "machine_secret", "secret_value", "drop ", "do $"} {
if strings.Contains(content, forbidden) {
t.Fatalf("identity pairing start reservation upgrade migration stores forbidden value field %q", forbidden)
t.Fatalf("identity pairing start reservation migration contains forbidden content %q", forbidden)
}
}
}
func TestIdentityPairingStartReservationUpgradeMigratesLegacyShapeAndIsIdempotent(t *testing.T) {
func TestIdentityPairingStartReservationMigrationSeedsOutstandingPairing(t *testing.T) {
pool := newIdentityMigrationPostgresTestSchema(t)
ctx := context.Background()
applyIdentityPairingStartReservationPrerequisites(t, ctx, pool)
revisionID, pairingID, pairingExpiresAt := seedOutstandingIdentityPairingForReservationMigration(t, ctx, pool)
legacyAttemptID := uuid.NewString()
if _, err := pool.Exec(ctx, `
CREATE TABLE gateway_identity_pairing_start_reservation (
singleton boolean PRIMARY KEY DEFAULT true CHECK (singleton),
attempt_id uuid NOT NULL UNIQUE,
expires_at timestamptz NOT NULL,
created_at timestamptz NOT NULL DEFAULT now()
)`); err != nil {
t.Fatalf("create legacy pairing start reservation: %v", err)
}
if _, err := pool.Exec(ctx, `
INSERT INTO gateway_identity_pairing_start_reservation(singleton,attempt_id,expires_at)
VALUES(true,$1::uuid,now()+interval '2 minutes')`, legacyAttemptID); err != nil {
t.Fatalf("seed legacy pairing start reservation: %v", err)
}
applyIdentityMigrationTestFile(t, ctx, pool, identityPairingStartReservationUpgradeMigration)
assertCurrentIdentityPairingStartReservation(t, ctx, pool, pairingID, revisionID, pairingExpiresAt)
assertIdentityPairingStartReservationSchema(t, ctx, pool)
// Migration runners apply each version once, but a repeat execution proves
// that recovery from an interrupted/manual rollout does not duplicate state.
applyIdentityMigrationTestFile(t, ctx, pool, identityPairingStartReservationUpgradeMigration)
assertCurrentIdentityPairingStartReservation(t, ctx, pool, pairingID, revisionID, pairingExpiresAt)
assertIdentityPairingStartReservationSchema(t, ctx, pool)
}
func TestIdentityPairingStartReservationUpgradePreservesLegacyStartingLease(t *testing.T) {
pool := newIdentityMigrationPostgresTestSchema(t)
ctx := context.Background()
applyIdentityPairingStartReservationPrerequisites(t, ctx, pool)
attemptID := uuid.NewString()
expiresAt := time.Now().UTC().Add(2 * time.Minute).Truncate(time.Microsecond)
if _, err := pool.Exec(ctx, `
CREATE TABLE gateway_identity_pairing_start_reservation (
singleton boolean PRIMARY KEY DEFAULT true CHECK (singleton),
attempt_id uuid NOT NULL UNIQUE,
expires_at timestamptz NOT NULL,
created_at timestamptz NOT NULL DEFAULT now()
)`); err != nil {
t.Fatalf("create legacy pairing start reservation: %v", err)
}
if _, err := pool.Exec(ctx, `
INSERT INTO gateway_identity_pairing_start_reservation(singleton,attempt_id,expires_at)
VALUES(true,$1::uuid,$2)`, attemptID, expiresAt); err != nil {
t.Fatalf("seed legacy starting reservation: %v", err)
}
applyIdentityMigrationTestFile(t, ctx, pool, identityPairingStartReservationUpgradeMigration)
applyIdentityMigrationTestFile(t, ctx, pool, identityPairingStartReservationUpgradeMigration)
var gotAttemptID, state string
var revisionID *string
var gotExpiresAt, updatedAt time.Time
if err := pool.QueryRow(ctx, `
SELECT attempt_id::text,state,revision_id::text,expires_at,updated_at
FROM gateway_identity_pairing_start_reservation`).
Scan(&gotAttemptID, &state, &revisionID, &gotExpiresAt, &updatedAt); err != nil {
t.Fatalf("read upgraded legacy starting reservation: %v", err)
}
if gotAttemptID != attemptID || state != "starting" || revisionID != nil ||
!gotExpiresAt.Equal(expiresAt) || updatedAt.IsZero() {
t.Fatalf("unexpected upgraded starting reservation attempt=%q state=%q revision=%v expires=%v updated=%v",
gotAttemptID, state, revisionID, gotExpiresAt, updatedAt)
}
_, err := pool.Exec(ctx, `UPDATE gateway_identity_pairing_start_reservation SET state='paired'`)
requireIdentityPairingStartReservationMigrationCode(t, err, "23514", "paired reservation without revision")
}
func TestIdentityPairingStartReservationUpgradeAcceptsFresh0071Schema(t *testing.T) {
pool := newIdentityMigrationPostgresTestSchema(t)
ctx := context.Background()
applyIdentityPairingStartReservationPrerequisites(t, ctx, pool)
revisionID, pairingID, pairingExpiresAt := seedOutstandingIdentityPairingForReservationMigration(t, ctx, pool)
applyIdentityMigrationTestFile(t, ctx, pool, "../../migrations/0071_identity_pairing_start_reservation.sql")
assertCurrentIdentityPairingStartReservation(t, ctx, pool, pairingID, revisionID, pairingExpiresAt)
applyIdentityMigrationTestFile(t, ctx, pool, identityPairingStartReservationUpgradeMigration)
applyIdentityMigrationTestFile(t, ctx, pool, identityPairingStartReservationUpgradeMigration)
assertCurrentIdentityPairingStartReservation(t, ctx, pool, pairingID, revisionID, pairingExpiresAt)
assertIdentityPairingStartReservationSchema(t, ctx, pool)
}
func applyIdentityPairingStartReservationPrerequisites(t *testing.T, ctx context.Context, pool *pgxpool.Pool) {
t.Helper()
for _, migration := range []string{
"../../migrations/0067_identity_configuration_revisions.sql",
"../../migrations/0068_identity_onboarding_exchanges.sql",
"../../migrations/0069_identity_pairing_cancellation.sql",
"../../migrations/0065_identity_configuration_revisions.sql",
"../../migrations/0066_identity_onboarding_exchanges.sql",
} {
applyIdentityMigrationTestFile(t, ctx, pool, migration)
}
}
func seedOutstandingIdentityPairingForReservationMigration(
t *testing.T,
ctx context.Context,
pool *pgxpool.Pool,
) (string, string, time.Time) {
t.Helper()
revisionID := uuid.NewString()
pairingID := uuid.NewString()
expiresAt := time.Now().UTC().Add(30 * time.Minute).Truncate(time.Microsecond)
@ -170,79 +66,31 @@ INSERT INTO gateway_identity_onboarding_exchanges (
pairingID, revisionID, uuid.NewString(), "identity-exchange-"+pairingID, expiresAt); err != nil {
t.Fatalf("seed identity exchange for pairing reservation migration: %v", err)
}
return revisionID, pairingID, expiresAt
}
func assertCurrentIdentityPairingStartReservation(
t *testing.T,
ctx context.Context,
pool *pgxpool.Pool,
wantAttemptID string,
wantRevisionID string,
wantExpiresAt time.Time,
) {
t.Helper()
var count int
var attemptID, state, revisionID string
var expiresAt, updatedAt time.Time
applyIdentityMigrationTestFile(t, ctx, pool, identityPairingStartReservationMigration)
var attemptID, state, reservedRevisionID string
var gotExpiresAt, updatedAt time.Time
if err := pool.QueryRow(ctx, `
SELECT count(*) OVER (),attempt_id::text,state,revision_id::text,expires_at,updated_at
FROM gateway_identity_pairing_start_reservation`).
Scan(&count, &attemptID, &state, &revisionID, &expiresAt, &updatedAt); err != nil {
t.Fatalf("read upgraded pairing start reservation: %v", err)
SELECT attempt_id::text,state,revision_id::text,expires_at,updated_at
FROM gateway_identity_pairing_start_reservation`).Scan(
&attemptID, &state, &reservedRevisionID, &gotExpiresAt, &updatedAt,
); err != nil {
t.Fatalf("read pairing start reservation: %v", err)
}
if count != 1 || attemptID != wantAttemptID || state != "paired" || revisionID != wantRevisionID ||
!expiresAt.Equal(wantExpiresAt) || updatedAt.IsZero() {
t.Fatalf("unexpected upgraded pairing reservation count=%d attempt=%q state=%q revision=%q expires=%v updated=%v",
count, attemptID, state, revisionID, expiresAt, updatedAt)
}
}
func assertIdentityPairingStartReservationSchema(t *testing.T, ctx context.Context, pool *pgxpool.Pool) {
t.Helper()
for _, column := range []struct {
name string
wantDefaultFragment string
}{
{name: "state", wantDefaultFragment: "starting"},
{name: "updated_at", wantDefaultFragment: "now()"},
} {
var nullable, defaultExpression string
if err := pool.QueryRow(ctx, `
SELECT is_nullable,COALESCE(column_default,'')
FROM information_schema.columns
WHERE table_schema=current_schema()
AND table_name='gateway_identity_pairing_start_reservation'
AND column_name=$1`, column.name).Scan(&nullable, &defaultExpression); err != nil {
t.Fatalf("read upgraded pairing reservation column %s: %v", column.name, err)
}
if nullable != "NO" || !strings.Contains(defaultExpression, column.wantDefaultFragment) {
t.Fatalf("pairing reservation column %s nullable=%q default=%q", column.name, nullable, defaultExpression)
}
}
var expiryIndex, revisionIndex string
if err := pool.QueryRow(ctx, `SELECT pg_get_indexdef('idx_gateway_identity_pairing_start_expiry'::regclass)`).
Scan(&expiryIndex); err != nil {
t.Fatalf("read pairing reservation expiry index: %v", err)
}
if err := pool.QueryRow(ctx, `SELECT pg_get_indexdef('idx_gateway_identity_pairing_start_revision_unique'::regclass)`).
Scan(&revisionIndex); err != nil {
t.Fatalf("read pairing reservation revision index: %v", err)
}
if !strings.Contains(strings.ToLower(expiryIndex), "(state, expires_at)") ||
!strings.Contains(strings.ToLower(revisionIndex), "unique") ||
!strings.Contains(strings.ToLower(revisionIndex), "(revision_id)") {
t.Fatalf("unexpected pairing reservation indexes expiry=%q revision=%q", expiryIndex, revisionIndex)
if attemptID != pairingID || state != "paired" || reservedRevisionID != revisionID ||
!gotExpiresAt.Equal(expiresAt) || updatedAt.IsZero() {
t.Fatalf("unexpected pairing reservation attempt=%q state=%q revision=%q expires=%v updated=%v",
attemptID, state, reservedRevisionID, gotExpiresAt, updatedAt)
}
_, err := pool.Exec(ctx, `UPDATE gateway_identity_pairing_start_reservation SET state='starting'`)
requireIdentityPairingStartReservationMigrationCode(t, err, "23514", "starting reservation with revision")
requirePairingReservationMigrationCode(t, err, "23514", "starting reservation with revision")
_, err = pool.Exec(ctx, `UPDATE gateway_identity_pairing_start_reservation SET revision_id=$1::uuid`, uuid.NewString())
requireIdentityPairingStartReservationMigrationCode(t, err, "23503", "reservation with unknown revision")
requirePairingReservationMigrationCode(t, err, "23503", "reservation with unknown revision")
}
func requireIdentityPairingStartReservationMigrationCode(t *testing.T, err error, wantCode, operation string) {
func requirePairingReservationMigrationCode(t *testing.T, err error, wantCode, operation string) {
t.Helper()
if err == nil {
t.Fatalf("%s unexpectedly satisfied migration constraints", operation)

12
apps/api/cmd/migrate/main.go
View File

@ -24,6 +24,10 @@ func main() {
os.Exit(1)
}
defer conn.Close(ctx)
if _, err := conn.Exec(ctx, "SET standard_conforming_strings = on"); err != nil {
logger.Error("enforce standard SQL string semantics failed", "error", err)
os.Exit(1)
}
if _, err := conn.Exec(ctx, `
CREATE TABLE IF NOT EXISTS schema_migrations (
@ -64,6 +68,14 @@ CREATE TABLE IF NOT EXISTS schema_migrations (
logger.Error("begin migration failed", "version", version, "error", err)
os.Exit(1)
}
// Pin string parsing semantics inside every migration transaction. A
// previous migration may have changed the session GUC, while each file is
// parsed and executed independently.
if _, err := tx.Exec(ctx, "SET LOCAL standard_conforming_strings = on"); err != nil {
_ = tx.Rollback(ctx)
logger.Error("enforce migration SQL string semantics failed", "version", version, "error", err)
os.Exit(1)
}
if _, err := tx.Exec(ctx, string(sqlBytes)); err != nil {
_ = tx.Rollback(ctx)
logger.Error("execute migration failed", "version", version, "error", err)

94
apps/api/cmd/migrate/main_test.go
View File

@ -14,42 +14,41 @@ import (
"github.com/jackc/pgx/v5/pgxpool"
)
func TestSecurityEventIdempotencyRepairMigrationExists(t *testing.T) {
payload, err := os.ReadFile("../../migrations/0064_security_event_connection_idempotency_repair.sql")
func TestSecurityEventSchemaMigrationsDefineCurrentLifecycle(t *testing.T) {
streamPayload, err := os.ReadFile("../../migrations/0063_oidc_security_events.sql")
if err != nil {
t.Fatalf("read repair migration: %v", err)
t.Fatalf("read security event stream migration: %v", err)
}
sql := string(payload)
streamSQL := string(streamPayload)
for _, statement := range []string{
"CREATE TABLE IF NOT EXISTS gateway_security_event_connection_idempotency",
"CREATE INDEX IF NOT EXISTS idx_gateway_security_event_connection_idempotency_created",
} {
if !strings.Contains(sql, statement) {
t.Fatalf("repair migration is missing %q", statement)
}
}
}
func TestSecurityEventVerificationStateRepairMigrationExists(t *testing.T) {
payload, err := os.ReadFile("../../migrations/0065_security_event_verification_state_repair.sql")
if err != nil {
t.Fatalf("read verification state repair migration: %v", err)
}
sql := string(payload)
for _, statement := range []string{
"ADD COLUMN IF NOT EXISTS stream_status",
"ADD COLUMN IF NOT EXISTS created_at",
"CREATE TABLE IF NOT EXISTS gateway_security_event_stream_state",
"CREATE TABLE IF NOT EXISTS gateway_security_event_verification_challenges",
"CREATE INDEX IF NOT EXISTS idx_gateway_security_event_challenges_expiry",
} {
if !strings.Contains(sql, statement) {
t.Fatalf("verification state repair migration is missing %q", statement)
if !strings.Contains(streamSQL, statement) {
t.Fatalf("security event stream migration is missing %q", statement)
}
}
connectionPayload, err := os.ReadFile("../../migrations/0064_security_event_connections.sql")
if err != nil {
t.Fatalf("read security event connection migration: %v", err)
}
connectionSQL := string(connectionPayload)
for _, statement := range []string{
"CREATE TABLE IF NOT EXISTS gateway_security_event_connections",
"management_client_id text",
"management_credential_ref text",
"CREATE TABLE IF NOT EXISTS gateway_security_event_connection_idempotency",
} {
if !strings.Contains(connectionSQL, statement) {
t.Fatalf("security event connection migration is missing %q", statement)
}
}
}
func TestIdentityConfigurationRevisionMigrationDefinesSecretReferencesAndSingleActiveRevision(t *testing.T) {
payload, err := os.ReadFile("../../migrations/0067_identity_configuration_revisions.sql")
payload, err := os.ReadFile("../../migrations/0065_identity_configuration_revisions.sql")
if err != nil {
t.Fatal(err)
}
@ -58,6 +57,7 @@ func TestIdentityConfigurationRevisionMigrationDefinesSecretReferencesAndSingleA
"CREATE TABLE IF NOT EXISTS gateway_identity_configuration_revisions",
"machine_credential_ref text",
"session_encryption_key_ref text",
"security_event_configuration_url text",
"WHERE state = 'active'",
"CHECK (state IN ('draft','validated','active','superseded','failed'))",
} {
@ -73,7 +73,7 @@ func TestIdentityConfigurationRevisionMigrationDefinesSecretReferencesAndSingleA
}
func TestIdentityOnboardingExchangeMigrationStoresOnlySecretReferences(t *testing.T) {
payload, err := os.ReadFile("../../migrations/0068_identity_onboarding_exchanges.sql")
payload, err := os.ReadFile("../../migrations/0066_identity_onboarding_exchanges.sql")
if err != nil {
t.Fatal(err)
}
@ -81,7 +81,8 @@ func TestIdentityOnboardingExchangeMigrationStoresOnlySecretReferences(t *testin
for _, required := range []string{
"create table if not exists gateway_identity_onboarding_exchanges",
"exchange_token_ref text not null",
"security_event_configuration_url text",
"cleanup_status text not null default 'none'",
"security_event_credential_handoff_unsafe",
} {
if !strings.Contains(content, required) {
t.Fatalf("identity onboarding migration is missing %q", required)
@ -94,8 +95,8 @@ func TestIdentityOnboardingExchangeMigrationStoresOnlySecretReferences(t *testin
}
}
func TestIdentityPairingCancellationMigrationSeparatesCleanupLifecycle(t *testing.T) {
payload, err := os.ReadFile("../../migrations/0069_identity_pairing_cancellation.sql")
func TestIdentityOnboardingMigrationDefinesCancellationLifecycle(t *testing.T) {
payload, err := os.ReadFile("../../migrations/0066_identity_onboarding_exchanges.sql")
if err != nil {
t.Fatal(err)
}
@ -106,9 +107,6 @@ func TestIdentityPairingCancellationMigrationSeparatesCleanupLifecycle(t *testin
"cleanup_completed_at",
"idx_gateway_identity_onboarding_cleanup",
"last_error_category",
"set last_error_category = 'pairing_step_failed'",
"set local lock_timeout = '10s'",
"set local statement_timeout = '60s'",
} {
if !strings.Contains(content, required) {
t.Fatalf("identity pairing cancellation migration is missing %q", required)
@ -121,14 +119,14 @@ func TestIdentityPairingCancellationMigrationSeparatesCleanupLifecycle(t *testin
}
}
func TestIdentityPairingErrorCategoryUpgradeMigrationExists(t *testing.T) {
payload, err := os.ReadFile("../../migrations/0074_identity_pairing_error_categories.sql")
func TestIdentityOnboardingMigrationDefinesFinalErrorCategories(t *testing.T) {
payload, err := os.ReadFile("../../migrations/0066_identity_onboarding_exchanges.sql")
if err != nil {
t.Fatal(err)
}
content := strings.ToLower(string(payload))
for _, required := range []string{
"drop constraint if exists gateway_identity_onboarding_error_category_check",
"gateway_identity_onboarding_error_category_check",
"security_event_credential_handoff_unsafe",
"security_event_connection_binding_missing",
"security_event_connection_binding_unavailable",
@ -142,18 +140,14 @@ func TestIdentityPairingErrorCategoryUpgradeMigrationExists(t *testing.T) {
}
}
func TestIdentityPairingErrorCategoryUpgradeMigrationExecutesAgainstCurrentSchema(t *testing.T) {
func TestIdentityPairingErrorCategoriesExecuteAgainstCurrentSchema(t *testing.T) {
pool := newIdentityMigrationPostgresTestSchema(t)
ctx := context.Background()
for _, migration := range []string{
"../../migrations/0067_identity_configuration_revisions.sql",
"../../migrations/0068_identity_onboarding_exchanges.sql",
"../../migrations/0069_identity_pairing_cancellation.sql",
"../../migrations/0070_identity_secret_cleanup_queue.sql",
"../../migrations/0071_identity_pairing_start_reservation.sql",
"../../migrations/0072_identity_secret_cleanup_claim_lifecycle.sql",
"../../migrations/0073_identity_pairing_start_reservation_upgrade.sql",
"../../migrations/0074_identity_pairing_error_categories.sql",
"../../migrations/0065_identity_configuration_revisions.sql",
"../../migrations/0066_identity_onboarding_exchanges.sql",
"../../migrations/0067_identity_secret_cleanup_queue.sql",
"../../migrations/0068_identity_pairing_start_reservation.sql",
} {
applyIdentityMigrationTestFile(t, ctx, pool, migration)
}
@ -193,7 +187,7 @@ SET last_error_category='credential_secret_leaked' WHERE id=$1::uuid`, pairingID
}
func TestIdentitySecretCleanupQueueMigrationStoresOnlyReferences(t *testing.T) {
payload, err := os.ReadFile("../../migrations/0070_identity_secret_cleanup_queue.sql")
payload, err := os.ReadFile("../../migrations/0067_identity_secret_cleanup_queue.sql")
if err != nil {
t.Fatal(err)
}
@ -219,11 +213,11 @@ func TestIdentitySecretCleanupQueueMigrationStoresOnlyReferences(t *testing.T) {
}
}
func TestIdentityPairingCancellationMigrationExecutesAgainstLegacyData(t *testing.T) {
func TestIdentityPairingCancellationLifecycleRejectsPartialStates(t *testing.T) {
pool := newIdentityMigrationPostgresTestSchema(t)
ctx := context.Background()
applyIdentityMigrationTestFile(t, ctx, pool, "../../migrations/0067_identity_configuration_revisions.sql")
applyIdentityMigrationTestFile(t, ctx, pool, "../../migrations/0068_identity_onboarding_exchanges.sql")
applyIdentityMigrationTestFile(t, ctx, pool, "../../migrations/0065_identity_configuration_revisions.sql")
applyIdentityMigrationTestFile(t, ctx, pool, "../../migrations/0066_identity_onboarding_exchanges.sql")
revisionID, pairingID := uuid.NewString(), uuid.NewString()
if _, err := pool.Exec(ctx, `
@ -236,13 +230,11 @@ INSERT INTO gateway_identity_configuration_revisions (
if _, err := pool.Exec(ctx, `
INSERT INTO gateway_identity_onboarding_exchanges (
id,revision_id,remote_exchange_id,exchange_token_ref,status,remote_version,expires_at,last_error_category
) VALUES ($1::uuid,$2::uuid,$3::uuid,$4,'credentials_saved',4,now() + interval '30 minutes','secret_token_abcdef')`,
) VALUES ($1::uuid,$2::uuid,$3::uuid,$4,'credentials_saved',4,now() + interval '30 minutes','pairing_step_failed')`,
pairingID, revisionID, uuid.NewString(), "identity-exchange-"+pairingID); err != nil {
t.Fatalf("seed legacy onboarding exchange: %v", err)
}
applyIdentityMigrationTestFile(t, ctx, pool, "../../migrations/0069_identity_pairing_cancellation.sql")
var status, cleanupStatus, errorCategory string
var cancelledAt, cleanupCompletedAt *time.Time
if err := pool.QueryRow(ctx, `

9
apps/api/docs/embed.go Normal file
View File

@ -0,0 +1,9 @@
package docs
import _ "embed"
//go:embed swagger.json
var SwaggerJSON []byte
//go:embed swagger.yaml
var SwaggerYAML []byte

512
apps/api/docs/swagger.json
View File

@ -12,6 +12,47 @@
},
"basePath": "/",
"paths": {
"/api-docs-json": {
"get": {
"description": "返回当前构建内嵌的完整机器可读 Swagger JSON，供 Agent 在 SKILL references 未覆盖接口时查询。",
"produces": [
"application/json"
],
"tags": [
"agent-resources"
],
"summary": "获取 AI Gateway Swagger JSON",
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "object",
"additionalProperties": true
}
}
}
}
},
"/api-docs-yaml": {
"get": {
"description": "返回当前构建内嵌的完整机器可读 Swagger YAML。",
"produces": [
"application/yaml"
],
"tags": [
"agent-resources"
],
"summary": "获取 AI Gateway Swagger YAML",
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "string"
}
}
}
}
},
"/api/admin/access-rules": {
"get": {
"security": [
@ -5218,7 +5259,7 @@
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/httpapi.TaskRequest"
"$ref": "#/definitions/httpapi.ChatCompletionRequest"
}
}
],
@ -6078,6 +6119,58 @@
}
}
},
"/api/v1/public/skills/ai-gateway-ops-management/download": {
"get": {
"description": "下载可交给 Agent 使用的 ai-gateway-ops-management ZIP 包。",
"produces": [
"application/zip"
],
"tags": [
"agent-resources"
],
"summary": "下载 AI Gateway 运维管理 SKILL",
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "file"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/httpapi.ErrorEnvelope"
}
}
}
}
},
"/api/v1/public/skills/ai-gateway-ops-management/metadata": {
"get": {
"description": "返回公开运维管理 SKILL 的名称、版本、模块、下载文件名和机器可读接口文档路径。",
"produces": [
"application/json"
],
"tags": [
"agent-resources"
],
"summary": "获取 AI Gateway 运维管理 SKILL 元数据",
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/httpapi.SkillBundleMetadataResponse"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/httpapi.ErrorEnvelope"
}
}
}
}
},
"/api/v1/reranks": {
"post": {
"security": [
@ -6178,31 +6271,26 @@
"BearerAuth": []
}
],
"description": "网关任务接口按 model 选择平台模型；除 /api/v1/chat/completions 以外的 /api/v1 任务路径返回任务受理结果，OpenAI-compatible 路径同步返回兼容响应或 SSE 流。",
"description": "公开 OpenAI-compatible Responses 入口。模型声明 openai_responses 时原生转发，否则使用 Chat Completions 转换；store 缺省为 true。previous_response_id 严格绑定首次成功的平台模型和上游协议，链路不可用时不跨平台续接。未提供 previous_response_id 时由调用方管理完整状态，Gateway 以本轮 input/messages 为准且不追加本地历史。",
"consumes": [
"application/json"
],
"produces": [
"application/json"
"application/json",
"text/event-stream"
],
"tags": [
"tasks"
"responses"
],
"summary": "创建或执行 AI 任务",
"summary": "创建 OpenAI Responses",
"parameters": [
{
"type": "boolean",
"description": "true 时异步创建任务并返回 202",
"name": "X-Async",
"in": "header"
},
{
"description": "AI 任务请求，字段随任务类型变化",
"description": "Responses 请求；Chat 回退只支持自定义 function tools",
"name": "input",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/httpapi.TaskRequest"
"$ref": "#/definitions/httpapi.ResponsesRequest"
}
}
],
@ -6210,17 +6298,17 @@
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/httpapi.CompatibleResponse"
}
},
"202": {
"description": "Accepted",
"schema": {
"$ref": "#/definitions/httpapi.TaskAcceptedResponse"
"$ref": "#/definitions/httpapi.ResponsesCompatibleResponse"
},
"headers": {
"X-Gateway-Task-Id": {
"type": "string",
"description": "网关审计任务 ID"
}
}
},
"400": {
"description": "Bad Request",
"description": "invalid_previous_response_id / unsupported_response_tool / unsupported_response_parameter",
"schema": {
"$ref": "#/definitions/httpapi.ErrorEnvelope"
}
@ -6243,20 +6331,8 @@
"$ref": "#/definitions/httpapi.ErrorEnvelope"
}
},
"404": {
"description": "Not Found",
"schema": {
"$ref": "#/definitions/httpapi.ErrorEnvelope"
}
},
"429": {
"description": "Too Many Requests",
"schema": {
"$ref": "#/definitions/httpapi.ErrorEnvelope"
}
},
"502": {
"description": "Bad Gateway",
"503": {
"description": "response_chain_unavailable",
"schema": {
"$ref": "#/definitions/httpapi.ErrorEnvelope"
}
@ -7677,31 +7753,26 @@
"BearerAuth": []
}
],
"description": "网关任务接口按 model 选择平台模型；除 /api/v1/chat/completions 以外的 /api/v1 任务路径返回任务受理结果，OpenAI-compatible 路径同步返回兼容响应或 SSE 流。",
"description": "OpenAI-compatible Chat Completions 入口；仅接受官方字段及文档声明的 EasyAI 路由扩展，未知顶层字段返回 400 invalid_parameter。",
"consumes": [
"application/json"
],
"produces": [
"application/json"
"application/json",
"text/event-stream"
],
"tags": [
"tasks"
"chat"
],
"summary": "创建或执行 AI 任务",
"summary": "创建 OpenAI Chat Completions",
"parameters": [
{
"type": "boolean",
"description": "true 时异步创建任务并返回 202",
"name": "X-Async",
"in": "header"
},
{
"description": "AI 任务请求，字段随任务类型变化",
"description": "Chat Completions 请求",
"name": "input",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/httpapi.TaskRequest"
"$ref": "#/definitions/httpapi.ChatCompletionRequest"
}
}
],
@ -7709,17 +7780,11 @@
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/httpapi.CompatibleResponse"
}
},
"202": {
"description": "Accepted",
"schema": {
"$ref": "#/definitions/httpapi.TaskAcceptedResponse"
"$ref": "#/definitions/httpapi.ChatCompletionCompatibleResponse"
}
},
"400": {
"description": "Bad Request",
"description": "invalid_parameter",
"schema": {
"$ref": "#/definitions/httpapi.ErrorEnvelope"
}
@ -7742,12 +7807,6 @@
"$ref": "#/definitions/httpapi.ErrorEnvelope"
}
},
"404": {
"description": "Not Found",
"schema": {
"$ref": "#/definitions/httpapi.ErrorEnvelope"
}
},
"429": {
"description": "Too Many Requests",
"schema": {
@ -8959,31 +9018,26 @@
"BearerAuth": []
}
],
"description": "网关任务接口按 model 选择平台模型；除 /api/v1/chat/completions 以外的 /api/v1 任务路径返回任务受理结果，OpenAI-compatible 路径同步返回兼容响应或 SSE 流。",
"description": "OpenAI-compatible Chat Completions 入口；仅接受官方字段及文档声明的 EasyAI 路由扩展，未知顶层字段返回 400 invalid_parameter。",
"consumes": [
"application/json"
],
"produces": [
"application/json"
"application/json",
"text/event-stream"
],
"tags": [
"tasks"
"chat"
],
"summary": "创建或执行 AI 任务",
"summary": "创建 OpenAI Chat Completions",
"parameters": [
{
"type": "boolean",
"description": "true 时异步创建任务并返回 202",
"name": "X-Async",
"in": "header"
},
{
"description": "AI 任务请求，字段随任务类型变化",
"description": "Chat Completions 请求",
"name": "input",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/httpapi.TaskRequest"
"$ref": "#/definitions/httpapi.ChatCompletionRequest"
}
}
],
@ -8991,17 +9045,11 @@
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/httpapi.CompatibleResponse"
}
},
"202": {
"description": "Accepted",
"schema": {
"$ref": "#/definitions/httpapi.TaskAcceptedResponse"
"$ref": "#/definitions/httpapi.ChatCompletionCompatibleResponse"
}
},
"400": {
"description": "Bad Request",
"description": "invalid_parameter",
"schema": {
"$ref": "#/definitions/httpapi.ErrorEnvelope"
}
@ -9024,12 +9072,6 @@
"$ref": "#/definitions/httpapi.ErrorEnvelope"
}
},
"404": {
"description": "Not Found",
"schema": {
"$ref": "#/definitions/httpapi.ErrorEnvelope"
}
},
"429": {
"description": "Too Many Requests",
"schema": {
@ -10491,6 +10533,158 @@
}
}
},
"httpapi.ChatCompletionRequest": {
"type": "object",
"properties": {
"audio": {
"type": "object",
"additionalProperties": true
},
"frequency_penalty": {
"type": "number",
"example": 0
},
"function_call": {},
"functions": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
},
"logit_bias": {
"type": "object",
"additionalProperties": true
},
"logprobs": {
"type": "boolean"
},
"max_completion_tokens": {
"type": "integer",
"example": 512
},
"max_tokens": {
"type": "integer",
"example": 512
},
"messages": {
"type": "array",
"items": {
"$ref": "#/definitions/httpapi.ChatMessage"
}
},
"metadata": {
"type": "object",
"additionalProperties": true
},
"modalities": {
"type": "array",
"items": {
"type": "string"
}
},
"model": {
"type": "string",
"example": "gpt-4o-mini"
},
"moderation": {},
"n": {
"type": "integer",
"example": 1
},
"parallel_tool_calls": {
"type": "boolean"
},
"prediction": {},
"presence_penalty": {
"type": "number",
"example": 0
},
"prompt_cache_key": {
"type": "string"
},
"prompt_cache_options": {
"type": "object",
"additionalProperties": true
},
"prompt_cache_retention": {
"type": "string",
"enum": [
"in_memory",
"24h"
]
},
"reasoning_effort": {
"description": "ReasoningEffort 推理强度，OpenAI-compatible 请求字段；支持 none、minimal、low、medium、high、xhigh、max。供应商自定义取值由网关按平台适配。",
"type": "string",
"enum": [
"none",
"minimal",
"low",
"medium",
"high",
"xhigh",
"max"
],
"example": "medium"
},
"response_format": {},
"runMode": {
"type": "string",
"example": "simulation"
},
"safety_identifier": {
"type": "string"
},
"seed": {
"type": "integer"
},
"service_tier": {
"type": "string"
},
"stop": {},
"store": {
"type": "boolean"
},
"stream": {
"type": "boolean",
"example": false
},
"stream_options": {
"type": "object",
"additionalProperties": true
},
"temperature": {
"type": "number",
"example": 0.7
},
"tool_choice": {},
"tools": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
},
"top_logprobs": {
"type": "integer"
},
"top_p": {
"type": "number",
"example": 1
},
"user": {
"type": "string"
},
"verbosity": {
"type": "string"
},
"web_search_options": {
"type": "object",
"additionalProperties": true
}
}
},
"httpapi.ChatCompletionUsage": {
"type": "object",
"properties": {
@ -10526,14 +10720,19 @@
"httpapi.ChatMessage": {
"type": "object",
"properties": {
"content": {
"type": "string",
"example": "Hello"
"content": {},
"function_call": {},
"name": {
"type": "string"
},
"role": {
"type": "string",
"example": "user"
}
},
"tool_call_id": {
"type": "string"
},
"tool_calls": {}
}
},
"httpapi.ChatPromptTokensDetails": {
@ -10592,9 +10791,14 @@
"type": "string",
"example": "invalid json body"
},
"param": {},
"status": {
"type": "integer",
"example": 400
},
"type": {
"type": "string",
"example": "invalid_request_error"
}
}
},
@ -11136,6 +11340,23 @@
"httpapi.ResponsesRequest": {
"type": "object",
"properties": {
"background": {
"type": "boolean"
},
"context_management": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
},
"conversation": {},
"include": {
"type": "array",
"items": {
"type": "string"
}
},
"input": {},
"instructions": {
"type": "string",
@ -11145,10 +11366,18 @@
"type": "integer",
"example": 512
},
"max_tool_calls": {
"type": "integer"
},
"metadata": {
"type": "object",
"additionalProperties": true
},
"model": {
"type": "string",
"example": "Doubao Seed 2.0 Pro"
},
"moderation": {},
"parallel_tool_calls": {
"type": "boolean",
"example": true
@ -11157,10 +11386,31 @@
"type": "string",
"example": "resp_0123456789abcdef0123456789abcdef"
},
"prompt": {},
"prompt_cache_key": {
"type": "string"
},
"prompt_cache_options": {
"type": "object",
"additionalProperties": true
},
"prompt_cache_retention": {
"type": "string",
"enum": [
"in_memory",
"24h"
]
},
"reasoning": {
"type": "object",
"additionalProperties": true
},
"safety_identifier": {
"type": "string"
},
"service_tier": {
"type": "string"
},
"store": {
"type": "boolean"
},
@ -11168,6 +11418,10 @@
"type": "boolean",
"example": false
},
"stream_options": {
"type": "object",
"additionalProperties": true
},
"temperature": {
"type": "number",
"example": 0.7
@ -11184,9 +11438,18 @@
"additionalProperties": true
}
},
"top_logprobs": {
"type": "integer"
},
"top_p": {
"type": "number",
"example": 1
},
"truncation": {
"type": "string"
},
"user": {
"type": "string"
}
}
},
@ -11201,6 +11464,48 @@
}
}
},
"httpapi.SkillBundleMetadataResponse": {
"type": "object",
"properties": {
"apiDocsJsonPath": {
"type": "string",
"example": "/api-docs-json"
},
"apiDocsYamlPath": {
"type": "string",
"example": "/api-docs-yaml"
},
"displayName": {
"type": "string",
"example": "AI Gateway 运维管理"
},
"downloadPath": {
"type": "string",
"example": "/api/v1/public/skills/ai-gateway-ops-management/download"
},
"fileName": {
"type": "string",
"example": "ai-gateway-ops-management-v1.0.2.zip"
},
"modules": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"model-runtime"
]
},
"name": {
"type": "string",
"example": "ai-gateway-ops-management"
},
"version": {
"type": "string",
"example": "1.0.2"
}
}
},
"httpapi.TaskAcceptedResponse": {
"type": "object",
"properties": {
@ -11307,14 +11612,20 @@
"type": "string",
"example": "happy"
},
"input": {
"type": "string",
"example": "Tell me a short story"
},
"input": {},
"makeInstrumental": {
"type": "boolean",
"example": false
},
"max_completion_tokens": {
"description": "MaxCompletionTokens includes visible output and reasoning tokens.",
"type": "integer",
"example": 512
},
"max_output_tokens": {
"type": "integer",
"example": 512
},
"max_tokens": {
"type": "integer",
"example": 512
@ -11342,8 +11653,17 @@
"example": "A watercolor robot reading a book"
},
"reasoning_effort": {
"description": "ReasoningEffort 推理强度，OpenAI-compatible 请求字段；仅支持 none、minimal、low、medium、high、xhigh。供应商自定义取值由网关按平台适配。",
"description": "ReasoningEffort 推理强度，OpenAI-compatible 请求字段；支持 none、minimal、low、medium、high、xhigh、max。供应商自定义取值由网关按平台适配。",
"type": "string",
"enum": [
"none",
"minimal",
"low",
"medium",
"high",
"xhigh",
"max"
],
"example": "medium"
},
"resolution": {

381
apps/api/docs/swagger.yaml
View File

@ -133,6 +133,118 @@ definitions:
usage:
$ref: '#/definitions/httpapi.ChatCompletionUsage'
type: object
httpapi.ChatCompletionRequest:
properties:
audio:
additionalProperties: true
type: object
frequency_penalty:
example: 0
type: number
function_call: {}
functions:
items:
additionalProperties: true
type: object
type: array
logit_bias:
additionalProperties: true
type: object
logprobs:
type: boolean
max_completion_tokens:
example: 512
type: integer
max_tokens:
example: 512
type: integer
messages:
items:
$ref: '#/definitions/httpapi.ChatMessage'
type: array
metadata:
additionalProperties: true
type: object
modalities:
items:
type: string
type: array
model:
example: gpt-4o-mini
type: string
moderation: {}
"n":
example: 1
type: integer
parallel_tool_calls:
type: boolean
prediction: {}
presence_penalty:
example: 0
type: number
prompt_cache_key:
type: string
prompt_cache_options:
additionalProperties: true
type: object
prompt_cache_retention:
enum:
- in_memory
- 24h
type: string
reasoning_effort:
description: ReasoningEffort 推理强度，OpenAI-compatible 请求字段；支持 none、minimal、low、medium、high、xhigh、max。供应商自定义取值由网关按平台适配。
enum:
- none
- minimal
- low
- medium
- high
- xhigh
- max
example: medium
type: string
response_format: {}
runMode:
example: simulation
type: string
safety_identifier:
type: string
seed:
type: integer
service_tier:
type: string
stop: {}
store:
type: boolean
stream:
example: false
type: boolean
stream_options:
additionalProperties: true
type: object
temperature:
example: 0.7
type: number
tool_choice: {}
tools:
items:
additionalProperties: true
type: object
type: array
top_logprobs:
type: integer
top_p:
example: 1
type: number
user:
type: string
verbosity:
type: string
web_search_options:
additionalProperties: true
type: object
type: object
httpapi.ChatCompletionUsage:
properties:
completion_tokens:
@ -157,12 +269,16 @@ definitions:
type: object
httpapi.ChatMessage:
properties:
content:
example: Hello
content: {}
function_call: {}
name:
type: string
role:
example: user
type: string
tool_call_id:
type: string
tool_calls: {}
type: object
httpapi.ChatPromptTokensDetails:
properties:
@ -203,9 +319,13 @@ definitions:
message:
example: invalid json body
type: string
param: {}
status:
example: 400
type: integer
type:
example: invalid_request_error
type: string
type: object
httpapi.FileStorageChannelListResponse:
properties:
@ -567,6 +687,18 @@ definitions:
type: object
httpapi.ResponsesRequest:
properties:
background:
type: boolean
context_management:
items:
additionalProperties: true
type: object
type: array
conversation: {}
include:
items:
type: string
type: array
input: {}
instructions:
example: Answer concisely
@ -574,23 +706,47 @@ definitions:
max_output_tokens:
example: 512
type: integer
max_tool_calls:
type: integer
metadata:
additionalProperties: true
type: object
model:
example: Doubao Seed 2.0 Pro
type: string
moderation: {}
parallel_tool_calls:
example: true
type: boolean
previous_response_id:
example: resp_0123456789abcdef0123456789abcdef
type: string
prompt: {}
prompt_cache_key:
type: string
prompt_cache_options:
additionalProperties: true
type: object
prompt_cache_retention:
enum:
- in_memory
- 24h
type: string
reasoning:
additionalProperties: true
type: object
safety_identifier:
type: string
service_tier:
type: string
store:
type: boolean
stream:
example: false
type: boolean
stream_options:
additionalProperties: true
type: object
temperature:
example: 0.7
type: number
@ -603,9 +759,15 @@ definitions:
additionalProperties: true
type: object
type: array
top_logprobs:
type: integer
top_p:
example: 1
type: number
truncation:
type: string
user:
type: string
type: object
httpapi.RuntimePolicySetListResponse:
properties:
@ -614,6 +776,36 @@ definitions:
$ref: '#/definitions/store.RuntimePolicySet'
type: array
type: object
httpapi.SkillBundleMetadataResponse:
properties:
apiDocsJsonPath:
example: /api-docs-json
type: string
apiDocsYamlPath:
example: /api-docs-yaml
type: string
displayName:
example: AI Gateway 运维管理
type: string
downloadPath:
example: /api/v1/public/skills/ai-gateway-ops-management/download
type: string
fileName:
example: ai-gateway-ops-management-v1.0.2.zip
type: string
modules:
example:
- model-runtime
items:
type: string
type: array
name:
example: ai-gateway-ops-management
type: string
version:
example: 1.0.2
type: string
type: object
httpapi.TaskAcceptedResponse:
properties:
next:
@ -688,12 +880,17 @@ definitions:
emotion:
example: happy
type: string
input:
example: Tell me a short story
type: string
input: {}
makeInstrumental:
example: false
type: boolean
max_completion_tokens:
description: MaxCompletionTokens includes visible output and reasoning tokens.
example: 512
type: integer
max_output_tokens:
example: 512
type: integer
max_tokens:
example: 512
type: integer
@ -714,7 +911,15 @@ definitions:
example: A watercolor robot reading a book
type: string
reasoning_effort:
description: ReasoningEffort 推理强度，OpenAI-compatible 请求字段；仅支持 none、minimal、low、medium、high、xhigh。供应商自定义取值由网关按平台适配。
description: ReasoningEffort 推理强度，OpenAI-compatible 请求字段；支持 none、minimal、low、medium、high、xhigh、max。供应商自定义取值由网关按平台适配。
enum:
- none
- minimal
- low
- medium
- high
- xhigh
- max
example: medium
type: string
resolution:
@ -2778,6 +2983,33 @@ info:
title: EasyAI AI Gateway API
version: 0.1.0
paths:
/api-docs-json:
get:
description: 返回当前构建内嵌的完整机器可读 Swagger JSON，供 Agent 在 SKILL references 未覆盖接口时查询。
produces:
- application/json
responses:
"200":
description: OK
schema:
additionalProperties: true
type: object
summary: 获取 AI Gateway Swagger JSON
tags:
- agent-resources
/api-docs-yaml:
get:
description: 返回当前构建内嵌的完整机器可读 Swagger YAML。
produces:
- application/yaml
responses:
"200":
description: OK
schema:
type: string
summary: 获取 AI Gateway Swagger YAML
tags:
- agent-resources
/api/admin/access-rules:
get:
description: 管理端返回用户组、租户、用户或 API Key 到平台、平台模型、基础模型的访问规则。
@ -6117,7 +6349,7 @@ paths:
name: input
required: true
schema:
$ref: '#/definitions/httpapi.TaskRequest'
$ref: '#/definitions/httpapi.ChatCompletionRequest'
produces:
- application/json
- text/event-stream
@ -6678,6 +6910,40 @@ paths:
summary: 获取公开统一认证状态
tags:
- identity
/api/v1/public/skills/ai-gateway-ops-management/download:
get:
description: 下载可交给 Agent 使用的 ai-gateway-ops-management ZIP 包。
produces:
- application/zip
responses:
"200":
description: OK
schema:
type: file
"500":
description: Internal Server Error
schema:
$ref: '#/definitions/httpapi.ErrorEnvelope'
summary: 下载 AI Gateway 运维管理 SKILL
tags:
- agent-resources
/api/v1/public/skills/ai-gateway-ops-management/metadata:
get:
description: 返回公开运维管理 SKILL 的名称、版本、模块、下载文件名和机器可读接口文档路径。
produces:
- application/json
responses:
"200":
description: OK
schema:
$ref: '#/definitions/httpapi.SkillBundleMetadataResponse'
"500":
description: Internal Server Error
schema:
$ref: '#/definitions/httpapi.ErrorEnvelope'
summary: 获取 AI Gateway 运维管理 SKILL 元数据
tags:
- agent-resources
/api/v1/reranks:
post:
consumes:
@ -6743,32 +7009,31 @@ paths:
post:
consumes:
- application/json
description: 网关任务接口按 model 选择平台模型；除 /api/v1/chat/completions 以外的 /api/v1 任务路径返回任务受理结果，OpenAI-compatible
路径同步返回兼容响应或 SSE 流。
description: 公开 OpenAI-compatible Responses 入口。模型声明 openai_responses 时原生转发，否则使用
Chat Completions 转换；store 缺省为 true。previous_response_id 严格绑定首次成功的平台模型和上游协议，链路不可用时不跨平台续接。未提供
previous_response_id 时由调用方管理完整状态，Gateway 以本轮 input/messages 为准且不追加本地历史。
parameters:
- description: true 时异步创建任务并返回 202
in: header
name: X-Async
type: boolean
- description: AI 任务请求，字段随任务类型变化
- description: Responses 请求；Chat 回退只支持自定义 function tools
in: body
name: input
required: true
schema:
$ref: '#/definitions/httpapi.TaskRequest'
$ref: '#/definitions/httpapi.ResponsesRequest'
produces:
- application/json
- text/event-stream
responses:
"200":
description: OK
headers:
X-Gateway-Task-Id:
description: 网关审计任务 ID
type: string
schema:
$ref: '#/definitions/httpapi.CompatibleResponse'
"202":
description: Accepted
schema:
$ref: '#/definitions/httpapi.TaskAcceptedResponse'
$ref: '#/definitions/httpapi.ResponsesCompatibleResponse'
"400":
description: Bad Request
description: invalid_previous_response_id / unsupported_response_tool /
unsupported_response_parameter
schema:
$ref: '#/definitions/httpapi.ErrorEnvelope'
"401":
@ -6783,23 +7048,15 @@ paths:
description: Forbidden
schema:
$ref: '#/definitions/httpapi.ErrorEnvelope'
"404":
description: Not Found
schema:
$ref: '#/definitions/httpapi.ErrorEnvelope'
"429":
description: Too Many Requests
schema:
$ref: '#/definitions/httpapi.ErrorEnvelope'
"502":
description: Bad Gateway
"503":
description: response_chain_unavailable
schema:
$ref: '#/definitions/httpapi.ErrorEnvelope'
security:
- BearerAuth: []
summary: 创建或执行 AI 任务
summary: 创建 OpenAI Responses
tags:
- tasks
- responses
/api/v1/security-events/ssf:
post:
consumes:
@ -7714,32 +7971,25 @@ paths:
post:
consumes:
- application/json
description: 网关任务接口按 model 选择平台模型；除 /api/v1/chat/completions 以外的 /api/v1 任务路径返回任务受理结果，OpenAI-compatible
路径同步返回兼容响应或 SSE 流。
description: OpenAI-compatible Chat Completions 入口；仅接受官方字段及文档声明的 EasyAI 路由扩展，未知顶层字段返回
400 invalid_parameter。
parameters:
- description: true 时异步创建任务并返回 202
in: header
name: X-Async
type: boolean
- description: AI 任务请求，字段随任务类型变化
- description: Chat Completions 请求
in: body
name: input
required: true
schema:
$ref: '#/definitions/httpapi.TaskRequest'
$ref: '#/definitions/httpapi.ChatCompletionRequest'
produces:
- application/json
- text/event-stream
responses:
"200":
description: OK
schema:
$ref: '#/definitions/httpapi.CompatibleResponse'
"202":
description: Accepted
schema:
$ref: '#/definitions/httpapi.TaskAcceptedResponse'
$ref: '#/definitions/httpapi.ChatCompletionCompatibleResponse'
"400":
description: Bad Request
description: invalid_parameter
schema:
$ref: '#/definitions/httpapi.ErrorEnvelope'
"401":
@ -7754,10 +8004,6 @@ paths:
description: Forbidden
schema:
$ref: '#/definitions/httpapi.ErrorEnvelope'
"404":
description: Not Found
schema:
$ref: '#/definitions/httpapi.ErrorEnvelope'
"429":
description: Too Many Requests
schema:
@ -7768,9 +8014,9 @@ paths:
$ref: '#/definitions/httpapi.ErrorEnvelope'
security:
- BearerAuth: []
summary: 创建或执行 AI 任务
summary: 创建 OpenAI Chat Completions
tags:
- tasks
- chat
/embeddings:
post:
consumes:
@ -8553,32 +8799,25 @@ paths:
post:
consumes:
- application/json
description: 网关任务接口按 model 选择平台模型；除 /api/v1/chat/completions 以外的 /api/v1 任务路径返回任务受理结果，OpenAI-compatible
路径同步返回兼容响应或 SSE 流。
description: OpenAI-compatible Chat Completions 入口；仅接受官方字段及文档声明的 EasyAI 路由扩展，未知顶层字段返回
400 invalid_parameter。
parameters:
- description: true 时异步创建任务并返回 202
in: header
name: X-Async
type: boolean
- description: AI 任务请求，字段随任务类型变化
- description: Chat Completions 请求
in: body
name: input
required: true
schema:
$ref: '#/definitions/httpapi.TaskRequest'
$ref: '#/definitions/httpapi.ChatCompletionRequest'
produces:
- application/json
- text/event-stream
responses:
"200":
description: OK
schema:
$ref: '#/definitions/httpapi.CompatibleResponse'
"202":
description: Accepted
schema:
$ref: '#/definitions/httpapi.TaskAcceptedResponse'
$ref: '#/definitions/httpapi.ChatCompletionCompatibleResponse'
"400":
description: Bad Request
description: invalid_parameter
schema:
$ref: '#/definitions/httpapi.ErrorEnvelope'
"401":
@ -8593,10 +8832,6 @@ paths:
description: Forbidden
schema:
$ref: '#/definitions/httpapi.ErrorEnvelope'
"404":
description: Not Found
schema:
$ref: '#/definitions/httpapi.ErrorEnvelope'
"429":
description: Too Many Requests
schema:
@ -8607,9 +8842,9 @@ paths:
$ref: '#/definitions/httpapi.ErrorEnvelope'
security:
- BearerAuth: []
summary: 创建或执行 AI 任务
summary: 创建 OpenAI Chat Completions
tags:
- tasks
- chat
/v1/embeddings:
post:
consumes:

4
apps/api/go.mod
View File

@ -14,7 +14,7 @@ require (
github.com/riverqueue/river v0.24.0
github.com/riverqueue/river/riverdriver/riverpgxv5 v0.24.0
github.com/riverqueue/river/rivertype v0.24.0
golang.org/x/crypto v0.37.0
golang.org/x/crypto v0.52.0
golang.org/x/oauth2 v0.36.0
)
@ -37,6 +37,6 @@ require (
github.com/tidwall/sjson v1.2.5 // indirect
go.uber.org/goleak v1.3.0 // indirect
golang.org/x/sync v0.20.0 // indirect
golang.org/x/text v0.36.0 // indirect
golang.org/x/text v0.37.0 // indirect
gopkg.in/yaml.v3 v3.0.1 // indirect
)

8
apps/api/go.sum
View File

@ -69,14 +69,14 @@ github.com/tidwall/sjson v1.2.5 h1:kLy8mja+1c9jlljvWTlSazM7cKDRfJuR/bOJhcY5NcY=
github.com/tidwall/sjson v1.2.5/go.mod h1:Fvgq9kS/6ociJEDnK0Fk1cpYF4FIW6ZF7LAe+6jwd28=
go.uber.org/goleak v1.3.0 h1:2K3zAYmnTNqV73imy9J1T3WC+gmCePx2hEGkimedGto=
go.uber.org/goleak v1.3.0/go.mod h1:CoHD4mav9JJNrW/WLlf7HGZPjdw8EucARQHekz1X6bE=
golang.org/x/crypto v0.37.0 h1:kJNSjF/Xp7kU0iB2Z+9viTPMW4EqqsrywMXLJOOsXSE=
golang.org/x/crypto v0.37.0/go.mod h1:vg+k43peMZ0pUMhYmVAWysMK35e6ioLh3wB8ZCAfbVc=
golang.org/x/crypto v0.52.0 h1:RMs7fP2rXdep0CftQlK8Uf+kibLm7qkCcradZWYz988=
golang.org/x/crypto v0.52.0/go.mod h1:1QgfPxDqh0T2M/elOJtp9RvuR95kVjir0e6/BvEmGbc=
golang.org/x/oauth2 v0.36.0 h1:peZ/1z27fi9hUOFCAZaHyrpWG5lwe0RJEEEeH0ThlIs=
golang.org/x/oauth2 v0.36.0/go.mod h1:YDBUJMTkDnJS+A4BP4eZBjCqtokkg1hODuPjwiGPO7Q=
golang.org/x/sync v0.20.0 h1:e0PTpb7pjO8GAtTs2dQ6jYa5BWYlMuX047Dco/pItO4=
golang.org/x/sync v0.20.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
golang.org/x/text v0.36.0 h1:JfKh3XmcRPqZPKevfXVpI1wXPTqbkE5f7JA92a55Yxg=
golang.org/x/text v0.36.0/go.mod h1:NIdBknypM8iqVmPiuco0Dh6P5Jcdk8lJL0CUebqK164=
golang.org/x/text v0.37.0 h1:Cqjiwd9eSg8e0QAkyCaQTNHFIIzWtidPahFWR83rTrc=
golang.org/x/text v0.37.0/go.mod h1:a5sjxXGs9hsn/AJVwuElvCAo9v8QYLzvavO5z2PiM38=
gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=

10
apps/api/internal/clients/chat_reasoning.go
View File

@ -9,7 +9,7 @@ import (
"github.com/easyai/easyai-ai-gateway/apps/api/internal/store"
)
const OpenAIReasoningEffortValidationMessage = "reasoning_effort must be one of: none, minimal, low, medium, high, xhigh"
const OpenAIReasoningEffortValidationMessage = "reasoning_effort must be one of: none, minimal, low, medium, high, xhigh, max"
var (
openAIReasoningEfforts = map[string]struct{}{
@ -19,6 +19,7 @@ var (
"medium": {},
"high": {},
"xhigh": {},
"max": {},
}
volcesChatReasoningEfforts = map[string]struct{}{
"minimal": {},
@ -212,13 +213,16 @@ func isZhipuReasoningEffortModel(model string) bool {
}
func highMaxReasoningEffort(effort string) string {
if effort == "xhigh" {
if effort == "xhigh" || effort == "max" {
return "max"
}
return "high"
}
func zhipuReasoningEffort(effort string) string {
if effort == "max" {
return "xhigh"
}
if _, ok := zhipuReasoningEfforts[effort]; ok {
return effort
}
@ -229,7 +233,7 @@ func volcesChatReasoningEffort(effort string) string {
switch effort {
case "none":
return "minimal"
case "xhigh":
case "xhigh", "max":
return "high"
default:
if _, ok := volcesChatReasoningEfforts[effort]; ok {

29
apps/api/internal/clients/chat_reasoning_max_test.go Normal file
View File

@ -0,0 +1,29 @@
package clients
import (
"testing"
"github.com/easyai/easyai-ai-gateway/apps/api/internal/store"
)
func TestCurrentOpenAIReasoningEffortMaxProviderMapping(t *testing.T) {
tests := []struct {
name string
candidate store.RuntimeModelCandidate
expected string
}{
{name: "generic", candidate: store.RuntimeModelCandidate{Provider: "openai"}, expected: "max"},
{name: "deepseek", candidate: store.RuntimeModelCandidate{Provider: "deepseek-openai"}, expected: "max"},
{name: "zhipu", candidate: store.RuntimeModelCandidate{Provider: "zhipu-openai", ProviderModelName: "glm-5.2"}, expected: "xhigh"},
{name: "volces", candidate: store.RuntimeModelCandidate{Provider: "volces-openai", ProviderModelName: "doubao-seed-2-0-pro-260215"}, expected: "high"},
}
for _, test := range tests {
t.Run(test.name, func(t *testing.T) {
body := map[string]any{"model": test.candidate.ProviderModelName, "reasoning_effort": "max"}
applyOpenAIChatReasoningParams(body, test.candidate)
if body["reasoning_effort"] != test.expected {
t.Fatalf("expected reasoning_effort %q, got %#v", test.expected, body["reasoning_effort"])
}
})
}
}

250
apps/api/internal/clients/clients_test.go
View File

@ -2294,6 +2294,256 @@ func TestKelingClientVideoSubmitsAndPollsImageTask(t *testing.T) {
}
}
func TestKelingClient30TurboUsesModelEndpointAndTasksAPI(t *testing.T) {
var submitPath string
var pollPath string
var pollQuery string
var gotAuth string
var submittedPayload map[string]any
var submittedTaskPayload map[string]any
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
gotAuth = r.Header.Get("Authorization")
switch r.Method + " " + r.URL.Path {
case "POST /text-to-video/kling-3.0-turbo":
submitPath = r.URL.Path
if err := json.NewDecoder(r.Body).Decode(&submittedPayload); err != nil {
t.Fatalf("decode keling 3.0 turbo submit: %v", err)
}
_ = json.NewEncoder(w).Encode(map[string]any{
"code": 0,
"request_id": "req-turbo-submit",
"data": map[string]any{
"id": "turbo-task-1",
"status": "submitted",
},
})
case "GET /tasks":
pollPath = r.URL.Path
pollQuery = r.URL.RawQuery
_ = json.NewEncoder(w).Encode(map[string]any{
"code": 0,
"request_id": "req-turbo-poll",
"data": []any{
map[string]any{
"id": "turbo-task-1",
"status": "succeeded",
"create_time": 789,
"outputs": []any{
map[string]any{
"type": "video",
"url": "https://example.com/turbo.mp4",
"watermark_url": "https://example.com/turbo-watermark.mp4",
"duration": "8",
},
},
},
},
})
default:
t.Fatalf("unexpected request %s %s", r.Method, r.URL.Path)
}
}))
defer server.Close()
response, err := (KelingClient{HTTPClient: server.Client()}).Run(context.Background(), Request{
Kind: "videos.generations",
ModelType: "video_generate",
Model: "可灵3.0 Turbo",
Body: map[string]any{
"prompt": "A cinematic city reveal",
"duration": 8,
"resolution": "1080p",
"aspect_ratio": "9:16",
"callback_url": "https://example.com/callback",
"external_task_id": "external-1",
},
Candidate: store.RuntimeModelCandidate{
BaseURL: server.URL + "/v1",
Provider: "keling",
AuthType: "APIKey",
ModelName: "可灵3.0 Turbo",
ProviderModelName: "kling-3.0-turbo",
Credentials: map[string]any{"apiKey": "kling-api-key"},
PlatformConfig: map[string]any{
"kelingPollIntervalMs": 100,
"kelingPollTimeoutSeconds": 1,
},
},
OnRemoteTaskSubmitted: func(remoteTaskID string, payload map[string]any) error {
if remoteTaskID != "turbo-task-1" {
t.Fatalf("unexpected remote task id: %s", remoteTaskID)
}
submittedTaskPayload = payload
return nil
},
})
if err != nil {
t.Fatalf("run keling 3.0 turbo video: %v", err)
}
if submitPath != "/text-to-video/kling-3.0-turbo" ||
pollPath != "/tasks" ||
pollQuery != "task_ids=turbo-task-1" ||
gotAuth != "Bearer kling-api-key" {
t.Fatalf("unexpected keling 3.0 turbo paths/auth submit=%s poll=%s?%s auth=%s", submitPath, pollPath, pollQuery, gotAuth)
}
if submittedTaskPayload["endpoint"] != "/text-to-video/kling-3.0-turbo" ||
submittedTaskPayload["taskApi"] != "keling_tasks_v2" {
t.Fatalf("unexpected submitted task payload: %+v", submittedTaskPayload)
}
settings, _ := submittedPayload["settings"].(map[string]any)
options, _ := submittedPayload["options"].(map[string]any)
if submittedPayload["prompt"] != "A cinematic city reveal" ||
numericValue(settings["duration"], 0) != 8 ||
settings["resolution"] != "1080p" ||
settings["aspect_ratio"] != "9:16" ||
options["callback_url"] != "https://example.com/callback" ||
options["external_task_id"] != "external-1" {
t.Fatalf("unexpected keling 3.0 turbo payload: %+v", submittedPayload)
}
data, _ := response.Result["data"].([]any)
item, _ := data[0].(map[string]any)
if response.Result["upstream_task_id"] != "turbo-task-1" ||
item["url"] != "https://example.com/turbo.mp4" ||
item["watermark_url"] != "https://example.com/turbo-watermark.mp4" {
t.Fatalf("unexpected keling 3.0 turbo response: %+v", response.Result)
}
}
func TestKelingClient30TurboRejectsLegacyCredentials(t *testing.T) {
_, err := (KelingClient{}).Run(context.Background(), Request{
Kind: "videos.generations",
Body: map[string]any{"prompt": "A cinematic city reveal"},
Candidate: store.RuntimeModelCandidate{
Provider: "keling",
AuthType: "AccessKey-SecretKey",
ProviderModelName: "kling-3.0-turbo",
Credentials: map[string]any{"accessKey": "ak", "secretKey": "sk"},
},
})
if err == nil || !strings.Contains(err.Error(), "new API key") {
t.Fatalf("expected keling 3.0 turbo API key requirement, got %v", err)
}
}
func TestKelingClient30TurboResumePollsWithoutSubmitting(t *testing.T) {
var submitCalled bool
var pollQuery string
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
switch r.Method + " " + r.URL.Path {
case "POST /text-to-video/kling-3.0-turbo":
submitCalled = true
t.Fatalf("resume should not submit a new keling 3.0 turbo task")
case "GET /tasks":
pollQuery = r.URL.RawQuery
_ = json.NewEncoder(w).Encode(map[string]any{
"code": 0,
"request_id": "req-turbo-resume",
"data": []any{
map[string]any{
"id": "turbo-existing",
"status": "succeeded",
"outputs": []any{
map[string]any{"type": "video", "url": "https://example.com/resumed-turbo.mp4"},
},
},
},
})
default:
t.Fatalf("unexpected request %s %s", r.Method, r.URL.Path)
}
}))
defer server.Close()
response, err := (KelingClient{HTTPClient: server.Client()}).Run(context.Background(), Request{
Kind: "videos.generations",
ModelType: "video_generate",
RemoteTaskID: "turbo-existing",
Body: map[string]any{},
Candidate: store.RuntimeModelCandidate{
BaseURL: server.URL + "/v1",
Provider: "keling",
AuthType: "APIKey",
ProviderModelName: "kling-3.0-turbo",
Credentials: map[string]any{"apiKey": "kling-api-key"},
PlatformConfig: map[string]any{
"kelingPollIntervalMs": 100,
"kelingPollTimeoutSeconds": 1,
},
},
})
if err != nil {
t.Fatalf("resume keling 3.0 turbo video: %v", err)
}
if submitCalled || pollQuery != "task_ids=turbo-existing" {
t.Fatalf("resume should only poll existing task, submit=%v query=%s", submitCalled, pollQuery)
}
data, _ := response.Result["data"].([]any)
item, _ := data[0].(map[string]any)
if item["url"] != "https://example.com/resumed-turbo.mp4" {
t.Fatalf("unexpected resumed keling 3.0 turbo response: %+v", response.Result)
}
}
func TestKeling30TurboPayloadBuildsFirstFrameAndMultiShotRequests(t *testing.T) {
imagePayload, endpoint, err := keling30TurboPayload(Request{
Body: map[string]any{
"duration": 5,
"resolution": "720p",
"content": []any{
map[string]any{"type": "text", "text": "The subject looks toward the camera"},
map[string]any{
"type": "image_url",
"role": "first_frame",
"image_url": map[string]any{"url": "https://example.com/first.png"},
},
},
},
})
if err != nil {
t.Fatalf("build keling 3.0 turbo image payload: %v", err)
}
if endpoint != "/image-to-video/kling-3.0-turbo" {
t.Fatalf("unexpected image endpoint: %s", endpoint)
}
if _, ok := mapFromAny(imagePayload["settings"])["aspect_ratio"]; ok {
t.Fatalf("image-to-video settings should not contain aspect_ratio: %+v", imagePayload)
}
contents, _ := imagePayload["contents"].([]any)
frame := mapFromAny(contents[1])
if frame["type"] != "first_frame" || frame["url"] != "https://example.com/first.png" {
t.Fatalf("unexpected image contents: %+v", imagePayload["contents"])
}
shotPayload, _, err := keling30TurboPayload(Request{
Body: map[string]any{
"resolution": "720p",
"content": []any{
map[string]any{"type": "text", "role": "shot_prompt", "shot_index": 1, "duration": 4, "text": "A car enters the tunnel"},
map[string]any{"type": "text", "role": "shot_prompt", "shot_index": 2, "duration": 3, "text": "The headlights fill the frame"},
},
},
})
if err != nil {
t.Fatalf("build keling 3.0 turbo shot payload: %v", err)
}
if shotPayload["prompt"] != "shot 1, 4s, A car enters the tunnel; shot 2, 3s, The headlights fill the frame;" ||
numericValue(mapFromAny(shotPayload["settings"])["duration"], 0) != 7 {
t.Fatalf("unexpected shot payload: %+v", shotPayload)
}
}
func TestKeling30TurboPayloadRejectsLastFrame(t *testing.T) {
_, _, err := keling30TurboPayload(Request{
Body: map[string]any{
"prompt": "Move forward",
"last_frame": "https://example.com/last.png",
},
})
if err == nil || !strings.Contains(err.Error(), "last frame") {
t.Fatalf("expected unsupported last frame error, got %v", err)
}
}
func TestKelingOmniPayloadConvertsGatewayContent(t *testing.T) {
payload, cleanupIDs, err := (KelingClient{}).kelingOmniPayload(context.Background(), Request{
Kind: "videos.generations",

316
apps/api/internal/clients/keling.go
View File

@ -9,9 +9,11 @@ import (
"io"
"math"
"net/http"
"net/url"
"sort"
"strings"
"time"
"unicode/utf8"
"github.com/easyai/easyai-ai-gateway/apps/api/internal/store"
"github.com/golang-jwt/jwt/v5"
@ -32,14 +34,34 @@ func (c KelingClient) Run(ctx context.Context, request Request) (Response, error
if request.Kind != "videos.generations" {
return Response{}, &ClientError{Code: "unsupported_kind", Message: "unsupported keling request kind", Retryable: false}
}
token, err := kelingAuthToken(request.Candidate)
token, err := kelingAuthTokenForRequest(request)
if err != nil {
return Response{}, err
}
return c.runVideo(ctx, request, token)
}
func kelingAuthTokenForRequest(request Request) (string, error) {
if kelingIs30TurboRequest(request) {
apiKey := credential(request.Candidate.Credentials, "apiKey", "api_key", "key", "token")
if apiKey == "" {
return "", &ClientError{
Code: "missing_credentials",
Message: "keling 3.0 turbo requires the new API key; legacy accessKey/secretKey credentials do not support new models",
Retryable: false,
StatusCode: http.StatusBadRequest,
}
}
return apiKey, nil
}
return kelingAuthToken(request.Candidate)
}
func (c KelingClient) runVideo(ctx context.Context, request Request, token string) (Response, error) {
if kelingIs30TurboRequest(request) {
return c.runTaskAPIVideo(ctx, request, token)
}
submitStartedAt := time.Now()
submitRequestID := strings.TrimSpace(request.RemoteTaskID)
upstreamTaskID := strings.TrimSpace(request.RemoteTaskID)
@ -143,6 +165,105 @@ func (c KelingClient) runVideo(ctx context.Context, request Request, token strin
}
}
func (c KelingClient) runTaskAPIVideo(ctx context.Context, request Request, token string) (Response, error) {
submitStartedAt := time.Now()
submitRequestID := strings.TrimSpace(request.RemoteTaskID)
upstreamTaskID := strings.TrimSpace(request.RemoteTaskID)
taskAPIBaseURL := kelingTaskAPIBaseURL(request.Candidate.BaseURL)
if upstreamTaskID == "" {
payload, endpoint, err := keling30TurboPayload(request)
if err != nil {
return Response{}, err
}
submitResult, requestID, err := c.postJSONAt(ctx, request, taskAPIBaseURL, endpoint, token, payload)
submitRequestID = requestID
if err != nil {
return Response{}, annotateResponseError(err, submitRequestID, submitStartedAt, time.Now())
}
upstreamTaskID = strings.TrimSpace(stringFromAny(kelingData(submitResult)["id"]))
if upstreamTaskID == "" {
return Response{}, &ClientError{Code: "invalid_response", Message: "keling 3.0 turbo task id is missing", RequestID: submitRequestID, Retryable: false}
}
if request.OnRemoteTaskSubmitted != nil {
if err := request.OnRemoteTaskSubmitted(upstreamTaskID, map[string]any{
"endpoint": endpoint,
"taskApi": "keling_tasks_v2",
"submit": submitResult,
}); err != nil {
return Response{}, err
}
}
}
interval := kelingPollInterval(request)
timeout := kelingPollTimeout(request)
deadline := time.NewTimer(timeout)
defer deadline.Stop()
ticker := time.NewTicker(interval)
defer ticker.Stop()
var lastStatus string
for {
select {
case <-ctx.Done():
return Response{}, &ClientError{Code: "cancelled", Message: ctx.Err().Error(), RequestID: submitRequestID, Retryable: true}
default:
}
pollStartedAt := time.Now()
pollResult, pollRequestID, err := c.getJSONAt(
ctx,
request,
taskAPIBaseURL,
"/tasks?task_ids="+url.QueryEscape(upstreamTaskID),
token,
)
pollFinishedAt := time.Now()
requestID := firstNonEmpty(pollRequestID, submitRequestID, upstreamTaskID)
if err != nil {
return Response{}, annotateResponseError(err, requestID, pollStartedAt, pollFinishedAt)
}
task := kelingTaskAPITask(pollResult, upstreamTaskID)
lastStatus = strings.ToLower(strings.TrimSpace(stringFromAny(task["status"])))
switch lastStatus {
case "succeeded", "succeed":
return Response{
Result: kelingTaskAPIVideoSuccessResult(request, upstreamTaskID, task, pollResult),
RequestID: requestID,
Progress: kelingVideoProgress(request, upstreamTaskID),
ResponseStartedAt: submitStartedAt,
ResponseFinishedAt: pollFinishedAt,
ResponseDurationMS: responseDurationMS(submitStartedAt, pollFinishedAt),
}, nil
case "failed":
return Response{}, &ClientError{
Code: "keling_task_failed",
Message: kelingTaskAPIErrorMessage(request.Candidate, task, pollResult),
RequestID: requestID,
ResponseStartedAt: submitStartedAt,
ResponseFinishedAt: pollFinishedAt,
ResponseDurationMS: responseDurationMS(submitStartedAt, pollFinishedAt),
Retryable: false,
}
}
select {
case <-ctx.Done():
return Response{}, &ClientError{Code: "cancelled", Message: ctx.Err().Error(), RequestID: requestID, Retryable: true}
case <-deadline.C:
return Response{}, &ClientError{
Code: "timeout",
Message: fmt.Sprintf("keling 3.0 turbo task %s did not finish before timeout; last status: %s", upstreamTaskID, lastStatus),
RequestID: requestID,
Retryable: true,
}
case <-ticker.C:
}
}
}
func (c KelingClient) prepareVideoTask(ctx context.Context, request Request, token string) (kelingPreparedTask, error) {
if kelingIsOmniRequest(request) {
payload, cleanupIDs, err := c.kelingOmniPayload(ctx, request, token)
@ -400,8 +521,12 @@ func (c KelingClient) kelingOmniElementList(ctx context.Context, request Request
}
func (c KelingClient) postJSON(ctx context.Context, request Request, path string, token string, body map[string]any) (map[string]any, string, error) {
return c.postJSONAt(ctx, request, request.Candidate.BaseURL, path, token, body)
}
func (c KelingClient) postJSONAt(ctx context.Context, request Request, baseURL string, path string, token string, body map[string]any) (map[string]any, string, error) {
raw, _ := json.Marshal(body)
req, err := http.NewRequestWithContext(ctx, http.MethodPost, joinURL(request.Candidate.BaseURL, path), bytes.NewReader(raw))
req, err := http.NewRequestWithContext(ctx, http.MethodPost, joinURL(baseURL, path), bytes.NewReader(raw))
if err != nil {
return nil, "", err
}
@ -423,7 +548,11 @@ func (c KelingClient) postJSON(ctx context.Context, request Request, path string
}
func (c KelingClient) getJSON(ctx context.Context, request Request, path string, token string) (map[string]any, string, error) {
req, err := http.NewRequestWithContext(ctx, http.MethodGet, joinURL(request.Candidate.BaseURL, path), nil)
return c.getJSONAt(ctx, request, request.Candidate.BaseURL, path, token)
}
func (c KelingClient) getJSONAt(ctx context.Context, request Request, baseURL string, path string, token string) (map[string]any, string, error) {
req, err := http.NewRequestWithContext(ctx, http.MethodGet, joinURL(baseURL, path), nil)
if err != nil {
return nil, "", err
}
@ -560,6 +689,127 @@ func kelingIsOmniRequest(request Request) bool {
request.Candidate.Capabilities["omni"] != nil
}
func kelingIs30TurboRequest(request Request) bool {
switch strings.ToLower(strings.TrimSpace(upstreamModelName(request.Candidate))) {
case "kling-3.0-turbo", "kling-v3-turbo", "kling-3-0-turbo":
return true
default:
return false
}
}
func kelingTaskAPIBaseURL(baseURL string) string {
trimmed := strings.TrimRight(strings.TrimSpace(baseURL), "/")
if strings.HasSuffix(strings.ToLower(trimmed), "/v1") {
return trimmed[:len(trimmed)-len("/v1")]
}
return trimmed
}
func keling30TurboPayload(request Request) (map[string]any, string, error) {
body := cleanProviderBody(request.Body)
content := contentItems(body["content"])
if len(content) == 0 {
content = buildVolcesContentFromBody(body)
}
shots := kelingShotPrompts(content)
if len(shots) > 6 {
return nil, "", &ClientError{Code: "invalid_parameter", Message: "keling 3.0 turbo supports at most 6 shots", StatusCode: 400, Retryable: false}
}
prompt := firstKelingPrompt(content)
duration := numericValue(body["duration"], 5)
if len(shots) > 0 {
var promptBuilder strings.Builder
duration = 0
for index, shot := range shots {
if shot.duration < 1 || math.Abs(shot.duration-math.Round(shot.duration)) > 1e-9 {
return nil, "", &ClientError{Code: "invalid_parameter", Message: "keling 3.0 turbo shot duration must be an integer of at least 1 second", StatusCode: 400, Retryable: false}
}
duration += shot.duration
fmt.Fprintf(&promptBuilder, "shot %d, %ds, %s; ", index+1, int(math.Round(shot.duration)), shot.text)
}
prompt = strings.TrimSpace(promptBuilder.String())
}
if prompt == "" {
return nil, "", &ClientError{Code: "invalid_parameter", Message: "keling 3.0 turbo video prompt is required", StatusCode: 400, Retryable: false}
}
if math.Abs(duration-math.Round(duration)) > 1e-9 || duration < 3 || duration > 15 {
return nil, "", &ClientError{Code: "invalid_parameter", Message: "keling 3.0 turbo duration must be an integer between 3 and 15 seconds", StatusCode: 400, Retryable: false}
}
firstFrame, lastFrame, referenceImages := kelingImageInputs(content)
if lastFrame != "" {
return nil, "", &ClientError{Code: "invalid_parameter", Message: "keling 3.0 turbo image-to-video supports first frame only; last frame is not supported", StatusCode: 400, Retryable: false}
}
imageCount := len(referenceImages)
if firstFrame != "" {
imageCount++
}
if imageCount > 1 {
return nil, "", &ClientError{Code: "invalid_parameter", Message: "keling 3.0 turbo image-to-video supports exactly one first-frame image", StatusCode: 400, Retryable: false}
}
if firstFrame == "" && len(referenceImages) == 1 {
firstFrame = referenceImages[0]
}
isImageToVideo := firstFrame != ""
resolution := strings.TrimSpace(firstNonEmptyStringValue(body, "resolution", "size"))
if resolution == "" {
resolution = "720p"
}
if resolution != "720p" && resolution != "1080p" {
return nil, "", &ClientError{Code: "invalid_parameter", Message: "keling 3.0 turbo resolution must be 720p or 1080p", StatusCode: 400, Retryable: false}
}
promptLimit := 3072
if isImageToVideo {
promptLimit = 2500
}
if utf8.RuneCountInString(prompt) > promptLimit {
return nil, "", &ClientError{Code: "invalid_parameter", Message: fmt.Sprintf("keling 3.0 turbo prompt exceeds %d characters", promptLimit), StatusCode: 400, Retryable: false}
}
settings := map[string]any{
"duration": int(math.Round(duration)),
"resolution": resolution,
}
options := map[string]any{
"watermark_info": map[string]any{"enabled": boolValue(body, "watermark")},
}
if callbackURL := strings.TrimSpace(firstNonEmptyStringValue(body, "callback_url", "callbackUrl")); callbackURL != "" {
options["callback_url"] = callbackURL
}
if externalTaskID := strings.TrimSpace(firstNonEmptyStringValue(body, "external_task_id", "externalTaskId")); externalTaskID != "" {
options["external_task_id"] = externalTaskID
}
if isImageToVideo {
return map[string]any{
"contents": []any{
map[string]any{"type": "prompt", "text": prompt},
map[string]any{"type": "first_frame", "url": firstFrame},
},
"settings": settings,
"options": options,
}, "/image-to-video/kling-3.0-turbo", nil
}
aspectRatio := strings.TrimSpace(firstNonEmptyStringValue(body, "aspect_ratio", "aspectRatio", "ratio"))
if aspectRatio == "" || aspectRatio == "adaptive" || aspectRatio == "keep_ratio" {
aspectRatio = "16:9"
}
if aspectRatio != "16:9" && aspectRatio != "9:16" && aspectRatio != "1:1" {
return nil, "", &ClientError{Code: "invalid_parameter", Message: "keling 3.0 turbo aspect_ratio must be 16:9, 9:16, or 1:1", StatusCode: 400, Retryable: false}
}
settings["aspect_ratio"] = aspectRatio
return map[string]any{
"prompt": prompt,
"settings": settings,
"options": options,
}, "/text-to-video/kling-3.0-turbo", nil
}
func firstKelingPrompt(content []map[string]any) string {
for _, item := range content {
if stringFromAny(item["type"]) == "text" && stringFromAny(item["role"]) != "shot_prompt" && item["shot_index"] == nil {
@ -822,6 +1072,30 @@ func kelingTaskStatus(result map[string]any) string {
return strings.ToLower(strings.TrimSpace(stringFromAny(kelingData(result)["task_status"])))
}
func kelingTaskAPITask(result map[string]any, taskID string) map[string]any {
tasks := mapListFromAny(result["data"])
for _, task := range tasks {
if strings.TrimSpace(stringFromAny(task["id"])) == taskID {
return task
}
}
if len(tasks) > 0 {
return tasks[0]
}
return map[string]any{}
}
func kelingTaskAPIErrorMessage(candidate store.RuntimeModelCandidate, task map[string]any, result map[string]any) string {
message := strings.TrimSpace(stringFromAny(task["message"]))
if message == "" {
message = strings.TrimSpace(stringFromAny(result["message"]))
}
if message == "" {
message = "keling 3.0 turbo video task failed"
}
return fmt.Sprintf("Platform:%s,Code:%v,requestId:%s,message:%s", candidate.Provider, result["code"], stringFromAny(result["request_id"]), message)
}
func kelingTaskErrorCode(result map[string]any) string {
if code := intFromAny(result["code"]); code != 0 {
return fmt.Sprintf("keling_%d", code)
@ -887,6 +1161,42 @@ func kelingVideoSuccessResult(request Request, upstreamTaskID string, raw map[st
}
}
func kelingTaskAPIVideoSuccessResult(request Request, upstreamTaskID string, task map[string]any, raw map[string]any) map[string]any {
outputs := mapListFromAny(task["outputs"])
items := make([]any, 0, len(outputs))
for _, output := range outputs {
if strings.ToLower(strings.TrimSpace(stringFromAny(output["type"]))) != "video" {
continue
}
videoURL := strings.TrimSpace(stringFromAny(output["url"]))
if videoURL == "" {
continue
}
item := map[string]any{"url": videoURL, "video_url": videoURL, "type": "video"}
if duration := numericValue(output["duration"], 0); duration > 0 {
item["duration"] = duration
}
if watermarkURL := strings.TrimSpace(stringFromAny(output["watermark_url"])); watermarkURL != "" {
item["watermark_url"] = watermarkURL
}
items = append(items, item)
}
created := intFromAny(task["create_time"])
if created == 0 {
created = int(nowUnix())
}
return map[string]any{
"id": upstreamTaskID,
"object": "video.generation",
"created": created,
"model": upstreamModelName(request.Candidate),
"status": "succeeded",
"upstream_task_id": upstreamTaskID,
"data": items,
"raw": raw,
}
}
func kelingVideoProgress(request Request, upstreamTaskID string) []Progress {
progress := providerProgress(request)
progress = append(progress, Progress{

7
apps/api/internal/clients/openai.go
View File

@ -43,7 +43,14 @@ func (c OpenAIClient) Run(ctx context.Context, request Request) (Response, error
if endpointKind == "chat.completions" {
body = NormalizeChatCompletionRequestBody(body)
applyOpenAIChatReasoningParams(body, request.Candidate)
body = FilterOpenAIChatRequestBody(body)
} else if request.Kind == "responses" {
body = FilterOpenAIResponsesRequestBody(body)
if _, hasInput := body["input"]; !hasInput {
if messages, hasMessages := request.Body["messages"]; hasMessages {
body["input"] = messages
}
}
delete(body, "messages")
if request.UpstreamPreviousResponseID != "" {
body["previous_response_id"] = request.UpstreamPreviousResponseID

108
apps/api/internal/clients/openai_request_params.go Normal file
View File

@ -0,0 +1,108 @@
package clients
import (
"fmt"
"net/http"
"sort"
)
// Keep these lists aligned with openai-node 6.47.0 and the public OpenAI API
// reference. The Gateway accepts a small, explicit set of routing extensions at
// ingress, but only protocol fields (plus controlled provider adaptations) are
// allowed across the upstream boundary.
var openAIChatRequestParameters = stringSet(
"messages", "model", "audio", "frequency_penalty", "function_call", "functions",
"logit_bias", "logprobs", "max_completion_tokens", "max_tokens", "metadata",
"modalities", "moderation", "n", "parallel_tool_calls", "prediction",
"presence_penalty", "prompt_cache_key", "prompt_cache_options", "prompt_cache_retention",
"reasoning_effort", "response_format", "safety_identifier", "seed", "service_tier",
"stop", "store", "stream", "stream_options", "temperature", "tool_choice", "tools",
"top_logprobs", "top_p", "user", "verbosity", "web_search_options",
)
var openAIResponsesRequestParameters = stringSet(
"background", "context_management", "conversation", "include", "input", "instructions",
"max_output_tokens", "max_tool_calls", "metadata", "model", "moderation",
"parallel_tool_calls", "previous_response_id", "prompt", "prompt_cache_key",
"prompt_cache_options", "prompt_cache_retention", "reasoning", "safety_identifier",
"service_tier", "store", "stream", "stream_options", "temperature", "text",
"tool_choice", "tools", "top_logprobs", "top_p", "truncation", "user",
)
var gatewayOpenAIRequestExtensions = stringSet(
"runMode", "run_mode", "conversationId", "conversation_id", "sessionId", "session_id",
"requestId", "request_id", "signal", "userMessage", "user_message", "platformId",
"platform_id", "options", "enable_thinking", "thinking_budget_tokens", "enable_web_search",
"modelType", "model_type", "capability", "capabilityType", "mode", "simulation", "testMode",
)
var gatewayResponsesRequestExtensions = stringSet("messages", "presence_penalty", "frequency_penalty")
var controlledOpenAIChatProviderParameters = stringSet(
"enable_thinking", "thinking_budget", "thinking", "enable_web_search",
)
var controlledOpenAIResponsesProviderParameters = stringSet("presence_penalty", "frequency_penalty")
func ValidateOpenAIRequestParameters(kind string, body map[string]any) error {
allowed := openAIChatRequestParameters
if kind == "responses" {
allowed = openAIResponsesRequestParameters
}
unknown := make([]string, 0)
for key := range body {
if _, ok := allowed[key]; ok {
continue
}
if _, ok := gatewayOpenAIRequestExtensions[key]; ok {
continue
}
if kind == "responses" {
if _, ok := gatewayResponsesRequestExtensions[key]; ok {
continue
}
}
unknown = append(unknown, key)
}
if len(unknown) == 0 {
return nil
}
sort.Strings(unknown)
return &ClientError{
Code: "invalid_parameter",
Message: fmt.Sprintf("Unknown parameter: %s", unknown[0]),
Param: unknown[0],
StatusCode: http.StatusBadRequest,
Retryable: false,
}
}
func FilterOpenAIChatRequestBody(body map[string]any) map[string]any {
return filterOpenAIRequestBody(body, openAIChatRequestParameters, controlledOpenAIChatProviderParameters)
}
func FilterOpenAIResponsesRequestBody(body map[string]any) map[string]any {
return filterOpenAIRequestBody(body, openAIResponsesRequestParameters, controlledOpenAIResponsesProviderParameters)
}
func filterOpenAIRequestBody(body map[string]any, allowed map[string]struct{}, extensions map[string]struct{}) map[string]any {
out := make(map[string]any, len(body))
for key, value := range body {
if _, ok := allowed[key]; ok {
out[key] = value
continue
}
if _, ok := extensions[key]; ok {
out[key] = value
}
}
return out
}
func stringSet(values ...string) map[string]struct{} {
out := make(map[string]struct{}, len(values))
for _, value := range values {
out[value] = struct{}{}
}
return out
}

89
apps/api/internal/clients/openai_request_params_test.go Normal file
View File

@ -0,0 +1,89 @@
package clients
import (
"strings"
"testing"
)
func TestOpenAIChatOfficialParametersSurviveBoundary(t *testing.T) {
body := map[string]any{}
for key := range openAIChatRequestParameters {
body[key] = "sentinel-" + key
}
body["conversationId"] = "internal"
body["unknown"] = "must-not-leak"
filtered := FilterOpenAIChatRequestBody(body)
for key := range openAIChatRequestParameters {
if _, ok := filtered[key]; !ok {
t.Fatalf("official Chat parameter %q was removed", key)
}
}
for _, key := range []string{"conversationId", "unknown"} {
if _, ok := filtered[key]; ok {
t.Fatalf("internal/unknown parameter %q leaked upstream", key)
}
}
}
func TestOpenAIResponsesOfficialParametersSurviveBoundary(t *testing.T) {
body := map[string]any{}
for key := range openAIResponsesRequestParameters {
body[key] = "sentinel-" + key
}
body["request_id"] = "internal"
body["unknown"] = "must-not-leak"
filtered := FilterOpenAIResponsesRequestBody(body)
for key := range openAIResponsesRequestParameters {
if _, ok := filtered[key]; !ok {
t.Fatalf("official Responses parameter %q was removed", key)
}
}
for _, key := range []string{"request_id", "unknown"} {
if _, ok := filtered[key]; ok {
t.Fatalf("internal/unknown parameter %q leaked upstream", key)
}
}
}
func TestValidateOpenAIRequestParametersRejectsUnknownTopLevelField(t *testing.T) {
err := ValidateOpenAIRequestParameters("responses", map[string]any{"model": "demo", "input": "hello", "rogue": true})
if err == nil || ErrorCode(err) != "invalid_parameter" || !strings.Contains(err.Error(), "rogue") {
t.Fatalf("expected OpenAI-style invalid_parameter for rogue field, got %v", err)
}
if ErrorParam(err) != "rogue" {
t.Fatalf("expected rogue parameter attribution, got %q", ErrorParam(err))
}
if err := ValidateOpenAIRequestParameters("responses", map[string]any{"model": "demo", "input": "hello", "messages": []any{}, "request_id": "internal"}); err != nil {
t.Fatalf("expected controlled Responses extensions to remain accepted, got %v", err)
}
}
func TestResponsesFallbackMapsEquivalentCurrentParameters(t *testing.T) {
body, err := ResponsesRequestToChat(map[string]any{
"input": "hello", "store": false, "metadata": map[string]any{"trace": "1"},
"request_id": "internal-request", "platform_id": "internal-platform",
"moderation": map[string]any{"type": "auto"}, "prompt_cache_key": "cache-key",
"prompt_cache_options": map[string]any{"type": "ephemeral"}, "prompt_cache_retention": "in_memory",
"safety_identifier": "safe", "service_tier": "priority", "top_logprobs": 3,
"stream_options": map[string]any{"include_usage": true},
"text": map[string]any{"format": map[string]any{"type": "text"}, "verbosity": "low"},
}, nil)
if err != nil {
t.Fatalf("convert Responses request: %v", err)
}
for _, key := range []string{"store", "metadata", "moderation", "prompt_cache_key", "prompt_cache_options", "prompt_cache_retention", "safety_identifier", "service_tier", "top_logprobs", "stream_options", "verbosity"} {
if _, ok := body[key]; !ok {
t.Fatalf("equivalent parameter %q was not mapped", key)
}
}
if body["logprobs"] != true {
t.Fatalf("top_logprobs fallback must enable Chat logprobs: %+v", body)
}
for _, key := range []string{"request_id", "platform_id"} {
if _, ok := body[key]; ok {
t.Fatalf("internal Responses parameter %q leaked into Chat fallback: %+v", key, body)
}
}
}

41
apps/api/internal/clients/responses_compat.go
View File

@ -21,11 +21,16 @@ var supportedResponseFallbackParameters = map[string]struct{}{
"model": {}, "input": {}, "messages": {}, "instructions": {}, "tools": {}, "tool_choice": {},
"parallel_tool_calls": {}, "max_output_tokens": {}, "temperature": {}, "top_p": {},
"presence_penalty": {}, "frequency_penalty": {}, "reasoning": {}, "text": {},
"stream": {}, "store": {}, "previous_response_id": {}, "metadata": {}, "user": {},
"stream": {}, "stream_options": {}, "store": {}, "previous_response_id": {}, "metadata": {}, "user": {},
"moderation": {}, "prompt_cache_key": {}, "prompt_cache_options": {}, "prompt_cache_retention": {},
"safety_identifier": {}, "service_tier": {}, "top_logprobs": {},
}
func ResponsesRequestToChat(body map[string]any, history []ResponseTurn) (map[string]any, error) {
for key := range body {
if _, internal := gatewayOpenAIRequestExtensions[key]; internal {
continue
}
if _, ok := supportedResponseFallbackParameters[key]; !ok {
return nil, unsupportedResponseParameter(key)
}
@ -61,11 +66,19 @@ func ResponsesRequestToChat(body map[string]any, history []ResponseTurn) (map[st
return nil, &ClientError{Code: "invalid_parameter", Message: "input is required", StatusCode: http.StatusBadRequest}
}
out := map[string]any{"messages": messages}
for _, key := range []string{"temperature", "top_p", "presence_penalty", "frequency_penalty", "parallel_tool_calls", "stream", "user"} {
for _, key := range []string{
"temperature", "top_p", "presence_penalty", "frequency_penalty", "parallel_tool_calls",
"stream", "stream_options", "store", "metadata", "user", "moderation", "prompt_cache_key",
"prompt_cache_options", "prompt_cache_retention", "safety_identifier", "service_tier",
} {
if value, ok := body[key]; ok {
out[key] = value
}
}
if value, ok := body["top_logprobs"]; ok {
out["top_logprobs"] = value
out["logprobs"] = true
}
if value, ok := body["max_output_tokens"]; ok {
out["max_tokens"] = value
}
@ -84,13 +97,16 @@ func ResponsesRequestToChat(body map[string]any, history []ResponseTurn) (map[st
}
}
if rawText, ok := body["text"]; ok {
responseFormat, err := responseTextFormat(rawText)
responseFormat, verbosity, err := responseTextParams(rawText)
if err != nil {
return nil, err
}
if responseFormat != nil {
out["response_format"] = responseFormat
}
if verbosity != nil {
out["verbosity"] = verbosity
}
}
if rawTools, ok := body["tools"]; ok {
tools, err := responseToolsToChat(rawTools)
@ -212,31 +228,32 @@ func responseToolChoiceToChat(value any) (any, error) {
return map[string]any{"type": "function", "function": map[string]any{"name": choice["name"]}}, nil
}
func responseTextFormat(value any) (map[string]any, error) {
func responseTextParams(value any) (map[string]any, any, error) {
text, ok := value.(map[string]any)
if !ok {
return nil, unsupportedResponseParameter("text")
return nil, nil, unsupportedResponseParameter("text")
}
for key := range text {
if key != "format" {
return nil, unsupportedResponseParameter("text." + key)
if key != "format" && key != "verbosity" {
return nil, nil, unsupportedResponseParameter("text." + key)
}
}
verbosity := text["verbosity"]
format, ok := text["format"].(map[string]any)
if !ok || len(format) == 0 {
return nil, nil
return nil, verbosity, nil
}
switch stringFromAny(format["type"]) {
case "text":
return map[string]any{"type": "text"}, nil
return map[string]any{"type": "text"}, verbosity, nil
case "json_object":
return map[string]any{"type": "json_object"}, nil
return map[string]any{"type": "json_object"}, verbosity, nil
case "json_schema":
return map[string]any{"type": "json_schema", "json_schema": map[string]any{
"name": format["name"], "schema": format["schema"], "strict": format["strict"],
}}, nil
}}, verbosity, nil
default:
return nil, unsupportedResponseParameter("text.format.type")
return nil, nil, unsupportedResponseParameter("text.format.type")
}
}

6
apps/api/internal/clients/responses_compat_test.go
View File

@ -23,6 +23,10 @@ func TestOpenAIResponsesNativeUsesResponsesEndpointAndPreservesVendorIDs(t *test
if body["messages"] != nil {
t.Fatalf("native Responses request must not contain messages: %+v", body)
}
input, _ := body["input"].([]any)
if len(input) != 1 {
t.Fatalf("native Responses request must translate controlled messages to input: %+v", body)
}
if body["previous_response_id"] != "resp_upstream_parent" {
t.Fatalf("expected translated upstream previous id, got %+v", body["previous_response_id"])
}
@ -41,7 +45,7 @@ func TestOpenAIResponsesNativeUsesResponsesEndpointAndPreservesVendorIDs(t *test
response, err := (OpenAIClient{}).Run(context.Background(), Request{
Kind: "responses", Model: "Demo",
Body: map[string]any{"input": "hello", "messages": []any{map[string]any{"role": "user", "content": "illegal"}}},
Body: map[string]any{"messages": []any{map[string]any{"role": "user", "content": "hello"}}},
Candidate: store.RuntimeModelCandidate{BaseURL: server.URL, ProviderModelName: "demo", Credentials: map[string]any{"apiKey": "secret"}},
UpstreamProtocol: ProtocolOpenAIResponses, PublicResponseID: "resp_12345678901234567890123456789012",
PublicPreviousResponseID: "resp_abcdefghijklmnopqrstuvwxyz123456", UpstreamPreviousResponseID: "resp_upstream_parent",

9
apps/api/internal/clients/types.go
View File

@ -103,6 +103,7 @@ type VoiceCloneDeleter interface {
type ClientError struct {
Code string
Message string
Param string
StatusCode int
RequestID string
ResponseStartedAt time.Time
@ -111,6 +112,14 @@ type ClientError struct {
Retryable bool
}
func ErrorParam(err error) string {
var clientErr *ClientError
if errors.As(err, &clientErr) {
return clientErr.Param
}
return ""
}
func (e *ClientError) Error() string {
if e.Message != "" {
return e.Message

85
apps/api/internal/clients/volces.go
View File

@ -74,12 +74,13 @@ func (c VolcesClient) runVideo(ctx context.Context, request Request, apiKey stri
submitStartedAt := time.Now()
submitRequestID := strings.TrimSpace(request.RemoteTaskID)
upstreamTaskID := strings.TrimSpace(request.RemoteTaskID)
taskPath := volcesVideoTaskPath(request)
if upstreamTaskID == "" {
body := volcesVideoBody(request)
if err := validateVolcesVideoTaskBody(body); err != nil {
return Response{}, err
}
submitResult, requestID, err := c.postJSON(ctx, request, request.Candidate.BaseURL, "/contents/generations/tasks", apiKey, body)
submitResult, requestID, err := c.postJSON(ctx, request, request.Candidate.BaseURL, taskPath, apiKey, body)
submitRequestID = requestID
if err != nil {
return Response{}, annotateResponseError(err, submitRequestID, submitStartedAt, time.Now())
@ -112,7 +113,7 @@ func (c VolcesClient) runVideo(ctx context.Context, request Request, apiKey stri
}
pollStartedAt := time.Now()
pollResult, pollRequestID, err := c.getJSON(ctx, request, request.Candidate.BaseURL, "/contents/generations/tasks/"+upstreamTaskID, apiKey)
pollResult, pollRequestID, err := c.getJSON(ctx, request, request.Candidate.BaseURL, taskPath+"/"+upstreamTaskID, apiKey)
pollFinishedAt := time.Now()
requestID := firstNonEmpty(pollRequestID, submitRequestID, upstreamTaskID)
if err != nil {
@ -159,6 +160,21 @@ func (c VolcesClient) runVideo(ctx context.Context, request Request, apiKey stri
}
}
func volcesVideoTaskPath(request Request) string {
path := firstNonEmptyStringValue(
request.Candidate.PlatformConfig,
"volcesVideoTaskPath",
"videoTaskPath",
)
if path == "" {
return "/contents/generations/tasks"
}
if !strings.HasPrefix(path, "/") {
path = "/" + path
}
return strings.TrimRight(path, "/")
}
func (c VolcesClient) postJSON(ctx context.Context, request Request, baseURL string, path string, apiKey string, body map[string]any) (map[string]any, string, error) {
raw, _ := json.Marshal(body)
req, err := http.NewRequestWithContext(ctx, http.MethodPost, joinURL(baseURL, path), bytes.NewReader(raw))
@ -173,7 +189,11 @@ func (c VolcesClient) postJSON(ctx context.Context, request Request, baseURL str
}
requestID := requestIDFromHTTPResponse(resp)
result, err := decodeHTTPResponse(resp)
return result, requestID, err
if err != nil {
return result, requestID, err
}
result, envelopeRequestID, err := normalizeVolcesCompatibleResult(result)
return result, firstNonEmpty(requestID, envelopeRequestID), err
}
func (c VolcesClient) getJSON(ctx context.Context, request Request, baseURL string, path string, apiKey string) (map[string]any, string, error) {
@ -188,7 +208,64 @@ func (c VolcesClient) getJSON(ctx context.Context, request Request, baseURL stri
}
requestID := requestIDFromHTTPResponse(resp)
result, err := decodeHTTPResponse(resp)
return result, requestID, err
if err != nil {
return result, requestID, err
}
result, envelopeRequestID, err := normalizeVolcesCompatibleResult(result)
return result, firstNonEmpty(requestID, envelopeRequestID), err
}
func normalizeVolcesCompatibleResult(result map[string]any) (map[string]any, string, error) {
requestID := firstNonEmpty(
stringFromAny(result["request_id"]),
stringFromAny(result["requestId"]),
)
if errorObject, ok := result["error"].(map[string]any); ok {
code := firstNonEmpty(
stringFromAny(errorObject["code"]),
stringFromAny(errorObject["type"]),
"volces_compatible_error",
)
message := strings.TrimSpace(stringFromAny(errorObject["message"]))
if message == "" {
message = "volces compatible request failed"
}
return result, requestID, &ClientError{
Code: code,
Message: message,
RequestID: requestID,
Retryable: false,
}
}
rawCode, hasCode := result["code"]
if !hasCode {
return result, requestID, nil
}
code, validCode := volcesIntFromAny(rawCode)
if !validCode {
return result, requestID, nil
}
if code != 0 {
message := strings.TrimSpace(stringFromAny(result["message"]))
if message == "" {
message = fmt.Sprintf("volces compatible request failed with code %d", code)
}
return result, requestID, &ClientError{
Code: fmt.Sprintf("volces_%d", code),
Message: message,
RequestID: requestID,
Retryable: false,
}
}
data, ok := result["data"].(map[string]any)
if !ok {
return result, requestID, nil
}
normalized := cloneBody(data)
if requestID != "" && requestIDFromResult(normalized) == "" {
normalized["request_id"] = requestID
}
return normalized, requestID, nil
}
func volcesImageBody(request Request) map[string]any {

129
apps/api/internal/clients/volces_deyun_test.go Normal file
View File

@ -0,0 +1,129 @@
package clients
import (
"context"
"encoding/json"
"net/http"
"net/http/httptest"
"strings"
"testing"
"github.com/easyai/easyai-ai-gateway/apps/api/internal/store"
)
func TestVolcesClientSupportsDeyunEnvelope(t *testing.T) {
var submitted bool
var polled bool
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
if r.Header.Get("Authorization") != "Bearer deyun-secret" {
t.Fatalf("unexpected authorization header: %q", r.Header.Get("Authorization"))
}
switch r.Method + " " + r.URL.Path {
case "POST /c39/api/v3/video/tasks":
submitted = true
_ = json.NewEncoder(w).Encode(map[string]any{
"code": 0,
"request_id": "deyun-submit-request",
"data": map[string]any{"id": "deyun-task-1"},
})
case "GET /c39/api/v3/video/tasks/deyun-task-1":
polled = true
_ = json.NewEncoder(w).Encode(map[string]any{
"code": 0,
"request_id": "deyun-poll-request",
"data": map[string]any{
"id": "deyun-task-1",
"status": "succeeded",
"created_at": 123,
"content": map[string]any{
"video_url": "https://example.com/deyun.mp4",
},
},
})
default:
t.Fatalf("unexpected request %s %s", r.Method, r.URL.Path)
}
}))
defer server.Close()
response, err := (VolcesClient{HTTPClient: server.Client()}).Run(context.Background(), Request{
Kind: "videos.generations",
ModelType: "video_generate",
Model: "deyun-seedance-2.0-canary",
Body: map[string]any{
"prompt": "A red cube rotates on a white table",
"resolution": "480p",
"ratio": "16:9",
"duration": 4,
"generate_audio": false,
},
Candidate: store.RuntimeModelCandidate{
BaseURL: server.URL + "/c39/api/v3",
ProviderModelName: "doubao-seedance-2-0",
Credentials: map[string]any{"apiKey": "deyun-secret"},
PlatformConfig: map[string]any{
"volcesPollIntervalMs": 100,
"volcesPollTimeoutSeconds": 1,
"volcesVideoTaskPath": "/video/tasks",
},
},
})
if err != nil {
t.Fatalf("run deyun-compatible video task: %v", err)
}
if !submitted || !polled {
t.Fatalf("expected submit and poll, submitted=%v polled=%v", submitted, polled)
}
if response.RequestID != "deyun-poll-request" {
t.Fatalf("unexpected request id: %s", response.RequestID)
}
data, _ := response.Result["data"].([]any)
item, _ := data[0].(map[string]any)
if response.Result["upstream_task_id"] != "deyun-task-1" || item["url"] != "https://example.com/deyun.mp4" {
t.Fatalf("unexpected response: %+v", response.Result)
}
}
func TestNormalizeVolcesCompatibleResultPreservesNativeResponse(t *testing.T) {
native := map[string]any{"id": "native-task", "status": "queued"}
got, requestID, err := normalizeVolcesCompatibleResult(native)
if err != nil {
t.Fatalf("normalize native response: %v", err)
}
if got["id"] != "native-task" || requestID != "" {
t.Fatalf("native response changed unexpectedly: %+v requestID=%q", got, requestID)
}
}
func TestNormalizeVolcesCompatibleResultRejectsBusinessError(t *testing.T) {
_, requestID, err := normalizeVolcesCompatibleResult(map[string]any{
"code": 1004,
"message": "Authorization is expired",
"request_id": "deyun-error-request",
})
if err == nil {
t.Fatal("expected business error")
}
if requestID != "deyun-error-request" || ErrorCode(err) != "volces_1004" {
t.Fatalf("unexpected error metadata requestID=%q code=%q err=%v", requestID, ErrorCode(err), err)
}
if !strings.Contains(err.Error(), "Authorization is expired") {
t.Fatalf("unexpected error message: %v", err)
}
}
func TestNormalizeVolcesCompatibleResultRejectsHTTP200ErrorObject(t *testing.T) {
_, _, err := normalizeVolcesCompatibleResult(map[string]any{
"error": map[string]any{
"code": "ModelNotOpen",
"message": "model service is not activated",
"type": "Not Found",
},
})
if err == nil {
t.Fatal("expected HTTP 200 error object to fail")
}
if ErrorCode(err) != "ModelNotOpen" || !strings.Contains(err.Error(), "not activated") {
t.Fatalf("unexpected error: code=%q err=%v", ErrorCode(err), err)
}
}

98
apps/api/internal/httpapi/agent_resources_handlers.go Normal file
View File

@ -0,0 +1,98 @@
package httpapi
import (
"net/http"
gatewaydocs "github.com/easyai/easyai-ai-gateway/apps/api/docs"
"github.com/easyai/easyai-ai-gateway/apps/api/internal/skillbundle"
)
const (
opsManagementSkillDownloadPath = "/api/v1/public/skills/ai-gateway-ops-management/download"
apiDocsJSONPath = "/api-docs-json"
apiDocsYAMLPath = "/api-docs-yaml"
)
// getOpsManagementSkillMetadata godoc
// @Summary 获取 AI Gateway 运维管理 SKILL 元数据
// @Description 返回公开运维管理 SKILL 的名称、版本、模块、下载文件名和机器可读接口文档路径。
// @Tags agent-resources
// @Produce json
// @Success 200 {object} SkillBundleMetadataResponse
// @Failure 500 {object} ErrorEnvelope
// @Router /api/v1/public/skills/ai-gateway-ops-management/metadata [get]
func (s *Server) getOpsManagementSkillMetadata(w http.ResponseWriter, _ *http.Request) {
metadata, err := skillbundle.LoadMetadata()
if err != nil {
s.logger.Error("load operations skill metadata failed", "error", err)
writeError(w, http.StatusInternalServerError, "operations skill metadata unavailable")
return
}
writeJSON(w, http.StatusOK, opsManagementSkillMetadataResponse(metadata))
}
// downloadOpsManagementSkill godoc
// @Summary 下载 AI Gateway 运维管理 SKILL
// @Description 下载可交给 Agent 使用的 ai-gateway-ops-management ZIP 包。
// @Tags agent-resources
// @Produce application/zip
// @Success 200 {file} binary
// @Failure 500 {object} ErrorEnvelope
// @Router /api/v1/public/skills/ai-gateway-ops-management/download [get]
func (s *Server) downloadOpsManagementSkill(w http.ResponseWriter, _ *http.Request) {
metadata, err := skillbundle.LoadMetadata()
if err != nil {
s.logger.Error("load operations skill metadata failed", "error", err)
writeError(w, http.StatusInternalServerError, "operations skill metadata unavailable")
return
}
archive, err := skillbundle.BuildArchive()
if err != nil {
s.logger.Error("build operations skill archive failed", "error", err)
writeError(w, http.StatusInternalServerError, "operations skill download unavailable")
return
}
w.Header().Set("Content-Type", "application/zip")
w.Header().Set("Content-Disposition", `attachment; filename="`+skillbundle.FileName(metadata)+`"`)
w.WriteHeader(http.StatusOK)
_, _ = w.Write(archive)
}
// apiDocsJSON godoc
// @Summary 获取 AI Gateway Swagger JSON
// @Description 返回当前构建内嵌的完整机器可读 Swagger JSON，供 Agent 在 SKILL references 未覆盖接口时查询。
// @Tags agent-resources
// @Produce json
// @Success 200 {object} map[string]interface{}
// @Router /api-docs-json [get]
func (s *Server) apiDocsJSON(w http.ResponseWriter, _ *http.Request) {
w.Header().Set("Content-Type", "application/json; charset=utf-8")
w.WriteHeader(http.StatusOK)
_, _ = w.Write(gatewaydocs.SwaggerJSON)
}
// apiDocsYAML godoc
// @Summary 获取 AI Gateway Swagger YAML
// @Description 返回当前构建内嵌的完整机器可读 Swagger YAML。
// @Tags agent-resources
// @Produce application/yaml
// @Success 200 {string} string
// @Router /api-docs-yaml [get]
func (s *Server) apiDocsYAML(w http.ResponseWriter, _ *http.Request) {
w.Header().Set("Content-Type", "application/yaml; charset=utf-8")
w.WriteHeader(http.StatusOK)
_, _ = w.Write(gatewaydocs.SwaggerYAML)
}
func opsManagementSkillMetadataResponse(metadata skillbundle.Metadata) SkillBundleMetadataResponse {
return SkillBundleMetadataResponse{
Name: metadata.Name,
Version: metadata.Version,
DisplayName: skillbundle.DisplayName,
Modules: metadata.Modules,
FileName: skillbundle.FileName(metadata),
DownloadPath: opsManagementSkillDownloadPath,
APIDocsJSONPath: apiDocsJSONPath,
APIDocsYAMLPath: apiDocsYAMLPath,
}
}

115
apps/api/internal/httpapi/agent_resources_handlers_test.go Normal file
View File

@ -0,0 +1,115 @@
package httpapi
import (
"archive/zip"
"bytes"
"encoding/json"
"io"
"log/slog"
"net/http"
"net/http/httptest"
"strings"
"testing"
)
func TestGetOpsManagementSkillMetadata(t *testing.T) {
server := &Server{logger: slog.New(slog.NewTextHandler(io.Discard, nil))}
request := httptest.NewRequest(http.MethodGet, "/api/v1/public/skills/ai-gateway-ops-management/metadata", nil)
response := httptest.NewRecorder()
server.getOpsManagementSkillMetadata(response, request)
if response.Code != http.StatusOK {
t.Fatalf("expected metadata status 200, got %d: %s", response.Code, response.Body.String())
}
var metadata SkillBundleMetadataResponse
if err := json.Unmarshal(response.Body.Bytes(), &metadata); err != nil {
t.Fatalf("decode metadata: %v", err)
}
if metadata.Name != "ai-gateway-ops-management" || metadata.Version != "1.0.2" {
t.Fatalf("unexpected metadata: %+v", metadata)
}
if len(metadata.Modules) != 1 || metadata.Modules[0] != "model-runtime" {
t.Fatalf("unexpected metadata modules: %+v", metadata.Modules)
}
if metadata.APIDocsJSONPath != "/api-docs-json" || metadata.APIDocsYAMLPath != "/api-docs-yaml" {
t.Fatalf("unexpected API docs paths: %+v", metadata)
}
}
func TestDownloadOpsManagementSkill(t *testing.T) {
server := &Server{logger: slog.New(slog.NewTextHandler(io.Discard, nil))}
request := httptest.NewRequest(http.MethodGet, "/api/v1/public/skills/ai-gateway-ops-management/download", nil)
response := httptest.NewRecorder()
server.downloadOpsManagementSkill(response, request)
if response.Code != http.StatusOK {
t.Fatalf("expected download status 200, got %d: %s", response.Code, response.Body.String())
}
if response.Header().Get("Content-Type") != "application/zip" {
t.Fatalf("unexpected content type: %q", response.Header().Get("Content-Type"))
}
if disposition := response.Header().Get("Content-Disposition"); !strings.Contains(disposition, "ai-gateway-ops-management-v1.0.2.zip") {
t.Fatalf("unexpected content disposition: %q", disposition)
}
raw := response.Body.Bytes()
archive, err := zip.NewReader(bytes.NewReader(raw), int64(len(raw)))
if err != nil {
t.Fatalf("open downloaded archive: %v", err)
}
foundSkill := false
for _, file := range archive.File {
if file.Name == "SKILL.md" {
foundSkill = true
break
}
}
if !foundSkill {
t.Fatalf("downloaded archive does not contain SKILL.md")
}
}
func TestEmbeddedAPIDocs(t *testing.T) {
server := &Server{}
jsonResponse := httptest.NewRecorder()
server.apiDocsJSON(jsonResponse, httptest.NewRequest(http.MethodGet, "/api-docs-json", nil))
if jsonResponse.Code != http.StatusOK {
t.Fatalf("expected JSON docs status 200, got %d", jsonResponse.Code)
}
if jsonResponse.Header().Get("Content-Type") != "application/json; charset=utf-8" {
t.Fatalf("unexpected JSON docs content type: %q", jsonResponse.Header().Get("Content-Type"))
}
var document struct {
Paths map[string]json.RawMessage `json:"paths"`
}
if err := json.Unmarshal(jsonResponse.Body.Bytes(), &document); err != nil {
t.Fatalf("decode embedded Swagger JSON: %v", err)
}
for _, path := range []string{
"/api-docs-json",
"/api/v1/public/skills/ai-gateway-ops-management/download",
"/api/admin/catalog/providers",
"/api/admin/catalog/base-models",
"/api/admin/platforms",
"/api/admin/runtime/policy-sets",
"/api/admin/pricing/rule-sets",
} {
if document.Paths[path] == nil {
t.Fatalf("embedded Swagger JSON missing %q", path)
}
}
yamlResponse := httptest.NewRecorder()
server.apiDocsYAML(yamlResponse, httptest.NewRequest(http.MethodGet, "/api-docs-yaml", nil))
if yamlResponse.Code != http.StatusOK {
t.Fatalf("expected YAML docs status 200, got %d", yamlResponse.Code)
}
if yamlResponse.Header().Get("Content-Type") != "application/yaml; charset=utf-8" {
t.Fatalf("unexpected YAML docs content type: %q", yamlResponse.Header().Get("Content-Type"))
}
if !strings.Contains(yamlResponse.Body.String(), "/api/v1/public/skills/ai-gateway-ops-management/metadata") {
t.Fatalf("embedded Swagger YAML missing operations skill metadata path")
}
}

5
apps/api/internal/httpapi/chat_completions_mode_test.go
View File

@ -142,7 +142,7 @@ func TestWriteCompatibleTaskResponseMapsInvalidParameterToBadRequest(t *testing.
executor := &fakeTaskExecutor{
runErr: &clients.ClientError{
Code: "invalid_parameter",
Message: "reasoning_effort must be one of: none, minimal, low, medium, high, xhigh",
Message: "reasoning_effort must be one of: none, minimal, low, medium, high, xhigh, max",
Retryable: false,
},
}
@ -157,6 +157,9 @@ func TestWriteCompatibleTaskResponseMapsInvalidParameterToBadRequest(t *testing.
if !strings.Contains(recorder.Body.String(), "invalid_parameter") {
t.Fatalf("response should include invalid_parameter code: %s", recorder.Body.String())
}
if !strings.Contains(recorder.Body.String(), `"type":"invalid_request_error"`) || !strings.Contains(recorder.Body.String(), `"param":null`) {
t.Fatalf("response should use OpenAI error fields: %s", recorder.Body.String())
}
}
func TestWriteCompatibleTaskResponseReturnsSSEWhenStreamIsTrue(t *testing.T) {

44
apps/api/internal/httpapi/handlers.go
View File

@ -429,6 +429,10 @@ func (s *Server) createPlatformModel(w http.ResponseWriter, r *http.Request) {
}
model, err := s.store.CreatePlatformModel(r.Context(), input)
if err != nil {
if errors.Is(err, store.ErrInvalidPlatformModelConfiguration) {
writeError(w, http.StatusBadRequest, err.Error(), "invalid_parameter")
return
}
if store.IsNotFound(err) {
writeError(w, http.StatusNotFound, "base model not found")
return
@ -473,6 +477,10 @@ func (s *Server) replacePlatformModels(w http.ResponseWriter, r *http.Request) {
models, err := s.store.ReplacePlatformModels(r.Context(), platformID, input.Models)
if err != nil {
if errors.Is(err, store.ErrInvalidPlatformModelConfiguration) {
writeError(w, http.StatusBadRequest, err.Error(), "invalid_parameter")
return
}
if store.IsNotFound(err) {
writeError(w, http.StatusNotFound, "base model not found")
return
@ -979,7 +987,6 @@ func (s *Server) listModelRateLimitStatuses(w http.ResponseWriter, r *http.Reque
// @Failure 404 {object} ErrorEnvelope
// @Failure 429 {object} ErrorEnvelope
// @Failure 502 {object} ErrorEnvelope
// @Router /api/v1/responses [post]
// @Router /api/v1/embeddings [post]
// @Router /api/v1/reranks [post]
// @Router /api/v1/images/generations [post]
@ -989,8 +996,6 @@ func (s *Server) listModelRateLimitStatuses(w http.ResponseWriter, r *http.Reque
// @Router /api/v1/music/generations [post]
// @Router /api/v1/speech/generations [post]
// @Router /api/v1/voice_clone [post]
// @Router /chat/completions [post]
// @Router /v1/chat/completions [post]
// @Router /embeddings [post]
// @Router /v1/embeddings [post]
// @Router /reranks [post]
@ -1024,6 +1029,12 @@ func (s *Server) createTask(kind string, compatible bool) http.Handler {
writeError(w, status, err.Error(), clients.ErrorCode(err))
return
}
if kind == "chat.completions" || kind == "responses" {
if err := clients.ValidateOpenAIRequestParameters(kind, body); err != nil {
writeErrorWithDetails(w, http.StatusBadRequest, err.Error(), map[string]any{"param": clients.ErrorParam(err)}, clients.ErrorCode(err))
return
}
}
model := requestModelName(body)
if model == "" {
writeError(w, http.StatusBadRequest, "model is required")
@ -1095,7 +1106,7 @@ func (s *Server) createTask(kind string, compatible bool) http.Handler {
// @Produce text/event-stream
// @Security BearerAuth
// @Param X-Async header bool false "该接口忽略此参数"
// @Param input body TaskRequest true "Chat Completions 请求"
// @Param input body ChatCompletionRequest true "Chat Completions 请求"
// @Success 200 {object} ChatCompletionCompatibleResponse
// @Failure 400 {object} ErrorEnvelope
// @Failure 401 {object} ErrorEnvelope
@ -1109,6 +1120,26 @@ func (s *Server) createAPIV1ChatCompletions() http.Handler {
return s.createTask("chat.completions", false)
}
// openAIChatCompletionsDoc godoc
// @Summary 创建 OpenAI Chat Completions
// @Description OpenAI-compatible Chat Completions 入口；仅接受官方字段及文档声明的 EasyAI 路由扩展，未知顶层字段返回 400 invalid_parameter。
// @Tags chat
// @Accept json
// @Produce json
// @Produce text/event-stream
// @Security BearerAuth
// @Param input body ChatCompletionRequest true "Chat Completions 请求"
// @Success 200 {object} ChatCompletionCompatibleResponse
// @Failure 400 {object} ErrorEnvelope "invalid_parameter"
// @Failure 401 {object} ErrorEnvelope
// @Failure 402 {object} ErrorEnvelope
// @Failure 403 {object} ErrorEnvelope
// @Failure 429 {object} ErrorEnvelope
// @Failure 502 {object} ErrorEnvelope
// @Router /chat/completions [post]
// @Router /v1/chat/completions [post]
func openAIChatCompletionsDoc() {}
// openAIResponsesDoc godoc
// @Summary 创建 OpenAI Responses
// @Description 公开 OpenAI-compatible Responses 入口。模型声明 openai_responses 时原生转发，否则使用 Chat Completions 转换；store 缺省为 true。previous_response_id 严格绑定首次成功的平台模型和上游协议，链路不可用时不跨平台续接。未提供 previous_response_id 时由调用方管理完整状态，Gateway 以本轮 input/messages 为准且不追加本地历史。
@ -1127,6 +1158,7 @@ func (s *Server) createAPIV1ChatCompletions() http.Handler {
// @Failure 503 {object} ErrorEnvelope "response_chain_unavailable"
// @Router /responses [post]
// @Router /v1/responses [post]
// @Router /api/v1/responses [post]
func openAIResponsesDoc() {}
func (s *Server) requestExecutionContext(r *http.Request) (context.Context, context.CancelFunc) {
@ -1357,6 +1389,10 @@ func statusFromRunError(err error) int {
return http.StatusServiceUnavailable
case clients.ErrorCode(err) == "bad_request" || clients.ErrorCode(err) == "invalid_parameter" || clients.ErrorCode(err) == "cloned_voice_expired" || clients.ErrorCode(err) == "cloned_voice_unavailable" || clients.ErrorCode(err) == "cloned_voice_platform_unavailable" || clients.ErrorCode(err) == "unsupported_operation" || clients.ErrorCode(err) == "invalid_proxy":
return http.StatusBadRequest
case store.ModelCandidateErrorCode(err) == "invalid_parameter":
return http.StatusBadRequest
case store.ModelCandidateErrorCode(err) == "model_capability_configuration_error":
return http.StatusInternalServerError
case clients.ErrorCode(err) == "cloned_voice_not_found":
return http.StatusNotFound
case store.ModelCandidateErrorCode(err) == "platform_cooling_down" || store.ModelCandidateErrorCode(err) == "model_cooling_down":

194
apps/api/internal/httpapi/keling_simulation_integration_test.go Normal file
View File

@ -0,0 +1,194 @@
package httpapi
import (
"context"
"io"
"log/slog"
"net/http"
"net/http/httptest"
"os"
"strconv"
"strings"
"testing"
"time"
"github.com/easyai/easyai-ai-gateway/apps/api/internal/config"
"github.com/easyai/easyai-ai-gateway/apps/api/internal/store"
)
func TestKeling30TurboSimulationFlow(t *testing.T) {
databaseURL := strings.TrimSpace(os.Getenv("AI_GATEWAY_TEST_DATABASE_URL"))
if databaseURL == "" {
t.Skip("set AI_GATEWAY_TEST_DATABASE_URL to run the Kling simulation integration flow")
}
ctx := context.Background()
applyMigration(t, ctx, databaseURL)
db, err := store.Connect(ctx, databaseURL)
if err != nil {
t.Fatalf("connect store: %v", err)
}
defer db.Close()
serverCtx, cancelServer := context.WithCancel(ctx)
defer cancelServer()
server := httptest.NewServer(NewServerWithContext(serverCtx, config.Config{
AppEnv: "test",
HTTPAddr: ":0",
DatabaseURL: databaseURL,
IdentityMode: "hybrid",
JWTSecret: "test-secret",
CORSAllowedOrigin: "*",
}, db, slog.New(slog.NewTextHandler(io.Discard, nil))))
defer server.Close()
suffix := strconv.FormatInt(time.Now().UnixNano(), 10)
username := "kling_sim_" + suffix
password := "password123"
var registerResponse struct {
AccessToken string `json:"accessToken"`
}
doJSON(t, server.URL, http.MethodPost, "/api/v1/auth/register", "", map[string]any{
"username": username,
"email": username + "@example.com",
"password": password,
}, http.StatusCreated, &registerResponse)
var apiKeyResponse struct {
Secret string `json:"secret"`
}
doJSON(t, server.URL, http.MethodPost, "/api/v1/api-keys", registerResponse.AccessToken, map[string]any{
"name": "kling simulation key",
}, http.StatusCreated, &apiKeyResponse)
if _, err := db.Pool().Exec(ctx, `
UPDATE gateway_users
SET roles = '["admin"]'::jsonb
WHERE username = $1`, username); err != nil {
t.Fatalf("promote Kling simulation user: %v", err)
}
var loginResponse struct {
AccessToken string `json:"accessToken"`
}
doJSON(t, server.URL, http.MethodPost, "/api/v1/auth/login", "", map[string]any{
"account": username,
"password": password,
}, http.StatusOK, &loginResponse)
var gatewayUserID string
if err := db.Pool().QueryRow(
ctx,
`SELECT id::text FROM gateway_users WHERE username = $1`,
username,
).Scan(&gatewayUserID); err != nil {
t.Fatalf("read Kling simulation user id: %v", err)
}
doJSON(t, server.URL, http.MethodPatch, "/api/admin/users/"+gatewayUserID+"/wallet", loginResponse.AccessToken, map[string]any{
"currency": "resource",
"balance": 1000,
"reason": "seed Kling simulation wallet",
}, http.StatusOK, nil)
var platform struct {
ID string `json:"id"`
}
doJSON(t, server.URL, http.MethodPost, "/api/admin/platforms", loginResponse.AccessToken, map[string]any{
"provider": "keling",
"platformKey": "keling-simulation-" + suffix,
"name": "Kling Simulation",
"baseUrl": "https://api-beijing.klingai.com/v1",
"authType": "AccessKey-SecretKey",
"credentials": map[string]any{
"accessKey": "legacy-ak",
"secretKey": "legacy-sk",
},
}, http.StatusCreated, &platform)
doJSON(t, server.URL, http.MethodPost, "/api/admin/platforms/"+platform.ID+"/models", loginResponse.AccessToken, map[string]any{
"canonicalModelKey": "keling:kling-3.0-turbo",
"modelName": "kling-3.0-turbo",
"providerModelName": "kling-3.0-turbo",
"modelAlias": "可灵3.0 Turbo",
"modelType": []string{"video_generate", "image_to_video"},
"displayName": "可灵3.0 Turbo",
}, http.StatusCreated, nil)
assertKeling30TurboSimulationTask := func(
name string,
request map[string]any,
expectedModelType string,
) {
t.Helper()
t.Run(name, func(t *testing.T) {
var response struct {
Task struct {
ID string `json:"id"`
Status string `json:"status"`
RunMode string `json:"runMode"`
ModelType string `json:"modelType"`
ResolvedModel string `json:"resolvedModel"`
Result map[string]any `json:"result"`
Metrics map[string]any `json:"metrics"`
BillingSummary map[string]any `json:"billingSummary"`
FinalChargeAmount float64 `json:"finalChargeAmount"`
ResponseDurationMS int64 `json:"responseDurationMs"`
} `json:"task"`
}
doJSON(
t,
server.URL,
http.MethodPost,
"/api/v1/videos/generations",
apiKeyResponse.Secret,
request,
http.StatusAccepted,
&response,
)
task := response.Task
if task.ID == "" ||
task.Status != "succeeded" ||
task.RunMode != "simulation" ||
task.ModelType != expectedModelType ||
task.ResolvedModel != "kling-3.0-turbo" {
t.Fatalf("unexpected Kling simulation task: %+v", task)
}
data, _ := task.Result["data"].([]any)
item, _ := data[0].(map[string]any)
if item["video_url"] != "/static/simulation/video.mp4" ||
item["assetSource"] != "simulation" {
t.Fatalf("unexpected Kling simulation result: %+v", task.Result)
}
if task.FinalChargeAmount <= 0 ||
task.BillingSummary["finalCharge"] == nil ||
task.Metrics["parameterPreprocessingSummary"] == nil ||
task.ResponseDurationMS <= 0 {
t.Fatalf("Kling simulation should preserve billing, preprocessing and timing: %+v", task)
}
})
}
assertKeling30TurboSimulationTask("text-to-video", map[string]any{
"model": "可灵3.0 Turbo",
"runMode": "simulation",
"simulation": true,
"simulationDurationMs": 5,
"prompt": "A cinematic city reveal",
"duration": 8,
"resolution": "1080p",
"aspect_ratio": "9:16",
"audio": true,
}, "video_generate")
assertKeling30TurboSimulationTask("image-to-video", map[string]any{
"model": "可灵3.0 Turbo",
"runMode": "simulation",
"simulation": true,
"simulationDurationMs": 5,
"prompt": "The subject looks toward the camera",
"image": "https://example.com/first.png",
"duration": 5,
"resolution": "720p",
"audio": true,
}, "image_to_video")
}

126
apps/api/internal/httpapi/openapi_models.go
View File

@ -16,6 +16,17 @@ type ReadyResponse struct {
OK bool `json:"ok" example:"true"`
}
type SkillBundleMetadataResponse struct {
Name string `json:"name" example:"ai-gateway-ops-management"`
Version string `json:"version" example:"1.0.2"`
DisplayName string `json:"displayName" example:"AI Gateway 运维管理"`
Modules []string `json:"modules" example:"model-runtime"`
FileName string `json:"fileName" example:"ai-gateway-ops-management-v1.0.2.zip"`
DownloadPath string `json:"downloadPath" example:"/api/v1/public/skills/ai-gateway-ops-management/download"`
APIDocsJSONPath string `json:"apiDocsJsonPath" example:"/api-docs-json"`
APIDocsYAMLPath string `json:"apiDocsYamlPath" example:"/api-docs-yaml"`
}
type ErrorEnvelope struct {
Error ErrorPayload `json:"error"`
}
@ -24,6 +35,8 @@ type ErrorPayload struct {
Message string `json:"message" example:"invalid json body"`
Status int `json:"status" example:"400"`
Code string `json:"code,omitempty" example:"rate_limit"`
Type string `json:"type,omitempty" example:"invalid_request_error"`
Param any `json:"param,omitempty"`
}
type AuthResponse struct {
@ -182,16 +195,19 @@ type PricingEstimateResponse struct {
type TaskRequest struct {
Model string `json:"model" example:"gpt-4o-mini"`
Messages []ChatMessage `json:"messages,omitempty"`
Input string `json:"input,omitempty" example:"Tell me a short story"`
Input interface{} `json:"input,omitempty"`
Prompt string `json:"prompt,omitempty" example:"A watercolor robot reading a book"`
Text string `json:"text,omitempty" example:"Hello from EasyAI audio synthesis."`
TextFileID string `json:"text_file_id,omitempty" example:""`
VoiceID string `json:"voice_id,omitempty" example:"female-shaonv"`
Stream bool `json:"stream,omitempty" example:"false"`
Stream *bool `json:"stream,omitempty" example:"false"`
RunMode string `json:"runMode,omitempty" example:"simulation"`
MaxTokens int `json:"max_tokens,omitempty" example:"512"`
// ReasoningEffort 推理强度，OpenAI-compatible 请求字段；仅支持 none、minimal、low、medium、high、xhigh。供应商自定义取值由网关按平台适配。
ReasoningEffort string `json:"reasoning_effort,omitempty" example:"medium"`
MaxTokens *int `json:"max_tokens,omitempty" example:"512"`
// MaxCompletionTokens includes visible output and reasoning tokens.
MaxCompletionTokens *int `json:"max_completion_tokens,omitempty" example:"512"`
MaxOutputTokens *int `json:"max_output_tokens,omitempty" example:"512"`
// ReasoningEffort 推理强度，OpenAI-compatible 请求字段；支持 none、minimal、low、medium、high、xhigh、max。供应商自定义取值由网关按平台适配。
ReasoningEffort string `json:"reasoning_effort,omitempty" example:"medium" enums:"none,minimal,low,medium,high,xhigh,max"`
Size string `json:"size,omitempty" example:"1024x1024"`
Duration int `json:"duration,omitempty" example:"5"`
Resolution string `json:"resolution,omitempty" example:"720p"`
@ -212,36 +228,88 @@ type TaskRequest struct {
}
type ChatCompletionRequest struct {
Model string `json:"model" example:"gpt-4o-mini"`
Messages []ChatMessage `json:"messages"`
Temperature float64 `json:"temperature,omitempty" example:"0.7"`
MaxTokens int `json:"max_tokens,omitempty" example:"512"`
// ReasoningEffort 推理强度，OpenAI-compatible 请求字段；仅支持 none、minimal、low、medium、high、xhigh。供应商自定义取值由网关按平台适配。
ReasoningEffort string `json:"reasoning_effort,omitempty" example:"medium"`
Stream bool `json:"stream,omitempty" example:"false"`
RunMode string `json:"runMode,omitempty" example:"simulation"`
Model string `json:"model" example:"gpt-4o-mini"`
Messages []ChatMessage `json:"messages"`
Audio map[string]interface{} `json:"audio,omitempty"`
FrequencyPenalty *float64 `json:"frequency_penalty,omitempty" example:"0"`
FunctionCall interface{} `json:"function_call,omitempty"`
Functions []map[string]interface{} `json:"functions,omitempty"`
LogitBias map[string]interface{} `json:"logit_bias,omitempty"`
Logprobs *bool `json:"logprobs,omitempty"`
MaxCompletionTokens *int `json:"max_completion_tokens,omitempty" example:"512"`
MaxTokens *int `json:"max_tokens,omitempty" example:"512"`
Metadata map[string]interface{} `json:"metadata,omitempty"`
Modalities []string `json:"modalities,omitempty"`
Moderation interface{} `json:"moderation,omitempty"`
N *int `json:"n,omitempty" example:"1"`
ParallelToolCalls *bool `json:"parallel_tool_calls,omitempty"`
Prediction interface{} `json:"prediction,omitempty"`
PresencePenalty *float64 `json:"presence_penalty,omitempty" example:"0"`
PromptCacheKey string `json:"prompt_cache_key,omitempty"`
PromptCacheOptions map[string]interface{} `json:"prompt_cache_options,omitempty"`
PromptCacheRetention string `json:"prompt_cache_retention,omitempty" enums:"in_memory,24h"`
// ReasoningEffort 推理强度，OpenAI-compatible 请求字段；支持 none、minimal、low、medium、high、xhigh、max。供应商自定义取值由网关按平台适配。
ReasoningEffort string `json:"reasoning_effort,omitempty" example:"medium" enums:"none,minimal,low,medium,high,xhigh,max"`
ResponseFormat interface{} `json:"response_format,omitempty"`
SafetyIdentifier string `json:"safety_identifier,omitempty"`
Seed *int `json:"seed,omitempty"`
ServiceTier string `json:"service_tier,omitempty"`
Stop interface{} `json:"stop,omitempty"`
Store *bool `json:"store,omitempty"`
Stream *bool `json:"stream,omitempty" example:"false"`
StreamOptions map[string]interface{} `json:"stream_options,omitempty"`
Temperature *float64 `json:"temperature,omitempty" example:"0.7"`
ToolChoice interface{} `json:"tool_choice,omitempty"`
Tools []map[string]interface{} `json:"tools,omitempty"`
TopLogprobs *int `json:"top_logprobs,omitempty"`
TopP *float64 `json:"top_p,omitempty" example:"1"`
User string `json:"user,omitempty"`
Verbosity string `json:"verbosity,omitempty"`
WebSearchOptions map[string]interface{} `json:"web_search_options,omitempty"`
RunMode string `json:"runMode,omitempty" example:"simulation"`
}
type ChatMessage struct {
Role string `json:"role" example:"user"`
Content string `json:"content" example:"Hello"`
Role string `json:"role" example:"user"`
Content interface{} `json:"content,omitempty"`
Name string `json:"name,omitempty"`
ToolCallID string `json:"tool_call_id,omitempty"`
ToolCalls interface{} `json:"tool_calls,omitempty"`
FunctionCall interface{} `json:"function_call,omitempty"`
}
type ResponsesRequest struct {
Model string `json:"model" example:"Doubao Seed 2.0 Pro"`
Input interface{} `json:"input"`
Instructions string `json:"instructions,omitempty" example:"Answer concisely"`
PreviousResponseID string `json:"previous_response_id,omitempty" example:"resp_0123456789abcdef0123456789abcdef"`
Tools []map[string]interface{} `json:"tools,omitempty"`
ToolChoice interface{} `json:"tool_choice,omitempty"`
ParallelToolCalls bool `json:"parallel_tool_calls,omitempty" example:"true"`
MaxOutputTokens int `json:"max_output_tokens,omitempty" example:"512"`
Reasoning map[string]interface{} `json:"reasoning,omitempty"`
Text map[string]interface{} `json:"text,omitempty"`
Temperature float64 `json:"temperature,omitempty" example:"0.7"`
TopP float64 `json:"top_p,omitempty" example:"1"`
Store *bool `json:"store,omitempty"`
Stream bool `json:"stream,omitempty" example:"false"`
Model string `json:"model" example:"Doubao Seed 2.0 Pro"`
Background *bool `json:"background,omitempty"`
ContextManagement []map[string]interface{} `json:"context_management,omitempty"`
Conversation interface{} `json:"conversation,omitempty"`
Include []string `json:"include,omitempty"`
Input interface{} `json:"input"`
Instructions string `json:"instructions,omitempty" example:"Answer concisely"`
MaxOutputTokens *int `json:"max_output_tokens,omitempty" example:"512"`
MaxToolCalls *int `json:"max_tool_calls,omitempty"`
Metadata map[string]interface{} `json:"metadata,omitempty"`
Moderation interface{} `json:"moderation,omitempty"`
ParallelToolCalls *bool `json:"parallel_tool_calls,omitempty" example:"true"`
PreviousResponseID string `json:"previous_response_id,omitempty" example:"resp_0123456789abcdef0123456789abcdef"`
Prompt interface{} `json:"prompt,omitempty"`
PromptCacheKey string `json:"prompt_cache_key,omitempty"`
PromptCacheOptions map[string]interface{} `json:"prompt_cache_options,omitempty"`
PromptCacheRetention string `json:"prompt_cache_retention,omitempty" enums:"in_memory,24h"`
Reasoning map[string]interface{} `json:"reasoning,omitempty"`
SafetyIdentifier string `json:"safety_identifier,omitempty"`
ServiceTier string `json:"service_tier,omitempty"`
Store *bool `json:"store,omitempty"`
Stream *bool `json:"stream,omitempty" example:"false"`
StreamOptions map[string]interface{} `json:"stream_options,omitempty"`
Temperature *float64 `json:"temperature,omitempty" example:"0.7"`
Text map[string]interface{} `json:"text,omitempty"`
ToolChoice interface{} `json:"tool_choice,omitempty"`
Tools []map[string]interface{} `json:"tools,omitempty"`
TopLogprobs *int `json:"top_logprobs,omitempty"`
TopP *float64 `json:"top_p,omitempty" example:"1"`
Truncation string `json:"truncation,omitempty"`
User string `json:"user,omitempty"`
}
type ResponsesCompatibleResponse struct {

6
apps/api/internal/httpapi/response.go
View File

@ -25,6 +25,12 @@ func writeErrorWithDetails(w http.ResponseWriter, status int, message string, de
if len(codes) > 0 {
if code := strings.TrimSpace(codes[0]); code != "" {
errorPayload["code"] = code
if code == "invalid_parameter" || code == "unsupported_response_parameter" {
errorPayload["type"] = "invalid_request_error"
if _, ok := details["param"]; !ok {
errorPayload["param"] = nil
}
}
}
}
for key, value := range details {

4
apps/api/internal/httpapi/server.go
View File

@ -128,6 +128,10 @@ func NewServerWithContext(ctx context.Context, cfg config.Config, db *store.Stor
mux.HandleFunc("GET /static/simulation/{asset}", serveSimulationAsset)
mux.HandleFunc("GET /static/generated/{asset}", server.serveGeneratedStaticAsset)
mux.HandleFunc("GET /static/uploaded/{asset}", server.serveUploadedStaticAsset)
mux.HandleFunc("GET /api-docs-json", server.apiDocsJSON)
mux.HandleFunc("GET /api-docs-yaml", server.apiDocsYAML)
mux.HandleFunc("GET /api/v1/public/skills/ai-gateway-ops-management/metadata", server.getOpsManagementSkillMetadata)
mux.HandleFunc("GET /api/v1/public/skills/ai-gateway-ops-management/download", server.downloadOpsManagementSkill)
mux.Handle("POST /api/v1/auth/register", server.auth.Require(auth.PermissionPublic, http.HandlerFunc(server.register)))
mux.Handle("POST /api/v1/auth/login", server.auth.Require(auth.PermissionPublic, http.HandlerFunc(server.login)))

232
apps/api/internal/runner/output_token_limit.go Normal file
View File

@ -0,0 +1,232 @@
package runner
import (
"fmt"
"math"
"strings"
"github.com/easyai/easyai-ai-gateway/apps/api/internal/store"
)
const (
volcesOutputTokenThreshold = 10240
volcesOutputCapabilityErrorCode = "model_capability_configuration_error"
volcesOutputInvalidParameterCode = "invalid_parameter"
)
type outputTokenLimitProcessor struct{}
func (outputTokenLimitProcessor) Name() string { return "OutputTokenLimitProcessor" }
func (outputTokenLimitProcessor) ShouldProcess(_ map[string]any, modelType string, context *paramProcessContext) bool {
return context != nil && isOpenAITextGenerationKind(context.kind) && isTextOutputModelType(modelType) && isVolcesCandidate(context.candidate)
}
func (outputTokenLimitProcessor) Process(params map[string]any, modelType string, context *paramProcessContext) bool {
modelMax, sourceType, capabilityValue, ok := candidateMaxOutputTokens(context.candidate, modelType)
path := capabilityPath(sourceType, "max_output_tokens")
if !ok {
return context.reject(
"OutputTokenLimitProcessor",
outputTokenParameter(context.kind),
nil,
"火山引擎文本候选未配置正整数 max_output_tokens，已禁止执行该候选。",
path,
capabilityValue,
)
}
if context.kind == "chat.completions" {
if value, explicit := nonNullParameter(params, "max_tokens"); explicit {
if parsed, valid := positiveInteger(value); !valid || parsed > modelMax {
return context.reject("OutputTokenLimitProcessor", "max_tokens", value, fmt.Sprintf("max_tokens must be a positive integer no greater than the selected Volcengine model limit (%d)", modelMax), path, capabilityValue)
}
return true
}
if _, explicit := nonNullParameter(params, "max_completion_tokens"); explicit {
return true
}
value := defaultVolcesOutputTokens(modelMax)
params["max_tokens"] = value
context.recordChange(
"OutputTokenLimitProcessor", "set", "max_tokens", nil, value,
fmt.Sprintf("火山候选未显式设置输出上限：floor(%d/3)=%d，阈值=%d，注入候选级默认值。", modelMax, modelMax/3, volcesOutputTokenThreshold),
path, capabilityValue,
)
return true
}
if value, explicit := nonNullParameter(params, "max_output_tokens"); explicit {
if parsed, valid := positiveInteger(value); !valid || parsed > modelMax {
return context.reject("OutputTokenLimitProcessor", "max_output_tokens", value, fmt.Sprintf("max_output_tokens must be a positive integer no greater than the selected Volcengine model limit (%d)", modelMax), path, capabilityValue)
}
return true
}
value := defaultVolcesOutputTokens(modelMax)
params["max_output_tokens"] = value
context.recordChange(
"OutputTokenLimitProcessor", "set", "max_output_tokens", nil, value,
fmt.Sprintf("火山候选未显式设置输出上限：floor(%d/3)=%d，阈值=%d，注入候选级默认值。", modelMax, modelMax/3, volcesOutputTokenThreshold),
path, capabilityValue,
)
return true
}
func filterRuntimeCandidatesByOutputTokens(kind string, requestedModel string, modelType string, body map[string]any, candidates []store.RuntimeModelCandidate) ([]store.RuntimeModelCandidate, map[string]any, error) {
if !isOpenAITextGenerationKind(kind) || !isTextOutputModelType(modelType) || len(candidates) == 0 {
return candidates, nil, nil
}
filtered := make([]store.RuntimeModelCandidate, 0, len(candidates))
rejected := make([]map[string]any, 0)
invalidExplicit := false
for _, candidate := range candidates {
if !isVolcesCandidate(candidate) {
filtered = append(filtered, candidate)
continue
}
modelMax, sourceType, raw, configured := candidateMaxOutputTokens(candidate, modelType)
detail := map[string]any{
"platformId": candidate.PlatformID, "platformKey": candidate.PlatformKey, "provider": candidate.Provider,
"platformModelId": candidate.PlatformModelID, "providerModelName": candidate.ProviderModelName,
"modelType": modelType, "capabilityPath": capabilityPath(sourceType, "max_output_tokens"), "capabilityValue": raw,
}
if !configured {
detail["reason"] = "max_output_tokens_missing"
rejected = append(rejected, detail)
continue
}
if parameter, value, explicit := explicitOutputTokenParameter(kind, body); explicit {
parsed, valid := positiveInteger(value)
if !valid || (parameter != "max_completion_tokens" && parsed > modelMax) {
detail["reason"] = "requested_output_tokens_exceed_capability"
detail["parameter"] = parameter
detail["requestedValue"] = value
invalidExplicit = true
rejected = append(rejected, detail)
continue
}
}
filtered = append(filtered, candidate)
}
if len(rejected) == 0 {
return filtered, nil, nil
}
summary := map[string]any{
"filter": "volces_output_token_limit", "kind": kind, "requestedModel": requestedModel, "modelType": modelType,
"candidateCount": len(candidates), "supportedCandidateCount": len(filtered), "filteredCandidateCount": len(rejected),
"threshold": volcesOutputTokenThreshold, "formula": "third=floor(modelMaxOutputTokens/3); default=third>=10240?third:modelMaxOutputTokens",
"rejectedCandidates": rejected,
}
if len(filtered) > 0 {
return filtered, summary, nil
}
code := volcesOutputCapabilityErrorCode
message := "所有火山引擎文本候选都缺少有效的 max_output_tokens 能力配置"
if invalidExplicit {
code = volcesOutputInvalidParameterCode
message = "请求的输出 token 上限超过所有可用火山引擎候选的模型能力"
}
summary["code"] = code
return nil, summary, &store.ModelCandidateUnavailableError{Code: code, Message: message, Details: summary}
}
func defaultVolcesOutputTokens(modelMax int) int {
third := modelMax / 3
if third >= volcesOutputTokenThreshold {
return third
}
return modelMax
}
func isVolcesCandidate(candidate store.RuntimeModelCandidate) bool {
provider := strings.ToLower(strings.TrimSpace(candidate.Provider))
baseURL := strings.ToLower(strings.TrimSpace(candidate.BaseURL))
return provider == "volces-openai" || strings.Contains(baseURL, "volces.com") || strings.Contains(baseURL, "byteplus.com")
}
func candidateMaxOutputTokens(candidate store.RuntimeModelCandidate, modelType string) (int, string, any, bool) {
capabilities := effectiveModelCapability(candidate)
seen := map[string]struct{}{}
for _, candidateType := range []string{candidate.ModelType, modelType, "text_generate"} {
candidateType = strings.TrimSpace(candidateType)
if candidateType == "" {
continue
}
if _, ok := seen[candidateType]; ok {
continue
}
seen[candidateType] = struct{}{}
capability := capabilityForType(capabilities, candidateType)
if capability == nil {
continue
}
raw, exists := capability["max_output_tokens"]
if !exists {
continue
}
value, ok := positiveInteger(raw)
return value, candidateType, raw, ok
}
return 0, firstNonEmptyString(candidate.ModelType, modelType, "text_generate"), nil, false
}
func positiveInteger(value any) (int, bool) {
number := floatFromAny(value)
if number <= 0 || math.Trunc(number) != number || number > float64(math.MaxInt) {
return 0, false
}
return int(number), true
}
func nonNullParameter(body map[string]any, key string) (any, bool) {
value, ok := body[key]
return value, ok && value != nil
}
func explicitOutputTokenParameter(kind string, body map[string]any) (string, any, bool) {
if kind == "responses" {
value, ok := nonNullParameter(body, "max_output_tokens")
return "max_output_tokens", value, ok
}
if value, ok := nonNullParameter(body, "max_tokens"); ok {
return "max_tokens", value, true
}
value, ok := nonNullParameter(body, "max_completion_tokens")
return "max_completion_tokens", value, ok
}
func outputTokenParameter(kind string) string {
if kind == "responses" {
return "max_output_tokens"
}
return "max_tokens"
}
func isOpenAITextGenerationKind(kind string) bool {
return kind == "chat.completions" || kind == "responses"
}
func isTextOutputModelType(modelType string) bool {
switch strings.TrimSpace(modelType) {
case "", "text_generate", "chat", "responses", "text":
return true
default:
return false
}
}
func mergeCandidateFilterSummaries(summaries ...map[string]any) map[string]any {
nonEmpty := make([]any, 0, len(summaries))
for _, summary := range summaries {
if len(summary) > 0 {
nonEmpty = append(nonEmpty, summary)
}
}
if len(nonEmpty) == 0 {
return nil
}
if len(nonEmpty) == 1 {
return nonEmpty[0].(map[string]any)
}
return map[string]any{"filters": nonEmpty}
}

113
apps/api/internal/runner/output_token_limit_test.go Normal file
View File

@ -0,0 +1,113 @@
package runner
import (
"testing"
"github.com/easyai/easyai-ai-gateway/apps/api/internal/store"
)
func volcTextCandidate(maxOutput any) store.RuntimeModelCandidate {
capability := map[string]any{}
if maxOutput != nil {
capability["max_output_tokens"] = maxOutput
}
return store.RuntimeModelCandidate{
Provider: "volces-openai", BaseURL: "https://ark.cn-beijing.volces.com/api/v3",
ModelType: "text_generate", ProviderModelName: "demo",
Capabilities: map[string]any{"text_generate": capability},
}
}
func TestDefaultVolcesOutputTokens(t *testing.T) {
tests := []struct {
name string
max int
want int
}{
{name: "128K", max: 131072, want: 43690},
{name: "32K", max: 32768, want: 10922},
{name: "24K below threshold", max: 24576, want: 24576},
{name: "threshold exact", max: 30720, want: 10240},
{name: "threshold minus one", max: 30719, want: 30719},
{name: "floor", max: 131071, want: 43690},
}
for _, test := range tests {
t.Run(test.name, func(t *testing.T) {
if got := defaultVolcesOutputTokens(test.max); got != test.want {
t.Fatalf("defaultVolcesOutputTokens(%d)=%d, want %d", test.max, got, test.want)
}
})
}
}
func TestVolcesOutputProcessorInjectsCandidateSpecificDefaults(t *testing.T) {
chat := preprocessRequestWithLog("chat.completions", map[string]any{"messages": []any{}, "max_tokens": nil}, volcTextCandidate(131072))
if chat.Err != nil || chat.Body["max_tokens"] != 43690 {
t.Fatalf("unexpected Chat preprocessing: body=%+v err=%v", chat.Body, chat.Err)
}
if len(chat.Log.Changes) != 1 || chat.Log.Changes[0].CapabilityPath != "capabilities.text_generate.max_output_tokens" {
t.Fatalf("expected auditable capability source, got %+v", chat.Log.Changes)
}
responses := preprocessRequestWithLog("responses", map[string]any{"input": "hello", "max_output_tokens": nil}, volcTextCandidate(24576))
if responses.Err != nil || responses.Body["max_output_tokens"] != 24576 {
t.Fatalf("unexpected Responses preprocessing: body=%+v err=%v", responses.Body, responses.Err)
}
}
func TestVolcesOutputProcessorPreservesExplicitLimits(t *testing.T) {
for _, body := range []map[string]any{
{"messages": []any{}, "max_tokens": 1234},
{"messages": []any{}, "max_completion_tokens": 2345},
{"messages": []any{}, "max_tokens": 1234, "max_completion_tokens": 2345},
} {
result := preprocessRequestWithLog("chat.completions", body, volcTextCandidate(32768))
if result.Err != nil || len(result.Log.Changes) != 0 {
t.Fatalf("explicit Chat limit should remain unchanged: body=%+v err=%v changes=%+v", result.Body, result.Err, result.Log.Changes)
}
}
result := preprocessRequestWithLog("responses", map[string]any{"input": "hello", "max_output_tokens": 3456}, volcTextCandidate(32768))
if result.Err != nil || result.Body["max_output_tokens"] != 3456 || len(result.Log.Changes) != 0 {
t.Fatalf("explicit Responses limit should remain unchanged: %+v", result)
}
}
func TestVolcesOutputCandidateFilterSupportsFailover(t *testing.T) {
missing := volcTextCandidate(nil)
missing.PlatformID = "missing"
valid := volcTextCandidate(32768)
valid.PlatformID = "valid"
filtered, summary, err := filterRuntimeCandidatesByOutputTokens("chat.completions", "demo", "text_generate", map[string]any{"messages": []any{}}, []store.RuntimeModelCandidate{missing, valid})
if err != nil || len(filtered) != 1 || filtered[0].PlatformID != "valid" {
t.Fatalf("expected missing capability candidate to be skipped: filtered=%+v summary=%+v err=%v", filtered, summary, err)
}
result := preprocessRequestWithLog("chat.completions", map[string]any{"messages": []any{}}, filtered[0])
if result.Body["max_tokens"] != 10922 {
t.Fatalf("failover candidate must recalculate its own default, got %+v", result.Body)
}
}
func TestVolcesOutputCandidateFilterRejectsMissingAndExceededCapabilities(t *testing.T) {
_, _, err := filterRuntimeCandidatesByOutputTokens("responses", "demo", "text_generate", map[string]any{"input": "hello"}, []store.RuntimeModelCandidate{volcTextCandidate(nil)})
if store.ModelCandidateErrorCode(err) != volcesOutputCapabilityErrorCode {
t.Fatalf("expected capability configuration error, got %v", err)
}
_, _, err = filterRuntimeCandidatesByOutputTokens("chat.completions", "demo", "text_generate", map[string]any{"messages": []any{}, "max_tokens": 32769}, []store.RuntimeModelCandidate{volcTextCandidate(32768)})
if store.ModelCandidateErrorCode(err) != volcesOutputInvalidParameterCode {
t.Fatalf("expected invalid_parameter for explicit limit, got %v", err)
}
}
func TestNonVolcesOutputProcessorDoesNotInject(t *testing.T) {
candidate := volcTextCandidate(131072)
candidate.Provider = "openai"
candidate.BaseURL = "https://api.openai.com/v1"
chat := preprocessRequestWithLog("chat.completions", map[string]any{"messages": []any{}}, candidate)
if _, ok := chat.Body["max_tokens"]; ok {
t.Fatalf("non-Volcengine Chat candidate must remain unchanged: %+v", chat.Body)
}
responses := preprocessRequestWithLog("responses", map[string]any{"input": "hello"}, candidate)
if _, ok := responses.Body["max_output_tokens"]; ok {
t.Fatalf("non-Volcengine Responses candidate must remain unchanged: %+v", responses.Body)
}
}

1
apps/api/internal/runner/param_processor.go
View File

@ -55,6 +55,7 @@ type parameterPreprocessChange struct {
func NewParamProcessorChain() ParamProcessorChain {
return ParamProcessorChain{
processors: []paramProcessor{
outputTokenLimitProcessor{},
resolutionNormalizeProcessor{},
aspectRatioProcessor{},
imageSizeProcessor{},

4
apps/api/internal/runner/pricing.go
View File

@ -28,6 +28,10 @@ func (s *Service) Estimate(ctx context.Context, kind string, model string, body
if err != nil {
return EstimateResult{}, err
}
candidates, _, err = filterRuntimeCandidatesByOutputTokens(kind, model, modelType, body, candidates)
if err != nil {
return EstimateResult{}, err
}
candidate := candidates[0]
body = preprocessRequest(kind, body, candidate)
items := s.estimatedBillings(ctx, user, kind, body, candidate)

5
apps/api/internal/runner/queue_worker.go
View File

@ -88,7 +88,10 @@ func (s *Service) startRiverQueue(ctx context.Context) error {
Queues: map[string]river.QueueConfig{
asyncTaskQueueName: {MaxWorkers: 32},
},
RescueStuckJobsAfter: 30 * time.Second,
// Provider-backed media jobs commonly poll for 10-20 minutes. River may
// execute a still-running job again once this window elapses, so keep the
// rescue horizon above the longest configured provider poll timeout.
RescueStuckJobsAfter: time.Hour,
TestOnly: s.cfg.AppEnv == "test",
Workers: workers,
})

30
apps/api/internal/runner/service.go
View File

@ -230,6 +230,22 @@ func (s *Service) execute(ctx context.Context, task store.GatewayTask, user *aut
}
return Result{Task: failed, Output: failed.Result}, err
}
var outputTokenFilterSummary map[string]any
candidates, outputTokenFilterSummary, err = filterRuntimeCandidatesByOutputTokens(task.Kind, task.Model, modelType, body, candidates)
candidateFilterSummary = mergeCandidateFilterSummaries(candidateFilterSummary, outputTokenFilterSummary)
if err != nil {
candidateFilterMetrics := candidateCapabilityFilterMetrics(candidateFilterSummary)
s.recordFailedAttempt(ctx, failedAttemptRecord{
Task: task, Body: body, AttemptNo: task.AttemptCount + 1, Code: store.ModelCandidateErrorCode(err), Cause: err,
Simulated: task.RunMode == "simulation", Scope: "candidate_output_token_filter", Reason: store.ModelCandidateErrorCode(err),
ExtraMetrics: []map[string]any{candidateFilterMetrics}, ModelType: modelType,
})
failed, finishErr := s.failTask(ctx, task.ID, store.ModelCandidateErrorCode(err), err.Error(), task.RunMode == "simulation", err, candidateFilterMetrics)
if finishErr != nil {
return Result{}, finishErr
}
return Result{Task: failed, Output: failed.Result}, err
}
if task.Kind == "responses" {
candidates, err = prepareResponseCandidates(candidates, responseExecution)
if err != nil {
@ -839,7 +855,7 @@ func (s *Service) runCandidate(ctx context.Context, task store.GatewayTask, user
}
func (s *Service) recordTaskParameterPreprocessing(ctx context.Context, taskID string, attemptID string, attemptNo int, candidate store.RuntimeModelCandidate, log parameterPreprocessingLog) error {
if skipTaskParameterPreprocessingLog(log.ModelType) {
if skipTaskParameterPreprocessingLog(log.ModelType) && !log.Changed {
return nil
}
_, err := s.store.CreateTaskParamPreprocessingLog(ctx, store.CreateTaskParamPreprocessingLogInput{
@ -1348,10 +1364,22 @@ func validateRequest(kind string, body map[string]any) error {
if err := clients.ValidateOpenAIReasoningEffort(body["reasoning_effort"]); err != nil {
return err
}
for _, key := range []string{"max_tokens", "max_completion_tokens"} {
if value, explicit := nonNullParameter(body, key); explicit {
if _, ok := positiveInteger(value); !ok {
return &clients.ClientError{Code: "invalid_parameter", Message: key + " must be a positive integer", Param: key, StatusCode: 400, Retryable: false}
}
}
}
case "responses":
if body["input"] == nil && body["messages"] == nil {
return errors.New("input or messages is required")
}
if value, explicit := nonNullParameter(body, "max_output_tokens"); explicit {
if _, ok := positiveInteger(value); !ok {
return &clients.ClientError{Code: "invalid_parameter", Message: "max_output_tokens must be a positive integer", Param: "max_output_tokens", StatusCode: 400, Retryable: false}
}
}
case "embeddings":
if body["input"] == nil {
return errors.New("input is required")

4
apps/api/internal/runner/service_test.go
View File

@ -16,7 +16,7 @@ func (namedClient) Run(context.Context, clients.Request) (clients.Response, erro
}
func TestValidateRequestAcceptsOpenAIReasoningEffort(t *testing.T) {
for _, effort := range []string{"none", "minimal", "low", "medium", "high", "xhigh"} {
for _, effort := range []string{"none", "minimal", "low", "medium", "high", "xhigh", "max"} {
t.Run(effort, func(t *testing.T) {
err := validateRequest("chat.completions", map[string]any{
"messages": []any{map[string]any{"role": "user", "content": "ping"}},
@ -30,7 +30,7 @@ func TestValidateRequestAcceptsOpenAIReasoningEffort(t *testing.T) {
}
func TestValidateRequestRejectsNonOpenAIReasoningEffort(t *testing.T) {
for _, effort := range []string{"max", "auto"} {
for _, effort := range []string{"auto"} {
t.Run(effort, func(t *testing.T) {
err := validateRequest("chat.completions", map[string]any{
"messages": []any{map[string]any{"role": "user", "content": "ping"}},

122
apps/api/internal/skillbundle/bundle.go Normal file
View File

@ -0,0 +1,122 @@
package skillbundle
import (
"archive/zip"
"bytes"
"embed"
"encoding/json"
"fmt"
"io/fs"
"path"
"regexp"
"sort"
"strings"
"time"
)
const (
Name = "ai-gateway-ops-management"
DisplayName = "AI Gateway 运维管理"
)
const bundleRoot = "content/skills/" + Name
var semverPattern = regexp.MustCompile(`^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$`)
//go:embed content/skills/ai-gateway-ops-management
var bundleFS embed.FS
type Metadata struct {
Name string `json:"name"`
Version string `json:"version"`
Modules []string `json:"modules"`
}
func LoadMetadata() (Metadata, error) {
raw, err := bundleFS.ReadFile(bundleRoot + "/skill.json")
if err != nil {
return Metadata{}, fmt.Errorf("read bundled skill metadata: %w", err)
}
var metadata Metadata
if err := json.Unmarshal(raw, &metadata); err != nil {
return Metadata{}, fmt.Errorf("parse bundled skill metadata: %w", err)
}
if metadata.Name != Name {
return Metadata{}, fmt.Errorf("bundled skill metadata name must be %q", Name)
}
if !semverPattern.MatchString(metadata.Version) {
return Metadata{}, fmt.Errorf("bundled skill metadata version %q is not semver", metadata.Version)
}
if len(metadata.Modules) == 0 {
return Metadata{}, fmt.Errorf("bundled skill metadata modules must not be empty")
}
seen := make(map[string]struct{}, len(metadata.Modules))
for _, module := range metadata.Modules {
module = strings.TrimSpace(module)
if module == "" {
return Metadata{}, fmt.Errorf("bundled skill metadata module must not be empty")
}
if _, exists := seen[module]; exists {
return Metadata{}, fmt.Errorf("bundled skill metadata module %q is duplicated", module)
}
seen[module] = struct{}{}
}
if _, err := bundleFS.ReadFile(bundleRoot + "/SKILL.md"); err != nil {
return Metadata{}, fmt.Errorf("read bundled SKILL.md: %w", err)
}
return metadata, nil
}
func FileName(metadata Metadata) string {
return fmt.Sprintf("%s-v%s.zip", metadata.Name, metadata.Version)
}
func BuildArchive() ([]byte, error) {
if _, err := LoadMetadata(); err != nil {
return nil, err
}
files := make([]string, 0)
if err := fs.WalkDir(bundleFS, bundleRoot, func(filePath string, entry fs.DirEntry, walkErr error) error {
if walkErr != nil {
return walkErr
}
if entry.IsDir() {
return nil
}
relativePath := strings.TrimPrefix(filePath, bundleRoot+"/")
if relativePath == "" || path.IsAbs(relativePath) || path.Clean(relativePath) != relativePath || strings.HasPrefix(relativePath, "../") {
return fmt.Errorf("unsafe bundled skill path %q", relativePath)
}
files = append(files, relativePath)
return nil
}); err != nil {
return nil, fmt.Errorf("walk bundled skill: %w", err)
}
sort.Strings(files)
var output bytes.Buffer
archive := zip.NewWriter(&output)
fixedTime := time.Date(2000, time.January, 1, 0, 0, 0, 0, time.UTC)
for _, relativePath := range files {
raw, err := bundleFS.ReadFile(bundleRoot + "/" + relativePath)
if err != nil {
_ = archive.Close()
return nil, fmt.Errorf("read bundled skill file %q: %w", relativePath, err)
}
header := &zip.FileHeader{Name: relativePath, Method: zip.Deflate}
header.SetModTime(fixedTime)
writer, err := archive.CreateHeader(header)
if err != nil {
_ = archive.Close()
return nil, fmt.Errorf("create bundled skill archive entry %q: %w", relativePath, err)
}
if _, err := writer.Write(raw); err != nil {
_ = archive.Close()
return nil, fmt.Errorf("write bundled skill archive entry %q: %w", relativePath, err)
}
}
if err := archive.Close(); err != nil {
return nil, fmt.Errorf("close bundled skill archive: %w", err)
}
return output.Bytes(), nil
}

95
apps/api/internal/skillbundle/bundle_test.go Normal file
View File

@ -0,0 +1,95 @@
package skillbundle
import (
"archive/zip"
"bytes"
"io"
"slices"
"strings"
"testing"
)
func TestLoadMetadata(t *testing.T) {
metadata, err := LoadMetadata()
if err != nil {
t.Fatalf("load metadata: %v", err)
}
if metadata.Name != Name || metadata.Version != "1.0.2" {
t.Fatalf("unexpected metadata: %+v", metadata)
}
if !slices.Equal(metadata.Modules, []string{"model-runtime"}) {
t.Fatalf("unexpected modules: %+v", metadata.Modules)
}
if FileName(metadata) != "ai-gateway-ops-management-v1.0.2.zip" {
t.Fatalf("unexpected file name: %s", FileName(metadata))
}
}
func TestBuildArchiveContainsOperationsSkill(t *testing.T) {
raw, err := BuildArchive()
if err != nil {
t.Fatalf("build archive: %v", err)
}
archive, err := zip.NewReader(bytes.NewReader(raw), int64(len(raw)))
if err != nil {
t.Fatalf("open archive: %v", err)
}
files := make(map[string]*zip.File, len(archive.File))
for _, file := range archive.File {
files[file.Name] = file
if strings.HasPrefix(file.Name, "/") || strings.Contains(file.Name, "..") {
t.Fatalf("unsafe archive path: %q", file.Name)
}
}
expected := []string{
"SKILL.md",
"agents/openai.yaml",
"skill.json",
"references/api-discovery-and-safety.md",
"references/model-providers-and-base-models.md",
"references/model-pricing-and-policies.md",
"references/model-billing-configuration-and-estimation.md",
"references/model-platforms-and-bindings.md",
"references/model-universal-platforms.md",
"references/model-acceptance-runbook.md",
}
for _, name := range expected {
if files[name] == nil {
t.Fatalf("archive missing %q; files=%v", name, archiveFileNames(archive.File))
}
}
skillFile, err := files["SKILL.md"].Open()
if err != nil {
t.Fatalf("open SKILL.md: %v", err)
}
defer skillFile.Close()
skillContent, err := io.ReadAll(skillFile)
if err != nil {
t.Fatalf("read SKILL.md: %v", err)
}
if !strings.Contains(string(skillContent), "name: "+Name) {
t.Fatalf("SKILL.md frontmatter has unexpected name")
}
billingFile, err := files["references/model-billing-configuration-and-estimation.md"].Open()
if err != nil {
t.Fatalf("open billing reference: %v", err)
}
defer billingFile.Close()
billingContent, err := io.ReadAll(billingFile)
if err != nil {
t.Fatalf("read billing reference: %v", err)
}
for _, required := range []string{"/api/v1/pricing/estimate", "finalChargeAmount", "transactionType=task_billing"} {
if !strings.Contains(string(billingContent), required) {
t.Fatalf("billing reference missing %q", required)
}
}
}
func archiveFileNames(files []*zip.File) []string {
names := make([]string, 0, len(files))
for _, file := range files {
names = append(names, file.Name)
}
return names
}

55
apps/api/internal/skillbundle/content/skills/ai-gateway-ops-management/SKILL.md Normal file
View File

@ -0,0 +1,55 @@
---
name: ai-gateway-ops-management
description: Operate and verify EasyAI AI Gateway administration capabilities. Use when Codex or an Agent needs to inspect, create, update, disable, restore, or troubleshoot AI Gateway providers, base models, pricing and billing configuration, price estimates and wallet deduction reconciliation, runtime policies, runner policies, integration platforms, platform-model bindings, or universal custom-script platforms; also use this skill as the extensible entry point for future AI Gateway operations modules.
---
# AI Gateway Operations Management
Use this skill to operate AI Gateway administration APIs through documented, evidence-first workflows.
## Operating Rules
- Obtain the Gateway API base URL and an administrator JWT before calling management APIs. Admin APIs reject `sk-*` API keys.
- Read `references/api-discovery-and-safety.md` before any write operation.
- Select only the references for the requested module. Do not load unrelated future operations modules.
- Read current state before changing it. Treat PATCH bodies as complete resource configurations unless the reference explicitly says otherwise.
- Never write credentials, tokens, script `authValues`, raw upstream responses, or other secrets into Skill files, logs, commands shown to users, or final summaries.
- Execute ordinary creates and updates only when the user requested the change. Before DELETE, full replacement, bulk reset, platform disablement, or credential clearing, show the current snapshot and impact and obtain explicit confirmation.
- Reuse existing pricing rules, runtime policy sets, providers, protocol clients, base models, and platforms whenever their effective behavior satisfies the target. Do not create a near-duplicate resource merely because the upstream account, base URL, or provider-side model name differs.
- Prefer a supported standard client before using `universal` scripts. Use custom scripts only when the upstream contract cannot be represented by the existing OpenAI, Gemini, or provider-specific clients.
- Do not invent platform config fields or assume an arbitrary config key is enforced. For `universal`, use only the recognized keys documented in `references/model-universal-platforms.md`; treat any extra key as script-owned data available through `context.env`.
- Use the module references as the primary API source. Only when the required API is absent, inspect `<gateway-api-base-url>/api-docs-json`; continue only when path, method, schema, authentication, permission, and side effects are unambiguous.
## Module Routing
### Model Runtime
Use these references for the current v1 module:
- `references/model-providers-and-base-models.md`: provider catalog and base-model lifecycle.
- `references/model-pricing-and-policies.md`: pricing rule sets, runtime policy sets, runner policy, priority, and recovery.
- `references/model-billing-configuration-and-estimation.md`: effective billing configuration, price-estimate calls, simulation/real charge comparison, and wallet reconciliation.
- `references/model-platforms-and-bindings.md`: integration platforms, credentials, platform-model upsert, replacement, and deletion.
- `references/model-universal-platforms.md`: `universal` custom platform triage, configuration, script contracts, and examples.
- `references/model-acceptance-runbook.md`: read-back, catalog, simulation, runtime, billing, and rollback verification.
## Standard Workflow
1. Read `references/api-discovery-and-safety.md` and confirm the API base URL, identity mode, administrator JWT, target documentation, and required credentials.
2. Read the current provider, base-model, pricing, policy, platform, and platform-model records relevant to the request.
3. Reuse an existing pricing rule when its base prices and calculators, combined with the effective platform or platform-model discount, produce the required price. Create a pricing rule only when that combination cannot represent the target.
4. Reuse an existing runtime policy set when its limits, scopes, retry, auto-disable, and degradation behavior match the requirement. Create a policy only for a real semantic difference.
5. Classify the upstream protocol against existing platforms and clients. If compatible, keep the existing `specType` and change only instance configuration such as `baseUrl`, credentials, and bindings. Use `universal` only for an unsupported protocol.
6. Reuse the base model across platforms. Put a platform-specific upstream invocation name in the platform-model `providerModelName`; do not duplicate the base model just because providers use different names.
7. Apply the minimum changes in dependency order: provider, base model, pricing/policy, platform, platform-model binding.
8. Read every changed resource back and verify the effective model catalog.
9. For billing work, read `references/model-billing-configuration-and-estimation.md`, call `/api/v1/pricing/estimate` with the same user identity and request parameters intended for execution, and reconcile the returned candidate, line items, discounts, quantities, and total.
10. Run a simulation or approved real request only after the estimate is accepted. Inspect task billing and wallet transactions; do not assume simulation is free or side-effect-free.
11. Report reused and created resource IDs, effective pricing evidence, protocol-fit evidence, verification results, unresolved risks, and whether the Swagger fallback was used, without exposing secrets.
## Extending This Skill
- Add future modules as one-level files under `references/` with stable prefixes such as `storage-`, `runtime-`, `identity-`, or `network-`.
- Add the module to this routing section and to `skill.json`.
- Increment the `skill.json` version whenever downloadable contents change.
- Keep the same skill name and public download route.

4
apps/api/internal/skillbundle/content/skills/ai-gateway-ops-management/agents/openai.yaml Normal file
View File

@ -0,0 +1,4 @@
interface:
display_name: "AI Gateway 运维管理"
short_description: "管理 AI Gateway 模型、平台、定价与运行策略"
default_prompt: "Use $ai-gateway-ops-management to inspect and safely operate the AI Gateway administration APIs."

73
apps/api/internal/skillbundle/content/skills/ai-gateway-ops-management/references/api-discovery-and-safety.md Normal file
View File

@ -0,0 +1,73 @@
# API Discovery and Safety
## Required Inputs
- Gateway API base URL. When using the bundled Web deployment this commonly includes `/gateway-api`; direct API access commonly uses port `8088`.
- Administrator JWT with the `manager` or `admin` role.
- Target provider documentation and authorization material.
- Clear requested outcome and whether real upstream calls are allowed.
Do not place credentials in files or reusable commands. Use shell environment variables:
```bash
export GATEWAY_BASE_URL='https://gateway.example.com/gateway-api'
export GATEWAY_ADMIN_TOKEN='<administrator-jwt>'
```
## Authentication
Management endpoints under `/api/admin/*` accept administrator user credentials only. A local or server-main `sk-*` API key is rejected even if it has broad model scopes.
For standalone or hybrid deployments, local login can return a JWT:
```bash
curl --fail-with-body \
-H 'Content-Type: application/json' \
-d '{"account":"<admin-account>","password":"<admin-password>"}' \
"$GATEWAY_BASE_URL/api/v1/auth/login"
```
Do not use local login when the deployment requires OIDC or server-main identity. Obtain the deployment's administrator access token instead.
Verify identity and role before writes:
```bash
curl --fail-with-body \
-H "Authorization: Bearer $GATEWAY_ADMIN_TOKEN" \
"$GATEWAY_BASE_URL/api/v1/me"
```
## Request Pattern
Use a temporary request file or a carefully quoted inline body without printing secrets:
```bash
curl --fail-with-body \
-H "Authorization: Bearer $GATEWAY_ADMIN_TOKEN" \
-H 'Content-Type: application/json' \
-X POST \
-d '<json-body>' \
"$GATEWAY_BASE_URL/api/admin/<resource>"
```
Always read current state before PATCH, DELETE, reset, disable, or full replacement. PATCH handlers for providers, base models, pricing rule sets, runtime policy sets, runner policy, and platforms write complete resource shapes rather than merging every omitted field.
## High-impact Operations
Obtain explicit confirmation after showing the current snapshot and impact before:
- Any DELETE request.
- `POST /api/admin/catalog/base-models/reset-all`.
- `PUT /api/admin/platforms/{platformID}/models`.
- Changing a platform status to `disabled`.
- Sending an empty `credentials` object to clear stored credentials.
- Replacing pricing rules or policy contents in a way that removes existing entries.
## Full API Fallback
The live machine-readable documents are:
- `<gateway-api-base-url>/api-docs-json`
- `<gateway-api-base-url>/api-docs-yaml`
Use them only when this Skill does not document the required operation. Before acting, confirm the exact path, method, body, authentication, permission, response, and side effect. Do not infer a write operation from a similarly named endpoint.

85
apps/api/internal/skillbundle/content/skills/ai-gateway-ops-management/references/model-acceptance-runbook.md Normal file
View File

@ -0,0 +1,85 @@
# Model Runtime Acceptance Runbook
## Before Changes
- Record the target deployment and identity mode.
- Confirm administrator identity with `/api/v1/me`.
- Save current provider, base model, pricing rule set, policy set, platform, and platform-model JSON without secrets.
- Confirm whether real upstream calls are allowed; otherwise use simulation.
- Confirm upstream endpoint, auth, model name, capabilities, limits, pricing, and sync/async behavior from documentation.
- Record which existing pricing rule and runtime policy were reused, or the exact semantic mismatch that required a new one.
- For billing changes, save the current effective rule bindings, discounts, user-group policy, wallet balance, and one representative estimate response as described in `model-billing-configuration-and-estimation.md`.
- Record the protocol compatibility decision and why the selected existing `specType` is sufficient, or the concrete gap that requires `universal`.
- When one base model has different upstream names across platforms, confirm each binding resolves the expected `providerModelName`.
## After Configuration
Read back:
- `/api/admin/catalog/providers`
- `/api/admin/catalog/base-models`
- `/api/admin/pricing/rule-sets`
- `/api/admin/runtime/policy-sets`
- `/api/admin/runtime/runner-policy`
- `/api/admin/platforms`
- `/api/admin/models`
Verify that IDs and bindings resolve as intended and no unrelated record was removed or reset.
## Catalog Verification
Use an authorized user JWT:
```bash
curl --fail-with-body \
-H "Authorization: Bearer <user-jwt>" \
"$GATEWAY_BASE_URL/api/v1/model-catalog"
```
Confirm model alias, model types, provider source, effective capabilities, pricing summary, rate limits, permissions, and enabled state.
For pricing, verify the effective rule source and discount source rather than checking IDs only. Confirm whether the platform-model discount overrides the platform default, and compare the estimated or simulated amount with the intended price.
Use `/api/v1/pricing/estimate` for the first read-only calculation. A simulation request is a task execution path and may reserve and settle wallet billing; do not treat it as a read-only replacement for the estimate endpoint.
## Execution Verification
Start with simulation:
```bash
curl --fail-with-body \
-H "Authorization: Bearer <user-jwt-or-approved-api-key>" \
-H 'Content-Type: application/json' \
-d '{
"model": "<model-alias>",
"messages": [{"role":"user","content":"Reply with OK"}],
"runMode": "simulation",
"simulation": true,
"stream": false
}' \
"$GATEWAY_BASE_URL/v1/chat/completions"
```
Simulation verifies Gateway routing, permissions, parameter normalization, pricing, and task behavior, but it does not execute the real universal submit or poll scripts. Validate universal scripts separately against a local mock or approved provider test environment before enabling production traffic.
For media or universal scripts, inspect:
- `/api/workspace/tasks/{taskID}`
- `/api/workspace/tasks/{taskID}/events`
- `/api/workspace/tasks/{taskID}/param-preprocessing`
- `/api/admin/runtime/model-rate-limits`
- `/api/admin/runtime/rate-limit-windows`
With explicit approval, run one real minimal request and verify upstream request ID, normalized output, task completion, `billings`, `billingSummary.totalAmount`, `finalChargeAmount`, and the wallet `task_billing` transaction. Explain any expected estimate difference caused by actual token usage, cached input, generated media duration/audio, preprocessing, or failover to another platform.
## Rollback
- Restore the prior complete resource body with PATCH.
- Restore an individual platform-model binding through POST.
- Use full platform-model PUT only when the saved list is complete and replacement is intentional.
- Remove newly created resources in reverse dependency order only after explicit confirmation.
- Use runtime restore only after the upstream problem is resolved.
## Final Report
Report resource IDs, before/after behavior, requests used for verification, simulation or real mode, billing evidence, remaining risks, rollback readiness, and whether `/api-docs-json` was used. Never include credentials or raw secret-bearing payloads.

249
apps/api/internal/skillbundle/content/skills/ai-gateway-ops-management/references/model-billing-configuration-and-estimation.md Normal file
View File

@ -0,0 +1,249 @@
# Model Billing Configuration and Estimate Reconciliation
## Contents
- Safety and Identity
- Effective Billing Layers
- Billing Configuration Workflow
- Price Estimate Requests
- Estimate Reconciliation
- Task and Wallet Charge Verification
- Expected Differences and Troubleshooting
## Safety and Identity
- Use an administrator JWT with `manager` permission for pricing, base-model, platform, platform-model, or user-group writes. Do not use an `sk-*` API key for management APIs.
- Call `POST /api/v1/pricing/estimate` with the same user JWT or API key that will execute the real request. The subject controls access rules, candidate visibility, API-key scopes, and user-group billing discount.
- The estimate endpoint is read-only for tasks and wallets: it selects and preprocesses a candidate and returns simulated billing lines, but it does not create a task, freeze balance, or debit the wallet.
- A request with `runMode: "simulation"` is different: it enters the task execution and billing path and may create task records, reserve wallet balance, and settle a charge. Use the estimate endpoint first and obtain approval before any task request intended only for billing verification.
- Never expose API keys, administrator JWTs, wallet identifiers, or credentials in reports.
## Effective Billing Layers
Read every applicable layer before changing one:
1. Base model: `pricingRuleSetId` and `baseBillingConfig`.
2. Platform: `pricingRuleSetId`, `defaultPricingMode`, and `defaultDiscountFactor`.
3. Platform model: `pricingRuleSetId`, `billingConfigOverride`, `pricingMode`, and `discountFactor`.
4. User group: `billingDiscountPolicy.discountFactor`.
The runtime resolves an effective billing configuration, then applies discounts. An explicit platform-model rule and `billingConfigOverride` can replace or merge inherited values. Do not infer the final price from one ID; confirm it with an estimate.
The current discount behavior is:
```text
candidate discount = positive platform-model discountFactor
else platform defaultDiscountFactor
effective discount = candidate discount × user-group billingDiscountPolicy.discountFactor
```
The platform and platform-model discount factors do not multiply together. The user-group factor, when positive, multiplies the selected candidate discount.
Pricing rule resource mappings include:
| `resourceType` | Effective use |
| --- | --- |
| `text_input` | uncached input token price per 1,000 tokens |
| `text_cached_input` | cached input token price per 1,000 tokens |
| `text_output` | output token price per 1,000 tokens |
| `text_total` | text prices from `basePrice` and optional `formulaConfig` |
| `image` | image generation base price and dynamic weights |
| `image_edit` | image-edit price; image pricing is a fallback when absent |
| `video` | price per five-second unit plus dynamic weights |
| other types | generic resource base price and weights, such as music or audio |
Common `dynamicWeight` dimensions are `qualityWeights`, `sizeWeights`, `resolutionWeights`, `audioWeights`, `referenceVideoWeights`, and `voiceSpecifiedWeights`. Configure only dimensions used by the runtime and proven by the target product pricing.
## Billing Configuration Workflow
### 1. Capture the current state
```bash
curl --fail-with-body -H "Authorization: Bearer $GATEWAY_ADMIN_TOKEN" \
"$GATEWAY_BASE_URL/api/admin/pricing/rule-sets"
curl --fail-with-body -H "Authorization: Bearer $GATEWAY_ADMIN_TOKEN" \
"$GATEWAY_BASE_URL/api/admin/catalog/base-models"
curl --fail-with-body -H "Authorization: Bearer $GATEWAY_ADMIN_TOKEN" \
"$GATEWAY_BASE_URL/api/admin/platforms"
curl --fail-with-body -H "Authorization: Bearer $GATEWAY_ADMIN_TOKEN" \
"$GATEWAY_BASE_URL/api/admin/models"
curl --fail-with-body -H "Authorization: Bearer $GATEWAY_ADMIN_TOKEN" \
"$GATEWAY_BASE_URL/api/admin/user-groups"
```
Use the runtime subject credential to read its effective group policy and wallet snapshot:
```bash
curl --fail-with-body -H "Authorization: Bearer $RUNTIME_TOKEN" \
"$GATEWAY_BASE_URL/api/workspace/user-groups"
curl --fail-with-body -H "Authorization: Bearer $RUNTIME_TOKEN" \
"$GATEWAY_BASE_URL/api/workspace/wallet"
```
Save IDs and non-secret fields. Record the wallet balance and frozen balance only when a later task charge will be verified.
### 2. Reuse or create the pricing rule
Compare active rules by resource type, unit, base price, `dynamicWeight`, `formulaConfig`, calculator type, currency, and status. Reuse an existing rule when its effective amount can be adjusted with platform or platform-model discounts. Read `model-pricing-and-policies.md` for the rule-set request shape.
Create a new rule only when no existing rule can express the required unit, formula, dimensions, or undiscounted price. `PATCH /api/admin/pricing/rule-sets/{ruleSetID}` replaces all rules in the set, so preserve every required row.
### 3. Bind the minimum required layer
- Put a reusable default rule on the base model with `pricingRuleSetId`.
- Put account-wide pricing on the platform with `pricingRuleSetId` and `defaultDiscountFactor`.
- Put a real per-model exception on the platform model with `pricingRuleSetId`, `discountFactor`, or `billingConfigOverride`.
- Use a user-group `billingDiscountPolicy.discountFactor` only for a subject-wide discount. Read the complete user-group record before PATCH and preserve unrelated rate-limit, quota, recharge, metadata, and status fields.
Avoid copying the same prices into multiple layers. Read back every changed record before estimating.
## Price Estimate Requests
`POST /api/v1/pricing/estimate` accepts a normal request-shaped JSON object plus `kind`. `kind` defaults to `chat.completions`. An API key must have the scope required by the selected kind.
### Chat estimate
```bash
curl --fail-with-body \
-H "Authorization: Bearer $RUNTIME_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"kind": "chat.completions",
"model": "<model-alias>",
"messages": [{"role": "user", "content": "Reply with OK"}],
"max_tokens": 256
}' \
"$GATEWAY_BASE_URL/api/v1/pricing/estimate"
```
Text input tokens are estimated from the request. Output tokens use `max_tokens`; when it is absent or zero, the estimate currently uses 64 output tokens. Use the intended output limit for a meaningful upper-bound comparison.
### Image estimate
```bash
curl --fail-with-body \
-H "Authorization: Bearer $RUNTIME_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"kind": "images.generations",
"model": "<model-alias>",
"prompt": "A small orange cat",
"n": 2,
"size": "1024x1024",
"quality": "high"
}' \
"$GATEWAY_BASE_URL/api/v1/pricing/estimate"
```
### Video estimate
```bash
curl --fail-with-body \
-H "Authorization: Bearer $RUNTIME_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"kind": "videos.generations",
"model": "<model-alias>",
"prompt": "A slow camera move over a lake",
"duration": 12,
"resolution": "1080p",
"audio": true,
"n": 1
}' \
"$GATEWAY_BASE_URL/api/v1/pricing/estimate"
```
The response has this shape:
```json
{
"items": [
{
"model": "example-model",
"modelAlias": "example-model",
"provider": "example",
"platformId": "<platform-id>",
"platformModelId": "<platform-model-id>",
"resourceType": "video",
"unit": "5s_video",
"quantity": 3,
"amount": 12.5,
"currency": "resource",
"discountFactor": 0.8,
"simulated": true,
"durationSeconds": 12,
"durationUnitCount": 3
}
],
"resolver": "effective-pricing-v1",
"totalAmount": 12.5,
"currency": "resource"
}
```
## Estimate Reconciliation
For every estimate, verify:
1. `platformId` and `platformModelId` identify the intended first eligible candidate after permissions, capabilities, output-token limits, priority, and runtime availability are applied.
2. `resourceType`, `unit`, `quantity`, and dimension details match the normalized request.
3. `discountFactor` equals the selected platform/platform-model factor multiplied by the effective user-group factor.
4. Each `amount` matches the configured base price, weights, quantity, and discount.
5. `totalAmount` equals the rounded sum of `items[].amount`, and `currency` is expected.
Useful calculation checks:
```text
text input = input tokens / 1000 × input price × discount
text output = output tokens / 1000 × output price × discount
image = count × base price × quality/size/resolution weights × discount
video = count × ceil(duration seconds / 5) × base price × applicable weights × discount
speech = Unicode character count × audio price × discount
```
Cached input is normally known only after execution. When cached input exists but has no configured price, the runtime currently falls back to one tenth of the normal input price.
If the estimate selects an unexpected platform, do not edit prices to hide the routing problem. Inspect access rules, enabled state, model type, capabilities, priority, cooldown/load, and output-token limits first.
## Task and Wallet Charge Verification
After the read-only estimate is accepted, obtain explicit approval before a simulation or real task if wallet mutation is possible.
1. Record `GET /api/workspace/wallet` before the request.
2. Submit the exact same `kind`, model, and billing-relevant parameters through the corresponding runtime API.
3. Read `GET /api/workspace/tasks/{taskID}` and capture:
- `billings`;
- `billingSummary.totalAmount` and currency;
- `finalChargeAmount`;
- resolved model and candidate evidence from metrics.
4. Query the final wallet debit:
```bash
curl --fail-with-body \
-H "Authorization: Bearer $RUNTIME_TOKEN" \
"$GATEWAY_BASE_URL/api/workspace/wallet/transactions?q=$TASK_ID&transactionType=task_billing&pageSize=20"
```
5. Read the wallet again and compare:
```text
task finalChargeAmount == billingSummary.totalAmount
task finalChargeAmount == task_billing transaction amount
wallet balance before - wallet balance after == task_billing transaction amount
```
The task may also create `reserve` and `release` transactions. Reservation changes frozen balance, not the spend balance; `task_billing` is the final debit to reconcile. Use the task ID as the reference and never sum `reserve`, `release`, and `task_billing` as three charges.
## Expected Differences and Troubleshooting
An estimate and final charge may legitimately differ when:
- actual text input/output or cached-input usage differs from the estimate;
- the request omitted `max_tokens`, so the estimate used the 64-token default;
- generated video duration or audio presence overrides the requested/preprocessed value;
- preprocessing normalizes duration, resolution, count, or model-specific fields;
- the first candidate fails and execution settles on another platform with different pricing;
- the estimate and task used different users, API keys, scopes, groups, or access rules;
- pricing or discount configuration changed between estimate and execution.
When the difference is unexplained, compare the estimate line, task `billings`, task preprocessing log, candidate metrics, effective user group, wallet transaction metadata, and configuration timestamps. Do not change wallet balances to make a mismatch disappear.

123
apps/api/internal/skillbundle/content/skills/ai-gateway-ops-management/references/model-platforms-and-bindings.md Normal file
View File

@ -0,0 +1,123 @@
# Platforms and Platform-model Bindings
## Read Current State
```bash
curl --fail-with-body \
-H "Authorization: Bearer $GATEWAY_ADMIN_TOKEN" \
"$GATEWAY_BASE_URL/api/admin/platforms"
curl --fail-with-body \
-H "Authorization: Bearer $GATEWAY_ADMIN_TOKEN" \
"$GATEWAY_BASE_URL/api/admin/models"
```
Platform responses expose masked `credentialsPreview`, not stored secrets.
## Reuse-compatible Platforms First
Before creating a platform or selecting `universal`:
1. Compare the upstream authentication, endpoint paths, content type, request schema, response schema, and sync/async lifecycle with the clients already represented by existing platform `config.specType` values.
2. If the upstream is compatible with an existing OpenAI, Gemini, or provider-specific client, keep that client type. For another compatible endpoint or account, the protocol layer normally needs only a different `baseUrl`; credentials and account-specific settings remain ordinary platform instance configuration.
3. Reuse the existing platform record only when it represents the same logical account/endpoint and changing it will not redirect unrelated models. Otherwise create another standard platform instance with the same compatible `specType`.
4. Use `universal` only when a documented request, authentication, task lifecycle, or response-mapping requirement cannot be expressed by a standard client.
Do not convert a compatible platform to `universal` merely because the host name, account, or provider-side model name differs.
## Create a Standard Platform
```bash
curl --fail-with-body \
-H "Authorization: Bearer $GATEWAY_ADMIN_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"provider": "example-openai",
"platformKey": "example-openai-primary",
"name": "Example OpenAI Primary",
"internalName": "example-openai-primary",
"baseUrl": "https://api.example.com/v1",
"authType": "bearer",
"credentials": {"apiKey": "<provider-api-key>"},
"config": {"specType": "openai"},
"retryPolicy": {},
"rateLimitPolicy": {},
"defaultPricingMode": "inherit_discount",
"defaultDiscountFactor": 1,
"pricingRuleSetId": "",
"priority": 100,
"status": "enabled"
}' \
"$GATEWAY_BASE_URL/api/admin/platforms"
```
Use `PATCH /api/admin/platforms/{platformID}` with the complete platform body. Omit `credentials` to preserve existing secrets. A non-empty credentials object is merged into stored credentials. An empty object clears credentials and requires explicit confirmation.
## Upsert One Platform Model
`POST /api/admin/platforms/{platformID}/models` inserts or updates the `(platformID, modelName)` binding:
```bash
curl --fail-with-body \
-H "Authorization: Bearer $GATEWAY_ADMIN_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"baseModelId": "<base-model-id>",
"canonicalModelKey": "example-openai:example-chat",
"modelName": "example-chat",
"providerModelName": "example-chat",
"modelAlias": "example-chat",
"modelType": ["text_generate"],
"displayName": "Example Chat",
"capabilityOverride": {},
"pricingMode": "inherit_discount",
"discountFactor": 1,
"pricingRuleSetId": "",
"billingConfigOverride": {},
"permissionConfig": {},
"retryPolicy": {},
"rateLimitPolicy": {},
"runtimePolicySetId": "",
"runtimePolicyOverride": {},
"enabled": true
}' \
"$GATEWAY_BASE_URL/api/admin/platforms/<platform-id>/models"
```
When fields are omitted, defaults may be derived from the base model. For predictable updates, read the current binding and send the intended complete configuration.
### Override the real upstream invocation name
Use the base model as the stable system identity and `providerModelName` as the platform-specific name sent to the upstream API:
- `modelName` is the platform binding key and participates in the `(platformId, modelName)` upsert identity.
- `providerModelName` is the real model/deployment name used by the selected runtime client.
- Bind the same `baseModelId` on multiple platforms and set a different `providerModelName` on each binding when providers expose different invocation names.
- Do not create duplicate base models solely for aliases such as a vendor deployment ID, endpoint ID, dated model ID, or regional model name.
Example:
```json
[
{
"platform": "platform-a",
"baseModelId": "base-example-chat",
"modelName": "example-chat",
"providerModelName": "example-chat-2026-07"
},
{
"platform": "platform-b",
"baseModelId": "base-example-chat",
"modelName": "example-chat",
"providerModelName": "deployment-prod-42"
}
]
```
The current create/upsert implementation stores the platform-model binding as enabled even when the request contains `"enabled": false`. Do not rely on that input field for canary isolation. Use an isolated test deployment or keep the whole platform disabled until configuration review is complete; enable the platform only for an approved protocol test.
## Full Replacement and Deletion
`PUT /api/admin/platforms/{platformID}/models` reconciles the platform to exactly the supplied `models` list. Omitted bindings are deleted together with their platform-model access rules. Never use it for a single-model update.
Delete one binding with `DELETE /api/admin/platform-models/{modelID}` after confirmation. Delete a platform with `DELETE /api/admin/platforms/{platformID}` only after reviewing all bindings and access-rule impact.

139
apps/api/internal/skillbundle/content/skills/ai-gateway-ops-management/references/model-pricing-and-policies.md Normal file
View File

@ -0,0 +1,139 @@
# Model Pricing and Policies
## Contents
- Pricing Rule Sets
- Billing Configuration and Estimate Reconciliation
- Runtime Policy Sets
- Runner Policy and Runtime Recovery
## Pricing Rule Sets
Read rule sets and effective rule rows:
```bash
curl --fail-with-body \
-H "Authorization: Bearer $GATEWAY_ADMIN_TOKEN" \
"$GATEWAY_BASE_URL/api/admin/pricing/rule-sets"
curl --fail-with-body \
-H "Authorization: Bearer $GATEWAY_ADMIN_TOKEN" \
"$GATEWAY_BASE_URL/api/admin/pricing/rules"
```
### Reuse-first pricing decision
Do not create a pricing rule until all existing active rule sets have been compared against the target resource types, units, calculator types, base prices, weights, and conditions.
Evaluate the price that the runtime will actually use:
1. Identify the inherited pricing source from the base model and platform, then check whether the platform-model has an explicit `pricingRuleSetId` or billing override.
2. Reuse the existing rule when it already describes the required raw unit prices and calculators.
3. Apply the effective discount:
- a positive platform-model `discountFactor` takes precedence;
- otherwise `pricingMode: "inherit_discount"` uses the platform `defaultDiscountFactor`;
- AI Gateway does not multiply the platform and platform-model discount factors together.
4. Verify the resulting amount with `/api/v1/pricing/estimate`, simulation billing lines, or an approved test request.
5. Create a new rule set only when no existing rule plus the available platform/platform-model discount can produce the required price or express the required unit/calculator structure.
Do not clone an otherwise identical pricing rule merely to represent a provider or account discount. Keep the reusable base price in the rule and express the instance-specific adjustment with `defaultDiscountFactor` or `discountFactor`.
For the complete binding, estimate, task-charge, and wallet-reconciliation workflow, read `model-billing-configuration-and-estimation.md` before changing billing settings.
Create an example text pricing rule set:
```bash
curl --fail-with-body \
-H "Authorization: Bearer $GATEWAY_ADMIN_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"ruleSetKey": "example-chat-pricing-v1",
"name": "Example Chat Pricing",
"description": "Input and output token pricing",
"category": "model",
"currency": "resource",
"status": "active",
"metadata": {},
"rules": [
{
"ruleKey": "input",
"displayName": "Input tokens",
"resourceType": "text_input",
"unit": "1k_tokens",
"basePrice": 0.001,
"calculatorType": "token_usage",
"priority": 10,
"status": "active"
},
{
"ruleKey": "output",
"displayName": "Output tokens",
"resourceType": "text_output",
"unit": "1k_tokens",
"basePrice": 0.002,
"calculatorType": "token_usage",
"priority": 20,
"status": "active"
}
]
}' \
"$GATEWAY_BASE_URL/api/admin/pricing/rule-sets"
```
`PATCH /api/admin/pricing/rule-sets/{ruleSetID}` replaces the stored rules with the supplied list. Preserve every rule that should remain. Delete only non-default rule sets after checking base-model, platform, and platform-model bindings.
## Runtime Policy Sets
Read and create policies:
```bash
curl --fail-with-body \
-H "Authorization: Bearer $GATEWAY_ADMIN_TOKEN" \
"$GATEWAY_BASE_URL/api/admin/runtime/policy-sets"
```
Compare the existing policy sets before creating one. Reuse a policy when the effective rate-limit metrics, limits, windows, concurrency lease TTL, retry count, auto-disable behavior, degradation behavior, and scope semantics match the target. A different platform name or model name alone is not a reason to duplicate a policy.
Create a new policy only when at least one required behavior cannot be represented by an existing policy plus the supported platform-model override fields. Record the mismatch that justified the new policy.
```json
{
"policyKey": "example-balanced-v1",
"name": "Example Balanced",
"description": "Retry and concurrency policy",
"rateLimitPolicy": {
"rules": [
{"metric": "rpm", "limit": 60, "windowSeconds": 60},
{"metric": "concurrent", "limit": 5, "leaseTtlSeconds": 120}
]
},
"retryPolicy": {"maxRetries": 2},
"autoDisablePolicy": {},
"degradePolicy": {},
"metadata": {},
"status": "active"
}
```
POST the body to `/api/admin/runtime/policy-sets`. Use PATCH with a complete body. Default policy sets cannot be deleted.
## Runner Policy and Runtime Recovery
Read the current global runner policy before changing it:
```bash
curl --fail-with-body \
-H "Authorization: Bearer $GATEWAY_ADMIN_TOKEN" \
"$GATEWAY_BASE_URL/api/admin/runtime/runner-policy"
```
PATCH the same endpoint with the complete current fields plus approved changes to `failoverPolicy`, `hardStopPolicy`, `singleSourcePolicy`, or `cacheAffinityPolicy`.
Operational endpoints:
- `PATCH /api/admin/platforms/{platformID}/dynamic-priority`
- `GET /api/admin/runtime/rate-limit-windows`
- `GET /api/admin/runtime/model-rate-limits`
- `POST /api/admin/runtime/model-rate-limits/{platformModelID}/restore`
Use restore only after identifying whether the model, platform cooldown, or platform disablement was automatic and whether the upstream condition has recovered.

87
apps/api/internal/skillbundle/content/skills/ai-gateway-ops-management/references/model-providers-and-base-models.md Normal file
View File

@ -0,0 +1,87 @@
# Model Providers and Base Models
## Read Current State
```bash
curl --fail-with-body \
-H "Authorization: Bearer $GATEWAY_ADMIN_TOKEN" \
"$GATEWAY_BASE_URL/api/admin/catalog/providers"
curl --fail-with-body \
-H "Authorization: Bearer $GATEWAY_ADMIN_TOKEN" \
"$GATEWAY_BASE_URL/api/admin/catalog/base-models"
```
Public read-only catalog endpoints also exist at `/api/v1/public/catalog/providers` and `/api/v1/public/catalog/base-models`.
## Provider Catalog
Create a provider:
```bash
curl --fail-with-body \
-H "Authorization: Bearer $GATEWAY_ADMIN_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"providerKey": "example-openai",
"code": "example-openai",
"displayName": "Example OpenAI Compatible",
"providerType": "openai",
"defaultBaseUrl": "https://api.example.com/v1",
"defaultAuthType": "APIKey",
"source": "gateway",
"capabilitySchema": {},
"defaultRateLimitPolicy": {},
"metadata": {"protocol": "openai-compatible"},
"status": "active"
}' \
"$GATEWAY_BASE_URL/api/admin/catalog/providers"
```
Use `PATCH /api/admin/catalog/providers/{providerID}` with the complete current provider body to update. `providerType` selects the runtime client through the platform candidate. Common supported values include `openai`, `gemini`, `volces`, `keling`, `minimax`, and `universal`. Unknown types may fall back to the OpenAI client, so never leave a custom integration type ambiguous.
Delete with `DELETE /api/admin/catalog/providers/{providerID}` only after checking platform references and obtaining confirmation.
## Base Model
Create a base model after its provider exists:
```bash
curl --fail-with-body \
-H "Authorization: Bearer $GATEWAY_ADMIN_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"providerKey": "example-openai",
"canonicalModelKey": "example-openai:example-chat",
"providerModelName": "example-chat",
"modelType": ["text_generate"],
"modelAlias": "example-chat",
"displayName": "Example Chat",
"capabilities": {
"text_generate": {
"supportedApiProtocols": ["openai_chat_completions"]
}
},
"baseBillingConfig": {
"textInputPer1k": 0.001,
"textOutputPer1k": 0.002
},
"defaultRateLimitPolicy": {},
"runtimePolicyOverride": {},
"metadata": {"description": "Example OpenAI-compatible chat model"},
"catalogType": "custom",
"defaultSnapshot": {},
"pricingVersion": 1,
"status": "active"
}' \
"$GATEWAY_BASE_URL/api/admin/catalog/base-models"
```
Use `PATCH /api/admin/catalog/base-models/{baseModelID}` with a complete body to update. Do not omit capabilities, billing, policy bindings, metadata, or status unintentionally.
Reset endpoints are destructive:
- `POST /api/admin/catalog/base-models/{baseModelID}/reset`
- `POST /api/admin/catalog/base-models/reset-all`
Only system-seeded models with default snapshots can be reset. Delete with `DELETE /api/admin/catalog/base-models/{baseModelID}` only after checking platform-model bindings.

92
apps/api/internal/skillbundle/content/skills/ai-gateway-ops-management/references/model-universal-platforms.md Normal file
View File

@ -0,0 +1,92 @@
# Universal Custom Platforms
## Selection Rule
Use `universal` only when documented upstream requirements cannot be represented by an existing standard client. Prefer:
1. `openai` for OpenAI-compatible chat, Responses, embeddings, reranks, image generation, or image editing.
2. `gemini` for Gemini `generateContent` contracts.
3. A provider-specific client such as `volces`, `keling`, or `minimax` when implemented.
4. `universal` for non-standard auth, submit/poll lifecycles, payload shaping, or response mapping.
Set the provider catalog `providerType` or platform `config.specType` explicitly to `universal`. An unknown type may fall back to OpenAI behavior.
Do not assume a new platform-model binding can be staged with `enabled: false`; the current upsert path enables it. Isolate tests with the platform status or a dedicated non-production deployment.
## Platform Configuration
Gateway directly recognizes these universal settings in the platform `config` object:
- `specType`
- `submitPath`
- `getTaskURL`
- `pollIntervalMs`
- `pollTimeoutMs` or `timeoutMs`
- `skipParamNormalization`
- `customPreprocessScript`
- `customGetParamsScript`
- `customSubmitScript`
- `customPollScript`
Do not invent additional enforcement fields. Other config keys are only exposed as data through `context.env` unless a custom script explicitly reads and enforces them.
```json
{
"specType": "universal",
"submitPath": "/video/generations",
"getTaskURL": "https://provider.example/tasks/{upstream_task_id}",
"pollIntervalMs": 2000,
"pollTimeoutMs": 600000,
"skipParamNormalization": false,
"customGetParamsScript": {
"video_generate": "function getGenerateParams(params, context) { return { model: context.options.providerModelName, prompt: params.prompt }; }"
},
"customSubmitScript": {
"video_generate": "async function submitTask(payload, context) { const response = await got.post(context.createRequestURL('/video/generations'), { json: payload, headers: { Authorization: 'Bearer ' + context.authValues.apiKey } }).json(); const taskId = String(response.id || ''); if (!/^[A-Za-z0-9._:-]{1,200}$/.test(taskId)) return { status: 'failed', code: 'invalid_response', message: 'invalid upstream task id' }; return { status: 'submitted', task_id: taskId }; }"
},
"customPollScript": {
"video_generate": "async function pollTask(taskId, context) { if (!/^[A-Za-z0-9._:-]{1,200}$/.test(taskId)) return { status: 'failed', code: 'invalid_response', message: 'invalid upstream task id' }; const response = await got.get(context.resolveGetTaskURL(taskId), { headers: { Authorization: 'Bearer ' + context.authValues.apiKey } }).json(); if (response.status === 'done') { const resultUrl = String(response.url || ''); if (!/^https:\\/\\/cdn\\.video\\.example(?:\\/|$)/.test(resultUrl)) return { status: 'failed', code: 'invalid_response', message: 'untrusted result URL' }; return { status: 'succeeded', data: [{ url: resultUrl }] }; } if (response.status === 'failed') return { status: 'failed', code: 'provider_failed', message: String(response.message || 'provider task failed').slice(0, 300) }; if (response.status === 'queued' || response.status === 'processing' || response.status === 'running') return { status: 'processing' }; return { status: 'failed', code: 'invalid_response', message: 'unknown upstream status' }; }"
}
}
```
Script values may be a string applied to all model types or an object keyed by model type with optional `common`.
## Script Contracts
- Preprocess: `(params, type, context)`; return an object merged into normalized parameters. Preferred names include `preprocessParams`, `preprocess`, `main`, and `handler`.
- Get params: `(params, context)`; return the upstream payload object. Preferred names include `getGenerateParams`, `getParams`, `main`, and `handler`.
- Submit: `(payload, context)`; return final success data or an asynchronous task ID. Preferred names include `submitTask`, `submitParams`, `submit`, `main`, and `handler`.
- Poll: `(upstreamTaskID, context)`; return processing, success, or failure state. Preferred names include `pollTask`, `poll`, `main`, and `handler`.
The context includes `baseURL`, `getTaskURL`, `authValues`, `headers`, `payload`, `type`, `options`, `env`, `candidate`, `createRequestURL`, and `resolveGetTaskURL`. The runtime also exposes `fetch`, `got`, and `FormData`.
If a result URL must be restricted, implement the HTTPS and host allowlist check inside the submit or poll script before returning `data`. Merely adding an `allowedResultUrlPrefixes`-style config field has no built-in effect. Do not convert HTTP failures into `processing` unless the upstream documentation proves that retrying the poll is safe.
Do not assume Node.js or browser globals exist. The runtime does not install `URL`, `Buffer`, `process`, `require`, or Node modules. Use the provided context helpers, `fetch`, `got`, `FormData`, and standard ECMAScript string or regular-expression checks.
## Result Shapes
Synchronous success:
```json
{"status":"succeeded","data":[{"url":"https://provider.example/result.png"}]}
```
Asynchronous submit:
```json
{"status":"submitted","task_id":"remote-task-id"}
```
Poll success or failure:
```json
{"status":"succeeded","data":[{"url":"https://provider.example/result.mp4"}]}
```
```json
{"status":"failed","code":"provider_failed","message":"upstream rejected request"}
```
Never log, return, or retain `authValues`, full raw responses, base64 media, Buffers, HTTP response objects, or entire request snapshots. Return only the fields required for routing and normalized output.

7
apps/api/internal/skillbundle/content/skills/ai-gateway-ops-management/skill.json Normal file
View File

@ -0,0 +1,7 @@
{
"name": "ai-gateway-ops-management",
"version": "1.0.2",
"modules": [
"model-runtime"
]
}

12
apps/api/internal/store/identity_pairing_integration_test.go
View File

@ -686,14 +686,10 @@ func newIdentityPairingPostgresTestStore(t *testing.T) *Store {
for _, migrationName := range []string{
"0001_init.sql",
"0061_oidc_server_sessions.sql",
"0067_identity_configuration_revisions.sql",
"0068_identity_onboarding_exchanges.sql",
"0069_identity_pairing_cancellation.sql",
"0070_identity_secret_cleanup_queue.sql",
"0071_identity_pairing_start_reservation.sql",
"0072_identity_secret_cleanup_claim_lifecycle.sql",
"0073_identity_pairing_start_reservation_upgrade.sql",
"0074_identity_pairing_error_categories.sql",
"0065_identity_configuration_revisions.sql",
"0066_identity_onboarding_exchanges.sql",
"0067_identity_secret_cleanup_queue.sql",
"0068_identity_pairing_start_reservation.sql",
} {
migration, err := os.ReadFile(filepath.Join(migrationDirectory, migrationName))
if err != nil {

90
apps/api/internal/store/identity_secret_cleanup_migration_integration_test.go
View File

@ -16,81 +16,53 @@ import (
"github.com/jackc/pgx/v5/pgxpool"
)
func TestIdentitySecretCleanupClaimLifecycleUpgradeMigrationExists(t *testing.T) {
payload, err := os.ReadFile(identitySecretCleanupMigrationPath(t, "0072_identity_secret_cleanup_claim_lifecycle.sql"))
const identitySecretCleanupMigration = "0067_identity_secret_cleanup_queue.sql"
func TestIdentitySecretCleanupMigrationDefinesClaimLifecycle(t *testing.T) {
payload, err := os.ReadFile(identitySecretCleanupMigrationPath(t, identitySecretCleanupMigration))
if err != nil {
t.Fatal(err)
}
content := strings.ToLower(string(payload))
for _, required := range []string{
"add column if not exists status text",
"add column if not exists claim_token uuid",
"add column if not exists lease_expires_at timestamptz",
"alter column status set default 'pending'",
"alter column status set not null",
"gateway_identity_secret_cleanup_status_check",
"create table if not exists gateway_identity_secret_cleanup_queue",
"secret_ref text primary key",
"status text not null default 'pending'",
"claim_token uuid",
"lease_expires_at timestamptz",
"gateway_identity_secret_cleanup_claim_check",
"drop index if exists idx_gateway_identity_secret_cleanup_due",
"create index idx_gateway_identity_secret_cleanup_due",
"idx_gateway_identity_secret_cleanup_due",
} {
if !strings.Contains(content, required) {
t.Fatalf("identity Secret cleanup lifecycle migration is missing %q", required)
t.Fatalf("identity Secret cleanup migration is missing %q", required)
}
}
for _, forbidden := range []string{"secret_value", "client_secret", "machine_secret", "token text"} {
for _, forbidden := range []string{"secret_value", "client_secret", "machine_secret", "token text", "drop ", "set not null"} {
if strings.Contains(content, forbidden) {
t.Fatalf("identity Secret cleanup lifecycle migration stores forbidden value field %q", forbidden)
t.Fatalf("identity Secret cleanup migration contains forbidden content %q", forbidden)
}
}
}
func TestIdentitySecretCleanupClaimLifecycleUpgradeMigratesLegacyQueue(t *testing.T) {
func TestIdentitySecretCleanupMigrationSupportsClaimLifecycle(t *testing.T) {
db := newIdentitySecretCleanupMigrationPostgresStore(t)
ctx := context.Background()
reference := "identity-cleanup-legacy-" + uuid.NewString()
applyIdentitySecretCleanupMigration(t, ctx, db.pool, identitySecretCleanupMigration)
reference := "identity-cleanup-" + uuid.NewString()
if _, err := db.pool.Exec(ctx, `
CREATE TABLE gateway_identity_secret_cleanup_queue (
secret_ref text PRIMARY KEY CHECK (secret_ref ~ '^[a-z0-9][a-z0-9-]{0,127}$'),
not_before timestamptz NOT NULL,
created_at timestamptz NOT NULL DEFAULT now(),
updated_at timestamptz NOT NULL DEFAULT now()
);`); err != nil {
t.Fatalf("create legacy identity Secret cleanup queue: %v", err)
if err := db.QueueIdentitySecretCleanup(ctx, reference, time.Now().Add(-time.Minute)); err != nil {
t.Fatalf("queue identity Secret cleanup: %v", err)
}
if _, err := db.pool.Exec(ctx, `CREATE INDEX idx_gateway_identity_secret_cleanup_due
ON gateway_identity_secret_cleanup_queue(not_before,updated_at)`); err != nil {
t.Fatalf("create legacy identity Secret cleanup due index: %v", err)
}
if _, err := db.pool.Exec(ctx, `INSERT INTO gateway_identity_secret_cleanup_queue(secret_ref,not_before)
VALUES($1,now()-interval '1 minute')`, reference); err != nil {
t.Fatalf("seed legacy identity Secret cleanup row: %v", err)
}
applyIdentitySecretCleanupMigration(t, ctx, db.pool, "0072_identity_secret_cleanup_claim_lifecycle.sql")
var status string
var claimToken, leaseExpiresAt *string
if err := db.pool.QueryRow(ctx, `
SELECT status,claim_token::text,lease_expires_at::text
FROM gateway_identity_secret_cleanup_queue WHERE secret_ref=$1`, reference).
Scan(&status, &claimToken, &leaseExpiresAt); err != nil {
t.Fatalf("read migrated cleanup row: %v", err)
}
if status != "pending" || claimToken != nil || leaseExpiresAt != nil {
t.Fatalf("legacy cleanup row was not backfilled to an unclaimed pending lifecycle")
}
claims, err := db.ClaimIdentitySecretCleanups(ctx, 1, time.Minute)
if err != nil {
t.Fatalf("claim migrated cleanup row: %v", err)
t.Fatalf("claim identity Secret cleanup: %v", err)
}
if len(claims) != 1 || claims[0].Reference != reference || claims[0].ClaimToken == "" {
t.Fatalf("claim migrated cleanup row returned unexpected claim metadata")
t.Fatalf("claim identity Secret cleanup returned unexpected metadata: %#v", claims)
}
completed, err := db.CompleteIdentitySecretCleanup(ctx, reference, claims[0].ClaimToken)
if err != nil || !completed {
t.Fatalf("complete migrated cleanup claim: completed=%t err=%v", completed, err)
t.Fatalf("complete identity Secret cleanup: completed=%t err=%v", completed, err)
}
invalidReference := "identity-cleanup-invalid-" + uuid.NewString()
@ -105,15 +77,11 @@ INSERT INTO gateway_identity_secret_cleanup_queue(
SELECT pg_get_indexdef(indexrelid)
FROM pg_index
WHERE indexrelid='idx_gateway_identity_secret_cleanup_due'::regclass`).Scan(&indexDefinition); err != nil {
t.Fatalf("read upgraded cleanup due index: %v", err)
t.Fatalf("read cleanup due index: %v", err)
}
if !strings.Contains(strings.ToLower(indexDefinition), "(status, not_before, lease_expires_at, updated_at)") {
t.Fatalf("cleanup due index does not cover the claim lifecycle")
t.Fatalf("cleanup due index does not cover the claim lifecycle: %q", indexDefinition)
}
// The production migration runner applies each version once. Reapplying here
// proves that the upgrade also accepts the already-current 0070 schema shape.
applyIdentitySecretCleanupMigration(t, ctx, db.pool, "0072_identity_secret_cleanup_claim_lifecycle.sql")
}
func newIdentitySecretCleanupMigrationPostgresStore(t *testing.T) *Store {
@ -125,12 +93,12 @@ func newIdentitySecretCleanupMigrationPostgresStore(t *testing.T) *Store {
ctx := context.Background()
admin, err := pgxpool.New(ctx, databaseURL)
if err != nil {
t.Fatalf("connect identity Secret cleanup migration test database: %v", err)
t.Fatalf("connect identity migration test database: %v", err)
}
var databaseName string
if err := admin.QueryRow(ctx, `SELECT current_database()`).Scan(&databaseName); err != nil {
admin.Close()
t.Fatalf("read identity Secret cleanup migration test database name: %v", err)
t.Fatalf("read identity migration test database name: %v", err)
}
if !strings.Contains(strings.ToLower(databaseName), "test") {
admin.Close()
@ -141,25 +109,25 @@ func newIdentitySecretCleanupMigrationPostgresStore(t *testing.T) *Store {
schemaIdentifier := pgx.Identifier{schemaName}.Sanitize()
if _, err := admin.Exec(ctx, `CREATE SCHEMA `+schemaIdentifier); err != nil {
admin.Close()
t.Fatalf("create identity Secret cleanup migration test schema: %v", err)
t.Fatalf("create identity migration test schema: %v", err)
}
config, err := pgxpool.ParseConfig(databaseURL)
if err != nil {
_, _ = admin.Exec(ctx, `DROP SCHEMA IF EXISTS `+schemaIdentifier+` CASCADE`)
admin.Close()
t.Fatalf("parse identity Secret cleanup migration test database URL: %v", err)
t.Fatalf("parse identity migration test database URL: %v", err)
}
config.ConnConfig.RuntimeParams["search_path"] = schemaName
pool, err := pgxpool.NewWithConfig(ctx, config)
if err != nil {
_, _ = admin.Exec(ctx, `DROP SCHEMA IF EXISTS `+schemaIdentifier+` CASCADE`)
admin.Close()
t.Fatalf("connect identity Secret cleanup migration test schema: %v", err)
t.Fatalf("connect identity migration test schema: %v", err)
}
t.Cleanup(func() {
pool.Close()
if _, err := admin.Exec(context.Background(), `DROP SCHEMA IF EXISTS `+schemaIdentifier+` CASCADE`); err != nil {
t.Errorf("drop identity Secret cleanup migration test schema: %v", err)
t.Errorf("drop identity migration test schema: %v", err)
}
admin.Close()
})

75
apps/api/internal/store/platform_models.go
View File

@ -3,6 +3,8 @@ package store
import (
"context"
"encoding/json"
"fmt"
"math"
"strings"
"github.com/jackc/pgx/v5"
@ -116,6 +118,9 @@ func (s *Store) createPlatformModel(ctx context.Context, q platformModelQuerier,
if len(capabilities) == 0 {
capabilities = EffectivePlatformModelCapabilities(base.Capabilities, input.CapabilityOverride)
}
if err := validateEnabledVolcesTextModelCapabilities(ctx, q, input, capabilities); err != nil {
return PlatformModel{}, err
}
billingConfig := input.BillingConfig
if len(billingConfig) == 0 {
billingConfig = mergeObjects(base.BaseBillingConfig, input.BillingConfigOverride)
@ -262,6 +267,76 @@ RETURNING id::text, platform_id::text, COALESCE(base_model_id::text, ''), model_
return model, nil
}
func validateEnabledVolcesTextModelCapabilities(ctx context.Context, q platformModelQuerier, input CreatePlatformModelInput, capabilities map[string]any) error {
// createPlatformModel enables/upserts models unconditionally, so every text
// model that reaches this path must already satisfy the Volcengine invariant.
if !containsTextOutputModelType(input.ModelType) {
return nil
}
var provider string
var baseURL string
if err := q.QueryRow(ctx, `SELECT provider, COALESCE(base_url, '') FROM integration_platforms WHERE id = $1::uuid`, input.PlatformID).Scan(&provider, &baseURL); err != nil {
return err
}
provider = strings.ToLower(strings.TrimSpace(provider))
baseURL = strings.ToLower(strings.TrimSpace(baseURL))
if provider != "volces-openai" && !strings.Contains(baseURL, "volces.com") && !strings.Contains(baseURL, "byteplus.com") {
return nil
}
seen := map[string]struct{}{}
for _, modelType := range append(append(StringList{}, input.ModelType...), "text_generate") {
modelType = strings.TrimSpace(modelType)
if modelType == "" {
continue
}
if _, ok := seen[modelType]; ok {
continue
}
seen[modelType] = struct{}{}
capability, _ := capabilities[modelType].(map[string]any)
if value, ok := positiveWholeNumber(capability["max_output_tokens"]); ok && value > 0 {
return nil
}
}
return fmt.Errorf("%w: enabled Volcengine text model %q requires a positive integer max_output_tokens capability for its text model type or text_generate fallback", ErrInvalidPlatformModelConfiguration, input.ProviderModelName)
}
func containsTextOutputModelType(values StringList) bool {
for _, value := range values {
switch strings.ToLower(strings.TrimSpace(value)) {
case "text_generate", "chat", "responses", "text":
return true
}
}
return false
}
func positiveWholeNumber(value any) (int64, bool) {
var number float64
switch typed := value.(type) {
case int:
number = float64(typed)
case int32:
number = float64(typed)
case int64:
number = float64(typed)
case float64:
number = typed
case json.Number:
parsed, err := typed.Float64()
if err != nil {
return 0, false
}
number = parsed
default:
return 0, false
}
if number <= 0 || math.Trunc(number) != number || number > math.MaxInt64 {
return 0, false
}
return int64(number), true
}
func (s *Store) DeletePlatformModel(ctx context.Context, id string) error {
tx, err := s.pool.Begin(ctx)
if err != nil {

5
apps/api/internal/store/runtime_types.go
View File

@ -7,8 +7,9 @@ import (
)
var (
ErrNoModelCandidate = errors.New("no enabled platform model matches request")
ErrRateLimited = errors.New("rate limit exceeded")
ErrNoModelCandidate = errors.New("no enabled platform model matches request")
ErrRateLimited = errors.New("rate limit exceeded")
ErrInvalidPlatformModelConfiguration = errors.New("invalid platform model configuration")
)
type ModelCandidateUnavailableError struct {

216
apps/api/migrations/0062_keling_30_turbo.sql Normal file
View File

@ -0,0 +1,216 @@
UPDATE model_catalog_providers
SET default_auth_type = 'APIKey',
updated_at = now()
WHERE provider_key = 'keling'
OR provider_code = 'keling';
UPDATE integration_platforms
SET auth_type = CASE
WHEN COALESCE(NULLIF(trim(credentials->>'accessKey'), ''), NULLIF(trim(credentials->>'secretKey'), '')) IS NULL
THEN 'APIKey'
ELSE auth_type
END,
credentials = CASE
WHEN credentials ? 'apiKey' THEN credentials
ELSE credentials || '{"apiKey": ""}'::jsonb
END,
updated_at = now()
WHERE provider = 'keling'
AND deleted_at IS NULL;
WITH keling_30_turbo AS (
SELECT
'keling:kling-3.0-turbo' AS canonical_model_key,
'kling-3.0-turbo' AS provider_model_name,
'可灵3.0 Turbo' AS display_name,
'["video_generate","image_to_video"]'::jsonb AS model_type,
'{
"video_generate": {
"aspect_ratio_allowed": ["16:9", "1:1", "9:16"],
"output_resolutions": ["720p", "1080p"],
"duration_range": [3, 15],
"output_audio": true,
"prompt_length_limit": {
"max": 3072,
"label": "可灵3.0 Turbo"
}
},
"image_to_video": {
"output_resolutions": ["720p", "1080p"],
"duration_range": [3, 15],
"input_first_frame": true,
"input_last_frame": false,
"input_first_last_frame": false,
"aspect_ratio_allowed": [],
"output_audio": true,
"input_reference_generate_single": false,
"input_reference_generate_multiple": false,
"support_video_effect_template": false,
"prompt_length_limit": {
"max": 2500,
"label": "可灵3.0 Turbo"
}
},
"originalTypes": ["video_generate", "image_to_video"]
}'::jsonb AS capabilities,
COALESCE(
(
SELECT base_billing_config
FROM base_model_catalog
WHERE canonical_model_key = 'keling:kling-v3'
LIMIT 1
),
'{
"video": {
"basePrice": 100,
"baseWeight": 1,
"dynamicWeight": {
"720p": 1,
"1080p": 1.5,
"audio-true": 2,
"audio-false": 1
}
},
"currency": "resource"
}'::jsonb
) AS base_billing_config,
COALESCE(
(
SELECT default_rate_limit_policy
FROM base_model_catalog
WHERE canonical_model_key = 'keling:kling-v3'
LIMIT 1
),
'{"platformLimits":{"max_concurrent_requests":5}}'::jsonb
) AS default_rate_limit_policy,
'{
"source": "server-main.integration-platform",
"sourceProviderCode": "keling",
"sourceProviderName": "可灵AI",
"sourceSpecType": "keling",
"originalTypes": ["video_generate", "image_to_video"],
"alias": "可灵3.0 Turbo",
"description": "可灵新任务 API 的 3.0 Turbo 文生视频与首帧图生视频模型",
"iconPath": "https://static.51easyai.com/kling-color.webp",
"billingType": "external-api",
"billingMode": "",
"referenceModel": "",
"modelWeight": null,
"selectable": true,
"rawModel": {
"name": "kling-3.0-turbo",
"types": ["video_generate", "image_to_video"],
"alias": "可灵3.0 Turbo",
"icon_path": "https://static.51easyai.com/kling-color.webp"
}
}'::jsonb AS metadata
)
INSERT INTO base_model_catalog (
provider_id,
provider_key,
canonical_model_key,
provider_model_name,
model_type,
display_name,
capabilities,
base_billing_config,
default_rate_limit_policy,
metadata,
catalog_type,
default_snapshot,
status
)
SELECT
(
SELECT id
FROM model_catalog_providers
WHERE provider_key = 'keling' OR provider_code = 'keling'
LIMIT 1
),
'keling',
model.canonical_model_key,
model.provider_model_name,
model.model_type,
model.display_name,
model.capabilities,
model.base_billing_config,
model.default_rate_limit_policy,
jsonb_set(model.metadata, '{rawModel,capabilities}', model.capabilities, true),
'system',
jsonb_build_object(
'providerKey', 'keling',
'canonicalModelKey', model.canonical_model_key,
'providerModelName', model.provider_model_name,
'modelType', model.model_type,
'modelAlias', model.display_name,
'displayName', model.display_name,
'capabilities', model.capabilities,
'baseBillingConfig', model.base_billing_config,
'defaultRateLimitPolicy', model.default_rate_limit_policy,
'metadata', jsonb_set(model.metadata, '{rawModel,capabilities}', model.capabilities, true),
'status', 'active'
),
'active'
FROM keling_30_turbo model
ON CONFLICT (canonical_model_key) DO UPDATE
SET provider_id = EXCLUDED.provider_id,
provider_key = EXCLUDED.provider_key,
provider_model_name = CASE WHEN base_model_catalog.customized_at IS NULL THEN EXCLUDED.provider_model_name ELSE base_model_catalog.provider_model_name END,
model_type = CASE WHEN base_model_catalog.customized_at IS NULL THEN EXCLUDED.model_type ELSE base_model_catalog.model_type END,
display_name = CASE WHEN base_model_catalog.customized_at IS NULL THEN EXCLUDED.display_name ELSE base_model_catalog.display_name END,
capabilities = CASE WHEN base_model_catalog.customized_at IS NULL THEN EXCLUDED.capabilities ELSE base_model_catalog.capabilities END,
base_billing_config = CASE WHEN base_model_catalog.customized_at IS NULL THEN EXCLUDED.base_billing_config ELSE base_model_catalog.base_billing_config END,
default_rate_limit_policy = CASE WHEN base_model_catalog.customized_at IS NULL THEN EXCLUDED.default_rate_limit_policy ELSE base_model_catalog.default_rate_limit_policy END,
metadata = CASE WHEN base_model_catalog.customized_at IS NULL THEN EXCLUDED.metadata ELSE base_model_catalog.metadata END,
catalog_type = CASE WHEN base_model_catalog.customized_at IS NULL THEN 'system' ELSE base_model_catalog.catalog_type END,
default_snapshot = CASE WHEN base_model_catalog.customized_at IS NULL THEN EXCLUDED.default_snapshot ELSE base_model_catalog.default_snapshot END,
status = CASE WHEN base_model_catalog.customized_at IS NULL THEN 'active' ELSE base_model_catalog.status END,
updated_at = now();
INSERT INTO platform_models (
platform_id,
base_model_id,
model_name,
provider_model_name,
model_alias,
model_type,
display_name,
capabilities,
pricing_mode,
billing_config,
retry_policy,
rate_limit_policy,
enabled
)
SELECT
platform.id,
base_model.id,
base_model.provider_model_name,
base_model.provider_model_name,
base_model.display_name,
base_model.model_type,
base_model.display_name,
base_model.capabilities,
'inherit_discount',
base_model.base_billing_config,
'{"enabled":true,"maxAttempts":1}'::jsonb,
base_model.default_rate_limit_policy,
true
FROM integration_platforms platform
JOIN base_model_catalog base_model
ON base_model.canonical_model_key = 'keling:kling-3.0-turbo'
WHERE platform.provider = 'keling'
AND platform.deleted_at IS NULL
ON CONFLICT (platform_id, model_name) DO UPDATE
SET base_model_id = EXCLUDED.base_model_id,
provider_model_name = EXCLUDED.provider_model_name,
model_alias = EXCLUDED.model_alias,
display_name = EXCLUDED.display_name,
model_type = EXCLUDED.model_type,
capabilities = EXCLUDED.capabilities,
pricing_mode = EXCLUDED.pricing_mode,
billing_config = EXCLUDED.billing_config,
retry_policy = EXCLUDED.retry_policy,
rate_limit_policy = EXCLUDED.rate_limit_policy,
enabled = EXCLUDED.enabled,
updated_at = now();

0
apps/api/migrations/0062_oidc_security_events.sql → apps/api/migrations/0063_oidc_security_events.sql
View File

15
apps/api/migrations/0064_security_event_connection_idempotency_repair.sql
View File

@ -1,15 +0,0 @@
-- 0063 was released before its idempotency table was added. Installations that
-- already recorded 0063 need a new immutable migration to repair that drift.
CREATE TABLE IF NOT EXISTS gateway_security_event_connection_idempotency (
operation text NOT NULL,
idempotency_key text NOT NULL,
request_hash text NOT NULL,
response jsonb NOT NULL,
created_at timestamptz NOT NULL DEFAULT now(),
PRIMARY KEY (operation, idempotency_key),
CONSTRAINT gateway_security_event_connection_idempotency_operation
CHECK (operation IN ('connect','verify','rotate','disconnect'))
);
CREATE INDEX IF NOT EXISTS idx_gateway_security_event_connection_idempotency_created
ON gateway_security_event_connection_idempotency(created_at);

6
apps/api/migrations/0063_security_event_connections.sql → apps/api/migrations/0064_security_event_connections.sql
View File

@ -7,6 +7,8 @@ CREATE TABLE IF NOT EXISTS gateway_security_event_connections (
stream_id uuid,
credential_ref text NOT NULL,
next_credential_ref text,
management_client_id text,
management_credential_ref text,
lifecycle_status text NOT NULL,
version bigint NOT NULL DEFAULT 1,
last_error_category text,
@ -19,6 +21,10 @@ CREATE TABLE IF NOT EXISTS gateway_security_event_connections (
)),
CONSTRAINT gateway_security_event_connection_stream_pair CHECK (
(audience IS NULL AND stream_id IS NULL) OR (audience IS NOT NULL AND stream_id IS NOT NULL)
),
CONSTRAINT gateway_security_event_management_credential_pair CHECK (
(management_client_id IS NULL AND management_credential_ref IS NULL) OR
(management_client_id IS NOT NULL AND management_credential_ref IS NOT NULL)
)
);

3
apps/api/migrations/0067_identity_configuration_revisions.sql → apps/api/migrations/0065_identity_configuration_revisions.sql
View File

@ -19,6 +19,9 @@ CREATE TABLE IF NOT EXISTS gateway_identity_configuration_revisions (
legacy_jwt_enabled boolean NOT NULL DEFAULT false,
token_introspection boolean NOT NULL DEFAULT false,
session_revocation boolean NOT NULL DEFAULT false,
security_event_issuer text,
security_event_configuration_url text,
security_event_audience text,
machine_credential_ref text,
session_encryption_key_ref text,
session_idle_seconds integer NOT NULL DEFAULT 1800 CHECK (session_idle_seconds > 0),

37
apps/api/migrations/0065_security_event_verification_state_repair.sql
View File

@ -1,37 +0,0 @@
-- 0062 was released before the verification challenge table and the complete
-- stream-state columns were added. Installations that already recorded 0062
-- need a new immutable migration to repair that drift.
ALTER TABLE gateway_security_event_stream_state
ADD COLUMN IF NOT EXISTS stream_status text NOT NULL DEFAULT 'unknown',
ADD COLUMN IF NOT EXISTS created_at timestamptz NOT NULL DEFAULT now();
DO $$
BEGIN
IF NOT EXISTS (
SELECT 1
FROM pg_constraint
WHERE conrelid = 'gateway_security_event_stream_state'::regclass
AND conname = 'gateway_security_event_stream_state_status'
) THEN
ALTER TABLE gateway_security_event_stream_state
ADD CONSTRAINT gateway_security_event_stream_state_status
CHECK (stream_status IN ('unknown','enabled','paused','disabled'));
END IF;
END
$$;
CREATE TABLE IF NOT EXISTS gateway_security_event_verification_challenges (
issuer text NOT NULL,
audience text NOT NULL,
state_hash bytea NOT NULL,
created_at timestamptz NOT NULL,
expires_at timestamptz NOT NULL,
PRIMARY KEY (issuer, audience, state_hash),
FOREIGN KEY (issuer, audience)
REFERENCES gateway_security_event_stream_state(issuer, audience) ON DELETE CASCADE,
CONSTRAINT gateway_security_event_verification_challenge_hash
CHECK (octet_length(state_hash) = 32)
);
CREATE INDEX IF NOT EXISTS idx_gateway_security_event_challenges_expiry
ON gateway_security_event_verification_challenges(expires_at);

55
apps/api/migrations/0066_identity_onboarding_exchanges.sql Normal file
View File

@ -0,0 +1,55 @@
CREATE TABLE IF NOT EXISTS gateway_identity_onboarding_exchanges (
id uuid PRIMARY KEY,
revision_id uuid NOT NULL UNIQUE REFERENCES gateway_identity_configuration_revisions(id) ON DELETE CASCADE,
remote_exchange_id uuid NOT NULL UNIQUE,
exchange_token_ref text NOT NULL CHECK (exchange_token_ref ~ '^[a-z0-9][a-z0-9-]{0,127}$'),
status text NOT NULL CHECK (status IN (
'metadata_pending','preparing','ready','credentials_saved','completed','failed','expired','cancelled'
)),
cleanup_status text NOT NULL DEFAULT 'none' CHECK (cleanup_status IN ('none','pending','completed')),
remote_version bigint NOT NULL CHECK (remote_version > 0),
expires_at timestamptz NOT NULL,
version bigint NOT NULL DEFAULT 1 CHECK (version > 0),
last_error_category text,
auth_center_audit_id text,
last_trace_id text,
cancelled_at timestamptz,
cleanup_completed_at timestamptz,
created_at timestamptz NOT NULL DEFAULT now(),
updated_at timestamptz NOT NULL DEFAULT now(),
CONSTRAINT gateway_identity_onboarding_cleanup_lifecycle_check CHECK (
(status <> 'cancelled' AND cleanup_status = 'none' AND cancelled_at IS NULL AND cleanup_completed_at IS NULL) OR
(status = 'cancelled' AND cancelled_at IS NOT NULL AND (
(cleanup_status = 'pending' AND cleanup_completed_at IS NULL) OR
(cleanup_status = 'completed' AND cleanup_completed_at IS NOT NULL)
))
),
CONSTRAINT gateway_identity_onboarding_error_category_check CHECK (
last_error_category IS NULL OR last_error_category IN (
'metadata_submission_failed','exchange_status_unavailable','credential_delivery_failed',
'exchange_completion_failed','exchange_expired','remote_exchange_failed','remote_state_invalid',
'security_event_configuration_invalid','security_event_connection_conflict',
'security_event_discovery_failed','security_event_management_token_failed',
'security_event_stream_create_failed','security_event_stream_response_invalid',
'security_event_receiver_activation_failed','security_event_preparation_failed',
'security_event_retirement_pending','security_event_credential_handoff_unsafe',
'security_event_connection_binding_missing','security_event_connection_binding_unavailable',
'security_event_connection_binding_invalid','security_event_connection_binding_mismatch',
'pairing_step_failed','cleanup_revision_unavailable','cleanup_security_event_unavailable',
'cleanup_security_event_configuration_invalid','cleanup_security_event_connection_conflict',
'cleanup_security_event_discovery_failed','cleanup_security_event_management_token_failed',
'cleanup_security_event_stream_create_failed','cleanup_security_event_stream_response_invalid',
'cleanup_security_event_receiver_activation_failed','cleanup_security_event_preparation_failed',
'cleanup_security_event_retirement_pending','cleanup_security_event_connection_cleanup_failed',
'cleanup_security_event_secret_cleanup_failed','cleanup_security_event_credential_handoff_unsafe',
'cleanup_security_event_failed','cleanup_secret_store_failed','cleanup_finalize_failed'
)
)
);
CREATE INDEX IF NOT EXISTS idx_gateway_identity_onboarding_status
ON gateway_identity_onboarding_exchanges(status, updated_at DESC);
CREATE INDEX IF NOT EXISTS idx_gateway_identity_onboarding_cleanup
ON gateway_identity_onboarding_exchanges(cleanup_status, updated_at)
WHERE cleanup_status = 'pending';

9
apps/api/migrations/0066_security_event_management_credential.sql
View File

@ -1,9 +0,0 @@
ALTER TABLE gateway_security_event_connections
ADD COLUMN IF NOT EXISTS management_client_id text,
ADD COLUMN IF NOT EXISTS management_credential_ref text;
ALTER TABLE gateway_security_event_connections
ADD CONSTRAINT gateway_security_event_management_credential_pair CHECK (
(management_client_id IS NULL AND management_credential_ref IS NULL) OR
(management_client_id IS NOT NULL AND management_credential_ref IS NOT NULL)
);

13
apps/api/migrations/0070_identity_secret_cleanup_queue.sql → apps/api/migrations/0067_identity_secret_cleanup_queue.sql
View File

@ -1,18 +1,15 @@
CREATE TABLE IF NOT EXISTS gateway_identity_secret_cleanup_queue (
secret_ref text PRIMARY KEY CHECK (secret_ref ~ '^[a-z0-9][a-z0-9-]{0,127}$'),
not_before timestamptz NOT NULL,
status text NOT NULL DEFAULT 'pending',
status text NOT NULL DEFAULT 'pending' CHECK (status IN ('pending','claimed')),
claim_token uuid,
lease_expires_at timestamptz,
created_at timestamptz NOT NULL DEFAULT now(),
updated_at timestamptz NOT NULL DEFAULT now(),
CONSTRAINT gateway_identity_secret_cleanup_status_check
CHECK (status IN ('pending','claimed')),
CONSTRAINT gateway_identity_secret_cleanup_claim_check
CHECK (
(status = 'pending' AND claim_token IS NULL AND lease_expires_at IS NULL) OR
(status = 'claimed' AND claim_token IS NOT NULL AND lease_expires_at IS NOT NULL)
)
CONSTRAINT gateway_identity_secret_cleanup_claim_check CHECK (
(status = 'pending' AND claim_token IS NULL AND lease_expires_at IS NULL) OR
(status = 'claimed' AND claim_token IS NOT NULL AND lease_expires_at IS NOT NULL)
)
);
CREATE INDEX IF NOT EXISTS idx_gateway_identity_secret_cleanup_due

23
apps/api/migrations/0068_identity_onboarding_exchanges.sql
View File

@ -1,23 +0,0 @@
ALTER TABLE gateway_identity_configuration_revisions
ADD COLUMN IF NOT EXISTS security_event_issuer text,
ADD COLUMN IF NOT EXISTS security_event_configuration_url text,
ADD COLUMN IF NOT EXISTS security_event_audience text;
CREATE TABLE IF NOT EXISTS gateway_identity_onboarding_exchanges (
id uuid PRIMARY KEY,
revision_id uuid NOT NULL UNIQUE REFERENCES gateway_identity_configuration_revisions(id) ON DELETE CASCADE,
remote_exchange_id uuid NOT NULL UNIQUE,
exchange_token_ref text NOT NULL CHECK (exchange_token_ref ~ '^[a-z0-9][a-z0-9-]{0,127}$'),
status text NOT NULL CHECK (status IN ('metadata_pending','preparing','ready','credentials_saved','completed','failed','expired')),
remote_version bigint NOT NULL CHECK (remote_version > 0),
expires_at timestamptz NOT NULL,
version bigint NOT NULL DEFAULT 1 CHECK (version > 0),
last_error_category text,
auth_center_audit_id text,
last_trace_id text,
created_at timestamptz NOT NULL DEFAULT now(),
updated_at timestamptz NOT NULL DEFAULT now()
);
CREATE INDEX IF NOT EXISTS idx_gateway_identity_onboarding_status
ON gateway_identity_onboarding_exchanges(status, updated_at DESC);

5
apps/api/migrations/0071_identity_pairing_start_reservation.sql → apps/api/migrations/0068_identity_pairing_start_reservation.sql
View File

@ -1,6 +1,3 @@
SET LOCAL lock_timeout = '10s';
SET LOCAL statement_timeout = '60s';
CREATE TABLE IF NOT EXISTS gateway_identity_pairing_start_reservation (
singleton boolean PRIMARY KEY DEFAULT true CHECK (singleton),
attempt_id uuid NOT NULL UNIQUE,
@ -16,7 +13,7 @@ CREATE TABLE IF NOT EXISTS gateway_identity_pairing_start_reservation (
);
CREATE INDEX IF NOT EXISTS idx_gateway_identity_pairing_start_expiry
ON gateway_identity_pairing_start_reservation(state,expires_at);
ON gateway_identity_pairing_start_reservation(state, expires_at);
INSERT INTO gateway_identity_pairing_start_reservation(singleton,attempt_id,state,revision_id,expires_at)
SELECT true,exchange.id,'paired',revision.id,exchange.expires_at

69
apps/api/migrations/0069_identity_pairing_cancellation.sql
View File

@ -1,69 +0,0 @@
SET LOCAL lock_timeout = '10s';
SET LOCAL statement_timeout = '60s';
ALTER TABLE gateway_identity_onboarding_exchanges
DROP CONSTRAINT gateway_identity_onboarding_exchanges_status_check;
ALTER TABLE gateway_identity_onboarding_exchanges
ADD CONSTRAINT gateway_identity_onboarding_exchanges_status_check
CHECK (status IN ('metadata_pending','preparing','ready','credentials_saved','completed','failed','expired','cancelled')),
ADD COLUMN cleanup_status text NOT NULL DEFAULT 'none',
ADD COLUMN cancelled_at timestamptz,
ADD COLUMN cleanup_completed_at timestamptz;
ALTER TABLE gateway_identity_onboarding_exchanges
ADD CONSTRAINT gateway_identity_onboarding_cleanup_status_check
CHECK (cleanup_status IN ('none','pending','completed')),
ADD CONSTRAINT gateway_identity_onboarding_cleanup_lifecycle_check
CHECK (
(status <> 'cancelled' AND cleanup_status = 'none' AND cancelled_at IS NULL AND cleanup_completed_at IS NULL) OR
(status = 'cancelled' AND cancelled_at IS NOT NULL AND (
(cleanup_status = 'pending' AND cleanup_completed_at IS NULL) OR
(cleanup_status = 'completed' AND cleanup_completed_at IS NOT NULL)
))
);
UPDATE gateway_identity_onboarding_exchanges
SET last_error_category = 'pairing_step_failed'
WHERE last_error_category IS NOT NULL
AND last_error_category NOT IN (
'metadata_submission_failed','exchange_status_unavailable','credential_delivery_failed',
'exchange_completion_failed','exchange_expired','remote_exchange_failed','remote_state_invalid',
'security_event_configuration_invalid','security_event_connection_conflict',
'security_event_discovery_failed','security_event_management_token_failed',
'security_event_stream_create_failed','security_event_stream_response_invalid',
'security_event_receiver_activation_failed','security_event_preparation_failed',
'security_event_retirement_pending','pairing_step_failed',
'cleanup_revision_unavailable','cleanup_security_event_unavailable',
'cleanup_security_event_configuration_invalid','cleanup_security_event_connection_conflict',
'cleanup_security_event_discovery_failed','cleanup_security_event_management_token_failed',
'cleanup_security_event_stream_create_failed','cleanup_security_event_stream_response_invalid',
'cleanup_security_event_receiver_activation_failed','cleanup_security_event_preparation_failed',
'cleanup_security_event_retirement_pending','cleanup_security_event_connection_cleanup_failed',
'cleanup_security_event_secret_cleanup_failed','cleanup_security_event_failed',
'cleanup_secret_store_failed','cleanup_finalize_failed'
);
ALTER TABLE gateway_identity_onboarding_exchanges
ADD CONSTRAINT gateway_identity_onboarding_error_category_check
CHECK (last_error_category IS NULL OR last_error_category IN (
'metadata_submission_failed','exchange_status_unavailable','credential_delivery_failed',
'exchange_completion_failed','exchange_expired','remote_exchange_failed','remote_state_invalid',
'security_event_configuration_invalid','security_event_connection_conflict',
'security_event_discovery_failed','security_event_management_token_failed',
'security_event_stream_create_failed','security_event_stream_response_invalid',
'security_event_receiver_activation_failed','security_event_preparation_failed',
'security_event_retirement_pending','pairing_step_failed',
'cleanup_revision_unavailable','cleanup_security_event_unavailable',
'cleanup_security_event_configuration_invalid','cleanup_security_event_connection_conflict',
'cleanup_security_event_discovery_failed','cleanup_security_event_management_token_failed',
'cleanup_security_event_stream_create_failed','cleanup_security_event_stream_response_invalid',
'cleanup_security_event_receiver_activation_failed','cleanup_security_event_preparation_failed',
'cleanup_security_event_retirement_pending','cleanup_security_event_connection_cleanup_failed',
'cleanup_security_event_secret_cleanup_failed','cleanup_security_event_failed',
'cleanup_secret_store_failed','cleanup_finalize_failed'
));
CREATE INDEX IF NOT EXISTS idx_gateway_identity_onboarding_cleanup
ON gateway_identity_onboarding_exchanges(cleanup_status, updated_at)
WHERE cleanup_status = 'pending';

34
apps/api/migrations/0072_identity_secret_cleanup_claim_lifecycle.sql
View File

@ -1,34 +0,0 @@
SET LOCAL lock_timeout = '10s';
SET LOCAL statement_timeout = '60s';
ALTER TABLE gateway_identity_secret_cleanup_queue
ADD COLUMN IF NOT EXISTS status text,
ADD COLUMN IF NOT EXISTS claim_token uuid,
ADD COLUMN IF NOT EXISTS lease_expires_at timestamptz;
ALTER TABLE gateway_identity_secret_cleanup_queue
DROP CONSTRAINT IF EXISTS gateway_identity_secret_cleanup_status_check,
DROP CONSTRAINT IF EXISTS gateway_identity_secret_cleanup_claim_check;
UPDATE gateway_identity_secret_cleanup_queue
SET status='pending',claim_token=NULL,lease_expires_at=NULL,updated_at=now()
WHERE status IS NULL
OR status NOT IN ('pending','claimed')
OR (status='pending' AND (claim_token IS NOT NULL OR lease_expires_at IS NOT NULL))
OR (status='claimed' AND (claim_token IS NULL OR lease_expires_at IS NULL));
ALTER TABLE gateway_identity_secret_cleanup_queue
ALTER COLUMN status SET DEFAULT 'pending',
ALTER COLUMN status SET NOT NULL,
ADD CONSTRAINT gateway_identity_secret_cleanup_status_check
CHECK (status IN ('pending','claimed')),
ADD CONSTRAINT gateway_identity_secret_cleanup_claim_check
CHECK (
(status='pending' AND claim_token IS NULL AND lease_expires_at IS NULL) OR
(status='claimed' AND claim_token IS NOT NULL AND lease_expires_at IS NOT NULL)
);
DROP INDEX IF EXISTS idx_gateway_identity_secret_cleanup_due;
CREATE INDEX idx_gateway_identity_secret_cleanup_due
ON gateway_identity_secret_cleanup_queue(status,not_before,lease_expires_at,updated_at);

89
apps/api/migrations/0073_identity_pairing_start_reservation_upgrade.sql
View File

@ -1,89 +0,0 @@
SET LOCAL lock_timeout = '10s';
SET LOCAL statement_timeout = '60s';
-- 0071 was briefly released with only the singleton reservation lease fields.
-- Add the durable lifecycle columns without rewriting that already-applied
-- migration, then reconcile the singleton with the canonical outstanding
-- pairing (when one exists).
ALTER TABLE gateway_identity_pairing_start_reservation
ADD COLUMN IF NOT EXISTS state text,
ADD COLUMN IF NOT EXISTS revision_id uuid,
ADD COLUMN IF NOT EXISTS updated_at timestamptz;
UPDATE gateway_identity_pairing_start_reservation
SET state=CASE WHEN revision_id IS NULL THEN 'starting' ELSE 'paired' END,
updated_at=COALESCE(updated_at,created_at,now())
WHERE state IS NULL
OR state NOT IN ('starting','paired')
OR (state='starting' AND revision_id IS NOT NULL)
OR (state='paired' AND revision_id IS NULL)
OR updated_at IS NULL;
WITH canonical_pairing AS (
SELECT exchange.id AS attempt_id,
revision.id AS revision_id,
exchange.expires_at
FROM gateway_identity_configuration_revisions revision
JOIN gateway_identity_onboarding_exchanges exchange
ON exchange.revision_id=revision.id
WHERE revision.state IN ('draft','validated','failed')
AND NOT (exchange.status='cancelled' AND exchange.cleanup_status='completed')
ORDER BY revision.created_at DESC,exchange.created_at DESC
LIMIT 1
)
INSERT INTO gateway_identity_pairing_start_reservation(
singleton,attempt_id,state,revision_id,expires_at,updated_at
)
SELECT true,attempt_id,'paired',revision_id,expires_at,now()
FROM canonical_pairing
ON CONFLICT (singleton) DO UPDATE
SET attempt_id=EXCLUDED.attempt_id,
state=EXCLUDED.state,
revision_id=EXCLUDED.revision_id,
expires_at=EXCLUDED.expires_at,
updated_at=now();
ALTER TABLE gateway_identity_pairing_start_reservation
ALTER COLUMN state SET DEFAULT 'starting',
ALTER COLUMN state SET NOT NULL,
ALTER COLUMN updated_at SET DEFAULT now(),
ALTER COLUMN updated_at SET NOT NULL;
ALTER TABLE gateway_identity_pairing_start_reservation
DROP CONSTRAINT IF EXISTS gateway_identity_pairing_start_state_value_check,
DROP CONSTRAINT IF EXISTS gateway_identity_pairing_start_state_check;
ALTER TABLE gateway_identity_pairing_start_reservation
ADD CONSTRAINT gateway_identity_pairing_start_state_value_check
CHECK (state IN ('starting','paired')),
ADD CONSTRAINT gateway_identity_pairing_start_state_check CHECK (
(state='starting' AND revision_id IS NULL) OR
(state='paired' AND revision_id IS NOT NULL)
);
DO $migration$
BEGIN
IF NOT EXISTS (
SELECT 1
FROM pg_constraint
WHERE conrelid='gateway_identity_pairing_start_reservation'::regclass
AND contype='f'
AND pg_get_constraintdef(oid) LIKE 'FOREIGN KEY (revision_id)%'
) THEN
ALTER TABLE gateway_identity_pairing_start_reservation
ADD CONSTRAINT gateway_identity_pairing_start_revision_fk
FOREIGN KEY (revision_id)
REFERENCES gateway_identity_configuration_revisions(id)
ON DELETE RESTRICT;
END IF;
END
$migration$;
CREATE UNIQUE INDEX IF NOT EXISTS idx_gateway_identity_pairing_start_revision_unique
ON gateway_identity_pairing_start_reservation(revision_id)
WHERE revision_id IS NOT NULL;
DROP INDEX IF EXISTS idx_gateway_identity_pairing_start_expiry;
CREATE INDEX idx_gateway_identity_pairing_start_expiry
ON gateway_identity_pairing_start_reservation(state,expires_at);

32
apps/api/migrations/0074_identity_pairing_error_categories.sql
View File

@ -1,32 +0,0 @@
SET LOCAL lock_timeout = '10s';
SET LOCAL statement_timeout = '60s';
-- Pairing recovery added explicit, redacted error categories after 0069 was
-- released. Keep the database allow-list in lockstep so PostgreSQL can persist
-- the reason an administrator must resolve instead of hiding it behind a CHECK
-- violation.
ALTER TABLE gateway_identity_onboarding_exchanges
DROP CONSTRAINT IF EXISTS gateway_identity_onboarding_error_category_check;
ALTER TABLE gateway_identity_onboarding_exchanges
ADD CONSTRAINT gateway_identity_onboarding_error_category_check
CHECK (last_error_category IS NULL OR last_error_category IN (
'metadata_submission_failed','exchange_status_unavailable','credential_delivery_failed',
'exchange_completion_failed','exchange_expired','remote_exchange_failed','remote_state_invalid',
'security_event_configuration_invalid','security_event_connection_conflict',
'security_event_discovery_failed','security_event_management_token_failed',
'security_event_stream_create_failed','security_event_stream_response_invalid',
'security_event_receiver_activation_failed','security_event_preparation_failed',
'security_event_retirement_pending','security_event_credential_handoff_unsafe',
'security_event_connection_binding_missing','security_event_connection_binding_unavailable',
'security_event_connection_binding_invalid','security_event_connection_binding_mismatch',
'pairing_step_failed',
'cleanup_revision_unavailable','cleanup_security_event_unavailable',
'cleanup_security_event_configuration_invalid','cleanup_security_event_connection_conflict',
'cleanup_security_event_discovery_failed','cleanup_security_event_management_token_failed',
'cleanup_security_event_stream_create_failed','cleanup_security_event_stream_response_invalid',
'cleanup_security_event_receiver_activation_failed','cleanup_security_event_preparation_failed',
'cleanup_security_event_retirement_pending','cleanup_security_event_connection_cleanup_failed',
'cleanup_security_event_secret_cleanup_failed','cleanup_security_event_credential_handoff_unsafe',
'cleanup_security_event_failed','cleanup_secret_store_failed','cleanup_finalize_failed'
));

2
apps/web/package.json
View File

@ -44,6 +44,6 @@
"@types/react-dom": "^19.0.0",
"tailwindcss": "^4.3.0",
"typescript": "^5.8.0",
"vitest": "3.2.4"
"vitest": "3.2.6"
}
}

77
apps/web/src/api.test.ts
View File

@ -1,15 +1,18 @@
import { afterEach, describe, expect, it, vi } from 'vitest';
import {
cancelIdentityPairing,
cancelIdentityPairing,
connectSecurityEventTransmitter,
createResponse,
deleteOIDCBrowserSession,
GatewayApiError,
gatewayErrorMessage,
getAPITask,
getCurrentUser,
getOpsManagementSkillMetadata,
OIDC_BROWSER_SESSION_CREDENTIAL,
startIdentityPairing,
retireIdentityPairingSecurityEventConflict,
validateIdentityRevision,
startIdentityPairing,
retireIdentityPairingSecurityEventConflict,
validateIdentityRevision,
} from './api';
describe('Gateway provisioning errors', () => {
@ -200,3 +203,69 @@ describe('OIDC browser session transport', () => {
expect(new Headers(init.headers).has('Authorization')).toBe(false);
});
});
describe('Public Agent resources', () => {
afterEach(() => {
vi.unstubAllGlobals();
});
it('loads operations skill metadata without authorization', async () => {
const metadata = {
name: 'ai-gateway-ops-management',
version: '1.0.2',
displayName: 'AI Gateway 运维管理',
modules: ['model-runtime'],
fileName: 'ai-gateway-ops-management-v1.0.2.zip',
downloadPath: '/api/v1/public/skills/ai-gateway-ops-management/download',
apiDocsJsonPath: '/api-docs-json',
apiDocsYamlPath: '/api-docs-yaml',
};
const fetchMock = vi.fn().mockResolvedValue(new Response(JSON.stringify(metadata), {
status: 200,
headers: { 'Content-Type': 'application/json' },
}));
vi.stubGlobal('fetch', fetchMock);
await expect(getOpsManagementSkillMetadata()).resolves.toEqual(metadata);
const [url, init] = fetchMock.mock.calls[0] as [string, RequestInit];
expect(url).toContain('/api/v1/public/skills/ai-gateway-ops-management/metadata');
expect(new Headers(init.headers).has('Authorization')).toBe(false);
});
});
describe('API documentation runner transports', () => {
afterEach(() => {
vi.unstubAllGlobals();
});
it('runs Responses against the public OpenAI-compatible endpoint', async () => {
const fetchMock = vi.fn().mockResolvedValue(new Response(JSON.stringify({ id: 'resp-test', object: 'response' }), {
status: 200,
headers: { 'Content-Type': 'application/json' },
}));
vi.stubGlobal('fetch', fetchMock);
await createResponse('sk-test', { model: 'gpt-test', input: 'hello', store: true, stream: false });
const [url, init] = fetchMock.mock.calls[0] as [string, RequestInit];
expect(url).toContain('/v1/responses');
expect(init.method).toBe('POST');
expect(new Headers(init.headers).get('Authorization')).toBe('Bearer sk-test');
expect(JSON.parse(String(init.body))).toMatchObject({ model: 'gpt-test', input: 'hello', store: true, stream: false });
});
it('retrieves a task from the documented API path', async () => {
const fetchMock = vi.fn().mockResolvedValue(new Response(JSON.stringify({ id: 'task-123', status: 'running' }), {
status: 200,
headers: { 'Content-Type': 'application/json' },
}));
vi.stubGlobal('fetch', fetchMock);
await getAPITask('sk-test', 'task-123');
const [url, init] = fetchMock.mock.calls[0] as [string, RequestInit];
expect(url).toContain('/api/v1/tasks/task-123');
expect(init.method).toBe('GET');
});
});

31
apps/web/src/api.ts
View File

@ -29,6 +29,7 @@ import type {
GatewayTenantUpsertRequest,
GatewayNetworkProxyConfig,
GatewayPricingEstimate,
GatewaySkillBundleMetadata,
GatewayTask,
GatewayTaskParamPreprocessingLog,
GatewayUser,
@ -95,6 +96,10 @@ export async function getHealth(): Promise<HealthResponse> {
return request<HealthResponse>('/healthz', { auth: false });
}
export async function getOpsManagementSkillMetadata(): Promise<GatewaySkillBundleMetadata> {
return request<GatewaySkillBundleMetadata>('/api/v1/public/skills/ai-gateway-ops-management/metadata', { auth: false });
}
export async function registerLocalAccount(input: {
username: string;
email?: string;
@ -605,6 +610,26 @@ export async function createCompatibleChatCompletion(
});
}
export async function createResponse(
token: string,
input: {
model: string;
input: unknown;
instructions?: string;
previous_response_id?: string;
runMode?: string;
simulation?: boolean;
store?: boolean;
stream?: boolean;
},
): Promise<Record<string, unknown>> {
return request<Record<string, unknown>>('/v1/responses', {
body: input,
method: 'POST',
token,
});
}
export async function createEmbedding(
token: string,
input: { model: string; input: string | string[]; dimensions?: number; runMode?: string; simulation?: boolean },
@ -818,6 +843,8 @@ export interface VideoGenerationParams {
mode?: 'std' | 'pro';
negative_prompt?: string;
cfg_scale?: number;
runMode?: string;
simulation?: boolean;
}
export async function createVideoGenerationTask(
@ -881,6 +908,10 @@ export async function getTask(token: string, taskId: string): Promise<GatewayTas
return request<GatewayTask>(`/api/workspace/tasks/${taskId}`, { token });
}
export async function getAPITask(token: string, taskId: string): Promise<GatewayTask> {
return request<GatewayTask>(`/api/v1/tasks/${taskId}`, { token });
}
export async function listTaskParamPreprocessing(
token: string,
taskId: string,

69
apps/web/src/lib/run-task.ts
View File

@ -1,5 +1,14 @@
import type { GatewayTask } from '@easyai-ai-gateway/contracts';
import { createCompatibleChatCompletion, createEmbedding, createImageEditTask, createImageGenerationTask, createRerank } from '../api';
import {
createCompatibleChatCompletion,
createEmbedding,
createImageEditTask,
createImageGenerationTask,
createRerank,
createResponse,
createVideoGenerationTask,
getAPITask,
} from '../api';
import type { TaskForm } from '../types';
export interface RunTaskResponse {
@ -19,6 +28,19 @@ export async function runTask(token: string, task: TaskForm): Promise<RunTaskRes
});
return { localOnly: true, task: compatibleTask(task, result) };
}
if (task.kind === 'responses') {
const result = await createResponse(token, {
model: task.model,
input: task.prompt,
instructions: task.instructions,
previous_response_id: task.previousResponseId,
runMode: 'simulation',
simulation: true,
store: true,
stream: false,
});
return { localOnly: true, task: compatibleTask(task, result) };
}
if (task.kind === 'embeddings') {
const result = await createEmbedding(token, {
model: task.model,
@ -60,6 +82,24 @@ export async function runTask(token: string, task: TaskForm): Promise<RunTaskRes
simulation: true,
});
}
if (task.kind === 'videos.generations') {
return createVideoGenerationTask(token, {
model: task.model,
content: [{ type: 'text', text: task.prompt }],
aspect_ratio: task.aspectRatio ?? '16:9',
resolution: task.resolution ?? '720p',
duration: task.duration ?? 5,
audio: task.outputAudio ?? true,
runMode: 'simulation',
simulation: true,
});
}
if (task.kind === 'tasks.retrieve') {
const taskId = task.taskId?.trim();
if (!taskId) throw new Error('请输入要取回的 Task ID');
const result = await getAPITask(token, taskId);
return { localOnly: true, task: compatibleTask(task, result as unknown as Record<string, unknown>) };
}
throw new Error(`Unsupported task kind: ${task.kind}`);
}
@ -83,6 +123,18 @@ function compatibleTask(task: TaskForm, result: Record<string, unknown>): Gatewa
}
function requestSnapshot(task: TaskForm): Record<string, unknown> {
if (task.kind === 'responses') {
return {
model: task.model,
input: task.prompt,
instructions: task.instructions,
previous_response_id: task.previousResponseId,
runMode: 'simulation',
simulation: true,
store: true,
stream: false,
};
}
if (task.kind === 'embeddings') {
return {
model: task.model,
@ -102,6 +154,19 @@ function requestSnapshot(task: TaskForm): Record<string, unknown> {
simulation: true,
};
}
if (task.kind === 'videos.generations') {
return {
model: task.model,
content: [{ type: 'text', text: task.prompt }],
aspect_ratio: task.aspectRatio ?? '16:9',
resolution: task.resolution ?? '720p',
duration: task.duration ?? 5,
audio: task.outputAudio ?? true,
runMode: 'simulation',
simulation: true,
};
}
if (task.kind === 'tasks.retrieve') return { taskId: task.taskId };
return {
model: task.model,
messages: [{ role: 'user', content: task.prompt }],
@ -133,5 +198,7 @@ function modelTypeForKind(kind: TaskForm['kind']) {
if (kind === 'reranks') return 'text_rerank';
if (kind === 'images.generations') return 'image_generate';
if (kind === 'images.edits') return 'image_edit';
if (kind === 'videos.generations') return 'video_generate';
if (kind === 'tasks.retrieve') return 'task';
return 'text_generate';
}

107
apps/web/src/pages/ApiDocsPage.test.tsx Normal file
View File

@ -0,0 +1,107 @@
import { renderToStaticMarkup } from 'react-dom/server';
import { describe, expect, it, vi } from 'vitest';
import type { ApiDocSection, TaskForm } from '../types';
import { ApiDocsPage } from './ApiDocsPage';
describe('ApiDocsPage extended task documentation', () => {
it.each([
['guideBaseUrl', '前往创建 API Key'],
['guideWebhook', 'TASK_PROGRESS_CALLBACK_ENABLED'],
['guideErrors', '400 invalid_parameter'],
['guideTesting', 'simulated=true'],
] as const)('renders the clickable guide page %s', (section, expectedContent) => {
const html = renderDocs(section, { kind: 'chat.completions', model: 'gpt-4o-mini', prompt: '你好' });
expect(html).toContain('data-active="true"');
expect(html).toContain(expectedContent);
expect(html).toContain('指南导航');
expect(html).not.toContain('/v1/chat/completions');
});
it('documents the OpenAI-compatible Responses request and continuity fields', () => {
const html = renderDocs('responses', { kind: 'responses', model: 'gpt-4o-mini', prompt: '你好' });
expect(html).toContain('/v1/responses');
expect(html).toContain('previous_response_id');
expect(html).toContain('X-Async');
expect(html).toContain('连续对话与状态归属');
});
it('documents video generation parameters and async retrieval guidance', () => {
const html = renderDocs('videoGeneration', { kind: 'videos.generations', model: '豆包Seedance-2.0', prompt: '雪山日出' });
expect(html).toContain('/api/v1/videos/generations');
expect(html).toContain('aspect_ratio');
expect(html).toContain('reference_image');
expect(html).toContain('任务取回接口');
});
it('documents async mode as a body-independent capability', () => {
const html = renderDocs('asyncMode', { kind: 'chat.completions', model: 'gpt-4o-mini', prompt: '你好' });
expect(html).toContain('X-Async');
expect(html).toContain('原请求 Header');
expect(html).toContain('同步与异步的区别');
expect(html).toContain('异步受理响应');
expect(html).not.toContain('/api/v1/videos/generations');
expect(html).not.toContain('Body 参数');
expect(html).not.toContain('视频模型 ID');
});
it.each(['chat', 'responses', 'embeddings', 'reranks', 'imageGeneration', 'imageEdit', 'videoGeneration'] as const)(
'shows the shared X-Async switch on the %s task API',
(section) => {
const html = renderDocs(section, { kind: 'chat.completions', model: 'gpt-4o-mini', prompt: '你好' });
expect(html).toContain('X-Async');
},
);
it('renders nested objects and object arrays recursively', () => {
const html = renderDocs('videoGeneration', { kind: 'videos.generations', model: '豆包Seedance-2.0', prompt: '雪山日出' });
expect(html).toContain('array&lt;object&gt;');
expect(html).toContain('data-depth="1"');
expect(html).toContain('data-depth="4"');
expect(html).toContain('inline_element');
expect(html).toContain('refer_images');
expect(html).toContain('slot_key');
});
it('renders task retrieval as GET with a path parameter instead of a request body', () => {
const html = renderDocs('taskRetrieve', { kind: 'tasks.retrieve', model: 'task', prompt: '', taskId: 'task-123' });
expect(html).toContain('GET');
expect(html).toContain('/api/v1/tasks/task-123');
expect(html).toContain('Path 参数');
expect(html).toContain('响应 Body');
expect(html).toContain('result');
expect(html).toContain('billingSummary');
expect(html).toContain('attempts');
expect(html).toContain('成功响应示例');
expect(html).toContain('Task ID');
expect(html).not.toContain('请求 Body');
});
});
function renderDocs(activeDocSection: ApiDocSection, taskForm: TaskForm) {
return renderToStaticMarkup(
<ApiDocsPage
activeDocSection={activeDocSection}
apiKeySecretsById={{}}
apiKeys={[]}
canRun
coreMessage=""
coreState="idle"
selectedApiKeyId=""
taskForm={taskForm}
taskResult={null}
onApiKeyChange={vi.fn()}
onCreateApiKey={vi.fn()}
onDocSectionChange={vi.fn()}
onLogin={vi.fn()}
onSubmitTask={vi.fn()}
onTaskFormChange={vi.fn()}
/>,
);
}

929
apps/web/src/pages/ApiDocsPage.tsx
View File

File diff suppressed because it is too large Load Diff

27
apps/web/src/routing.test.ts Normal file
View File

@ -0,0 +1,27 @@
import { describe, expect, it } from 'vitest';
import { parseAppRoute, pathForApiDocSection } from './routing';
describe('API documentation routes', () => {
it.each([
['guideBaseUrl', '/docs/auth'],
['guideWebhook', '/docs/webhook'],
['guideErrors', '/docs/errors'],
['guideTesting', '/docs/testing'],
['responses', '/docs/responses'],
['videoGeneration', '/docs/videos/generations'],
['asyncMode', '/docs/async'],
['taskRetrieve', '/docs/tasks/retrieve'],
] as const)('maps %s to a stable documentation URL', (section, path) => {
expect(pathForApiDocSection(section)).toBe(path);
expect(parseAppRoute(path).apiDocSection).toBe(section);
});
it.each([
['/docs/playground', 'guideTesting'],
['/docs/api/responses', 'responses'],
['/docs/api/videos', 'videoGeneration'],
['/docs/api/tasks', 'taskRetrieve'],
] as const)('keeps the legacy documentation URL %s working', (path, section) => {
expect(parseAppRoute(path).apiDocSection).toBe(section);
});
});

23
apps/web/src/routing.ts
View File

@ -43,11 +43,19 @@ const adminPaths: Record<AdminSection, string> = {
};
const docsPaths: Record<ApiDocSection, string> = {
guideBaseUrl: '/docs/auth',
guideWebhook: '/docs/webhook',
guideErrors: '/docs/errors',
guideTesting: '/docs/testing',
chat: '/docs/chat',
responses: '/docs/responses',
embeddings: '/docs/embeddings',
reranks: '/docs/reranks',
imageGeneration: '/docs/images/generations',
imageEdit: '/docs/images/edits',
videoGeneration: '/docs/videos/generations',
asyncMode: '/docs/async',
taskRetrieve: '/docs/tasks/retrieve',
pricing: '/docs/pricing',
files: '/docs/files',
};
@ -63,8 +71,9 @@ const adminSections = reverseMap(adminPaths);
const docsSections = reverseMap(docsPaths);
const playgroundSections = reverseMap(playgroundPaths);
export function parseAppRoute(input = `${window.location.pathname}${window.location.search}`): AppRouteState {
const url = new URL(input, window.location.origin);
export function parseAppRoute(input = currentLocationPath()): AppRouteState {
const origin = typeof window === 'undefined' ? 'http://localhost' : window.location.origin;
const url = new URL(input, origin);
const path = normalizePath(url.pathname);
const workspaceTaskQuery = parseWorkspaceTaskQuery(url.searchParams);
if (path === '/') return { ...defaultRouteState };
@ -84,6 +93,11 @@ export function parseAppRoute(input = `${window.location.pathname}${window.locat
return { ...defaultRouteState };
}
function currentLocationPath() {
if (typeof window === 'undefined') return '/';
return `${window.location.pathname}${window.location.search}`;
}
export function pathForPage(page: PageKey, route: AppRouteState): string {
if (page === 'playground') return pathForPlaygroundMode(route.playgroundMode);
if (page === 'models') return '/models';
@ -135,11 +149,14 @@ function parseAdminSection(path: string): AdminSection {
function parseDocSection(path: string): ApiDocSection {
if (path === '/docs') return 'chat';
if (path === '/docs/playground') return 'guideTesting';
if (path === '/docs/api/chat') return 'chat';
if (path === '/docs/api/responses') return 'responses';
if (path === '/docs/api/embeddings') return 'embeddings';
if (path === '/docs/api/reranks') return 'reranks';
if (path === '/docs/api/media') return 'imageGeneration';
if (path === '/docs/playground') return 'chat';
if (path === '/docs/api/videos') return 'videoGeneration';
if (path === '/docs/api/tasks') return 'taskRetrieve';
return docsSections[path] ?? 'chat';
}

204
apps/web/src/styles/api-docs.css
View File

@ -120,6 +120,83 @@
line-height: 1.7;
}
.agentResourceCard {
display: grid;
grid-template-columns: auto minmax(0, 1fr);
gap: 16px;
margin: 0 0 24px;
padding: 18px;
border: 1px solid #bfdbfe;
border-radius: 12px;
background: linear-gradient(135deg, #eff6ff 0%, #ffffff 70%);
}
.agentResourceIcon {
display: grid;
width: 44px;
height: 44px;
place-items: center;
border-radius: 10px;
background: #dbeafe;
color: #1d4ed8;
}
.agentResourceContent {
display: grid;
gap: 12px;
min-width: 0;
}
.agentResourceContent p {
margin: 0;
color: var(--text-soft);
line-height: 1.6;
}
.agentResourceTitle,
.agentResourceActions,
.agentResourceModules {
display: flex;
align-items: center;
gap: 10px;
}
.agentResourceTitle {
justify-content: space-between;
}
.agentResourceTitle h2 {
margin: 2px 0 0;
font-size: 1.0625rem;
}
.agentResourceTitle .eyebrow {
color: #2563eb;
}
.agentResourceModules {
color: var(--text-soft);
font-size: 0.8125rem;
}
.agentResourceModules strong {
color: var(--text-strong);
}
.agentResourceActions {
flex-wrap: wrap;
}
.agentResourceMetadataLink {
color: #2563eb;
font-size: 0.8125rem;
text-decoration: none;
}
.agentResourceMetadataLink:hover {
text-decoration: underline;
}
.paramCard {
margin-top: 18px;
overflow: hidden;
@ -141,6 +218,7 @@
.paramRow {
display: grid;
grid-template-columns: 150px 110px minmax(0, 1fr) 50px;
align-items: start;
gap: 12px;
padding: 13px 16px;
border-bottom: 1px solid #f0f2f5;
@ -148,11 +226,91 @@
font-size: 0.8125rem;
}
.paramRow[data-nested='true'] {
background: #fbfcfe;
}
.paramName {
position: relative;
min-width: 0;
}
.paramName code {
overflow-wrap: anywhere;
}
.paramTreeMarker {
position: absolute;
top: -13px;
width: 12px;
height: 23px;
border-bottom: 1px solid #cfd7e3;
border-left: 1px solid #cfd7e3;
border-radius: 0 0 0 4px;
}
.paramRow em {
color: #a16207;
font-style: normal;
}
.docsDetailContent {
display: grid;
gap: 12px;
padding: 16px;
color: var(--text-soft);
font-size: 0.875rem;
line-height: 1.7;
}
.docsDetailContent p {
margin: 0;
}
.docsDetailContent pre {
overflow: auto;
margin: 0;
padding: 14px;
border-radius: 8px;
background: #f7f8fa;
color: var(--text-normal);
font-size: 0.75rem;
line-height: 1.6;
}
.docsSteps {
display: grid;
gap: 8px;
margin: 0;
padding-left: 20px;
}
.docsGuideActions {
display: flex;
align-items: center;
flex-wrap: wrap;
gap: 10px;
}
.docsStatusGrid {
display: grid;
grid-template-columns: minmax(190px, auto) minmax(0, 1fr);
gap: 0;
}
.docsStatusGrid > * {
margin: 0;
padding: 13px 16px;
border-bottom: 1px solid #f0f2f5;
color: var(--text-soft);
font-size: 0.8125rem;
line-height: 1.6;
}
.docsStatusGrid > code {
color: var(--text-normal);
}
.docsRunner {
border-left: 1px solid var(--border);
background: #fff;
@ -164,6 +322,40 @@
padding: 0 16px 16px;
}
.docsRunnerUnavailable {
padding: 14px;
border: 1px dashed var(--border);
border-radius: 8px;
background: var(--surface-muted);
color: var(--text-soft);
font-size: 0.8125rem;
line-height: 1.6;
}
.docsGuideAside header {
display: flex;
align-items: center;
min-height: 58px;
}
.docsGuideAside > div {
display: grid;
gap: 10px;
padding: 18px 16px;
color: var(--text-soft);
font-size: 0.8125rem;
line-height: 1.6;
}
.docsGuideAside span,
.docsGuideAside p {
margin: 0;
}
.docsGuideAside strong {
color: var(--text-normal);
}
.runnerResult {
display: grid;
gap: 12px;
@ -201,4 +393,16 @@
.paramRow {
grid-template-columns: 1fr;
}
.docsStatusGrid {
grid-template-columns: 1fr;
}
.agentResourceCard {
grid-template-columns: 1fr;
}
.agentResourceTitle {
align-items: flex-start;
}
}

34
apps/web/src/types.ts
View File

@ -1,10 +1,33 @@
export type LoadState = 'idle' | 'loading' | 'ready' | 'error';
export type AuthMode = 'login' | 'register' | 'external';
export type TaskKind = 'chat.completions' | 'embeddings' | 'reranks' | 'images.generations' | 'images.edits';
export type TaskKind =
| 'chat.completions'
| 'responses'
| 'embeddings'
| 'reranks'
| 'images.generations'
| 'images.edits'
| 'videos.generations'
| 'tasks.retrieve';
export type PageKey = 'home' | 'playground' | 'models' | 'workspace' | 'admin' | 'docs';
export type PlaygroundMode = 'chat' | 'image' | 'video';
export type WorkspaceSection = 'overview' | 'billing' | 'apiKeys' | 'tasks' | 'transactions';
export type ApiDocSection = 'chat' | 'embeddings' | 'reranks' | 'imageGeneration' | 'imageEdit' | 'pricing' | 'files';
export type ApiDocSection =
| 'guideBaseUrl'
| 'guideWebhook'
| 'guideErrors'
| 'guideTesting'
| 'chat'
| 'responses'
| 'embeddings'
| 'reranks'
| 'imageGeneration'
| 'imageEdit'
| 'videoGeneration'
| 'asyncMode'
| 'taskRetrieve'
| 'pricing'
| 'files';
export type AdminSection =
| 'overview'
| 'globalModels'
@ -37,10 +60,17 @@ export interface TaskForm {
kind: TaskKind;
model: string;
prompt: string;
aspectRatio?: string;
dimensions?: number;
documents?: string;
duration?: number;
image?: string;
instructions?: string;
mask?: string;
outputAudio?: boolean;
previousResponseId?: string;
resolution?: string;
taskId?: string;
topN?: number;
}

36
deploy/ci/act-runner-v2-config.yaml Normal file
View File

@ -0,0 +1,36 @@
log:
level: info
runner:
file: /data/.runner
capacity: 1
envs:
GOPROXY: "https://goproxy.cn,direct"
GOSUMDB: "sum.golang.google.cn"
PATH: "/opt/easyai-gateway-ci/bin:/opt/easyai-gateway-ci/toolchains/go/bin:/opt/easyai-gateway-ci/toolchains/node/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
timeout: 3h
shutdown_timeout: 5m
insecure: false
fetch_timeout: 5s
fetch_interval: 2s
labels:
- "easyai-gateway-ci-unprivileged-v2:docker://docker.io/library/node:24.16.0-bookworm@sha256:40ad9f3064e67d6860b4bc3fe1880b2953934fd6320ada990e45fe0efa6badd7"
cache:
enabled: false
container:
docker_host: "-"
privileged: false
force_pull: false
force_rebuild: false
require_docker: true
docker_timeout: 1m
bind_workdir: false
workdir_parent: workspace
options: "--volume /opt/easyai-gateway-ci:/opt/easyai-gateway-ci:ro"
valid_volumes:
- "/opt/easyai-gateway-ci"
host:
workdir_parent: /data/host-work

44
deploy/ci/easyai-gateway-ci-v2-runner.service Normal file
View File

@ -0,0 +1,44 @@
[Unit]
Description=EasyAI AI Gateway rootless DinD Gitea Actions runner v2
Requires=docker.service
After=network-online.target docker.service
Wants=network-online.target
[Service]
Type=simple
User=root
Group=root
Environment=RUNNER_SECURITY_OPTIONS=
Environment=RUNNER_IMAGE_REF=
EnvironmentFile=-/etc/easyai-gateway-ci-v2/runner.env
ExecStartPre=-/usr/bin/docker rm --force easyai-gateway-ci-v2-runner
ExecStart=/usr/bin/docker run --rm --pull=never --name easyai-gateway-ci-v2-runner --privileged --cpus 2 --memory 2g --memory-swap 3g --pids-limit 1024 $RUNNER_SECURITY_OPTIONS --volume easyai-gateway-ci-v2-data:/data --volume /etc/easyai-gateway-ci-v2/config.yaml:/config.yaml:ro --volume /etc/easyai-gateway-ci-v2/daemon.json:/home/rootless/.config/docker/daemon.json:ro --volume /opt/easyai-gateway-ci:/opt/easyai-gateway-ci:ro --env CONFIG_FILE=/config.yaml --env DOCKERD_ROOTLESS_ROOTLESSKIT_NET=slirp4netns --env DOCKERD_ROOTLESS_ROOTLESSKIT_MTU=65520 --env DOCKERD_ROOTLESS_ROOTLESSKIT_FLAGS=--pidns $RUNNER_IMAGE_REF
ExecStop=-/usr/bin/docker stop --time 360 easyai-gateway-ci-v2-runner
Restart=always
RestartSec=5s
TimeoutStartSec=60s
TimeoutStopSec=390s
# systemd only launches the host Docker client. Pull-request jobs run inside the
# nested rootless daemon and never receive the host or nested Docker socket.
NoNewPrivileges=true
CapabilityBoundingSet=
AmbientCapabilities=
PrivateTmp=true
PrivateDevices=true
ProtectSystem=strict
ProtectHome=true
ProtectKernelTunables=true
ProtectKernelModules=true
ProtectKernelLogs=true
ProtectControlGroups=true
ProtectClock=true
ProtectHostname=true
LockPersonality=true
RestrictRealtime=true
RestrictSUIDSGID=true
SystemCallArchitectures=native
UMask=0077
[Install]
WantedBy=multi-user.target

1
deploy/ci/production-migration-base Normal file
View File

@ -0,0 +1 @@
2d6c16fec0bec9c0288e5cb142b458af982fff8f

70
docs/decisions/001-production-cicd.md Normal file
View File

@ -0,0 +1,70 @@
# ADR-001: 隔离质量 CI 与 root-owned 生产发布
## 状态
Accepted
## 日期
2026-07-17
## 背景
AI Gateway 已通过独立部署仓库和 Docker Compose 运行在 `110.42.51.33`，公共入口是 `https://ai.51easyai.com`。同一服务器还运行认证中心、K3s 和其他 EasyAI 服务，磁盘与信任边界都很紧张。Gitea 1.22 对依赖 Job、`environment`、`permissions` 和 `concurrency` 的支持也不能作为生产发布的安全边界。
源码仓需要为 Pull Request、`main` 和版本 Tag 提供真实质量门禁；生产发布还必须满足源码可追溯、镜像不可变、数据库迁移前有备份、失败可恢复上一应用版本，以及 Tag 控制的脚本不能直接取得宿主 root 权限。
## 决策
### 质量 CI
- `BCAI/easyai-ai-gateway` 使用仓库级 Runner 标签 `easyai-gateway-ci-unprivileged-v2`。PR 与 `main` 由 `ci.yml` 执行，context 分别为 `ci / verify (pull_request)`、`ci / verify (push)`；`v*` Tag 必须由独立 `release-ci.yml` 执行，context 为 `release-ci / verify-tag (push)`。两份 workflow 执行相同质量门禁，但 Tag 不复用 `main` 的旧 context。
- Runner 外层固定为 `gitea/runner:2.0.0-dind-rootless` 的指定 digest；Job 固定为 `node:24.16.0-bookworm` 的指定 digest。外层按官方 rootless DinD 要求使用 `--privileged`，但内层 Docker daemon 和 Runner 以 UID 1000 运行。
- 不把宿主或内层 Docker socket 挂入 Job。Runner 配置使用 `docker_host: "-"`、`privileged: false`，工作流唯一允许的 bind source 是只读 `/opt/easyai-gateway-ci`，其中提供固定 Go、Node、pnpm、ShellCheck、Compose、Trivy 和 govulncheck 工具链。ShellCheck 与 Compose 使用官方静态发行物和固定 SHA-256，不复制宿主的可变插件或在 Job 中临时安装。RootlessKit 强制 `--pidns`，即使 PR 传入 `--pid=host`，Job 也不能进入外层 Runner 的 PID namespace；provision 会实测 namespace inode。
- CI 只执行格式、静态检查、单元测试、依赖审计、Compose 校验、仓库扫描和 CI 自测；不构建发布镜像，不调用 `sudo`，不执行生产发布助手。
- PR、`main` 与 Tag CI 都把 `deploy/ci/production-migration-base` 中的当前生产提交作为数据库兼容基线：已经存在于生产基线的迁移不得修改或删除，新迁移静态拒绝 DROP、TRUNCATE、DELETE、MERGE、CREATE OR REPLACE、RENAME、列类型/非空收紧等 contract 操作。PR/`main` 还使用事件中不可变的 base/before SHA 比对，确保基线更新稍有滞后时，已经进入 `main` 的新迁移仍不可被改写。
- 版本 Tag 必须是完整 SemVer，且目标提交必须属于 `main` 历史。该检查是发布前置证据，但本身不授予生产权限。
- Runner 注册状态保存在专用 Docker named volume，首次注册 Token 只传给短命注册容器；长期 systemd 服务不保存 Token，也不加入宿主 `docker`/`sudo` 用户组。
### 生产 CD
- 生产发布由部署仓的 root-owned dispatcher 负责，和源码 CI Runner 分离。dispatcher 只接受受保护的 `main` 历史版本 Tag，并在对应源码 SHA 上同时等待 `ci / verify (push)` 与本次 Tag 新产生的 `release-ci / verify-tag (push)` 成功。
- root 服务不执行 Tag 控制的 `pnpm`、测试脚本、源码仓 shell 脚本或应用程序。它只调用部署仓中由 root 固定和审核的命令，通过 BuildKit 构建目标镜像、用 Trivy 扫描镜像、发布 Registry digest，再进行备份、迁移、健康检查和回滚。
- API/Web 镜像以完整 Git SHA 作为可追溯 Tag，但生产 Compose 使用 Registry digest。服务器为每个 Git SHA 保存 root-only digest 清单，并拒绝把未知的既有 SHA Tag 当作可信发布物。
- 发布助手在迁移前生成并验证 PostgreSQL custom-format 备份，保留最近 5 份。应用健康检查失败时恢复上一组 digest-pinned 镜像；数据库恢复仍需人工确认。
### 残余风险与触发策略
rootless DinD 显著缩小了 Job 到宿主 Docker/root 的直接通路，但不是虚拟机级隔离。外层容器仍需 `--privileged`；Runner、rootless Docker、内核或容器运行时漏洞，以及 Gitea 对 `jobs.<job>.container.options` 的透传，都可能造成容器边界突破。Job 还保留依赖安装所需的出站网络，并可能消耗共享主机的 CPU、内存和磁盘。因此：
- 来自同仓受信任分支的 PR 可自动运行；来自 Fork 的 PR 必须先由维护者检查工作流变更并在 Gitea 中批准，不能自动调度。
- CI Job 不接收生产 Secret、宿主 Docker socket、部署目录或 Runner 状态目录。
- Runner 容量固定为 1，外层容器设 4096 PID 上限；磁盘在安装前后硬门禁，但共享主机仍不具备完整的 CPU、内存和长期磁盘配额隔离。
- 中长期应把不受信任 PR CI 迁移到独立主机或虚拟机；当前 rootless Runner 不能被描述为强多租户沙箱。
- Ubuntu 22.04 没有受限 user namespace，生产主机缺少 `rootlesskit` AppArmor profile 时不硬编码该 profile。provision 会先探测；在启用了 `kernel.apparmor_restrict_unprivileged_userns=1` 的新系统上，如果 profile 缺失则失败，不会降级为 `apparmor=unconfined` 或关闭内核限制。
## 备选方案
### 让源码 Runner 直接挂载宿主 Docker socket
拒绝。Docker socket 等价于宿主 root，任何 PR 工作流都可能取得生产服务器控制权，Fork 审批也不能把它变成可靠的技术隔离。
### 使用 host executor 但移除 Docker 组
拒绝。host Job 仍可读取宿主可见文件、消耗宿主资源并攻击同一用户进程；Gitea 对容器选项的处理也无法为 host executor 提供隔离。
### 让 Tag 工作流通过 `sudo` 调用发布脚本
拒绝。Tag 可以控制 checkout 中的脚本和应用代码；root 服务不得执行这些内容。固定部署仓 dispatcher 是独立的受保护信任根。
### `main` 通过后立即发布或只依赖 `latest`
拒绝。语义版本 Tag 是明确的发布授权点；digest 才能证明运行中的容器对应不可变产物并可靠选择回滚版本。
## 影响
- PR、`main` 和版本 Tag 都有自动质量证据，但源码仓 CI 成功不会单独获得生产权限。
- 创建受保护版本 Tag 后，部署仓 dispatcher 必须同时取得同 SHA 的 `main` context 和独立 Tag context，不能把旧 `main` 成功状态误当作本次 Tag 验证。
- 首次安装会清理本项目专属 Buildx 缓存并执行 8 GiB 前置、4 GiB 后置磁盘门禁，不会全局 prune 共享 Docker 状态。
- 首次启用 CD 仍需捕获当前运行镜像作为 bootstrap 回滚基线，并保证数据库迁移对上一应用版本向后兼容。
- 每次生产发布和恢复演练成功后，必须用单独受审 PR 把 `deploy/ci/production-migration-base` 前移到刚刚部署的完整源码 SHA；不得在发布成功前前移。静态门禁不能证明任意数据变换可逆，生产发布仍必须先做可恢复备份并定期执行真实 `pg_restore` 演练。

157
docs/runbooks/production-ci-cd.md Normal file
View File

@ -0,0 +1,157 @@
# 生产 CI/CD 运行手册
## 信任边界与固定资源
- 源码仓：`https://git.51easyai.com/BCAI/easyai-ai-gateway`
- CI Runner：`easyai-gateway-ci-v2-runner.service`
- CI 标签：`easyai-gateway-ci-unprivileged-v2`
- Runner 状态：Docker named volume `easyai-gateway-ci-v2-data` 内的 `/data/.runner`
- 只读工具链：`/opt/easyai-gateway-ci`
- Runner 配置：`/etc/easyai-gateway-ci-v2/config.yaml`
- Runner 运行参数：`/etc/easyai-gateway-ci-v2/runner.env`
- 生产入口：`https://ai.51easyai.com`
- 部署目录：`/root/easyai-ai-gateway-deploy`
源码仓只执行质量 CI：PR context 是 `ci / verify (pull_request)`，`main` context 是 `ci / verify (push)`，版本 Tag 使用独立 workflow/context `release-ci / verify-tag (push)`。三者都执行生产迁移兼容门禁、Go 格式/vet/test/govulncheck、前端 lint/test/build、依赖审计、Compose 校验、Trivy 仓库扫描和 CI 脚本自测。Job 没有 Docker socket、`sudo` 或部署目录权限，也不构建发布镜像。
生产 CD 由部署仓的 root-owned dispatcher 执行。它在相同源码 SHA 上同时等待 `ci / verify (push)` 与本次新产生的 `release-ci / verify-tag (push)` 成功，然后只运行部署仓中固定的 BuildKit 构建、Trivy 镜像扫描、digest 发布、备份、迁移、健康检查和回滚命令；不得执行 Tag checkout 中的 `pnpm`、测试、shell 脚本或应用程序。
provision 安装 checksum-pinned 的官方静态 ShellCheck `0.11.0` 和 Docker Compose `5.3.1`，不会依赖宿主是否预装这些命令。所有下载都在使用前校验固定 SHA-256，并在精确 Node Job 镜像内实际执行版本检查。
## 首次安装或修复 CI Runner
前置条件：Linux x86_64、可用 Docker Engine、root 权限，以及 Docker 文件系统至少 8 GiB 可用空间。脚本只压缩本项目专属 `easyai-gateway-ci` Buildx 缓存，不运行全局 `docker system prune`，因为该服务器与其他服务共享 Docker 状态。
从 Gitea 仓库设置的 Actions Runner 页面取得一次性仓库注册 Token，在服务器可信的源码 checkout 中执行：
```bash
RUNNER_REGISTRATION_TOKEN='<一次性 Token>' ./scripts/provision-ci-runner.sh
```
已有有效 named volume 时可直接重跑，不再需要 Token：
```bash
./scripts/provision-ci-runner.sh
```
注册 Token 通过交互 stdin 送给短命注册容器，不出现在宿主或容器的命令行参数中；provision 随后立即从环境中清除它，长期 systemd unit 也不包含 Token。不要输出或复制 `/data/.runner` 内容。脚本会停用旧 host Runner，并确保旧 Runner 用户和 v2 遗留用户不属于 `docker`/`sudo` 组。
默认磁盘门禁可用环境变量提高，但生产环境不应降低：
```bash
CI_RUNNER_MIN_FREE_GIB=8 \
CI_RUNNER_MIN_POST_INSTALL_FREE_GIB=4 \
RUNNER_REGISTRATION_TOKEN='<一次性 Token>' \
./scripts/provision-ci-runner.sh
```
## AppArmor 分支
Ubuntu 22.04 默认没有 `kernel.apparmor_restrict_unprivileged_userns` 限制，当前服务器没有 `rootlesskit` profile 是受支持路径。provision 会实测 Docker 是否接受该 profile；不存在时写入：
```text
RUNNER_SECURITY_OPTIONS=""
```
如果新系统的 `/proc/sys/kernel/apparmor_restrict_unprivileged_userns` 为 `1`，则必须先由宿主发行版或 Docker 安装包提供并加载 `rootlesskit` profile；provision 只探测和使用，不会自行复制一份 profile。缺失时 provision 会停止；不得手工关闭该 sysctl，也不得使用 `apparmor=unconfined` 绕过。
参考：[Docker Rootless Docker-in-Docker](https://docs.docker.com/engine/security/rootless/tips/#rootless-docker-in-docker)、[Ubuntu 安全特性版本矩阵](https://documentation.ubuntu.com/security/security-features/security-features-overview/)。
## Runner 真实验证
安装脚本会先启动一个无 Token、无持久 Runner 状态挂载、无宿主 bind mount 的短命 rootless DinD probe；随后启动长期服务，确认 Runner 已向 Gitea declare、通过内层 `docker info` 验证 `name=rootless`，再从内层 daemon 拉取固定 digest 的 Job 镜像，并在该镜像中实际运行全部工具。人工复核：
```bash
systemctl is-active easyai-gateway-ci-v2-runner.service
systemctl is-enabled easyai-gateway-ci-v2-runner.service
systemctl cat easyai-gateway-ci-v2-runner.service
journalctl -u easyai-gateway-ci-v2-runner.service --since '15 minutes ago' --no-pager
docker inspect -f 'user={{.Config.User}} privileged={{.HostConfig.Privileged}} apparmor={{.AppArmorProfile}}' \
easyai-gateway-ci-v2-runner
docker inspect -f '{{range .Mounts}}{{println .Source " -> " .Destination .Mode}}{{end}}' \
easyai-gateway-ci-v2-runner
docker exec easyai-gateway-ci-v2-runner docker info \
--format '{{range .SecurityOptions}}{{println .}}{{end}}'
docker exec easyai-gateway-ci-v2-runner docker image inspect \
'docker.io/library/node:24.16.0-bookworm@sha256:40ad9f3064e67d6860b4bc3fe1880b2953934fd6320ada990e45fe0efa6badd7' \
--format '{{.Id}}'
```
预期：外层 image user 为 `rootless`、外层因 DinD 为 `privileged=true`、内层安全选项含 `name=rootless`；RootlessKit 使用独立 PID namespace，内层 `--pid=host` 也不能看到外层 Runner；挂载仅包含专用 `/data`、只读配置和只读工具链，不能出现 `/var/run/docker.sock` 或 `/run/docker.sock`。
在 Gitea 中分别验证：
1. 同仓 PR 的 `ci / verify (pull_request)` 成功。
2. `main` Push 的 `ci / verify (push)` 成功。
3. 合法 SemVer Tag 新产生独立 `release-ci / verify-tag (push)`；非法或不属于 `main` 历史的 Tag 失败，且 Tag context 不能被旧 `main` context 替代。
4. Fork PR 默认不自动调度，维护者先检查 `.gitea/workflows/**` 和容器选项后再批准。
PR 与 `main` Push workflow 都校验事件携带的 base/before SHA 必须是触发 SHA 的祖先；分支落后或主干历史被改写时 CI 会 fail-closed。PR 先合并最新 `main` 再重跑，Gitea 分支保护同时启用 `block_on_outdated_branch`。
## Fork PR 残余风险
rootless DinD 不是 VM 沙箱。外层仍按官方要求使用 `--privileged`，Gitea runner 也会解析 PR 控制的 `jobs.<job>.container.options`。配置已禁止 Job privileged、宿主/内层 Docker socket 和任意 bind source，但 Runner、rootless Docker、容器运行时或内核漏洞仍可能突破边界；Job 的出站网络和资源消耗也不是强租户隔离。因此 Fork PR 必须维护者批准，CI 不得注入生产 Secret；未来应迁移到独立 CI 主机或虚拟机。
## 数据库迁移兼容门禁
`deploy/ci/production-migration-base` 必须等于当前生产 API 对应的完整源码 SHA。`scripts/ci-validate-migrations.mjs` 只允许新增、按文件名严格追加且为普通文件的迁移；生产已知迁移以及已经进入 `main` 的迁移不可修改或删除。DROP、TRUNCATE、DELETE、MERGE、CREATE OR REPLACE、动态 EXECUTE、事务控制、DO/函数/过程定义、RENAME、列类型变更、增加/设置 `NOT NULL`、删除默认值和 REVOKE 会直接使 CI 失败。需要过程式迁移时先拆成可审计的声明式 expand/contract SQL；不能把过程体藏在普通或 dollar-quoted 字符串中。
该规则允许 INSERT/UPDATE 等数据迁移，因此不能替代备份和恢复验证。每次生产发布成功并完成 `pg_restore` 演练后，创建一个只前移 `deploy/ci/production-migration-base` 的受审 PR；不要把基线指向尚未成功部署的提交。
## 发布生产版本
1. 合并到受保护 `main`，确认源码 CI 成功。
2. 在已验证提交上创建完整 SemVer Tag 并推送。
3. 确认同一 SHA 的 `ci / verify (push)` 和本次 `release-ci / verify-tag (push)` 都成功。
4. 由部署仓 root-owned dispatcher 构建、扫描并发布 digest；源码仓工作流不会直接调用生产 helper。
5. 发布、健康检查和恢复演练完成后，用单独 PR 把 `deploy/ci/production-migration-base` 更新为该生产 Tag 的完整源码 SHA。
```bash
git switch main
git pull --ff-only
git tag -a v0.1.1 -m 'release: v0.1.1'
git push origin v0.1.1
```
dispatcher 以完整 Git SHA 发布 Registry Tag，并把 Registry 返回的 digest 写入服务器 root-only 发布清单。生产 Compose 使用 `repository@sha256:...`，不是 `latest`、版本号或可变 SHA Tag。
## 发布后验证
```bash
curl -fsS https://ai.51easyai.com/gateway-api/healthz
curl -fsS https://ai.51easyai.com/gateway-api/readyz
ssh root@110.42.51.33 'cd /root/easyai-ai-gateway-deploy && ./gateway-ops.sh ps'
```
同时检查服务器磁盘、API 日志和数据库容器健康状态。发布后的首小时如出现错误率翻倍、P95 延迟增加 50%、数据完整性或安全问题，应立即回滚。
## 应用与数据库回滚
发布失败时固定部署脚本会恢复上一组 API/Web digest 并重复健康检查。人工回滚只选择服务器已有 root-only 发布清单的历史 Git SHA：
```bash
sudo /usr/local/sbin/easyai-ai-gateway-release <40 位历史 Git SHA>
```
没有 `/root/easyai-ai-gateway-deploy/.releases/<SHA>.env` 的远端 SHA Tag 不应被盲目信任。数据库备份位于 `/var/backups/easyai-ai-gateway`，只保留最近 5 份。应用回滚不会自动恢复数据库；只有停止写入并再次保留当前副本后，操作员才能选择备份执行 `pg_restore`。
## Runner 故障恢复
先在 Gitea 确认没有运行中的 Job，再检查服务与两个 daemon：
```bash
systemctl status easyai-gateway-ci-v2-runner.service --no-pager
docker logs --tail 100 easyai-gateway-ci-v2-runner
docker exec easyai-gateway-ci-v2-runner docker info
df -h /var/lib/docker
```
确认空闲后才执行：
```bash
systemctl restart easyai-gateway-ci-v2-runner.service
journalctl -u easyai-gateway-ci-v2-runner.service -n 100 --no-pager
```
不要删除 `easyai-gateway-ci-v2-data` volume；它包含 Runner 注册状态和内层 daemon 缓存。不得用全局 prune 处理磁盘压力。

3
package.json
View File

@ -21,6 +21,7 @@
"dotenv-cli": "^11.0.0",
"nx": "^21.0.0",
"typescript": "^5.8.0",
"vite": "^7.0.0"
"vite": "^7.3.5",
"vitest": "3.2.6"
}
}

11
packages/contracts/src/index.ts
View File

@ -303,6 +303,17 @@ export interface GatewayRunnerPolicyUpsertRequest {
status?: 'active' | 'disabled' | string;
}
export interface GatewaySkillBundleMetadata {
name: string;
version: string;
displayName: string;
modules: string[];
fileName: string;
downloadPath: string;
apiDocsJsonPath: string;
apiDocsYamlPath: string;
}
export interface GatewayUser {
id: string;
userKey: string;

1670
pnpm-lock.yaml
View File

File diff suppressed because it is too large Load Diff

14
pnpm-workspace.yaml
View File

@ -1,6 +1,20 @@
packages:
- apps/web
- packages/*
allowBuilds:
esbuild: true
nx: true
overrides:
'@babel/core@<=7.29.0': 7.29.6
'dompurify@<=3.4.10': 3.4.11
'esbuild@>=0.27.3 <0.28.1': 0.28.1
'form-data@>=4.0.0 <4.0.6': 4.0.6
'js-yaml@<3.15.0': 4.1.1
'mermaid@>=11.0.0-alpha.1 <=11.14.0': 11.15.0
'minimatch@>=9.0.0 <9.0.7': 9.0.7
'@nx/js>picomatch': 4.0.5
'@nx/vite>picomatch': 4.0.5
'@nx/workspace>picomatch': 4.0.5
'tmp@<0.2.7': 0.2.7

101
scripts/ci-build-images.sh Executable file
View File

@ -0,0 +1,101 @@
#!/usr/bin/env bash
set -euo pipefail
root=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
cd "$root"
tag=${IMAGE_TAG:-}
registry=${AI_GATEWAY_IMAGE_REGISTRY:-registry.cn-shanghai.aliyuncs.com/easyaigc}
builder=${AI_GATEWAY_BUILDX_BUILDER:-easyai-gateway-ci}
cache_limit=${AI_GATEWAY_BUILDX_CACHE_LIMIT:-2gb}
platform=${AI_GATEWAY_PLATFORM:-linux/amd64}
keep_images=0
build_complete=0
readonly trivy_db_repository=ghcr.m.daocloud.io/aquasecurity/trivy-db:2
case ${1:-} in
'') ;;
--keep-images) keep_images=1 ;;
*)
echo 'usage: ci-build-images.sh [--keep-images]' >&2
exit 64
;;
esac
if [[ ! $tag =~ ^[0-9a-f]{40}$ ]]; then
echo 'IMAGE_TAG must be a full lowercase Git SHA' >&2
exit 1
fi
if [[ ! $registry =~ ^[A-Za-z0-9.-]+(:[0-9]+)?(/[A-Za-z0-9._/-]+)+$ ]]; then
echo 'AI_GATEWAY_IMAGE_REGISTRY has an invalid format' >&2
exit 1
fi
if [[ ! $cache_limit =~ ^[1-9][0-9]*(kb|mb|gb)$ ]]; then
echo 'AI_GATEWAY_BUILDX_CACHE_LIMIT has an invalid format' >&2
exit 1
fi
api_image="$registry/ai-gateway:$tag"
web_image="$registry/ai-gateway-web:$tag"
cleanup() {
original_status=$?
trap - EXIT HUP INT TERM
cleanup_status=0
docker buildx prune --builder "$builder" --force --max-used-space "$cache_limit" >/dev/null || {
cleanup_status=$?
echo 'failed to prune the CI BuildKit cache' >&2
}
if [[ $keep_images -ne 1 || $build_complete -ne 1 ]]; then
docker image rm "$api_image" "$web_image" >/dev/null 2>&1 || {
image_rm_status=$?
[[ $cleanup_status -ne 0 ]] || cleanup_status=$image_rm_status
echo 'failed to remove CI image tags' >&2
}
fi
if [[ $original_status -ne 0 ]]; then
exit "$original_status"
fi
exit "$cleanup_status"
}
trap cleanup EXIT
trap 'exit 129' HUP
trap 'exit 130' INT
trap 'exit 143' TERM
if ! docker buildx inspect "$builder" >/dev/null 2>&1; then
docker buildx create --name "$builder" --driver docker-container --use >/dev/null
fi
docker buildx inspect "$builder" --bootstrap >/dev/null
common_args=(
--builder "$builder"
--platform "$platform"
--file Dockerfile
--pull
--load
)
docker buildx build --builder "$builder" \
"${common_args[@]:2}" \
--target api \
--build-arg "GO_BUILD_IMAGE=${AI_GATEWAY_GO_BUILD_IMAGE:-docker.m.daocloud.io/library/golang:1.26.5-alpine}" \
--build-arg "API_RUNTIME_IMAGE=${AI_GATEWAY_API_RUNTIME_IMAGE:-docker.m.daocloud.io/library/alpine:3.22}" \
--tag "$api_image" .
docker buildx build --builder "$builder" \
"${common_args[@]:2}" \
--target web \
--build-arg "NODE_BUILD_IMAGE=${AI_GATEWAY_NODE_BUILD_IMAGE:-docker.m.daocloud.io/library/node:24-alpine}" \
--build-arg "WEB_RUNTIME_IMAGE=${AI_GATEWAY_WEB_RUNTIME_IMAGE:-docker.m.daocloud.io/library/nginx:1.27-alpine}" \
--tag "$web_image" .
for image in "$api_image" "$web_image"; do
trivy image --db-repository "$trivy_db_repository" \
--scanners vuln,secret --severity HIGH,CRITICAL --ignore-unfixed \
--exit-code 1 --timeout 15m "$image"
done
build_complete=1
printf 'gateway_images=PASS git_sha=%s api=%s web=%s\n' "$tag" "$api_image" "$web_image"

435
scripts/ci-validate-migrations.mjs Executable file
View File

@ -0,0 +1,435 @@
#!/usr/bin/env node
import { execFileSync, spawnSync } from 'node:child_process'
import { lstatSync, readFileSync } from 'node:fs'
import { basename } from 'node:path'
const migrationDirectory = 'apps/api/migrations/'
const baselineFile = 'deploy/ci/production-migration-base'
const base = process.argv[2] || process.env.PRODUCTION_MIGRATION_BASE_SHA || ''
const immutableRef =
process.argv[3] || process.env.MIGRATION_IMMUTABILITY_REF || ''
function fail(message) {
console.error(`migration_safety=FAIL ${message}`)
process.exit(1)
}
function git(args, options = {}) {
try {
return execFileSync('git', args, {
encoding: options.encoding ?? 'utf8',
stdio: ['ignore', 'pipe', 'pipe'],
})
} catch (error) {
const stderr = error.stderr?.toString().trim()
fail(stderr ? `git_error=${JSON.stringify(stderr)}` : 'git command failed')
}
}
if (!/^[0-9a-f]{40}$/.test(base)) {
fail('PRODUCTION_MIGRATION_BASE_SHA must be a full lowercase commit SHA')
}
const root = git(['rev-parse', '--show-toplevel']).trim()
process.chdir(root)
const resolvedBase = git([
'rev-parse',
'--verify',
'--end-of-options',
`${base}^{commit}`,
]).trim()
if (resolvedBase !== base) {
fail('production migration baseline did not resolve exactly')
}
const ancestry = spawnSync('git', ['merge-base', '--is-ancestor', base, 'HEAD'], {
stdio: 'ignore',
})
if (ancestry.status !== 0) {
fail('production migration baseline is not an ancestor of HEAD')
}
const head = git(['rev-parse', '--verify', 'HEAD^{commit}']).trim()
const baselineTreeEntry = git(['ls-tree', 'HEAD', '--', baselineFile]).trim()
let baselineState
try {
baselineState = lstatSync(baselineFile)
} catch {
fail('production migration baseline file is unavailable in the worktree')
}
if (
!/^100644 blob [0-9a-f]+\t/.test(baselineTreeEntry) ||
!baselineState.isFile() ||
baselineState.isSymbolicLink()
) {
fail('production migration baseline must be a mode 100644 regular file')
}
if (readFileSync(baselineFile, 'utf8').trim() !== base) {
fail('production migration baseline argument does not match the reviewed file')
}
function changedMigrations(from) {
const rawChanges = git(
[
'diff',
'--name-status',
'-z',
'--no-renames',
`${from}..HEAD`,
'--',
migrationDirectory,
],
{ encoding: null },
)
const fields = rawChanges.toString('utf8').split('\0')
if (fields.at(-1) === '') fields.pop()
if (fields.length % 2 !== 0) {
fail('could not parse changed migration paths')
}
return fields
}
const fields = changedMigrations(base)
function executableSql(sql, source = 'SQL input') {
let output = ''
for (let index = 0; index < sql.length; index += 1) {
const current = sql[index]
const next = sql[index + 1]
if (current === '-' && next === '-') {
index += 2
while (index < sql.length && sql[index] !== '\n') index += 1
output += '\n'
continue
}
if (current === '/' && next === '*') {
let depth = 1
index += 2
while (index < sql.length && depth > 0) {
if (sql[index] === '/' && sql[index + 1] === '*') {
depth += 1
index += 2
continue
}
if (sql[index] === '*' && sql[index + 1] === '/') {
depth -= 1
index += 2
continue
}
index += 1
}
if (depth !== 0) fail('unterminated SQL block comment')
index -= 1
output += ' '
continue
}
if (current === "'" || current === '"') {
const prefix = sql.slice(Math.max(0, index - 2), index).toUpperCase()
const previous = sql[index - 1]?.toUpperCase()
const beforePrevious = sql[index - 2] || ''
const beforeUnicodePrefix = sql[index - 3] || ''
const escapeString =
current === "'" &&
previous === 'E' &&
!/[A-Za-z0-9_$]/.test(beforePrevious)
const unicodeString =
prefix === 'U&' && !/[A-Za-z0-9_$]/.test(beforeUnicodePrefix)
if (escapeString || unicodeString) {
fail(`${source}: PostgreSQL escape/unicode strings are not allowed in migrations`)
}
const quote = current
index += 1
let closed = false
while (index < sql.length) {
if (sql[index] === quote && sql[index + 1] === quote) {
index += 2
continue
}
if (sql[index] === quote) {
closed = true
break
}
index += 1
}
if (!closed) fail('unterminated SQL quoted value')
output += ' '
continue
}
if (current === '$') {
const delimiter = sql.slice(index).match(/^\$(?:[A-Za-z_][A-Za-z0-9_]*)?\$/)?.[0]
if (delimiter) {
const bodyStart = index + delimiter.length
const bodyEnd = sql.indexOf(delimiter, bodyStart)
if (bodyEnd === -1) fail('unterminated SQL dollar-quoted body')
// PostgreSQL function bodies may contain executable DDL. Scan their
// contents recursively instead of treating them as inert strings.
const bodySql = executableSql(sql.slice(bodyStart, bodyEnd), source)
// A bare END terminates a PL/pgSQL block inside a dollar-quoted body,
// but at the top level PostgreSQL treats END as COMMIT. Mask only the
// block terminator here so the top-level transaction rule stays exact.
const bodyWithoutBlockEnd = bodySql
.split(';')
.map((statement) => (/^\s*END\s*$/i.test(statement) ? ' ' : statement))
.join(';')
output += ` ${bodyWithoutBlockEnd} `
index = bodyEnd + delimiter.length - 1
continue
}
}
output += current
}
return output
}
const destructiveRules = [
{
name: 'procedural SQL body',
pattern:
/^\s*(?:DO\b|CREATE\s+(?:OR\s+REPLACE\s+)?(?:FUNCTION|PROCEDURE)\b)/i,
},
{
name: 'dynamic SQL execution',
pattern: /\bEXECUTE\b/i,
},
{
name: 'destructive DROP operation',
pattern: /\bDROP\b/i,
},
{ name: 'MERGE operation', pattern: /\bMERGE\b/i },
{
name: 'CREATE OR REPLACE operation',
pattern: /\bCREATE\s+OR\s+REPLACE\b/i,
},
{ name: 'TRUNCATE operation', pattern: /\bTRUNCATE(?:\s+TABLE)?\b/i },
{ name: 'DELETE FROM operation', pattern: /\bDELETE\s+FROM\b/i },
{ name: 'permission revocation', pattern: /\bREVOKE\b/i },
{
name: 'transaction control operation',
pattern:
/\b(?:COMMIT|ROLLBACK|ABORT|SAVEPOINT)\b|\bRELEASE\s+SAVEPOINT\b|\bPREPARE\s+TRANSACTION\b|^\s*END(?:\s+(?:WORK|TRANSACTION))?(?:\s+AND\s+(?:NO\s+)?CHAIN)?\s*$/i,
},
{
name: 'SQL string semantics override',
pattern:
/\bSET\s+(?:LOCAL\s+|SESSION\s+)?STANDARD_CONFORMING_STRINGS\b/i,
},
{
name: 'object or column rename',
pattern: /\bRENAME\b/i,
},
{ name: 'SET SCHEMA operation', pattern: /\bSET\s+SCHEMA\b/i },
{
name: 'column type change',
pattern:
/\bALTER\s+TABLE\b[\s\S]*\bALTER\s+(?:COLUMN\s+)?[\s\S]*\b(?:SET\s+DATA\s+)?TYPE\b/i,
},
{
name: 'SET NOT NULL operation',
pattern:
/\bALTER\s+TABLE\b[\s\S]*\bALTER\s+(?:COLUMN\s+)?[\s\S]*\bSET\s+NOT\s+NULL\b/i,
},
{
name: 'non-null column addition',
pattern:
/\bALTER\s+TABLE\b[\s\S]*\bADD\s+(?:COLUMN\s+)?[\s\S]*\bNOT\s+NULL\b/i,
},
{
name: 'DROP DEFAULT operation',
pattern:
/\bALTER\s+TABLE\b[\s\S]*\bALTER\s+(?:COLUMN\s+)?[\s\S]*\bDROP\s+DEFAULT\b/i,
},
]
const violations = []
let addedFiles = 0
let immutableBase = ''
const orderingCandidates = new Set()
if (immutableRef) {
if (
!/^[0-9a-f]{40}$/.test(immutableRef) &&
immutableRef !== 'refs/remotes/origin/main'
) {
fail('MIGRATION_IMMUTABILITY_REF must be a full commit SHA or refs/remotes/origin/main')
}
const immutableTip = git([
'rev-parse',
'--verify',
'--end-of-options',
`${immutableRef}^{commit}`,
]).trim()
const baseAtEvent = spawnSync(
'git',
['show', `${immutableTip}:${baselineFile}`],
{ encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] },
)
if (baseAtEvent.status === 0) {
const previousBaselineTreeEntry = git([
'ls-tree',
immutableTip,
'--',
baselineFile,
]).trim()
if (!/^100644 blob [0-9a-f]+\t/.test(previousBaselineTreeEntry)) {
fail('previous production migration baseline must be a mode 100644 regular file')
}
const previousProductionBase = baseAtEvent.stdout.trim()
if (!/^[0-9a-f]{40}$/.test(previousProductionBase)) {
fail('previous production migration baseline is invalid')
}
const baselineAdvance = spawnSync(
'git',
['merge-base', '--is-ancestor', previousProductionBase, base],
{ stdio: 'ignore' },
)
if (baselineAdvance.status !== 0) {
fail('production migration baseline must only move forward')
}
}
const baselineWasAlreadyReviewed = spawnSync(
'git',
['merge-base', '--is-ancestor', base, immutableTip],
{ stdio: 'ignore' },
)
if (baselineWasAlreadyReviewed.status !== 0) {
fail('production migration baseline must belong to the immutable event base history')
}
if (immutableTip === head) {
const parent = spawnSync(
'git',
['rev-parse', '--verify', `${immutableTip}^1^{commit}`],
{ encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] },
)
immutableBase = parent.status === 0 ? parent.stdout.trim() : ''
} else {
const immutableAncestry = spawnSync(
'git',
['merge-base', '--is-ancestor', immutableTip, head],
{ stdio: 'ignore' },
)
if (immutableAncestry.status !== 0) {
fail('migration immutability base is not an ancestor of HEAD')
}
immutableBase = immutableTip
}
if (immutableBase) {
const immutableChanges = changedMigrations(immutableBase)
for (let index = 0; index < immutableChanges.length; index += 2) {
const status = immutableChanges[index]
const file = immutableChanges[index + 1]
if (status === 'A') {
orderingCandidates.add(file)
} else {
violations.push(
`${file}: migration present on main is immutable (status ${status})`,
)
}
}
}
}
function migrationNamesAt(ref) {
const output = git(
['ls-tree', '-r', '-z', '--name-only', ref, '--', migrationDirectory],
{ encoding: null },
)
return output
.toString('utf8')
.split('\0')
.filter(Boolean)
.filter((file) => {
const relative = file.slice(migrationDirectory.length)
return file.startsWith(migrationDirectory) && !relative.includes('/')
})
.map((file) => basename(file))
.filter((name) => /^\d{4}_[a-z0-9][a-z0-9_]*\.sql$/.test(name))
.sort()
}
const orderingBase = immutableBase || base
const existingNames = migrationNamesAt(orderingBase)
const previousMaximumName = existingNames.at(-1) || ''
if (!immutableBase) {
for (let index = 0; index < fields.length; index += 2) {
if (fields[index] === 'A') orderingCandidates.add(fields[index + 1])
}
}
for (let index = 0; index < fields.length; index += 2) {
const status = fields[index]
const file = fields[index + 1]
if (status !== 'A') {
violations.push(`${file}: applied migrations are immutable (status ${status})`)
continue
}
addedFiles += 1
const filename = basename(file)
if (
file !== `${migrationDirectory}${filename}` ||
!/^\d{4}_[a-z0-9][a-z0-9_]*\.sql$/.test(filename)
) {
violations.push(`${file}: new migration must use NNNN_lowercase_name.sql`)
continue
}
if (
orderingCandidates.has(file) &&
previousMaximumName &&
filename <= previousMaximumName
) {
violations.push(
`${file}: new migration name must sort after ${previousMaximumName}`,
)
continue
}
const treeEntry = git(['ls-tree', 'HEAD', '--', file]).trim()
let fileState
try {
fileState = lstatSync(file)
} catch {
violations.push(`${file}: new migration is unavailable in the worktree`)
continue
}
if (
!/^100644 blob [0-9a-f]+\t/.test(treeEntry) ||
!fileState.isFile() ||
fileState.isSymbolicLink()
) {
violations.push(`${file}: new migration must be a mode 100644 regular file`)
continue
}
const statements = executableSql(readFileSync(file, 'utf8'), file).split(';')
for (const statement of statements) {
for (const rule of destructiveRules) {
if (rule.pattern.test(statement)) {
violations.push(`${file}: ${rule.name}`)
}
}
}
}
if (violations.length > 0) {
for (const violation of [...new Set(violations)]) {
console.error(`migration_safety_violation=${JSON.stringify(violation)}`)
}
fail(`base=${base} violations=${new Set(violations).size}`)
}
console.log(`migration_safety=PASS base=${base} added_files=${addedFiles}`)

22
scripts/ci-validate-semver.sh Executable file
View File

@ -0,0 +1,22 @@
#!/usr/bin/env bash
set -euo pipefail
tag=${1:-}
die() {
printf 'invalid release tag: %s\n' "$tag" >&2
exit 1
}
[[ $tag == v* ]] || die
version=${tag#v}
# Bash arrays discard trailing empty fields, so parsing first would accept
# values such as v1.2.3. and v1.2.3-alpha. Validate the complete string with
# the SemVer 2.0.0 grammar before doing anything else with the tag.
semver_pattern='^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(-((0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*)(\.(0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*))*))?(\+([0-9A-Za-z-]+(\.[0-9A-Za-z-]+)*))?$'
LC_ALL=C
export LC_ALL
[[ $version =~ $semver_pattern ]] || die
printf 'release_tag=PASS tag=%s\n' "$tag"

452
scripts/deyun-video-e2e.mjs Executable file
View File

@ -0,0 +1,452 @@
#!/usr/bin/env node
import { execFileSync } from 'node:child_process';
import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { dirname, join } from 'node:path';
const baseURL = (process.env.GATEWAY_BASE_URL || 'http://127.0.0.1:8088').replace(/\/+$/, '');
const model = process.env.DEYUN_VIDEO_MODEL || 'deyun-seedance-2.0-canary';
const expectedPlatform = process.env.DEYUN_VIDEO_PLATFORM || '漫路（火山兼容）';
const expectedProviderModel = process.env.DEYUN_VIDEO_PROVIDER_MODEL || 'doubao-seedance-2-0';
const pollIntervalMs = positiveInteger(process.env.DEYUN_VIDEO_POLL_INTERVAL_MS, 5000);
const taskTimeoutMs = positiveInteger(process.env.DEYUN_VIDEO_TASK_TIMEOUT_MS, 20 * 60 * 1000);
const outputPath =
process.env.DEYUN_VIDEO_E2E_OUTPUT ||
`artifacts/deyun-video-e2e-${new Date().toISOString().replaceAll(/[:.]/g, '-')}.json`;
const database = {
container: process.env.GATEWAY_E2E_DB_CONTAINER || 'postgres',
name: process.env.GATEWAY_E2E_DB_NAME || 'easyai_ai_gateway',
user: process.env.GATEWAY_E2E_DB_USER || 'easyai',
};
const validationCases = [
{
name: '480p-4s-audio-off',
request: {
model,
prompt: 'A glossy red cube rotates slowly on a clean white studio table, locked camera, soft daylight.',
resolution: '480p',
ratio: '16:9',
duration: 4,
generate_audio: false,
seed: 41001,
watermark: false,
runMode: 'real',
},
expected: {
height: 480,
duration: 4,
audio: false,
ratio: 16 / 9,
},
},
{
name: '720p-6s-audio-on',
request: {
model,
prompt: 'A calm ocean wave rolls toward a sandy beach at sunrise, locked camera, natural ambient sound.',
resolution: '720p',
ratio: '16:9',
duration: 6,
generate_audio: true,
seed: 42002,
watermark: false,
runMode: 'real',
},
expected: {
height: 720,
duration: 6,
audio: true,
ratio: 16 / 9,
},
},
];
const requestedCases = new Set(
String(process.env.DEYUN_VIDEO_CASES || '')
.split(',')
.map((value) => value.trim())
.filter(Boolean),
);
if (requestedCases.size > 0) {
const selectedCases = validationCases.filter((validationCase) => requestedCases.has(validationCase.name));
if (selectedCases.length !== requestedCases.size) {
const knownCases = validationCases.map((validationCase) => validationCase.name).join(', ');
throw new Error(`Unknown DEYUN_VIDEO_CASES value; known cases: ${knownCases}`);
}
validationCases.splice(0, validationCases.length, ...selectedCases);
}
const submittedTaskIds = [];
function assert(condition, message) {
if (!condition) throw new Error(message);
}
function positiveInteger(value, fallback) {
const parsed = Number.parseInt(String(value || ''), 10);
return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
}
function nearlyEqual(left, right, tolerance = 1e-6) {
return Math.abs(Number(left) - Number(right)) <= tolerance;
}
function runPSQL(query) {
return execFileSync(
'docker',
['exec', database.container, 'psql', '-U', database.user, '-d', database.name, '-At', '-F', '\t', '-c', query],
{ encoding: 'utf8' },
).trim();
}
function resolveGatewayAPIKey() {
if (process.env.GATEWAY_E2E_API_KEY) {
assert(process.env.GATEWAY_E2E_API_KEY_ID, 'Set GATEWAY_E2E_API_KEY_ID when GATEWAY_E2E_API_KEY is provided');
const metadata = apiKeyMetadata(process.env.GATEWAY_E2E_API_KEY_ID);
return {
...metadata,
secret: process.env.GATEWAY_E2E_API_KEY,
source: 'environment',
};
}
const query = `
SELECT key.id::text,
key.key_secret,
key.gateway_user_id::text,
wallet.balance::float8,
wallet.frozen_balance::float8
FROM gateway_api_keys key
JOIN gateway_wallet_accounts wallet
ON wallet.gateway_user_id = key.gateway_user_id
AND wallet.currency = 'resource'
AND wallet.status = 'active'
WHERE key.deleted_at IS NULL
AND key.status = 'active'
AND COALESCE(key.key_secret, '') <> ''
AND (key.expires_at IS NULL OR key.expires_at > now())
AND (key.scopes ? 'video' OR key.scopes ? '*' OR key.scopes ? 'all')
AND (wallet.balance - wallet.frozen_balance) > 0
ORDER BY (wallet.balance - wallet.frozen_balance) DESC, key.created_at DESC
LIMIT 1`;
const fields = runPSQL(query).split('\t');
assert(fields.length === 5 && fields[0] && fields[1], 'No recoverable video-scoped Gateway API Key with positive balance was found');
return {
keyId: fields[0],
secret: fields[1],
userId: fields[2],
balance: Number(fields[3]),
frozenBalance: Number(fields[4]),
source: 'database',
};
}
function apiKeyMetadata(keyId) {
const escapedKeyId = String(keyId).replaceAll("'", "''");
const output = runPSQL(`
SELECT key.id::text,
key.gateway_user_id::text,
wallet.balance::float8,
wallet.frozen_balance::float8
FROM gateway_api_keys key
JOIN gateway_wallet_accounts wallet
ON wallet.gateway_user_id = key.gateway_user_id
AND wallet.currency = 'resource'
WHERE key.id = '${escapedKeyId}'::uuid
LIMIT 1`);
const fields = output.split('\t');
assert(fields.length === 4 && fields[0], `Gateway API Key ${keyId} was not found`);
return {
keyId: fields[0],
userId: fields[1],
balance: Number(fields[2]),
frozenBalance: Number(fields[3]),
};
}
function walletState(userId) {
const escapedUserId = String(userId).replaceAll("'", "''");
const fields = runPSQL(`
SELECT balance::float8, frozen_balance::float8
FROM gateway_wallet_accounts
WHERE gateway_user_id = '${escapedUserId}'::uuid
AND currency = 'resource'
LIMIT 1`).split('\t');
assert(fields.length === 2, `Wallet for Gateway user ${userId} was not found`);
return {
balance: Number(fields[0]),
frozenBalance: Number(fields[1]),
};
}
async function request(path, init = {}) {
const response = await fetch(`${baseURL}${path}`, {
...init,
headers: {
Authorization: `Bearer ${authentication.secret}`,
...(init.body ? { 'Content-Type': 'application/json' } : {}),
...(init.headers || {}),
},
});
const text = await response.text();
if (!response.ok) {
throw new Error(`${init.method || 'GET'} ${path} failed ${response.status}: ${text}`);
}
return text ? JSON.parse(text) : {};
}
async function createVideoTask(body) {
const accepted = await request('/api/v1/videos/generations', {
method: 'POST',
headers: { 'X-Async': 'true' },
body: JSON.stringify(body),
});
const taskId = accepted.taskId || accepted.task?.id;
assert(taskId, `Video task acceptance is missing taskId: ${JSON.stringify(accepted)}`);
submittedTaskIds.push(taskId);
return taskId;
}
async function pollTask(taskId) {
const startedAt = Date.now();
while (Date.now() - startedAt < taskTimeoutMs) {
const task = await request(`/api/v1/tasks/${taskId}`);
if (task.status === 'succeeded') return task;
if (task.status === 'failed' || task.status === 'cancelled') {
throw new Error(`Task ${taskId} ended as ${task.status}: ${task.errorMessage || task.error || JSON.stringify(task.result)}`);
}
await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
}
throw new Error(`Timed out after ${taskTimeoutMs}ms waiting for task ${taskId}`);
}
async function taskEvents(taskId) {
const response = await fetch(`${baseURL}/api/v1/tasks/${taskId}/events`, {
headers: { Authorization: `Bearer ${authentication.secret}` },
});
const text = await response.text();
if (!response.ok) throw new Error(`GET task events failed ${response.status}: ${text}`);
return text
.split(/\r?\n\r?\n/)
.flatMap((block) => {
const data = block
.split(/\r?\n/)
.filter((line) => line.startsWith('data:'))
.map((line) => line.slice(5).trim())
.join('\n');
return data ? [JSON.parse(data)] : [];
});
}
async function taskPreprocessingLogs(taskId) {
return request(`/api/v1/tasks/${taskId}/param-preprocessing`);
}
function videoURLFromTask(task) {
const data = Array.isArray(task.result?.data) ? task.result.data : [];
return data.find((item) => item?.type === 'video')?.url || data.find((item) => item?.url)?.url || '';
}
async function downloadVideo(url, filePath) {
const response = await fetch(url);
assert(response.ok, `Download ${url} failed ${response.status}`);
const bytes = Buffer.from(await response.arrayBuffer());
assert(bytes.length > 0, `Downloaded video ${url} is empty`);
await writeFile(filePath, bytes);
return bytes.length;
}
function probeVideo(filePath) {
const output = execFileSync(
'ffprobe',
['-v', 'error', '-show_streams', '-show_format', '-of', 'json', filePath],
{ encoding: 'utf8', maxBuffer: 16 * 1024 * 1024 },
);
return JSON.parse(output);
}
function validateRequestSnapshot(task, expectedRequest) {
const snapshot = task.request || {};
for (const key of ['model', 'resolution', 'ratio', 'duration', 'generate_audio', 'seed']) {
assert(
snapshot[key] === expectedRequest[key],
`Task ${task.id} request.${key}=${JSON.stringify(snapshot[key])}, expected ${JSON.stringify(expectedRequest[key])}`,
);
}
}
function validateTaskAudit(task, events) {
const attempts = Array.isArray(task.attempts) ? task.attempts : [];
assert(attempts.length === 1, `Task ${task.id} has ${attempts.length} attempts, expected exactly one`);
const attempt = attempts[0];
assert(attempt.platformName === expectedPlatform, `Task ${task.id} used platform ${attempt.platformName}, expected ${expectedPlatform}`);
assert(attempt.provider === 'volces', `Task ${task.id} used provider ${attempt.provider}, expected volces`);
assert(
attempt.providerModelName === expectedProviderModel,
`Task ${task.id} used provider model ${attempt.providerModelName}, expected ${expectedProviderModel}`,
);
assert(task.remoteTaskId, `Task ${task.id} is missing remoteTaskId`);
assert(attempt.requestId, `Task ${task.id} attempt is missing requestId`);
const startedEvents = events.filter((event) => event.eventType === 'task.attempt.started');
assert(startedEvents.length === 1, `Task ${task.id} emitted ${startedEvents.length} task.attempt.started events`);
assert(Number(task.finalChargeAmount) > 0, `Task ${task.id} finalChargeAmount must be positive`);
return attempt;
}
function validateMedia(probe, expected, taskId) {
const streams = Array.isArray(probe.streams) ? probe.streams : [];
const video = streams.find((stream) => stream.codec_type === 'video');
const audioStreams = streams.filter((stream) => stream.codec_type === 'audio');
assert(video, `Task ${taskId} output has no video stream`);
const width = Number(video.width);
const height = Number(video.height);
const duration = Number(video.duration || probe.format?.duration);
assert(height === expected.height, `Task ${taskId} output height=${height}, expected ${expected.height}`);
const ratioError = Math.abs(width / height - expected.ratio) / expected.ratio;
assert(ratioError <= 0.02, `Task ${taskId} aspect ratio ${width}:${height} differs from 16:9 by ${(ratioError * 100).toFixed(2)}%`);
assert(Number.isFinite(duration), `Task ${taskId} output duration is unavailable`);
assert(Math.abs(duration - expected.duration) <= 1, `Task ${taskId} duration=${duration}s, expected ${expected.duration}s ±1s`);
if (expected.audio) {
assert(audioStreams.length > 0, `Task ${taskId} requested audio but output has no audio stream`);
const audioDuration = Number(audioStreams[0].duration || probe.format?.duration);
if (Number.isFinite(audioDuration)) {
assert(audioDuration >= duration - 1, `Task ${taskId} audio duration=${audioDuration}s is too short for video duration=${duration}s`);
}
} else {
assert(audioStreams.length === 0, `Task ${taskId} disabled audio but output has ${audioStreams.length} audio stream(s)`);
}
return {
width,
height,
duration,
ratio: width / height,
videoCodec: video.codec_name || null,
audioStreams: audioStreams.map((stream) => ({
codec: stream.codec_name || null,
channels: Number(stream.channels || 0),
sampleRate: Number(stream.sample_rate || 0),
duration: Number(stream.duration || probe.format?.duration || 0),
})),
};
}
const authentication = resolveGatewayAPIKey();
function sanitizedFailureMessage(error) {
return String(error instanceof Error ? error.message : error)
.replace(/Request id:\s*[A-Za-z0-9_-]+/gi, 'Request id: [redacted]')
.replace(/\b\d{8,}\b/g, '[redacted-id]');
}
async function writeFailureReport(error) {
const report = {
ok: false,
generatedAt: new Date().toISOString(),
baseURL,
model,
expectedPlatform,
expectedProviderModel,
authentication: {
type: 'gateway_api_key',
source: authentication.source,
keyId: authentication.keyId,
},
submittedTaskIds,
error: sanitizedFailureMessage(error),
};
await mkdir(dirname(outputPath), { recursive: true });
await writeFile(outputPath, `${JSON.stringify(report, null, 2)}\n`, 'utf8');
return report;
}
async function main() {
const tempDirectory = await mkdtemp(join(tmpdir(), 'deyun-video-e2e-'));
const walletBefore = walletState(authentication.userId);
const results = [];
try {
for (const validationCase of validationCases) {
const taskId = await createVideoTask(validationCase.request);
const task = await pollTask(taskId);
const [events, preprocessing] = await Promise.all([
taskEvents(taskId),
taskPreprocessingLogs(taskId),
]);
validateRequestSnapshot(task, validationCase.request);
const attempt = validateTaskAudit(task, events);
assert(
Array.isArray(preprocessing.items) && preprocessing.items.length > 0,
`Task ${taskId} has no parameter preprocessing audit record`,
);
const videoURL = videoURLFromTask(task);
assert(videoURL, `Task ${taskId} result is missing a video URL`);
const videoPath = join(tempDirectory, `${validationCase.name}.mp4`);
const byteSize = await downloadVideo(videoURL, videoPath);
const probe = probeVideo(videoPath);
const observed = validateMedia(probe, validationCase.expected, taskId);
results.push({
name: validationCase.name,
taskId,
remoteTaskId: task.remoteTaskId,
requestId: attempt.requestId,
platform: attempt.platformName,
providerModelName: attempt.providerModelName,
requested: {
resolution: validationCase.request.resolution,
ratio: validationCase.request.ratio,
duration: validationCase.request.duration,
generateAudio: validationCase.request.generate_audio,
seed: validationCase.request.seed,
},
observed,
byteSize,
finalChargeAmount: Number(task.finalChargeAmount),
billingSummary: task.billingSummary || {},
eventTypes: events.map((event) => event.eventType),
preprocessingChangeCount: preprocessing.items.reduce((sum, item) => sum + Number(item.changeCount || 0), 0),
});
}
} finally {
await rm(tempDirectory, { recursive: true, force: true });
}
const walletAfter = walletState(authentication.userId);
const totalCharge = results.reduce((sum, result) => sum + result.finalChargeAmount, 0);
const walletDebit = walletBefore.balance - walletAfter.balance;
assert(nearlyEqual(walletDebit, totalCharge, 1e-6), `Wallet debit=${walletDebit}, expected total charge=${totalCharge}`);
assert(
nearlyEqual(walletAfter.frozenBalance, walletBefore.frozenBalance, 1e-6),
`Wallet frozen balance changed from ${walletBefore.frozenBalance} to ${walletAfter.frozenBalance}`,
);
const report = {
ok: true,
generatedAt: new Date().toISOString(),
baseURL,
model,
expectedPlatform,
expectedProviderModel,
authentication: {
type: 'gateway_api_key',
source: authentication.source,
keyId: authentication.keyId,
},
wallet: {
balanceBefore: walletBefore.balance,
balanceAfter: walletAfter.balance,
frozenBalanceBefore: walletBefore.frozenBalance,
frozenBalanceAfter: walletAfter.frozenBalance,
debit: walletDebit,
totalCharge,
},
results,
};
await mkdir(dirname(outputPath), { recursive: true });
await writeFile(outputPath, `${JSON.stringify(report, null, 2)}\n`, 'utf8');
console.log(JSON.stringify({ ...report, outputPath }, null, 2));
}
main().catch(async (error) => {
const report = await writeFailureReport(error);
console.error(report.error);
console.error(`Failure report: ${outputPath}`);
process.exitCode = 1;
});

272
scripts/output-token-limit-e2e.mjs Normal file
View File

@ -0,0 +1,272 @@
#!/usr/bin/env node
import { execFileSync } from 'node:child_process';
import { mkdir, writeFile } from 'node:fs/promises';
import { dirname } from 'node:path';
const baseURL = (process.env.GATEWAY_BASE_URL || 'http://127.0.0.1:8088').replace(/\/+$/, '');
const authentication = resolveGatewayAPIKey();
const timeoutMs = Number(process.env.GATEWAY_E2E_TIMEOUT_MS || 180_000);
const scenarios = [
{
name: '火山 128K Chat 未传上限',
platform: '火山引擎',
model: process.env.GATEWAY_E2E_VOLCES_128K_MODEL || 'volces-openai:doubao-seed-2-0-pro-260215',
path: '/v1/chat/completions',
body: chatBody(),
expected: { parameter: 'max_tokens', value: 43690, injected: true },
},
{
name: '火山 32K Chat 未传上限',
platform: '火山引擎',
model: process.env.GATEWAY_E2E_VOLCES_32K_MODEL || 'volces-openai:doubao-seed-1-8-251228',
path: '/v1/chat/completions',
body: chatBody(),
expected: { parameter: 'max_tokens', value: 10922, injected: true },
},
{
name: '火山 Chat max_tokens=null',
platform: '火山引擎',
model: process.env.GATEWAY_E2E_VOLCES_128K_MODEL || 'volces-openai:doubao-seed-2-0-pro-260215',
path: '/v1/chat/completions',
body: chatBody({ max_tokens: null }),
expected: { parameter: 'max_tokens', value: 43690, injected: true },
},
{
name: '火山 Chat 显式 max_tokens',
platform: '火山引擎',
model: process.env.GATEWAY_E2E_VOLCES_128K_MODEL || 'volces-openai:doubao-seed-2-0-pro-260215',
path: '/v1/chat/completions',
body: chatBody({ max_tokens: 64 }),
expected: { parameter: 'max_tokens', value: 64, injected: false },
},
{
name: '火山 Chat 显式 max_completion_tokens',
platform: '火山引擎',
model: process.env.GATEWAY_E2E_VOLCES_128K_MODEL || 'volces-openai:doubao-seed-2-0-pro-260215',
path: '/v1/chat/completions',
body: chatBody({ max_completion_tokens: 64 }),
expected: { parameter: 'max_tokens', absent: true, injected: false, preserved: { max_completion_tokens: 64 } },
},
{
name: '火山 Responses 未传上限',
platform: '火山引擎',
model: process.env.GATEWAY_E2E_VOLCES_128K_MODEL || 'volces-openai:doubao-seed-2-0-pro-260215',
path: '/v1/responses',
body: responsesBody(),
expected: { parameter: 'max_output_tokens', value: 43690, injected: true },
},
{
name: '阿里百炼 Qwen Chat 未传上限',
platform: '阿里云百炼',
model: process.env.GATEWAY_E2E_QWEN_MODEL || 'aliyun-bailian-openai:qwen3.7-plus',
path: '/v1/chat/completions',
body: chatBody(),
expected: { parameter: 'max_tokens', absent: true, injected: false },
},
{
name: '阿里百炼 Qwen Responses 未传上限',
platform: '阿里云百炼',
model: process.env.GATEWAY_E2E_QWEN_MODEL || 'aliyun-bailian-openai:qwen3.7-plus',
path: '/v1/responses',
body: responsesBody(),
expected: { parameter: 'max_output_tokens', absent: true, injected: false },
},
{
name: 'DeepSeek 官网 Chat 未传上限',
platform: 'DeepSeek 官网',
model: process.env.GATEWAY_E2E_DEEPSEEK_MODEL || 'deepseek-openai:deepseek-v4-pro',
path: '/v1/chat/completions',
body: chatBody(),
expected: { parameter: 'max_tokens', absent: true, injected: false },
},
{
name: 'DeepSeek 官网 Responses 回退未传上限',
platform: 'DeepSeek 官网',
model: process.env.GATEWAY_E2E_DEEPSEEK_MODEL || 'deepseek-openai:deepseek-v4-pro',
path: '/v1/responses',
body: responsesBody(),
expected: { parameter: 'max_output_tokens', absent: true, injected: false },
},
{
name: '智谱 GLM-5.2 Chat 未传上限',
platform: '智谱AI',
model: process.env.GATEWAY_E2E_ZHIPU_MODEL || 'zhipu-openai:glm-5.2',
path: '/v1/chat/completions',
body: chatBody(),
expected: { parameter: 'max_tokens', absent: true, injected: false },
},
{
name: 'OpenAI GPT-4o Chat 未传上限',
platform: 'OpenAI',
model: process.env.GATEWAY_E2E_OPENAI_MODEL || 'openai:gpt-4o',
path: '/v1/chat/completions',
body: chatBody(),
expected: { parameter: 'max_tokens', absent: true, injected: false },
},
{
name: 'Google Gemini Chat 未传上限',
platform: 'Google Gemini',
model: process.env.GATEWAY_E2E_GEMINI_MODEL || 'gemini:gemini-2.5-pro',
path: '/v1/chat/completions',
body: chatBody(),
expected: { parameter: 'max_tokens', absent: true, injected: false },
},
];
function chatBody(extra = {}) {
return {
messages: [{ role: 'user', content: '这是输出上限链路验证。只回复 OK。' }],
...extra,
};
}
function responsesBody(extra = {}) {
return { input: '这是输出上限链路验证。只回复 OK。', ...extra };
}
function resolveGatewayAPIKey() {
if (process.env.GATEWAY_E2E_API_KEY) {
return { value: process.env.GATEWAY_E2E_API_KEY, source: 'environment', keyId: null };
}
const container = process.env.GATEWAY_E2E_DB_CONTAINER || 'postgres';
const database = process.env.GATEWAY_E2E_DB_NAME || 'easyai_ai_gateway';
const user = process.env.GATEWAY_E2E_DB_USER || 'easyai';
const query = `SELECT key.id::text || E'\\t' || key.key_secret FROM gateway_api_keys key JOIN gateway_wallet_accounts wallet ON wallet.gateway_user_id = key.gateway_user_id AND wallet.status = 'active' WHERE key.deleted_at IS NULL AND key.status = 'active' AND key.key_secret IS NOT NULL AND key.key_secret <> '' AND key.scopes ? 'chat' AND (key.expires_at IS NULL OR key.expires_at > now()) AND (wallet.balance - wallet.frozen_balance) > 0 ORDER BY (wallet.balance - wallet.frozen_balance) DESC, key.created_at DESC LIMIT 1`;
let output = '';
try {
output = execFileSync('docker', ['exec', container, 'psql', '-U', user, '-d', database, '-At', '-c', query], { encoding: 'utf8' }).trim();
} catch {
throw new Error('Unable to load an active chat-scoped Gateway API Key; set GATEWAY_E2E_API_KEY explicitly');
}
const separator = output.indexOf('\t');
if (separator <= 0 || separator === output.length - 1) {
throw new Error('No active chat-scoped Gateway API Key with a positive balance was found');
}
return { keyId: output.slice(0, separator), value: output.slice(separator + 1), source: 'database' };
}
async function fetchText(path, options = {}) {
const response = await fetch(`${baseURL}${path}`, {
...options,
signal: AbortSignal.timeout(timeoutMs),
headers: { Authorization: `Bearer ${authentication.value}`, ...(options.headers || {}) },
});
const text = await response.text();
let body = null;
try {
body = text ? JSON.parse(text) : null;
} catch {
body = { raw: text.slice(0, 2_000) };
}
return { response, body };
}
async function getTask(taskId) {
const { response, body } = await fetchText(`/api/v1/tasks/${taskId}`);
if (!response.ok) throw new Error(`GET task ${taskId} failed ${response.status}: ${JSON.stringify(body)}`);
return body;
}
async function getPreprocessing(taskId) {
const { response, body } = await fetchText(`/api/v1/tasks/${taskId}/param-preprocessing`);
if (!response.ok) throw new Error(`GET preprocessing ${taskId} failed ${response.status}: ${JSON.stringify(body)}`);
return body?.items || [];
}
function successfulAttempt(task) {
const attempts = Array.isArray(task.attempts) ? task.attempts : [];
return attempts.findLast((attempt) => attempt.status === 'succeeded') || attempts.at(-1);
}
function hasOwn(value, key) {
return value != null && Object.prototype.hasOwnProperty.call(value, key);
}
function validateAudit(scenario, task, preprocessing) {
const attempt = successfulAttempt(task);
if (!attempt) throw new Error('task does not contain an upstream attempt');
if (task.simulated || attempt.simulated) throw new Error('request was served by a simulation candidate');
const platformName = String(attempt.metrics?.platformName || task.metrics?.platformName || '');
if (!platformName.includes(scenario.platform)) {
throw new Error(`unexpected platform ${platformName}; expected ${scenario.platform}`);
}
const snapshot = attempt.requestSnapshot || {};
const expected = scenario.expected;
if (expected.absent) {
if (hasOwn(snapshot, expected.parameter)) {
throw new Error(`${expected.parameter} was unexpectedly sent upstream as ${JSON.stringify(snapshot[expected.parameter])}`);
}
} else if (snapshot[expected.parameter] !== expected.value) {
throw new Error(`${expected.parameter}=${JSON.stringify(snapshot[expected.parameter])}; expected ${expected.value}`);
}
for (const [key, value] of Object.entries(expected.preserved || {})) {
if (snapshot[key] !== value) throw new Error(`${key} was not preserved in the upstream snapshot`);
}
const changes = preprocessing.flatMap((item) => item.changes || []);
const outputLimitChanges = changes.filter((change) => change.processor === 'OutputTokenLimitProcessor');
if (expected.injected) {
const matched = outputLimitChanges.some((change) => change.action === 'set' && change.path === expected.parameter && change.after === expected.value);
if (!matched) throw new Error(`missing OutputTokenLimitProcessor audit for ${expected.parameter}=${expected.value}`);
} else if (outputLimitChanges.length > 0) {
throw new Error(`unexpected OutputTokenLimitProcessor audit: ${JSON.stringify(outputLimitChanges)}`);
}
return {
taskId: task.id,
attemptId: attempt.id,
platform: platformName,
provider: attempt.metrics?.provider || task.metrics?.provider || null,
platformModelId: attempt.metrics?.platformModelId || task.metrics?.platformModelId || null,
upstreamProtocol: attempt.metrics?.upstreamProtocol || task.metrics?.upstreamProtocol || null,
upstreamEndpoint: attempt.metrics?.upstreamEndpoint || task.metrics?.upstreamEndpoint || null,
simulated: Boolean(task.simulated || attempt.simulated),
requestParameters: {
max_tokens: hasOwn(snapshot, 'max_tokens') ? snapshot.max_tokens : '(absent)',
max_completion_tokens: hasOwn(snapshot, 'max_completion_tokens') ? snapshot.max_completion_tokens : '(absent)',
max_output_tokens: hasOwn(snapshot, 'max_output_tokens') ? snapshot.max_output_tokens : '(absent)',
},
outputLimitAudit: outputLimitChanges,
usage: task.usage || attempt.usage || null,
};
}
const results = [];
for (const scenario of scenarios) {
const startedAt = Date.now();
let taskId = null;
try {
const requestBody = { model: scenario.model, ...scenario.body };
const { response, body } = await fetchText(scenario.path, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(requestBody),
});
taskId = response.headers.get('x-gateway-task-id');
if (!response.ok) throw new Error(`POST ${scenario.path} failed ${response.status}: ${JSON.stringify(body)}`);
if (!taskId) throw new Error('response is missing X-Gateway-Task-Id');
const [task, preprocessing] = await Promise.all([getTask(taskId), getPreprocessing(taskId)]);
const audit = validateAudit(scenario, task, preprocessing);
results.push({ name: scenario.name, model: scenario.model, path: scenario.path, passed: true, durationMs: Date.now() - startedAt, audit });
process.stderr.write(`PASS ${scenario.name} (${Date.now() - startedAt} ms)\n`);
} catch (error) {
results.push({ name: scenario.name, model: scenario.model, path: scenario.path, passed: false, durationMs: Date.now() - startedAt, taskId, error: error instanceof Error ? error.message : String(error) });
process.stderr.write(`FAIL ${scenario.name}: ${error instanceof Error ? error.message : String(error)}\n`);
}
}
const report = {
ok: results.every((result) => result.passed),
generatedAt: new Date().toISOString(),
baseURL,
authentication: { type: 'gateway_api_key', source: authentication.source, keyId: authentication.keyId },
summary: { total: results.length, passed: results.filter((result) => result.passed).length, failed: results.filter((result) => !result.passed).length },
results,
};
const outputPath = process.env.GATEWAY_E2E_OUTPUT;
if (outputPath) {
await mkdir(dirname(outputPath), { recursive: true });
await writeFile(outputPath, `${JSON.stringify(report, null, 2)}\n`, 'utf8');
}
console.log(JSON.stringify(report, null, 2));
if (!report.ok) process.exitCode = 1;

401
scripts/provision-ci-runner.sh Executable file
View File

@ -0,0 +1,401 @@
#!/bin/sh
set -eu
ROOT=$(CDPATH='' cd -- "$(dirname -- "$0")/.." && pwd)
PREFIX=/opt/easyai-gateway-ci
GITEA_INSTANCE_URL=${GITEA_INSTANCE_URL:-https://git.51easyai.com}
RUNNER_NAME=${RUNNER_NAME:-easyai-gateway-ci-unprivileged-v2}
RUNNER_VOLUME=easyai-gateway-ci-v2-data
RUNNER_CONTAINER=easyai-gateway-ci-v2-runner
LEGACY_BUILDER=${AI_GATEWAY_BUILDX_BUILDER:-easyai-gateway-ci}
MIN_FREE_GIB=${CI_RUNNER_MIN_FREE_GIB:-8}
MIN_POST_INSTALL_FREE_GIB=${CI_RUNNER_MIN_POST_INSTALL_FREE_GIB:-4}
RUNNER_CPUS=2
RUNNER_MEMORY=2g
RUNNER_MEMORY_SWAP=3g
RUNNER_PIDS_LIMIT=1024
GITEA_RUNNER_VERSION=2.0.0
GO_VERSION=1.26.5
GO_SHA256=5c2c3b16caefa1d968a94c1daca04a7ca301a496d9b086e17ad77bb81393f053
NODE_VERSION=24.16.0
NODE_SHA256=d804845d34eddc21dc1092b519d643ef40b1f58ec5dec5c22b1f4bd8fabde6c9
TRIVY_VERSION=0.70.0
TRIVY_SHA256=8b4376d5d6befe5c24d503f10ff136d9e0c49f9127a4279fd110b727929a5aa9
SHELLCHECK_VERSION=0.11.0
SHELLCHECK_SHA256=8c3be12b05d5c177a04c29e3c78ce89ac86f1595681cab149b65b97c4e227198
COMPOSE_VERSION=5.3.1
COMPOSE_SHA256=f9ebc6ebdb19d769b793c245a736caaeb198c62587f13b25c660c13b4987f959
PNPM_VERSION=10.18.1
RUNNER_IMAGE='docker.io/gitea/runner:2.0.0-dind-rootless@sha256:5b7b625ff773d0ee761788c47582503ec1b241fa5b81edebad48a57e663f4f3a'
JOB_IMAGE='docker.io/library/node:24.16.0-bookworm@sha256:40ad9f3064e67d6860b4bc3fe1880b2953934fd6320ada990e45fe0efa6badd7'
RUNNER_IMAGE_SOURCE=${CI_RUNNER_IMAGE_SOURCE:-$RUNNER_IMAGE}
NESTED_DOCKER_REGISTRY_MIRROR=${CI_NESTED_DOCKER_REGISTRY_MIRROR:-}
RUNNER_LABEL="easyai-gateway-ci-unprivileged-v2:docker://$JOB_IMAGE"
fail() {
echo "$*" >&2
exit 1
}
case $MIN_FREE_GIB:$MIN_POST_INSTALL_FREE_GIB in
*[!0-9:]* | :* | *:)
fail "CI runner free-space limits must be whole GiB values"
;;
esac
[ "$MIN_FREE_GIB" -ge 8 ] || fail "CI_RUNNER_MIN_FREE_GIB cannot be lower than 8"
[ "$MIN_POST_INSTALL_FREE_GIB" -ge 4 ] || \
fail "CI_RUNNER_MIN_POST_INSTALL_FREE_GIB cannot be lower than 4"
[ "$(id -u)" -eq 0 ] || fail "run as root"
[ "$(uname -s)-$(uname -m)" = "Linux-x86_64" ] || fail "only Linux x86_64 is supported"
case $RUNNER_IMAGE in
*"/runner:${GITEA_RUNNER_VERSION}-dind-rootless@sha256:"*) ;;
*) fail "RUNNER_IMAGE does not match GITEA_RUNNER_VERSION" ;;
esac
runner_manifest_digest=${RUNNER_IMAGE##*@}
case $RUNNER_IMAGE_SOURCE in
*@"$runner_manifest_digest") ;;
*) fail "CI_RUNNER_IMAGE_SOURCE must use the pinned runner manifest digest" ;;
esac
if [ -n "$NESTED_DOCKER_REGISTRY_MIRROR" ] && \
! printf '%s\n' "$NESTED_DOCKER_REGISTRY_MIRROR" | \
grep -Eq '^https://[A-Za-z0-9.-]+(:[0-9]+)?$'; then
fail "CI_NESTED_DOCKER_REGISTRY_MIRROR must be an HTTPS registry origin"
fi
command -v docker >/dev/null 2>&1 || fail "Docker Engine is required"
docker info >/dev/null 2>&1 || fail "Docker Engine is not reachable"
grep -Fq "\"$RUNNER_LABEL\"" "$ROOT/deploy/ci/act-runner-v2-config.yaml" || \
fail "runner label does not match the pinned job image"
# Fail closed before installing anything. Neither the legacy host runner nor an
# earlier v2 unit may poll for work while its replacement is being prepared.
systemctl disable --now easyai-gateway-act-runner.service >/dev/null 2>&1 || true
systemctl disable --now easyai-gateway-ci-v2-runner.service >/dev/null 2>&1 || true
docker rm --force "$RUNNER_CONTAINER" >/dev/null 2>&1 || true
rm -f /etc/systemd/system/easyai-gateway-act-runner.service
if id easyai-gateway-runner >/dev/null 2>&1; then
if getent group docker >/dev/null 2>&1; then
gpasswd -d easyai-gateway-runner docker >/dev/null 2>&1 || true
fi
if getent group sudo >/dev/null 2>&1; then
gpasswd -d easyai-gateway-runner sudo >/dev/null 2>&1 || true
fi
fi
if id easyai-gateway-ci-v2 >/dev/null 2>&1; then
if getent group docker >/dev/null 2>&1; then
gpasswd -d easyai-gateway-ci-v2 docker >/dev/null 2>&1 || true
fi
if getent group sudo >/dev/null 2>&1; then
gpasswd -d easyai-gateway-ci-v2 sudo >/dev/null 2>&1 || true
fi
fi
for account in easyai-gateway-runner easyai-gateway-ci-v2; do
if id "$account" >/dev/null 2>&1 && \
id -nG "$account" | tr ' ' '\n' | grep -Eq '^(docker|sudo)$'; then
fail "$account must not belong to a privileged group"
fi
done
if ! command -v make >/dev/null 2>&1 || ! command -v gcc >/dev/null 2>&1 || \
! command -v jq >/dev/null 2>&1 || ! command -v curl >/dev/null 2>&1 || \
! command -v xz >/dev/null 2>&1; then
export DEBIAN_FRONTEND=noninteractive
apt-get update
apt-get install -y --no-install-recommends \
build-essential ca-certificates curl git jq perl unzip util-linux xz-utils
fi
docker_root=$(docker info --format '{{.DockerRootDir}}')
[ -n "$docker_root" ] || fail "Docker root directory could not be determined"
require_free_space() {
minimum_gib=$1
phase=$2
available_kib=$(df -Pk "$docker_root" | awk 'NR == 2 { print $4 }')
case $available_kib in
'' | *[!0-9]*) fail "free space could not be determined for $docker_root" ;;
esac
minimum_kib=$((minimum_gib * 1024 * 1024))
if [ "$available_kib" -lt "$minimum_kib" ]; then
echo "$phase requires at least ${minimum_gib} GiB free on the Docker filesystem" >&2
return 1
fi
}
# This builder belonged only to the retired gateway image-building runner. Cap
# its unused cache before adding the nested daemon; never prune global images,
# volumes, or caches owned by another service on this shared production host.
if docker buildx version >/dev/null 2>&1 && \
docker buildx inspect "$LEGACY_BUILDER" >/dev/null 2>&1; then
docker buildx prune --builder "$LEGACY_BUILDER" --force --max-used-space 512mb
fi
require_free_space "$MIN_FREE_GIB" "CI runner installation"
download_verified() {
url=$1
output=$2
checksum=$3
if [ ! -f "$output" ] || ! printf '%s %s\n' "$checksum" "$output" | sha256sum -c - >/dev/null 2>&1; then
rm -f "$output"
curl -fL --retry 5 --retry-delay 2 "$url" -o "$output"
fi
printf '%s %s\n' "$checksum" "$output" | sha256sum -c -
}
install -d -m 0755 "$PREFIX/bin" "$PREFIX/downloads" "$PREFIX/toolchains"
download_verified \
"https://github.com/koalaman/shellcheck/releases/download/v${SHELLCHECK_VERSION}/shellcheck-v${SHELLCHECK_VERSION}.linux.x86_64.tar.xz" \
"$PREFIX/downloads/shellcheck-v${SHELLCHECK_VERSION}.linux.x86_64.tar.xz" \
"$SHELLCHECK_SHA256"
rm -rf "$PREFIX/downloads/shellcheck-v${SHELLCHECK_VERSION}"
tar -xJf "$PREFIX/downloads/shellcheck-v${SHELLCHECK_VERSION}.linux.x86_64.tar.xz" \
-C "$PREFIX/downloads"
install -m 0755 "$PREFIX/downloads/shellcheck-v${SHELLCHECK_VERSION}/shellcheck" "$PREFIX/bin/shellcheck"
download_verified \
"https://github.com/docker/compose/releases/download/v${COMPOSE_VERSION}/docker-compose-linux-x86_64" \
"$PREFIX/downloads/docker-compose-${COMPOSE_VERSION}-linux-x86_64" \
"$COMPOSE_SHA256"
install -m 0755 "$PREFIX/downloads/docker-compose-${COMPOSE_VERSION}-linux-x86_64" "$PREFIX/bin/docker-compose"
download_verified \
"https://go.dev/dl/go${GO_VERSION}.linux-amd64.tar.gz" \
"$PREFIX/downloads/go${GO_VERSION}.linux-amd64.tar.gz" \
"$GO_SHA256"
rm -rf "$PREFIX/toolchains/go"
tar -xzf "$PREFIX/downloads/go${GO_VERSION}.linux-amd64.tar.gz" -C "$PREFIX/toolchains"
download_verified \
"https://nodejs.org/dist/v${NODE_VERSION}/node-v${NODE_VERSION}-linux-x64.tar.xz" \
"$PREFIX/downloads/node-v${NODE_VERSION}-linux-x64.tar.xz" \
"$NODE_SHA256"
rm -rf "$PREFIX/toolchains/node"
mkdir -p "$PREFIX/toolchains/node"
tar -xJf "$PREFIX/downloads/node-v${NODE_VERSION}-linux-x64.tar.xz" \
-C "$PREFIX/toolchains/node" --strip-components=1
PATH="$PREFIX/toolchains/node/bin:$PATH" \
"$PREFIX/toolchains/node/bin/npm" install --global --prefix "$PREFIX/toolchains/node" \
--ignore-scripts "pnpm@${PNPM_VERSION}"
download_verified \
"https://github.com/aquasecurity/trivy/releases/download/v${TRIVY_VERSION}/trivy_${TRIVY_VERSION}_Linux-64bit.tar.gz" \
"$PREFIX/downloads/trivy_${TRIVY_VERSION}_Linux-64bit.tar.gz" \
"$TRIVY_SHA256"
tar -xzf "$PREFIX/downloads/trivy_${TRIVY_VERSION}_Linux-64bit.tar.gz" -C "$PREFIX/bin" trivy
chmod 0755 "$PREFIX/bin/trivy"
GOBIN="$PREFIX/bin" GOPROXY="${GO_MODULE_PROXY:-https://goproxy.cn,direct}" \
"$PREFIX/toolchains/go/bin/go" install golang.org/x/vuln/cmd/govulncheck@v1.6.0
chown -R root:root "$PREFIX"
chmod -R go-w "$PREFIX"
require_free_space "$MIN_FREE_GIB" "runner image pull"
docker pull "$RUNNER_IMAGE_SOURCE"
runner_runtime_image=$(docker image inspect --format '{{.Id}}' "$RUNNER_IMAGE_SOURCE")
printf '%s\n' "$runner_runtime_image" | grep -Eq '^sha256:[0-9a-f]{64}$' || \
fail "pinned runner image did not resolve to an immutable local image ID"
require_free_space "$MIN_POST_INSTALL_FREE_GIB" "completed runner image pull"
docker volume create "$RUNNER_VOLUME" >/dev/null
# The registered runner state and the nested rootless daemon cache share one
# dedicated volume. Persisting the pinned job image lets validation finish
# before registration and avoids racing the first queued workflow for layers.
docker run --rm --pull=never --user 0:0 \
--volume "$RUNNER_VOLUME:/data" \
--entrypoint /bin/sh "$runner_runtime_image" \
-ec 'chown 1000:1000 /data && chmod 0700 /data'
install -d -m 0755 /etc/easyai-gateway-ci-v2
if [ -n "$NESTED_DOCKER_REGISTRY_MIRROR" ]; then
printf '{"data-root":"/data/docker","registry-mirrors":["%s"]}\n' "$NESTED_DOCKER_REGISTRY_MIRROR" \
> /etc/easyai-gateway-ci-v2/daemon.json
else
printf '{"data-root":"/data/docker"}\n' > /etc/easyai-gateway-ci-v2/daemon.json
fi
chmod 0644 /etc/easyai-gateway-ci-v2/daemon.json
# Docker's official rootless DinD baseline is --privileged. Gitea's example
# additionally names an AppArmor profile, but Docker does not create that host
# profile. Enable it only when this daemon proves it can start the pinned image
# with the profile; otherwise leave the option empty.
RUNNER_SECURITY_OPTIONS=
if docker run --rm --pull=never --privileged \
--security-opt apparmor=rootlesskit \
--entrypoint /bin/true "$runner_runtime_image" >/dev/null 2>&1; then
RUNNER_SECURITY_OPTIONS="--security-opt=apparmor=rootlesskit"
elif [ -r /proc/sys/kernel/apparmor_restrict_unprivileged_userns ] && \
[ "$(cat /proc/sys/kernel/apparmor_restrict_unprivileged_userns)" = "1" ]; then
fail "restricted AppArmor user namespaces require the rootlesskit profile (install it with the host Docker packages)"
fi
# Exercise the actual daemon startup before registration. This probe has no
# token, state volume, host bind mount, or socket mount.
PROBE_CONTAINER="easyai-gateway-ci-v2-probe-$$"
cleanup_probe() {
docker rm --force "$PROBE_CONTAINER" >/dev/null 2>&1 || true
}
trap 'cleanup_probe' EXIT
trap 'cleanup_probe; exit 129' HUP
trap 'cleanup_probe; exit 130' INT
trap 'cleanup_probe; exit 143' TERM
if [ -n "$RUNNER_SECURITY_OPTIONS" ]; then
set -- "$RUNNER_SECURITY_OPTIONS"
else
set --
fi
docker run --detach --rm --pull=never \
--name "$PROBE_CONTAINER" --privileged \
--cpus "$RUNNER_CPUS" --memory "$RUNNER_MEMORY" \
--memory-swap "$RUNNER_MEMORY_SWAP" --pids-limit "$RUNNER_PIDS_LIMIT" "$@" \
--volume "$RUNNER_VOLUME:/data" \
--volume /etc/easyai-gateway-ci-v2/daemon.json:/home/rootless/.config/docker/daemon.json:ro \
--volume "$PREFIX:$PREFIX:ro" \
--env DOCKERD_ROOTLESS_ROOTLESSKIT_NET=slirp4netns \
--env DOCKERD_ROOTLESS_ROOTLESSKIT_MTU=65520 \
--env DOCKERD_ROOTLESS_ROOTLESSKIT_FLAGS=--pidns \
--entrypoint dockerd-entrypoint.sh "$runner_runtime_image" >/dev/null
attempt=0
until docker exec "$PROBE_CONTAINER" docker info >/dev/null 2>&1; do
attempt=$((attempt + 1))
if [ "$attempt" -ge 30 ] || \
[ "$(docker inspect --format '{{.State.Running}}' "$PROBE_CONTAINER" 2>/dev/null || true)" != "true" ]; then
docker logs "$PROBE_CONTAINER" 2>&1 || true
fail "pinned rootless Docker-in-Docker probe did not become ready"
fi
sleep 2
done
[ "$(docker exec "$PROBE_CONTAINER" id -u)" = "1000" ] || \
fail "rootless Docker-in-Docker probe is not uid 1000"
[ "$(docker inspect --format '{{.HostConfig.Memory}}:{{.HostConfig.MemorySwap}}:{{.HostConfig.NanoCpus}}:{{.HostConfig.PidsLimit}}' "$PROBE_CONTAINER")" = \
'2147483648:3221225472:2000000000:1024' ] || \
fail "rootless Docker-in-Docker probe does not have the required aggregate resource limits"
docker exec "$PROBE_CONTAINER" docker info --format '{{range .SecurityOptions}}{{println .}}{{end}}' | \
grep -Fq 'name=rootless' || fail "rootless Docker-in-Docker probe is not rootless"
[ "$(docker exec "$PROBE_CONTAINER" docker info --format '{{.DockerRootDir}}')" = /data/docker ] || \
fail "rootless Docker-in-Docker probe is not using its persistent dedicated data root"
# Complete every slow and capability-sensitive validation before registration;
# otherwise a queued workflow can race the installer for the same image layers.
docker exec "$PROBE_CONTAINER" docker pull "$JOB_IMAGE"
outer_sentinel_pid=$(docker exec "$PROBE_CONTAINER" /bin/sh -c \
'sleep 300 >/dev/null 2>&1 & printf "%s\n" "$!"')
case $outer_sentinel_pid in
'' | *[!0-9]*) fail "could not create the outer PID namespace sentinel" ;;
esac
if ! docker exec "$PROBE_CONTAINER" docker run --rm --pull=never \
--pid=host --entrypoint /bin/sh "$JOB_IMAGE" \
-ec 'test ! -e "/proc/$1"' sh "$outer_sentinel_pid"; then
docker exec "$PROBE_CONTAINER" kill "$outer_sentinel_pid" >/dev/null 2>&1 || true
fail "nested --pid=host can see the outer runner PID namespace"
fi
docker exec "$PROBE_CONTAINER" kill "$outer_sentinel_pid" >/dev/null 2>&1 || true
docker exec "$PROBE_CONTAINER" docker run --rm --pull=never \
--volume "$PREFIX:$PREFIX:ro" \
--entrypoint /bin/sh "$JOB_IMAGE" -ec '
export PATH=/opt/easyai-gateway-ci/bin:/opt/easyai-gateway-ci/toolchains/go/bin:/opt/easyai-gateway-ci/toolchains/node/bin:$PATH
go version
node --version
pnpm --version
docker-compose version
shellcheck --version
trivy --version
govulncheck -version
'
cleanup_probe
trap - EXIT HUP INT TERM
install -m 0644 "$ROOT/deploy/ci/act-runner-v2-config.yaml" /etc/easyai-gateway-ci-v2/config.yaml
umask 077
printf 'RUNNER_SECURITY_OPTIONS="%s"\nRUNNER_IMAGE_REF="%s"\n' \
"$RUNNER_SECURITY_OPTIONS" "$runner_runtime_image" \
> /etc/easyai-gateway-ci-v2/runner.env
install -m 0644 "$ROOT/deploy/ci/easyai-gateway-ci-v2-runner.service" \
/etc/systemd/system/easyai-gateway-ci-v2-runner.service
runner_is_registered() {
docker run --rm --pull=never \
--volume "$RUNNER_VOLUME:/data" \
--entrypoint /bin/sh "$runner_runtime_image" \
-ec 'test -s /data/.runner'
}
if ! runner_is_registered; then
[ -n "${RUNNER_REGISTRATION_TOKEN:-}" ] || \
fail "RUNNER_REGISTRATION_TOKEN is required for first registration"
docker rm --force easyai-gateway-ci-v2-register >/dev/null 2>&1 || true
printf '%s\n%s\n%s\n' "$GITEA_INSTANCE_URL" "$RUNNER_REGISTRATION_TOKEN" "$RUNNER_NAME" | \
docker run --rm --interactive --pull=never \
--name easyai-gateway-ci-v2-register \
--volume "$RUNNER_VOLUME:/data" \
--volume /etc/easyai-gateway-ci-v2/config.yaml:/config.yaml:ro \
--env HOME=/data \
--entrypoint /usr/local/bin/gitea-runner \
"$runner_runtime_image" --config /config.yaml register
fi
unset RUNNER_REGISTRATION_TOKEN
docker run --rm --pull=never \
--volume "$RUNNER_VOLUME:/data" \
--entrypoint /bin/sh "$runner_runtime_image" \
-ec 'test -s /data/.runner && chmod 0600 /data/.runner'
RUNNER_VALIDATED=0
cleanup_unvalidated_runner() {
if [ "$RUNNER_VALIDATED" -ne 1 ]; then
systemctl disable --now easyai-gateway-ci-v2-runner.service >/dev/null 2>&1 || true
docker rm --force "$RUNNER_CONTAINER" >/dev/null 2>&1 || true
fi
}
trap 'cleanup_unvalidated_runner' EXIT
trap 'exit 129' HUP
trap 'exit 130' INT
trap 'exit 143' TERM
systemctl daemon-reload
systemctl enable --now easyai-gateway-ci-v2-runner.service
attempt=0
until docker exec "$RUNNER_CONTAINER" docker info >/dev/null 2>&1; do
attempt=$((attempt + 1))
if [ "$attempt" -ge 30 ]; then
systemctl --no-pager --full status easyai-gateway-ci-v2-runner.service || true
docker logs "$RUNNER_CONTAINER" 2>&1 || true
fail "rootless Docker daemon did not become ready"
fi
sleep 2
done
attempt=0
until docker logs "$RUNNER_CONTAINER" 2>&1 | grep -Fq 'declare successfully'; do
attempt=$((attempt + 1))
if [ "$attempt" -ge 30 ] || \
[ "$(docker inspect --format '{{.State.Running}}' "$RUNNER_CONTAINER" 2>/dev/null || true)" != "true" ]; then
docker logs "$RUNNER_CONTAINER" 2>&1 || true
fail "Gitea runner did not declare itself successfully"
fi
sleep 2
done
[ "$(docker inspect --format '{{.Config.User}}' "$RUNNER_CONTAINER")" = "rootless" ] || \
fail "outer runner container is not using the rootless image user"
[ "$(docker inspect --format '{{.HostConfig.Privileged}}' "$RUNNER_CONTAINER")" = "true" ] || \
fail "outer rootless DinD container is not privileged"
[ "$(docker inspect --format '{{.HostConfig.Memory}}:{{.HostConfig.MemorySwap}}:{{.HostConfig.NanoCpus}}:{{.HostConfig.PidsLimit}}' "$RUNNER_CONTAINER")" = \
'2147483648:3221225472:2000000000:1024' ] || \
fail "outer rootless DinD container does not have the required aggregate resource limits"
if docker inspect --format '{{range .Mounts}}{{println .Source}}{{end}}' "$RUNNER_CONTAINER" | \
grep -Eq '/var/run/docker\.sock|/run/docker\.sock'; then
fail "host Docker socket was mounted into the runner"
fi
docker exec "$RUNNER_CONTAINER" docker info --format '{{range .SecurityOptions}}{{println .}}{{end}}' | \
grep -Fq 'name=rootless' || fail "nested Docker daemon is not rootless"
[ "$(docker exec "$RUNNER_CONTAINER" docker info --format '{{.DockerRootDir}}')" = /data/docker ] || \
fail "nested Docker daemon is not using its persistent dedicated data root"
docker exec "$RUNNER_CONTAINER" docker image inspect "$JOB_IMAGE" >/dev/null || \
fail "validated pinned job image is unavailable after runner activation"
if ! require_free_space "$MIN_POST_INSTALL_FREE_GIB" "completed CI runner installation"; then
fail "CI runner was stopped because the post-install disk reserve was not met"
fi
systemctl --no-pager --full status easyai-gateway-ci-v2-runner.service
RUNNER_VALIDATED=1
trap - EXIT HUP INT TERM

109
tests/ci/ci-build-images-test.sh Executable file
View File

@ -0,0 +1,109 @@
#!/usr/bin/env bash
set -euo pipefail
root=$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)
script=$root/scripts/ci-build-images.sh
tmp=$(mktemp -d)
trap 'rm -rf "$tmp"' EXIT
mkdir -p "$tmp/bin"
cat >"$tmp/bin/docker" <<'MOCK'
#!/usr/bin/env bash
set -euo pipefail
printf 'docker %s\n' "$*" >>"$MOCK_LOG"
case "$*" in
'buildx inspect '*|'buildx create '*) exit 0 ;;
'buildx build '*)
if [[ ${MOCK_BUILD_FAIL:-0} == 1 && $* == *'--target web'* ]]; then
exit 21
fi
;;
'buildx prune '*)
[[ ${MOCK_PRUNE_FAIL:-0} == 0 ]] || exit 22
;;
'image rm '*)
[[ ${MOCK_IMAGE_RM_FAIL:-0} == 0 ]] || exit 23
;;
*)
printf 'unexpected docker invocation: %s\n' "$*" >&2
exit 99
;;
esac
MOCK
cat >"$tmp/bin/trivy" <<'MOCK'
#!/usr/bin/env bash
set -euo pipefail
printf 'trivy %s\n' "$*" >>"$MOCK_LOG"
MOCK
chmod +x "$tmp/bin/docker" "$tmp/bin/trivy"
sha=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
registry=registry.example.com/easyai
api_image=$registry/ai-gateway:$sha
web_image=$registry/ai-gateway-web:$sha
run_build() {
env \
PATH="$tmp/bin:$PATH" \
MOCK_LOG="$tmp/calls.log" \
IMAGE_TAG="$sha" \
AI_GATEWAY_IMAGE_REGISTRY="$registry" \
AI_GATEWAY_BUILDX_BUILDER=gateway-test \
AI_GATEWAY_BUILDX_CACHE_LIMIT=2gb \
"$script" "$@"
}
: >"$tmp/calls.log"
run_build
grep -Fq "docker buildx prune --builder gateway-test --force --max-used-space 2gb" "$tmp/calls.log"
grep -Fq "docker image rm $api_image $web_image" "$tmp/calls.log"
grep -Fq 'trivy image --db-repository ghcr.m.daocloud.io/aquasecurity/trivy-db:2' \
"$tmp/calls.log"
: >"$tmp/calls.log"
run_build --keep-images
grep -Fq "docker buildx prune --builder gateway-test --force --max-used-space 2gb" "$tmp/calls.log"
if grep -Fq 'docker image rm ' "$tmp/calls.log"; then
echo '--keep-images must preserve fully built images' >&2
exit 1
fi
: >"$tmp/calls.log"
if MOCK_PRUNE_FAIL=1 run_build; then
echo 'a prune failure must fail an otherwise successful build' >&2
exit 1
fi
: >"$tmp/calls.log"
if MOCK_IMAGE_RM_FAIL=1 run_build; then
echo 'an image cleanup failure must fail an otherwise successful build' >&2
exit 1
fi
: >"$tmp/calls.log"
if MOCK_BUILD_FAIL=1 run_build; then
echo 'a failed image build must fail the script' >&2
exit 1
fi
grep -Fq "docker image rm $api_image $web_image" "$tmp/calls.log"
for invalid_limit in 0gb 2 2GB -1gb '2gb --all'; do
: >"$tmp/calls.log"
if env \
PATH="$tmp/bin:$PATH" \
MOCK_LOG="$tmp/calls.log" \
IMAGE_TAG="$sha" \
AI_GATEWAY_IMAGE_REGISTRY="$registry" \
AI_GATEWAY_BUILDX_CACHE_LIMIT="$invalid_limit" \
"$script" >/dev/null 2>&1; then
printf 'invalid cache limit was accepted: %s\n' "$invalid_limit" >&2
exit 1
fi
if [[ -s $tmp/calls.log ]]; then
printf 'invalid cache limit reached Docker: %s\n' "$invalid_limit" >&2
exit 1
fi
done
echo 'ci_build_images_tests=PASS'

331
tests/ci/migrations-test.sh Executable file
View File

@ -0,0 +1,331 @@
#!/usr/bin/env bash
set -euo pipefail
root=$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)
validator=$root/scripts/ci-validate-migrations.mjs
fixture_root=$(mktemp -d)
trap 'rm -rf "$fixture_root"' EXIT
new_repo() {
local name=$1
local repo=$fixture_root/$name
mkdir -p "$repo/apps/api/migrations"
git -C "$repo" init -q
git -C "$repo" config user.name 'CI Migration Test'
git -C "$repo" config user.email 'ci-migration-test@example.invalid'
printf 'CREATE TABLE accounts (id bigint PRIMARY KEY);\n' > \
"$repo/apps/api/migrations/0001_init.sql"
git -C "$repo" add apps/api/migrations/0001_init.sql
git -C "$repo" commit -qm baseline
mkdir -p "$repo/deploy/ci"
git -C "$repo" rev-parse HEAD > \
"$repo/deploy/ci/production-migration-base"
printf '%s\n' "$repo"
}
commit_all() {
local repo=$1
local message=$2
git -C "$repo" add -A
git -C "$repo" commit -qm "$message"
}
expect_pass() {
local repo=$1
local base=$2
local immutable_base=${3:-}
(
cd "$repo"
if [[ -n $immutable_base ]]; then
node "$validator" "$base" "$immutable_base"
else
node "$validator" "$base"
fi
)
}
expect_fail() {
local repo=$1
local base=$2
local expected=$3
local immutable_base=${4:-}
local output status
if [[ -n $immutable_base ]]; then
set +e
output=$(cd "$repo" && node "$validator" "$base" "$immutable_base" 2>&1)
status=$?
set -e
else
set +e
output=$(cd "$repo" && node "$validator" "$base" 2>&1)
status=$?
set -e
fi
if [[ $status -eq 0 ]]; then
printf 'migration validator unexpectedly passed: %s\n' "$expected" >&2
exit 1
fi
grep -Fq "$expected" <<<"$output" || {
printf 'missing expected migration failure %q in:\n%s\n' "$expected" "$output" >&2
exit 1
}
}
repo=$(new_repo safe)
base=$(git -C "$repo" rev-parse HEAD)
cat >"$repo/apps/api/migrations/0002_expand_accounts.sql" <<'SQL'
-- A comment mentioning DROP TABLE must not trigger the gate.
ALTER TABLE accounts ADD COLUMN display_name text;
CREATE TABLE audit_events (id bigint PRIMARY KEY, note text);
INSERT INTO audit_events (id, note) VALUES (1, 'DROP TABLE is documentation');
UPDATE accounts SET display_name = 'ready' WHERE display_name IS NULL;
SQL
commit_all "$repo" safe
expect_pass "$repo" "$base"
repo=$(new_repo drop)
base=$(git -C "$repo" rev-parse HEAD)
printf 'DROP\nTABLE accounts;\n' >"$repo/apps/api/migrations/0002_drop.sql"
commit_all "$repo" drop
expect_fail "$repo" "$base" 'destructive DROP operation'
repo=$(new_repo delete)
base=$(git -C "$repo" rev-parse HEAD)
printf 'DELETE FROM accounts;\n' >"$repo/apps/api/migrations/0002_delete.sql"
commit_all "$repo" delete
expect_fail "$repo" "$base" 'DELETE FROM operation'
repo=$(new_repo incompatible_alter)
base=$(git -C "$repo" rev-parse HEAD)
cat >"$repo/apps/api/migrations/0002_alter.sql" <<'SQL'
ALTER TABLE accounts ADD COLUMN external_id text NOT NULL;
ALTER TABLE accounts ALTER COLUMN id TYPE numeric;
SQL
commit_all "$repo" alter
expect_fail "$repo" "$base" 'non-null column addition'
expect_fail "$repo" "$base" 'column type change'
repo=$(new_repo dynamic_sql)
base=$(git -C "$repo" rev-parse HEAD)
cat >"$repo/apps/api/migrations/0002_dynamic.sql" <<'SQL'
DO $$
BEGIN
EXECUTE 'DROP ' || 'TABLE accounts';
END
$$;
SQL
commit_all "$repo" dynamic
expect_fail "$repo" "$base" 'dynamic SQL execution'
repo=$(new_repo escape_string)
base=$(git -C "$repo" rev-parse HEAD)
cat >"$repo/apps/api/migrations/0002_escape.sql" <<'SQL'
SELECT E'foo\'bar'; DROP TABLE accounts; --';
SQL
commit_all "$repo" escape
expect_fail "$repo" "$base" 'PostgreSQL escape/unicode strings are not allowed'
repo=$(new_repo string_semantics_override)
base=$(git -C "$repo" rev-parse HEAD)
printf 'SET standard_conforming_strings = off;\n' > \
"$repo/apps/api/migrations/0002_string_mode.sql"
commit_all "$repo" string_mode
expect_fail "$repo" "$base" 'SQL string semantics override'
repo=$(new_repo transaction_control)
base=$(git -C "$repo" rev-parse HEAD)
cat >"$repo/apps/api/migrations/0002_commit.sql" <<'SQL'
ALTER TABLE accounts ADD COLUMN display_name text;
COMMIT;
UPDATE accounts SET display_name = 'partially committed';
SQL
commit_all "$repo" transaction_control
expect_fail "$repo" "$base" 'transaction control operation'
repo=$(new_repo bare_end_transaction)
base=$(git -C "$repo" rev-parse HEAD)
cat >"$repo/apps/api/migrations/0002_end.sql" <<'SQL'
ALTER TABLE accounts ADD COLUMN display_name text;
END;
UPDATE accounts SET display_name = 'partially committed';
SQL
commit_all "$repo" bare_end_transaction
expect_fail "$repo" "$base" 'transaction control operation'
repo=$(new_repo plpgsql_block_end)
base=$(git -C "$repo" rev-parse HEAD)
cat >"$repo/apps/api/migrations/0002_function.sql" <<'SQL'
CREATE FUNCTION account_count() RETURNS bigint
LANGUAGE plpgsql AS $$
BEGIN
RETURN (SELECT count(*) FROM accounts);
END;
$$;
SQL
commit_all "$repo" plpgsql_block_end
expect_fail "$repo" "$base" 'procedural SQL body'
repo=$(new_repo ordinary_string_procedural_body)
base=$(git -C "$repo" rev-parse HEAD)
cat >"$repo/apps/api/migrations/0002_do_string.sql" <<'SQL'
DO LANGUAGE plpgsql 'BEGIN DROP TABLE accounts; END';
SQL
commit_all "$repo" ordinary_string_procedural_body
expect_fail "$repo" "$base" 'procedural SQL body'
repo=$(new_repo ordinary_string_boundary)
base=$(git -C "$repo" rev-parse HEAD)
cat >"$repo/apps/api/migrations/0002_string_boundary.sql" <<'SQL'
SELECT '\'; DROP TABLE accounts; --';
SQL
commit_all "$repo" ordinary_string
expect_fail "$repo" "$base" 'destructive DROP operation'
repo=$(new_repo unicode_string)
base=$(git -C "$repo" rev-parse HEAD)
printf "SELECT U&'d\\0061ta';\n" >"$repo/apps/api/migrations/0002_unicode.sql"
commit_all "$repo" unicode
expect_fail "$repo" "$base" 'PostgreSQL escape/unicode strings are not allowed'
repo=$(new_repo merge_delete)
base=$(git -C "$repo" rev-parse HEAD)
cat >"$repo/apps/api/migrations/0002_merge.sql" <<'SQL'
MERGE INTO accounts USING stale_accounts ON accounts.id = stale_accounts.id
WHEN MATCHED THEN DELETE;
SQL
commit_all "$repo" merge
expect_fail "$repo" "$base" 'MERGE operation'
repo=$(new_repo replace_view)
base=$(git -C "$repo" rev-parse HEAD)
printf 'CREATE OR REPLACE VIEW active_accounts AS SELECT id FROM accounts;\n' > \
"$repo/apps/api/migrations/0002_replace.sql"
commit_all "$repo" replace
expect_fail "$repo" "$base" 'CREATE OR REPLACE operation'
repo=$(new_repo rename_function)
base=$(git -C "$repo" rev-parse HEAD)
printf 'ALTER FUNCTION calculate_total() RENAME TO calculate_total_legacy;\n' > \
"$repo/apps/api/migrations/0002_rename.sql"
commit_all "$repo" rename
expect_fail "$repo" "$base" 'object or column rename'
repo=$(new_repo set_schema)
base=$(git -C "$repo" rev-parse HEAD)
printf 'ALTER TABLE accounts SET SCHEMA archive;\n' > \
"$repo/apps/api/migrations/0002_schema.sql"
commit_all "$repo" schema
expect_fail "$repo" "$base" 'SET SCHEMA operation'
repo=$(new_repo drop_domain)
base=$(git -C "$repo" rev-parse HEAD)
printf 'DROP DOMAIN account_code CASCADE;\n' > \
"$repo/apps/api/migrations/0002_drop_domain.sql"
commit_all "$repo" drop_domain
expect_fail "$repo" "$base" 'destructive DROP operation'
repo=$(new_repo immutable)
base=$(git -C "$repo" rev-parse HEAD)
printf '\n-- retroactive edit\n' >>"$repo/apps/api/migrations/0001_init.sql"
commit_all "$repo" edit
expect_fail "$repo" "$base" 'applied migrations are immutable (status M)'
repo=$(new_repo immutable_after_baseline)
base=$(git -C "$repo" rev-parse HEAD)
printf 'ALTER TABLE accounts ADD COLUMN nickname text;\n' > \
"$repo/apps/api/migrations/0002_nickname.sql"
commit_all "$repo" add
immutable_base=$(git -C "$repo" rev-parse HEAD)
printf '\nUPDATE accounts SET nickname = NULL;\n' >> \
"$repo/apps/api/migrations/0002_nickname.sql"
commit_all "$repo" modify
output=$(
cd "$repo"
node "$validator" "$base" "$immutable_base" 2>&1 || true
)
grep -Fq 'migration present on main is immutable (status M)' <<<"$output" || {
printf 'stale production baseline did not preserve main migration immutability:\n%s\n' \
"$output" >&2
exit 1
}
repo=$(new_repo filename)
base=$(git -C "$repo" rev-parse HEAD)
printf 'SELECT 1;\n' >"$repo/apps/api/migrations/next.SQL"
commit_all "$repo" filename
expect_fail "$repo" "$base" 'new migration must use NNNN_lowercase_name.sql'
repo=$(new_repo ordering)
base=$(git -C "$repo" rev-parse HEAD)
printf 'SELECT 1;\n' >"$repo/apps/api/migrations/0000_late.sql"
commit_all "$repo" ordering
expect_fail "$repo" "$base" 'new migration name must sort after 0001_init.sql'
repo=$(new_repo stale_baseline)
base=$(git -C "$repo" rev-parse HEAD)
printf 'ALTER TABLE accounts ADD COLUMN nickname text;\n' > \
"$repo/apps/api/migrations/0002_nickname.sql"
commit_all "$repo" main_migration
immutable_base=$(git -C "$repo" rev-parse HEAD)
printf 'ordinary code change\n' >"$repo/README.md"
commit_all "$repo" code_only
expect_pass "$repo" "$base" "$immutable_base"
repo=$(new_repo baseline_advance)
production_base=$(git -C "$repo" rev-parse HEAD)
mkdir -p "$repo/deploy/ci"
printf '%s\n' "$production_base" >"$repo/deploy/ci/production-migration-base"
commit_all "$repo" baseline_file
immutable_base=$(git -C "$repo" rev-parse HEAD)
git -C "$repo" switch -q -c release-baseline-update "$immutable_base"
printf '%s\n' "$immutable_base" >"$repo/deploy/ci/production-migration-base"
commit_all "$repo" valid_baseline_advance
expect_pass "$repo" "$immutable_base" "$immutable_base"
git -C "$repo" switch -q -c malicious-baseline "$immutable_base"
printf 'DROP TABLE accounts;\n' >"$repo/apps/api/migrations/0002_drop.sql"
commit_all "$repo" hidden_destructive_migration
hidden_sha=$(git -C "$repo" rev-parse HEAD)
printf '%s\n' "$hidden_sha" >"$repo/deploy/ci/production-migration-base"
commit_all "$repo" hide_migration_in_baseline
expect_fail "$repo" "$hidden_sha" \
'production migration baseline must belong to the immutable event base history' \
"$immutable_base"
repo=$(new_repo nested)
base=$(git -C "$repo" rev-parse HEAD)
mkdir -p "$repo/apps/api/migrations/archive"
printf 'SELECT 1;\n' >"$repo/apps/api/migrations/archive/9999_hidden.sql"
commit_all "$repo" nested
expect_fail "$repo" "$base" 'new migration must use NNNN_lowercase_name.sql'
repo=$(new_repo symlink)
base=$(git -C "$repo" rev-parse HEAD)
printf 'SELECT 1;\n' >"$repo/outside.sql"
ln -s ../../../outside.sql "$repo/apps/api/migrations/0002_symlink.sql"
commit_all "$repo" symlink
expect_fail "$repo" "$base" 'new migration must be a mode 100644 regular file'
repo=$(new_repo baseline_symlink)
base=$(git -C "$repo" rev-parse HEAD)
printf '%s\n' "$base" >"$repo/baseline-target"
rm "$repo/deploy/ci/production-migration-base"
ln -s ../../baseline-target "$repo/deploy/ci/production-migration-base"
commit_all "$repo" baseline_symlink
expect_fail "$repo" "$base" \
'production migration baseline must be a mode 100644 regular file'
repo=$(new_repo ancestry)
base=$(git -C "$repo" rev-parse HEAD)
git -C "$repo" switch -q --orphan unrelated
printf 'unrelated\n' >"$repo/unrelated"
git -C "$repo" add unrelated
git -C "$repo" commit -qm unrelated
expect_fail "$repo" "$base" 'production migration baseline is not an ancestor of HEAD'
repo=$(new_repo invalid_sha)
expect_fail "$repo" deadbeef 'must be a full lowercase commit SHA'
echo 'migration_tests=PASS'

323
tests/ci/pipeline-test.sh Executable file
View File

@ -0,0 +1,323 @@
#!/usr/bin/env bash
# shellcheck disable=SC2016 # Assertions intentionally match literal workflow variables.
set -euo pipefail
root=$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)
workflow=$root/.gitea/workflows/ci.yml
release_workflow=$root/.gitea/workflows/release-ci.yml
runner_service=$root/deploy/ci/easyai-gateway-ci-v2-runner.service
runner_config=$root/deploy/ci/act-runner-v2-config.yaml
provision=$root/scripts/provision-ci-runner.sh
build_images=$root/scripts/ci-build-images.sh
validate_semver=$root/scripts/ci-validate-semver.sh
validate_migrations=$root/scripts/ci-validate-migrations.mjs
build_images_test=$root/tests/ci/ci-build-images-test.sh
migrations_test=$root/tests/ci/migrations-test.sh
migration_base=$root/deploy/ci/production-migration-base
adr=$root/docs/decisions/001-production-cicd.md
runbook=$root/docs/runbooks/production-ci-cd.md
migrator=$root/apps/api/cmd/migrate/main.go
for file in "$workflow" "$release_workflow" "$runner_service" "$runner_config" "$provision" "$build_images" "$validate_semver" "$validate_migrations" "$build_images_test" "$migrations_test" "$migration_base" "$adr" "$runbook" "$migrator"; do
[[ -f $file ]] || {
printf 'missing CI/CD file: %s\n' "$file" >&2
exit 1
}
done
if [[ $(wc -l <"$migration_base") -ne 1 ]]; then
echo 'production migration baseline must contain exactly one line' >&2
exit 1
fi
grep -Fq 'SET standard_conforming_strings = on' "$migrator" || {
echo 'database migrator does not pin standard SQL string semantics' >&2
exit 1
}
if ! grep -Eq '^[0-9a-f]{40}$' "$migration_base"; then
echo 'production migration baseline must be a full lowercase SHA' >&2
exit 1
fi
grep -q '^name: ci$' "$workflow"
grep -q '^ push:$' "$workflow"
grep -q '^ branches: \[main\]$' "$workflow"
grep -q '^ pull_request:$' "$workflow"
grep -q '^ verify:$' "$workflow"
grep -Fq 'git checkout --detach "$CI_SHA"' "$workflow"
grep -Fq 'test "$(git rev-parse HEAD)" = "$CI_SHA"' "$workflow"
if grep -Fq 'git checkout --detach FETCH_HEAD' "$workflow"; then
echo 'main/PR CI must not checkout mutable FETCH_HEAD after comparison fetches' >&2
exit 1
fi
if grep -Eq "^[[:space:]]+tags:|Verify release tag ancestry" "$workflow" || \
grep -Fq './scripts/ci-validate-semver.sh "$tag_name"' "$workflow"; then
echo 'main/PR CI must not share the release-tag context' >&2
exit 1
fi
grep -q '^name: release-ci$' "$release_workflow"
grep -q '^ push:$' "$release_workflow"
grep -q "^ tags: \['v\*'\]$" "$release_workflow"
grep -q '^ verify-tag:$' "$release_workflow"
grep -q '^ - name: Verify release tag ancestry$' "$release_workflow"
grep -Fq './scripts/ci-validate-semver.sh "$tag_name"' "$release_workflow"
grep -Fq 'git merge-base --is-ancestor "$CI_SHA" refs/remotes/origin/main' "$release_workflow"
if grep -Eq 'branches:|pull_request:' "$release_workflow"; then
echo 'release CI must be a tag-only workflow/context' >&2
exit 1
fi
for quality_workflow in "$workflow" "$release_workflow"; do
grep -q '^ runs-on: easyai-gateway-ci-unprivileged-v2$' "$quality_workflow"
grep -q '^ - name: Checkout without external Actions$' "$quality_workflow"
if grep -q -- '--depth=' "$quality_workflow"; then
echo 'quality verification must not use a shallow checkout' >&2
exit 1
fi
grep -Fq 'test ! -f .git/shallow' "$quality_workflow"
grep -Fq './tests/ci/ci-build-images-test.sh' "$quality_workflow"
grep -Fq './tests/ci/migrations-test.sh' "$quality_workflow"
grep -Fq './tests/ci/pipeline-test.sh' "$quality_workflow"
grep -Fq './tests/ci/semver-test.sh' "$quality_workflow"
grep -Fq 'docker-compose version' "$quality_workflow"
grep -Fq 'docker-compose -f docker-compose.yml config --quiet' "$quality_workflow"
if grep -Fq 'docker compose' "$quality_workflow"; then
echo 'job container must use the read-only standalone Compose binary' >&2
exit 1
fi
for forbidden in \
'sudo' \
'/usr/local/sbin/easyai-ai-gateway-release' \
'docker version' \
'docker buildx' \
'./scripts/ci-build-images.sh --keep-images' \
'Deploy verified release to Production'; do
if grep -Fq "$forbidden" "$quality_workflow"; then
printf 'unprivileged workflow contains forbidden capability: %s\n' "$forbidden" >&2
exit 1
fi
done
if grep -Eq '^[[:space:]]+\./scripts/ci-build-images\.sh([[:space:]]|$)' "$quality_workflow"; then
echo 'unprivileged workflow must not build container images' >&2
exit 1
fi
for gate in \
'scripts/ci-validate-migrations.mjs' \
'gofmt -l' \
'go vet ./...' \
'go test ./...' \
'pnpm install --frozen-lockfile' \
'pnpm lint' \
'pnpm test' \
'pnpm build' \
'pnpm audit --audit-level high' \
'docker-compose -f docker-compose.yml config --quiet' \
'govulncheck ./...' \
'trivy fs'; do
grep -Fq "$gate" "$quality_workflow" || {
printf '%s is missing quality gate: %s\n' "$quality_workflow" "$gate" >&2
exit 1
}
done
grep -Fq 'TRIVY_DB_REPOSITORY: ghcr.m.daocloud.io/aquasecurity/trivy-db:2' \
"$quality_workflow" || {
printf '%s does not pin the reachable Trivy vulnerability DB mirror\n' \
"$quality_workflow" >&2
exit 1
}
grep -Fq 'production_base=$(cat deploy/ci/production-migration-base)' \
"$quality_workflow" || {
printf '%s does not read the versioned production migration baseline\n' \
"$quality_workflow" >&2
exit 1
}
done
if [[ $(sed -n '/^ - name: Verify Go formatting$/,$p' "$workflow") != \
"$(sed -n '/^ - name: Verify Go formatting$/,$p' "$release_workflow")" ]]; then
echo 'main/PR and release-tag workflows must have identical quality gates' >&2
exit 1
fi
grep -Fq 'CI_EVENT_BEFORE: ${{ github.event.before }}' "$workflow"
grep -Fq 'CI_PR_BASE_SHA: ${{ github.event.pull_request.base.sha }}' "$workflow"
grep -Fq 'git merge-base --is-ancestor "$immutable_base" HEAD' "$workflow"
grep -Fq '"$production_base" "$immutable_base"' "$workflow"
grep -Fq 'node ./scripts/ci-validate-migrations.mjs "$production_base"' \
"$release_workflow"
runner_image='docker.io/gitea/runner:2.0.0-dind-rootless@sha256:5b7b625ff773d0ee761788c47582503ec1b241fa5b81edebad48a57e663f4f3a'
job_image='docker.io/library/node:24.16.0-bookworm@sha256:40ad9f3064e67d6860b4bc3fe1880b2953934fd6320ada990e45fe0efa6badd7'
grep -q '^User=root$' "$runner_service"
grep -q '^Group=root$' "$runner_service"
grep -q '^NoNewPrivileges=true$' "$runner_service"
grep -q '^ProtectSystem=strict$' "$runner_service"
grep -q '^ProtectHome=true$' "$runner_service"
grep -q '^CapabilityBoundingSet=$' "$runner_service"
grep -Fq 'Requires=docker.service' "$runner_service"
grep -Fq -- "--pull=never" "$runner_service"
grep -Fq -- "--privileged" "$runner_service"
grep -Fq -- '--pids-limit 1024' "$runner_service"
grep -Fq -- '--cpus 2' "$runner_service"
grep -Fq -- '--memory 2g' "$runner_service"
grep -Fq -- '--memory-swap 3g' "$runner_service"
grep -Fq -- '--env DOCKERD_ROOTLESS_ROOTLESSKIT_FLAGS=--pidns' "$runner_service"
grep -Fq 'EnvironmentFile=-/etc/easyai-gateway-ci-v2/runner.env' "$runner_service"
grep -Fq '$RUNNER_SECURITY_OPTIONS' "$runner_service"
grep -Fq -- "--volume easyai-gateway-ci-v2-data:/data" "$runner_service"
grep -Fq -- "--volume /etc/easyai-gateway-ci-v2/config.yaml:/config.yaml:ro" "$runner_service"
grep -Fq -- "--volume /etc/easyai-gateway-ci-v2/daemon.json:/home/rootless/.config/docker/daemon.json:ro" "$runner_service"
grep -Fq -- "--volume /opt/easyai-gateway-ci:/opt/easyai-gateway-ci:ro" "$runner_service"
grep -Fq 'Environment=RUNNER_IMAGE_REF=' "$runner_service"
grep -Fq '$RUNNER_IMAGE_REF' "$runner_service"
if grep -Eq 'GITEA_RUNNER_REGISTRATION_TOKEN|/var/run/docker\.sock|/run/docker\.sock' "$runner_service"; then
echo 'persistent runner service exposes a registration token or host Docker socket' >&2
exit 1
fi
if grep -Fq 'apparmor=rootlesskit' "$runner_service"; then
echo 'runner service must not hard-code an AppArmor profile that may be absent' >&2
exit 1
fi
grep -Fq "easyai-gateway-ci-unprivileged-v2:docker://$job_image" "$runner_config"
if grep -Fq ':host' "$runner_config"; then
echo 'CI runner must never use the host executor' >&2
exit 1
fi
grep -q '^ capacity: 1$' "$runner_config"
grep -q '^ file: /data/.runner$' "$runner_config"
grep -q '^ docker_host: "-"$' "$runner_config"
grep -q '^ privileged: false$' "$runner_config"
grep -q '^ require_docker: true$' "$runner_config"
grep -q '^ bind_workdir: false$' "$runner_config"
grep -Fq ' options: "--volume /opt/easyai-gateway-ci:/opt/easyai-gateway-ci:ro"' "$runner_config"
grep -q '^ valid_volumes:$' "$runner_config"
grep -q '^ - "/opt/easyai-gateway-ci"$' "$runner_config"
if awk '
/^ valid_volumes:$/ { in_volumes=1; next }
in_volumes && /^ - / { count++; next }
in_volumes && /^ [A-Za-z_]+:/ { in_volumes=0 }
END { exit count == 1 ? 0 : 1 }
' "$runner_config"; then
:
else
echo 'runner must allow exactly one workflow volume source' >&2
exit 1
fi
if grep -Eq '/var/run/docker\.sock|/run/docker\.sock' "$runner_config"; then
echo 'job configuration must not expose a Docker socket' >&2
exit 1
fi
if grep -Eq 'apparmor=unconfined|sysctl .*(apparmor_restrict_unprivileged_userns)' "$runner_service" "$runner_config" "$provision"; then
echo 'runner must not disable AppArmor isolation or its user-namespace restriction' >&2
exit 1
fi
grep -q '^GITEA_RUNNER_VERSION=2.0.0$' "$provision"
grep -q '^GO_VERSION=1.26.5$' "$provision"
grep -q '^NODE_VERSION=24.16.0$' "$provision"
grep -q '^TRIVY_VERSION=0.70.0$' "$provision"
grep -q '^PREFIX=/opt/easyai-gateway-ci$' "$provision"
grep -q '^RUNNER_VOLUME=easyai-gateway-ci-v2-data$' "$provision"
grep -q '^SHELLCHECK_VERSION=0.11.0$' "$provision"
grep -q '^SHELLCHECK_SHA256=8c3be12b05d5c177a04c29e3c78ce89ac86f1595681cab149b65b97c4e227198$' "$provision"
grep -q '^COMPOSE_VERSION=5.3.1$' "$provision"
grep -q '^COMPOSE_SHA256=f9ebc6ebdb19d769b793c245a736caaeb198c62587f13b25c660c13b4987f959$' "$provision"
grep -Fq 'RUNNER_NAME=${RUNNER_NAME:-easyai-gateway-ci-unprivileged-v2}' "$provision"
grep -Fq "RUNNER_IMAGE='$runner_image'" "$provision"
grep -Fq 'RUNNER_IMAGE_SOURCE=${CI_RUNNER_IMAGE_SOURCE:-$RUNNER_IMAGE}' "$provision"
grep -Fq 'runner_manifest_digest=${RUNNER_IMAGE##*@}' "$provision"
grep -Fq 'CI_RUNNER_IMAGE_SOURCE must use the pinned runner manifest digest' "$provision"
grep -Fq 'runner_runtime_image=$(docker image inspect' "$provision"
grep -Fq 'RUNNER_IMAGE_REF="%s"' "$provision"
grep -Fq "JOB_IMAGE='$job_image'" "$provision"
grep -Fq 'RUNNER_LABEL="easyai-gateway-ci-unprivileged-v2:docker://$JOB_IMAGE"' "$provision"
grep -Fq 'docker volume create "$RUNNER_VOLUME"' "$provision"
grep -Fq '"data-root":"/data/docker"' "$provision"
grep -Fq -- '--security-opt apparmor=rootlesskit' "$provision"
grep -Fq 'RUNNER_SECURITY_OPTIONS="--security-opt=apparmor=rootlesskit"' "$provision"
grep -Fq 'RUNNER_SECURITY_OPTIONS=' "$provision"
grep -Fq '/proc/sys/kernel/apparmor_restrict_unprivileged_userns' "$provision"
grep -Fq -- '--entrypoint dockerd-entrypoint.sh "$runner_runtime_image"' "$provision"
grep -Fq '/etc/easyai-gateway-ci-v2/daemon.json:/home/rootless/.config/docker/daemon.json:ro' "$provision"
grep -Fq 'CI_NESTED_DOCKER_REGISTRY_MIRROR must be an HTTPS registry origin' "$provision"
grep -Fq 'PROBE_CONTAINER="easyai-gateway-ci-v2-probe-$$"' "$provision"
grep -Fq -- '--pids-limit "$RUNNER_PIDS_LIMIT"' "$provision"
grep -Fq -- '--cpus "$RUNNER_CPUS"' "$provision"
grep -Fq -- '--memory "$RUNNER_MEMORY"' "$provision"
grep -Fq -- '--memory-swap "$RUNNER_MEMORY_SWAP"' "$provision"
grep -Fq "'2147483648:3221225472:2000000000:1024'" "$provision"
grep -Fq -- '--entrypoint /usr/local/bin/gitea-runner' "$provision"
grep -Fq 'shellcheck-v${SHELLCHECK_VERSION}.linux.x86_64.tar.xz' "$provision"
grep -Fq 'docker-compose-linux-x86_64' "$provision"
grep -Fq 'install -m 0755 "$PREFIX/downloads/shellcheck-v${SHELLCHECK_VERSION}/shellcheck" "$PREFIX/bin/shellcheck"' "$provision"
grep -Fq 'install -m 0755 "$PREFIX/downloads/docker-compose-${COMPOSE_VERSION}-linux-x86_64" "$PREFIX/bin/docker-compose"' "$provision"
grep -Fq 'PATH="$PREFIX/toolchains/node/bin:$PATH"' "$provision"
grep -Fq 'gpasswd -d easyai-gateway-ci-v2 docker' "$provision"
grep -Fq 'gpasswd -d easyai-gateway-ci-v2 sudo' "$provision"
if grep -Fq 'usermod -aG docker' "$provision"; then
echo 'unprivileged runner must never join the Docker group' >&2
exit 1
fi
grep -Fq 'systemctl disable --now easyai-gateway-act-runner.service' "$provision"
grep -Fq 'systemctl disable --now easyai-gateway-ci-v2-runner.service' "$provision"
grep -Fq 'RUNNER_REGISTRATION_TOKEN is required for first registration' "$provision"
grep -Fq 'printf '\''%s\n%s\n%s\n'\'' "$GITEA_INSTANCE_URL" "$RUNNER_REGISTRATION_TOKEN" "$RUNNER_NAME"' "$provision"
if grep -Fq -- '--token "$RUNNER_REGISTRATION_TOKEN"' "$provision"; then
echo 'registration token must not be exposed in a host-visible process argv' >&2
exit 1
fi
grep -Fq "grep -Fq 'name=rootless'" "$provision"
grep -Fq "grep -Fq 'declare successfully'" "$provision"
grep -Fq 'docker buildx prune --builder "$LEGACY_BUILDER" --force --max-used-space 512mb' "$provision"
grep -Fq 'require_free_space "$MIN_FREE_GIB" "runner image pull"' "$provision"
grep -Fq 'require_free_space "$MIN_POST_INSTALL_FREE_GIB" "completed CI runner installation"' "$provision"
grep -Fq 'CI_RUNNER_MIN_FREE_GIB cannot be lower than 8' "$provision"
grep -Fq 'CI_RUNNER_MIN_POST_INSTALL_FREE_GIB cannot be lower than 4' "$provision"
grep -Fq 'docker exec "$PROBE_CONTAINER" docker pull "$JOB_IMAGE"' "$provision"
grep -Fq 'docker exec "$PROBE_CONTAINER" docker run --rm --pull=never' "$provision"
grep -Fq -- '--volume "$RUNNER_VOLUME:/data"' "$provision"
grep -Fq -- '--volume "$PREFIX:$PREFIX:ro"' "$provision"
probe_pull_line=$(grep -nF 'docker exec "$PROBE_CONTAINER" docker pull "$JOB_IMAGE"' "$provision" | cut -d: -f1)
registration_line=$(grep -nF 'if ! runner_is_registered; then' "$provision" | cut -d: -f1)
[[ -n $probe_pull_line && -n $registration_line && $probe_pull_line -lt $registration_line ]] || {
echo 'pinned job image and isolation probes must complete before runner registration' >&2
exit 1
}
grep -Fq 'nested --pid=host can see the outer runner PID namespace' "$provision"
grep -Fq 'chown -R root:root "$PREFIX"' "$provision"
grep -Fq 'chmod -R go-w "$PREFIX"' "$provision"
if grep -Eq 'SHELLCHECK_BIN|COMPOSE_PLUGIN|command -v shellcheck|docker compose version' "$provision"; then
echo 'runner provisioning must use checksum-pinned static CI tools, not host copies' >&2
exit 1
fi
if grep -Eq 'docker (system|builder|image|volume) prune' "$provision"; then
echo 'runner provisioning must not globally prune shared Docker state' >&2
exit 1
fi
grep -Fq 'root-owned dispatcher' "$adr"
grep -Fq 'release-ci / verify-tag (push)' "$adr"
grep -Fq '来自 Fork 的 PR 必须先由维护者检查工作流变更并在 Gitea 中批准' "$adr"
grep -Fq 'rootless DinD 不是 VM 沙箱' "$runbook"
grep -Fq '同时等待 `ci / verify (push)` 与本次新产生的 `release-ci / verify-tag (push)`' "$runbook"
grep -Fq '不得执行 Tag checkout 中的' "$runbook"
grep -Fq 'docker buildx build --builder "$builder"' "$build_images"
grep -q -- '--target api' "$build_images"
grep -q -- '--target web' "$build_images"
grep -Fq 'docker buildx prune --builder "$builder" --force --max-used-space "$cache_limit"' "$build_images"
grep -Fq 'trivy image' "$build_images"
grep -Fq 'docker image rm "$api_image" "$web_image"' "$build_images"
grep -Fq 'AI_GATEWAY_BUILDX_CACHE_LIMIT has an invalid format' "$build_images"
if grep -En '(password|secret|token):[[:space:]]+[^$<{]' "$workflow" "$release_workflow"; then
echo 'workflow contains a literal credential' >&2
exit 1
fi
echo 'gateway_ci_pipeline_tests=PASS'

52
tests/ci/semver-test.sh Executable file
View File

@ -0,0 +1,52 @@
#!/usr/bin/env bash
set -euo pipefail
root=$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)
validator=$root/scripts/ci-validate-semver.sh
valid_tags=(
v0.0.0
v1.2.3
v1.2.3-alpha
v1.2.3-alpha.1
v1.2.3-0.3.7
v1.2.3-01a
v1.2.3-alpha-beta
v1.2.3--
v1.2.3-x.7.z.92+build.5
v1.2.3+build.11.e0f985a
v1.2.3+001
)
invalid_tags=(
1.2.3
v01.2.3
v1.02.3
v1.2.03
v1.2.3.foo
v1.2.3.
v1.2.3-.
v1.2.3-alpha.
v1.2.3-alpha..1
v1.2.3-01
v1.2.3-00.1
v1.2.3+
v1.2.3+build.
v1.2.3+build..1
v1.2.3+build+1
'v1.2.3 '
v1.2.3-alpha_1
v1.2
)
for tag in "${valid_tags[@]}"; do
"$validator" "$tag"
done
for tag in "${invalid_tags[@]}"; do
if "$validator" "$tag" >/dev/null 2>&1; then
printf 'invalid SemVer tag was accepted: %s\n' "$tag" >&2
exit 1
fi
done
echo 'semver_tests=PASS'