diff --git a/deploy/container/api-server.env.example b/deploy/container/api-server.env.example index 6dddc3e82..0df2547c6 100644 --- a/deploy/container/api-server.env.example +++ b/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= diff --git a/docs/project-memory/shared-memory/pitfalls.md b/docs/project-memory/shared-memory/pitfalls.md index 491bab7af..871460243 100644 --- a/docs/project-memory/shared-memory/pitfalls.md +++ b/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 的真实后代命中 diff --git a/docs/technical/【开发运维】Jenkins容器预览部署控制面技术方案-2026-08-15.md b/docs/technical/【开发运维】Jenkins容器预览部署控制面技术方案-2026-08-15.md index 6fcf77ff7..a4cf5113d 100644 --- a/docs/technical/【开发运维】Jenkins容器预览部署控制面技术方案-2026-08-15.md +++ b/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 参数与产物 diff --git a/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md b/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md index 5ac6aeace..861504fe7 100644 --- a/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md +++ b/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md @@ -969,3 +969,4 @@ node scripts/rebind-orphan-work-owners.mjs --in --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` 连带失败。维护预览环境时必须先补齐这三个键并重建镜像。