企业官网建设流程全解析

• 网络
• 网络安全
• 零信任
• 后端

导读：本文以 Firezone 官方贡献指南（docs/CONTRIBUTING.md）为骨架，完整还原其从零搭建本地开发集群、初始化数据库、生成自签名证书、配置版本管理与 pre-commit、到提交 PR 的全流程，并辅以仓库源码（docker-compose.yml、elixir/mix.exs、.tool-versions 等）进行底层印证。读完你将掌握 Firezone 的完整开发工作流：如何用 Docker 一键拉起 portal/gateway/client/relay 四类组件、如何通过mix命令引导 Ecto 数据库、如何满足仓库要求的提交签名与静态检查门槛，以及如何写出能被审阅者顺利合并的 PR。

一、贡献总览与总体原则

Firezone 是一个由 Elixir（Portal / API）与 Rust（Gateway、Relay、客户端）共同构成的多语言代码库，欢迎任何形式的贡献。在动手之前，官方指南要求贡献者遵守以下总体原则（Overview 章节）：

1. 遵守行为准则：见 docs/CODE_OF_CONDUCT.md。
2. Rust 代码遵循编码规范：见 rust/CODING_GUIDELINES.md。
3. 尽可能测试你的代码，并包含单元测试。
4. 由你本人论证改动的合理性：说明为什么这是一个好改动，是贡献者的责任。
5. 安全问题走负责任披露：任何安全漏洞不要通过公开 Issue 上报，请遵循 docs/SECURITY.md 中描述的流程。

AI 使用政策

仓库对使用 AI/LLM 辅助编码持欢迎态度，但对与维护者的沟通内容有严格要求：不得使用 AI 生成评论，评论必须由真人撰写；经判断由 AI 撰写的外部评论、Issue 或 PR 可能会被直接关闭且不予通知。换言之，AI 可以帮你写代码，但沟通层仍需真人把关。

二、Quick Start：用 Docker 快速拉起本地集群

Quick Start 的目标是让新手在几分钟内得到一个完整的本地 Firezone 运行环境，从而直观感受 Portal、Gateway、Client、Relay 各组件如何协作。验证通过后再按组件深入开发。

2.1 Docker 环境准备

官方推荐使用 Docker Desktop（即使是 Linux 开发者也推荐，Firezone 核心开发者即使用它），因为它自带正确版本的compose。如果使用 Linux 上的 Docker Engine，则需额外安装compose 插件（v2），否则无法识别docker compose子命令。可通过以下命令确认版本：

> docker compose version Docker Compose version v2.27.0

2.2 引导数据库（Bootstrapping the DB）

启动本地集群的完整步骤如下：

docker compose build docker compose run --rm elixir /bin/sh -c "mix ecto.create && mix ecto.migrate && mix ecto.seed" # 进入下一步前，请从 seed 输出中复制 Firezone 账号 UUID # 输出示例： Created accounts: c89bcc8c-9392-4dae-a40d-888aef6d28e0: Firezone Account docker compose up -d portal vault gateway client relay-1 relay-2

完成上述步骤后，访问http://localhost:8080/<account-uuid-here>，使用以下凭据登录：

Email: firezone@localhost.local Password: Firezone1234

源码印证：docker compose run --rm elixir对应 docker-compose.yml 中名为elixir的服务容器——它专门用于在无需宿主机安装 Elixir/Erlang 的前提下运行mix任务，其环境变量MIX_ENV: "prod"确保 seed 使用正确的密钥生成有效令牌，POOL_MEMBER_FIREZONE_ID则控制mix ecto.seed中账号级 ICE-less 特性开关（FEATURE_ICELESS_ENABLED，默认关闭）。而ecto.seed别名在 elixir/mix.exs 中被定义为ecto.create + ecto.migrate + run priv/repo/seeds.exs的组合。

2.3 启动后的集群拓扑

启动后你将得到（均由根目录 docker-compose.yml 编排）：

• portal：Elixir/Phoenix 控制平面，监听8080（Web）与8081（API），并通过portal-router把流量路由到模拟公网网段203.0.113.0/24；
• gateway：一个已连接 portal 的网关，使用 TUN 设备（/dev/net/tun）转发流量，并开启net.ipv4.ip_forward系统参数；
• client：一个已连接 portal 的无头 Linux 客户端；
• relay-1 / relay-2：两个 TURN 中继，公网地址分别为203.0.113.101与203.0.113.102，由relay-1-router/relay-2-router做 UDP 端口转发（3478及49152-65535）；
• resource：一台位于与网关共享的独立网络中的资源主机，IP 为10.20.0.100。

此外，docker-compose.yml 中的network-config服务会在两个 relay 健康后为 relay-internal 桥接 veth 挂载xdp_passeBPF 程序，用于解决 XDP_TX 回传与 checksum 校验问题——这是研究 relay 数据面时值得注意的细节。

2.4 验证一切正常

# 测试客户端能否 ping 通资源主机 docker compose exec -it client ping 10.20.0.100 # 也可以直接进入客户端容器交互 docker compose exec -it client /bin/sh

如果ping成功，说明 Portal→Gateway→Client→Relay→Resource 整条链路已打通，本地环境就绪。

三、生成自签名证书（本地 TLS 调试）

本地开发强烈建议生成并信任一张自签名证书，以避免在浏览器与 API 之间反复排查 TLS 问题。macOS 上可执行：

cd elixir # 为 localhost 生成自签名证书 # 注：使用 openssl 而非 `mix phx.gen.cert`，是因为 Phoenix 存在生成缺失 :NULL 参数 # 无效证书的 bug（详见 phoenixframework/phoenix issue #6319） openssl req -x509 -newkey rsa:2048 -nodes -sha256 -days 365 \ -keyout priv/cert/selfsigned-key.pem \ -out priv/cert/selfsigned.pem \ -subj "/O=Firezone Development/CN=localhost" \ -addext "subjectAltName=DNS:localhost,DNS:host.docker.internal,IP:127.0.0.1" \ -addext "basicConstraints=critical,CA:FALSE" \ -addext "keyUsage=critical,digitalSignature,keyEncipherment" \ -addext "extendedKeyUsage=critical,serverAuth" # 将证书加入系统信任库 sudo security add-trusted-cert -d -p ssl -k /Library/Keychains/System.keychain priv/cert/selfsigned.pem

证书生成后会被加入系统信任库，方便浏览器直接访问。Firefox 用户注意：Firefox 默认使用自己的证书库而忽略 macOS 系统钥匙串，可通过两种方式信任该证书：

1. 打开about:config，将security.enterprise_roots.enabled设为true；
2. 直接导入证书：Settings → Privacy & Security → Certificates → View Certificates → Authorities → Importpriv/cert/selfsigned.pem。

提示：subjectAltName中同时包含host.docker.internal，正是为了让容器内组件（如通过host.docker.internal访问宿主机服务的 Gateway）也能校验通过；证书输出目录为elixir/priv/cert/，在仓库中已被.gitignore排除，不会误提交。

四、开发者环境搭建

4.1 Git 提交签名（强制要求）

Firezone 要求仓库内所有提交都必须签名。如果你需要配置git的提交签名校验，请参考 Git 官方关于 Commit Signature Verification 的文档完成 GPG/SSH 签名配置，之后再执行提交。

4.2 工具链版本管理：.tool-versions+ mise/asdf

大多数工具与 SDK 的版本由各目录下的.tool-versions文件管理（Elixir 工具见 elixir/.tool-versions，Rust 工具见 rust/.tool-versions，根目录见 .tool-versions）。任何兼容.tool-versions的版本管理器（推荐 Mise 或 asdf）都可以安装这些工具。例如 fresh asdf 环境需要先安装对应插件：

asdf plugin add nodejs && asdf install nodejs

以仓库当前版本为例（elixir/.tool-versions）：

nodejs 22.20.0 pnpm 10.33.0 elixir 1.20.3-otp-29 erlang 29.0.5

而根目录 .tool-versions 则固定了静态分析相关工具：python 3.11.14、shfmt 3.9.0、shellcheck 0.9.0、prettier 3.6.2、bats 1.13.0、actionlint 1.7.9、uv 0.12.5。

这些工具用于 pre-commit 阶段的静态检查，以及任何本地（非 Docker）的开发与测试。

4.3 Pre-commit

仓库使用pre-commit在提交前拦截静态分析问题：

• 安装 Mise 自动安装 pre-commit 及其它所需工具）；
• 安装仓库级检查钩子：

pre-commit install --config .github/pre-commit-config.yaml

源码印证：根目录 mise.toml 中定义了mise run lint（等价于pre-commit run --all-files --config .github/pre-commit-config.yaml）、lint-staged（仅检查暂存文件）以及format（对所有 prettier 管理文件执行格式化）。mise 的minimum_release_age = "7d"设置还会拒绝安装发布不足 7 天的工具版本，以缓解恶意发布供应链攻击窗口。

4.4 按组件选择开发入口

• Elixir（Web 应用 / API）：完整指南见 elixir/README.md。从elixir/目录执行mise install（或asdf install）安装 elixir/.tool-versions 中声明的工具；随后docker compose up -d postgres启动数据库，在elixir/下依次运行mix deps.get、mix setup、mix ecto.seed、iex -S mix启动 Portal。注意 elixir/mix.exs 的 aliases 中把ecto.seed绑定为create + migrate + seed，把test绑定为ecto.create --quiet → ecto.migrate → openapi.generate → test，即跑测试前会自动先建库、迁移并重新生成 OpenAPI 规范。
• Rust（Gateway / Relay / 客户端库）：完整指南见 rust/README.md。仓库针对最新的 stable Rust，并通过 rust/rust-toolchain.toml 固定版本；若用rustup会自动处理，否则需自行安装最新 stable。Ubuntu 下还需要安装 GTK、WebKitGTK、OpenSSL 等系统依赖，以及 relay 所需的 eBPF 工具链（nightly-2025-05-30+rust-src+bpf-linker）。
• Shell 脚本：见 scripts/README.md。本地开发需安装shfmt与shellcheck，提交前执行shfmt -i 4 **/*.sh与shellcheck --severity=warning **/*.sh；脚本规范建议 dev/test 脚本使用#!/usr/bin/env bash加set -euox pipefail，Docker 等最小环境则用#!/bin/sh加set -eu。Elixir 死代码检查可用mise run //:elixir:dead-code --check。

Rust 开发与 Docker 结合

根目录的docker-compose.yml每次测试改动都要求重建镜像。仓库提供了覆盖方案——使用 rust/docker-compose-dev.yml 叠加：

docker compose -f docker-compose.yml -f rust/docker-compose-dev.yml <command>

这样会直接使用本地编译产物（位于rust/target/x86_64-unknown-musl/debug）。也可以设置环境变量COMPOSE_FILE避免每次手动指定：

export COMPOSE_FILE="docker-compose.yml:rust/docker-compose-dev.yml"

五、报告 Bug

任何 Bug 报告都受欢迎。报告前请先在 issues 追踪器中搜索（包括已关闭的 issue）。确认不存在后，新建 issue 并包含以下要素：

• 问题描述
• 预期行为
• 复现步骤
• 预估影响：High / Medium / Low
• Firezone 版本
• 平台架构（amd64、aarch64 等）
• Linux 发行版
• Linux 内核版本

六、提交 Pull Request

6.1 运行测试

测试是你作为贡献者的责任：代码有 Bug 可能被直接拒绝。同时建议查看代码覆盖率报告，确认新代码已被测试覆盖。

单元测试：在项目根目录（elixir/）执行：

mix test

如需行级覆盖率，运行mix coveralls.html生成 HTML 报告（输出到cover/）。仓库在 elixir/mix.exs 中通过test_coverage: [tool: ExCoveralls]集成了 ExCoveralls，并配置了test_ignore_filters: [~r"^test/fixtures/"]。

端到端测试：更全面的 e2e 测试在 CI 流水线中执行；出于安全原因，e2e 不会随你的 PR 自动触发，必须由审阅者手动触发。

6.2 使用详细的提交信息（Conventional Commits）

详细的提交信息对发布工程流程帮助极大。请遵循Conventional Commits规范撰写提交信息，示例如下：

read -r -d '' COMMIT_MSG << EOM Updating the foobar widget to support additional widths Additional widths are needed to various device screen sizes. Closes #72 EOM git commit -m "$COMMIT_MSG"

6.3 确保静态分析通过

静态检查会在git commit时自动执行；若未触发，可手动运行：

mise run lint

七、日志与敏感信息

仓库对日志级别与敏感信息有明确约定：IP 地址和域名只允许在 DEBUG 级别记录，不允许出现在 INFO 或其他生产构建默认开启的级别中。这意味着贡献者在新增日志时，应避免在默认日志级别下泄露端点信息，相关日志过滤逻辑可参考 elixir/lib/portal/logger_filters.ex。

八、寻求帮助

卡住时不要犹豫，可以在 Firezone 社区论坛提问。此外，docs/AGENT.md 与 rust/AGENT.md 为 AI Agent 和开发者提供了仓库结构与编码约定的快速索引，可作为深入开发的补充资料。

• 网络
• 网络安全
• 零信任
• 后端