AIClient-2-API/static/components/section-tutorial.html

<link rel="stylesheet" href="components/section-tutorial.css">
<!-- Tutorial Section -->
<section id="tutorial" class="section" aria-labelledby="tutorial-title">
    <h2 id="tutorial-title" data-i18n="tutorial.title">配置教程</h2>
    
    <!-- 配置文件说明 -->
    <div class="tutorial-panel">
        <h3><i class="fas fa-file-code"></i> <span data-i18n="tutorial.config.title">配置文件说明</span></h3>
        <div class="tutorial-content">
            <p data-i18n="tutorial.config.desc">所有配置文件都存放在 <code>configs/</code> 目录下。主要配置文件包括：</p>
            
            <div class="config-file-list">
                <div class="config-file-item">
                    <div class="file-header">
                        <i class="fas fa-file-alt"></i>
                        <span class="file-name">config.json</span>
                        <span class="file-badge required" data-i18n="tutorial.config.badge.required">必需</span>
                    </div>
                    <p class="file-desc" data-i18n="tutorial.config.file.config">主配置文件，包含 API Key、端口、模型提供商等核心设置 (保存配置管理后自动新建)</p>
                </div>
                <div class="config-file-item">
                    <div class="file-header">
                        <i class="fas fa-file-alt"></i>
                        <span class="file-name">provider_pools.json</span>
                        <span class="file-badge required" data-i18n="tutorial.config.badge.required">必需</span>
                    </div>
                    <p class="file-desc" data-i18n="tutorial.config.file.pools">提供商池配置，用于多账号轮询和故障转移 (保存节点后自动新建)</p>
                </div>
                <div class="config-file-item">
                    <div class="file-header">
                        <i class="fas fa-file-alt"></i>
                        <span class="file-name">plugins.json</span>
                        <span class="file-badge optional" data-i18n="tutorial.config.badge.optional">可选</span>
                    </div>
                    <p class="file-desc" data-i18n="tutorial.config.file.plugins">插件配置，用于启用或禁用系统插件</p>
                </div>
                <div class="config-file-item">
                    <div class="file-header">
                        <i class="fas fa-lock"></i>
                        <span class="file-name">pwd</span>
                        <span class="file-badge optional" data-i18n="tutorial.config.badge.optional">可选</span>
                    </div>
                    <p class="file-desc" data-i18n="tutorial.config.file.pwd">后台登录密码文件，默认密码为 admin123</p>
                </div>
            </div>
        </div>
    </div>

    <!-- 主配置详解 -->
    <div class="tutorial-panel">
        <h3><i class="fas fa-cogs"></i> <span data-i18n="tutorial.main.title">主配置详解 (config.json)</span></h3>
        <div class="tutorial-content">
            <!-- 基础设置 -->
            <div class="config-section">
                <h4 data-i18n="config.basic.title">基础设置</h4>
                <div class="config-table">
                    <table>
                        <thead>
                            <tr>
                                <th data-i18n="tutorial.main.table.param">参数</th>
                                <th data-i18n="tutorial.main.table.type">类型</th>
                                <th data-i18n="tutorial.main.table.default">默认值</th>
                                <th data-i18n="tutorial.main.table.desc">说明</th>
                            </tr>
                        </thead>
                        <tbody>
                            <tr>
                                <td><code>REQUIRED_API_KEY</code></td>
                                <td>string</td>
                                <td>-</td>
                                <td data-i18n="tutorial.main.basic.apikey">访问本服务所需的 API Key</td>
                            </tr>
                            <tr>
                                <td><code>SERVER_PORT</code></td>
                                <td>number</td>
                                <td>3000</td>
                                <td data-i18n="tutorial.main.basic.port">服务监听端口</td>
                            </tr>
                            <tr>
                                <td><code>HOST</code></td>
                                <td>string</td>
                                <td>0.0.0.0</td>
                                <td data-i18n="tutorial.main.basic.host">服务监听地址</td>
                            </tr>
                            <tr>
                                <td><code>MODEL_PROVIDER</code></td>
                                <td>string</td>
                                <td>-</td>
                                <td data-i18n="tutorial.main.basic.provider">默认模型提供商</td>
                            </tr>
                        </tbody>
                    </table>
                </div>
            </div>

            <!-- 代理设置 -->
            <div class="config-section">
                <h4 data-i18n="config.proxy.title">代理设置</h4>
                <div class="config-table">
                    <table>
                        <thead>
                            <tr>
                                <th data-i18n="tutorial.main.table.param">参数</th>
                                <th data-i18n="tutorial.main.table.type">类型</th>
                                <th data-i18n="tutorial.main.table.desc">说明</th>
                            </tr>
                        </thead>
                        <tbody>
                            <tr>
                                <td><code>PROXY_URL</code></td>
                                <td>string</td>
                                <td data-i18n="tutorial.proxy.url">代理地址，支持 HTTP、HTTPS、SOCKS5</td>
                            </tr>
                            <tr>
                                <td><code>PROXY_ENABLED_PROVIDERS</code></td>
                                <td>array</td>
                                <td data-i18n="tutorial.proxy.providers">启用代理的提供商列表</td>
                            </tr>
                        </tbody>
                    </table>
                </div>
            </div>

            <!-- 服务治理 -->
            <div class="config-section">
                <h4 data-i18n="config.governance.title">服务治理</h4>
                <div class="config-table">
                    <table>
                        <thead>
                            <tr>
                                <th data-i18n="tutorial.main.table.param">参数</th>
                                <th data-i18n="tutorial.main.table.type">类型</th>
                                <th data-i18n="tutorial.main.table.default">默认值</th>
                                <th data-i18n="tutorial.main.table.desc">说明</th>
                            </tr>
                        </thead>
                        <tbody>
                            <tr>
                                <td><code>REQUEST_MAX_RETRIES</code></td>
                                <td>number</td>
                                <td>3</td>
                                <td data-i18n="tutorial.main.retry.max">最大重试次数</td>
                            </tr>
                            <tr>
                                <td><code>REQUEST_BASE_DELAY</code></td>
                                <td>number</td>
                                <td>1000</td>
                                <td data-i18n="tutorial.main.retry.delay">重试基础延迟（毫秒）</td>
                            </tr>
                            <tr>
                                <td><code>CREDENTIAL_SWITCH_MAX_RETRIES</code></td>
                                <td>number</td>
                                <td>5</td>
                                <td data-i18n="tutorial.main.retry.credentialSwitch">坏凭证切换最大重试次数</td>
                            </tr>
                            <tr>
                                <td><code>MAX_ERROR_COUNT</code></td>
                                <td>number</td>
                                <td>10</td>
                                <td data-i18n="tutorial.main.retry.error">提供商最大错误次数，超过后标记为不健康</td>
                            </tr>
                            <tr>
                                <td><code>WARMUP_TARGET</code></td>
                                <td>number</td>
                                <td>0</td>
                                <td data-i18n="tutorial.main.governance.warmup">系统启动时自动刷新的节点数量</td>
                            </tr>
                            <tr>
                                <td><code>REFRESH_CONCURRENCY_PER_PROVIDER</code></td>
                                <td>number</td>
                                <td>1</td>
                                <td data-i18n="tutorial.main.governance.concurrency">提供商内刷新并发数</td>
                            </tr>
                        </tbody>
                    </table>
                </div>
            </div>

            <!-- 日志设置 -->
            <div class="config-section">
                <h4 data-i18n="config.log.title">日志设置</h4>
                <div class="config-table">
                    <table>
                        <thead>
                            <tr>
                                <th data-i18n="tutorial.main.table.param">参数</th>
                                <th data-i18n="tutorial.main.table.type">类型</th>
                                <th data-i18n="tutorial.main.table.desc">说明</th>
                            </tr>
                        </thead>
                        <tbody>
                            <tr>
                                <td><code>LOG_ENABLED</code></td>
                                <td>boolean</td>
                                <td data-i18n="config.log.enabled">启用日志</td>
                            </tr>
                            <tr>
                                <td><code>LOG_OUTPUT_MODE</code></td>
                                <td>string</td>
                                <td data-i18n="config.log.outputMode">日志输出模式 (all/console/file/none)</td>
                            </tr>
                            <tr>
                                <td><code>PROMPT_LOG_MODE</code></td>
                                <td>string</td>
                                <td data-i18n="tutorial.log.mode">提示词日志模式：none(关闭)、console(控制台)、file(文件)</td>
                            </tr>
                        </tbody>
                    </table>
                </div>
            </div>

            <div class="config-example">
                <h4 data-i18n="tutorial.main.example.title">配置示例</h4>
                <pre><code>{
    "REQUIRED_API_KEY": "your-api-key",
    "SERVER_PORT": 3000,
    "HOST": "0.0.0.0",
    "MODEL_PROVIDER": "gemini-cli-oauth,claude-kiro-oauth",
    "PROXY_URL": "http://127.0.0.1:7890",
    "PROXY_ENABLED_PROVIDERS": ["gemini-cli-oauth", "claude-kiro-oauth"],
    "REQUEST_MAX_RETRIES": 3,
    "MAX_ERROR_COUNT": 10,
    "WARMUP_TARGET": 5,
    "LOG_ENABLED": true,
    "LOG_OUTPUT_MODE": "all"
}</code></pre>
            </div>
        </div>
    </div>

    <!-- 提供商池配置 -->
    <div class="tutorial-panel">
        <h3><i class="fas fa-layer-group"></i> <span data-i18n="tutorial.pool.title">提供商池配置 (provider_pools.json)</span></h3>
        <div class="tutorial-content">
            <p data-i18n="tutorial.pool.desc">提供商池用于配置多个账号，实现负载均衡和故障转移。每个提供商类型可以配置多个账号节点。</p>
            
            <div class="config-section">
                <h4 data-i18n="tutorial.pool.node.title">节点配置参数</h4>
                <div class="config-table">
                    <table>
                        <thead>
                            <tr>
                                <th data-i18n="tutorial.main.table.param">参数</th>
                                <th data-i18n="tutorial.main.table.type">类型</th>
                                <th data-i18n="tutorial.main.table.desc">说明</th>
                            </tr>
                        </thead>
                        <tbody>
                            <tr>
                                <td><code>uuid</code></td>
                                <td>string</td>
                                <td data-i18n="tutorial.pool.node.uuid">节点唯一标识，自动生成</td>
                            </tr>
                            <tr>
                                <td><code>name</code></td>
                                <td>string</td>
                                <td data-i18n="tutorial.pool.node.name">节点自定义名称</td>
                            </tr>
                            <tr>
                                <td><code>oauthCredsFilePath</code></td>
                                <td>string</td>
                                <td data-i18n="tutorial.pool.node.oauth">OAuth 凭据文件路径</td>
                            </tr>
                            <tr>
                                <td><code>checkHealth</code></td>
                                <td>boolean</td>
                                <td data-i18n="tutorial.pool.node.health">是否启用健康检查</td>
                            </tr>
                            <tr>
                                <td><code>checkModel</code></td>
                                <td>string</td>
                                <td data-i18n="tutorial.pool.node.model">健康检查使用的模型</td>
                            </tr>
                            <tr>
                                <td><code>notSupportedModels</code></td>
                                <td>array</td>
                                <td data-i18n="tutorial.pool.node.unsupported">该节点不支持的模型列表</td>
                            </tr>
                            <tr>
                                <td><code>disabled</code></td>
                                <td>boolean</td>
                                <td data-i18n="tutorial.pool.node.disabled">是否禁用该节点</td>
                            </tr>
                        </tbody>
                    </table>
                </div>
            </div>

            <div class="config-example">
                <h4 data-i18n="tutorial.pool.example.title">配置示例</h4>
                <pre><code>{
    "gemini-cli-oauth": [
        {
            "uuid": "gemini-account-1",
            "name": "Gemini 账号 1",
            "oauthCredsFilePath": "configs/gemini/oauth_creds_1.json",
            "checkHealth": true,
            "checkModel": "gemini-3-flash-preview"
        }
    ],
    "claude-kiro-oauth": [
        {
            "uuid": "kiro-account-1",
            "name": "Kiro 账号 1",
            "oauthCredsFilePath": "configs/kiro/kiro-auth-token.json",
            "checkHealth": true
        }
    ]
}</code></pre>
            </div>
        </div>
    </div>

    <!-- Fallback 配置 -->
    <div class="tutorial-panel">
        <h3><i class="fas fa-random"></i> <span data-i18n="tutorial.fallback.title">Fallback 降级配置</span></h3>
        <div class="tutorial-content">
            <p data-i18n="tutorial.fallback.desc">当某一提供商类型的所有账号都不可用时，可以自动切换到配置的备用提供商。</p>
            
            <div class="config-section">
                <h4 data-i18n="tutorial.fallback.chain.title">跨类型 Fallback 链</h4>
                <p data-i18n="tutorial.fallback.chain.desc">在 config.json 中配置 providerFallbackChain，指定每个提供商类型的备用类型：</p>
                <pre><code>{
    "providerFallbackChain": {
        "gemini-cli-oauth": ["gemini-antigravity"],
        "gemini-antigravity": ["gemini-cli-oauth"],
        "claude-kiro-oauth": ["claude-custom"],
        "claude-custom": ["claude-kiro-oauth"]
    }
}</code></pre>
            </div>

            <div class="config-section">
                <h4 data-i18n="tutorial.fallback.model.title">跨协议模型映射</h4>
                <p data-i18n="tutorial.fallback.model.desc">当主提供商不可用时，可以将特定模型映射到其他协议的提供商：</p>
                <pre><code>{
    "modelFallbackMapping": {
        "gemini-claude-opus-4-5-thinking": {
            "targetProviderType": "claude-kiro-oauth",
            "targetModel": "claude-opus-4-5"
        }
    }
}</code></pre>
            </div>
        </div>
    </div>

    <!-- OAuth 授权路径 -->
    <div class="tutorial-panel">
        <h3><i class="fas fa-key"></i> <span data-i18n="tutorial.oauth.title">OAuth 授权路径</span></h3>
        <div class="tutorial-content">
            <p data-i18n="tutorial.oauth.desc">各提供商的 OAuth 凭据文件默认存储位置（建议保持在 <code>configs/</code> 目录下以便统一管理）：</p>
            
            <div id="oauthPathList" class="oauth-path-list">
                <!-- 动态生成 -->
            </div>

            <div class="tutorial-note">
                <i class="fas fa-lightbulb"></i>
                <span data-i18n="tutorial.oauth.note">推荐通过 Web UI 控制台的"提供商池管理"页面点击"生成授权"按钮进行可视化授权，系统会自动保存凭据文件。</span>
            </div>
        </div>
    </div>
</section>