仓库目录与产物边界说明

最新复审（2026-09-30 20:53）

P0-03 已按本文范围复审通过：部署源码独立克隆正式构建、发布模块完整测试、发布清单和实际远端包校验、构建后索引检查均通过，未删除既有文件。证据见《Linux生产流程测试记录》同日章节。换行导致的原始构建输入差异转入 P0-04 继续整改，不把目录边界复审等同于可重复构建或完整生产放行。

一、源码和产物分离

目录	用途	Git 边界
`backend/`	Go 服务端、运维入口、就近单元测试	源码、模块锁和迁移纳入；运行数据、二进制排除
`frontend/`	Web 页面、页面旁测试和依赖锁	源码和锁文件纳入；依赖、构建及覆盖率输出排除
`desktop/`	范围外历史源码	保留源码；二进制和 dist 排除，不进入正式发布
`deploy/`	安装、卸载、服务模板和正式部署测试	脚本、模板及测试纳入；远程临时数据排除
`build/`	发布构建入口及本地构建工作目录	仅构建脚本和说明纳入，其余产物排除
`doc/`	中文需求、设计、操作说明和脱敏验收结论	文档纳入，不嵌入凭据和数据库内容
`tests/`	正式跨模块测试	测试源码纳入；不强制迁移模块旁既有测试
`scripts/`	经审查的开发辅助工具	当前仅说明；禁止新增临时脚本替代验收
`release/`	可分发候选包	仅说明纳入，包和 manifest 留本地或发布存储
`artifacts/`	脱敏测试输出与证据	仅说明纳入，完整结果单独留存
`.runtime/`、`.deploy-stage/`	本机运行与部署暂存	全部排除

已有发布目录仍可位于 build/。release/ 是分发边界，不要求复制或删除历史包。本次整理不物理删除现有文件。

二、忽略规则与例外

仓库 .gitignore 覆盖各层级的可执行文件、归档、依赖、dist、日志、临时补丁、浏览器常用缓存目录、数据库和旁路文件、环境凭据及常见私钥名。自定义浏览器用户目录必须置于 .runtime/，远端下载文件必须置于 .deploy-stage/，避免凭文件名猜测遗漏。

不可整体忽略 *.pem 或 *.sql：backend/internal/certificate/trust/ 的 PEM 是 ACME Staging 公共 CA 证书，数据库迁移 SQL 是正式源码。它们继续纳入 Git。测试使用的合成密钥应在隔离临时目录生成；真实私钥只允许存于产品受保护存储。

忽略规则只降低误提交风险，不是安全扫描器：任意文件名都可能包含秘密；已跟踪文件也不会因为新增规则自动取消跟踪。因此提交前仍须检查索引、差异和文件内容，禁止以 git add -f 绕过边界提交产物。生产配置不得用 .env.example 的例外名存放。

三、核对方法

在项目根目录执行以下只读检查：

git status --short --untracked-files=all
git ls-files
git check-ignore -v --no-index -- .runtime/probe.json release/probe.zip artifacts/probe.json
git diff --check
git diff --cached --stat

正式回归测试在 backend/ 执行：

go test -count=1 ./internal/releasearchive -run 'TestRepositoryIgnore'

测试复制仓库 .gitignore 到临时 Git 仓库，禁用用户级和系统级 Git 配置，逐项验证应忽略和应保留的路径，并比较实际受跟踪文件清单。不使用开发机专属排除规则作为证据。测试自身创建的隔离临时目录由测试框架管理，不删除工作区已有文件。

四、复审边界

P0-03 的源码边界可通过 Git 和隔离回归复核；不得据此标记 SSH、证书签发、系统服务或恢复验收通过。独立克隆构建证据沿用对应源码提交记录，应用代码或发布逻辑变化后须重新构建验证。

3.8 KiB Raw Permalink Blame History Unescape Escape