fuzhengwei/waliapi

🎁 免费渠道开箱即用：启动即内置 OpenCode 免费车道 与 Kilo 免费池 两条免 Key 渠道，零配置直接调用；另提供 11 个免费层渠道预设——国际（Groq / Cerebras / Mistral / NVIDIA NIM / OpenRouter / GitHub Models / Hugging Face / SambaNova / Cohere）与国内（ModelScope 魔搭 / SiliconFlow 硅基流动）——注册领取 API Key 即用，Google Gemini 与智谱 GLM 也提供免费层。详见 免费渠道。

---

🧭 30 秒看懂 WaLiAPI

下面这张图描述了 WaLiAPI 的完整工作流：左侧是发出请求的 AI 应用，中间是 WaLiAPI 网关的处理链路（含内置的 RAG 知识库与 LLM-Wiki 知识引擎），右侧是你配置的三类上游渠道——API 渠道（Key 接入）、免费渠道（免 Key / 免费层）与账号渠道（OAuth 登录的 Auth 账号）。

flowchart LR
    subgraph Clients["💬 下游 AI 应用"]
        direction TB
        A1["Claude Code"]
        A2["Codex CLI"]
        A3["Gemini CLI"]
        A4["WaLiCode"]
        A5["OpenClaw"]
        A6["ChatBox / NextChat"]
    end

    subgraph Gateway["🛡️ WaLiAPI 本地网关  127.0.0.1:8777"]
        direction TB
        B["① 多协议接入OpenAI Chat · Responses · Anthropic"]
        C["② 安全审计敏感信息扫描 · 脱敏 / 阻断"]
        D["③ 智能调度优先级 + 权重 · 多 Key 负载 · 故障切换"]
        E["④ 协议转换 · 上游适配OpenAI · Claude · Gemini · DeepSeek · 自定义"]

        B --> C --> D --> E

        subgraph Knowledge["📚 内置知识服务（复用同一调度与审计）"]
            direction LR
            R["RAG 知识库解析 → 分块 → 向量化HNSW + FTS5 混合检索问答"]
            W["LLM-WikiMarkdown 页面 · 知识图谱MCP 工具对外暴露"]
        end
    end

    subgraph Channels["☁️ 上游渠道（三类）"]
        direction TB
        F1["🔗 API 渠道（Key 接入）OpenAI · Claude · DeepSeek · Gemini智谱 · 通义 · Moonshot · 豆包 · StepFun"]
        F2["🎁 免费渠道OpenCode 车道 / Kilo 池（免 Key · 启动即内置）11 家免费层：Groq · Cerebras · Mistral · NIM · OpenRouterModelScope · 硅基流动 · GitHub Models · HF · SambaNova · Cohere"]
        F3["👤 账号渠道（OAuth 登录）Codex · Kimi · AntigravityQoder · WorkBuddy · Grok"]
    end

    Clients -- "统一密钥sk-waliapi-*" --> B
    E -- "HTTPS 转发" --> Channels
    Clients -. "MCP /mcp · REST /api/kbRAG 检索 · Wiki 问答" .-> Knowledge
    Knowledge -. "Embedding / 问答模型走网关调度" .-> D

    style Clients fill:#f0f7ff,stroke:#4a90d9,color:#1a3a5c
    style Gateway fill:#f6f0ff,stroke:#7c5cd6,color:#3a2a5c
    style Knowledge fill:#fffbea,stroke:#d9a514,color:#5c4a1a
    style Channels fill:#f0fdf4,stroke:#34a853,color:#1a4a2c

一句话总结：所有下游 AI 应用都指向 WaLiAPI —— 它完成协议翻译、安全审计、负载均衡与日志审计，再把请求转发给你配置的 API 渠道、免费渠道或账号渠道；某个渠道额度用尽或故障时自动切换到下一个，AI 工具全程无感。网关内置 RAG 知识库与 LLM-Wiki 知识引擎，Agent 可通过 MCP / REST 直接检索私有知识，知识服务的模型调用同样走渠道调度与审计。

🎁 免费渠道开箱即用

不花一分钱也能跑起来。WaLiAPI 提供两类免费渠道：

1. 免 Key 内置渠道（零配置）

首次启动时自动预建进「渠道管理」，无需注册、无需 Key，保存密钥后即可调用：

种子渠道仅添加一次，删除后不会自动加回；你可以像普通渠道一样编辑、启停或参与调度。

2. 免费层渠道预设（注册领 Key）

「新建渠道」中选择以下预设，按界面上的「获取 API Key」链接注册即用，模型清单支持「同步上游模型」拉取（自动过滤免费可用模型）：

此外，已有渠道也带免费层：Google Gemini（AI Studio 免费层，Flash 系列每日 100 万 token，15 RPM）与智谱 GLM（glm-4.7-flash 等 Flash 系列免费）的预设描述中已标注免费层说明与注册入口。

💡 免费渠道额度与速率各有约束，超额时上游返回 429，网关会自动切换到下一个可用渠道。此外，通过「Auth 账号」OAuth 登录的账号渠道（如 Antigravity、Codex、Kimi、Qoder）也可使用账号自带额度，部分供应商提供免费或订阅内额度。

🌟 为什么选择 WaLiAPI

• 🔌 多协议统一入口 —— 下游可以用 OpenAI Chat Completions、OpenAI Responses、Anthropic Messages 三种协议接入，网关内部完成双向转换，上游渠道无感知。Claude Code 可以跑 DeepSeek，Codex 可以跑 Kimi，一切由你编排。
• ⚖️ 不浪费每一分额度 —— 渠道按优先级 + 权重负载均衡，单渠道支持多 API Key 加权轮询；额度用尽、渠道故障自动切换下一个候选，额度可直观查看（如 Antigravity 各模型剩余额度与重置时间）。
• 🛡️ 让你清楚知道 AI 在说什么 —— 每一次请求/响应完整落库，可按关键词、密钥、渠道、模型、Trace ID 检索；内置 25+ 条安全规则，自动扫描敏感信息泄露、路径暴露、Unicode 隐写，支持只审计 / 警告 / 脱敏 / 阻断四种策略。
• 📚 不止是网关 —— 内置知识库 RAG 引擎（tree-sitter 代码符号感知分块、HNSW + FTS5 混合检索）、Wiki 知识引擎和 MCP Server（29 个工具），让你的 AI Agent 能直接检索私有知识。
• 🏠 数据完全本地化 —— 桌面端本地运行，SQLite 存储，数据不出你的电脑；同时提供 Docker / headless 服务端，适合团队服务器与私有化部署。

💡 推荐配合 WaLiCode 编码使用：https://walicode.xiaofuge.cn

• Github：https://github.com/fuzhengwei/WaLiAPI
• Gitcode：https://gitcode.com/fuzhengwei/WaLiAPI

---

📑 目录

• 快速开始
• 免费渠道开箱即用
• 工作原理
• 核心功能
• 多协议接入
• 技术栈
• 项目结构
• 安全边界与威胁模型
• 版本历史
• 贡献者
• 许可证

---

🚀 快速开始

WaLiAPI 提供两种部署方式：桌面端安装（适合个人开发者在本地使用）和 Docker 部署（适合团队或云服务器长期运行）。

方式一：桌面端安装（推荐个人使用）

1. 下载安装包

从 GitHub Releases 或网盘下载对应平台安装包：

• GitHub: https://github.com/fuzhengwei/WaLiAPI/releases
• 网盘: https://drive.weixin.qq.com/s?k=ACMA4AfQABU4S23jg8#/

2. 配置渠道

打开 WaLiAPI →「渠道管理」→「新建渠道」→ 填写名称、Base URL、API Key、支持的模型 → 保存。

使用 Antigravity OAuth 时，在「Auth 账号」登录后可查看各模型的已用、剩余额度和上游返回的重置时间；点击「刷新额度」可立即更新。额度百分比来自 Antigravity 模型目录的 remainingFraction，不代表具体 Token 数量。

3. 创建密钥

「API 密钥」→「新建密钥」→ 生成 sk-waliapi-* 格式的本地访问令牌。

4. 下游接入

在 ChatBox / NextChat / OpenAI SDK / WaLiCode 中配置：

• Base URL: http://127.0.0.1:8777/v1
• API Key: 创建的 sk-waliapi-... 密钥

5. 应用配置（可选）

在「应用配置」页面选择已安装的 AI 编程工具，一键写入网关地址和密钥，无需手动编辑配置文件。

其中 Claude Code 使用的是 WaLiAPI 数据面 Bearer 网关（写入单一 ANTHROPIC_AUTH_TOKEN，值为所选真实密钥；不会写入 ANTHROPIC_API_KEY）：应用配置会增量更新 ~/.claude/settings.json，保留已有环境变量、权限和模型选择，并在首次写入前 保留可恢复的原文件备份。重复应用不会覆盖该备份；点击恢复即可回到写入前的 原始内容，若文件原本不存在则会删除本次创建的文件。

Claude Code 的网关密钥不等于 Anthropic 账号登录状态；配置写入后请重启客户端并发送一条消息验证。 发送失败或出现「Not logged in」应按故障排查，不能忽略。只有 需要使用 Anthropic 账号直连时才应登录。对于 Claude Code 目录未知的非 Claude 模型，WaLiAPI 只会在已有可信模型元数据时写入上下文窗口；没有可信窗口时保留 Claude Code 默认值，不会把未知模型擅自声明为 1M。需要自定义窗口时，请在 settings.json 中明确设置 CLAUDE_CODE_MAX_CONTEXT_TOKENS 与不大于它的 CLAUDE_CODE_AUTO_COMPACT_WINDOW，用户值会优先于自动兼容值。

方式二：Docker 部署（推荐云服务器/团队使用）

WaLiAPI 提供 Docker 镜像，适合部署到 Linux 云服务器长期运行。镜像采用多阶段构建：Node/pnpm 编译前端，Rust 编译服务端二进制，运行时使用非 root 用户；SQLite 数据持久化在 /data。

快速启动

使用 Docker Hub 镜像 fuzhengwei/waliapi 一键部署：

# 拉取镜像
docker pull fuzhengwei/waliapi:latest

# 生成管理令牌
export WALIAPI_ADMIN_TOKEN="$(openssl rand -hex 32)"
export WALIAPI_MCP_TOKEN="$(openssl rand -hex 32)"

# 启动容器 
docker run -d --name waliapi \
  -p 127.0.0.1:8777:8777 \
  -v waliapi-data:/data \
  -e WALIAPI_ADMIN_TOKEN \
  -e WALIAPI_MCP_TOKEN \
  fuzhengwei/waliapi:latest

docker run -d --name waliapi \
  -p 127.0.0.1:8777:8777 \
  -v waliapi-data:/data \
  -e WALIAPI_ADMIN_TOKEN \
  -e WALIAPI_MCP_TOKEN \
  registry.cn-hangzhou.aliyuncs.com/xfg-studio/waliapi:0.2.5-amd64

# 验证服务
 curl http://127.0.0.1:8777/health

使用 Docker Compose

从源码构建部署（也可直接使用上面的镜像）：

git clone https://github.com/fuzhengwei/WaLiAPI.git
cd WaLiAPI
export WALIAPI_ADMIN_TOKEN="$(openssl rand -hex 32)"
export WALIAPI_MCP_TOKEN="$(openssl rand -hex 32)"
docker compose up -d --build
curl http://127.0.0.1:8777/health

配置说明

Web 管理面板的前端静态资源已内嵌进 waliapi-web 二进制（rust-embed），无需单独的静态资源目录。

反向代理与 HTTPS

Compose 默认只发布到宿主机 127.0.0.1（可用 WALIAPI_BIND / WALIAPI_PORT 变量覆盖），生产环境不要把端口直接暴露到公网。推荐使用 Caddy 或 Nginx 终止 HTTPS 后反代到 127.0.0.1:8777。Caddy 配置域名后会自动申请和续期证书，示例配置见 deploy/caddy/Caddyfile.example。

认证体系

后台会话、管理 Token 和 API Key 的权限分别管理：

• Web 管理面板：管理员用户名/密码登录会话（首次启动自动生成初始密码，存于数据目录 INITIAL_PASSWORD 文件）
• RAG 查询：在“密钥 → 知识库查询权限”勾选允许访问的 RAG，使用同一个 API Key 调用 REST / MCP；无需设置环境变量 Token。旧 Key 默认没有知识库权限。
• KB/Wiki REST 管理操作：WALIAPI_ADMIN_TOKEN（Authorization: Bearer ）；不接受普通 API Key。
• MCP（/mcp）：已授权 API Key 可用无会话 HTTP POST 调用 5 个 RAG 查询工具，目标库还须开启 MCP；管理工具、Wiki 和旧版 SSE 继续使用 WALIAPI_MCP_TOKEN。
• 数据面 API（/v1/*）：后台创建的 sk-waliapi-* 密钥

# 将已授权的 API Key 保存到 WALIAPI_API_KEY 环境变量
curl -H "Authorization: Bearer $WALIAPI_API_KEY" http://127.0.0.1:8777/api/kb
curl http://127.0.0.1:8777/api/kb/ask \
  -H "Authorization: Bearer $WALIAPI_API_KEY" -H "Content-Type: application/json" \
  -d '{"kb_id":"你的知识库 ID","question":"你的问题","model":"已授权的生成模型"}'

RAG 的“服务 → MCP”页可选择已授权 Key 测试 REST / MCP 连接；测试不调用模型。查询必须指定 kb_id，top_k 为 1–50，向量检索与问答的全部模型调用沿用该 Key 的模型、渠道限制和额度，Embedding 也会记录在该 Key 的日志中。API Key 暂不支持 deep_research，也不能读取或写入共享会话历史。

宽松 CORS 只作用于数据面 /v1/* 路由；KB/Wiki/MCP 服务路由与管理面板不附带跨域允许头，任意网页无法跨域读取知识资产。反向代理只负责 TLS 和转发，不得移除或绕过认证头。绑定非回环地址而缺少上述 token 时，启动日志会输出醒目告警。

数据备份与运维

• 保持单实例运行（SQLite 不支持多个写入实例共享同一数据目录）
• 定期在停机窗口或使用 SQLite 一致性备份方式备份 /data（systemd 部署为 /var/lib/waliapi）
• 升级前保留可回滚副本
• 管理员 token、渠道密钥和数据库备份都属于敏感数据，应限制文件权限并通过 HTTPS 传输

---

🔄 工作原理

WaLiAPI 作为本地网关，在下游 AI 应用和上游模型供应商之间做协议翻译、负载均衡、安全审计和日志记录。同时内置知识库引擎、Wiki 知识引擎和 MCP Server，让 AI Agent 能直接检索私有知识。

下面是完整的内部架构（含知识库 / Wiki / MCP 服务子系统）：

请求转发流程

graph TD
    subgraph Downstream[下游 AI 应用]
        A1[WaLiCode]
        A2[Claude Code]
        A3[Codex CLI]
        A4[Gemini CLI]
        A5[OpenClaw]
        A6[ChatBox / NextChat]
    end

    Downstream -->|"OpenAI / Anthropic / Responses 协议Authorization: Bearer sk-waliapi-*"| Gateway

    subgraph Gateway[WaLiAPI 本地网关]
        B[协议转换层OpenAI Chat · Responses · Anthropic双向转换]
        C[安全审计引擎风险扫描 · 脱敏/阻断 · 规则引擎]
        D[渠道调度器优先级+权重 · 故障切换 · 模型映射]
        E[适配器层OpenAI · Claude · DeepSeekGemini · Custom]
        F[审计日志记录请求/响应体 · Token 统计 · Trace ID]

        B --> C --> D --> E
        C --> F

        subgraph KBService[知识库 & Wiki & MCP 服务]
            G1[文档解析Markdown / Code / PDF]
            G2[智能分块器滑动窗口 · 符号感知]
            G3[向量化复用渠道 Embedding]
            G4[HNSW 索引向量检索 + FTS5 混合]
            G5[RAG 引擎混合检索 → 重排 → 生成回答]
            G6["MCP ServerStreamable HTTP + SSE29 个工具 [KB 13 + Wiki 16]"]
            G7[Wiki 引擎结构化知识库 · frontmatter 标签wikilinks 图谱 · 摄入管道]

            G1 --> G2 --> G3 --> G4
            G4 --> G5
            G4 -.-> G6
            G7 -.-> G6
        end
    end

    E -->|HTTPS| Upstream

    subgraph Upstream[上游模型供应商]
        U1[OpenAI]
        U2[Claude]
        U3[DeepSeek]
        U4[Gemini]
        U5[通义 · 智谱 · Moonshot · StepFun · 豆包 · Ollama]
    end

知识库 RAG 流程

MCP 工具服务

---

🎯 核心功能

🔌 多渠道管理

• 支持 11 种渠道类型：OpenAI、DeepSeek、Claude、Gemini、智谱、通义、Moonshot、阶跃星辰 StepFun、豆包、Ollama 及自定义渠道
• 优先级 + 权重的负载均衡策略，自动故障切换
• 多 Key 负载均衡：单个渠道可配置多个 API Key，每个 Key 独立设置权重，请求按权重随机选择 Key 转发，分散单渠道并发压力
• 渠道复制：一键复制现有渠道配置，快速创建相似渠道，免去重复配置
• 模型映射（渠道级别 model mapping），下游模型名自动映射到上游实际模型
• 渠道连通性测试，实时显示延迟与错误信息
• 渠道统计：调用次数、Token 消耗、成功率、平均延迟

🔑 密钥管理

• 为下游应用生成 sk-waliapi-* 格式的本地访问密钥
• 支持配额限制与启用/禁用
• 每个密钥展示调用次数、成功率、Token 消耗、平均延迟

📊 仪表盘

• 6 项核心指标一目了然：今日请求、今日 Token、累计请求、累计 Token、活跃渠道、平均延迟
• 服务可用率徽章，颜色分级（绿/黄/红）实时反映健康度
• 运维建议根据当前数据动态生成（延迟超阈值建议排查、渠道不足建议启用等）

📝 审计日志

• 完整记录每次 API 调用：请求体、响应体、模型参数、工具调用、Token 消耗、状态码
• 支持按关键词、密钥、渠道、模型、日期范围、Trace ID 搜索筛选
• 请求/响应 JSON 标签页切换，Trace ID 默认折叠可展开
• 日志编号自增，方便定位与引用
• 自动刷新：页面可见时每 5 秒静默轮询，新日志自动出现，无需手动刷新
• 日志清理：按日期删除 / 一键清空

🛡️ 安全审计中心

• 风险检测引擎：自动扫描请求中的敏感信息泄露（API Key、私钥、JWT、Cookie、Bearer Token）、敏感文件路径（~/.ssh、.env、云凭据）、Unicode 隐写字符（零宽字符、方向控制字符）、可疑工具调用（curl 外联、管道上传）、网络风险（公网 IP 探测、Webhook/隧道域名）、追踪像素与风控指纹
• 风险等级：clean / info / low / medium / high / critical，综合评分 0–100
• 策略模式：只审计 / 警告 / 脱敏 / 阻断，默认只审计不影响请求
• 规则管理：内置 25+ 条风险规则 + 自定义黑白名单（域名/工具/路径/关键词）

📚 知识库引擎

• 文档解析：Markdown、代码文件（TS/JS/Python/Rust/Go/Java 等 20+ 语言）、PDF、JSON/YAML/CSV
• 代码符号感知：基于 tree-sitter 提取函数、类、结构体等符号信息，分块时保留语义边界
• 智能分块：滑动窗口 + 重叠分块，符号感知避免截断函数体
• 向量化：复用 WaLiAPI 渠道调度获取 Embedding，无需额外配置
• HNSW 向量索引：轻量级分层导航小世界图，O(log n) 检索复杂度，适合桌面级数据量（≤100K 切片）
• FTS5 混合检索：向量语义检索 + SQLite FTS5 全文检索加权融合，支持三种模式（向量 / 关键词 / 混合）
• RAG 问答：检索 Top-K 片段 + 对话历史 → 网关转发至 LLM → 生成回答 + 来源引用
• 多源导入：Git 仓库克隆导入、URL 批量导入、本地目录扫描导入
• 会话管理：按知识库维度的对话历史记录与清除

📓 Wiki 知识引擎

• 结构化知识库：以项目为单位组织 Wiki，页面按 Markdown + frontmatter 管理，支持目录层级
• 文档摄入管道：源文件解析 → 结构化页面生成 → 自动提取 frontmatter 标签和 [[wikilinks]] → 摄入状态机（pending / ingested / failed）
• 页面管理：CRUD 操作、按路径/标题/内容搜索、按标签筛选
• Wiki 问答：检索相关页面 → LLM 生成回答 + 来源引用
• 知识图谱：页面（节点）+ wikilinks（边）构成图谱，可视化知识关联
• 标签体系：从 frontmatter 自动提取标签，按频率排序
• 多源管理：Wiki 源文件列表、添加、删除、摄入

🔗 MCP Server

• 内置 Model Context Protocol Server，通过 /mcp 端点对外提供 29 个工具（知识库 13 + Wiki 16）
• 支持 Streamable HTTP（POST JSON-RPC）和 SSE（GET 升级）两种传输模式
• 兼容 Claude Desktop、OpenClaw 等支持 MCP 协议的 AI Agent
• 知识库工具（13 个）：搜索、RAG 问答、读取文档、知识库 CRUD、文档上传/删除、索引管理、多源导入
• Wiki 工具（16 个）：项目 CRUD、页面 CRUD、搜索、问答、标签、图谱、源文件管理、摄入

⚙️ 设置中心

• Tab 切换式布局：安全审计 / 服务配置 / 通用设置 / 界面设置 / 重试策略
• 深色 / 浅色 / 跟随系统主题切换
• 最小化到托盘、关闭到托盘、开机自启
• 失败自动重试策略配置（默认 2 次）

🔧 应用配置

• 一键将 WaLiAPI 网关地址和密钥写入 8 款 AI 编程工具的配置文件： Claude Code、Codex CLI、Gemini CLI、Claude Desktop、OpenCode、OpenClaw、Hermes Agent、WaLiCode
• 自动检测已安装应用，支持配置预览、写入、清除、打开配置目录

📦 导入导出

• 渠道配置批量导出为 JSON 备份
• 支持导入 WaLiCode 备份文件恢复渠道配置

📡 流式响应

• 完整 SSE 流式转发，兼容 ChatBox / NextChat / OpenAI SDK 等下游客户端
• 流式使用量解析（累积 input/output tokens）

---

🔗 多协议接入

WaLiAPI 在网关层做协议翻译，入口多协议，出口统一为 OpenAI Chat Completions，上游渠道无感知。

接入示例（以 OpenAI 协议为例）：

curl http://127.0.0.1:8777/v1/chat/completions \
  -H "Authorization: Bearer sk-waliapi-xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

接入示例（以 Anthropic 协议为例）：

curl http://127.0.0.1:8777/v1/messages \
  -H "x-api-key: sk-waliapi-xxxx" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

💡 在「接入示例」页面可查看 cURL / Python / Node.js / TypeScript / Rust / Java 共 5 平台 × 3 协议 = 15 套代码示例。

---

🏗️ 技术栈

---

📁 项目结构

WaLiAPI/
├── src/                              # 前端源码
│   ├── pages/
│   │   ├── DashboardPage.tsx         # 仪表盘
│   │   ├── ChannelsPage.tsx          # 渠道管理
│   │   ├── AuthChannelsPage.tsx      # Auth 账号管理
│   │   ├── ApiKeysPage.tsx           # 密钥管理
│   │   ├── LogsPage.tsx              # 审计日志
│   │   ├── KnowledgeBasePage.tsx     # 知识库 + Wiki + MCP 服务
│   │   ├── UsagePage.tsx             # 接入示例
│   │   ├── SettingsPage.tsx          # 设置中心
│   │   └── AppConfigPage.tsx        # 应用配置
│   ├── components/                   # 通用组件
│   │   ├── ChannelForm.tsx           # 渠道表单
│   │   ├── ImportDialog.tsx          # 导入对话框
│   │   ├── MappingSection.tsx        # 模型映射组件
│   │   ├── UpdateChecker.tsx         # 应用更新检查
│   │   ├── auth/                     # Auth 账号组件
│   │   ├── channel-form/             # 渠道表单子组件
│   │   └── layout/                   # 布局组件
│   ├── hooks/                        # 自定义 Hooks
│   ├── lib/                          # 工具库 (api.ts, constants.ts)
│   └── types/                        # TypeScript 类型定义
├── src-tauri/                        # 后端源码
│   ├── src/
│   │   ├── server/                   # HTTP 服务器
│   │   │   ├── router.rs             # 路由定义 (含服务注册)
│   │   │   └── handlers.rs            # 请求处理器
│   │   ├── adaptor/                  # 渠道适配器
│   │   │   ├── mod.rs                # Adaptor Trait + 配置
│   │   │   ├── openai.rs             # OpenAI 适配器
│   │   │   ├── claude.rs             # Claude 适配器
│   │   │   ├── deepseek.rs           # DeepSeek 适配器
│   │   │   ├── gemini.rs             # Gemini 适配器
│   │   │   └── custom.rs            # 自定义适配器
│   │   ├── protocol/                 # 协议转换层 (v0.2.1 结构化重构)
│   │   │   ├── mod.rs                # 双向格式转换
│   │   │   ├── sse_bridge.rs         # SSE 流桥接 (字节级重组 · CJK 安全)
│   │   │   ├── codec/                # 编解码器 (目录化)
│   │   │   │   ├── chat/             # Chat 协议编解码
│   │   │   │   ├── messages/         # Anthropic Messages 编解码
│   │   │   │   ├── responses_codec/  # Responses API 编解码
│   │   │   │   └── directions/       # 跨协议方向转换
│   │   │   │       ├── messages_to_responses/
│   │   │   │       └── responses_to_messages/
│   │   │   └── responses.rs          # Responses SSE 流式
│   │   ├── core/                     # 核心逻辑
│   │   │   ├── proxy.rs              # 代理转发 + 安全扫描 + 重试
│   │   │   ├── dispatcher.rs         # 渠道调度 (优先级/权重/故障切换)
│   │   │   ├── endpoint_executor/    # 端点执行器
│   │   │   │   ├── driver.rs         # 请求驱动 (日志写入/重试/流式)
│   │   │   │   ├── sse.rs            # SSE 流处理
│   │   │   │   └── estimate_usage.rs # Token 用量估算
│   │   │   └── auth_provider/        # Auth 账号管理
│   │   │       ├── service.rs        # Auth 服务
│   │   │       ├── maintenance.rs    # Token 维护/刷新
│   │   │       ├── codex_login.rs    # Codex 登录流程
│   │   │       ├── codex_backend.rs  # Codex 后端对接
│   │   │       ├── kimi_login.rs     # Kimi 设备 OAuth 登录
│   │   │       ├── kimi_backend.rs   # Kimi 后端对接
│   │   │       ├── spec.rs           # Provider 元数据与协议快照
│   │   │       └── types.rs          # Auth 通用类型
│   │   ├── security/                 # 安全审计
│   │   │   ├── scanner.rs            # 风险扫描引擎
│   │   │   ├── rules.rs              # 规则定义
│   │   │   ├── redact.rs             # 脱敏处理
│   │   │   └── mod.rs                # 安全设置
│   │   ├── services/                 # 服务层
│   │   │   ├── mod.rs                # Service Trait + 注册表
│   │   │   ├── knowledge/            # 知识库服务
│   │   │   │   ├── parser.rs         # 文档解析 (MD/Code/PDF/JSON)
│   │   │   │   ├── code_parser.rs    # tree-sitter 代码符号提取
│   │   │   │   ├── splitter.rs       # 智能分块器
│   │   │   │   ├── embedder.rs       # 向量化 (复用渠道调度)
│   │   │   │   ├── index.rs          # HNSW 向量索引
│   │   │   │   ├── retriever.rs      # 混合检索 (HNSW + FTS5)
│   │   │   │   ├── rag.rs            # RAG 问答引擎
│   │   │   │   ├── processor.rs      # 文档处理流水线
│   │   │   │   ├── importer.rs       # 多源导入 (Git/URL/目录)
│   │   │   │   ├── repository.rs     # 数据访问层
│   │   │   │   └── routes.rs         # 知识库路由
│   │   │   ├── wiki/                 # Wiki 知识引擎
│   │   │   │   ├── mod.rs            # WikiService 定义
│   │   │   │   ├── models.rs         # 数据模型 (Project/Page/Source)
│   │   │   │   ├── repository.rs     # 数据访问层
│   │   │   │   ├── project.rs        # 项目目录管理
│   │   │   │   ├── ingest.rs         # 文档摄入管道 (frontmatter/wikilinks)
│   │   │   │   ├── handlers.rs       # Wiki 请求处理器
│   │   │   │   └── routes.rs         # Wiki 路由
│   │   │   └── mcp/                  # MCP Server
│   │   │       ├── mod.rs            # MCP Service 定义
│   │   │       └── handlers.rs       # JSON-RPC 工具处理 (29 个工具)
│   │   ├── commands/                 # Tauri Commands
│   │   │   ├── channel.rs            # 渠道管理
│   │   │   ├── api_key.rs            # 密钥管理
│   │   │   ├── auth.rs              # Auth 账号管理
│   │   │   ├── log.rs                # 日志管理
│   │   │   ├── stats.rs              # 统计数据
│   │   │   ├── settings.rs           # 设置管理
│   │   │   ├── security.rs           # 安全规则
│   │   │   ├── knowledge_base.rs     # 知识库命令
│   │   │   ├── wiki.rs              # Wiki 命令
│   │   │   ├── services.rs           # 服务状态
│   │   │   ├── app_config.rs         # 应用配置 (8 款工具)
│   │   │   ├── import_export.rs      # 导入导出
│   │   │   └── server.rs             # 服务控制
│   │   ├── db/                       # 数据库层
│   │   │   ├── mod.rs                # Database 初始化
│   │   │   ├── models.rs             # 数据模型
│   │   │   └── repository.rs         # 数据访问
│   │   ├── utils/                    # 工具函数
│   │   ├── channel_presets.rs        # 渠道预设注册表
│   │   ├── lib.rs                    # 入口 + 系统托盘
│   │   └── main.rs                   # main 函数
│   ├── migrations/                   # 数据库迁移 (27 个)
│   └── tauri.conf.json               # Tauri 配置
└── package.json

---

🛡️ 安全边界与威胁模型

WaLiAPI 定位为本地 / 内网优先的 LLM 网关。公网部署前请先阅读本节，并确认边界假设与你的部署环境一致。

凭证与权限：

明文密钥存储（知情声明）：上游渠道密钥与网关 API Key 以明文存储在本地 SQLite 数据目录中——数据目录的文件系统权限就是安全边界，本项目不提供静态加密。渠道导出文件包含明文密钥（界面有明示警告），请仅在受控环境操作。网关密钥在管理界面仅显示掩码，复制等显式动作才按需取回全量。

安全扫描的边界（尽力而为的 DLP）：内置风险扫描引擎（敏感信息、路径、Unicode 隐写等规则）是启发式检测，按策略支持只审计 / 警告 / 脱敏 / 阻断，定位为「尽力而为的数据泄露防护」，不构成完整的内容安全方案。响应侧扫描覆盖非流式、流式与原生 Anthropic 路径，为尽力而为语义——扫描异常不阻断响应转发；扫描预算超限按 fail-closed 拒绝请求。

CORS 作用域：宽松 CORS（Access-Control-Allow-Origin: *）仅作用于数据面网关路由（API Key 鉴权的 /v1/*——跨域调用是网关的设计用法）。管理面、KB/Wiki REST 与 MCP 端点不附带宽松 CORS，浏览器跨域不可读取其响应；管理面另带 CSRF 防护（变更类请求要求 X-Requested-With 头）。

公网部署建议：Docker 默认仅绑定 127.0.0.1；确需公网暴露时，由 Caddy/Nginx 终止 TLS 后反代，注入强 WALIAPI_ADMIN_TOKEN / WALIAPI_MCP_TOKEN，不要移除认证头；SQLite 不支持多实例写同一数据目录，保持单实例。

视觉能力路由（长期方案，#15）：当前版本对「请求含图片块而上游渠道以 400 拒绝」的场景，在错误信息中追加诊断提示（该渠道疑似不支持图片），不改变路由行为（fail-open）。基于渠道能力标记（supports_vision）的故障转移跳过是长期方案，见 docs/reliability-fixes-prd.md。

---

📌 版本历史

v0.4.5 (2026-10-22)

免费渠道对接（@fuzhengwei）

• ✨ 内置免费渠道种子，开箱即用：启动时自动预建 OpenCode 免费车道与 Kilo 免费池两条免 Key 免费渠道（services/builtin_channels.rs），零配置即可调用；每实例仅种子一次，删除后不会自动加回，幂等兜底不产生重复渠道
• ✨ OpenCode 免费车道专用执行器：新增 endpoint_executor/opencode_lane.rs，就地把请求整形为上游 v2 客户端指纹门禁接受的形状（公开令牌 public、固定 UA / 客户端头、会话 id 降序编码铸造 + 会话池轮换、read / shell 工具指纹逐字声明与同名工具改名），绕开 403 FreeTierError
• ✨ 新增 11 个免费层渠道预设：Groq / Cerebras / Mistral / NVIDIA NIM / OpenRouter / GitHub Models / Hugging Face / SambaNova / Cohere（国际）与 ModelScope 魔搭 / SiliconFlow 硅基流动（国内），预设新增 key_signup_url「获取 API Key」跳转链接（前端在 Key 配置上方渲染注册提示），配套基线测试守护
• ✨ 免费模型同步过滤：Kilo 同步只保留 isFree == true 模型、OpenCode 同步只保留 -free 后缀模型（付费模型免 Key 调用必 401，同步进来只会误导），各自新增回归测试
• ✨ 免费层标注补齐：Google Gemini（AI Studio Flash 免费层每日 100 万 token）与智谱 GLM（glm-4.7-flash 等免费）预设描述补充免费层说明并补注册链接
• 📝 免费渠道对接方案文档：新增 docs/free-channel-integration-plan.md；全量 cargo fmt（无功能变化）

Wiki 重建与体验（PR #166，@freakojc）

• ✨ Wiki index/log 累积修复：程序化重建（services/wiki/rebuild.rs）——程序化重建索引 + LLM 语义归组 + log 一致性回溯
• 🎨 Wiki 页面 tab 体验修复与增强：页面滚动位置保持、下拉样式统一、搜索文档能力增强

WorkBuddy 兼容（PR #168，@mw）

• 🐛 WorkBuddy 响应数据兼容性处理：后端响应解析与 SSE 流式处理兼容加固

其他

• 📝 README 完善：顶部新增「免费渠道开箱即用」提示；「30 秒看懂」架构图补充内置知识服务（RAG / LLM-Wiki）与三类上游渠道（API 渠道 / 免费渠道 / 账号渠道）分流；贡献者数据同步
• 🔧 版本号统一升级至 0.4.5（package.json / Cargo.toml / tauri.conf.json / Cargo.lock）

v0.4.4 (2026-10-18)

Wiki 备份与全链路修复（PR #163 #164，@freakojc）

• ✨ Wiki 项目导出 / 导入 zip 备份恢复：新增 services/wiki/backup.rs，将页面 Markdown、源文件、图片资产（含 token）与核心数据打包为 zip 备份；新增导出 / 导入命令与管理端路由，前端新增「导出 Wiki 备份」弹窗
• 🐛 ask_wiki 全链路修复：修复中文标点按字节切片导致的 panic、图片 URL 嵌套解析、推理档位审计归因到真实 API Key、MCP 工具描述双 http:// 前缀、渠道导入导出图标方向

协议转换（PR #165，@ymsy2021）

• 🐛 Responses→Chat 转换缺省时不再注入 max_tokens=4096：Codex 等 Responses 客户端从不发送 max_output_tokens，旧转换硬编码 max_tokens=4096 导致长回答被静默腰斩（finish_reason=length，且预算含 reasoning tokens）；现仅在请求显式携带时映射注入（修复 #162）

UI 统一（@fuzhengwei）

• 🎨 推理档位下拉框统一：知识库设置、新建 Wiki 项目弹窗与 Wiki 项目设置三处「推理档位（思考级别）」由原生 `` 替换为统一自定义 Select 组件，与整体 UI 语言一致

其他

• 📝 README 贡献者数据同步：新增贡献者 ymsy2021（PR #165），更新小傅哥（362 commits）、Jason（24 commits，PR #163 #164）提交数与代码变更统计
• 🔧 版本号统一升级至 0.4.4（package.json / Cargo.toml / tauri.conf.json / Cargo.lock）

---

👥 贡献者

WaLiAPI 由一个热情的开源社区共同构建。感谢以下开发者的代码贡献（按贡献量排序）。

---

📄 License

MIT

本项目基于 MIT 开源协议发布，具有以下权利和说明：

✅ 你可以

• 商业使用：可将 WaLiAPI 用于商业项目、企业内部工具或 SaaS 服务，无需支付授权费用
• 个人使用：个人开发者可免费下载、安装和使用
• 二次开发：可基于本项目进行修改、扩展和定制，满足业务需求
• 分发与部署：可在组织内部或向客户分发部署
• 私有化部署：支持完全离线的私有化部署，数据不出本地

⚠️ 需要注意

• 保留原始版权声明和许可证声明
• 二次开发后的衍生项目建议开源回馈社区
• 本项目不提供任何形式的担保，使用风险自负
• 如将 WaLiAPI 作为商业产品的一部分分发，建议在产品文档中注明基于 WaLiAPI 构建

💡 常见场景

---