企业官网建设流程全解析

• API网关
• 后端
• 负载均衡

本文围绕 GPT-Load（自托管 AI 网关）仓库的 CONTRIBUTING.md 展开，逐条拆解人类贡献者的完整协作路径：先弄清1.x与2.x两条版本线的分工，再掌握make dev/build/test/check四件套与独立third_party/cpaembeddedmodule 的本地验证方法，接着理解维护者专用的make release/make release-simulate发版验收机制，最后落实 PR 提交、Commit 规范、代码风格与凭据安全红线。读完本文，你将能按项目自身的验收标准独立提交一个高质量 PR，并准确判断"哪些检查必须本地跑、哪些交给 CI"。

开始之前：三类请求的正确入口

GPT-Load 的贡献入口按问题性质严格分流，仓库在.github/ISSUE_TEMPLATE/config.yml中固化了这一约定：

• 安全漏洞：禁止开公开 issue。必须走私有漏洞报告（SECURITY.md 明确要求通过 Private Vulnerability Reporting 提交），以便维护者在公开披露前完成调查与修复。
• 使用类问题：先查官方文档或到社区交流群，不要开 issue。仓库的 issue 模板配置了blank_issues_enabled: false，并在contact_links中把文档、群聊、漏洞报告三类入口分别固定到对应链接。
• 较大的改动：先开 issue 讨论方向，避免完成后才发现方案不合适，白费一轮实现成本。

也就是说，main分支的 PR 通道只面向"已经讨论清楚方向的实质贡献"。

版本线：1.x 与 2.x 是两套不互通的实现

从仓库结构看，CONTRIBUTING.md 强调的版本线差异是真实且重要的工程事实：

• 2.x是当前开发主线，基于main分支，PR 也提交到main。这是唯一接受新功能开发的版本线。
• 1.x处于维护状态，只接受安全和严重缺陷修复。

两条版本线的数据不互通，因此不能把 1.x 的修复或配置直接"平迁"到 2.x。结合 SECURITY.md 中 "Supported versions" 表格可见，当前2.0.x处于预发布安全支持候选阶段，而1.4.x是维护中的安全支持线——这印证了"1.x 仅维护"的定位。

本地开发：Go + Node/pnpm 双栈与四个 Make 目标

环境要求

按 CONTRIBUTING.md 的说明，本地开发需要：

• Go：具体版本以 go.mod 为准（当前声明go 1.27.2），CI 也通过actions/setup-go的go-version-file: go.mod读取同一版本来源，保证本地与 CI 一致。
• Node.js + pnpm：pnpm 通过 corepack 调用。仓库前端在 web/package.json 中声明了"packageManager": "pnpm@11.17.0"与"engines": {"node": ">=24.11.0"}，corepack 会自动按此声明切换 pnpm 版本。

四个核心 Make 目标

Makefile 中与日常开发直接相关的是这四个目标：

make dev # 构建管理 UI 并以 race 检测运行 / build the web UI and run with race detection make build # 构建 UI 与二进制 / build the UI and the binary make test # 运行 Go 单元测试 / run Go unit tests make check # 完整验收门禁 / the full acceptance gate

逐个拆解其实际行为：

• make dev：先执行_web-build（corepack pnpm --dir web install --frozen-lockfile+pnpm run build），再以go run -race .启动。race 检测在开发阶段就默认开启，这一点直接对应"开发即发现数据竞争"的工程取向。
• make build：同样的 UI 构建流程，随后go build -o gpt-load .产出二进制，供本地试运行或打包。
• make test：执行go test -count=1 . ./internal/...。注意-count=1强制禁用测试缓存，确保每次都是真实执行——这是避免"缓存假绿"的严谨做法。
• make check：真正的"验收门禁"，按 Makefile 依次执行：

1. gofmt -l .必须输出为空（Go 格式检查）；
2. go mod tidy -diff（依赖清单与go.mod/go.sum一致，无多余或缺失条目）；
3. go vet ./...（静态检查）；
4. 前端pnpm lint、pnpm format、pnpm build（其中 lint 包含eslint . --max-warnings=0和样式检查脚本，见 web/package.json）；
5. go build -o gpt-load .（后端构建）；
6. go test -count=1 . ./internal/...（全量单元测试）；
7. git diff --check（空白错误检查）。

make check的每一步都能在.github/workflows/ci.yml的 CI 任务中找到对应镜像（gofmt、mod tidy -diff、vet、web 构建、后端构建、git diff --check），也就是说make check是 CI 的本地等价物——PR 前本地跑通它，基本等价于 CI 的静态与单测部分通过。

独立模块 third_party/cpaembedded 的特殊处理

CONTRIBUTING.md 特别指出：third_party/cpaembedded是独立的 Go module，不在make check覆盖范围内。这一点在 go.mod 中有明确依据：主 module 通过replace github.com/router-for-me/CLIProxyAPI/v8/gptload-embedded => ./third_party/cpaembedded将其作为嵌入式 CPA 桥接模块引入。改动该目录时需额外执行：

cd third_party/cpaembedded go mod tidy -diff go vet ./...

而该 module 的race 测试由 CI 负责，按仓库约定不在本地运行——对应 .github/workflows/ci.yml 中的race-cpajob（在 Linux ARM64 runner 上执行go test -race -count=1 -timeout=15m ./...）。同样地，主仓库的 race 测试也有独立的race-testsjob（macOS ARM64 runner）。因此发版工具的 Python 测试单独运行：

python3 -m unittest discover -s scripts -p 'test_release_*.py'

浏览器 E2E 则只在手动发版验收及其模拟模式中运行（见下文）。

维护者发版验收：make release 与 make release-simulate

这是 CONTRIBUTING.md 中最具项目特色的部分——GPT-Load 把"发版"做成了一条可本地重演的验收流水线，而非仅靠远程 CI。

make release：PR 合并后的交互式发版入口

本地make release（对应 Makefile 的python3 -m scripts.release）用于 PR 合并后的发版。从 scripts/release.py 的源码可以还原其完整流程：

1. 从最新origin/main建立隔离工作区（不切换、不改写调用者工作区与本地main）；
2. 前置校验：检查git、gh、docker、go、corepack、python3、jq是否齐备；校验当前仓库确为tbphp/gpt-load；要求本地存在.env；并要求本地发版工具与远端 main 一致（对比scripts/release*.py文件，若本地落后则停止并提示先更新工具）；
3. 上一版本核验：确认上一发布 tag 指向预期 commit 且为公开 Release，且该 tag 有成功完成的 Release 记录——防止在损坏的历史上继续发版；
4. 构建候选原生程序与候选镜像（go build注入v2.0.0-preflight.<sha>版本号；docker build生成临时镜像，结束时清理）；
5. 三数据库新装与旧版升级验收：覆盖三种数据库驱动、从上一版本升级、Compose、流式请求，以及新旧管理界面的主要页面（浏览器验收由 scripts/release_browser.py 驱动，报告与截图保存到~/.cache/gpt-load/release-acceptance/<sha>/browser/html/index.html）；
6. mini 真实数据验收：gpt-load/mini隔离副本 + 一次真实上游请求；
7. 全部通过后才建议 tag：展示候选 commit 与上一 tag 之间的提交摘要，输入yes确认后推送；现有 Release workflow 随 tag 按原配置运行，手动工具既不等待其完成，也不重复执行make check。

关键安全细节：真实数据仅复制到带归属标记的临时 PostgreSQL 库；本机报告目录以0o700权限创建，报告中的日志与浏览器 trace不得上传。失败时先核对报告与远端 tag 状态，不要强制改写 tag。

make release-simulate：PR 合并前的彩排

make release-simulate（python3 -m scripts.release --simulate）在 PR 合并前运行，从已提交且干净的当前分支出发：

• 以当前HEAD执行同一套验收（同样包含 mini 真实上游请求），保存报告与截图；
• 结束时不进入 tag 输入或推送；
• 由于未提交的改动不会进入隔离工作区，模拟模式会直接拒绝脏工作区——这相当于强制要求"先提交、再彩排"。

Playwright 依赖与测试独立放在 scripts/release-e2e/（含playwright.config.ts与release-pages.spec.ts），不改变常规前端安装与 CI/Release 门禁。

从 scripts/release.py 的实现可以看到，--simulate与正式模式共用run_release(repository, simulate=...)，唯一区别是模拟模式在全部验收通过后直接返回、不进入prompt_for_tag/publish_tag。因此模拟通过的结果与正式发版的前置验收等价，可以放心在 PR 合并前用它验证发布路径。

提交 PR：聚焦、可复现、可验证

CONTRIBUTING.md 给出的 PR 提交五步，每一环都有仓库依据：

1. 从main切出分支，保持改动聚焦，不夹带无关重构或格式化——这是git diff --check与 CI 之外靠自觉维护的代码卫生；
2. 修复缺陷或改变行为时，优先补一个能复现问题的测试——"先红后绿"是验收门禁make test能信任的前提；
3. 提交前跑一次make check；无法运行时在 PR 里说明原因和未验证范围。这一点在 .github/pull_request_template.md 的自查清单中被固化为"我已运行make check，或在说明中写明无法运行的原因和未验证范围"；
4. 按 PR 模板填写，如实勾选自查清单：模板包含关联 Issue（Closes #...）、变更内容（Bug fix / New feature / Other changes）与五项 checklist（make check、范围聚焦、文档更新、敏感信息确认、兼容性/数据迁移说明）；
5. 涉及用户可见能力时，三份 README 必须同步更新：README.md、README_CN.md、README_JP.md。这是与后端 internal/platform/i18n 三语言体系（zh-CN / en-US / ja-JP）相匹配的文档要求。

Commit 规范：type(scope) 前缀

提交信息格式为<type>(scope): <summary>，scope可选。常用 type：feat、fix、refactor、docs、test、chore。CONTRIBUTING.md 给出的两个示例直接对应仓库的真实演进方向：

fix(subscription): 避免临时刷新失败锁死凭据 feat(gateway): 支持 OpenAI Embeddings API

从仓库目录看，internal/subscription/（订阅账号管理）与internal/gateway/（网关转发核心）确实是两个高频变更区域，subscription、gateway正是这类提交最自然的 scope 取值。

代码风格：editorconfig、gofmt 与 i18n 文案

基础格式约定

CONTRIBUTING.md 的格式要求以 .editorconfig 为权威配置：

• UTF-8、LF 换行、文件末尾保留换行（insert_final_newline = true）；
• .go与Makefile用 Tab，其余用 2 空格（.editorconfig中[*.go]与[Makefile]段显式indent_style = tab）；
• Markdown 文件关闭行尾空白修剪（trim_trailing_whitespace = false），避免破坏文档内的行尾空格语义。

Go 侧约定

• gofmt 格式：make check的第一步与 CI 的 "Check Go formatting" job 都用gofmt -l .输出为空来强制；
• import 分组顺序：stdlib → 第三方 →gpt-load/internal/...。这一约定在仓库源码中普遍可见，例如 internal/platform/i18n/i18n.go 的 import 区即按 stdlib（encoding/json、fmt…）、第三方（github.com/nicksnyder/go-i18n/v2/i18n、golang.org/x/text/language）、内部包（gpt-load/internal/platform/i18n/locales）排列；
• 标识符用英文，注释优先使用简体中文：源码中大量//中文注释即为佐证。

用户可见文案必须走 i18n

"对外错误消息走internal/platform/i18n，不要在 handler 里硬编码用户可见文案"——这是与 GPT-Load 多语言定位直接绑定的硬性约束。internal/platform/i18n 的实现要点：

• 基于github.com/nicksnyder/go-i18n/v2/i18n，支持zh-CN、en-US、ja-JP三语言（i18n.go 从locales包加载MessagesZhCN/MessagesEnUS/MessagesJaJP）；
• 按Accept-Language头协商语言，默认回退zh-CN，并对头部长度与条目数做了防御性限制；
• 翻译失败时T()返回消息 ID 本身，避免静默丢失文案。

因此在 handler 中新增用户可见错误时，正确做法是：在internal/platform/i18n/locales的zh-CN.go/en-US.go/ja-JP.go中为三种语言各加一条消息，再通过i18n.T(localizer, "msgID")引用，而不是硬编码字符串。

依赖与安全：两条不可逾越的红线

CONTRIBUTING.md 的最后一部分是依赖治理与凭据安全：

• 新增依赖需要先在 issue 或 PR 中说明理由，并确认许可证兼容。仓库的做法可参考：THIRD_PARTY_NOTICES.md汇总第三方声明，LICENSES/ 下存放 Apache-2.0、Inno-Setup、MIT、MPL-2.0 等许可证文本；Release 流程还会生成 CycloneDX SBOM（见 .github/workflows/release.yml 的package-metadatajob）。
• 提交、日志、测试数据和截图中不得包含AUTH_KEY、ENCRYPTION_KEY、上游密钥或任何真实凭据。这与 SECURITY.md 的 "Channel credential exposure boundary" 相互呼应——凭据及派生片段不得出现在数据面响应头/体、请求日志与请求日志管理 API 中。发版工具同样贯彻了这一点：报告目录权限0o700、日志文件0o600，且明确"不得上传其中的日志或浏览器 trace"。

参与即同意行为准则

按 CONTRIBUTING.md 的约定，参与本项目即表示同意遵守 行为准则，这也是所有贡献类仓库的通行前提。

小结：贡献者的最小行动清单

把 CONTRIBUTING.md 压缩成一张可执行的检查表：

1. 漏洞走私有报告、使用问题先查文档/社区、大改动先开 issue；
2. 功能开发一律基于main（2.x 线），1.x 只接受安全与严重缺陷修复；
3. 本地环境：Go（版本见 go.mod）+ Node/pnpm（corepack，版本见 web/package.json）；
4. 日常循环用make dev，提交前必须make check；动了third_party/cpaembedded还要补跑该 module 的go mod tidy -diff与go vet；
5. 维护者发版：PR 合并后make release，合并前用make release-simulate彩排（须干净已提交分支）；
6. PR 按模板填写并如实勾选 checklist，改动用户可见能力时三份 README 同步更新；
7. Commit 用<type>(scope): <summary>格式；
8. 代码风格以 .editorconfig 为准，用户可见文案必须走internal/platform/i18n；
9. 新增依赖先说明理由与许可证；任何提交/日志/截图都不得出现真实凭据。

遵循这套流程，你的贡献就能与 GPT-Load 自身的 CI（.github/workflows/ci.yml）和 Release 流水线（.github/workflows/release.yml）无缝衔接——这也是该项目把"贡献指南"落到可执行层面的真正价值所在。

• API网关
• 后端
• 负载均衡