7.4 billion tokens per month. 34 free LLM providers. 635 free model endpoints. All behind one /v1 endpoint, plus any custom OpenAI-compatible endpoint. Smart routing, automatic failover, encrypted keys. Personal experimentation only.
TypeScript
docs: second sweep — stale link texts, changelog hashes that never reached main, missing index row, glossary (#1168)
Tashfeen7331d7ac773a
diff --git a/README.md b/README.mdindex 1d75a8b1..b8953feb 100644--- a/README.md+++ b/README.md@@ -185,7 +185,7 @@ Open http://localhost:3001, add your provider keys on the **Keys** page, reorderOn Windows, the easiest path is the desktop **[`.exe` installer from Releases](https://github.com/tashfeenahmed/freellmapi/releases/latest)** (below). On Android, see the experimental [Termux guide](docs/en/install/02-android-termux.md).-Everything else — Docker Compose, local development, declarative startup config, production builds, LAN access, and backups — is in **[docs/install.md](docs/en/install/01-install.md)**.+Everything else — Docker Compose, local development, declarative startup config, production builds, LAN access, and backups — is in **[docs/en/install/01-install.md](docs/en/install/01-install.md)**.## Desktop app@@ -193,7 +193,7 @@ A native menu-bar app lives in [`desktop/`](./desktop): the entire router + dash-**[Download from Releases](https://github.com/tashfeenahmed/freellmapi/releases/latest)** — the macOS `.dmg` and the Windows `.exe` installer are attached to every release. No account or password to set up: the only credential you need is the unified API key from the tray popover. Build-from-source steps and where your data lives: [docs/install.md](docs/en/install/01-install.md#desktop-app).+**[Download from Releases](https://github.com/tashfeenahmed/freellmapi/releases/latest)** — the macOS `.dmg` and the Windows `.exe` installer are attached to every release. No account or password to set up: the only credential you need is the unified API key from the tray popover. Build-from-source steps and where your data lives: [docs/en/install/01-install.md#desktop-app](docs/en/install/01-install.md#desktop-app).## Works with OpenAI-compatible clients@@ -335,7 +335,7 @@ Request volume, success rate, tokens in and out, average latency, and per-provid-One request in, the best free model out: the router picks the highest-priority model with a healthy key that's under all its rate limits, decrypts the key in memory, and calls the provider — on a 429/5xx it cools that key down and retries the next model in your chain. The component walkthrough, routing internals, and operational details live in **[docs/architecture.md](docs/en/architecture/00-high-level-index.md)**.+One request in, the best free model out: the router picks the highest-priority model with a healthy key that's under all its rate limits, decrypts the key in memory, and calls the provider — on a 429/5xx it cools that key down and retries the next model in your chain. The component walkthrough, routing internals, and operational details live in **[docs/en/architecture/00-high-level-index.md](docs/en/architecture/00-high-level-index.md)**.## FAQ@@ -347,11 +347,11 @@ One request in, the best free model out: the router picks the highest-priority m**How do I uninstall?** Remove the app (Trash on macOS, *Settings → Apps* on Windows, `docker compose down -v` for Docker), then delete the data directory: `%APPDATA%\FreeLLMAPI\`, `~/Library/Application Support/FreeLLMAPI/`, or `~/.config/FreeLLMAPI/`. Uninstalling never touches that folder on its own.-Longer answers, per install method: **[docs/install.md#faq-passwords-logs-uninstall](docs/en/install/01-install.md#faq-passwords-logs-uninstall)**.+Longer answers, per install method: **[docs/en/install/01-install.md#faq-passwords-logs-uninstall](docs/en/install/01-install.md#faq-passwords-logs-uninstall)**.## Limitations-Stacking free tiers has real trade-offs: no frontier models, variable latency, no SLA — and the effective intelligence of the endpoint dips late in the day as top models hit their daily caps, then resets at UTC midnight. Read the honest list in **[docs/architecture.md#limitations](docs/en/architecture/00-high-level-index.md#limitations)** before building anything real on this.+Stacking free tiers has real trade-offs: no frontier models, variable latency, no SLA — and the effective intelligence of the endpoint dips late in the day as top models hit their daily caps, then resets at UTC midnight. Read the honest list in **[docs/en/architecture/00-high-level-index.md#limitations](docs/en/architecture/00-high-level-index.md#limitations)** before building anything real on this.## Contributing@@ -486,7 +486,7 @@ Contributors very welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for the dev lo**This project is for personal experimentation and learning, not production.** Free tiers exist so developers can prototype against them; they aren't a stable, supported inference substrate and shouldn't be treated as one. If you build something real on top of FreeLLMAPI, swap in a paid API before you ship. Your relationship with each upstream provider is governed by the terms you accepted when you created your account — those terms still apply when the traffic is proxied through this project, and you're responsible for complying with them.-How each provider's ToS views a personal, single-user proxy — reviewed provider by provider in May 2026 — is in [docs/architecture.md#terms-of-service-review](docs/en/architecture/00-high-level-index.md#terms-of-service-review).+How each provider's ToS views a personal, single-user proxy — reviewed provider by provider in May 2026 — is in [docs/en/architecture/00-high-level-index.md#terms-of-service-review](docs/en/architecture/00-high-level-index.md#terms-of-service-review).## Licensediff --git a/README.zh-cn.md b/README.zh-cn.mdindex 7db5984f..8e0a8af3 100644--- a/README.zh-cn.md+++ b/README.zh-cn.md@@ -177,7 +177,7 @@ curl -fsSL https://freellmapi.co/install.sh | bash在 Windows 上,最省事的方式是下面提到的桌面版 **[Releases 里的 `.exe` 安装包](https://github.com/tashfeenahmed/freellmapi/releases/latest)**。Android 上可参考实验性的 [Termux 指南](docs/zh-cn/install/02-android-termux.md)。-其余内容,包括 Docker Compose、本地开发、声明式启动配置、生产构建、局域网访问和备份,都在 **[docs/install.md](docs/zh-cn/install/01-install.md)**。+其余内容,包括 Docker Compose、本地开发、声明式启动配置、生产构建、局域网访问和备份,都在 **[docs/zh-cn/install/01-install.md](docs/zh-cn/install/01-install.md)**。## 桌面应用@@ -185,11 +185,11 @@ curl -fsSL https://freellmapi.co/install.sh | bash-**[从 Releases 下载](https://github.com/tashfeenahmed/freellmapi/releases/latest)** —— 每个版本都附带 macOS 的 `.dmg` 和 Windows 的 `.exe` 安装包。不需要注册账号或设置密码:你唯一需要的凭据就是托盘悬浮窗里的统一 API 密钥。从源码构建的步骤,以及数据存放位置,见 [docs/install.md](docs/zh-cn/install/01-install.md#桌面应用)。+**[从 Releases 下载](https://github.com/tashfeenahmed/freellmapi/releases/latest)** —— 每个版本都附带 macOS 的 `.dmg` 和 Windows 的 `.exe` 安装包。不需要注册账号或设置密码:你唯一需要的凭据就是托盘悬浮窗里的统一 API 密钥。从源码构建的步骤,以及数据存放位置,见 [docs/zh-cn/install/01-install.md#桌面应用](docs/zh-cn/install/01-install.md#桌面应用)。## 兼容 OpenAI 的客户端-任何能指定 OpenAI 兼容 base URL 的东西都能用:把它设成 `http://localhost:3001/v1`,配上仪表盘里的统一密钥。**Claude Code**、**Codex CLI**、**Cline / Roo Code**、**Continue**(含行内补全)、**Aider**、**opencode** 和 **Cursor** 在 **[docs/en/clients/01-agent-clients.md](docs/zh-cn/clients/01-agent-clients.md)** 里各有一段简短配方。此外路由器本身还兼作 MCP 服务,你的智能体可以在会话中随时查询它。+任何能指定 OpenAI 兼容 base URL 的东西都能用:把它设成 `http://localhost:3001/v1`,配上仪表盘里的统一密钥。**Claude Code**、**Codex CLI**、**Cline / Roo Code**、**Continue**(含行内补全)、**Aider**、**opencode** 和 **Cursor** 在 **[docs/zh-cn/clients/01-agent-clients.md](docs/zh-cn/clients/01-agent-clients.md)** 里各有一段简短配方。此外路由器本身还兼作 MCP 服务,你的智能体可以在会话中随时查询它。最快的配置方式是根据你服务器上实际可用的模型生成:@@ -263,7 +263,7 @@ print(resp.choices[0].message.content)print("Routed via:", resp.headers.get("x-routed-via"))```-流式、`auto:*` 路由策略、工具调用、视觉输入、Gemini 的 Google 搜索接地、嵌入,以及 Anthropic Messages 接口,连同各自的 curl 和 Python 示例,全都在 **[docs/en/api/01-rest-api.md](docs/zh-cn/api/01-rest-api.md)**。每个响应都带一个 `X-Routed-Via: <平台>/<模型>` 头,你可以据此看出实际是哪家提供方处理的。+流式、`auto:*` 路由策略、工具调用、视觉输入、Gemini 的 Google 搜索接地、嵌入,以及 Anthropic Messages 接口,连同各自的 curl 和 Python 示例,全都在 **[docs/zh-cn/api/01-rest-api.md](docs/zh-cn/api/01-rest-api.md)**。每个响应都带一个 `X-Routed-Via: <平台>/<模型>` 头,你可以据此看出实际是哪家提供方处理的。## 截图@@ -295,11 +295,11 @@ print("Routed via:", resp.headers.get("x-routed-via"))-一个请求进去,最合适的免费模型出来:路由器挑出优先级最高、密钥健康且未超出任何限流的模型,在内存中解密密钥并调用提供方;遇到 429/5xx 就让那个密钥进入冷却,然后重试你链路上的下一个模型。组件走查、路由内部实现和运维细节都在 **[docs/architecture.md](docs/zh-cn/architecture/00-high-level-index.md)**。+一个请求进去,最合适的免费模型出来:路由器挑出优先级最高、密钥健康且未超出任何限流的模型,在内存中解密密钥并调用提供方;遇到 429/5xx 就让那个密钥进入冷却,然后重试你链路上的下一个模型。组件走查、路由内部实现和运维细节都在 **[docs/zh-cn/architecture/00-high-level-index.md](docs/zh-cn/architecture/00-high-level-index.md)**。## 局限性-叠加免费额度是有实实在在的代价的:没有前沿模型,延迟不稳定,没有 SLA。而且到了一天的后半段,顶级模型陆续触及当日上限,这个端点的实际智能水平会下滑,然后在 UTC 午夜重置。在拿它做任何正经东西之前,请先读一遍 **[docs/architecture.md#limitations](docs/zh-cn/architecture/00-high-level-index.md#局限性)** 里那份诚实的清单。+叠加免费额度是有实实在在的代价的:没有前沿模型,延迟不稳定,没有 SLA。而且到了一天的后半段,顶级模型陆续触及当日上限,这个端点的实际智能水平会下滑,然后在 UTC 午夜重置。在拿它做任何正经东西之前,请先读一遍 **[docs/zh-cn/architecture/00-high-level-index.md#局限性](docs/zh-cn/architecture/00-high-level-index.md#局限性)** 里那份诚实的清单。## 参与贡献@@ -321,7 +321,7 @@ print("Routed via:", resp.headers.get("x-routed-via"))**本项目用于个人实验和学习,不适用于生产环境。** 免费额度的存在是为了让开发者拿来做原型;它们不是稳定、有支持的推理基础设施,也不该被当成这种东西。如果你要在 FreeLLMAPI 之上做真正的产品,上线前请换成付费 API。你和每家上游提供方之间的关系,受你注册账号时接受的条款约束;流量经由本项目代理时这些条款依然适用,遵守它们是你的责任。-各家提供方的服务条款如何看待一个个人的、单用户的代理,在 2026 年 5 月逐家审查过,结论在 [docs/architecture.md#terms-of-service-review](docs/zh-cn/architecture/00-high-level-index.md#服务条款审查)。+各家提供方的服务条款如何看待一个个人的、单用户的代理,在 2026 年 5 月逐家审查过,结论在 [docs/zh-cn/architecture/00-high-level-index.md#服务条款审查](docs/zh-cn/architecture/00-high-level-index.md#服务条款审查)。## 许可证diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.mdindex 20c8cbfc..bb87e4c9 100644--- a/docs/CHANGELOG.md+++ b/docs/CHANGELOG.md@@ -1,63 +1,46 @@# Changelog-## 2026-09-02 — Per-language structure+Revision history for `docs/`, derived from git commits touching this directory. Most recent first. Rows marked "landed via #N" describe work done on a contributor branch and squash-merged; the commit shown is the squash on `main`.++## 2026-09-05 — Per-language structure| Commit | Date | Summary || --- | --- | --- |-| `c108132` | 2026-09-02 | scaffold per-language en/ and zh-cn/ top-level |-| `7378adc` | 2026-09-02 | move English domains under en/ (17 domains, git mv) |-| `cbb2620` | 2026-09-02 | fix link depths after move (0 broken in en/) |-| `91c1776` | 2026-09-02 | migrate Chinese translations to zh-cn/ (10 domains) |-| `ab0d0f9` | 2026-09-02 | obliterate i18n wrapper — simple /docs/{en,zh-cn} |-| `9c679bd` | 2026-09-02 | fix zh-cn link depths |-| `4761a0b` | 2026-09-02 | fix remaining link depths |-| `5f887aa` | 2026-09-02 | translate cli and desktop domains to zh-cn |-| `13ca740` | 2026-09-02 | translate proxy, fallback, glossary to zh-cn |-| `a0a4df7` | 2026-09-02 | translate troubleshooting to zh-cn |----Revision history for `docs/`, derived from git commits touching this directory. Most recent first.+| `ef1b9ce` | 2026-09-05 | docs(zh-cn): translate the four stub pages, fix the Chinese index, anchors and language switchers (#1167) |+| `eab992f` | 2026-09-05 | docs: per-language layout `docs/{en,zh-cn}`, Chinese README, redirect stubs at the old paths (#1164). Squash of the contributor branch: scaffold `en/` and `zh-cn/`, move the 17 English domains under `en/`, migrate the Chinese translations out of `docs/i18n/zh-CN/docs/` into `zh-cn/`, translate the cli, desktop, proxy, fallback, glossary and troubleshooting domains, fix link depths. |+| `36850e8` | 2026-09-01 | docs: per-domain folders with OVERVIEW/CHANGELOG metadata (#979). Squash of the contributor branch whose rows are dated 2026-08-22 to 2026-08-25 below. |## 2026-09-02| Commit | Date | Summary || --- | --- | --- |-| `c2114c0` | 2026-09-02 | docs(proxy): create proxy domain and move Fetch Relay into it — `01-fetch-relay.md` moved from flat `fetch-relay.md`, `detectSystemProxy()` OS auto-detect, `TRUST_PROXY` |-| `26f71dd` | 2026-09-02 | docs(env): cover `PROXY_MODE`, `FETCH_RELAY_TOKEN`, `TRUST_PROXY`, `QUOTA_OBSERVATIONS_*`, `IDEMPOTENCY_TTL_MS` — full precedence chain, callout boxes |-| `8bd3acd` | 2026-09-02 | docs(api): document Idempotency-Key safe retries (`02-idempotency.md`) — replay/409/miss, fingerprint, curl example |+| `eab992f` | 2026-09-02 | docs(proxy): create proxy domain and move Fetch Relay into it — `01-fetch-relay.md` moved from flat `fetch-relay.md`, `detectSystemProxy()` OS auto-detect, `TRUST_PROXY` (landed via #1164) |+| `eab992f` | 2026-09-02 | docs(env): cover `PROXY_MODE`, `FETCH_RELAY_TOKEN`, `TRUST_PROXY`, `QUOTA_OBSERVATIONS_*`, `IDEMPOTENCY_TTL_MS` — full precedence chain, callout boxes (landed via #1164) |+| `eab992f` | 2026-09-02 | docs(api): document Idempotency-Key safe retries (`02-idempotency.md`) — replay/409/miss, fingerprint, curl example (landed via #1164) |## 2026-08-25| Commit | Date | Summary || --- | --- | --- |-| `60d03d6` | 2026-08-25 | docs(api): document video platforms (pollinations/huggingface, 5-min bound, fal queue), free-tier budget API (`GET /api/free-tier`, pool-deduped), and backups API (`GET /api/backups`, DUMP_FORMAT=1, sha256 fingerprint) |-| `b7482d4` | 2026-08-25 | docs(fallback): add named-chains domain — chain lifecycle, empty-chain authoritative 400 (`activeChainOrThrow`, e852ff1), `auto:<name>` in `GET /v1/models` (cc1e985), `profiles.auto_include_new_models` (b3bf20f), named-chain manager UI (8bb2004) |-| `5a77e44` | 2026-08-25 | docs(observability): dedupe 06-observability.md against logs viewer, cross-link both ways, add desktop `freeapi.log` file-logger note (90aaa5b) |-| `f4135a3` | 2026-08-25 | docs(providers): refresh free-tier numbers to 34 providers / 474 families / 635 endpoints (~7.4B tokens/month) in providers/OVERVIEW.md and providers/01-supported-platforms.md |+| `36850e8` | 2026-08-25 | docs(api): document video platforms (pollinations/huggingface, 5-min bound, fal queue), free-tier budget API (`GET /api/free-tier`, pool-deduped), and backups API (`GET /api/backups`, DUMP_FORMAT=1, sha256 fingerprint) (landed via #979) |+| `36850e8` | 2026-08-25 | docs(fallback): add named-chains domain — chain lifecycle, empty-chain authoritative 400 (`activeChainOrThrow`, e852ff1), `auto:<name>` in `GET /v1/models` (cc1e985), `profiles.auto_include_new_models` (b3bf20f), named-chain manager UI (8bb2004) (landed via #979) |+| `36850e8` | 2026-08-25 | docs(observability): dedupe 06-observability.md against logs viewer, cross-link both ways, add desktop `freeapi.log` file-logger note (90aaa5b) (landed via #979) |+| `36850e8` | 2026-08-25 | docs(providers): refresh free-tier numbers to 34 providers / 474 families / 635 endpoints (~7.4B tokens/month) in providers/OVERVIEW.md and providers/01-supported-platforms.md (landed via #979) |## 2026-08-23| Commit | Date | Summary || --- | --- | --- |-| `0e515ac` | 2026-08-23 | docs(meta): fix broken links from 2026-08-23 doc updates — 24 links fixed across 16 files (api/compression/clients/i18nzh) |+| `36850e8` | 2026-08-23 | docs(meta): fix broken links from 2026-08-23 doc updates — 24 links fixed across 16 files (api/compression/clients/i18nzh) (landed via #979) || `1a0ce48` | 2026-08-23 | feat(cli): setup-dsh — configure DeepSeek Harness in one command (#995) || `cf0c216` | 2026-08-23 | perf(compression): early-exit protected-span check in the per-line hot path (#990) || `74df985` | 2026-08-23 | Server log viewer in the dashboard, under an Analytics nav menu (#993) |-| `96b6f75` | 2026-08-22 | docs(meta): index providers/testing domains and log today's additions |-| `676ae20` | 2026-08-22 | docs(testing): add test matrix and compatibility-suite documentation |-| `b21ec10` | 2026-08-22 | docs(providers): add platform catalog and integration guides |-| `abe6b00` | 2026-08-22 | docs(deployment): add Docker operations and maintenance domain |-| `ac0a9ce` | 2026-08-22 | docs(env): add runtime configuration reference domain |+| `36850e8` | 2026-08-22 | docs(meta): index providers/testing domains and log today's additions (landed via #979) |+| `36850e8` | 2026-08-22 | docs(testing): add test matrix and compatibility-suite documentation (landed via #979) |+| `36850e8` | 2026-08-22 | docs(providers): add platform catalog and integration guides (landed via #979) |+| `36850e8` | 2026-08-22 | docs(deployment): add Docker operations and maintenance domain (landed via #979) |+| `36850e8` | 2026-08-22 | docs(env): add runtime configuration reference domain (landed via #979) |-## 2026-08-22--| Commit | Date | Summary |-| --- | --- | --- |-| `676ae20` | 2026-08-22 | docs(testing): add test matrix and compatibility-suite documentation |-| `b21ec10` | 2026-08-22 | docs(providers): add platform catalog and integration guides |-| `abe6b00` | 2026-08-22 | docs(deployment): add Docker operations and maintenance domain |-| `ac0a9ce` | 2026-08-22 | docs(env): add runtime configuration reference domain |## 2026-08-10 and earlierdiff --git a/docs/en/CHANGELOG.md b/docs/en/CHANGELOG.mdindex b09f7ae6..c6e1f1de 100644--- a/docs/en/CHANGELOG.md+++ b/docs/en/CHANGELOG.md@@ -4,13 +4,14 @@| Commit | Date | Summary || --- | --- | --- |-| `c108132` | 2026-09-02 | scaffold per-language en/ top-level |-| `7378adc` | 2026-09-02 | move English domains under en/ (17 domains) |-| `cbb2620` | 2026-09-02 | fix link depths after move |-| `07506ed` | 2026-09-02 | fix root flat-file violations and name collisions |-| `688a88a` | 2026-09-02 | complete desktop, cli, troubleshooting and glossary domains |-| `8bd3acd` | 2026-09-02 | document Idempotency-Key safe retries |-| `26f71dd` | 2026-09-02 | cover PROXY_MODE, FETCH_RELAY_TOKEN, TRUST_PROXY, QUOTA_OBSERVATIONS_* |-| `c2114c0` | 2026-09-02 | create proxy domain and move Fetch Relay into it |+| `ef1b9ce` | 2026-09-05 | language-switcher line on every page, root-README anchors fixed from inside docs/, cli config page path (#1167) |+| `eab992f` | 2026-09-02 | scaffold per-language en/ top-level (landed via #1164) |+| `eab992f` | 2026-09-02 | move English domains under en/ (17 domains) (landed via #1164) |+| `eab992f` | 2026-09-02 | fix link depths after move (landed via #1164) |+| `eab992f` | 2026-09-02 | fix root flat-file violations and name collisions (landed via #1164) |+| `eab992f` | 2026-09-02 | complete desktop, cli, troubleshooting and glossary domains (landed via #1164) |+| `eab992f` | 2026-09-02 | document Idempotency-Key safe retries (landed via #1164) |+| `eab992f` | 2026-09-02 | cover PROXY_MODE, FETCH_RELAY_TOKEN, TRUST_PROXY, QUOTA_OBSERVATIONS_* (landed via #1164) |+| `eab992f` | 2026-09-02 | create proxy domain and move Fetch Relay into it (landed via #1164) |Regenerate: `git log --oneline -- docs/en/`diff --git a/docs/en/api/02-idempotency.md b/docs/en/api/02-idempotency.mdindex 7c19f465..48fa9cfa 100644--- a/docs/en/api/02-idempotency.md+++ b/docs/en/api/02-idempotency.md@@ -2,7 +2,7 @@# Idempotency-Key — Safe Retries for Non-Streaming Chat Completions-> **Sources:** `server/src/services/idempotency.ts`, `server/src/routes/proxy.ts:1793-1835` (entry) + `2640-2656` (persist), `server/src/db/migrations/20260901_000001_idempotency_claims.ts`, commit `36b877d` (feature), `95bc46f` (in-flight clarification), env `IDEMPOTENCY_TTL_MS` documented in `docs/env/01-variables.md#idempotency`.+> **Sources:** `server/src/services/idempotency.ts`, `server/src/routes/proxy.ts:1793-1835` (entry) + `2640-2656` (persist), `server/src/db/migrations/20260901_000001_idempotency_claims.ts`, commit `36b877d` (feature), `95bc46f` (in-flight clarification), env `IDEMPOTENCY_TTL_MS` documented in [`docs/en/env/01-variables.md#idempotency`](../env/01-variables.md#idempotency).Non-streaming `POST /v1/chat/completions` supports an opt-in `Idempotency-Key` header so a client that times out and retries does not burn a second free-tier slot for an answer it already received. When the same key + same request content is seen again inside the replay window the gateway replays the stored response at **zero provider cost**; the same key with different content is a `409` rather than a silent wrong answer.@@ -91,7 +91,7 @@ Guarding the in-flight window would require a `pending`-claim state with its own- Read **per call** via `idempotencyTtlMs()` → `envNum('IDEMPOTENCY_TTL_MS', 24*60*60*1000)` so tests can flip it live; non-finite / negative → fallback.- `expires_at_ms = now + ttl`; stale rows are lazily swept **per `key_hash`** at the next `storeIdempotencyResult` (`DELETE ... WHERE key_hash = ? AND expires_at_ms <= ?`) and via the `idx_idempotency_claims_expires` index for range scans.-- Source of truth: `server/src/services/idempotency.ts:40-42`, `docs/env/01-variables.md#idempotency`.+- Source of truth: `server/src/services/idempotency.ts:40-42`, [`docs/en/env/01-variables.md#idempotency`](../env/01-variables.md#idempotency).---@@ -181,13 +181,13 @@ Tips:## 10. Relationship to response cache & degraded mode- **Response cache** (`services/cache.ts`, `X-FreeLLM-Cache`) is orthogonal: global, temperature-gated, in-memory LRU; idempotency is durable (SQLite), per-caller, and fingerprint-bound. Both short-circuit provider calls.-- **Degraded mode** (`docs/architecture/04-degraded-mode-and-failover.md`) disables bandit exploration but does not affect idempotency — replays still bypass routing entirely.+- **Degraded mode** ([`docs/en/architecture/04-degraded-mode-and-failover.md`](../architecture/04-degraded-mode-and-failover.md)) disables bandit exploration but does not affect idempotency — replays still bypass routing entirely.- **Failover**: only the final successful body is stored. If a request exhausts the fallback loop, nothing is stored for that key.---## Related-- `docs/env/01-variables.md#idempotency` — `IDEMPOTENCY_TTL_MS` defaults and bounds.-- `docs/architecture/04-degraded-mode-and-failover.md` — retry budget, hedging, and fallback headers that apply when a `miss` enters the loop.+- [`docs/en/env/01-variables.md#idempotency`](../env/01-variables.md#idempotency) — `IDEMPOTENCY_TTL_MS` defaults and bounds.+- [`docs/en/architecture/04-degraded-mode-and-failover.md`](../architecture/04-degraded-mode-and-failover.md) — retry budget, hedging, and fallback headers that apply when a `miss` enters the loop.- `01-rest-api.md` — OpenAI-compatible surface (`/v1/chat/completions`) and response headers (`X-Routed-Via`, `X-Fallback-Detail`).diff --git a/docs/en/api/CHANGELOG.md b/docs/en/api/CHANGELOG.mdindex 5a0481c0..850b1b5f 100644--- a/docs/en/api/CHANGELOG.md+++ b/docs/en/api/CHANGELOG.md@@ -11,7 +11,7 @@ Doc revision history for `docs/api/`, seeded from API-relevant commits.## 2026-09-02-- **docs(api): add Idempotency-Key documentation (02-idempotency.md)** — documents non-streaming `POST /v1/chat/completions` idempotency from `36b877d` / `95bc46f`: `Idempotency-Key` header (trim + `≤255` UTF-8 bytes, first value on repeat), `replay` vs `409 idempotency_key_conflict` vs `miss` via `lookupIdempotencyReplay`, fingerprint `SHA-256(model+messages+temperature/top_p/max_tokens/tools/tool_choice)`, SHA-256 key-hash storage, `X-Routed-Via: idempotency` zero-cost replay, `stream:true` bypass and `finish_reason:length` not stored, in-flight NOT deduplicated (both attempts execute; pending-claim out of scope per `95bc46f` / `idempotency.ts:17-20`), `IDEMPOTENCY_TTL_MS` 24 h (`idempotencyTtlMs` + `envNum` guard, lazy sweep per `key_hash`), `409` handling, and a `curl` timeout→retry→replay example. Sources: `server/src/services/idempotency.ts`, `server/src/routes/proxy.ts:1793-1835` + `2640-2656`, migration `20260901_000001_idempotency_claims.ts`. Updated `docs/api/OVERVIEW.md` index and added cross-ref in `docs/architecture/04-degraded-mode-and-failover.md:10`.+- **docs(api): add Idempotency-Key documentation (02-idempotency.md)** — documents non-streaming `POST /v1/chat/completions` idempotency from `36b877d` / `95bc46f`: `Idempotency-Key` header (trim + `≤255` UTF-8 bytes, first value on repeat), `replay` vs `409 idempotency_key_conflict` vs `miss` via `lookupIdempotencyReplay`, fingerprint `SHA-256(model+messages+temperature/top_p/max_tokens/tools/tool_choice)`, SHA-256 key-hash storage, `X-Routed-Via: idempotency` zero-cost replay, `stream:true` bypass and `finish_reason:length` not stored, in-flight NOT deduplicated (both attempts execute; pending-claim out of scope per `95bc46f` / `idempotency.ts:17-20`), `IDEMPOTENCY_TTL_MS` 24 h (`idempotencyTtlMs` + `envNum` guard, lazy sweep per `key_hash`), `409` handling, and a `curl` timeout→retry→replay example. Sources: `server/src/services/idempotency.ts`, `server/src/routes/proxy.ts:1793-1835` + `2640-2656`, migration `20260901_000001_idempotency_claims.ts`. Updated `docs/en/api/OVERVIEW.md` index and added cross-ref in `docs/architecture/04-degraded-mode-and-failover.md:10`.## 2026-08-25@@ -19,7 +19,7 @@ Doc revision history for `docs/api/`, seeded from API-relevant commits.## 2026-08-23 — Docs reorganization-- **e8dde9e** `docs(api): fold API guide into api domain` — moved `docs/api.md` → `docs/api/01-rest-api.md` with `OVERVIEW.md` + `CHANGELOG.md` scaffold.+- **36850e8** `docs(api): fold API guide into api domain` — moved `docs/api.md` → `docs/api/01-rest-api.md` with `OVERVIEW.md` + `CHANGELOG.md` scaffold. (landed via #979)## 2026-08-10 and earlierdiff --git a/docs/en/architecture/CHANGELOG.md b/docs/en/architecture/CHANGELOG.mdindex 0a17e635..74c21d8a 100644--- a/docs/en/architecture/CHANGELOG.md+++ b/docs/en/architecture/CHANGELOG.md@@ -6,7 +6,7 @@ Doc revision history for `docs/architecture/`, seeded from commits touching arch## 2026-09-02-- **docs(architecture): cross-ref Idempotency-Key replay in degraded-mode doc** — `04-degraded-mode-and-failover.md:10` now maps the pre-routing idempotency lookup (`server/src/services/idempotency.ts`, `proxy.ts:1793-1838`) and post-success persist (`proxy.ts:2640-2656`) to the fallback loop, notes `X-Routed-Via: idempotency` zero-cost replay, `stream:true` + `finish_reason:length` exclusion, in-flight NOT deduplicated (`95bc46f`), `IDEMPOTENCY_TTL_MS` 24 h lazy sweep, and that `409` + replay bypass `isDegraded()` / retry budget / hedging. Client contract lives in `docs/api/02-idempotency.md` (`36b877d`).+- **docs(architecture): cross-ref Idempotency-Key replay in degraded-mode doc** — `04-degraded-mode-and-failover.md:10` now maps the pre-routing idempotency lookup (`server/src/services/idempotency.ts`, `proxy.ts:1793-1838`) and post-success persist (`proxy.ts:2640-2656`) to the fallback loop, notes `X-Routed-Via: idempotency` zero-cost replay, `stream:true` + `finish_reason:length` exclusion, in-flight NOT deduplicated (`95bc46f`), `IDEMPOTENCY_TTL_MS` 24 h lazy sweep, and that `409` + replay bypass `isDegraded()` / retry budget / hedging. Client contract lives in `docs/en/api/02-idempotency.md` (`36b877d`).## 2026-08-25diff --git a/docs/en/architecture/OVERVIEW.md b/docs/en/architecture/OVERVIEW.mdindex 01a3d8a6..8d17cc8e 100644--- a/docs/en/architecture/OVERVIEW.md+++ b/docs/en/architecture/OVERVIEW.md@@ -4,7 +4,7 @@## Scope-This domain holds the implementation deep-dives for FreeLLMAPI's server-side architecture. Each file expands one subsystem with source pointers, scoring formulas, state machines and commit-tagged history. For the high-level summary — what the system is, how a request flows, honest limitations and the provider ToS review — see the high-level index [`architecture.md`](00-high-level-index.md).+This domain holds the implementation deep-dives for FreeLLMAPI's server-side architecture. Each file expands one subsystem with source pointers, scoring formulas, state machines and commit-tagged history. For the high-level summary — what the system is, how a request flows, honest limitations and the provider ToS review — see the high-level index [00-high-level-index.md](00-high-level-index.md).## File Index@@ -20,7 +20,7 @@ This domain holds the implementation deep-dives for FreeLLMAPI's server-side arc## How deep-dives fit-The root [`architecture.md`](00-high-level-index.md) stays the high-level index (two-paragraph system summary, request-flow diagram, limitations and ToS). The files above are the deep-dives: start with `01` (bandit scoring & routing) and `02` (quota & cooldown) for the router core, then `03`/`04` for streaming and degraded-mode failover, `05` for catalog sync and `06` for observability internals. The operator-facing logs viewer and polling API are documented separately in [`logs/`](../logs/01-server-logs-viewer.md) and cross-linked from `06`.+The root [00-high-level-index.md](00-high-level-index.md) stays the high-level index (two-paragraph system summary, request-flow diagram, limitations and ToS). The files above are the deep-dives: start with `01` (bandit scoring & routing) and `02` (quota & cooldown) for the router core, then `03`/`04` for streaming and degraded-mode failover, `05` for catalog sync and `06` for observability internals. The operator-facing logs viewer and polling API are documented separately in [`logs/`](../logs/01-server-logs-viewer.md) and cross-linked from `06`.## Navigationdiff --git a/docs/en/deployment/01-docker.md b/docs/en/deployment/01-docker.mdindex 9a08e6fd..176e81cc 100644--- a/docs/en/deployment/01-docker.md+++ b/docs/en/deployment/01-docker.md@@ -46,7 +46,7 @@ printf "ENCRYPTION_KEY=%s\nPORT=3001\n" "$ENCRYPTION_KEY" > .envdocker compose up -d```-Windows PowerShell variant and a curl one-liner bootstrap live in [`docs/install.md`](../install/01-install.md#docker-compose). Then follow the logs:+Windows PowerShell variant and a curl one-liner bootstrap live in [docs/en/install/01-install.md#docker-compose](../install/01-install.md#docker-compose). Then follow the logs:```bashdocker compose logs -f freellmapidiff --git a/docs/en/deployment/OVERVIEW.md b/docs/en/deployment/OVERVIEW.mdindex 8d026222..5c411209 100644--- a/docs/en/deployment/OVERVIEW.md+++ b/docs/en/deployment/OVERVIEW.md@@ -4,7 +4,7 @@## Scope-Operating FreeLLMAPI in Docker: the published image, Compose quickstart, persistence, healthchecks, the container-networking gotchas, and the ongoing maintenance work — upgrading, backups, and declarative configuration. Content is derived from [`Dockerfile`](../../../Dockerfile), [`docker-compose.yml`](../../../docker-compose.yml), [`.dockerignore`](../../../.dockerignore), and [`docs/install.md`](../install/01-install.md).+Operating FreeLLMAPI in Docker: the published image, Compose quickstart, persistence, healthchecks, the container-networking gotchas, and the ongoing maintenance work — upgrading, backups, and declarative configuration. Content is derived from [`Dockerfile`](../../../Dockerfile), [`docker-compose.yml`](../../../docker-compose.yml), [`.dockerignore`](../../../.dockerignore), and [docs/en/install/01-install.md](../install/01-install.md).For installation paths beyond Docker (one-liner script, local development, desktop app), see [Install & deploy](../install/01-install.md).diff --git a/docs/en/env/03-outbound-proxies.md b/docs/en/env/03-outbound-proxies.mdindex 79e1e68b..fc5da979 100644--- a/docs/en/env/03-outbound-proxies.md+++ b/docs/en/env/03-outbound-proxies.md@@ -4,7 +4,7 @@How FreeLLMAPI routes its provider-bound traffic through proxies, which variables win when several are set, and the Docker networking gotchas that come with that.-Sources: [`.env.example`](../../../.env.example) (proxy block), [`docker-compose.yml`](../../../docker-compose.yml), the container-networking notes in [`docs/install.md`](../install/01-install.md), the proxy transports in [`../proxy/01-fetch-relay.md`](../proxy/01-fetch-relay.md) / [`../proxy/OVERVIEW.md`](../proxy/OVERVIEW.md) (`server/src/lib/proxy.ts:52-414`, `server/src/lib/config.ts:95-110` for `TRUST_PROXY`).+Sources: [`.env.example`](../../../.env.example) (proxy block), [`docker-compose.yml`](../../../docker-compose.yml), the container-networking notes in [docs/en/install/01-install.md](../install/01-install.md), the proxy transports in [`../proxy/01-fetch-relay.md`](../proxy/01-fetch-relay.md) / [`../proxy/OVERVIEW.md`](../proxy/OVERVIEW.md) (`server/src/lib/proxy.ts:52-414`, `server/src/lib/config.ts:95-110` for `TRUST_PROXY`).- [Proxy chain precedence](#proxy-chain-precedence)- [Fetch Relay transport](#fetch-relay-transport-summary)diff --git a/docs/en/glossary/CHANGELOG.md b/docs/en/glossary/CHANGELOG.mdindex 89d8a47f..45043d63 100644--- a/docs/en/glossary/CHANGELOG.md+++ b/docs/en/glossary/CHANGELOG.md@@ -4,7 +4,7 @@| Commit | Date | Summary || --- | --- | --- |-| `688a88a` | 2026-09-02 | Create glossary domain — terms: headroom, RPD/TPD, pool key, least-remaining, auto:<name>, model-age gate, bandit, TRUST_PROXY, FREEAPI_SHOT |-| `eb19dcf` | 2026-09-02 | Fix glossary broken link `../architecture` → `architecture` (glossary lives in docs/ itself) |+| `eab992f` | 2026-09-02 | Create glossary domain — terms: headroom, RPD/TPD, pool key, least-remaining, auto:<name>, model-age gate, bandit, TRUST_PROXY, FREEAPI_SHOT (landed via #1164) |+| `eab992f` | 2026-09-02 | Fix glossary broken link `../architecture` → `architecture` (glossary lives in docs/ itself) (landed via #1164) |Regenerate: `git log --oneline -- docs/glossary/`diff --git a/docs/en/logs/CHANGELOG.md b/docs/en/logs/CHANGELOG.mdindex 8734a3db..3b1d32f6 100644--- a/docs/en/logs/CHANGELOG.md+++ b/docs/en/logs/CHANGELOG.md@@ -7,6 +7,6 @@ Doc revision history for `docs/logs/`. Most recent first.| Date | Commit | Change || --- | --- | --- || 2026-08-23 | `74df985` | Server log viewer in the dashboard, under an Analytics nav menu (#993) |-| 2026-08-22 | `96b6f75` | docs(meta): index providers/testing domains and log today's additions |+| 2026-08-22 | `36850e8` | docs(meta): index providers/testing domains and log today's additions (landed via #979) |-> Implementation commits: `74df985` (log viewer feature), `96b6f75` (meta indexing).\ No newline at end of file+> Implementation commits: `74df985` (log viewer feature), `36850e8` (meta indexing, landed via #979).\ No newline at end of filediff --git a/docs/en/proxy/CHANGELOG.md b/docs/en/proxy/CHANGELOG.mdindex ba9856c3..abc459d9 100644--- a/docs/en/proxy/CHANGELOG.md+++ b/docs/en/proxy/CHANGELOG.md@@ -8,7 +8,7 @@ Revision history for `docs/proxy/`, derived from git commits touching the outbou| --- | --- | --- || `46ea0de` | 2026-09-02 | feat(proxy): honor `TRUST_PROXY` for reverse-proxied client IPs (#1041) — adds `TRUST_PROXY` (`false\|true\|<hops>\|addr/CIDR`, `.env.example:306-315`, `server/src/lib/config.ts:95-112` `parseTrustProxy`) forwarded to Express `trust proxy` so Analytics + `PROXY_RATE_LIMIT_RPM`/`ADMIN_RATE_LIMIT_RPM` see real client IP behind Caddy/nginx/Traefik; default `false` (no spoof). || `86368ac` | 2026-09-01 | feat(proxy): auto-detect system-wide proxy settings as a last-resort fallback (#838) — adds `detectSystemProxy()` (`server/src/lib/proxy.ts:52-414` — `scutil --proxy` on macOS, Windows registry `ProxyEnable`+`ProxyServer`, GNOME `gsettings` `manual` + `http host/port` on Linux) at end of `PROXY_URL → dashboard → ALL_PROXY → HTTPS_PROXY → HTTP_PROXY → detectSystemProxy() → direct` chain (`resolveProxySource`), closes #353/#1069, best-effort 2s timeout, never throws. |-| `56eb257` | 2026-08-31 | Add an opt-in Fetch Relay outbound transport (#975) — adds `PROXY_MODE` (`forward` default, `fetch-relay` opt-in, `.env.example:74-78`, `server/src/lib/proxy.ts:52` `PROXY_MODES`) and `FETCH_RELAY_TOKEN` (bearer, encrypted at rest, empty=unauthenticated but not recommended, env precedence over dashboard, `.env.example:78`, `server/src/lib/proxy.ts:389-417`, `isLoopbackRelayHostname`/`fetchRelayUrlError` loopback-https guard, `Fetch-Relay-Target`/`Fetch-Relay-Authorization` headers, `fetchRelayFetch` streaming + manual redirect, `examples/fetch-relay-worker/` Cloudflare Worker reference); initial `docs/fetch-relay.md` (now `docs/proxy/01-fetch-relay.md`) with protocol, security contract, and Worker details. |-| `ac0a9ce` | 2026-08-22 | docs(env): add runtime configuration reference domain — initial outbound proxy documentation in `docs/env/03-outbound-proxies.md` (precedence `PROXY_URL → dashboard → ALL_PROXY → HTTPS_PROXY → HTTP_PROXY`, scheme support `http`/`https`/`socks4`/`socks4a`/`socks5`/`socks5h`, `NO_PROXY` bypasses, Docker `host.docker.internal` gotcha, inbound rate-limit knobs), scaffolded `docs/env/` domain with `OVERVIEW.md` + `CHANGELOG.md`. |+| `56eb257` | 2026-08-31 | Add an opt-in Fetch Relay outbound transport (#975) — adds `PROXY_MODE` (`forward` default, `fetch-relay` opt-in, `.env.example:74-78`, `server/src/lib/proxy.ts:52` `PROXY_MODES`) and `FETCH_RELAY_TOKEN` (bearer, encrypted at rest, empty=unauthenticated but not recommended, env precedence over dashboard, `.env.example:78`, `server/src/lib/proxy.ts:389-417`, `isLoopbackRelayHostname`/`fetchRelayUrlError` loopback-https guard, `Fetch-Relay-Target`/`Fetch-Relay-Authorization` headers, `fetchRelayFetch` streaming + manual redirect, `examples/fetch-relay-worker/` Cloudflare Worker reference); initial `docs/fetch-relay.md` (now `docs/en/proxy/01-fetch-relay.md`) with protocol, security contract, and Worker details. |+| `36850e8` | 2026-08-22 | docs(env): add runtime configuration reference domain — initial outbound proxy documentation in `docs/en/env/03-outbound-proxies.md` (precedence `PROXY_URL → dashboard → ALL_PROXY → HTTPS_PROXY → HTTP_PROXY`, scheme support `http`/`https`/`socks4`/`socks4a`/`socks5`/`socks5h`, `NO_PROXY` bypasses, Docker `host.docker.internal` gotcha, inbound rate-limit knobs), scaffolded `docs/env/` domain with `OVERVIEW.md` + `CHANGELOG.md`. (landed via #979) |Regenerate with `git log --oneline -- docs/proxy/ docs/fetch-relay.md docs/env/03-outbound-proxies.md` and `git log --oneline --grep=proxy --grep=relay --grep=TRUST_PROXY`.diff --git a/docs/en/troubleshooting/CHANGELOG.md b/docs/en/troubleshooting/CHANGELOG.mdindex 66b4e263..41a5f722 100644--- a/docs/en/troubleshooting/CHANGELOG.md+++ b/docs/en/troubleshooting/CHANGELOG.md@@ -4,7 +4,7 @@| Commit | Date | Summary || --- | --- | --- |-| `8bd3acd` | 2026-09-02 | Idempotency `409` — fingerprint/ TTL documented |+| `eab992f` | 2026-09-02 | Idempotency `409` — fingerprint/ TTL documented (landed via #1164) || `e852ff1` | 2026-08-23 | Empty chain authoritative `400` — `activeChainOrThrow` || `86368ac` | 2026-09-01 | System proxy auto-detect `scutil`/`registry`/`gsettings` || `56eb257` | 2026-08-31 | Fetch Relay `PROXY_MODE`/`FETCH_RELAY_TOKEN` loopback guard |diff --git a/docs/zh-cn/CHANGELOG.md b/docs/zh-cn/CHANGELOG.mdindex 8c88def7..ad4265e5 100644--- a/docs/zh-cn/CHANGELOG.md+++ b/docs/zh-cn/CHANGELOG.md@@ -1,24 +1,25 @@[English](../en/CHANGELOG.md) · **简体中文**-# Changelog+# 变更记录`docs/zh-cn/` 的文档修订历史(2026-09-05 之前位于 `docs/i18n/zh-CN/`)。最近的在前。| Date | Commit | Change || --- | --- | --- |-| 2026-09-05 | [`eab992f`](https://github.com/tashfeenahmed/freellmapi/commit/eab992f) | docs: 按语言重排为 `docs/zh-cn/`(#1164);补齐幂等、架构索引、Termux、安装总览四页中文;修正索引与锚点 |-| 2026-08-23 | `e82f85f` | docs(i18n): translate logs/ and architecture/ domains to zh-CN |+| 2026-09-05 | [`ef1b9ce`](https://github.com/tashfeenahmed/freellmapi/commit/ef1b9ce) | docs(zh-cn): 翻译四个占位页,重写中文索引,修正锚点与语言切换(#1167) |+| 2026-09-05 | [`eab992f`](https://github.com/tashfeenahmed/freellmapi/commit/eab992f) | docs: 按语言重排为 `docs/zh-cn/`,并翻译 cli、desktop、proxy、fallback、glossary、troubleshooting 六个域(#1164) |+| 2026-08-23 | `36850e8` | docs(i18n): translate logs/ and architecture/ domains to zh-CN(经 #979 合入) || 2026-08-23 | [`2331045`](https://github.com/tashfeenahmed/freellmapi/commit/2331045) | docs(providers): add unorouter and xkiro to platform catalog |-| 2026-08-23 | [`453de80`](https://github.com/tashfeenahmed/freellmapi/commit/453de80) | docs(providers): document xkiro 5M tokens/day and unorouter per-min RPM in quotas |-| 2026-08-23 | [`acb1511`](https://github.com/tashfeenahmed/freellmapi/commit/acb1511) | docs(env): add FREEAPI_PROXY_LOCAL_DESTINATIONS, SERVER_LOGS_RETENTION_DAYS/MAX_ROWS |-| 2026-08-23 | [`e8dde9e`](https://github.com/tashfeenahmed/freellmapi/commit/e8dde9e) | docs(clients): add setup-dsh note in coding agents intro |-| 2026-08-23 | [`6a1c1a9`](https://github.com/tashfeenahmed/freellmapi/commit/6a1c1a9) | docs(compression): add early-exit protected-span check perf note |-| 2026-08-23 | [`6813e40`](https://github.com/tashfeenahmed/freellmapi/commit/6813e40) | docs(testing): add new test files note for August 2026 batch |+| 2026-08-23 | [`36850e8`](https://github.com/tashfeenahmed/freellmapi/commit/36850e8) | docs(providers): document xkiro 5M tokens/day and unorouter per-min RPM in quotas(经 #979 合入) |+| 2026-08-23 | [`36850e8`](https://github.com/tashfeenahmed/freellmapi/commit/36850e8) | docs(env): add FREEAPI_PROXY_LOCAL_DESTINATIONS, SERVER_LOGS_RETENTION_DAYS/MAX_ROWS(经 #979 合入) |+| 2026-08-23 | [`36850e8`](https://github.com/tashfeenahmed/freellmapi/commit/36850e8) | docs(clients): add setup-dsh note in coding agents intro(经 #979 合入) |+| 2026-08-23 | [`36850e8`](https://github.com/tashfeenahmed/freellmapi/commit/36850e8) | docs(compression): add early-exit protected-span check perf note(经 #979 合入) |+| 2026-08-23 | [`36850e8`](https://github.com/tashfeenahmed/freellmapi/commit/36850e8) | docs(testing): add new test files note for August 2026 batch(经 #979 合入) || 2026-08-22 | — | env/deployment/providers/testing 四个域的 zh-CN 镜像;翻译提交的哈希见 git log |-| 2026-08-22 | [`ac0a9ce`](https://github.com/tashfeenahmed/freellmapi/commit/ac0a9ce) | docs(env): add runtime configuration reference domain —— 英文原文已镜像到 zh-CN |-| 2026-08-22 | [`abe6b00`](https://github.com/tashfeenahmed/freellmapi/commit/abe6b00) | docs(deployment): add Docker operations and maintenance domain —— 英文原文已镜像到 zh-CN |-| 2026-08-22 | [`b21ec10`](https://github.com/tashfeenahmed/freellmapi/commit/b21ec10) | docs(providers): add platform catalog and integration guides —— 英文原文已镜像到 zh-CN |-| 2026-08-22 | [`676ae20`](https://github.com/tashfeenahmed/freellmapi/commit/676ae20) | docs(testing): add test matrix and compatibility-suite documentation —— 英文原文已镜像到 zh-CN |+| 2026-08-22 | [`36850e8`](https://github.com/tashfeenahmed/freellmapi/commit/36850e8) | docs(env): add runtime configuration reference domain —— 英文原文已镜像到 zh-CN(经 #979 合入) |+| 2026-08-22 | [`36850e8`](https://github.com/tashfeenahmed/freellmapi/commit/36850e8) | docs(deployment): add Docker operations and maintenance domain —— 英文原文已镜像到 zh-CN(经 #979 合入) |+| 2026-08-22 | [`36850e8`](https://github.com/tashfeenahmed/freellmapi/commit/36850e8) | docs(providers): add platform catalog and integration guides —— 英文原文已镜像到 zh-CN(经 #979 合入) |+| 2026-08-22 | [`36850e8`](https://github.com/tashfeenahmed/freellmapi/commit/36850e8) | docs(testing): add test matrix and compatibility-suite documentation —— 英文原文已镜像到 zh-CN(经 #979 合入) || 2026-08-03 | [`5d51fec`](https://github.com/tashfeenahmed/freellmapi/commit/5d51fec) | docs(docker): container/provider network mismatch note (#737) || 2026-08-01 | [`93afdca`](https://github.com/tashfeenahmed/freellmapi/commit/93afdca) | zh README 贡献者 heading alignment (#701) || 2026-07-31 | [`76c3e6b`](https://github.com/tashfeenahmed/freellmapi/commit/76c3e6b) | language toggle centering (#691) |diff --git a/docs/zh-cn/api/02-idempotency.md b/docs/zh-cn/api/02-idempotency.mdindex 80b47dda..87d51108 100644--- a/docs/zh-cn/api/02-idempotency.md+++ b/docs/zh-cn/api/02-idempotency.md@@ -2,7 +2,7 @@# Idempotency-Key —— 非流式聊天补全的安全重试-> **来源:** `server/src/services/idempotency.ts`、`server/src/routes/proxy.ts:1793-1835`(入口)+ `2640-2656`(持久化)、`server/src/db/migrations/20260901_000001_idempotency_claims.ts`、提交 `36b877d`(功能)、`95bc46f`(在途请求说明),环境变量 `IDEMPOTENCY_TTL_MS` 记录在 `docs/en/env/01-variables.md#idempotency`。+> **来源:** `server/src/services/idempotency.ts`、`server/src/routes/proxy.ts:1793-1835`(入口)+ `2640-2656`(持久化)、`server/src/db/migrations/20260901_000001_idempotency_claims.ts`、提交 `36b877d`(功能)、`95bc46f`(在途请求说明),环境变量 `IDEMPOTENCY_TTL_MS` 记录在 [`docs/en/env/01-variables.md#idempotency`](../../en/env/01-variables.md#idempotency)。非流式的 `POST /v1/chat/completions` 支持可选的 `Idempotency-Key` 请求头:客户端超时后重试时,不会为一个已经收到过的答案再消耗一次免费额度。在重放窗口内再次看到相同的键与相同的请求内容时,网关以**零提供方成本**重放已存储的响应;相同的键配上不同的内容则返回 `409`,而不是悄悄给出错误答案。@@ -91,7 +91,7 @@ Idempotency-Key: <opaque client token>- 通过 `idempotencyTtlMs()` → `envNum('IDEMPOTENCY_TTL_MS', 24*60*60*1000)` **每次调用时**读取,便于测试实时切换;非有限值或负数 → 回退到默认值。- `expires_at_ms = now + ttl`;过期行在下一次 `storeIdempotencyResult` 时**按 `key_hash`** 惰性清理(`DELETE ... WHERE key_hash = ? AND expires_at_ms <= ?`),范围扫描则借助 `idx_idempotency_claims_expires` 索引。-- 权威来源:`server/src/services/idempotency.ts:40-42`、`docs/en/env/01-variables.md#idempotency`。+- 权威来源:`server/src/services/idempotency.ts:40-42`、[`docs/en/env/01-variables.md#idempotency`](../../en/env/01-variables.md#idempotency)。---@@ -188,6 +188,6 @@ curl -i http://localhost:3001/v1/chat/completions \## 相关-- `docs/en/env/01-variables.md#idempotency` —— `IDEMPOTENCY_TTL_MS` 的默认值与边界。+- [`docs/en/env/01-variables.md#idempotency`](../../en/env/01-variables.md#idempotency) —— `IDEMPOTENCY_TTL_MS` 的默认值与边界。- [`../architecture/04-degraded-mode-and-failover.md`](../architecture/04-degraded-mode-and-failover.md) —— `miss` 进入循环后适用的重试预算、对冲和回退响应头。- [`01-rest-api.md`](01-rest-api.md) —— 兼容 OpenAI 的接口(`/v1/chat/completions`)与响应头(`X-Routed-Via`、`X-Fallback-Detail`)。diff --git a/docs/zh-cn/api/CHANGELOG.md b/docs/zh-cn/api/CHANGELOG.mdindex f55b6be9..6d28dd5a 100644--- a/docs/zh-cn/api/CHANGELOG.md+++ b/docs/zh-cn/api/CHANGELOG.md@@ -6,4 +6,4 @@## 2026-08-23 —— 文档重组-- **e8dde9e** `docs(api): fold API guide into api domain` — `docs/api.md` → `docs/api/01-rest-api.md`,补 `OVERVIEW.md` + `CHANGELOG.md` 脚手架。+- **36850e8** `docs(api): fold API guide into api domain` — `docs/api.md` → `docs/api/01-rest-api.md`,补 `OVERVIEW.md` + `CHANGELOG.md` 脚手架。(经 #979 合入)diff --git a/docs/zh-cn/api/OVERVIEW.md b/docs/zh-cn/api/OVERVIEW.mdindex 2beac55c..99c7323d 100644--- a/docs/zh-cn/api/OVERVIEW.md+++ b/docs/zh-cn/api/OVERVIEW.md@@ -9,6 +9,7 @@| 文件 | 范围 ||------|-------|| [`01-rest-api.md`](01-rest-api.md) | OpenAI 兼容端点(`/v1/chat/completions`、`/v1/responses`、`/v1/embeddings`、`/v1/models`、流式、工具调用、视觉、Gemini grounding、响应头)及 Anthropic Messages 接口(`/v1/messages`)。 |+| [`02-idempotency.md`](02-idempotency.md) | 非流式 `POST /v1/chat/completions` 上的 `Idempotency-Key` —— `replay` / `409 conflict` / `miss` 三种状态、指纹构成(`model`+`messages`+`temperature`/`top_p`/`max_tokens`/`tools`/`tool_choice`)、SHA-256 键哈希、仅限非流式、在途请求不去重(95bc46f)、24 小时 `IDEMPOTENCY_TTL_MS` 窗口、`X-Routed-Via: idempotency`、curl 重试示例。来源:`server/src/services/idempotency.ts`、`proxy.ts:1793-1835`。 || [`CHANGELOG.md`](CHANGELOG.md) | 本域文档修订历史 |## 导航diff --git a/docs/zh-cn/architecture/OVERVIEW.md b/docs/zh-cn/architecture/OVERVIEW.mdindex 0ccd2475..43913cd1 100644--- a/docs/zh-cn/architecture/OVERVIEW.md+++ b/docs/zh-cn/architecture/OVERVIEW.md@@ -2,7 +2,7 @@# 架构域 —— 概览与文件索引-本目录包含 FreeLLMAPI 服务端架构的深度文档。根目录的 [`architecture.md`](00-high-level-index.md) 仍是高层索引;这些文件把各子系统展开并给出实现细节。+本目录包含 FreeLLMAPI 服务端架构的深度文档。根目录的 [00-high-level-index.md](00-high-level-index.md) 仍是高层索引;这些文件把各子系统展开并给出实现细节。## 文件索引diff --git a/docs/zh-cn/clients/01-agent-clients.md b/docs/zh-cn/clients/01-agent-clients.mdindex 5c623d05..6bd8b499 100644--- a/docs/zh-cn/clients/01-agent-clients.md+++ b/docs/zh-cn/clients/01-agent-clients.md@@ -71,15 +71,15 @@ npx @deepseek-ai/dsh web### QwenPaw[QwenPaw](https://github.com/agentscope-ai/QwenPaw) 支持使用 OpenAI-`chat.completions` API 的自定义提供商。先启动 FreeLLMAPI,并从其仪表盘创建或复制统一密钥,+`chat.completions` API 的自定义提供方。先启动 FreeLLMAPI,并从其仪表盘创建或复制统一密钥,然后在 QwenPaw Console 中打开 **设置 → 模型**:-1. 在 **提供商** 下选择 **添加提供商**。-2. 填写 **提供商 ID**(例如 `freellmapi`)和 **提供商名称**(例如 `FreeLLMAPI`),+1. 在 **提供方** 下选择 **添加提供方**。+2. 填写 **提供方 ID**(例如 `freellmapi`)和 **提供方名称**(例如 `FreeLLMAPI`),并将 API 兼容模式设为 OpenAI `chat.completions`。-3. 进入该提供商的设置页,将 **Base URL** 设为 `http://localhost:3001/v1`,+3. 进入该提供方的设置页,将 **Base URL** 设为 `http://localhost:3001/v1`,将 **API 密钥** 设为 FreeLLMAPI 统一密钥。-4. 在该提供商的模型页面添加模型。**模型 ID** 可填 `auto` 让 FreeLLMAPI 自动路由,+4. 在该提供方的模型页面添加模型。**模型 ID** 可填 `auto` 让 FreeLLMAPI 自动路由,或从 `GET http://localhost:3001/v1/models` 复制当前可用的模型 id。5. 保存后把该模型设为默认(或在单次对话中选用),并发一条消息验证。diff --git a/docs/zh-cn/clients/CHANGELOG.md b/docs/zh-cn/clients/CHANGELOG.mdindex e682250a..dc7c92f5 100644--- a/docs/zh-cn/clients/CHANGELOG.md+++ b/docs/zh-cn/clients/CHANGELOG.md@@ -6,4 +6,4 @@## 2026-08-23 —— 领域创建-- **e8dde9e** `docs(clients): fold agent guide into clients domain` — `docs/clients.md` → `docs/clients/01-agent-clients.md`,补 `OVERVIEW.md` + `CHANGELOG.md`。+- **36850e8** `docs(clients): fold agent guide into clients domain` — `docs/clients.md` → `docs/clients/01-agent-clients.md`,补 `OVERVIEW.md` + `CHANGELOG.md`。(经 #979 合入)diff --git a/docs/zh-cn/compression/CHANGELOG.md b/docs/zh-cn/compression/CHANGELOG.mdindex 212d8dc3..ebcc34ac 100644--- a/docs/zh-cn/compression/CHANGELOG.md+++ b/docs/zh-cn/compression/CHANGELOG.md@@ -6,4 +6,4 @@## 2026-08-23 —— 领域创建-- **6a1c1a9** `docs(compression): fold pipeline guide into compression domain` — `docs/compression.md` → `docs/compression/01-compression-pipeline.md`,补 `OVERVIEW.md` + `CHANGELOG.md`。+- **36850e8** `docs(compression): fold pipeline guide into compression domain` — `docs/compression.md` → `docs/en/compression/01-compression-pipeline.md`,补 `OVERVIEW.md` + `CHANGELOG.md`。(经 #979 合入)diff --git a/docs/zh-cn/deployment/01-docker.md b/docs/zh-cn/deployment/01-docker.mdindex c54ad4ce..a4b3cbd2 100644--- a/docs/zh-cn/deployment/01-docker.md+++ b/docs/zh-cn/deployment/01-docker.md@@ -46,7 +46,7 @@ printf "ENCRYPTION_KEY=%s\nPORT=3001\n" "$ENCRYPTION_KEY" > .envdocker compose up -d```-Windows PowerShell 版本和 curl 一行命令引导见 [`docs/install.md`](../install/01-install.md#docker-compose)。然后跟踪日志:+Windows PowerShell 版本和 curl 一行命令引导见 [docs/zh-cn/install/01-install.md#docker-compose](../install/01-install.md#docker-compose)。然后跟踪日志:```bashdocker compose logs -f freellmapidiff --git a/docs/zh-cn/deployment/OVERVIEW.md b/docs/zh-cn/deployment/OVERVIEW.mdindex ef45aef5..4580875a 100644--- a/docs/zh-cn/deployment/OVERVIEW.md+++ b/docs/zh-cn/deployment/OVERVIEW.md@@ -4,7 +4,7 @@## 范围-在 Docker 中运营 FreeLLMAPI:已发布的镜像、Compose 快速开始、持久化、健康检查、容器网络坑点,以及日常维护工作——升级、备份和声明式配置。内容取材自 [`Dockerfile`](../../../Dockerfile)、[`docker-compose.yml`](../../../docker-compose.yml)、[`.dockerignore`](../../../.dockerignore) 与 [`docs/install.md`](../install/01-install.md)。+在 Docker 中运营 FreeLLMAPI:已发布的镜像、Compose 快速开始、持久化、健康检查、容器网络坑点,以及日常维护工作——升级、备份和声明式配置。内容取材自 [`Dockerfile`](../../../Dockerfile)、[`docker-compose.yml`](../../../docker-compose.yml)、[`.dockerignore`](../../../.dockerignore) 与 [docs/zh-cn/install/01-install.md](../install/01-install.md)。Docker 之外的安装路径(一行命令脚本、本地开发、桌面应用)见「[安装与部署](../install/01-install.md)」。diff --git a/docs/zh-cn/env/03-outbound-proxies.md b/docs/zh-cn/env/03-outbound-proxies.mdindex 9f5d2485..d6073bfe 100644--- a/docs/zh-cn/env/03-outbound-proxies.md+++ b/docs/zh-cn/env/03-outbound-proxies.md@@ -4,7 +4,7 @@FreeLLMAPI 如何把发往提供方的流量经由代理转发、多个变量同时设置时谁说了算,以及随之而来的 Docker 网络坑点。-来源:[`.env.example`](../../../.env.example)(代理配置块)、[`docker-compose.yml`](../../../docker-compose.yml),以及 [`docs/install.md`](../install/01-install.md) 中的容器网络说明。+来源:[`.env.example`](../../../.env.example)(代理配置块)、[`docker-compose.yml`](../../../docker-compose.yml),以及 [docs/zh-cn/install/01-install.md](../install/01-install.md) 中的容器网络说明。- [代理链优先级](#代理链优先级)- [协议支持](#协议支持)diff --git a/docs/zh-cn/glossary/CHANGELOG.md b/docs/zh-cn/glossary/CHANGELOG.mdindex fb56a796..3311979b 100644--- a/docs/zh-cn/glossary/CHANGELOG.md+++ b/docs/zh-cn/glossary/CHANGELOG.md@@ -4,7 +4,7 @@| 提交 | 日期 | 摘要 || --- | --- | --- |-| `688a88a` | 2026-09-02 | 创建术语表域 —— 术语:余量、RPD/TPD、池键、最少剩余、auto:<name>、模型年龄闸、老虎机、TRUST_PROXY、FREEAPI_SHOT |-| `eb19dcf` | 2026-09-02 | 修复术语表失效链接 `../architecture` → `architecture`(术语表位于 docs/ 自身) |+| `eab992f` | 2026-09-02 | 创建术语表域 —— 术语:余量、RPD/TPD、池键、最少剩余、auto:<name>、模型年龄闸、老虎机、TRUST_PROXY、FREEAPI_SHOT(经 #1164 合入) |+| `eab992f` | 2026-09-02 | 修复术语表失效链接 `../architecture` → `architecture`(术语表位于 docs/ 自身)(经 #1164 合入) |重新生成:`git log --oneline -- docs/glossary/`diff --git a/docs/zh-cn/install/01-install.md b/docs/zh-cn/install/01-install.mdindex f2ae7603..e9368c4e 100644--- a/docs/zh-cn/install/01-install.md+++ b/docs/zh-cn/install/01-install.md@@ -219,7 +219,7 @@ FREEAPI_DB_BACKUP_INTERVAL_MS=300000启动时如果数据库文件不存在,FreeLLMAPI 会先恢复备份,再执行迁移。服务运行期间,它会定期上传一份新的加密备份。如果没有设置 `FREEAPI_DB_BACKUP_KEY`,备份信封也会使用 `ENCRYPTION_KEY`。-更多 Docker 运维内容和示例在 [docker/../../en/README.md](../../../docker/README.md)。+更多 Docker 运维内容和示例在 [docker/README.md](../../../docker/README.md)。## 桌面应用@@ -239,7 +239,7 @@ npm run desktop:dist:win # Windows → "desktop/dist-electron/FreeLLMAPI Se```> 本地构建出来的应用没有签名,所以 Windows SmartScreen 首次运行时可能会警告(点「更多信息」→「仍要运行」);macOS 构建则不会触发 Gatekeeper 提示。-> 完整说明见 [desktop/../../en/README.md](../README.md)。+> 完整说明见 [desktop/README.md](../../../desktop/README.md)。## 凭据与数据存放位置diff --git a/docs/zh-cn/install/CHANGELOG.md b/docs/zh-cn/install/CHANGELOG.mdindex 4c3aca36..ae31b6fa 100644--- a/docs/zh-cn/install/CHANGELOG.md+++ b/docs/zh-cn/install/CHANGELOG.md@@ -1,6 +1,6 @@[English](../../en/install/CHANGELOG.md) · **简体中文**-# Changelog — install (zh-cn)+# 变更记录 —— install| Commit | Date | Summary || --- | --- | --- |diff --git a/docs/zh-cn/logs/CHANGELOG.md b/docs/zh-cn/logs/CHANGELOG.mdindex cf367600..f458e05a 100644--- a/docs/zh-cn/logs/CHANGELOG.md+++ b/docs/zh-cn/logs/CHANGELOG.md@@ -7,6 +7,6 @@| 日期 | 提交 | 变更 || --- | --- | --- || 2026-08-23 | `74df985` | 仪表盘里的服务器日志查看器,位于分析导航菜单下 (#993) |-| 2026-08-22 | `96b6f75` | docs(meta): 为 providers/testing 域建索引并记录今日新增 |+| 2026-08-22 | `36850e8` | docs(meta): 为 providers/testing 域建索引并记录今日新增(经 #979 合入) |-> 实现提交:`74df985`(日志查看器功能),`96b6f75`(元索引)。\ No newline at end of file+> 实现提交:`74df985`(日志查看器功能),`36850e8`(元索引,经 #979 合入)。\ No newline at end of filediff --git a/docs/zh-cn/proxy/CHANGELOG.md b/docs/zh-cn/proxy/CHANGELOG.mdindex a60ac179..d36d1f18 100644--- a/docs/zh-cn/proxy/CHANGELOG.md+++ b/docs/zh-cn/proxy/CHANGELOG.md@@ -8,7 +8,7 @@| --- | --- | --- || `46ea0de` | 2026-09-02 | feat(proxy): 为反向代理后的客户端 IP 适配 `TRUST_PROXY` (#1041) —— 新增 `TRUST_PROXY`(`false\|true\|<hops>\|addr/CIDR`,`.env.example:306-315`,`server/src/lib/config.ts:95-112` 的 `parseTrustProxy`)并转发给 Express `trust proxy`,使分析与 `PROXY_RATE_LIMIT_RPM`/`ADMIN_RATE_LIMIT_RPM` 在 Caddy/nginx/Traefik 之后能看到真实客户端 IP;默认 `false`(不信任伪造)。 || `86368ac` | 2026-09-01 | feat(proxy): 作为最后兜底自动检测系统级代理设置 (#838) —— 新增 `detectSystemProxy()`(`server/src/lib/proxy.ts:52-414` —— macOS 上 `scutil --proxy`,Windows 注册表 `ProxyEnable`+`ProxyServer`,Linux 上 GNOME `gsettings` `manual` + `http host/port`)位于 `PROXY_URL → 仪表盘 → ALL_PROXY → HTTPS_PROXY → HTTP_PROXY → detectSystemProxy() → 直连` 链末尾(`resolveProxySource`),关闭 #353/#1069,尽力而为,2 秒超时,永不抛异常。 |-| `56eb257` | 2026-08-31 | 按需启用的 Fetch Relay 出站传输 (#975) —— 新增 `PROXY_MODE`(`forward` 默认,`fetch-relay` 按需启用,`.env.example:74-78`,`server/src/lib/proxy.ts:52` 的 `PROXY_MODES`)与 `FETCH_RELAY_TOKEN`(bearer,静态加密,空值表示未鉴权但不推荐,环境变量优先于仪表盘,`.env.example:78`,`server/src/lib/proxy.ts:389-417`,`isLoopbackRelayHostname`/`fetchRelayUrlError` 回环-https 防护,`Fetch-Relay-Target`/`Fetch-Relay-Authorization` 头,`fetchRelayFetch` 流式 + 手动重定向,`examples/fetch-relay-worker/` Cloudflare Worker 参考);初始 `docs/fetch-relay.md`(现为 `docs/proxy/01-fetch-relay.md`)包含协议、安全契约与 Worker 详情。 |-| `ac0a9ce` | 2026-08-22 | docs(env): 新增运行时配置参考域 —— 在 `docs/env/03-outbound-proxies.md` 中首次加入出站代理文档(优先级 `PROXY_URL → 仪表盘 → ALL_PROXY → HTTPS_PROXY → HTTP_PROXY`,协议支持 `http`/`https`/`socks4`/`socks4a`/`socks5`/`socks5h`,`NO_PROXY` 绕过,Docker `host.docker.internal` 坑点,入站限流旋钮),搭建 `docs/env/` 域脚手架,含 `OVERVIEW.md` + `CHANGELOG.md`。 |+| `56eb257` | 2026-08-31 | 按需启用的 Fetch Relay 出站传输 (#975) —— 新增 `PROXY_MODE`(`forward` 默认,`fetch-relay` 按需启用,`.env.example:74-78`,`server/src/lib/proxy.ts:52` 的 `PROXY_MODES`)与 `FETCH_RELAY_TOKEN`(bearer,静态加密,空值表示未鉴权但不推荐,环境变量优先于仪表盘,`.env.example:78`,`server/src/lib/proxy.ts:389-417`,`isLoopbackRelayHostname`/`fetchRelayUrlError` 回环-https 防护,`Fetch-Relay-Target`/`Fetch-Relay-Authorization` 头,`fetchRelayFetch` 流式 + 手动重定向,`examples/fetch-relay-worker/` Cloudflare Worker 参考);初始 `docs/fetch-relay.md`(现为 `docs/en/proxy/01-fetch-relay.md`)包含协议、安全契约与 Worker 详情。 |+| `36850e8` | 2026-08-22 | docs(env): 新增运行时配置参考域 —— 在 `docs/en/env/03-outbound-proxies.md` 中首次加入出站代理文档(优先级 `PROXY_URL → 仪表盘 → ALL_PROXY → HTTPS_PROXY → HTTP_PROXY`,协议支持 `http`/`https`/`socks4`/`socks4a`/`socks5`/`socks5h`,`NO_PROXY` 绕过,Docker `host.docker.internal` 坑点,入站限流旋钮),搭建 `docs/env/` 域脚手架,含 `OVERVIEW.md` + `CHANGELOG.md`。(经 #979 合入) |使用 `git log --oneline -- docs/proxy/ docs/fetch-relay.md docs/env/03-outbound-proxies.md` 与 `git log --oneline --grep=proxy --grep=relay --grep=TRUST_PROXY` 重新生成。diff --git a/docs/zh-cn/troubleshooting/CHANGELOG.md b/docs/zh-cn/troubleshooting/CHANGELOG.mdindex 01c3173f..1e1f11ae 100644--- a/docs/zh-cn/troubleshooting/CHANGELOG.md+++ b/docs/zh-cn/troubleshooting/CHANGELOG.md@@ -6,7 +6,7 @@| 提交 | 日期 | 摘要 || --- | --- | --- |-| `8bd3acd` | 2026-09-02 | 幂等 `409`—— 指纹 / TTL 已文档化 |+| `eab992f` | 2026-09-02 | 幂等 `409`—— 指纹 / TTL 已文档化(经 #1164 合入) || `e852ff1` | 2026-08-23 | 空链权威 `400`—— `activeChainOrThrow` || `86368ac` | 2026-09-01 | 系统代理自动探测 `scutil` / `registry` / `gsettings` || `56eb257` | 2026-08-31 | Fetch Relay `PROXY_MODE` / `FETCH_RELAY_TOKEN` 环回防护 |