用量观测:SpendLogs 保留策略登记 - #76
Open
Mushroom47 wants to merge 90 commits into
Open
Conversation
added 30 commits
August 8, 2026 20:12
动机与背景：PH-1 处理阻断级缺口 1.1。原 Compose 将 LITELLM_MASTER_KEY、含密码 DATABASE_URL 与 POSTGRES_PASSWORD 放入服务 environment，导致凭据进入渲染配置和容器 metadata。 关键设计取舍：遵循冻结决策 D-3，复用 Redis 的 Docker Secret 模式。PostgreSQL 改用原生 POSTGRES_PASSWORD_FILE；LiteLLM 入口脚本在最终 exec 前读取 Secret 文件并构造所需运行时变量。LiteLLM 最终进程环境可见性为已接受残余风险，已写入 README。 验证：执行 bash -n docker_litellm/work/start-litellm.sh；使用本地占位值执行 docker compose --env-file /dev/null -f docker_litellm/demo/docker-compose.litellm.yml --profile single config --format json | jq -e <服务 environment 与 Secret 挂载断言>；执行 git diff --check。关键输出：PASS static secret boundary。 影响面：仅 LiteLLM Compose、运行时入口和服务 README；未修改镜像、CI、P6/P7 或 Compose 参数化。关联 Linear：CHE-664。 剩余风险：最终 LiteLLM 进程仍需获得 LITELLM_MASTER_KEY 与 DATABASE_URL；具备容器内调试权限的主体仍应视为高权限主体。
动机与背景：PH-1 需要证明管理密钥、数据库连接凭据和 PostgreSQL 密码不会重新进入 Compose metadata、argv、日志或临时文件，并要求真实 LiteLLM 管理面探活。 关键设计取舍：新增无上游的 test-secret-boundary.sh，只生成随机本地占位值且不读取 demo/.env。它先启动 PostgreSQL/Redis、经入口 wrapper 执行独立 migration job，再启动 LiteLLM；这样 migration lock 进程也在读取 Prisma DATABASE_URL 前获得 Docker Secret。管理面以创建并删除测试 user/key 证明认证与清理路径。 验证：执行 bash -n docker_litellm/work/start-litellm.sh docker_litellm/demo/scripts/smoke-baseline.sh docker_litellm/demo/scripts/test-secret-boundary.sh；执行 ./docker_litellm/demo/scripts/test-secret-boundary.sh；执行 ./docker_litellm/demo/scripts/smoke-baseline.sh --security-check；执行 ./docker_litellm/demo/scripts/test-verification-gates.sh；执行 git diff --check。关键输出：compose_config/readiness/inspect/argv/logs/temporary_files/management_smoke/cleanup 均为 passed，management_http_status=200。 影响面：LiteLLM P1 本地 Compose 与长期安全门禁；未修改镜像、CI、P6/P7、镜像 digest 或 Compose 参数化。关联 Linear：CHE-664。 剩余风险：LiteLLM 最终进程仍可见 LITELLM_MASTER_KEY 与 DATABASE_URL，这是冻结方案接受的风险；具备容器内调试或 Docker daemon 权限的主体仍是高权限主体。
动机与背景：PH-1 真实 migration 门禁发现 Prisma 子进程可在一次性 migration 容器日志中回显完整 PostgreSQL 连接串，违反凭据不得进入日志的硬门槛。 关键设计取舍：migration lock 进程保留原有锁、返回码与诊断标记；仅捕获其子进程的合并输出，对 postgresql:// 或 postgres:// 连接串整体替换为 postgresql://<REDACTED> 后再输出。回归门禁以 0600 临时日志捕获 migration 输出并断言三类随机占位凭据均不存在。 验证：执行 python3 -m py_compile docker_litellm/work/run-migration-locked.py；执行 bash -n docker_litellm/work/start-litellm.sh docker_litellm/demo/scripts/smoke-baseline.sh docker_litellm/demo/scripts/test-secret-boundary.sh；执行 ./docker_litellm/demo/scripts/test-secret-boundary.sh；执行 ./docker_litellm/demo/scripts/smoke-baseline.sh --security-check；执行 ./docker_litellm/demo/scripts/test-verification-gates.sh；执行 git diff --check。关键运行报告：compose_config/readiness/inspect/argv/logs/temporary_files/management_smoke/cleanup 全部 passed，management_http_status=200。 影响面：仅 LiteLLM migration 子进程输出与 PH-1 回归断言；不变更数据库 schema、镜像、CI、P6/P7、镜像 digest 或 Compose 参数化。关联 Linear：CHE-664。 剩余风险：LiteLLM 最终进程环境中仍需要 LITELLM_MASTER_KEY 与 DATABASE_URL，这是冻结方案已接受的风险；本提交不改变该决策。
动机与背景：LLM Hub 生产加固 PH-3 对应 X-07。D-10 要求将 P6 已冻结的固定组合、受限输入、黄金 runner、报告聚合与 runtime Compose 留在 Git 历史回读，而不是作为产品仓长期维护的运行入口。 关键设计取舍：删除 p6-runner、预处理/产品链/聚合器、固定输入模板、runtime Compose（其中原有 docker.sock:rw）、仅用于这些编排的 driver-flow 与 Compose-render 测试；不迁移文件。保留并重写 test-p6-gates.sh 为无 Docker、无网络、无凭据、无历史 commit/digest/绝对路径依赖的 OpenClaw 静态产品契约检查。P6 README 改为精确 git show 回读说明，父 README 移除固定组合事实。 验证：bash -n docker_openclaw/p6/scripts/test-p6-gates.sh；./docker_openclaw/p6/scripts/test-p6-gates.sh（PASS P6 gates: OpenClaw image state, entrypoint, ports, and standard Compose avoid Docker socket access.）；git diff --check。未启动服务容器。 影响面：仅 docker_openclaw/p6 的历史证据编排、其说明与保留静态门禁；未改 OpenClaw Dockerfile、常规 demo Compose 或其他服务。关联 Linear：CHE-673（In Progress）。 剩余风险：跨仓 P6 真实黄金运行只能通过基线 fdbbab2 的 Git 历史审阅，不能由本次保留门禁重放；P7 归档仍待本批下一提交完成。
动机与背景：LLM Hub 生产加固 PH-3 对应 X-07。D-10 要求把 P7 已冻结的固定组合、受限输入、Launcher overlay、黄金 runner 与报告聚合保留为可由 Git 历史读取的历史证据，而不是产品仓长期维护的运行面。 关键设计取舍：删除 p7-runner、预处理器、产品链、固定输入模板、runtime Compose 与只服务于固定组合的 Launcher overlay；不迁移这些一次性文件。保留并重写 test-p7-gates.sh，使其只做无 Docker、无网络、无凭据、无历史 commit/digest/绝对路径的 Hermes 静态产品契约检查。P7 README 与父 README 均改为精确 git show 回读说明。 验证：bash -n docker_openclaw/p6/scripts/test-p6-gates.sh docker_hermes/p7/scripts/test-p7-gates.sh；./docker_openclaw/p6/scripts/test-p6-gates.sh（PASS P6 gates: OpenClaw image state, entrypoint, ports, and standard Compose avoid Docker socket access.）；./docker_hermes/p7/scripts/test-p7-gates.sh（PASS P7 gates: Hermes source pin, provenance labels, explicit local image, pull policy, and loopback dashboard publication.）；git diff --cached --check；git grep --cached 检查已删入口，除本地 skip-worktree AGENTS.md 的历史操作范例外，产品树零残留。未启动服务容器。 影响面：仅 docker_hermes/p7 的历史证据编排、其说明与保留静态门禁；未改 Hermes Dockerfile、常规 demo Compose 或其他服务。关联 Linear：CHE-673（In Progress）。 剩余风险：P7 跨仓真实黄金运行只能通过基线 fdbbab2 的 Git 历史审阅，不能由本次保留门禁重放；最终交付仍需 HEAD git ls-tree 核验与总控将 CHE-673 置于 In Review。
背景：PH-3 归档后保留的 test-p6-gates.sh 应在不启动容器的前提下断言常规 OpenClaw Compose 的稳定端口契约。 修复：端口映射在 YAML 中以双引号包裹；门禁改用与真实声明一致的模式，避免产品代码正确时发生静态误报。未改变 Dockerfile、Compose 或运行行为。 验证：bash -n docker_openclaw/p6/scripts/test-p6-gates.sh；./docker_openclaw/p6/scripts/test-p6-gates.sh（PASS P6 gates: OpenClaw image state, entrypoint, ports, and standard Compose avoid Docker socket access.）；git diff --check。未启动容器。 影响面：仅 PH-3 留存的 P6 静态门禁。关联 Linear：CHE-673（In Progress）。剩余风险：历史 P6 黄金证据继续仅能通过 D-10 指定 Git 快照回读。
动机与背景：LiteLLM Compose 过去将 project、外部网络和显式代理容器固定为 litellm-baseline/svc-litellm-*。不同本地实例或残留栈会发生资源冲突，且 smoke 与 PH-1 回归脚本直接依赖这些固定名称。
关键设计取舍：沿用本仓 PROFILE_ENV 惯例，不新增第二套 LITELLM_COMPOSE_PROJECT 配置源。Compose project 使用 ${PROFILE_ENV:-litellm-baseline}-svc-litellm；显式容器与外部网络使用相同前缀。保留 LITELLM_*_CONTAINER_NAME 显式覆盖入口以兼容定向测试。脚本改按 Compose service ID 查询容器；PH-1 回归脚本为每次 run 设置唯一 PROFILE_ENV。回环端口默认绑定和 pull_policy: never 未改变。
验证：执行两套无敏感占位环境的 docker compose -f docker_litellm/demo/docker-compose.litellm.yml --profile ha|migrate config --format json（PROFILE_ENV=ph4-config-a/b）；HA 渲染分别为 ph4-config-a/b-svc-litellm、对应 -1/-2 容器和 -net 网络，migration 渲染对应 -migrate 容器，集合无交集。另执行 bash -n docker_litellm/demo/scripts/smoke-baseline.sh docker_litellm/demo/scripts/smoke-redis-recovery.sh docker_litellm/demo/scripts/test-secret-boundary.sh 与 git diff --check，均通过。未启动服务容器。
影响面：仅 LiteLLM demo Compose、其运行态验证脚本、PH-1 回归清理逻辑和使用说明。调用方应以 PROFILE_ENV 选择实例，避免混用 -p/COMPOSE_PROJECT_NAME。
关联 Linear：CHE-674（LLM Hub 生产加固，PH-4）。
剩余风险：本提交为配置级验证，未运行需要真实镜像和 Docker daemon 的 smoke/PH-1 容器测试；该限制符合本批不启动容器的执行边界。
动机与背景：smoke-baseline.sh 与 smoke-redis-recovery.sh 分别内联 BSD stat -f 与 GNU/Linux stat -c 的权限检查，重复实现使错误信息和平台兼容策略可能漂移。 关键设计取舍：在既有 verification-lib.sh 集中提供 verification_file_mode 与 verification_assert_file_mode，按 uname -s 明确分派 BSD 系列到 stat -f %Lp、Linux 到 stat -c %a；未知平台失败关闭并给出平台名，不猜测 stat 语义。三个调用点保留原有 0600 安全断言和失败退出行为。 验证：在本机 Darwin/BSD stat 上，以只读 /dev/null 执行 source docker_litellm/demo/scripts/verification-lib.sh; verification_file_mode; verification_assert_file_mode，原生和 helper 均输出 mode=666 且断言通过。Linux 分支以静态审查确认 helper 的 Linux case 含 stat -c %a；未在本机实测，原因是当前执行主机为 Darwin，且本批明确不启动 Linux 容器。另执行重复 stat 搜索、bash -n docker_litellm/demo/scripts/verification-lib.sh docker_litellm/demo/scripts/smoke-baseline.sh docker_litellm/demo/scripts/smoke-redis-recovery.sh 与 git diff --check，均通过。 影响面：仅 LiteLLM 验证脚本的宿主机临时凭据/header 文件权限检查；不改变 Compose、镜像或运行服务。 关联 Linear：CHE-674（LLM Hub 生产加固，PH-4）。 剩余风险：Linux stat 分支仅做静态审查，待 Linux CI 或后续允许的 Linux 宿主验证补充运行态证据。
动机与背景：start-litellm.sh 仅使用 set -eu，standalone fallback 直接重定向写入 config.yaml。若写入中断，可能留下部分内容或权限不符合凭据相邻配置的最小权限原则。 关键设计取舍：启用 set -Eeuo pipefail，并安装只清理本次 mktemp 路径的 EXIT trap。fallback 以 umask 077 在目标 config.yaml 同目录创建临时文件，显式 chmod 600，写完后以 mv 原子替换，再清空清理句柄；失败时 trap 删除尚未移动的临时文件。Compose 挂载既有只读 config.yaml 的主路径未变。 验证：执行 bash -n docker_litellm/work/start-litellm.sh；静态检查确认严格模式、EXIT trap、umask 077、同目录 config.yaml.tmp.XXXXXX、chmod 600、mv -f 和失败清理路径均存在；执行 git diff --check，均通过。未启动 LiteLLM 或其他服务容器。 影响面：仅无 Compose 挂载 config.yaml 时的 backwards-compatible standalone fallback；常规 P1 Compose 启动继续使用只读挂载配置。 关联 Linear：CHE-674（LLM Hub 生产加固，PH-4）。 剩余风险：在本批“不启动服务容器”的限制下，未对中断时序做运行态故障注入；实现采用同目录临时文件和 POSIX rename/mv 原子替换语义。
动机与背景：PH-4 的 Compose 参数化验收要求保留 pull_policy: never。对链式基点的完整 Compose 复核发现该安全约束未在 LiteLLM、PostgreSQL 与 Redis 服务渲染中声明，可能允许本地验证静默拉取可变外部状态。 关键设计取舍：在共享 LiteLLM service extension 及 PostgreSQL、Redis 两个独立服务上统一声明 pull_policy: never；不改变已固定的镜像引用、端口、profiles、卷或网络结构。 验证：使用无敏感占位环境分别以 PROFILE_ENV=ph4-config-a 与 PROFILE_ENV=ph4-config-b 执行 docker compose -f docker_litellm/demo/docker-compose.litellm.yml --profile ha|migrate config --format json；每份渲染的 services 均为 pull_policy=never，且 project、显式容器、网络名在两个实例间无交集。执行 git diff --check 通过；未启动服务容器。 影响面：LiteLLM demo 仅在本地不存在镜像时失败并要求调用者显式构建/准备所需镜像，避免静默拉取；不涉及镜像 digest 或 CI（PH-2 边界）。 关联 Linear：CHE-674（LLM Hub 生产加固，PH-4）。 剩余风险：本提交为 Compose 渲染验证，未运行服务容器；镜像可复现性、digest 与 CI 门禁仍由 PH-2 负责。
按代码规范裁决,7 个 test/smoke 脚本移出版本控制,本地保留; verify-p1 等环境编排工具不属测试,保留在分支。历史提交仍可回读。 Co-Authored-By: Claude Fable 5 <[email protected]>
lab-dev 每个 docker_<服务>/ 模块的 demo/ 子目录存放的是该镜像的 Compose 运行包(compose + 配置 + .env.example + 配套脚本),按内容 本质更名为 compose/,与 work/(构建进镜像的脚本)形成清晰对照。 8 个模块 git mv,同步修正 .gitignore、README、AGENTS 约定文档与 脚本内路径引用;compose config 校验通过。 Co-Authored-By: Claude Fable 5 <[email protected]>
- 删除 p6/p7 归档墓碑 README;父 README 去除归档指引与阶段命名 - docker_litellm README 重写为产品文档:去除阶段过程叙述与已移出脚本引用 - .env.example/Dockerfile/启动脚本注释中性化;删除无消费方的 OPENCLAW 参考变量 - 验收流水线脚本(verify-p1/migration-concurrency/aggregate)移出分支,本地保留; run-migration 与其依赖的 verification-lib 作为运维工具保留 Co-Authored-By: Claude Fable 5 <[email protected]>
Co-Authored-By: Claude Fable 5 <[email protected]>
AGENTS.md / CLAUDE.md / .claude/skills 为本地开发协作配置,不进入版本控制。 Co-Authored-By: Claude Fable 5 <[email protected]>
Co-Authored-By: Claude Fable 5 <[email protected]>
|
陈庚 seems not to be a GitHub user. You need a GitHub account to be able to sign the CLA. If you have already a GitHub account, please add the email address used for this commit to your account. You have signed the CLA already but the status is still pending? Let us recheck it. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
概要
配合 labnow-shell 用量观测功能,在
docker_litellm/README.md登记 LiteLLM SpendLogs 数据保留运维说明(单文件 +15 行,纯文档)。maximum_spend_logs_retention_period支持(附源码链接);当前基线未启用,仅登记策略🤖 Generated with Claude Code