# Changelog

格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)（版本段不记日期），版本号遵循语义化版本。

## [0.7.2]

### Added

- AI 网关设置新增「上游无响应预算」（`upstreamWaitSeconds`，30..900 秒，缺省 300，持久化、即时生效）：非流式为单次尝试总超时，流式为等待响应头上限，供 multi-agent / 搜索类慢模型调宽

### Changed

- 出站代理 Transport 补齐阶段超时（连接 30 秒 / TLS 握手 10 秒，对齐 SDK 直连模板）：连不上的代理快速失败，不再拖满总超时

### Fixed

- 修复 Responses 直通调用 multi-agent / 搜索类模型必然超时：SDK 默认 `http.Client` 60 秒总超时覆盖到 body 读完，流式恰好 60 秒断流、非流式（响应头 >60 秒才返回）重试耗尽后约 121 秒报错。非流式改用预算总超时；流式去掉总超时，以定时取消模拟等待响应头预算，响应头到达后流时长不限、生命周期由客户端连接决定。附带消除此类超时对渠道熔断计数的误伤

## [0.7.1]

### Added

- 审计事件接口新增检索参数 `q`：服务端 `logContent` 全文粗筛 + 可见字段（事件名 / 资源 / 操作者 / IP / 请求路径等）精筛，不区分大小写、支持 `*` 通配；关键字内嵌续查游标，跨批过滤口径一致。全文粗筛不作最终判定——`logContent` 会命中隐藏认证元数据（如 `opc-principal` 头里的 `ttype: login`）
- 审计批式响应新增 `scannedThrough`（已完整回溯到的时刻），供前端展示回溯进度
- Logging Search 服务配额为零的租户（报错含 `maxQueriesPerMinute: 0`，部分免费租户如此）自动回退 Audit API 小窗回溯：游标携带通道模式、续查不再试错，搜索降级为客户端可见字段匹配，审计页不再报错

### Changed

- 审计事件数据源由 Audit API 切换为 Logging Search（`_Audit` 日志按 `datetime` 倒序，单页 200 条）；空窗倍增上限由 30 天收紧到 14 天（单次查询时间窗硬限），单批新增约 20 秒时间预算，命中稀疏的深回溯拆成多个有界请求由前端接力

### Fixed

- 修复审计日志固定显示旧事件、刷新也看不到最新记录：Audit API 无排序参数且窗口内固定按处理时间正序，原实现凑满一批即返回，首批永远是 24h 窗口内最旧的一段，「向更早加载」实际在向更新方向翻页

## [0.7.0]

### Added

- AI 网关运行时设置扩展（`GET` / `PUT /api/v1/ai-settings`，持久化、即时生效）：
  - Responses 流式保险丝：开关 + 阈值（KB，1..1024），超阈值的流式请求预防性改非流式上游并合成最小 SSE
  - grok 服务端搜索工具默认注入：`xai.` 前缀模型的 Responses 请求按开关默认注入 `web_search` / `x_search`，请求 `tools` 已含同名工具（任意参数形态）时不覆盖，注入动作记服务端日志
- 聚合模型目录端点 `GET /api/v1/ai-model-catalog`：启用渠道去重、含能力字段（空能力归一 CHAT），与模型列表同口径（随「过滤弃用」开关），供设置页黑名单添加弹窗使用

### Changed

- Responses 流式保险丝触发口径由「完整请求体 > 76KB（环境变量 `AI_RESP_STREAM_UPGRADE_KB`）」改为「`instructions` + `tools` 原始字节合计超阈值（默认开、60KB，设置页可调）」：复测证实约 82KB 的纯体积断流已由上游修复，而 `instructions`+`tools` 合计 >≈64.5KB 的流式静默断流仍存在（`input` 不计入）；环境变量随之废弃
- 升级 oci-go-sdk 到 v65.121.0

### Fixed

- 修复多网卡实例的列表 / 详情地址字段随机：并发填充改以主网卡为准（主卡未返回前允许先到网卡兜底，主卡到达后覆盖并锁定），公网 IP / 私网 IP / IPv6 / 子网恒为主网卡数据

## [0.6.1]

### Added

- Responses 直通 codex 兼容层，codex CLI（`wire_api = "responses"`）指向网关即用，实测 codex-cli 0.144.1 主会话与 multi-agent 子代理全链路可用：
  - `namespace` 工具组（承载 codex multi-agent 与全部 MCP 工具，仅 OpenAI 原生后端识别，OCI 实测 422）拍平为限定名 `function` 工具上送（`ns__child`，`mcp__` 开头子工具名不加前缀），响应中命中的 `function_call` 还原为短名并补回 `namespace` 字段（codex 以该双字段路由）；多轮历史 `function_call` 与对象形态 `tool_choice` 上的 `namespace` 字段自动重限定
  - `custom` 自由格式工具（apply_patch 及 GPT-5.x 档位子代理形态，OCI 不识别）转换为带 `{"input": string}` 包装 schema 的 `function`，响应回转 `custom_tool_call` 并解包 `input`，多轮历史的 `custom_tool_call(_output)` 逆向转换，往返无损；例外：`apply_patch` 整体剥离（grok 系未训练 codex 补丁格式，模型自然回落 shell 编辑）
  - `tool_search`（codex 工具目录搜索）剥离：namespace 已全量拍平上送，搜索语义冗余且上游不识别
  - `web_search` 的 OpenAI 专有参数 `external_web_access`（OCI 实测 400）：`true` 仅删键放行（等价上游默认行为），`false` 为"仅缓存检索"降权模式，按不越权原则连工具剥离
  - 以上改写动作（拍平 / 转换 / 剥离）与校验拒绝均记服务端日志可观测
- Responses 直通流式升级回退：实测 OCI 上游对超过约 82KB 的流式请求会在推理阶段掐断流（纯请求体积触发，与工具构成无关，非流式不受影响），请求体超 76KB 时自动改调非流式上游并合成最小 SSE 事件序列（`created` → 逐项 `output_item.done` → `completed`）返回，语义完整仅丢失增量输出——0.3.1 中「Responses 直通无法透明降级」的限制自此按体积预判解除

### Changed

- `/ai/v1/responses` 工具类型白名单扩展：`namespace` / `custom` / `tool_search` 不再 400 拒绝，按上述兼容策略处理后转发；其余未知工具类型维持请求前置拒绝

## [0.6.0]

### Added

- 渠道模型缓存列表端点 `GET /api/v1/ai-channels/{id}/models`：黑名单模型查询层兜底排除，「过滤弃用模型」开关开启时同样剔除已宣布弃用者（数据保留，展示口径过滤）
- 单模型测试端点 `POST /api/v1/ai-channels/{id}/test-model`：对指定模型发 max_tokens=16 试调，通过即写入渠道「探测验证模型」（此后手动探测与每日后台任务将其置于试调候选首位），渠道探测状态不为可用时顺带置可用并复位熔断；未通过如实返回上游错误且不改动渠道状态
- 渠道列表响应回填 `modelCount`（模型缓存计数，与模型列表同口径：排除黑名单、随过滤弃用开关）

### Fixed

- 修复渠道探测「无配额」误判：配额试调遇 401/403/鉴权 404 不再立即定论租户无配额（可能仅个别模型无权限），改为继续尝试其余候选，任一成功即判可用，全部失败且出现过鉴权拒绝才判无配额
- 探测试调 `max_output_tokens` 由 1 提升到 16：openai.gpt-oss 系列要求 ≥16，原值被 400 拒导致仅有该系列对话模型的渠道被误判

## [0.5.1]

### Fixed

- 修复外部身份（OAuth2）登录 / 绑定无系统日志的问题：回调成功记 200（用户名为面板账号）、失败记 401（附失败原因）；此前回调为 GET 请求不经写操作日志中间件，完全无记录

## [0.5.0]

### Added

- xAI 官方格式文本转语音端点 `POST /ai/v1/tts`：接受 xAI 官方 TTS 请求（`text` / `language` 必填，`voice_id`、`output_format`{codec, sample_rate, bit_rate}、`speed` 等），网关转换为 OpenAI 兼容形态后与 `/ai/v1/audio/speech` 走同一上游与渠道调度；`model` 为网关扩展字段（缺省 `xai.grok-tts`）；实测 `output_format` 对象与 `speed` 透传生效，xAI SDK / 客户端可直接指向网关
- 「过滤弃用模型」开关（`GET` / `PUT /api/v1/ai-settings`，持久化）：开启后 OCI 已宣布弃用（即使未到退役日）的模型从模型列表与路由中同时排除，关闭恢复；渠道同步入库与 30 天退役提醒不受影响

### Changed

- AI 网关文档更名为 `docs/AI网关.md`（原 `docs/ai-gateway.md`），README 引用同步

## [0.4.0]

### Added

- 文本转语音端点 `POST /ai/v1/audio/speech`：OpenAI Audio Speech 兼容，直通 OCI 兼容面（模型 `xai.grok-tts`，voice 取 xAI Grok Voice 列表 `ara`/`eve`/`leo`/`rex`/`sal`）；上游必填的 `language` 缺省时自动注入 `"auto"`，xAI 专属参数平铺透传；响应为一次性完整音频（Content-Type 透传上游，缺省 audio/mpeg），不提供流式
- 文档重排端点 `POST /ai/v1/rerank`：Jina / Cohere 通行协议，走 OCI typed 面（`cohere.rerank-v4.0-pro` / `-fast`），支持 `top_n` 与 `return_documents`，`results[].index` 指向入参 `documents` 下标
- 内容审核端点 `POST /ai/v1/moderations`：OpenAI moderations 外壳映射 OCI Guardrails（内容审核 / PII / 提示注入），`input` 为字符串或字符串数组（单次至多 8 条），categories 用 OCI 原生维度 `overall` / `blocklist` / `prompt_injection`（任一得分 ≥0.5 判 `flagged`），PII 命中放扩展字段 `results[].pii`（不参与 flagged；实测中文人名 / 手机号识别较弱，英文正常）
- Responses 服务端工具扩展：放行 Oracle 文档化的 xAI `code_interpreter` 与远程 `mcp` 工具，并解除 `web_search` / `x_search` 仅非流式的限制——四类服务端工具非流式与流式均实测可用；`code_interpreter` 的命名容器管理与 File Search 不提供
- 模型能力映射扩展：`TEXT_RERANK` → RERANK、`TEXT_TO_AUDIO` → TTS，渠道探测 / 同步自动发现重排与语音模型入池

### Changed

- AI 网关文档独立成篇 `docs/ai-gateway.md`（端点定位、兼容边界、已知上游限制、字段兼容矩阵——矩阵只列支持项，不支持 / 忽略项以文字简述），README 精简为概览并引用；实测披露：Responses `input_file` 内容块被上游以 ZDR 形态拒绝，能力不可用
- swagger 全面修缺：135 处响应注解从泛型 map 改为具体类型（补文档用途响应结构与泛型列表外壳），AI 网关端点请求 / 响应 schema 完整可见；`json.RawMessage` 与联合类型统一渲染为任意 JSON 值（AnyJSON），不再误显示为 byte 数组；swag overrides 配置移至 `docs/.swaggo`，生成命令加 `--overridesFile docs/.swaggo`；顺带修正网页控制台会话创建响应码（200→201）与 SAML 元数据下载（改文件响应）两处注解失真

## [0.3.1]

### Added

- AI 网关流式断流自动降级：Messages 与 Chat Completions 流式请求在客户端尚未收到任何输出时遭遇上游断流，自动降级为非流式重做，结果按标准事件 / chunk 序列一次推送，调用日志记 `retries=1` 与降级标记。实测 OCI 兼容面对 `instructions` 与 `tools` 合计超约 64.5KB 的流式请求会静默断连（无错误事件，非流式正常，消息正文不计入），Claude Code 等大体量系统提示客户端极易触发；Responses 直通因初始事件已转发无法透明降级，日志记「上游流提前终止」；README 增补「已知上游限制：大 system 区流式断流」小节

### Changed

- Messages 的 `max_tokens` 改为可缺省：缺省或 ≤0 时按默认值 8192 放行（此前返回 400；部分客户端将该字段视为选填）

### Fixed

- AI 网关流式假成功：上游 error / `response.failed` 事件此前被吞掉，流提前 EOF 也被伪装成正常结束，调用日志呈现 200 · 0/0 且无错误信息；现 Messages 将上游失败转为 Anthropic `error` 事件，三个流式端点日志均记录上游错误消息或「上游流提前终止，未返回终态事件」

## [0.3.0]

### Added

- 恢复 OpenAI Chat Completions 兼容端点 `/ai/v1/chat/completions`：请求经 OCI Responses 接口转换转发，支持非流式与 SSE、文本与图片、function 工具调用、结构化输出、推理力度、模型白名单、缓存 token 用量和调用日志
- 代理侧批量关联租户接口 `PUT /api/v1/proxies/{id}/tenants`：一次调用设置关联该代理的租户全集——列表内租户改挂到本代理（含从其他代理改挂），列表外已关联的解除，事务生效并返回最新关联计数；含无效租户 ID 返回 400，代理不存在返回 404
- `/api/v1/about` 扩展运行时信息：进程启动时刻 `startedAt`、运行秒数 `uptimeSeconds` 与资源占用 `resources`——CPU 自启动均值（占单核百分比）、CPU 核数、goroutine 数、Go 堆内存与向系统申请内存、数据库引擎与磁盘占用（SQLite 统计主文件与 -wal / -shm；MySQL / PostgreSQL 外部库返回 -1 表示不可度量）
- README 重构部署、配置、鉴权、反向代理、AI 网关与升级发布说明，并新增 Responses、Chat Completions、Embeddings、Anthropic Messages 与标准接口的字段兼容矩阵，明确直通、转换、降级、忽略和拒绝边界

### Changed

- 云端关键事件通知补充操作者、来源 IP、执行结果和说明信息；支持从 OCI Audit 与 IDCS 登录事件提取成功 / 失败状态、策略描述和登录失败原因，缺失字段统一显示占位符

### Removed

- **移除自定义审计告警规则**及其阈值、窗口和冷却匹配能力；`/api/v1/log-events/alert-rules` 与 `/api/v1/log-events/alert-rules/{ruleId}` 管理接口、`audit_alert` 通知模板不再提供，已有规则升级后不再执行

## [0.2.0]

### Added

- AI 网关模型黑名单：面板集中拉黑模型，全渠道剔除（模型列表 / 路由 / 探测候选不再出现，同步不入库），移除条目并重新同步后恢复；新表 `ai_model_blacklists`（启动自动迁移），管理接口 `/api/v1/ai-blacklist`
- AI 密钥模型白名单：密钥可限定放行的模型列表（空 = 不限），白名单外调用 404，模型列表只返回交集
- 推理力度（effort）直通：Responses `reasoning.effort` 与 Anthropic Messages `output_config.effort` 原样透传上游、不做档位校验；grok-4.3 五档（`none` 完全关闭思考）、gpt-oss `minimal`-`high`、multi-agent `xhigh`（控制并行 agent 数）实测生效
- xAI Grok 服务端工具：`/ai/v1/responses` 的 `tools` 支持 `{"type":"web_search"}` / `{"type":"x_search"}`（官方 Agent Tools 格式，可与 `function` 混用，仅非流式），响应保留 `web_search_call` 输出项与引用

### Changed

- **AI 网关对话链路整体切换到 OCI OpenAI 兼容面**（`/actions/v1/responses`），typed chat 面全链路移除：`/ai/v1/responses` 请求体原样直通（仅强制 `store:false`），流式为上游原生事件流，gpt-oss 推理增量直达客户端；`/ai/v1/messages` 转换为 Responses 请求直通，流式经事件桥转回标准 Anthropic 事件序列，`stop_sequences` / `top_k` 等无兼容面对应物的字段改为静默忽略，思考输出不转 `thinking` 块；渠道探测改用兼容面最小请求；流式建立后绑定渠道，中断不重试不计熔断
- 后台任务「立即执行」改异步触发：接口立即返回 202，执行结果经任务日志轮询呈现；同一任务在途时重复触发返回 409「任务正在执行中」，与 cron 重叠触发静默跳过（此前同步阻塞数十秒且同一任务可并发重复执行）
- 渠道探测候选跨厂商分散（上限 8，voice 等不可对话形态排除）：单一厂商在区域内全为微调基座时不再拖垮整个渠道的探测结论
- 网关调用遇「模型不可按需调用」类错误（微调基座 400 / 实体不存在 404）自动换渠道重试且不计入渠道熔断，错误信息带模型名便于加入黑名单；仅鉴权类错误才判定租户无配额
- 同名模型多条目去重优先保留非微调基座条目，降低缓存到不可调用 OCID 的概率

### Removed

- **`/ai/v1/chat/completions` 端点移除**（404）：OpenAI 官方新能力已集中到 Responses 且本面板真实流量为零，请迁移 `/ai/v1/responses` 或 `/ai/v1/messages`
- google / cohere 对话模型不再供给（OCI OpenAI 兼容面不承接，上游 400；cohere embed 向量模型不受影响），模型目录按 `xai.` / `meta.` / `openai.` 厂商前缀过滤

### Fixed

- 渠道「同步模型成功但探测报错不可用」：法兰克福等区域的微调基座模型占满探测候选导致的误报（探测状态与真实可用性不符的根因）
- 租户删除：告警命中清理改子查询，日志事件数万条时不再超出 SQL 绑定变量上限导致删除失败；无法解析的任务 payload 记警告跳过并保留原任务，不再永久阻断租户删除

## [0.1.0]

### Added

- 通知渠道扩展：Webhook（Slack / 飞书 / 钉钉 / 企微预设）、ntfy、Bark、SMTP 邮件与 Telegram 五渠道并存，逐渠道推送互不影响，密钥加密落库
- 审计告警规则：按租户 / 事件 / 资源 / 来源 IP（CIDR in|notin）组合匹配，阈值窗口计数与冷却，命中即推送模板通知
- 撤销全部会话：`POST /auth/revoke-sessions` 使全部旧令牌立即失效，响应携带操作者的新令牌
- 租户暂停状态识别：测活经账户 capabilities 判定 `suspended`，独立于存活 / 失效展示
- 抢机成功通知补全实例明细：租户别名、区域别名、类型与配置、镜像、公网 IPv4 与 root 密码

### Changed

- 敏感身份操作（修改凭据、TOTP 开关、外部身份绑定 / 解绑、密码登录开关）成功后令牌版本递增：全部旧 JWT 立即失效，响应返回新令牌无感续期（原 204 改为 200 + token）
- 管理员徽标与管理员组识别支持双候选组名（Administrators / OCI_Administrators）
- Release 流程：前端产物版本由 `DASH_VERSION` 显式固定并做 sha256 校验，二进制附 `SHA256SUMS`；docker-compose 示例默认只绑定 `127.0.0.1`
- README 新增「反向代理」小节（Caddy / nginx / Traefik 示例与路由前缀清单）

### Fixed

- 删除租户改为单事务清理全部关联本地数据（任务及日志、测活 / 成本快照、回传事件、告警规则、AI 渠道、Webhook 密钥），等待在途任务执行结束，迟到写入不再残留孤儿数据

### Security

- 实例 root 密码收敛：实例详情默认掩码、点击查看，串口控制台不再提供「复制 root 密码」
- JWT 令牌版本机制：凭据 / TOTP / 外部身份 / 登录策略变更即失效全部旧令牌
- HTTP 入口加固：显式读写超时与优雅关闭、请求体上限（面板 1MB / AI 网关 10MB）、登录字段长度上限、登录守卫条目数有界
- 出错响应脱敏：内部错误只返回固定文案 + requestId，完整原因写服务端日志；GORM SQL 日志参数化输出，不再记录实参

## [0.0.1]

首个版本：自托管 OCI 多租户管理面板后端。

### Added

- 多租户管理：OCI API Key 配置集中管理（AES-256-GCM 加密落库）、分组、批量测活、账户画像
- 资源管理：实例、网络（VCN/子网/安全列表/IPv6）、块存储、限额与成本，多区域/多区间
- 自动化任务：抢机、测活、成本同步、AI 渠道探测四类 cron 任务，支持熔断与执行日志
- 网页控制台：串行控制台（xterm）与 VNC（noVNC），两跳 SSH 隧道
- AI 网关：OpenAI / Anthropic 兼容端点转发 OCI GenAI，号池负载均衡、熔断探测、密钥与用量日志
- 日志回传：OCI Audit 事件经 Connector Hub → Notifications HTTPS 订阅入库，一键创建链路
- 租户治理：IAM 用户/MFA/API Key、密码策略、SAML 身份提供商、通知收件人
- 登录安全：JWT + bcrypt、TOTP、OIDC/GitHub 外部登录、登录锁定、IP 限速、操作审计；Telegram 模板化通知
