补齐容器预览的 AGC Router 密钥说明

- deploy/container/api-server.env.example 增加 AGC 官方 LLM Router 段，列明容器预览必须由 .env.secrets.local 提供的三个密钥
- 【开发运维】Jenkins容器预览部署控制面技术方案 补充预览 secrets 必含密钥与缺失时的失败表现
- 【开发运维】本地开发验证与生产运维 补充容器与 Jenkins 预览路径同样受 Router 启动校验约束
- project-memory pitfalls 补充容器预览缺少 Router 密钥时的排障特征

deploy/container/api-server.env.example

@@ -65,5 +65,11 @@ GENARRATIVE_LLM_PROVIDER=openai-compatible
 GENARRATIVE_LLM_BASE_URL=https://api.vectorengine.cn/v1
 GENARRATIVE_LLM_API_KEY=
 GENARRATIVE_LLM_MODEL=gpt-5.4-mini
+# AGC 官方 LLM Router：api / all 角色启动时硬校验官方 HTTPS 地址、固定模型和以下三个密钥，缺失直接拒绝启动。
+# 容器预览的密钥来自镜像内 /srv/genarrative/.env.secrets.local（Jenkins 预览 secrets 副本），
+# 该副本必须包含 GENARRATIVE_LLM_ROUTER_PROVISIONING_SECRET、
+# GENARRATIVE_LLM_ROUTER_API_KEY_ENCRYPTION_SECRET 和 GENARRATIVE_LLM_ROUTER_ADMIN_TOKEN。
+# 本文件只用于按实例显式覆盖；容器环境变量留空时仍由镜像内 .env.secrets.local 提供取值。
+# GENARRATIVE_LLM_ROUTER_BASE_URL=https://router.genarrative.world/v1
 WECHAT_MINIPROGRAM_MESSAGE_TOKEN=
 WECHAT_MINIPROGRAM_MESSAGE_ENCODING_AES_KEY=

docs/project-memory/shared-memory/pitfalls.md

@@ -5197,6 +5197,7 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`
 - 外层 `start-tauri-dev.mjs` 应在启动 Tauri 前完成配套开发服务准备，并统一收束自有服务进程树；不要让冷编译和数据库发布挤占 Tauri 的前端就绪等待。自动发布必须保留数据库，不能靠清库解决启动问题。
 - CLI 与 standalone 可能是两个独立软链接。必须同时核对 `spacetime --version` 和 `spacetimedb-standalone --version`，不能把 CLI 的版本记录当作宿主版本证明；PATH 中存在宿主时启动器检查两者一致。更换宿主前停机备份数据，按原目录启动，不通过清库处理版本错配。
 - Router 配置缺失不应只在首次请求时报错。API/All 启动必须先校验官方地址、固定模型、provisioning secret、管理员 Token 和凭据加密密钥；否则服务看似 healthy，但登录后的 provisioning/模型调用才延迟失败。
+- 容器预览没有独立的 Router 配置来源，密钥只能来自 Jenkins 预览 secrets 副本内置的 `.env.secrets.local`。新增启动期密钥校验时必须同步维护该副本并重建预览镜像，否则表现为 api-server 退出码 1、nginx 停在 `Created`、worker 反复报“模型定价服务身份尚未初始化”，而 systemd 生产路径仍然正常，容易误判成容器或数据库问题。
 
 ## 共享画布框选需要识别 world 的真实后代命中
 

docs/technical/【开发运维】Jenkins容器预览部署控制面技术方案-2026-08-15.md

@@ -55,6 +55,8 @@ Jenkins 节点上的预览 `.env.local` 与 secrets 只允许来自受控的 Jen
 
 宿主固定目录应由 Jenkins 运行账号所有且权限为 `0700`，两个源文件权限均为 `0600`；缺失、不是普通文件、owner 不匹配或权限过宽时，预览构建必须失败关闭。任一源文件变更后必须重新构建并替换 API 与 worker 预览镜像，只重启容器不会刷新已内置的内容。容器启动时显式注入的运行环境变量优先级高于镜像内的 `.env.local` 与 `.env.secrets.local`，用于按实例覆盖非通用值。
 
+预览 secrets 副本还必须包含 AGC 官方 Router 的三个密钥：`GENARRATIVE_LLM_ROUTER_PROVISIONING_SECRET`、`GENARRATIVE_LLM_ROUTER_API_KEY_ENCRYPTION_SECRET` 与 `GENARRATIVE_LLM_ROUTER_ADMIN_TOKEN`。容器 `api` / `all` 角色启动时会硬校验官方 HTTPS 地址、固定模型和这三个密钥，缺失时 api-server 立即以退出码 1 结束，`nginx` 停在 `Created`、`external-generation-worker` 因模型定价服务身份未初始化而反复重启。该失败发生在镜像构建和模块发布之后，因此新增任何启动期密钥校验时必须同步维护预览 secrets 副本并重建镜像，不能等预览页面报错再排查。
+
 这种方案只隐藏构建传输过程，不能让内置后的 secrets 对镜像持有者保密：能读取、保存或运行 `api-runtime` 镜像的人可以提取该文件。因此该镜像只能留在当前受信任内网 Docker 主机，禁止 push 到公共或跨信任边界的 registry，也禁止通过 `docker save`/构建 artifact 导出传播。需要跨边界分发时必须改用不含 secrets 的镜像与运行时密钥注入。
 
 ## Jenkins 参数与产物

docs/【开发运维】本地开发验证与生产运维-2026-05-15.md

@@ -969,3 +969,4 @@ node scripts/rebind-orphan-work-owners.mjs --in <exported-migration.json> --out
 
 `scripts/deploy/maintenance-on.sh` 只允许把同目录临时普通文件原子替换到普通文件或尚不存在的 `page.html` / `enabled` 目标。目标只要是符号链接（包括指向目录的链接）或目录，脚本必须在替换前失败，不能跟随链接把临时文件移入链接目标，也不能打印“已进入维护模式”。`page_temp` 与 `marker_temp` 必须在 `set -u` 下安全初始化，清理 trap 必须在首次 `mktemp` 前生效；任一失败退出都不得在目标同级遗留 `page.html.tmp.*` 或 `enabled.tmp.*`，成功替换后则清空临时路径并解除 trap，不能误删已安装目标。跨平台实现继续使用 POSIX `mv -f`，安全语义由替换函数的目标类型门禁保证；修改后运行 `bash -n scripts/deploy/maintenance-on.sh` 与 `npm run check:maintenance-page`。
 api-server 启动时会硬校验 AGC 官方 Router 配置：API/All 角色必须使用官方 HTTPS 地址和固定模型，并配置 provisioning secret、Router 管理员 Token，以及专用加密 secret 或有效 JWT secret；缺失或不匹配直接拒绝启动。`test` 环境仅允许 loopback fixture，worker-only 角色不执行 Router 配置校验。
+容器与 Jenkins 预览路径同样受该校验约束，且密钥只能来自预览 secrets 副本内置的 `.env.secrets.local`：缺少上述三个密钥时，预览的 api-server 容器启动即退出，`nginx` 与 `external-generation-worker` 连带失败。维护预览环境时必须先补齐这三个键并重建镜像。