企业官网建设流程全解析

Keploy 贡献工作流实战：客户数据脱敏、Conventional Commits 与 PR/Issue 规范（keploy-pr-workflow）

【免费下载链接】keployOpen-source platform for creating safe, isolated production sandboxes for API, integration, and E2E testing.项目地址: https://gitcode.com/GitHub_Trending/ke/keploy

Keploy 是一个以“录制真实生产流量并生成 mock”为核心机制的测试平台，这意味着任何从仓库或本地环境流出的 fixture、日志、报错输出都可能携带真实客户数据。本文基于 Keploy 仓库内置的贡献工作流技能文档.claude/skills/keploy-pr-workflow/SKILL.md展开，完整覆盖其中的客户数据卫生（customer-data hygiene）红线清单、Conventional Commits 提交规范、PR/Issue 模板要求、破坏性 git 操作禁区与 Issue 提交要素，并结合仓库中 commitizen 预提交钩子、DCO 签署文档与keploy sanitize脱敏工具的源码实现加以印证。读完后你将掌握：在向 Keploy 仓库提交任何 PR、Issue 或 commit 之前，如何系统性地完成数据脱敏自查、写出合规的提交信息，并避开不可逆的 git 操作。

何时触发这套工作流

原文档给出了四条明确的触发场景。当处于以下任一状态时，就应该把这套流程当作“离开本机前的检查关卡”：

• 即将执行gh pr create、gh pr edit或gh issue create；
• 正在撰写一条将落入main分支的 commit message；
• 在推送前自查自己写的 diff；
• 要把错误输出、日志或样例数据复制进 PR 描述、Issue、测试 fixture 或 README。

这四条场景的共同点是：内容即将离开本地机器。文档因此把数据卫生定义为“non-negotiable（不可谈判）”——这是整个工作流的第一优先级。

客户数据卫生：Keploy 贡献者的一号红线

为什么 Keploy 特别强调这一点

Keploy 的工作方式是“录制真实用户应用”（records real user applications）。它的 traces、mocks、recordings 和 logs 天然会携带客户数据：带鉴权 token 的响应头、含 PII 的请求体、内部主机名、可以反查到具体用户的 request ID。原文档的要求是：

在检查之前，把每一个 fixture、日志片段、错误 dump 都当作**已污染（tainted）**对待。

这并非抽象的合规口号，而是与产品形态直接绑定的风险模型：Keploy 的录制产物本身就是客户的完整流量画像。

离开机器前的逐项脱敏清单

原文档列出了七类必须清洗的内容，这里完整继承并逐项说明处理方式：

1. 凭证（Credentials）— API key、bearer token、JWT、数据库密码、session cookie、OAuth client secret、AWS/GCP/Azure 密钥。如果某个测试确实需要一个凭证，应从环境变量读取；文档中使用占位符，如sk-xxxxxxxx、Bearer <token>。
2. 内部主机名与 URL—*.internal、*.prod、*.corp、真实公司域名。样例中应使用example.com、httpbin.org或 loopback 地址。
3. 非保留网段的 IP 地址— 凡是日志中出现的公网 IP，都应假设为可追踪的；替换为192.0.2.1（TEST-NET-1，RFC5737 文档专用网段）。原文档的判定标准是：只有 RFC1918 / loopback / TEST-NET 三类地址可以保留。
4. 用户标识符— 邮箱、用户名、账号 ID、订单 ID、客户姓名。用user@example.com、user-123等替代。
5. Request/Trace ID— 这些 ID 会在可观测性系统中回连到真实流量，粘贴进日志前必须打码。
6. 真实录制流量— 永远不要提交客户的keploy/test-set-*目录。即便“匿名化”过的录制，也往往在路径或时序中留下可识别特征。如果确实需要样例录制，应针对samples-go、samples-python等官方样例应用重新生成。
7. 生产环境运行的堆栈跟踪— 会泄露文件路径、二进制版本，有时还包含内存中的值。

原文档最后给出一条判定原则：

只要你不确定某个东西是否来自客户，那它就是。宁可脱敏过度——细节可以补回来，但发布出去的内容收不回来（you can always add detail back, you can't un-publish）。

源码印证：仓库内置了keploy sanitize自动脱敏工具

上述清单中的第 6 类风险（提交的 test-set 目录）在仓库源码中有对应的自动化防线。CLI 层在 cli/sanitize.go 注册了sanitize子命令，其用途描述为 “sanitize the keploy testcases to remove the sensitive data”，使用示例为：

keploy sanitize -t "test-set-id"

该命令进入 pkg/service/tools/sanitize.go 的Sanitize方法，其实现要点与 PR 卫生规则直接呼应：

• 通过extractTestSetIDs解析-t指定的测试集，未指定时处理全部测试集；
• 定位./keploy/<testSetID>目录后，若目录中已存在secret.yaml则跳过该测试集（说明已经脱敏并抽取过密钥）；
• 对测试集内文件执行 gitleaks 风格的密钥检测：RedactYAML会把检测到的密钥从 YAML 中原位替换为占位符，同时将真实值集中写入keploy/<set>/secret.yaml（见 pkg/service/tools/sanitize.go）。这意味着“密钥从 fixture 中剥离、集中管理”正是工具化的标准动作，而贡献者手写 fixture 时也应遵循同一原则：从环境变量读取、文档中留占位符。

检测规则由仓库内嵌的自定义 gitleaks 配置 pkg/service/tools/custom_gitleaks_rules.toml 提供，其中包含 AWS Access Key、AWS Secret Key、GitHub PAT / OAuth / App Token 等规则（AKIA[A-Z0-9]{16}、ghp_[0-9a-zA-Z]{36}等正则），覆盖了卫生清单第 1 类“凭证”的常见形态。

此外，仓库的 .gitignore 已经将keploy、keploy.yml、keploy-logs.txt、keploy-config.yaml等录制/运行产物列入忽略清单，从版本控制层面堵住了“误提交客户 test-set”的通道。

Commit Message 规范：Conventional Commits + commitizen + DCO 签署

格式与强制机制

原文档规定的格式为：

<type>(<scope>): <subject>

即 Conventional Commits 规范，且由 commitizen 通过.pre-commit-config.yaml在提交时强制校验。仓库中的实际配置印证了这一点：

.pre-commit-config.yaml的全部内容：

repos: - hooks: - id: commitizen stages: - commit-msg repo: https://github.com/commitizen-tools/commitizen rev: v2.21.2

钩子挂在commit-msg阶段，意味着不符合规范的提交信息会在本地被拦截。而.cz.toml进一步把约定固定下来：

[tool.commitizen] name = "cz_conventional_commits" version = "0.2.4" tag_format = "v$version"

允许的 type 有：feat、fix、docs、style、refactor、test、chore。

仓库的 AGENTS.md 在 “Commit hygiene” 一节重申了同一套规则，并补充了执行细节，可作为规范的第二出处：

• .pre-commit-config.yaml接入 commitizen（Conventional Commits）；
• .cz.toml将约定锁定为cz_conventional_commits，type 使用feat:、fix:、chore:、refactor:、test:、docs:；
• 每个 commit 都必须有正文（空一行后写一段“改了什么、为什么改”）。

三条写作规则

1. 主题行用现在时、祈使语气：写fix: resolve null pointer on test-set reset，而不是fixed/fixes。
2. 正文强制存在：主题行后空一行，再写一段描述what changed and why。原文档特别强调：即便是单行小改动，正文也是必选的。
3. 用git commit -s签署：让 git 从配置中读取身份生成Signed-off-by尾注，不要手工拼写trailer——手写的Signed-off-by与 author 不一致是常见的签署失败原因。

DCO 背景

签署要求并非该技能文档的发明，而是仓库贡献协议的硬性条款。.github/CONTRIBUTING.md 的 “Signing-off on Commits (Developer Certificate of Origin)” 一节要求所有贡献者对每个 commit 接受 DCO 声明，并给出同样的操作示例：

$ commit -s -m "my commit message w/signoff"

文档还建议在~/.gitconfig中设置别名，让所有提交默认带签：

[alias] amend = commit -s --amend cm = commit -s -m commit = commit -s

并要求使用真实姓名与可达邮箱（不接受匿名贡献）。这与技能文档中 “don't hand-construct theSigned-off-bytrailer” 的要求互为表里：-s保证 tailer 与 git 配置中的 author 一致，从而通过 DCO 检查。

PR/Issue 标题与正文：跟随当前仓库的模板

原文档对此给出的核心规则只有一句：

PR/issue 的模板应该与你正在工作的仓库中实际使用的模板保持一致。

对于 Keploy 主仓库，当前生效的 PR 模板是.github/PULL_REQUEST_TEMPLATE.md。提交 PR 时应完整填写其结构，主要包括：

• Describe the changes that are made— 变更描述；
• Links & References— 包括Closes: #<issue number>（极小改动可写 NA）、相关 PR、相关 Issue、相关文档；
• What type of PR is this?— 勾选类型（Chore / Feature / Bug Fix / Documentation / Style / Refactor / Performance / Test / CI / Revert）；
• Added e2e test pipeline?— 是否新增了端到端测试流水线（可勾选 “no, because they aren't needed” 并说明）；
• Self Review done?、文档更新、测试步骤、截图/日志等自检项；
• PR 标题与分支命名的语义约定— 模板给出示例：PR 标题如fix: patch MongoDB document update bug，分支名如feat/#1-login-flow，要求遵循 Keploy 的 PR/分支语义约定。

注意一个与 commit 规范一致的细节：模板里的 PR 标题示例fix: patch MongoDB document update bug正是 Conventional Commits 形式，说明 commit 规范与 PR 标题规范在 Keploy 中是同一套语义体系的两层落地。Issue 模板则位于.github/ISSUE_TEMPLATE目录，提交 Issue 时按其中的字段填写，不要自创格式。

破坏性 git 操作禁区

原文档第 4 节划定了一条明确的红线：以下操作未经用户明确批准，一律不得执行：

文档给出的原则是：“拿不准就问（When in doubt, ask）”——破坏性操作的确认成本极低，但撤销成本极高。这条规则对使用 AI Agent 协作的贡献者尤其关键：Agent 在自动化流程中默认不应执行上述任何一条。

Issue 提交规范：四要素 + 复现录制

在向 Keploy 仓库提交 Issue 或在他人 Issue 下评论时，原文档要求：

1. 同样的客户数据规则适用— 粘贴日志前先按前文的脱敏清单清洗；
2. 提交内容必须包含四个要素：
   • Keploy 版本（keploy --version的输出）；
   • 操作系统与架构（OS/arch）；
   • 你执行的确切命令；
   • 该问题在 Docker 与原生（native）两种运行方式下是否都能复现。
3. 附带的复现录制必须重新生成— 如果要贴一份录制来复现问题，必须针对公开样例应用（如samples-go、samples-python）重新录制，永远不要附带客户真实的 test-set。

其中keploy --version命令在源码中对应 main.go 处设置的版本标识符（utils.VersionIdentifier = "version"），keploy二进制本身即以 CLI 形式暴露该子命令，Issue 作者可直接复制输出。

Keploy 对 Docker 与原生两种方式分别支持（两者在录制机制上有差异，见 AGENTS.md 的兼容矩阵），因此“是否两边都能复现”是区分“环境问题”与“代码缺陷”的关键分诊信号。

与 keploy-e2e-test 技能的衔接

原文档末尾声明了与另一技能keploy-e2e-test的关联：

keploy-e2e-test— 在开 PR 之前，先针对真实样例应用验证行为变更。

该技能定义于.claude/skills/keploy-e2e-test/SKILL.md，其要点是：用源码构建 Keploy 二进制（与 CI 相同的go build命令），在官方样例应用上跑真实的 record → replay 流程，以reports/test-run-*/test-set-*-report.yaml全部status: PASSED作为验证标准。两个技能构成一条完整的贡献流水线：

e2e 验证行为变更（keploy-e2e-test） │ ▼ 数据脱敏自查 + 合规 commit + 模板化 PR（keploy-pr-workflow） │ ▼ push / gh pr create

即：先用 e2e 证明“变更是对的”，再用 pr-workflow 保证“离开本机的内容是无害且合规的”。

提交前自检清单（综合提炼）

将原文档各节规则合并为一份可直接执行的 checklist：

• diff 与粘贴内容是否按七类清单完成脱敏（凭证、内部域名、公网 IP、用户标识、request ID、客户 test-set、生产堆栈）？
• 是否确认没有提交keploy/test-set-*目录或其中的任何文件？（必要时可用keploy sanitize先做工具化脱敏）
• commit message 是否为<type>(<scope>): <subject>形式，type 属于feat/fix/docs/style/refactor/test/chore？
• 主题行是否现在时祈使语气，正文（空行 + 一段 what & why）是否存在？
• 是否使用git commit -s由 git 生成Signed-off-by？
• PR/Issue 是否遵循当前仓库模板（.github/PULL_REQUEST_TEMPLATE.md/.github/ISSUE_TEMPLATE）？
• Issue 是否包含keploy --version、OS/arch、确切命令、Docker vs 原生复现情况四项？
• 是否未执行任何需要显式批准的破坏性 git 操作？
• 行为类变更是否已先用 e2e record/replay 验证（参见keploy-e2e-test技能）？

这套工作流的本质是把“Keploy 会接触真实客户数据”这一产品事实，转化为贡献者侧的强制性操作规程：规范落在.claude/skills/keploy-pr-workflow/SKILL.md，机制落在 commitizen 钩子（.pre-commit-config.yaml）、DCO 签署（.github/CONTRIBUTING.md）与 sanitize 工具（cli/sanitize.go）上，二者共同保证进入main分支与公开 Issue 区的内容既合规又安全。

【免费下载链接】keployOpen-source platform for creating safe, isolated production sandboxes for API, integration, and E2E testing.项目地址: https://gitcode.com/GitHub_Trending/ke/keploy