企业官网建设流程全解析

本文为 AtomGit 码动四季·开源同行征稿活动参与文章

难度等级：⭐⭐⭐（3/5）｜前置知识：Git 基础、grep 正则、基础 CI 概念

今年 9 月我用 AI 辅助开发做了一个桌面工具——仓衡 RepoBalance，一个给 Git 仓库做"体检"的应用：用 Rust 写检查器插件，扫出大文件、密钥残留、提交规范问题这些"仓库健康度"指标，Tauri 2 + Vue 3 做壳，20 多天迭代出可打包发布的版本。

本地能跑、demo 能演之后，下一步就是开源。但"本地能跑"和"敢给外人 clone"之间，我给自己设了四道关：合规、结构、历史、发布。真正动手过这四道关之后我才发现——哪怕是一个只有 24 次提交的小仓库，坑一点不少：.gitignore没盖住的中间产物、git 历史里躺着本机绝对路径的原型文件、CI 里 token 权限差一种就发不出 Release。

这篇文章完整复盘这次开源化体检：四道关各查什么、用什么命令查、我真实踩过的三个坑。如果你也有一个"自己用没问题、开源就心虚"的代码仓库，这篇就是给你的检查清单。

一、先想清楚：本地可用和开源合格，差了四道关

本地仓库的目标读者只有一个人——我自己。我知道哪些目录是构建产物、哪个文件里嵌着我的机器路径、哪些提交只是给自己看的备忘。开源之后读者换成了陌生人，评价标准就完全变了。

我把这个差距整理成四道关，后面每一段对应一道关的真实操作：

四道关的顺序是有讲究的：先做合规（内容层面），再做结构（仓库骨架层面），然后处理历史（时间层面），最后才是发布（分发层面）。反过来做的代价是返工——先搭发布流程再回头扫敏感信息，每扫出一批命中，打包脚本、README 截图就得跟着改一遍。这个顺序教训我在上一个内容仓库的开源改造里已经吃过一次，这次直接按对的顺序来。

二、合规关：先知道有什么，再谈删什么

脱敏最忌讳的是"凭感觉删"。我的做法是先把敏感模式定义清楚，然后全量扫描拿到真实命中数，再逐类处理。

四类敏感模式，对应的扫描命令如下（这几条命令本身可以直接复用）：

# 1. 内网 IP 与内网地址（10.x / 172.16-31.x / 192.168.x）grep-rEn"https?://(10|172\.(1[6-9]|2[0-9]|3[01])|192\.168)\.[0-9]{1,3}"\--include="*.rs"--include="*.ts"--include="*.vue"--include="*.md"\--exclude-dir=target --exclude-dir=node_modules.>hits_intranet_ip.txt# 2. 本机绝对路径（泄露用户名和目录结构）grep-rEn"/Users/[a-zA-Z0-9_]+/"\--exclude-dir=target --exclude-dir=node_modules.>hits_local_path.txt# 3. 邮箱与个人联系方式grep-rEn"[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.(com|cn|net)"\--exclude-dir=target --exclude-dir=node_modules --exclude-dir=.git.>hits_email.txt# 4. 硬编码密钥的高危形态（辅助人工确认，不能只靠它）grep-rEin"(api[_-]?key|secret|token|password)\s*[:=]\s*['\"][^'\"]{8,}"\--include="*.rs"--include="*.ts"--include="*.yml".>hits_secret.txt

扫出来的真实结果：

工作区很干净，但历史不干净。这就是下一节历史关要讲的——git log -S一扫，那个 HTML 原型文件的初稿版本就现形了。

合规关还有一个代码仓库特有的项：.gitignore是否真的把中间产物挡在了库外。我git ls-files数了一遍：跟踪文件 135 个，target/（Rust 构建产物，本地实际占 500MB+）和node_modules/均为 0 个跟踪文件——这一项过关。开源仓库里混进一个构建产物目录，比泄露一个路径更让 clone 的人困惑。

脱敏不是扫一遍就完事。我实际执行了两轮：第一轮按模式清单全量处理，第二轮隔了一天用相同命令复扫，确认零新增命中。所以合规关的验收标准是"连续两轮扫描零新增命中"，而不是"扫过一遍了"。

三、结构关：三件套盘点与 gitignore 治理

3.1 协作三件套，缺一样补一样

开源仓库没有这三样东西，外人 clone 之后的第一反应是"然后呢"：

• README.md：回答三个问题——这个工具是什么（给 Git 仓库做体检的桌面应用，附功能演示 GIF）、怎么跑起来（pnpm install+cargo tauri dev，CI 打包流程写明）、能不能商用（Apache-2.0，指向 LICENSE）；
• LICENSE：开源前就位，选型过程（为什么是 Apache-2.0 而不是 MIT）写在 02 号文章里；
• CONTRIBUTING.md：初始版本缺失，开源前补齐——哪怕暂时只有一个人维护，也要写清楚 issue 怎么提、PR 需要过哪些检查、commit message 必须符合 Conventional Commits（03 号文章的流水线依赖这一点）。

盘点命令一行搞定，缺什么一目了然：

lsLICENSE README.md CONTRIBUTING.md CHANGELOG.md

3.2 AI 协作入口的收敛

这个仓库是用 AI 编程助手按"投喂话术 + 每日验收"的节奏开发出来的，过程中沉淀了一份AGENTS.md项目指令——里面是构建命令、验收标准、代码约定。开源前我把它做了一轮脱敏和去上下文化：删掉只有我自己看得懂的阶段性备忘，保留"任何人 clone 下来也能按它构建和验收"的部分。这件事的额外收益是：任何 AI 编程工具接手这个仓库时，都有了统一的上下文入口。

3.3 gitignore 是结构关的隐形主角

代码仓库和内容仓库在结构关的重心完全不同：内容仓库操心图片体积和目录组织，代码仓库操心中间产物隔离。我的检查方法是把"本地目录大小"和"跟踪文件数"对个账：

du-sh.# 本地 576MB（含 target/、node_modules/）gitls-files|wc-l# 跟踪 135 个文件

本地 576MB、跟踪文件只有 135 个——说明构建产物全部被.gitignore正确挡住了。反过来，如果这两个数字比例失衡，第一件事就是把产物目录补进.gitignore，再git rm -r --cached清掉已跟踪的产物。

四、历史关：git 历史比工作区更危险

这是整次体检里我认知刷新最大的一关，也是这次唯一真正扫出问题的一关。工作区脱敏得再干净，git 历史里的每一次提交都是可以 checkout 回来的。

# 在全部历史中搜索敏感内容（不只查最新版本）gitlog--all-S"/Users/"--onelinegitlog--all-S"192.168."--oneline

第一条命令扫出了一个真实命中：docs: 添加仓衡 HTML 原型文件那次提交——609 行的 HTML 原型里嵌着我的机器绝对路径。工作区后来已经处理，但初稿还躺在历史里。任何拿到仓库的人 checkout 到那个 commit，路径原样奉还。

处理方案对比：

这个仓库的实际情况是：24 次提交、单作者、开发期只有三周。历史本身没有"考古价值"（不是需要对外承诺兼容性的框架代码），而需要清洗的只有一个文件的一个提交。我最终选了filter-repo 定点替换：保留演进历史（24 次提交本身是这个项目开发方法论的证据），只把历史里的本机路径串替换掉，然后 force push 到两个远端。替换后再跑一遍git log -S验证，双零命中。

一个必须诚实交代的细节：清洗会导致历史哈希变化，如果有别人已经 clone 过旧哈希，他们的本地历史会和远端分叉。开源首日就做这件事，代价最小——拖到有 star 有 fork 之后，清洗成本会指数级上升。历史脱敏要赶在"有人关心你的历史"之前做完。

五、发布关：CI 打包、体积账与最后的检查

5.1 发布通道：双平台 + 自动打包

发布关要回答两个问题：发到哪里、谁来做安装包。

• 发到哪里：GitHub 为主站（Actions 生态成熟，桌面应用打包 workflow 现成），AtomGit 做国内镜像（国内用户 clone 快，这也是参加本次征稿的载体）；
• 谁做安装包：CI。GitHub Actions 上配了两条 workflow——一条跑测试和 Rust/前端构建检查，一条打 Windows/macOS 安装包并发布 Release；AtomGit 侧用ci/atomgit-pipeline.yml做同步构建。

5.2 体积账：代码仓库的幸运

代码仓库在体积上天然比内容仓库幸运：Rust 源码 3746 行、前端 2617 行，全部源码加起来不到 7MB，clone 秒级完成。真正的大头——target/构建目录（500MB+）和node_modules/——都在.gitignore之外。git count-objects一看 pack 只有 KB 级，无需 LFS、无需浅克隆。

这也反过来说明 3.3 节那个对账动作的必要性：只要有一个产物目录漏进跟踪区，clone 体积就会从 MB 级跳到百 MB 级。

5.3 发布前最后一轮验证

# 发布前的最终验证清单（三条全绿才 push）grep-rEn"192\.168\.|/Users/"--exclude-dir=target --exclude-dir=node_modules --exclude-dir=.git.\&&echo"FAIL: 敏感残留"||echo"PASS"gitlog--all-S"/Users/"--oneline|wc-l# 应为 0（清洗后）lsLICENSE README.md CONTRIBUTING.md# 三件套齐全

六、三个真实踩坑

1. CI 机器人权限不足，tag 打了 Release 没建

现象：桌面打包 workflow 跑完，tag 已推上去，Release 创建那一步失败——仓库陷入"有 tag 无 Release"的脏状态，下一次运行还把 tag 当成"已发版"。

根因：默认GITHUB_TOKEN只有读权限，创建 Release 需要contents: write，没显式授予。

解决：workflow 里显式声明permissions: contents: write，并养成发版后去 Release 页对账的习惯：git tag -l与平台 Release 列表逐个核对。

教训：发版动作需要 tag、Release、push 三种写权限，权限是 CI 发版的第一故障源——一次配齐，好过每次 403 再补。

2. Windows 打包productName 踩了安装包兼容性

现象：Windows 安装包打出来后安装/卸载行为异常，桌面应用在 Windows 侧的元数据不对。

根因：Tauri 配置里的productName取值与 Windows 安装器对产品名的预期不兼容，macOS 侧没暴露这个问题，测试只在一台 Mac 上跑过。

解决：productName改为RepoBalance，CI 的 Windows 打包 job 补进验收清单，两个平台都要打包验证过才能发 Release。

教训：桌面应用"开源"的验收单位是每个目标平台一个安装包，不是"我的机器上能跑"——单平台验证过的发布脚本，等于没验证。

3. CI 里二进制路径本地与打包环境不一致

现象：新增桌面打包 workflow 后第一次运行就失败，CI 找不到rb二进制——本地cargo build产物路径和打包 job 的工作目录对不上。

根因：workflow 手写的二进制路径沿用了我本地目录结构的假设，CI 环境的 target 目录层级不同。

解决：CI 里改为从cargo build的标准输出位置解析路径，并在 PR 模板里加一条"新增路径引用必须在 CI 跑绿后再合并"。

教训：一切写死本机路径假设的脚本，开源的那一刻都是定时炸弹——CI 是检验"仓库是否自包含"的最诚实测试。

七、效果与边界

整个开源化体检的执行时间线，四个阶段累计约三天（业余时间节奏，可参考）：

适用边界也要说清楚：这套"四道关"流程的样本是小型代码仓库（单人、单仓、20 余次提交）。它和内容型仓库的开源改造重心不同——内容仓库的主战场是图片体积、占位符和目录组织，代码仓库的主战场是 gitignore 治理、依赖许可证审计（02 号文章的主题）和 CI 密钥泄露。仓库越大、历史越长，历史关的清洗成本越高，"历史脱敏要趁早"这条对所有类型都成立。

八、总结

复盘下来，这次体检最值得说的三个判断：

第一，小仓库不等于低风险。24 次提交照样扫出了历史里的本机路径——敏感信息的暴露面积和仓库规模无关，只和"有没有认真扫过"有关。

第二，CI 是开源合格性的试金石。三件套齐不齐、路径自不自包含、权限配没配对，本地怎么检查都有盲区，推上 CI 跑一遍全部现形。

第三，历史脱敏要赶在有人关心你的历史之前。开源首日清洗历史，代价是一次 force push；有了 star 和 fork 之后，同样的清洗要面对无数分叉的本地副本。

这个仓库现在已在 GitHub 和 AtomGit 双平台开源，发版流水线（03 号）、依赖与 issue 治理（04 号）都跑在这个仓库上。下一篇讲开源改造里最容易被敷衍但后果最重的一步：许可证怎么选——为什么这个仓库最终选了 Apache-2.0。

真实性声明

本文所有数据（135 个跟踪文件、Rust 3746 行 + 前端 2617 行、24 次提交、扫描命中数、本地 576MB 目录体积）均来自仓库实际扫描与 git 历史统计，扫描命令文中已给全，可自行复现验证。案例仓库：atomgit.com/dickeryang/repo-balance（GitHub 同名镜像）。

参考资源

• git filter-repo 官方文档
• AtomGit 平台文档
• GitHub Docs: Removing sensitive data from a repository

专栏导航

• 上一篇：无
• 下一篇：开源许可证选择与合规落地实战

如果本文对你有帮助，欢迎点赞、收藏、转发。有任何问题或建议，请在评论区留言交流。行文仓促，定有不足之处，欢迎各位朋友在评论区批评指正，不胜感激。