开发与贡献

基本要求复制链接

• 较大的改动先开 issue。
• 新依赖、进程或部署形态、节点通道协议、NodeConfig IR 语义、安全基线的改动，先在 issue 中确定设计。
• 安全漏洞按 SECURITY.md 私下报告，不开公开 issue。
• 违反下表原则的 PR 不合入。

开发环境复制链接

端到端测试另需：curl、jq、goreleaser v2、syft、cosign v3.1.3，与本仓库同级的 edgeweir-node 检出（或 EDGEWEIR_NODE_CONTEXT），其中 out/openresty 有 Docker 架构对应的 edgeweir-openresty 包（make openresty-packages；缺少时 scripts/e2e.sh 先构建，需要 Docker Buildx），G3 之前的节点镜像 edgeweir-node:pre-g3（缺少时 scripts/e2e-g3.mjs 从 edgeweir-node 提交 6da3403 构建），以及对 deb.debian.org、openresty.org 的网络访问（首次构建节点镜像或 edgeweir-openresty 包时另需 github.com、download.gnome.org、vault.almalinux.org）。Playwright 步骤需要 Chromium：

pnpm --filter @edgeweir/console exec playwright install chromium

本地运行复制链接

1. 安装依赖。

   复制

   pnpm install

2. 启动本地 PostgreSQL 18。监听 127.0.0.1:5432（DEV_POSTGRES_PORT 可改），用户、密码、数据库均为 edgeweir。

   复制

   docker compose -f compose.dev.yml up -d

3. 创建 .env，把 openssl rand 的输出原样写入 EDGEWEIR_MASTER_KEY。.env.example 中的 DATABASE_URL 与 compose.dev.yml 一致。

   复制

   cp .env.example .env
   openssl rand -base64 32

4. 启动控制台。

   复制

   pnpm dev

   单个进程：:3000 提供 UI 与 API（前端走 Vite HMR），:8443 提供节点通道。服务端改动重启整个进程。初始化完成前，启动日志打印 setup token（setupToken 字段）。

5. 验证。

   复制

   curl -s http://localhost:3000/healthz

   预期输出 {"status":"ok","version":"dev"}。打开 http://localhost:3000/setup，输入 setup token 完成初始化向导。

命令复制链接

CI 在 PR 与 master 推送时运行：pnpm lint、pnpm proto:gen 后 packages/proto 无差异、pnpm typecheck、pnpm test、pnpm build、helpers/certd 的 go vet 与 go test -race、镜像构建、端到端测试。

测试复制链接

单个 Vitest 文件在 apps/console 下运行：

pnpm exec vitest run test/server/docs.test.ts

以下约定由测试强制执行：

新增的 API 过程都要有 Vitest 用例。

端到端测试复制链接

1. 构建并启动测试环境（postgres、console、node、测试源站与测试客户端）。

   复制

   docker compose -f compose.e2e.yml up -d --build

2. 运行测试。--up 先启动环境；--down 结束后删除环境与卷；--skip-ui 跳过 Playwright。

   复制

   pnpm e2e

3. 验证：输出以 E2E OK 结束。

并行运行第二套环境所需的变量（COMPOSE_PROJECT_NAME、E2E_CONSOLE_PORT、E2E_NODE_PORT、E2E_TAG、E2E_SUBNET、E2E_ISOLATED_SUBNET、E2E_INSTALL_IMAGE、EDGEWEIR_NODE_CONTEXT）见 README 端到端测试。

提交规范复制链接

使用 Conventional Commits。

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

<body>

<footer>

scope：console、web、api、db、contract、compiler、proto、node-channel、certd、deploy、e2e、doc。跨多个模块时省略 scope。

示例：

feat(deploy): add deploy.sh to install and upgrade 宝塔 / aaPanel compose deployments
fix(certd): renew without ARI replaces when the CA rejects the new order
feat(console)!: drop the public landing page from the open core

代码约定复制链接

界面规则复制链接

国际化复制链接

• 所有 UI 字符串经 Paraglide 消息函数输出。消息文件为 apps/console/messages/zh-CN.json（默认语言）与 apps/console/messages/en.json。
• key 用 snake_case，以页面或功能开头，如 nav_sites、cert_brotli_unavailable。
• 两种语言同时增改：key 集合一致，占位符一致，值不为空。
• 英文中的数量用 inlang message format 的复数变体（local countPlural = count: plural，每个复数类别一条 match，各变体占位符一致）；zh-CN 保持普通字符串。
• src/web/routes 与 src/web/components 中不写中文字面量，也不写英文 UI 文案，包括 aria-*、title、alt、placeholder。
• 服务端不拼接面向用户的句子：API 返回错误码，UI 按当前语言翻译；未知错误码回退到服务端的英文 message。

错误码复制链接

1. 在 packages/contract/src/errors.ts 的 errorDefs 中新增错误码，写明 HTTP 状态与 params。
2. 服务端调用 fail(CODE, message, data)（apps/console/src/server/lib/errors.ts）：message 是英文后备文本，data 提供 params 中的字段。
3. 在两个消息文件中新增对应消息，占位符与 params 一致。

API 与服务端约定复制链接

proto 变更复制链接

proto/ 是控制台与 edgeweir-node 之间唯一的契约。

1. 修改 proto/ 下的 .proto 文件。edgeweir.node.v1 包内只做向后兼容的新增；破坏性变更新建 v2 包。NodeConfig 遵守规范化约束：不用 map 字段，字段按字段号升序声明。

2. 运行 lint。

   复制

   pnpm proto:lint

3. 与上一个 proto tag 比较，确认没有破坏性变更。

   复制

   pnpm exec buf breaking proto --against '.git#tag=proto/vX.Y.Z,subdir=proto'

4. 生成 TypeScript，把 proto/ 改动与 packages/proto 的生成代码放在同一个提交里。CI 检查生成代码与 proto/ 一致。

   复制

   pnpm proto:gen

5. 合入 master 后，维护者打 tag proto/vX.Y.Z：新增字段或 RPC 升 minor，只改注释升 patch。

6. 在 edgeweir-node 中把 Makefile 的 PROTO_TAG 改为新 tag，重新生成 Go 代码并适配，提交 internal/gen/。

   复制

   make proto

7. 发布顺序：先升级控制台，再升级节点。控制台必须兼容上一个 proto 版本的节点。

数据库 schema 变更复制链接

1. 修改 packages/db/src/schema。

2. 生成迁移。

   复制

   pnpm db:generate

3. 把 packages/db/migrations 中新增的 SQL 文件与 meta/ 快照和 schema 改动放在同一个提交里。

4. 在 ARCHITECTURE.md 的数据模型一节列出新迁移文件名与新表名。

5. 验证。

   复制

   pnpm test

控制台启动时执行数据库迁移。

环境变量复制链接

1. 在 apps/console/src/server/lib/env.ts 的 schema 中声明变量（zod 校验与默认值）。

2. 在 .env.example 中加入变量，注释写明用途与默认值。compose 文件插值的变量同样要出现在 .env.example。

3. 在环境变量参考页的中英文版本中加入变量说明。

4. 验证。

   复制

   pnpm test

运营配置优先放在 系统设置，环境变量只保留初始化之前或基础设施层面需要的值。同一配置同时存在系统设置与环境变量时，生效顺序为：系统设置中保存的值、环境变量、默认值。

更新固定的镜像与 Actions复制链接

第三方输入按不可变引用固定，pnpm test 拒绝未固定的写法；edgeweir-node 用 make pin-check 做同样的检查。本仓库与 edgeweir-node 构建的镜像按 tag 引用。

1. 查镜像 digest：输出中的 Digest 是多架构 index digest，不用单一平台的 digest。

   复制

   docker buildx imagetools inspect <镜像>:<tag>

2. 查 Action 版本对应的提交：附注 tag 取带 ^{} 那一行的 SHA。

   复制

   git ls-remote --tags https://github.com/<owner>/<action>

3. tag 与 digest（或 SHA 与版本注释）一起修改。

4. 修改 compose.baota.yml 或 compose.baota-host.yml 后，把全文同步进 deploy.sh 的内嵌模板；deploy.sh 的 PG_IMAGE 与 compose.baota.yml 的 PostgreSQL 镜像保持一致。

5. 验证。

   复制

   pnpm test
   bash deploy.sh template bundled | diff - compose.baota.yml
   bash deploy.sh template host | diff - compose.baota-host.yml

基础镜像更新后，在 Actions 中手动运行 Release，重建 master 最新提交。

发布复制链接

版本固定、升级与回滚见版本、升级与回滚；发布物的签名与校验见 SECURITY.md。

文档复制链接

• 发布的文档是纯 GitHub Markdown：name.md（简体中文，默认）与 name.en.md（英文，章节与 name.md 相同）。
• 文档站点位于 doc/（Fumadocs，Next.js 静态导出），是独立的 pnpm workspace（doc/pnpm-workspace.yaml、doc/pnpm-lock.yaml）。.github/workflows/docs.yml 在 PR 中构建站点，在 master 推送后发布到 GitHub Pages：https://marvinli001.github.io/edgeweir/。
• doc/scripts/sync-content.mjs 保存页面表（SECTIONS）并转换 Markdown。新页面须加入页面表。

Pull Request 检查清单复制链接

• 一个 PR 一个主题；描述写明动机、改动内容与验证方式，关联 issue。
• pnpm lint、pnpm typecheck、pnpm test 通过；按命令表的时机运行 pnpm build、pnpm e2e。
• 提交符合提交规范。
• UI 文案 zh-CN 与 en 同时更新；新错误码有对应消息。
• schema 改动附带迁移 SQL、快照与 ARCHITECTURE.md 数据模型更新。
• 新环境变量写入 env.ts、.env.example 与环境变量参考页。
• 管理操作写审计日志。
• UI 改动附截图。
• 行为变化同步更新中英文文档（README、部署文档）。
• 没有跳过、删除或弱化测试。

许可证复制链接

Edgeweir 以 AGPL-3.0-only 发布。提交贡献即表示同意以 AGPL-3.0-only 授权该贡献，并确认有权这样授权。

开源核心允许合规商用；开源版面向单一运营者，多租户（组织、成员、角色与隔离）、对外客户门户、套餐计费、财务与分销属于独立商业运营产品（LICENSING.md）。向核心贡献不自动授予项目方闭源再许可的权利；双许可或插件链接例外须另行核实代码权利与贡献授权。