feat(B3.2): 运行时配置热更 + 管理台设置页

新增 runtime_settings 表与 RuntimeSettings 覆盖层：热更项读 DB 覆盖值、
其余透明委托 Settings，**DB 覆盖 > .env**。管理台新增第 7 页「运行时配置」，
改完立即生效、无需重启（推翻 PROPOSAL Q11「无设置页」）。

- config.live()：标量/零参 callable 归一成取值器，测试仍传标量，
  避免为热更改动全部 Settings()/Scheduler() 构造点
- 热更 13 项：默认模型、模型黑名单、到期主/次窗口、会话粘性 TTL、
  成长不可逆开关、成长与探测周期、pacer min/max、CB 聊天最小间隔、
  活跃上报开关与时点
- 消费端每轮/每请求现读：Scheduler（含 expiry_windows 归一化）、
  ConversationAffinity TTL、Pacer（校验挪到读取期）、Executor
  default_model/max_auto_continues、GrowthTask、TaskRunner 周期；
  活跃上报由「关就不装配」改为恒建对象 + 每轮 gate，才能热开
- GET/PUT /api/settings（admin + CSRF + 审计日志），组合校验
  （pacer_min ≤ pacer_max）按「这一批写完之后」的对端值，失败整批不落库
- SCHEMA_VERSION 9→10（纯加表）；老库升级测试补断言
- 文档：README 新增「管理台热更」小节、TECHNICAL §3.8、PROPOSAL Q34

后端 1256 passed / 行+分支 100%；前端 tsc + vitest(125) + build 全绿。

Author: RobbsLuo

PROPOSAL.md

@@ -18,7 +18,7 @@
 | Q8 | 协议出口 | v1 仅 OpenAI；v1.1 加 Anthropic |
 | Q9 | 存储 | SQLite，schema 重新设计，凭证入加密列 |
 | Q10 | 配额 | 不做配额，只做按人统计 |
-| Q11 | 前端范围 | 中等 6 页：Dashboard / 凭证 / API Key / 统计 / Playground / 登录（无设置页，配置走 env） |
+| Q11 | 前端范围 | Dashboard / 凭证 / API Key / 统计 / Playground / 运行时配置 / 登录（Q34 推翻「无设置页」：13 项可热更配置走管理台，其余配置仍走 env） |
 | Q12 | 调度策略 | 统一健康度 + 到期积分指标 + 冷却状态机，保留手动 pin |
 | Q13 | Anthropic | v1.1，架构预留中立事件层 |
 | Q14 | 测试 | 全量 100%（行 + 分支），契约测试优先 |
@@ -39,6 +39,7 @@
 | Q31 | 到期积分排序 | 两级字典序：主窗口（36h）+ 次窗口（7 天）内到期积分总量依次做排序键（均 env 可配）；落库到期阶梯而非单一日期 |
 | Q32 | Responses 出口 | v1 只做 `chat/completions` 子集：`POST /v1/responses` 与 chat 共用同一 executor，出口 translator 可注入；`include`/`store`/`previous_response_id` 按 Codex CLI 实测取舍（见 TECHNICAL §3.7） |
 | Q33 | 凭证暂停语义 | 复用现有 `enabled`（不新增 `manual_disabled` 列）：`enabled=0` 实测已只摘对话流量，后台任务（签到/刷新/成长/探测）只认 `disabled`；UI 文案统一为「暂停/取消暂停」以区别于系统禁用后的「恢复」（见计划 B3.1 实测收窄） |
+| Q34 | 运行时配置热更 | **推翻 Q11 的「无设置页」**：新增 `runtime_settings` 表 + `RuntimeSettings` 覆盖层 + 管理台第 7 页「运行时配置」。白名单 13 项（默认模型 / 模型黑名单 / 到期两个窗口 / 会话粘性 TTL / 成长不可逆开关 / 成长与探测周期 / 两个节流窗口 / CB 聊天最小间隔 / 活跃上报开关与时点）改完立即生效，无需重启；**DB 覆盖值优先于 .env**，UI 与日志明示，可「恢复默认」清掉覆盖。启动期项（密钥 / 端口 / 数据目录 / 上游白名单）不进白名单——它们决定进程如何启动，运行期改只会让内存与磁盘静默分叉 |
 
 ## 2. 目标与非目标
 

README.en.md

@@ -26,6 +26,7 @@ upstream channels, with a shared credential pool, unified scheduling, and per-us
 - **Hardened admin surface**: login rate limiting (global/IP/username + PBKDF2 concurrency cap), CSRF checks on writes, request body limits, security headers, Host allowlist
 - **Model catalog hygiene**: `MODEL_BLOCKLIST` filters placeholder/legacy models; cached model list as fallback when upstreams fail; credit rates and token limits passed through to `/v1/models` and the Playground
 - **Per-credential pause**: the admin credential menu's "Pause" removes one credential from *chat traffic only* — quota probing, token refresh, daily check-in, growth-center and activity-report tasks keep running (they only honor the system hard-disable `disabled`). Unlike "Disabled", which means the upstream rejected the session and requires re-login plus "Restore"
+- **Runtime-configurable settings**: 13 settings (default model, model blocklist, both expiry windows, conversation-sticky TTL, irreversible growth actions, growth/probe intervals, both pacer bounds, CodeBuddy chat interval, activity-report toggle/hour) can be changed from the admin UI's *Runtime settings* page and take effect immediately — no restart. **DB overrides win over `.env`**; the page marks each row as "DB override" and offers "Reset to default" to fall back to `.env`. Startup-only knobs (`APP_SECRET`, `PORT`, `DATA_DIR`, allowlists) are deliberately excluded
 
 ## Quick start
 

README.md

@@ -187,6 +187,19 @@ CodeBuddy 成长中心的「连登天数 / 活跃地图」按日统计客户端
 | `AUTO_CONTINUE_MAX` | `10` | 上游以 `finish_reason=length` 截断时同凭证自动续写的最多次数；`0` 关闭（见 TECHNICAL.md §3.4） |
 | `HOST` / `PORT` | `127.0.0.1` / `8000` | 监听地址与端口（compose 默认 `0.0.0.0`，`PORT` 同时决定宿主机映射端口） |
 
+### 管理台热更（运行时配置）
+
+上表中带「可热更」语义的 13 项可以不改 `.env`、不重启，直接在管理台「运行时配置」页修改：
+
+`DEFAULT_MODEL`、`MODEL_BLOCKLIST`、`QUOTA_EXPIRY_WINDOW_SECONDS`、`QUOTA_EXPIRY_SECONDARY_WINDOW_SECONDS`、`CONVERSATION_STICKY_SECONDS`、`GROWTH_IRREVERSIBLE_ACTIONS`、`GROWTH_INTERVAL_MINUTES`、`QUOTA_PROBE_MINUTES`、`CODEBUDDY_CHAT_MIN_INTERVAL`、`PACER_MIN_SECONDS`、`PACER_MAX_SECONDS`、`ACTIVITY_REPORT_ENABLED`、`ACTIVITY_REPORT_HOUR`。
+
+要点：
+
+- **优先级 `DB 覆盖值 > .env`**：改过之后 .env 对该项不再生效，页面会标「DB 覆盖」；「恢复默认」删掉覆盖行，才重新回落 .env。日志同步记录是谁改的。
+- 值存 `runtime_settings` 表（纯 key/value），新增可热更项不需要迁移；白名单外的 key、非法类型/越界值在写入前被拒，读取时坏行跳过并记警告。
+- 启动期项（`APP_SECRET` / `PORT` / `DATA_DIR` / `USERS_FILE` / 上游端点白名单）**不在**白名单，改它们仍需重启：它们决定进程如何启动，运行期变更只会让内存与磁盘静默分叉。
+- 接口：`GET /api/settings` 读快照，`PUT /api/settings` 写（admin + CSRF），body 形如 `{"values": {"QUOTA_PROBE_MINUTES 对应的 key": 15}}`，传 `null` 表示恢复默认。
+
 ## 部署注意
 
 - **挂载目录属主**：容器内以 uid 1001（`appuser`）运行，`./data` 与 `./secrets`

TECHNICAL.md

@@ -27,7 +27,8 @@ coding2api/
 ├── pyproject.toml               # uv 项目；[tool.pytest.ini_options] 设 coverage 目标
 ├── src/
 │   ├── main.py                  # FastAPI 组装、lifespan、路由挂载（只做接线）
-│   ├── config.py                # pydantic-settings：README「配置」全部 env
+│   ├── config.py                # pydantic-settings：README「配置」全部 env；live() 归一化标量/取值器
+│   ├── runtime_settings.py      # 运行时配置覆盖层（B3.2）：DB 覆盖 > env，白名单 + 校验 + snapshot
 │   ├── webapp/                  # HTTP 边缘层（横切关注点，与业务装配分开）
 │   │   ├── limits.py            # 请求体上限 ASGI 中间件（登录 8KB / 其余 16MB）
 │   │   ├── security.py          # Host 白名单 + 安全响应头（CSP/nosniff）
@@ -98,6 +99,7 @@ coding2api/
 │       ├── authorize.py         # GET /authorize（TRAE 回调落点）
 │       ├── admin_credentials.py # 凭证 CRUD / toggle / pin / probe / checkin / 成长中心 / 账号切换
 │       ├── admin_keys.py        # API Key CRUD
+│       ├── admin_settings.py    # 运行时配置：GET 快照 / PUT 覆盖（admin + CSRF，B3.2）
 │       ├── admin_stats.py       # 统计查询（overview / by-provider / timeline / model-timeline）
 │       ├── admin_auth.py        # 登录 / 登出 / 会话；上游登录 start/poll/cancel
 │       ├── playground.py        # 会话调试端点（无需 API Key）
@@ -392,6 +394,55 @@ item 类型（`local_shell_call`/`custom_tool_call` 等）显式 400。
 
 ---
 
+### 3.8 运行时配置热更（B3.2，推翻 Q11「无设置页」）
+
+**问题**：12+ 项运行期语义的配置（默认模型、到期窗口、节流区间、后台周期、活跃上报开关）此前只在
+`build_app` 启动时读一次并烘焙进对象（`Scheduler(...)`、`Pacer(...)`、`growth_interval_minutes=...`），
+改一项要重启整个进程；管理台没有任何入口。
+
+**分层**（这是设计核心，不是实现细节）：
+
+| 类别 | 例子 | 位置 | 变更方式 |
+|---|---|---|---|
+| 启动期不可变项 | `APP_SECRET` / `HOST` / `PORT` / `DATA_DIR` / `USERS_FILE` / `CODEBUDDY_ALLOWED_ENDPOINTS` | `config.Settings`（frozen） | 改 env + 重启；**不进白名单**，管理台改不了 |
+| 运行时可覆盖项 | 见 `runtime_settings.HOT_SETTINGS`（13 项） | `RuntimeSettings` 覆盖层 | 管理台改，立即生效 |
+
+启动期项之所以拒绝热更：它们决定进程如何启动（监听地址、加密密钥、上游白名单），
+运行期变更只会让「当前进程」与「磁盘配置」静默分叉，而分叉后的行为无法从任一处推断。
+
+**生效优先级**：`runtime_settings` 表（DB 覆盖）> `.env`（默认值来源）。
+覆盖行只有被管理台改过的 key；「恢复默认」= 删除该行，不是写入 env 当前值。
+UI 与日志都必须明示「DB 覆盖 .env」，否则用户改 `.env` 不生效会当成 bug。
+
+**读取机制**：`RuntimeSettings` 对热更 key 返回覆盖值，其余属性 `__getattr__` 透明委托给
+`Settings`——调用方仍写 `settings.default_model`，不必感知覆盖层。覆盖值在内存缓存，
+写入后 `reload()` 刷新；读取路径不查库（每次选号/建请求都查库的开销远超热更省的收益）。
+
+**消费端**：`config.live(value)` 把「标量或零参 callable」统一成取值器。生产装配传
+`lambda: runtime.xxx`（每次读当前值），测试与一次性任务仍传标量。已接线的热更点：
+
+- `Scheduler.expiry_window` / `secondary_expiry_window`：读取时跑 `expiry_windows()`
+  归一化（主窗口 ≤0 → 次窗口一并归零），避免只热更主窗口导致次窗口单独排序
+- `ConversationAffinity.ttl_seconds`：存量条目按写入时的到期时刻失效，调小 TTL 不会让旧条目突然作废
+- `Pacer.min/max_seconds`：校验从构造期挪到读取期（覆盖层把下限改到上限之上只能在用时拒绝），
+  但构造时仍校验一次尽早失败
+- `Executor`：`default_model` / `max_auto_continues` 每次请求现读
+- `GrowthTask.allow_irreversible`：每轮现读
+- `TaskRunner` 周期（探测/成长/刷新/清理）与活跃上报开关、时点：每轮 `sleep` 前现读
+- 活跃上报改为**恒建对象**（构造成本为零），由 `TaskRunner._activity_enabled` callable 每轮 gate：
+  只有对象先存在，管理台才能把默认关闭的它热开到不需要重启
+
+**校验**：白名单外 key 直接拒绝；类型（`int`/`float`/`bool`/`str`）与范围（min/max）在写入前校验；
+跨字段组合（`pacer_min ≤ pacer_max`）用「这一批写完之后」的对端值比较，校验失败则整批不落库
+（半新半旧的组合比拒绝更糟）。表里的坏行（白名单外/类型非法）在读取时跳过并记警告——
+一行坏数据不能让服务起不来。
+
+**接口**：`GET /api/settings`（admin）返回 `snapshot()`（`key`/`env_name`/`label`/`description`/
+`kind`/`value`/`default`/`overridden`）+ 覆盖计数；`PUT /api/settings`（admin + CSRF）body
+`{"values": {key: 标量 | null}}`，`null` 表示恢复默认。写操作记审计日志（谁改了哪些 key）。
+
+---
+
 ## 4. Provider 协议（Q16=A 细接口）
 
 ```python

src/api/admin_settings.py

@@ -0,0 +1,50 @@
+"""运行时配置热更：读取覆盖层快照 / 写入覆盖值（B3.2）。
+
+语义约定：**DB 覆盖值优先于 .env**。管理台写下的值存进 runtime_settings 表，
+进程重启后依然生效；要回到 .env 的默认值，把该项「恢复默认」（提交 null）。
+界面与日志都必须明示这一点，否则用户会以为改 .env 就能改回来。
+"""
+
+from __future__ import annotations
+
+import logging
+
+from fastapi import APIRouter, Depends
+
+from ..auth.rbac import require_admin
+from ..compat.openai.request import InvalidRequest
+from ..runtime_settings import InvalidSetting
+from .deps import Services, csrf_protected, principal_from_request
+
+logger = logging.getLogger(__name__)
+
+
+def create_router(services: Services) -> APIRouter:
+    router = APIRouter()
+    runtime = services.settings
+
+    @router.get("/api/settings")
+    async def list_settings(principal=Depends(principal_from_request)):
+        require_admin(principal)
+        return {
+            "settings": runtime.snapshot(),
+            "overridden": sum(1 for item in runtime.snapshot() if item["overridden"]),
+        }
+
+    @router.put("/api/settings")
+    async def update_settings(payload: dict,
+                              _csrf: None = Depends(csrf_protected),
+                              principal=Depends(principal_from_request)):
+        require_admin(principal)
+        values = payload.get("values")
+        if not isinstance(values, dict):
+            raise InvalidRequest("values must be an object")
+        try:
+            runtime.set_many(values)
+        except InvalidSetting as error:
+            raise InvalidRequest(str(error)) from error
+        keys = ", ".join(sorted(values)) or "(空)"
+        logger.info("管理员 %s 更新运行时配置 %s（DB 覆盖 .env）", principal.username, keys)
+        return {"settings": runtime.snapshot()}
+
+    return router

src/api/deps.py

@@ -23,6 +23,7 @@
 from ..config import Settings
 from ..db.repo import ApiKeyRepository, CredentialRepository, GrowthRepository
 from ..engine.executor import Executor
+from ..runtime_settings import RuntimeSettings
 from ..stats.query import StatsQuery
 
 SESSION_COOKIE = "coding2api_session"
@@ -37,7 +38,7 @@ class Services:
     统一迁移会扩大改动面而无实际收益。
     """
 
-    settings: Settings
+    settings: Settings | RuntimeSettings
     credentials: CredentialRepository
     growth_events: GrowthRepository
     api_keys: ApiKeyRepository

src/config.py

@@ -5,7 +5,9 @@
 
 from __future__ import annotations
 
+from collections.abc import Callable
 from functools import cached_property
+from typing import Any
 
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
@@ -124,3 +126,15 @@ def load_settings(env: dict[str, str] | None = None) -> Settings:
 def validate_endpoint_allowed(endpoint: str, settings: Settings) -> bool:
     """上游地址必须落在白名单内，否则拒绝发出真实 Token（PROPOSAL §8）。"""
     return endpoint.strip() in settings.allowed_endpoints
+
+
+def live(value: Any) -> Callable[[], Any]:
+    """把「标量或零参 callable」统一成取当前值的零参 callable（B3.2）。
+
+    热更消费方（调度器 / 节流器 / 后台任务 / 执行器）持有的都是这个封装：
+    生产装配传零参 lambda 实时读运行时覆盖层，测试仍可传标量。两条路径
+    共用同一套逻辑，不必为「可热更」把每个构造点都改成传 callable。
+    """
+    if callable(value):
+        return value
+    return lambda: value

src/db/migrate.py

@@ -16,7 +16,9 @@
 SCHEMA_NAME = "schema.sql"
 
 # 当前 schema 版本。新增列/表、删表时 +1，并在下方对应元组里补增量。
-SCHEMA_VERSION = 9
+# 10：新增 runtime_settings 表（B3.2 运行时配置热更新）。新增表只需进
+# schema.sql（CREATE TABLE IF NOT EXISTS 对老库同样生效），无需迁移动作。
+SCHEMA_VERSION = 10
 
 # (表, 列定义)：历史库升级时逐条补列
 _MIGRATION_COLUMNS: tuple[tuple[str, str], ...] = (

src/db/repo.py

@@ -401,3 +401,39 @@ def recent(self, credential_id: str, limit: int = 20) -> list[dict[str, Any]]:
             "SELECT * FROM growth_events WHERE credential_id = ? ORDER BY ts DESC LIMIT ?",
             (credential_id, max(1, limit))).fetchall()
         return [dict(row) for row in rows]
+
+
+class RuntimeSettingsRepository:
+    """运行时配置覆盖（runtime_settings）：只存管理台改过的 key。
+
+    纯 key/value/updated_at 三列，不在这里做类型校验——白名单与取值范围
+    属于 `src/runtime_settings.py`（配置语义），仓储只负责存取。这样新增一个
+    可热更项不需要改 schema，与「表结构只加不改」的纪律一致。
+    """
+
+    def __init__(self, db) -> None:
+        self._db = db
+
+    def load(self) -> dict[str, str]:
+        rows = self._db.connect().execute(
+            "SELECT key, value FROM runtime_settings").fetchall()
+        return {row["key"]: row["value"] for row in rows}
+
+    def set(self, key: str, value: str, now: int | None = None) -> None:
+        with self._db.transaction() as conn:
+            conn.execute(
+                "INSERT INTO runtime_settings (key, value, updated_at) VALUES (?,?,?) "
+                "ON CONFLICT(key) DO UPDATE SET value = excluded.value, "
+                "updated_at = excluded.updated_at",
+                (key, value, int(now if now is not None else time.time())),
+            )
+
+    def delete(self, key: str) -> None:
+        with self._db.transaction() as conn:
+            conn.execute("DELETE FROM runtime_settings WHERE key = ?", (key,))
+
+    def updated_at(self) -> dict[str, int]:
+        """key → 最近一次修改时间（界面显示「何时改的」）。"""
+        rows = self._db.connect().execute(
+            "SELECT key, updated_at FROM runtime_settings").fetchall()
+        return {row["key"]: row["updated_at"] for row in rows}

src/db/schema.sql

@@ -122,3 +122,16 @@ CREATE TABLE IF NOT EXISTS credential_model_cooldowns (
 
 CREATE INDEX IF NOT EXISTS idx_model_cooling_until
     ON credential_model_cooldowns(cooling_until);
+
+-- 运行时配置覆盖（B3.2）：只存「管理台改过」的 key，未出现的 key 回落 env。
+--
+-- 为什么单独建表而不是加列到别的表：键集合随版本演进（新增可热更项不
+-- 需要迁移），且 key/value 都是文本，值的类型与取值范围由
+-- src/runtime_settings.py 的 HOT_SETTINGS 白名单校验——表本身不做约束，
+-- 白名单外/类型非法的行在读取时被忽略并记日志，不让一行坏数据把服务拖崩。
+-- 注意：这里存的是**覆盖意图**，不是权威值；env 仍是默认值来源。
+CREATE TABLE IF NOT EXISTS runtime_settings (
+    key         TEXT PRIMARY KEY,
+    value       TEXT NOT NULL,        -- 统一以文本存储，读时按白名单类型解析
+    updated_at  INTEGER NOT NULL
+);