[English](../en/upgrade-notes.md) | 简体中文 # 升级说明 这篇按时间倒序列出各次更新里，对使用者和运维有影响的变化，以及升级时要做的事。给运维和管理员看。功能本身的说明在各主题文档里。 ## 2026-10 编排完善第 2 波：PostgreSQL 与多进程 **要做的事**：多进程部署升级前，先停掉全部工作进程；代码节点要用的值改成显式传入；别删数据目录里的 `.agentlab-data`。 - 缺省仍是数据目录里的 SQLite、单进程，不改配置的部署升级后行为不变。启动时自动补上这一波的新列和索引。运行事件的 `(run_id, seq)` 改成唯一索引；存量库里要是已有重号，记一条日志、这一次不建，不影响启动。 - 数据目录里多了一个 `.agentlab-data` 标记文件，`deploy.sh` 靠它（或 `agentlab.db`、`.secret_key`）认数据目录，别删。 - 应用库可以换成 PostgreSQL，现有数据用 `python -m app.db copy-to-postgres` 导入；Docker 部署可以用内置或外接的 PostgreSQL，只能选一种（见 [PostgreSQL 与多进程](postgresql-and-scaling.md)、[部署](deployment.md#应用库放哪里)）。 - 用 PostgreSQL 时可以起多个工作进程（`AGENTLAB_WORKERS`）。SQLite 只支持单进程，第二个进程拒绝启动。升级要先停掉全部工作进程：库里还有活着的、版本不同的进程时，新版本拒绝启动（`deploy.sh upgrade` 就是这样做的）。 - 运行按类别排队：交互、应用、定时、系统。全站上限照旧是 `AGENTLAB_MAX_CONCURRENT_RUNS`，缺省留四分之一给交互，可在「设置 → 偏好设置 → 运行并发」调。满载时评测、召回会比以前慢，换来问数据总有名额；评测每题的时限不算排队的时间。 - `deploy.sh upgrade` 升级前自动备份：SQLite 拷到 `backups/sqlite/`，内置 PostgreSQL 用 `pg_dump` 存到 `backups/postgres/`，各留最近 5 份。`restart` 缺省只重启服务，`restart --postgres` 连库一起。 - bubblewrap 沙箱不再继承后端的环境变量：代码节点里读不到模型的 API Key、数据库地址这类变量了。代码要用的值请显式传进去。 - 子工作流放在循环里多次执行时，写外部系统的幂等键改用父运行里的全局 id：以前循环第二轮的写入会拿到第一轮的回执、不发送，现在照常发。升级前停在子工作流里的运行恢复时仍认旧的键，已经生效的不重发。 - 问数据的心跳不再落库；结束超过 14 天的轮次清掉事件日志（那一轮的问答和答案照旧在对话里）。服务重启后接手一轮时，按账号现在的角色重新核对，停用或没了权限的照实标中断。 - 多行查询没有 `ORDER BY` 时，引用其中一格不再算「来自口径」，召回、对账里标「行序不定」，E1 统计会跟着变。全部指标都行序不定的召回，结论写「核对不了」并开待办，不再写「没变」。对账要人选对照指标时，按逐个数核对过的列预选。 - 待办、通知、Webhook 里照实写驳回的去向（「被驳回，转到 X」「这一路到此为止」），子工作流里的写「子工作流 › x」。子工作流里一步失败时，自动复核只报一条。用户看得到的列表遇到同名、同时间的并列时按 id 排，两种库顺序一致。 ## 2026-10 编排完善第 1 波 - 问数据的一整轮（建图、发起运行、复核、按复核重来、落库）改在服务端的后台任务里跑，页面只负责看；停止走接口 `/api/chat/turns`。服务重启时还在建图的那一轮标中断、可重试。同一段对话同时只跑一轮。使用者的问数据现在也会被复核；继续运行照旧只给搭建者以上（见[问数据与助手](ask-data.md#一轮里发生什么)）。 - 子工作流里的每一步现在进同一个运行的事件流；子工作流出口的字段带着出处回到父图（最多 3 层），子工作流里追不到原始数据的，父图照样降档（见[子工作流](workflows.md#子工作流)）。 - 审批、补充输入、编辑稿件、动作确认、代码和工具审批、双盲裁决可以多接一个「驳回」出口。不接时行为不变（记「已取消 · 被驳回」）。发布检查拦下走不到结束的驳回路径（见[驳回](workflows.md#驳回)）。 - 定时任务可以选「事件触发」，跟着 `AGENTLAB_SCHEDULER` 开关：关着时事件留着不派发（见[事件触发](schedules.md#事件触发)）。 ## 2026-10 下一轮第 4 波 **要做的事**：读事件的外部系统，按 `node.failed` 的 `reason` 区分驳回和失败。 - 导航多了「评测」（搭建者以上可见，⌥0，排在「设置」前面）。 - 受管口径发布新版本后，系统在后台召回重算用过旧版的答案，数真变了才开「召回」待办；每次发布最多重算 `ledger.recall_limit` 组（缺省 50）。发布后自动的那一批和启动时接着做，跟着 `AGENTLAB_SCHEDULER` 开关（见[召回](evaluation-and-ledger.md#召回)）。 - 审阅改了影响数字的目录项，或者表结构删表、删列、改列类型时，用过它的答案标「依据有变」；按新目录新出现错误级问题的才开待办。 - 被驳回的那一步，`node.failed` 事件多带 `reason: "rejected"`（和 `run.cancelled` 同一个字段），画布、航迹、时间线、问数据过程都画「被驳回」。老运行不变。 - 问数据每一轮的建图用量改成读完模型的流再记：以前流末尾才报的输出 token 没记上，这一轮的花费会比以前多一些，多的是原来漏掉的。 - 可订阅的通知事件多了「数据源有变化要处理」和「口径升版，答案的数变了」，消息里都不放数字。 - 口径标签改成逐个数判，比对算法升到第 4 版；老的比对记录照常可读，不会自动重算。评测评分规则升到第 2 版，老评测可以在评测详情里按新规则重评（只读封存，不调模型）。 - 助手只给了思考、一个操作都没给时，问数据和评测都自动重来一次。被取消、超时的模型调用也记一次调用（标「未完成」）。 - 数据目录页起草、剖析的进度挪到一条后台任务条，页头只留入口。数据源卡片上可以设「定时维护」。链到某个数据源卡片的地址统一是 `/data/databases#source-`。 ## 2026-10 下一轮第 3 波 **要做的事**：没有必须的操作。升级后第一次探查，每张表只建结构基线、不报变化。 - 探查结构时每张表记一个结构版本，和上一次比出结构变化，记进数据源的变化记录。从发布版本发起的正式运行，引用的表结构在发布之后变了时，多一条「表结构变化」提醒（`schema.drift`，在封存范围内）。 - 剖析多了取值观察；标了「已列全」的码值表出现新取值时，系统撤销「已列全」（见[取值观察](data-catalog.md#取值观察)）。 - 数据源可以设定时维护；定时任务的目标也可以是评测题集。这两种目标不收 Webhook（回 422），通知走「设置 → 通知」的渠道订阅。 - 变化记录、评测、口径出具与对账在这一波只有接口（`/api/datasources/{id}/changes`、`/api/evals/…`、`/api/ledger/answers/{run_id}/…`），界面随第 4 波上线。 - 问数据的答案整题等价于一份已发布的受管口径时，系统按口径自动发起一次正式运行。「设置」的 `ledger` 一组可以关掉（`auto_issue`）；自动和一键合计每天最多 20 次。 - 应用视图、趋势、分享链接、视图数据接口取「最近一次封存」时，按口径出具、补算出来的运行不会顶替看板上的数（见[视图与印章](apps.md#视图与印章)）。 - 开了登录时，使用者能读原始运行记录、事件和实时流的，只剩自己的问数据运行。 - 通知多了邮件（SMTP）、每天的待办汇总（`notify.digest_at`）和访问密钥到期提醒；关登录时后两项都不发。 - 分享链接缺省关（见[分享链接](apps.md#分享链接)）。 ## 2026-10 下一轮第 2 波 **要做的事**：升级后每个数据源点一次「探查结构」，建立对象索引；超过 500 张表的库，先设「探查范围」。 - 探查结构改成后台任务，和同一个数据源的起草、剖析排队。老的表结构在探查读完之前原样保留。 - 超过 500 张表、又没设探查范围的库，第一次探查会被拒绝，并说出命中了多少张。先在「探查范围」里设规则，或调高上限（最多 2,000）。 - 正式探查不再接受 `?schema=` 临时换 schema（一个数据源一个 schema），预览照旧可以。 - 运行时的 `db_schema__` 不传表名时只列前 50 张；点名探查范围外的表会当场读结构、加进范围（每次运行最多 8 张，留痕）。 - 探索运行封存后，后台比对已发布的口径，追加一条封存后事件 `ledger.matched`，不在封存范围内。启动时补比最近 7 天的运行，跟着 `AGENTLAB_SCHEDULER` 开关。 - 报告导出和可验证报告下载各记一条审计 `report.exported`。问数据发起的运行带上所在对话和轮次（`origin_ref`），「在画布里打开」建的工作流记下来自哪一轮。 ## 2026-10 下一轮第 1 波 **要做的事**：已经用 iframe 嵌 AgentLab 的门户，把门户地址写进 `AGENTLAB_FRAME_ANCESTORS`；设置里填了对外访问地址的部署，核对身份提供方登记的 OIDC 回调地址；升级后每个数据源点一次「探查结构」。 - 人工驳回的运行记为「已取消 · 被驳回」，不再算失败：通知走「实例结束」，定时任务推「未出具（被驳回）」，不能继续运行。配了失败重试或「出错时继续」的关卡，驳回不再重问、也不接着往下走。已封存的老运行不改写。 - 开了登录时，应用入口和待办表单里的选人控件按候选池核对，池外的名字回 422（`principal`）。 - 页面默认只能被本站嵌入（`frame-ancestors 'self'`，另加 `X-Frame-Options`）。 - 「对外访问地址」只剩一个设置（「设置 → 通用」；`AGENTLAB_PUBLIC_URL` 优先，写错了启动就报错）。设置里填了地址的部署，OIDC 回调改按这个地址拼，和身份提供方登记的不一致时要去改登记。开了登录时，`/docs`、`/openapi.json` 要搭建者登录。 - 探查结构时，列类型改存各数据库的完整写法（`VARCHAR2(20 CHAR)`、`ENUM('a','b')`）。新运行的表结构快照哈希会变，旧运行不受影响。MySQL / MariaDB 上，升级后第一次重新剖析时，这些表的目录各升一次版本（文字列多一句排序规则、ENUM 补上没出现的取值、日期列写明排除的无效日期）。剖析设置的「抽样键值数」改叫「核对键值数」。 ## 应用平台 **要做的事**：子工作流、口径卡固定着没有正式运行凭据的老版本时，按提示改为固定一个已发布的版本；之后新建的内网 MCP 要管理员先在「工具 → 端点」登记。 升级后第一次启动会自动做这些事，都幂等： - 存量的待审批补建成待办；自定义工具的请求头、MCP 的环境变量里的明文加密一遍；能力登记同步一遍。 - 记级别之前发布过、有正式运行凭据的老版本，补记为「已发布」。子工作流、口径卡固定的版本须已发布且未退役；固定着没有凭据的老版本时，正式运行会被拒绝。 - 指向本机或内网的 http MCP 服务，自动登记一个开了内网访问的端点（`mcp-<服务名>`）并绑定，写审计。 - `/api/copilot/generate` 改图时只出改动操作，不再是整张新图。每次运行多一条 `run.origin` 事件（在封存范围内）。