diff --git a/docs/configuration/service/ccm.md b/docs/configuration/service/ccm.md index 9aa7d95bb..582390139 100644 --- a/docs/configuration/service/ccm.md +++ b/docs/configuration/service/ccm.md @@ -70,7 +70,7 @@ List of credential configurations for multi-credential mode. When set, top-level `credential_path`, `usages_path`, and `detour` are forbidden. Each user must specify a `credential` tag. -Each credential has a `type` field (`default`, `external`, `balancer`, or `fallback`) and a required `tag` field. +Each credential has a `type` field (`default`, `external`, or `balancer`) and a required `tag` field. ##### Default Credential @@ -94,8 +94,8 @@ A single OAuth credential file. The `type` field can be omitted (defaults to `de - `detour`: Outbound tag for connecting to the Claude API with this credential. - `reserve_5h`: Reserve threshold (1-99) for 5-hour window. Credential pauses at (100-N)% utilization. Conflict with `limit_5h`. - `reserve_weekly`: Reserve threshold (1-99) for weekly window. Credential pauses at (100-N)% utilization. Conflict with `limit_weekly`. -- `limit_5h`: Explicit utilization cap (1-99) for 5-hour window. Credential pauses when utilization reaches this value. Conflict with `reserve_5h`. -- `limit_weekly`: Explicit utilization cap (1-99) for weekly window. Credential pauses when utilization reaches this value. Conflict with `reserve_weekly`. +- `limit_5h`: Explicit utilization cap (0-100) for 5-hour window. `0` means unset. Credential pauses when utilization reaches this value. Conflict with `reserve_5h`. +- `limit_weekly`: Explicit utilization cap (0-100) for weekly window. `0` means unset. Credential pauses when utilization reaches this value. Conflict with `reserve_weekly`. ##### Balancer Credential @@ -111,22 +111,23 @@ A single OAuth credential file. The `type` field can be omitted (defaults to `de Assigns sessions to default credentials based on the selected strategy. Sessions are sticky until the assigned credential hits a rate limit. -- `strategy`: Selection strategy. One of `least_used` `round_robin` `random`. `least_used` will be used by default. +- `strategy`: Selection strategy. One of `least_used` `round_robin` `random` `fallback`. `least_used` will be used by default. - `credentials`: ==Required== List of default credential tags. - `poll_interval`: How often to poll upstream usage API. Default `60s`. -##### Fallback Credential +##### Fallback Strategy ```json { "tag": "backup", - "type": "fallback", + "type": "balancer", + "strategy": "fallback", "credentials": ["a", "b"], "poll_interval": "30s" } ``` -Uses credentials in order. Falls through to the next when the current one is exhausted. +A balancer with `strategy: "fallback"` uses credentials in order. It falls through to the next when the current one is exhausted. - `credentials`: ==Required== Ordered list of default credential tags. - `poll_interval`: How often to poll upstream usage API. Default `60s`. @@ -150,11 +151,11 @@ Uses credentials in order. Falls through to the next when the current one is exh Proxies requests through a remote CCM instance instead of using a local OAuth credential. -- `url`: URL of the remote CCM instance. Omit in reverse receiver mode. +- `url`: URL of the remote CCM instance. Omit to create a receiver that only waits for inbound reverse connections. - `server`: Override server address for dialing, separate from URL hostname. - `server_port`: Override server port for dialing. - `token`: ==Required== Authentication token for the remote instance. -- `reverse`: Enable reverse proxy mode. When `url` is set with `reverse`, acts as a connector that dials out to the remote instance. When `url` is empty, acts as a receiver waiting for inbound reverse connections. +- `reverse`: Enable connector mode. Requires `url`. A connector dials out to `/ccm/v1/reverse` on the remote instance and cannot serve local requests directly. When `url` is set without `reverse`, the credential proxies requests through the remote instance normally and prefers an established reverse connection when one is available. - `detour`: Outbound tag for connecting to the remote instance. - `usages_path`: Optional usage tracking file. - `poll_interval`: How often to poll the remote status endpoint. Default `30m`. @@ -204,7 +205,7 @@ Object fields: !!! question "Since sing-box 1.14.0" - `credential`: Credential tag to use for this user. ==Required== when `credentials` is set. -- `external_credential`: Tag of an external credential dedicated to serving this user. Response rate-limit headers are rewritten with aggregated utilization from all other credentials available to this user. +- `external_credential`: Tag of an external credential used only to rewrite response rate-limit headers with aggregated utilization from this user's other available credentials. It does not control request routing; request selection still comes from `credential` and `allow_external_usage`. - `allow_external_usage`: Allow this user to use external credentials. `false` by default. #### headers diff --git a/docs/configuration/service/ccm.zh.md b/docs/configuration/service/ccm.zh.md index 9a0e0380c..586cb5bb1 100644 --- a/docs/configuration/service/ccm.zh.md +++ b/docs/configuration/service/ccm.zh.md @@ -70,7 +70,7 @@ Claude Code OAuth 凭据文件的路径。 设置后，顶层 `credential_path`、`usages_path` 和 `detour` 被禁止。每个用户必须指定 `credential` 标签。 -每个凭据有一个 `type` 字段（`default`、`external`、`balancer` 或 `fallback`）和一个必填的 `tag` 字段。 +每个凭据有一个 `type` 字段（`default`、`external` 或 `balancer`）和一个必填的 `tag` 字段。 ##### 默认凭据 @@ -94,8 +94,8 @@ Claude Code OAuth 凭据文件的路径。 - `detour`：此凭据用于连接 Claude API 的出站标签。 - `reserve_5h`：5 小时窗口的保留阈值（1-99）。凭据在利用率达到 (100-N)% 时暂停。与 `limit_5h` 冲突。 - `reserve_weekly`：每周窗口的保留阈值（1-99）。凭据在利用率达到 (100-N)% 时暂停。与 `limit_weekly` 冲突。 -- `limit_5h`：5 小时窗口的显式利用率上限（1-99）。凭据在利用率达到此值时暂停。与 `reserve_5h` 冲突。 -- `limit_weekly`：每周窗口的显式利用率上限（1-99）。凭据在利用率达到此值时暂停。与 `reserve_weekly` 冲突。 +- `limit_5h`：5 小时窗口的显式利用率上限（0-100）。`0` 表示未设置显式上限。凭据在利用率达到此值时暂停。与 `reserve_5h` 冲突。 +- `limit_weekly`：每周窗口的显式利用率上限（0-100）。`0` 表示未设置显式上限。凭据在利用率达到此值时暂停。与 `reserve_weekly` 冲突。 ##### 均衡凭据 @@ -111,22 +111,23 @@ Claude Code OAuth 凭据文件的路径。 根据选择的策略将会话分配给默认凭据。会话保持粘性，直到分配的凭据触发速率限制。 -- `strategy`：选择策略。可选值：`least_used` `round_robin` `random`。默认使用 `least_used`。 +- `strategy`：选择策略。可选值：`least_used` `round_robin` `random` `fallback`。默认使用 `least_used`。 - `credentials`：==必填== 默认凭据标签列表。 - `poll_interval`：轮询上游使用 API 的间隔。默认 `60s`。 -##### 回退凭据 +##### 回退策略 ```json { "tag": "backup", - "type": "fallback", + "type": "balancer", + "strategy": "fallback", "credentials": ["a", "b"], "poll_interval": "30s" } ``` -按顺序使用凭据。当前凭据耗尽后切换到下一个。 +将 `strategy` 设为 `fallback` 的均衡凭据会按顺序使用凭据。当前凭据耗尽后切换到下一个。 - `credentials`：==必填== 有序的默认凭据标签列表。 - `poll_interval`：轮询上游使用 API 的间隔。默认 `60s`。 @@ -150,11 +151,11 @@ Claude Code OAuth 凭据文件的路径。 通过远程 CCM 实例代理请求，而非使用本地 OAuth 凭据。 -- `url`：远程 CCM 实例的 URL。在反向接收模式下省略。 +- `url`：远程 CCM 实例的 URL。省略时，此凭据作为仅等待入站反向连接的接收器。 - `server`：覆盖拨号的服务器地址，与 URL 主机名分开。 - `server_port`：覆盖拨号的服务器端口。 - `token`：==必填== 远程实例的身份验证令牌。 -- `reverse`：启用反向代理模式。当设置了 `url` 和 `reverse` 时，作为连接器主动拨出到远程实例。当 `url` 为空时，作为接收器等待入站反向连接。 +- `reverse`：启用连接器模式。要求设置 `url`。启用后，此凭据会主动拨出到远程实例的 `/ccm/v1/reverse`，且不能直接为本地请求提供服务。当设置了 `url` 但未启用 `reverse` 时，此凭据会正常通过远程实例转发请求，并在反向连接建立后优先使用该反向连接。 - `detour`：用于连接远程实例的出站标签。 - `usages_path`：可选的使用跟踪文件。 - `poll_interval`：轮询远程状态端点的间隔。默认 `30m`。 @@ -204,7 +205,7 @@ Claude Code OAuth 凭据文件的路径。 !!! question "自 sing-box 1.14.0 起" - `credential`：此用户使用的凭据标签。设置 `credentials` 时==必填==。 -- `external_credential`：专用于为此用户提供服务的外部凭据标签。响应的速率限制头会被重写为来自此用户所有其他可用凭据的聚合利用率。 +- `external_credential`：仅用于用此用户其他可用凭据的聚合利用率重写响应速率限制头的外部凭据标签。它不参与请求路由；请求选择仍由 `credential` 和 `allow_external_usage` 决定。 - `allow_external_usage`：允许此用户使用外部凭据。默认为 `false`。 #### headers diff --git a/docs/configuration/service/ocm.md b/docs/configuration/service/ocm.md index 63e232db5..43027d9db 100644 --- a/docs/configuration/service/ocm.md +++ b/docs/configuration/service/ocm.md @@ -66,7 +66,7 @@ List of credential configurations for multi-credential mode. When set, top-level `credential_path`, `usages_path`, and `detour` are forbidden. Each user must specify a `credential` tag. -Each credential has a `type` field (`default`, `external`, `balancer`, or `fallback`) and a required `tag` field. +Each credential has a `type` field (`default`, `external`, or `balancer`) and a required `tag` field. ##### Default Credential @@ -90,8 +90,8 @@ A single OAuth credential file. The `type` field can be omitted (defaults to `de - `detour`: Outbound tag for connecting to the OpenAI API with this credential. - `reserve_5h`: Reserve threshold (1-99) for primary rate limit window. Credential pauses at (100-N)% utilization. Conflict with `limit_5h`. - `reserve_weekly`: Reserve threshold (1-99) for secondary (weekly) rate limit window. Credential pauses at (100-N)% utilization. Conflict with `limit_weekly`. -- `limit_5h`: Explicit utilization cap (1-99) for primary rate limit window. Credential pauses when utilization reaches this value. Conflict with `reserve_5h`. -- `limit_weekly`: Explicit utilization cap (1-99) for secondary (weekly) rate limit window. Credential pauses when utilization reaches this value. Conflict with `reserve_weekly`. +- `limit_5h`: Explicit utilization cap (0-100) for primary rate limit window. `0` means unset. Credential pauses when utilization reaches this value. Conflict with `reserve_5h`. +- `limit_weekly`: Explicit utilization cap (0-100) for secondary (weekly) rate limit window. `0` means unset. Credential pauses when utilization reaches this value. Conflict with `reserve_weekly`. ##### Balancer Credential @@ -107,22 +107,23 @@ A single OAuth credential file. The `type` field can be omitted (defaults to `de Assigns sessions to default credentials based on the selected strategy. Sessions are sticky until the assigned credential hits a rate limit. -- `strategy`: Selection strategy. One of `least_used` `round_robin` `random`. `least_used` will be used by default. +- `strategy`: Selection strategy. One of `least_used` `round_robin` `random` `fallback`. `least_used` will be used by default. - `credentials`: ==Required== List of default credential tags. - `poll_interval`: How often to poll upstream usage API. Default `60s`. -##### Fallback Credential +##### Fallback Strategy ```json { "tag": "backup", - "type": "fallback", + "type": "balancer", + "strategy": "fallback", "credentials": ["a", "b"], "poll_interval": "30s" } ``` -Uses credentials in order. Falls through to the next when the current one is exhausted. +A balancer with `strategy: "fallback"` uses credentials in order. It falls through to the next when the current one is exhausted. - `credentials`: ==Required== Ordered list of default credential tags. - `poll_interval`: How often to poll upstream usage API. Default `60s`. @@ -146,11 +147,11 @@ Uses credentials in order. Falls through to the next when the current one is exh Proxies requests through a remote OCM instance instead of using a local OAuth credential. -- `url`: URL of the remote OCM instance. Omit in reverse receiver mode. +- `url`: URL of the remote OCM instance. Omit to create a receiver that only waits for inbound reverse connections. - `server`: Override server address for dialing, separate from URL hostname. - `server_port`: Override server port for dialing. - `token`: ==Required== Authentication token for the remote instance. -- `reverse`: Enable reverse proxy mode. When `url` is set with `reverse`, acts as a connector that dials out to the remote instance. When `url` is empty, acts as a receiver waiting for inbound reverse connections. +- `reverse`: Enable connector mode. Requires `url`. A connector dials out to `/ocm/v1/reverse` on the remote instance and cannot serve local requests directly. When `url` is set without `reverse`, the credential proxies requests through the remote instance normally and prefers an established reverse connection when one is available. - `detour`: Outbound tag for connecting to the remote instance. - `usages_path`: Optional usage tracking file. - `poll_interval`: How often to poll the remote status endpoint. Default `30m`. @@ -200,7 +201,7 @@ Object fields: !!! question "Since sing-box 1.14.0" - `credential`: Credential tag to use for this user. ==Required== when `credentials` is set. -- `external_credential`: Tag of an external credential dedicated to serving this user. Response rate-limit headers are rewritten with aggregated utilization from all other credentials available to this user. +- `external_credential`: Tag of an external credential used only to rewrite response rate-limit headers with aggregated utilization from this user's other available credentials. It does not control request routing; request selection still comes from `credential` and `allow_external_usage`. - `allow_external_usage`: Allow this user to use external credentials. `false` by default. #### headers diff --git a/docs/configuration/service/ocm.zh.md b/docs/configuration/service/ocm.zh.md index 9839acb80..2d06206f0 100644 --- a/docs/configuration/service/ocm.zh.md +++ b/docs/configuration/service/ocm.zh.md @@ -66,7 +66,7 @@ OpenAI OAuth 凭据文件的路径。 设置后，顶层 `credential_path`、`usages_path` 和 `detour` 被禁止。每个用户必须指定 `credential` 标签。 -每个凭据有一个 `type` 字段（`default`、`external`、`balancer` 或 `fallback`）和一个必填的 `tag` 字段。 +每个凭据有一个 `type` 字段（`default`、`external` 或 `balancer`）和一个必填的 `tag` 字段。 ##### 默认凭据 @@ -90,8 +90,8 @@ OpenAI OAuth 凭据文件的路径。 - `detour`：此凭据用于连接 OpenAI API 的出站标签。 - `reserve_5h`：主要速率限制窗口的保留阈值（1-99）。凭据在利用率达到 (100-N)% 时暂停。与 `limit_5h` 冲突。 - `reserve_weekly`：次要（每周）速率限制窗口的保留阈值（1-99）。凭据在利用率达到 (100-N)% 时暂停。与 `limit_weekly` 冲突。 -- `limit_5h`：主要速率限制窗口的显式利用率上限（1-99）。凭据在利用率达到此值时暂停。与 `reserve_5h` 冲突。 -- `limit_weekly`：次要（每周）速率限制窗口的显式利用率上限（1-99）。凭据在利用率达到此值时暂停。与 `reserve_weekly` 冲突。 +- `limit_5h`：主要速率限制窗口的显式利用率上限（0-100）。`0` 表示未设置显式上限。凭据在利用率达到此值时暂停。与 `reserve_5h` 冲突。 +- `limit_weekly`：次要（每周）速率限制窗口的显式利用率上限（0-100）。`0` 表示未设置显式上限。凭据在利用率达到此值时暂停。与 `reserve_weekly` 冲突。 ##### 均衡凭据 @@ -107,22 +107,23 @@ OpenAI OAuth 凭据文件的路径。 根据选择的策略将会话分配给默认凭据。会话保持粘性，直到分配的凭据触发速率限制。 -- `strategy`：选择策略。可选值：`least_used` `round_robin` `random`。默认使用 `least_used`。 +- `strategy`：选择策略。可选值：`least_used` `round_robin` `random` `fallback`。默认使用 `least_used`。 - `credentials`：==必填== 默认凭据标签列表。 - `poll_interval`：轮询上游使用 API 的间隔。默认 `60s`。 -##### 回退凭据 +##### 回退策略 ```json { "tag": "backup", - "type": "fallback", + "type": "balancer", + "strategy": "fallback", "credentials": ["a", "b"], "poll_interval": "30s" } ``` -按顺序使用凭据。当前凭据耗尽后切换到下一个。 +将 `strategy` 设为 `fallback` 的均衡凭据会按顺序使用凭据。当前凭据耗尽后切换到下一个。 - `credentials`：==必填== 有序的默认凭据标签列表。 - `poll_interval`：轮询上游使用 API 的间隔。默认 `60s`。 @@ -146,11 +147,11 @@ OpenAI OAuth 凭据文件的路径。 通过远程 OCM 实例代理请求，而非使用本地 OAuth 凭据。 -- `url`：远程 OCM 实例的 URL。在反向接收模式下省略。 +- `url`：远程 OCM 实例的 URL。省略时，此凭据作为仅等待入站反向连接的接收器。 - `server`：覆盖拨号的服务器地址，与 URL 主机名分开。 - `server_port`：覆盖拨号的服务器端口。 - `token`：==必填== 远程实例的身份验证令牌。 -- `reverse`：启用反向代理模式。当设置了 `url` 和 `reverse` 时，作为连接器主动拨出到远程实例。当 `url` 为空时，作为接收器等待入站反向连接。 +- `reverse`：启用连接器模式。要求设置 `url`。启用后，此凭据会主动拨出到远程实例的 `/ocm/v1/reverse`，且不能直接为本地请求提供服务。当设置了 `url` 但未启用 `reverse` 时，此凭据会正常通过远程实例转发请求，并在反向连接建立后优先使用该反向连接。 - `detour`：用于连接远程实例的出站标签。 - `usages_path`：可选的使用跟踪文件。 - `poll_interval`：轮询远程状态端点的间隔。默认 `30m`。 @@ -200,7 +201,7 @@ OpenAI OAuth 凭据文件的路径。 !!! question "自 sing-box 1.14.0 起" - `credential`：此用户使用的凭据标签。设置 `credentials` 时==必填==。 -- `external_credential`：专用于为此用户提供服务的外部凭据标签。响应的速率限制头会被重写为来自此用户所有其他可用凭据的聚合利用率。 +- `external_credential`：仅用于用此用户其他可用凭据的聚合利用率重写响应速率限制头的外部凭据标签。它不参与请求路由；请求选择仍由 `credential` 和 `allow_external_usage` 决定。 - `allow_external_usage`：允许此用户使用外部凭据。默认为 `false`。 #### headers