Skip to content

Commit 2649368

Browse files
zhushanwen321zhushanwen321
committed
feat: restructure docs - new pages (Architecture/FAQ/OtherFeatures), new sidebar groups, 17→15 pages
1 parent 0cd9dd2 commit 2649368

8 files changed

Lines changed: 343 additions & 83 deletions

File tree

‎src/composables/useLocale.ts‎

Lines changed: 11 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -27,27 +27,23 @@ export const SIDEBAR_KEYS = {
2727
quickStart: 'sidebar.quickStart',
2828
overview: 'sidebar.overview',
2929
startRouter: 'sidebar.startRouter',
30-
features: 'sidebar.features',
31-
autoRetry: 'sidebar.autoRetry',
30+
usageGuide: 'sidebar.usageGuide',
3231
providers: 'sidebar.providers',
3332
modelMapping: 'sidebar.modelMapping',
33+
autoRetry: 'sidebar.autoRetry',
3434
concurrency: 'sidebar.concurrency',
35-
loopDetection: 'sidebar.loopDetection',
36-
proxy: 'sidebar.proxy',
37-
failover: 'sidebar.failover',
38-
monitor: 'sidebar.monitor',
3935
multiKey: 'sidebar.multiKey',
40-
openaiCompat: 'sidebar.openaiCompat',
41-
config: 'sidebar.config',
36+
monitor: 'sidebar.monitor',
37+
otherFeatures: 'sidebar.otherFeatures',
38+
clientConfig: 'sidebar.clientConfig',
4239
claudeCode: 'sidebar.claudeCode',
40+
deploy: 'sidebar.deploy',
4341
env: 'sidebar.env',
4442
docker: 'sidebar.docker',
4543
architecture: 'sidebar.architecture',
46-
systemContext: 'sidebar.systemContext',
47-
requestPipeline: 'sidebar.requestPipeline',
48-
logging: 'sidebar.logging',
49-
pipeline: 'sidebar.pipeline',
50-
metrics: 'sidebar.metrics',
51-
ttftTps: 'sidebar.ttftTps',
52-
tokens: 'sidebar.tokens',
44+
archOverview: 'sidebar.archOverview',
45+
loggingMetrics: 'sidebar.loggingMetrics',
46+
logPipeline: 'sidebar.logPipeline',
47+
faq: 'sidebar.faq',
48+
faqPage: 'sidebar.faqPage',
5349
} as const

‎src/config/sidebar.ts‎

Lines changed: 12 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -15,33 +15,30 @@ export const llmSimpleRouterSidebar: SidebarGroup[] = [
1515
{ titleKey: K.overview, path: '/project/llm-simple-router/' },
1616
{ titleKey: K.startRouter, path: '/project/llm-simple-router/guide/getting-started' },
1717
]},
18-
{ titleKey: K.features, items: [
19-
{ titleKey: K.autoRetry, path: '/project/llm-simple-router/guide/features/auto-retry' },
18+
{ titleKey: K.usageGuide, items: [
2019
{ titleKey: K.providers, path: '/project/llm-simple-router/guide/features/providers' },
2120
{ titleKey: K.modelMapping, path: '/project/llm-simple-router/guide/features/model-mapping' },
21+
{ titleKey: K.autoRetry, path: '/project/llm-simple-router/guide/features/auto-retry' },
2222
{ titleKey: K.concurrency, path: '/project/llm-simple-router/guide/features/concurrency' },
23-
{ titleKey: K.loopDetection, path: '/project/llm-simple-router/guide/features/loop-detection' },
24-
{ titleKey: K.proxy, path: '/project/llm-simple-router/guide/features/proxy' },
25-
{ titleKey: K.failover, path: '/project/llm-simple-router/guide/features/failover' },
26-
{ titleKey: K.openaiCompat, path: '/project/llm-simple-router/guide/features/openai-compat' },
27-
{ titleKey: K.monitor, path: '/project/llm-simple-router/guide/features/monitor' },
2823
{ titleKey: K.multiKey, path: '/project/llm-simple-router/guide/features/multi-key' },
24+
{ titleKey: K.monitor, path: '/project/llm-simple-router/guide/features/monitor' },
25+
{ titleKey: K.otherFeatures, path: '/project/llm-simple-router/guide/features/other' },
2926
]},
30-
{ titleKey: K.config, items: [
27+
{ titleKey: K.clientConfig, items: [
3128
{ titleKey: K.claudeCode, path: '/project/llm-simple-router/guide/config/claude-code' },
29+
]},
30+
{ titleKey: K.deploy, items: [
3231
{ titleKey: K.env, path: '/project/llm-simple-router/guide/config/env' },
3332
{ titleKey: K.docker, path: '/project/llm-simple-router/guide/config/docker' },
3433
]},
3534
{ titleKey: K.architecture, items: [
36-
{ titleKey: K.systemContext, path: '/project/llm-simple-router/guide/architecture/system-context' },
37-
{ titleKey: K.requestPipeline, path: '/project/llm-simple-router/guide/architecture/request-pipeline' },
35+
{ titleKey: K.archOverview, path: '/project/llm-simple-router/guide/architecture/overview' },
3836
]},
39-
{ titleKey: K.logging, items: [
40-
{ titleKey: K.pipeline, path: '/project/llm-simple-router/guide/logging/pipeline' },
37+
{ titleKey: K.loggingMetrics, items: [
38+
{ titleKey: K.logPipeline, path: '/project/llm-simple-router/guide/logging/pipeline' },
4139
]},
42-
{ titleKey: K.metrics, items: [
43-
{ titleKey: K.ttftTps, path: '/project/llm-simple-router/guide/metrics/ttft-tps' },
44-
{ titleKey: K.tokens, path: '/project/llm-simple-router/guide/metrics/tokens' },
40+
{ titleKey: K.faq, items: [
41+
{ titleKey: K.faqPage, path: '/project/llm-simple-router/guide/faq' },
4542
]},
4643
]
4744

‎src/locales/en.ts‎

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,17 @@
11
export default {
22
nav: { about: 'About', projects: 'Projects', social: 'Social' },
33
sidebar: {
4-
quickStart: 'Quick Start', overview: 'Overview', startRouter: 'Starting Router',
5-
features: 'Features', autoRetry: 'Auto Retry', providers: 'Multi-Provider Support',
6-
modelMapping: 'Model Mapping', concurrency: 'Concurrency Control',
7-
loopDetection: 'Loop Detection', proxy: 'Network Proxy', failover: 'Failover',
8-
monitor: 'Live Monitor', multiKey: 'Multi-Key Management',
9-
openaiCompat: 'OpenAI Compatible',
10-
config: 'Configuration', claudeCode: 'Claude Code Setup', env: 'Environment Variables',
11-
docker: 'Docker Deployment', architecture: 'Architecture',
12-
systemContext: 'System Context', requestPipeline: 'Request Pipeline',
13-
logging: 'Request Logging', pipeline: 'Four-Stage Pipeline',
14-
metrics: 'Performance Metrics', ttftTps: 'TTFT / TPS', tokens: 'Token Usage',
4+
quickStart: 'Quick Start', overview: 'Overview', startRouter: 'Getting Started',
5+
usageGuide: 'Usage Guide',
6+
providers: 'Provider Management', modelMapping: 'Model Mapping & Scheduling',
7+
autoRetry: 'Auto Retry', concurrency: 'Concurrency Control',
8+
multiKey: 'Multi-Key Management', monitor: 'Live Monitor',
9+
otherFeatures: 'Additional Features',
10+
clientConfig: 'Client Config', claudeCode: 'Claude Code Setup',
11+
deploy: 'Deployment', env: 'Environment Variables', docker: 'Docker Deployment',
12+
architecture: 'Architecture', archOverview: 'Architecture Overview',
13+
loggingMetrics: 'Logging & Metrics', logPipeline: 'Logging & Performance Metrics',
14+
faq: 'FAQ', faqPage: 'FAQ',
1515
},
1616
footer: { prev: 'Previous', next: 'Next' },
1717
social: { title: 'Social Platforms', scanOrClick: 'Scan QR code or tap to connect', repos: 'Code Repositories' },

‎src/locales/zh.ts‎

Lines changed: 11 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,17 @@
11
export default {
22
nav: { about: '个人介绍', projects: '项目介绍', social: '社交平台' },
33
sidebar: {
4-
quickStart: '快速开始', overview: '概览', startRouter: '启动 Router',
5-
features: '功能特性', autoRetry: '自动重试', providers: '多供应商支持',
6-
modelMapping: '模型映射', concurrency: '并发控制', loopDetection: '循环检测',
7-
proxy: '网络代理', failover: '故障转移',
8-
monitor: '实时监控', multiKey: '多密钥管理', openaiCompat: 'OpenAI 兼容',
9-
config: '配置指南', claudeCode: 'Claude Code 配置', env: '环境变量',
10-
docker: 'Docker 部署', architecture: '架构原理',
11-
systemContext: '系统上下文', requestPipeline: '请求流水线',
12-
logging: '请求日志', pipeline: '四阶段链路',
13-
metrics: '性能指标', ttftTps: 'TTFT / TPS', tokens: 'Token 用量',
4+
quickStart: '快速开始', overview: '概览', startRouter: '快速上手',
5+
usageGuide: '使用指南',
6+
providers: '供应商管理', modelMapping: '模型映射与调度',
7+
autoRetry: '自动重试', concurrency: '并发控制',
8+
multiKey: '多密钥管理', monitor: '实时监控',
9+
otherFeatures: '其他增强',
10+
clientConfig: '客户端配置', claudeCode: 'Claude Code 配置',
11+
deploy: '部署运维', env: '环境变量', docker: 'Docker 部署',
12+
architecture: '架构原理', archOverview: '架构概览',
13+
loggingMetrics: '日志与指标', logPipeline: '请求日志与性能指标',
14+
faq: '常见问题', faqPage: 'FAQ',
1415
},
1516
footer: { prev: '上一页', next: '下一页' },
1617
social: { title: '社交平台', scanOrClick: '扫码或点击图标联系我', repos: '代码仓库' },

‎src/router/index.ts‎

Lines changed: 12 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -44,10 +44,6 @@ const router = createRouter({
4444
path: 'guide/getting-started',
4545
component: () => import('../views/project/llm-simple-router/getting-started/Index.vue'),
4646
},
47-
{
48-
path: 'guide/features/auto-retry',
49-
component: () => import('../views/project/llm-simple-router/features/AutoRetry.vue'),
50-
},
5147
{
5248
path: 'guide/features/providers',
5349
component: () => import('../views/project/llm-simple-router/features/Providers.vue'),
@@ -57,32 +53,24 @@ const router = createRouter({
5753
component: () => import('../views/project/llm-simple-router/features/ModelMapping.vue'),
5854
},
5955
{
60-
path: 'guide/features/concurrency',
61-
component: () => import('../views/project/llm-simple-router/features/Concurrency.vue'),
62-
},
63-
{
64-
path: 'guide/features/loop-detection',
65-
component: () => import('../views/project/llm-simple-router/features/LoopDetection.vue'),
56+
path: 'guide/features/auto-retry',
57+
component: () => import('../views/project/llm-simple-router/features/AutoRetry.vue'),
6658
},
6759
{
68-
path: 'guide/features/proxy',
69-
component: () => import('../views/project/llm-simple-router/features/Proxy.vue'),
60+
path: 'guide/features/concurrency',
61+
component: () => import('../views/project/llm-simple-router/features/Concurrency.vue'),
7062
},
7163
{
72-
path: 'guide/features/failover',
73-
component: () => import('../views/project/llm-simple-router/features/Failover.vue'),
64+
path: 'guide/features/multi-key',
65+
component: () => import('../views/project/llm-simple-router/features/MultiKey.vue'),
7466
},
7567
{
7668
path: 'guide/features/monitor',
7769
component: () => import('../views/project/llm-simple-router/features/Monitor.vue'),
7870
},
7971
{
80-
path: 'guide/features/multi-key',
81-
component: () => import('../views/project/llm-simple-router/features/MultiKey.vue'),
82-
},
83-
{
84-
path: 'guide/features/openai-compat',
85-
component: () => import('../views/project/llm-simple-router/features/OpenAICompat.vue'),
72+
path: 'guide/features/other',
73+
component: () => import('../views/project/llm-simple-router/features/OtherFeatures.vue'),
8674
},
8775
{
8876
path: 'guide/config/claude-code',
@@ -97,24 +85,16 @@ const router = createRouter({
9785
component: () => import('../views/project/llm-simple-router/config/Docker.vue'),
9886
},
9987
{
100-
path: 'guide/architecture/system-context',
101-
component: () => import('../views/project/llm-simple-router/architecture/SystemContext.vue'),
102-
},
103-
{
104-
path: 'guide/architecture/request-pipeline',
105-
component: () => import('../views/project/llm-simple-router/architecture/RequestPipeline.vue'),
88+
path: 'guide/architecture/overview',
89+
component: () => import('../views/project/llm-simple-router/architecture/Architecture.vue'),
10690
},
10791
{
10892
path: 'guide/logging/pipeline',
10993
component: () => import('../views/project/llm-simple-router/logging/Pipeline.vue'),
11094
},
11195
{
112-
path: 'guide/metrics/ttft-tps',
113-
component: () => import('../views/project/llm-simple-router/metrics/TtftTps.vue'),
114-
},
115-
{
116-
path: 'guide/metrics/tokens',
117-
component: () => import('../views/project/llm-simple-router/metrics/Tokens.vue'),
96+
path: 'guide/faq',
97+
component: () => import('../views/project/llm-simple-router/FAQ.vue'),
11898
},
11999
],
120100
},

‎src/views/project/llm-simple-router/FAQ.vue‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
<script setup lang="ts">
2+
import { computed } from 'vue'
3+
import { useI18n } from 'vue-i18n'
4+
const { locale } = useI18n()
5+
const isZh = computed(() => locale.value === 'zh')
6+
</script>
7+
8+
<template>
9+
<div class="prose prose-invert max-w-none">
10+
<template v-if="isZh">
11+
<h1>常见问题</h1>
12+
13+
<h2>Claude Code 连接不上 Router？</h2>
14+
<ol>
15+
<li>确认 Router 正在运行：访问 <code>http://localhost:9981/admin</code></li>
16+
<li>确认 API Key 正确：管理后台 &gt; 密钥管理，确保使用了正确的 <code>sk-router-xxx</code> 密钥</li>
17+
<li>检查环境变量：<code>ANTHROPIC_BASE_URL</code> 是否指向 Router 地址</li>
18+
<li>如果 Router 在其他机器上，确保端口可访问（非 127.0.0.1）</li>
19+
<li>调试模式启动 Claude Code：<code>claude --debug --verbose</code> 查看详细错误</li>
20+
</ol>
21+
22+
<h2>怎么设置并发数？</h2>
23+
<p>
24+
建议根据 Provider 的 API 限制来设定。例如智谱 Coding Plan 限制 5 并发，则设为 5。
25+
启用自适应模式后，Router 会根据响应时间自动调整，无需精确估算。
26+
初始建议：智谱 5、Moonshot 3、其他供应商参考官方文档。
27+
</p>
28+
29+
<h2>供应商突然不可用了？</h2>
30+
<p>
31+
配置 <strong>Failover 故障转移</strong>：在模型映射页面为同一客户端模型配置多个映射规则，
32+
路由策略选择 Failover。主力 Provider 故障时自动切换到备用 Provider。
33+
</p>
34+
35+
<h2>Token 消耗太快？</h2>
36+
<ul>
37+
<li>在 Dashboard 查看哪个模型 Token 用量最大，分析是否正常</li>
38+
<li>开启 <strong>LLM 循环检测</strong>，避免输出死循环浪费 Token</li>
39+
<li>设置 <strong>每模型流式超时</strong>，避免单个请求长时间占用</li>
40+
</ul>
41+
42+
<h2>怎么升级到新版本？</h2>
43+
<p>非 Docker 部署：</p>
44+
<div class="not-prose my-4 rounded-lg border border-white/10 bg-surface-50 p-4">
45+
<code class="text-sm font-mono text-gray-300">npx llm-simple-router@latest</code>
46+
</div>
47+
<p>Docker 部署：</p>
48+
<div class="not-prose my-4 rounded-lg border border-white/10 bg-surface-50 p-4">
49+
<code class="text-sm font-mono text-gray-300">docker compose pull && docker compose up -d</code>
50+
</div>
51+
<p>升级前建议备份 <code>~/.llm-simple-router/router.db</code>。</p>
52+
53+
<h2>怎么备份和迁移数据？</h2>
54+
<p>所有数据存储在 <code>~/.llm-simple-router/</code> 目录下，备份该目录即可：</p>
55+
<div class="not-prose my-4 rounded-lg border border-white/10 bg-surface-50 p-4">
56+
<code class="text-sm font-mono text-gray-300">cp -r ~/.llm-simple-router ~/.llm-simple-router.bak</code>
57+
</div>
58+
59+
<h2>HTTP 环境下无法登录？</h2>
60+
<p>Router 自动检测请求协议设置 Cookie Secure 标志。如果通过 HTTP 访问（非 HTTPS），
61+
Cookie 会设置为非 Secure 模式，无需额外配置。</p>
62+
</template>
63+
64+
<template v-else>
65+
<h1>FAQ</h1>
66+
67+
<h2>Claude Code can't connect to Router?</h2>
68+
<ol>
69+
<li>Verify Router is running: visit <code>http://localhost:9981/admin</code></li>
70+
<li>Check API key: Admin Panel &gt; Key Management, ensure correct <code>sk-router-xxx</code> key</li>
71+
<li>Check env vars: <code>ANTHROPIC_BASE_URL</code> points to Router address</li>
72+
<li>If Router is on another machine, ensure port is accessible (not 127.0.0.1)</li>
73+
<li>Debug Claude Code: <code>claude --debug --verbose</code> for detailed errors</li>
74+
</ol>
75+
76+
<h2>How to set concurrency limits?</h2>
77+
<p>
78+
Set based on Provider API limits. e.g. Zhipu Coding Plan caps at 5 concurrency → set to 5.
79+
Enable adaptive mode and Router auto-adjusts based on response times.
80+
Suggested defaults: Zhipu 5, Moonshot 3, others per official docs.
81+
</p>
82+
83+
<h2>Provider suddenly unavailable?</h2>
84+
<p>
85+
Configure <strong>Failover</strong>: add multiple mapping rules for the same client model
86+
on the Model Mapping page, select Failover strategy. Primary down → auto-switch to backup.
87+
</p>
88+
89+
<h2>Token usage too high?</h2>
90+
<ul>
91+
<li>Check Dashboard for per-model token breakdown</li>
92+
<li>Enable <strong>LLM Loop Detection</strong> to prevent output loops</li>
93+
<li>Set <strong>per-model stream timeout</strong> to cap long-running requests</li>
94+
</ul>
95+
96+
<h2>How to upgrade?</h2>
97+
<p>Non-Docker:</p>
98+
<div class="not-prose my-4 rounded-lg border border-white/10 bg-surface-50 p-4">
99+
<code class="text-sm font-mono text-gray-300">npx llm-simple-router@latest</code>
100+
</div>
101+
<p>Docker:</p>
102+
<div class="not-prose my-4 rounded-lg border border-white/10 bg-surface-50 p-4">
103+
<code class="text-sm font-mono text-gray-300">docker compose pull && docker compose up -d</code>
104+
</div>
105+
<p>Backup <code>~/.llm-simple-router/router.db</code> before upgrading.</p>
106+
107+
<h2>How to backup and migrate data?</h2>
108+
<p>All data is in <code>~/.llm-simple-router/</code>. Back up the entire directory:</p>
109+
<div class="not-prose my-4 rounded-lg border border-white/10 bg-surface-50 p-4">
110+
<code class="text-sm font-mono text-gray-300">cp -r ~/.llm-simple-router ~/.llm-simple-router.bak</code>
111+
</div>
112+
113+
<h2>Can't login over HTTP?</h2>
114+
<p>Router auto-detects protocol for cookie security. HTTP access automatically uses non-secure cookies — no extra config needed.</p>
115+
</template>
116+
</div>
117+
</template>

0 commit comments

Comments
 (0)