diff --git a/docs/project-memory/shared-memory/pitfalls.md b/docs/project-memory/shared-memory/pitfalls.md index a8f7b69d4..14b72578c 100644 --- a/docs/project-memory/shared-memory/pitfalls.md +++ b/docs/project-memory/shared-memory/pitfalls.md @@ -14,6 +14,10 @@ Copy Artifact 插件在**非 SYSTEM 认证**下按「认证用户」判权：只有当被复制 Job 的 `CopyArtifactPermissionProperty`（仓库里由 Declarative 的 `copyArtifactPermission(...)` 维护）显式列出当前消费者，或者该 Job 对认证用户开放 Item.Read 时才放行；`ACL.SYSTEM2` 的定时构建会短路通过。因此会出现「定时调度一路成功、手动发布必挂」的现象（2026-09-21 手动发布 #6/#7 与同期的用户触发探测全部命中，定时调度 #104+ 正常）。`Genarrative-Agc-Global-Version-Issue` 生产权限模式的授权名单必须同时包含 `Genarrative-Scheduled-Revision-Trigger` 与 `Genarrative-Manual-Build-And-Deploy`；改完 `copyArtifactPermission` 后要先跑一次发号 Job 把 Job property 写回 Jenkins，只改仓库文件不生效。 +## 手工发布目标不会自动映射成 AGC 更新渠道 + +`Genarrative-Manual-Build-And-Deploy` 的 `DEPLOY_TARGET=release` 只控制 Stdb / API / Web 全量发布，不会自动成为 AGC 的 `AGC_UPDATE_CHANNEL`。2026-09-21 的手工发布 #10 就因此让 Windows #107 与 macOS #16 使用默认 `dev`，把 `0.1.95` 上传到 `agc/dev-win`、`agc/dev-mac`，而 `agc/release-win/latest.json`、`agc/release-mac/latest.json` 保持 404。现行口径：手工入口按 `release -> release`、`development -> dev` 同时给 Windows 与 macOS AGC Build 传 `AGC_UPDATE_CHANNEL`；补发已烧号的同一版本时用相同 `AGC_RELEASE_VERSION` 直接重跑两条 AGC Job，不重新发号。OSS 发布对象是 `agc/-win|mac/`，不存在 `agc/release/` 这一层。 + ## 同一条链路两处上限不一致：平台合法产出被客户端整条丢弃 - 现象：客户端报「生成素材失败：platform-generation-result-unknown: 异步生成完成结果无法绑定到 operationId：External Editor 旧同步结果的图集切片超过 64 个」，而平台侧这次生成**其实已经成功并切完图**（任务账本耗时正常、`assetId` 为空、没有任何素材落盘，付费产物被丢）。 diff --git a/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md b/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md index 4e8f879dd..c7916f2c8 100644 --- a/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md +++ b/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md @@ -145,6 +145,8 @@ BgFilter 对已经落入私有 OSS 的生成原图、动作抽取帧和手动去 revision 变化时，调度管线把同一个完整 commit 通过 `COMMIT_HASH` 同时传给 `Genarrative-Full-Build-And-Deploy`、`Genarrative-Agc-Windows-Build` 与 `Genarrative-Agc-MacOS-Build`，各条管线都按这个 commit 检出（Full Job 继续把 `env.SOURCE_COMMIT` 透传给 Web / API / Stdb 的 Build、Publish、Deploy），因此两个产物必然来自同一个版本，不会各自解析分支 HEAD 造成漂移。这些下游管线自身不带任何定时触发器，也不在管线内部做版本比较。Windows 客户端发布额外按路径过滤：调度管线比较「上一轮已触发的 revision」与本次 revision 之间的变更路径，只有出现 `apps/ai-game-creator-shell/`、`packages/`、`server-rs/crates/`、`plugins/agc-cocos-editor/`、`apps/desktop-shell/src-tauri/icons/`、`package.json` 或 `package-lock.json` 时才触发 `Genarrative-Agc-Windows-Build` 与 `Genarrative-Agc-MacOS-Build`（两个平台分区发布同一个发号 Job 下发的总版本号），纯文档或流水线自身的提交只触发 Full Build、不推高客户端版本号；判定取消或失败一律按「需要发布」处理，勾选 `FORCE_TRIGGER` 可强制两条都触发。两条下游各自判定：AGC Windows Build 采用「客户端相关路径白名单」，Full Build 采用「与线上站点 / 后端无关的路径黑名单」（`docs/`、`.codex/`、`jenkins/`、`apps/ai-game-creator-shell/`、`apps/mobile-shell/`、`apps/desktop-shell/`、`apps/preview-deployer-web/`、`tools/`、根级 `*.md`），改动只要落在黑名单之外就会照常部署，避免漏发线上站点或后端；两条同时被判为跳过时调度管线只推进 revision 状态、不触发任何发布。AGC 客户端版本号不再由渠道各自递增：唯一发号源是 OSS 对象 `agc/global-version.json`，发号收口到 `Genarrative-Agc-Global-Version-Issue`（`disableConcurrentBuilds()` + 写后回读校验；集群未装 `lockable-resources` 插件）。调度管线与手动发布管线都先调用该 Job 发号，再用归档产物 `agc-global-version.txt` 读取总号并作为 `AGC_RELEASE_VERSION` 透传给客户端构建；统一构建只发一次号供各渠道共用，单渠道热修只把号传给该渠道。显式传入的号低于本渠道当前清单版本时构建失败关闭；`AGC_RELEASE_DRY_RUN` 只预览下一位，不写回、不烧号。一次性播种用 `SEED_ONLY`：基线取「仓库版本 / 各渠道清单 / 旧迁移指针」的最大值，播种本身不烧号。仓库里的 5 个版本文件仍由构建改写，只作构建输入参考，不是事实源。客户端渠道清单的更新摘要同样自动生成：发布脚本读取上一份渠道清单的 `commit` 字段，把该提交到本次提交之间触及客户端相关路径的提交标题逐条写进 `notes`（旧协议清单写入 `releaseNotes`，并落盘归档文件 `release-notes.txt`）；`AGC_UPDATE_RELEASE_NOTES` 非空时以手动文案为准，缺少上一份 `commit` 时不写摘要。Full Job 默认以 `DEPLOY_TARGET=development`、`STDB_API_ROLLOUT_MODE=normal` 对仅供开发使用的 dev 服务器执行 Stdb → API → Web 完整发布，不进入人工 rollout gate；三个下游 Build 都由 Full Job 显式传 `PUBLISH_AFTER_BUILD=false`，统一 Build 完成后仍由 Full Job 按固定顺序发布。人工维护窗口才选择 `pause-after-stdb`，且必须配置 `STDB_API_ROLLOUT_APPROVERS`。 `Genarrative-Agc-Windows-Build` 与 `Genarrative-Agc-MacOS-Build` 结束后都会触发 `Genarrative-Notify-Email`；只有正式 OSS 发布成功时，通知正文才附加本次生成的 `latest.json` 首装包 URL，演练、失败或跳过构建时留空，避免把未写入或不完整的对象地址发给收件人。 +手工发布入口 `Genarrative-Manual-Build-And-Deploy` 的 `DEPLOY_TARGET` 与 AGC 更新渠道是两个独立维度。手工入口必须把 `release` 映射为 `AGC_UPDATE_CHANNEL=release`、把 `development` 映射为 `dev`，并把该参数同时透传给 `Genarrative-Agc-Windows-Build` 与 `Genarrative-Agc-MacOS-Build`；只传 `AGC_RELEASE_VERSION` 时下游会落回各自默认 `dev`。统一号 `0.1.95` 的 release 包应分别位于 `agc/release-win/0.1.95/` 与 `agc/release-mac/0.1.95/`，渠道清单为对应目录下的 `latest.json`，不存在 `agc/release/` 这一层。补发本轮已烧号的版本时，直接以相同 `AGC_RELEASE_VERSION` 重跑两条 AGC Job，不重新发号。 + 调度状态是调度 Job 工作区里的 `.jenkins-last-triggered-revision`，构建描述同时回显本次 revision 与结果。工作区被清理（例如 `Wipe Out Workspace`）或状态文件缺失时，下一次运行按“版本变化”处理并触发一次，之后恢复稳定；需要重建同一版本时勾选 `FORCE_TRIGGER`。Job 按仓库内 `jenkins/scheduled-revision-trigger-job-config.xml` 创建：`scriptPath=jenkins/Jenkinsfile.scheduled-revision-trigger`、Git 入口 `ssh://git@127.0.0.1:2222/GenarrativeAI/Genarrative.git`、凭据 `genarrative-local-gitea-ssh`、`` 留空（定时器写在 Jenkinsfile 里）。推送后必须让三个 live Job 各自加载一次新 Jenkinsfile，并只读核对 `config.xml`：Full 与 AGC 不再有 cron，定时只来自新调度 Job；只改 Jenkinsfile 而不确认 live 配置时，旧 cron 仍会继续触发。 Full Job 通过 `EXIT_MAINTENANCE_MODE_AFTER_COMPLETION` 明确选择完整发布成功后是否退出维护，默认勾选以保持历史行为。Full 对 Stdb Publish 和 API Deploy 两个下游阶段都固定传 `KEEP_MAINTENANCE_MODE=true`，让 maintenance marker 持续覆盖 Stdb → API → Web 整段发布；Web Deploy 成功后才进入独立 `Exit Maintenance` 阶段。该阶段只能通过 `agent none` 和显式 `node(...)` 分配目标机，直接执行 `/opt/genarrative/current/scripts/deploy/maintenance-off.sh`；目标机不得 checkout Git、挂载 Git SSH 凭据或依赖 Jenkins workspace 源码。取消勾选时跳过最终退出阶段，便于内网验收完成后人工恢复公网。`Genarrative-Api-Deploy` 也单独暴露 `KEEP_MAINTENANCE_MODE` 参数，并转换为随发布包脚本的 `--keep-maintenance-mode`；失败路径仍按既有 current 切换边界保留或退出维护，不受成功态选项覆盖。外部生成 queue 的 `warning` 由 API/worker 固化为可直接展示的完整文案，Web 不再补前缀，因此 API/worker 与 Web 必须在同一维护窗口按同一版本协调发布；分开运行 Job 时先保持维护态完成 API/worker，再发布 Web，二者完成后才能恢复公网，不得在公网可用期间只滚动其中一侧。