From 3a0f65eabb5bb34d9ff24ae01895aa9ffe2a65ad Mon Sep 17 00:00:00 2001 From: lili Date: Sun, 5 Jul 2026 07:44:34 -0700 Subject: [PATCH] =?UTF-8?q?docs(.agents):=20=E8=A7=82=E6=B5=8B=E6=A0=88?= =?UTF-8?q?=E8=B5=B7=E5=AE=B9=E5=99=A8=E5=9B=9B=E5=9D=91=E8=92=B8=E9=A6=8F?= =?UTF-8?q?=E8=BF=9B=20staging-ops=20=C2=A76(compose=20=E9=83=A8=E7=BD=B2?= =?UTF-8?q?=20mini-infra)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 阶段四第一波起容器排障蒸馏成复用 checklist(staging-ops.md 新增 §6): ①端口 ss -tlnp 查(docker ps 看不到 host 网/宿主进程端口,如 mihomo:9090) ②expand-env 组件配置注释禁写 ${}(Loki/Tempo/collector 连注释严格校验、通配符触发 missing closing brace) ③镜像 pull 成功≠binary 在,docker run --version 验(daocloud mirror 的 collector 0.116.0 缺 binary) ④换 tag 复核配置字段兼容(redaction blocked_key_patterns/redact_all_types 降版本丢=脱敏红线) + §4 边际登记②观测保留期第一波已定(Prom/Loki 15d、Tempo 7d);README 索引描述补 compose 部署。 Co-Authored-By: Claude Opus 4.8 (1M context) --- .agents/README.md | 2 +- .agents/skills/staging-ops.md | 13 ++++++++++++- 2 files changed, 13 insertions(+), 2 deletions(-) diff --git a/.agents/README.md b/.agents/README.md index 2bbe92e1..53b54a8f 100644 --- a/.agents/README.md +++ b/.agents/README.md @@ -54,7 +54,7 @@ | `contract-first-development.md` | 契约先行：8 类契约对齐与各工位 mock 并行解耦 | | `prompt-governance.md` | Prompt 即第 8 契约：Registry/加载注入/eval 门禁/HITL 治理手册 | | `wave-close-checklist.md` | 波次收口八步检查单——所有收口铁律指向的唯一可执行清单 | -| `staging-ops.md` | staging 运维配方：机器分工/代码同步/后端重部署/前端构建门/冒烟门 | +| `staging-ops.md` | staging 运维配方：机器分工/代码同步/后端重部署/前端构建门/冒烟门/compose 部署 mini-infra | | `ui-walkthrough-cdp.md` | 真 UI 走查配方（CDP on mini-desktop）：studio/admin 走查 + CDP 七坑 + 信道探针 | | `game-e2e-cdp-harness.md` | Canvas 游戏 e2e 证据 harness：驱动器六律 + 出厂红线 + 九门真玩（A–G 假绿守卫 + H 机制/latch + I 控制手感） | | `cheap-model-game-generation.md` | 便宜模型生成跨路通用蒸馏：成本/前缀缓存降本/L1 纪律坑/质量三层/scale-20 模型画像（旧 gamedef/factory 路已压缩留指针，现行走 cheap-worker） | diff --git a/.agents/skills/staging-ops.md b/.agents/skills/staging-ops.md index 9076797a..2922b96c 100644 --- a/.agents/skills/staging-ops.md +++ b/.agents/skills/staging-ops.md @@ -44,7 +44,7 @@ > **后端接 staging 前环境检查:代理劫持防护（创始人 2026-06-22 历史回收判定捡回·边际登记）**。staging 机若装了 mihomo 之类代理客户端(占 7890/9090),Java 进程连内网 MySQL/Redis 可能被代理拦截,表现为莫名其妙的连接失败。接线前先把内网网段 `100.64.0.0/10` 加进 `no_proxy`/JVM `nonProxyHosts`,放行内网中间件连接。(与生成域 new-api 出网调模型的 no_proxy 是两个场景:那条放行出网,这条放行内网。) -> **边际登记(创始人 2026-06-22 历史回收判定,真部署时补,不在此展开)**:① **快检部署落点**(运维 033)——`deploy/smoke-test.sh` 等就绪快检在哪台机怎么跑,真部署时在本配方 §5 补;② **观测数据保留期**(运维 034)——trace/metrics 存多久、和 `security-and-reliability.md` §6 的日志保留期(ERROR/WARN 90 天、INFO 30 天)、磁盘水位告警(运维 021)、¥500/月监控预算(运维 027)一起对账,观测栈真上线时定;③ **staging 数据脱敏子集归属**(运维 006)——真上线后 staging 要不要用生产数据脱敏子集来验(暴露真实数据分布下的 bug),是运维-合规交叉约束,**待定**(现状 staging 是 seed 假数据,可幂等重建)。 +> **边际登记(创始人 2026-06-22 历史回收判定,真部署时补,不在此展开)**:① **快检部署落点**(运维 033)——`deploy/smoke-test.sh` 等就绪快检在哪台机怎么跑,真部署时在本配方 §5 补;② **观测数据保留期**(运维 034)——**第一波已定基础保留期**(Prometheus/Loki 15 天、Tempo 7 天,见 `deploy/infra/observability/` 及 §6);与 `security-and-reliability.md` §6 日志保留期(ERROR/WARN 90 天、INFO 30 天)、磁盘水位告警(运维 021)、¥500/月监控预算(运维 027)的完整对账,待后续波观测真接数据后收口;③ **staging 数据脱敏子集归属**(运维 006)——真上线后 staging 要不要用生产数据脱敏子集来验(暴露真实数据分布下的 bug),是运维-合规交叉约束,**待定**(现状 staging 是 seed 假数据,可幂等重建)。 ## 4. 构建/测试门（红线） @@ -59,3 +59,14 @@ - API 就绪门：`deploy/smoke-test.sh`（只读 12 项）+ `--deep`（13 项含 generate 入队），含 CORS/鉴权（test1 token）验证。 - gotcha：feed item 的 `packageUrl` 恒 null，真实取包走 `GET /app-api/runtime/package/{versionId}`。 - **API 全绿 ≠ UI 通**：编排器旁路会掩盖 UI 缺陷，用户可见波次收口前必须做一次真 UI 走查（见 [`ui-walkthrough-cdp.md`](./ui-walkthrough-cdp.md)）。 + +## 6. docker compose 部署到 mini-infra（观测栈第一波实战蒸馏，2026-07-05） + +观测栈五件（Collector/Prometheus/Tempo/Loki/Grafana）起在 mini-infra 时，从 compose 写好到五件全绿踩了四个坑，没一个是 compose 语法错——`docker compose config` 全过、`pull` 也成功，问题全在环境和镜像。起容器前按这四条自查，能省一整轮排障。 + +- **端口要 `ss -tlnp` 查、别只信 `docker ps`**。`docker ps --format` 只列 bridge 网容器的端口映射，host 网容器（mini-infra 的 nacos/rocketmq 用 host 网）和宿主进程占的端口一个都不显示。观测栈 Prometheus 默认 9090，恰好撞上 mini-infra 自己跑的 mihomo（clash 内核，§3 已记它占 9090 当 API 端口）——摸底时 `docker ps` 看不到、起容器才报 `address already in use`。起容器前对每个要对外映射的端口跑 `ss -tlnp | grep :`，撞了就让（Prometheus 让到了 9091）。 +- **开了 `-config.expand-env` 的组件，配置注释里别写 `${...}`**。Loki、Tempo、OTel Collector 开 `-config.expand-env` 后，会把整个配置文件文本（**连注释一起**）拿去展开 `${VAR}`，而且校验严格：变量名里出现通配符（比如注释里图省事写 `${MINIO_*}` 指代两个变量）就报 `missing closing brace`、容器起不来。注释写成纯文字（「MINIO_ACCESS_KEY / MINIO_SECRET_KEY 两个变量」），别用 `${}` 形式。这坑 Tempo 和 Loki 同款，别以为哪个展开器宽松（我第一次还误判 Tempo 宽松、又在修复注释里写了一遍反例 `${MINIO_*}` 二次踩坑）。 +- **`pull` 成功不等于 binary 在，起容器前 `docker run --rm --version` 验一下**。daocloud mirror（mini-infra 的 registry-mirror）缓存的 `otel/opentelemetry-collector-contrib:0.116.0` 是坏的——只有两层、缺主 binary，起容器报 `exec /otelcol-contrib: no such file or directory`；`docker rmi -f` 后重新下载 layer、digest 不变、还是坏。这种坏 `docker compose config` 和 `pull` 都发现不了。验法：`docker run --rm --version`，输出版本号才算真好。坏了换邻近 tag（0.116.0 坏、0.114.0 和 0.155.0 好；0.115.0 mirror 直接 403）。 +- **换镜像 tag 要顺带复核配置字段兼容**。上一条换 tag 时踩到：降到 collector 0.114.0 后，redaction 处理器不认 `blocked_key_patterns` / `redact_all_types`（这俩是新版才加的字段），而脱敏是安全红线、砍了键名屏蔽不行，只能往上取 0.155.0（字段最全、向后兼容 0.116 配置）。换 tag 别只看 binary 起不起来，还要看这版本认不认你的配置字段。 + +部署落点与运维：compose 源在仓 `deploy/infra/observability/`、部署位置 `mini-infra:/opt/infra-observability/`，`rsync` 同步（`.env` 排除、服务器上 chmod 600 不入仓），`docker compose up -d`，`HOST=100.64.0.8 bash health-check.sh` 五件全 200 = 绿。访问方式（Grafana 口令/端口/MinIO 桶）见 [`docs/内网凭据与端点.md`](../../docs/内网凭据与端点.md) 观测栈段。ssh 连法同 §2：`ssh -o ProxyCommand=none root@100.64.0.8`。