docs(usage): phase 2 batch 2 — usage side 4 docs (#167)#178
Merged
Conversation
Write the four usage-side documents from issue #167 phase 2 first batch, grounded in the current admin UI and proxy implementation: - guide/usage/admin-overview.md: dashboard sidebar inventory (main + system sections), per-page purpose, login / session model, mobile nav differences. Routes and labels cross-checked against src/components/admin/sidebar.tsx and src/messages/zh-CN.json. - guide/usage/first-upstream.md: end-to-end OpenAI-compatible upstream creation, the four minimum fields, all route_capabilities enum values with corresponding client paths, optional fields with defaults from createUpstreamSchema, the connection test errorType taxonomy, and the localhost-vs-service-name pitfall again. - guide/usage/client-keys.md: client key creation including access_mode inference rule, allowed_models semantics, the one-shot key_value reveal in the create response, ALLOW_KEY_REVEAL gating, the legacy bcrypt-only key path, and the three accepted auth header forms. - guide/usage/invoke-models.md: curl / OpenAI SDK (Python+TS) / Anthropic SDK / Gemini SDK examples, the complete supported path table, SSE handling, and the unified error code summary. Sources cited per claim: src/app/api/admin/{upstreams,keys}/route.ts and route_capabilities, src/lib/services/key-manager.ts and upstream-crud.ts, src/lib/route-capabilities.ts, src/lib/services/route-capability-matcher.ts, src/app/api/proxy/v1/[...path]/route.ts. No claim is left unsubstantiated; example values that depend on deployment (host, port, key prefix tail) use angle-bracket placeholders. Out of scope: architecture batch, README slimming, UI helper text.
All three issues confirmed against the current source before fixing.
1. Gemini SDK base URL was missing the trailing /v1, which would
have made google-genai SDK target /api/proxy/v1beta/... — the
proxy handler is at /api/proxy/v1/[...path] so that path is a
404. Corrected the example to use /api/proxy/v1 as the base URL
so SDK-side concatenation yields /api/proxy/v1/v1beta/..., and
added an explicit note explaining the wiring.
Source: src/app/api/proxy/v1/[...path]/route.ts.
2. The "revoke vs delete" lifecycle description was wrong. The UI
"revoke" button calls DELETE /api/admin/keys/[id] which routes to
deleteApiKey and actually removes the record. There is no separate
"revoke that retains the record" operation. Merged the two rows in
the lifecycle table and added a warning callout pointing users
toward is_active=false ("disable") when audit retention matters.
Source: src/app/api/admin/keys/[id]/route.ts:45.
3. The proxy error code table claimed 401 returns
{ code: "INVALID_API_KEY", ... } and that NO_UPSTREAMS_CONFIGURED
is HTTP 404. In reality:
- Auth-stage failures return bare { error: "Missing API key" } /
"Invalid API key" / "API key has expired" with HTTP 401 and no
code field (route.ts:2446-2473).
- NO_UPSTREAMS_CONFIGURED is HTTP 503; NO_AUTHORIZED_UPSTREAMS is
HTTP 403 (src/lib/services/unified-error.ts:105-106).
Rewrote the section to split "auth-stage" vs "routing/forward
stage" error shapes and corrected both rows.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Phase 2 第二批：撰写 issue #167 第一批 10 篇中的使用侧 4 篇正文，事实依据为当前管理 UI 与代理路由源码。
docs/guide/usage/admin-overview.mddocs/guide/usage/first-upstream.mdroute_capabilities全枚举、可选字段默认值、连通性测试错误分类docs/guide/usage/client-keys.mdallowed_models、密钥一次性返回与ALLOW_KEY_REVEAL揭示、三种鉴权 headerdocs/guide/usage/invoke-models.md事实依据
逐条以当前 master 源码为根：
src/components/admin/sidebar.tsx+src/messages/zh-CN.json：导航条目与中文标签src/app/api/admin/upstreams/route.ts、src/lib/services/upstream-crud.ts、upstream-connection-tester.ts：上游创建 / 加密 / 连通性测试src/lib/route-capabilities.ts：route_capabilities枚举与 provider 同组约束src/app/api/admin/keys/route.ts、src/lib/services/key-manager.ts：密钥创建、access_mode 推断、bcrypt + Fernet 双存src/app/api/admin/keys/[id]/reveal/route.ts、src/lib/utils/config.ts：揭示接口与ALLOW_KEY_REVEAL校验src/app/api/proxy/v1/[...path]/route.ts、src/lib/services/route-capability-matcher.ts：路径到能力的映射、三种鉴权 header、SSE 包装无法在源码中定值的部分（部署 host、端口、Key 后缀）一律用尖括号占位符
<...>形式标注，避免给出假数据。不在本 PR 范围
Test plan
pnpm format:check全绿（prettier 自动对齐表格列宽）pnpm docs:build3.62 s 构建成功，无 dead link 报告[失败转移与熔断](#)，改为指向/circuit-breakerDocsworkflow build job 通过