Git 仓库清洁实践:在 ffmpeg-skill 中防御密钥泄露与开发产物污染

原创2026-11-18 05:00:481,462 阅读
文章标签:音视频视频处理音频处理AI 技能MCP 服务CLI

Git 仓库清洁实践:在 ffmpeg-skill 中防御密钥泄露与开发产物污染

仓库里反复混进两类文件:密钥(secrets)与开发产物(dev artifacts)。前者一旦推送就等于公开,后者会悄悄膨胀仓库、污染 npm 包与静态站点。本文以仓库内的 git-hygiene 技能文档 为主线,完整梳理“预防—审计—清除—验证”的方法论,并用 ffmpeg-skill 自身的 .gitignore、package.json 发布白名单、tests/release_check.sh 与契约测试作为真实落地案例,说明这套规则在 Python + Node 混合项目里如何生效。

两类文件的共性是:预防几乎零成本,事后清理代价极高,因为 git 历史是永久的,公开仓库会把一切推送出去。下面按“为什么 .gitignore 不够 → 如何审计 → 密钥如何真正处置 → 如何防住验证过程弄脏工作树”的顺序展开。

两类会被提交的错误文件

类别 典型内容 为什么危险
密钥 .env 里的真实 token、settings 模块里硬编码的 AWS_*/数据库口令、被送到生产环境的 SECRET_KEY = "CHANGEME" 占位符 一旦推送即视为泄露,克隆、fork、git log -p 都会保留
构建产物 LaTeX 的 .aux/.toc/.log/.synctex.gz/.pdf、LLVM 的 *.profraw、编译后的二进制、htmlcov/、dist/、*.egg-info/ 体积大、可再生成、会与他人改动冲突
临时/个人产物 todo.db 等工具自建的 SQLite 草稿库、编辑器备份 *.backup/*.bak/~$*.docx、散落的 *.log 含本机路径、私人数据,且极易被 git add -A 卷入
操作系统噪声 .DS_Store、Thumbs.db 与项目无关,跨平台协作时反复产生 diff

在 ffmpeg-skill 中,.gitignore 已经把后两类的大部分路径挡住,并且当前检出里没有 .env、*.pem、*.key、*.db 这类文件被跟踪(依据 git ls-files 审计,仓库按设计不含云端或 API 密钥,使用说明见 README.md)。真正需要长期盯防的是 Python 字节码这类“验证过程顺手生成”的产物。

最容易忘的一条规则:.gitignore 不会取消已跟踪文件

.gitignore 只阻止“未来新增的未跟踪文件”被暂存,对 git 已经在跟踪的文件完全无效。 一个文件即使写进了 .gitignore,只要它此前已被提交,就会继续被 git add/git commit 带上。最常见的翻车现场是:.env 在规则存在之前就被提交过,于是规则形同虚设,密钥继续随每次提交外发。

要停止跟踪但保留本地副本,正确姿势是:

git rm --cached path/to/file        # untrack, leave working-tree copy in place
git rm -r --cached some/dir/        # for a directory
echo "path/to/file" >> .gitignore   # then ignore it so it doesn't come back
git commit -m "Stop tracking <file>; add to .gitignore"

关键在 --cached:不带它,git rm 会连工作区副本一起删除,本地正在用的配置就丢了。目录场景用 -r --cached,随后把路径补进 .gitignore,否则下一次 git status 它又会作为未跟踪文件冒出来。

审计仓库真正跟踪了什么

不要用 .gitignore 来推断仓库是否干净,直接读索引。以下命令来自 git-hygiene 技能文档,可原样执行:

git ls-files | grep -iE '\.(env|pem|key|p12|profraw|log|bak|db|sqlite3?)$'
git ls-files | grep -iE '(^|/)(\.DS_Store|~\$|todo\.db|node_modules/|__pycache__/)'
git ls-files '*.db' '*.sqlite*'                 # scratch databases
git ls-files | xargs -I{} du -h {} | sort -rh | head   # surprisingly large tracked files

四条命令分别对应四个问题:是否有密钥形态文件被跟踪、是否有编辑器/OS/临时产物、是否有草稿数据库、是否有异常大的被跟踪文件。最后一条尤其值得形成习惯——大文件往往不是代码,而是误入的媒体素材、数据集或打包产物。

在此基础上可以加一条“已跟踪但已被忽略”的反查,用于发现历史遗留:

git ls-files -ci --exclude-standard   # tracked-but-ignored: 规则已写,文件还在索引里

这条命令正是“.gitignore 写了但没 git rm --cached”的直接证据。在 ffmpeg-skill 当前检出上执行结果为空,说明忽略规则与索引是一致的;一旦有输出,就应当用上一节的 git rm --cached 处理。

在 ffmpeg-skill 实测(git ls-files 共 425 个文件)中,体积前列的是演示素材而非代码:assets/demo.gif(1.6M)、site/media/filler_en.mp4(1.4M)、site/media/reframe_talk.mp4(1.2M),以及 516K 的 CHANGELOG.md。这些属于产品要展示的资源,是有意跟踪的;审计的价值在于区分“有意跟踪”与“顺手带进来”,而不是追求一条零命中的 grep。

密钥处置:git rm 远远不够

把密钥从 HEAD 移除不会把它从历史里移除:git log -p、引入它的那次提交、以及所有已克隆/已 fork 的副本仍然能看到明文。文档给出的三步顺序不可颠倒,而且只有第一步真正保护你:

  1. 轮换凭证(rotate)。 任何曾经接触过远端的密钥都按已泄露处理:签发新 token/key/password,吊销旧的。这一步必须最先做,因为值在推送瞬间就已经公开。
  2. 停止继续跟踪。 git rm --cached + 写入 .gitignore,并补一个 .env.example,只记录需要哪些变量名,值必须是占位符。
  3. 必要时清洗历史。 例如 git filter-repo --invert-paths --path .env,或使用 BFG,然后强制推送。这会重写 SHA、打断协作者,因此通常作为维护者在轮换之后单独执行的步骤,而不是塞进自动化 PR。

文档特别点出一个危险的反模式:只做 (2) 和 (3)、跳过 (1) 的 PR 会带来虚假安全感——值仍然有效,仍然存在于历史克隆与 fork 中。因此评审时必须明确把“轮换”写成人类负责的必办后续项,而不是让 PR 合入即宣告问题解决。

ffmpeg-skill 的定位让这件事简单很多:项目宣称“No API keys, no cloud”,仓库中不存在 .env 形态文件,所以轮换这一半当前不适用;但流程仍应保留,因为一旦将来引入任何云端能力,第一步的优先级高于任何 git rm。

“已提交”等于“已公开”

对公开仓库而言,尤其是用 path: '.' 部署的静态站点(GitHub Pages 会把整个仓库上传),每个被跟踪文件都可以通过公开 URL 取到。宣传站根目录下放一个草稿 todo.db,它就真的可以通过 /todo.db 被下载。提交到任何公开仓库前,都应假设任何人都能下载它。

ffmpeg-skill 的站点构建提供了一个更可控的对照方案:.github/workflows/pages.yml 并不采用“整仓上传”,而是先用 .github/scripts/build_pages.py 把首页与仓库 Markdown 组装到 _pages,再产出 _site 并作为 Pages artifact 发布;同时 .gitignore 明确忽略这两个目录:

# GitHub Pages build (.github/scripts/build_pages.py)
_pages/
_site/

这形成两道隔离:构建中间产物不会进索引,发布内容也不是“仓库有什么就发什么”。无论采用哪种发布方式,判定标准不变——凡是进了索引的文件,都按“已公开”对待。

预防一:把个人噪声交给全局忽略

编辑器文件、OS 文件、工具自建草稿库属于“每个开发者自己的噪声”,应当全局忽略,而不是在每个项目的 .gitignore 里重复一遍,这样它们在任何仓库都不会落地:

git config --global core.excludesFile ~/.gitignore_global
printf '%s\n' '.DS_Store' '*.swp' 'todo.db' '*.profraw' >> ~/.gitignore_global

core.excludesFile 只影响本机,不会随仓库分发,因此适合承载“个人习惯”;项目级的公共产物规则仍应写在仓库的 .gitignore 里,两者互补而非替代。

预防二:在提交时拦截密钥

比“事后清洗”便宜得多的是在 commit 阶段就阻断,让密钥永不进入历史。文档给出的 .pre-commit-config.yaml 同时挂两个扫描器:

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/gitleaks/gitleaks
    rev: v8.18.0
    hooks: [{id: gitleaks}]
  - repo: https://github.com/Yelp/detect-secrets
    rev: v1.5.0
    hooks: [{id: detect-secrets, args: ["--baseline", ".secrets.baseline"]}]

两者定位略有差异:gitleaks 面向提交内容做模式匹配,detect-secrets 借助 baseline 文件把“已确认的历史误报”固定下来,避免每次提交重复报警。注意 ffmpeg-skill 目前没有 .pre-commit-config.yaml,这条属于可选的加固手段,而不是仓库现状。

配套的项目级 .gitignore 起步模板(应当提交进仓库):

# Secrets / local config
.env
.env.*
!.env.example
*.pem
*.key

# Python build/test artifacts
__pycache__/
*.py[cod]
build/
dist/
*.egg-info/
.coverage
htmlcov/
.pytest_cache/

# Scratch / OS / editor
*.db
*.sqlite
*.sqlite3
*.profraw
*.log
*.bak
*.backup
.DS_Store
~$*

对照 ffmpeg-skill 实际的 .gitignore,可以看到同一套思路按项目形态做了裁剪:

# demo / test output
examples/out/
demos/out/
tests/out/
*.log

# python
__pycache__/
*.pyc

# node
node_modules/
package-lock.json

# editors / OS
.DS_Store
.vscode/
.idea/

# downloaded real-world corpus
tests/corpus/

# eval staging (fixtures, prompts, per-run outputs) -- not part of the repo
scratchpad/

# GitHub Pages build (.github/scripts/build_pages.py)
_pages/
_site/

三点值得注意:tests/corpus/ 与 scratchpad/ 是“可再生成的输入/暂存区”,忽略它们可避免把评测数据与下载语料带进仓库;package-lock.json 被忽略属于该项目的取舍(它不使用运行时 npm 依赖);*.log、__pycache__/ 与模板完全一致。

验证会弄脏工作树:括号式检查法

编译器、测试运行器、资源管线经常在只是“验证改动”的命令里写入检出目录:生成未忽略的缓存文件,或重新生成一个被跟踪的分发产物(PDF、编译后的 CSS)。命令返回绿色,不代表工作树里只剩你的改动。

正确做法是用 git status 把验证“括起来”,并且只暂存审阅过的路径:

git status --short
make test                         # or the project's real build command
git status --short
git diff -- path/you/changed
git add path/you/changed          # never sweep in generated files with git add -A
git diff --cached --check
git diff --cached --stat

git add -A 是这里最需要戒掉的命令:它会把验证过程产生的所有垃圾一起带走。git diff --cached --check 还能提前发现行尾空白等会被 CI 卡住的问题。

如果某个工具必然产生噪声输出,就在一次性副本里跑,既保留真实构建,又让生成物远离补丁:

scratch_dir=$(mktemp -d)
rsync -a --exclude .git ./ "$scratch_dir/"
(cd "$scratch_dir" && make build)

当验证确实改动了“有意不纳入本次改动”的被跟踪产物时,先看 diff 再精确恢复那一个路径:

git diff -- docs/manual.pdf
git restore -- docs/manual.pdf

两条禁令同样重要:不要用宽泛的 restore/reset 清理,检出目录里可能已有他人的工作;不要把 git stash 当作未跟踪产物的垃圾桶——普通 stash 不包含未跟踪文件,即使加 --include-untracked,也可能与 stash pop 之前重新生成的文件冲突。治本之道是显式地预防或删除已知的生成路径。

真实案例:ffmpeg-skill 的 Python 字节码进了 npm 包

这是本文最有价值的落地样本,因为它同时踩中了“验证弄脏工作树”和“忽略规则与发布白名单不一致”两个坑。

现象。 本地跑过测试后,scripts/__pycache__/*.pyc 会出现在 npm publish --dry-run 的清单里——一次实测中多达 59 个 .pyc,还带着本机路径。注意 .gitignore 里明明写着 __pycache__/,但 .gitignore 对 npm 打包没有任何约束力,它只影响 git 索引。

第一版修复(0.12.6)。 参见 CHANGELOG.md:package.json 的 files 数组把 tarball 限定在 bin/、scripts/、mcp/、references/、SKILL.md、README.md、LICENSE,但这种 files 作用域的打包并不会像 git 那样自动尊重 .gitignore,于是 0.12.5 的包把解释器生成的每个 .pyc 都发了出去——运行时无害(Python 会重新生成),却白白占了约 45% 的解包体积。当时新增了 .npmignore 来排除 __pycache__/、*.pyc、*.pyo,解包体积从 913.7 kB / 64 个文件降到 496.8 kB / 40 个文件。

第二版修复(npm 10 下仍会复发)。 后续审计发现:一旦设置了 files,npm 10 会打包所列目录下的所有内容,.npmignore 说什么都不算。真正的生效位置是 files 末尾的否定条目,见 package.json:

"files": [
  "bin/",
  "scripts/",
  "templates/",
  "mcp/",
  "references/scripts.md",
  "...",
  "docs/contract.md",
  "SKILL.md",
  "README.md",
  "LICENSE",
  "!**/__pycache__/**",
  "!**/*.pyc",
  "!**/*.pyo"
]

设计说明把它写成了一条明确决策,见 docs/design-decisions.md:字节码靠 files 而非 .npmignore 挡在包外,.npmignore 保留下来并在文件里注明“为什么它不够”,以便将来某个版本的 npm 真的会应用它。.npmignore 的注释正是这段历史的现场记录:

# Compiled Python bytecode caches: interpreter-specific, never meant to ship.
# This file alone does NOT keep them out. package.json's "files" allow-list wins over it: with
# npm 10, a checkout that had run the tests packed 59 scripts/__pycache__/*.pyc files (#467 A222).
# The exclusion that works is the negated entries at the end of "files" ...

三层防线。 修复不只改了配置,还补了可执行的守卫:

  1. 发布前闸门。 tests/release_check.sh 第一步就 npm pack 到临时目录,逐个校验必需文件存在、references/process-pitfalls.md 不在包内,然后直接对 tarball 列表做正则匹配:一旦命中 __pycache__/ 或 .py[co] 结尾的文件就 exit 1。
  2. 契约测试固化规则。 tests/test_contract.py 的 test_npm_package_leaves_out_python_bytecode 先静态断言 files 里三个否定条目存在、release_check.sh 里含对应正则,再在能启动 npm 的环境里真正 py_compile 出一个 .pyc,跑 npm pack --dry-run --json 验证它不会出现在清单中(Windows 与无 npm 的 CI 任务会跳过运行时那一半,静态那一半仍然执行)。
  3. 安装器按 files 裁剪。 bin/install.js 的 payloadPaths() 把 package.json 的 files 当作唯一白名单:references/、docs/ 在 npm 包里只剩列出的单文件,但在 git 检出里还含演示图库与维护者笔记(17 MB 对 2.5 MB),所以安装器逐文件复制而不是整目录搬运。这从另一侧印证了“files 才是发布闸门”这一结论。

由此得到的可迁移经验:

  • 忽略规则至少有三套作用域——git 索引(.gitignore)、打包器(files/.npmignore)、安装/部署脚本(自定义白名单),它们互不继承,必须逐一验证;
  • 修完配置要加一条会失败的测试,否则规则会在下一次 npm 行为变化或目录调整时静默失效;
  • 验证命令跑完必须用 git status --short 复查。本例的廉价替代方案是:删掉散落的 __pycache__/ 目录后重跑 npm publish --dry-run,确认清单恢复干净。

提交前检查清单

把上面的规则压缩成可勾选清单,建议随 PR 模板一起使用:

Audit:
- [ ] `git ls-files` reviewed for secrets, build output, scratch DBs, OS files
- [ ] No live credentials in tracked source or .env
- [ ] No surprisingly large/binary tracked files

Remediate (if dirty):
- [ ] Secret rotated/revoked FIRST (history is public the moment it was pushed)
- [ ] `git rm --cached` + .gitignore entry for each offending file
- [ ] .env.example documents required vars with placeholder values only
- [ ] History scrub flagged as a maintainer follow-up if the secret is in history

Prevent:
- [ ] Project .gitignore covers secrets, build artifacts, OS/editor noise
- [ ] Global core.excludesFile catches per-developer scratch files
- [ ] gitleaks / detect-secrets pre-commit hook installed
- [ ] Verification bracketed by `git status --short`; only reviewed paths staged

对照 ffmpeg-skill 的现状,这份清单大部分已满足(.gitignore 覆盖产物与 OS/编辑器噪声、无密钥文件、发布闸门有自动化校验),缺口是没有安装 pre-commit 密钥扫描钩子,以及“验证弄脏工作树”仍需靠人工习惯与 release_check.sh 兜底。

与漏洞扫描的分工

本技能只回答一个问题:git 到底跟踪了什么、包到底发布了什么。若目标是扫描源码中的漏洞与硬编码密钥模式(而不是索引状态),应使用会话中已有的 /security-review 技能。两者的输入不同——一个读索引与 tarball 清单,一个读代码语义——因此不能互相替代:清干净了索引,不代表代码里没有硬编码凭证;反之亦然。

一页速查

# 1. 审计
git ls-files | grep -iE '\.(env|pem|key|p12|profraw|log|bak|db|sqlite3?)$'
git ls-files -ci --exclude-standard          # 已跟踪但仍被忽略(规则写了没生效)

# 2. 停止跟踪(保留本地副本)
git rm --cached path/to/file
git rm -r --cached some/dir/
echo "path/to/file" >> .gitignore
git commit -m "Stop tracking <file>; add to .gitignore"

# 3. 密钥:先轮换,再清理,必要时清洗历史
#    rotate -> git rm --cached + .env.example -> git filter-repo --invert-paths --path .env

# 4. 验证前后夹住工作树
git status --short && make test && git status --short
git add path/you/changed && git diff --cached --check && git diff --cached --stat

# 5. 发布前确认打包内容
npm pack --dry-run
npm run release-check

一句话总结:.gitignore 只防未来、不治已跟踪;密钥先轮换再谈清理;“已提交”即“已公开”;一切验证都要用 git status 括起来,只暂存你审阅过的路径。 ffmpeg-skill 的 __pycache__ 事件说明,这条纪律在打包器与安装器的第二、第三套作用域里同样成立,而且只有写成会失败的测试,才算真正修好。

登录后查看全文
ffmpeg-skill