网络网络安全零信任后端【免费下载链接】firezoneBlazing-fast remote access项目地址https://gitcode.com/gh_mirrors/fi/firezone点击查看免费下载导读本文以 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 是一个由 ElixirPortal / API与 RustGateway、Relay、客户端共同构成的多语言代码库欢迎任何形式的贡献。在动手之前官方指南要求贡献者遵守以下总体原则Overview 章节遵守行为准则见 docs/CODE_OF_CONDUCT.md。Rust 代码遵循编码规范见 rust/CODING_GUIDELINES.md。尽可能测试你的代码并包含单元测试。由你本人论证改动的合理性说明为什么这是一个好改动是贡献者的责任。安全问题走负责任披露任何安全漏洞不要通过公开 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.02.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: firezonelocalhost.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 编排portalElixir/Phoenix 控制平面监听8080Web与8081API并通过portal-router把流量路由到模拟公网网段203.0.113.0/24gateway一个已连接 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-65535resource一台位于与网关共享的独立网络中的资源主机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 /OFirezone Development/CNlocalhost \ -addext subjectAltNameDNS:localhost,DNS:host.docker.internal,IP:127.0.0.1 \ -addext basicConstraintscritical,CA:FALSE \ -addext keyUsagecritical,digitalSignature,keyEncipherment \ -addext extendedKeyUsagecritical,serverAuth # 将证书加入系统信任库 sudo security add-trusted-cert -d -p ssl -k /Library/Keychains/System.keychain priv/cert/selfsigned.pem证书生成后会被加入系统信任库方便浏览器直接访问。Firefox 用户注意Firefox 默认使用自己的证书库而忽略 macOS 系统钥匙串可通过两种方式信任该证书打开about:config将security.enterprise_roots.enabled设为true直接导入证书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-versionsRust 工具见 rust/.tool-versions根目录见 .tool-versions。任何兼容.tool-versions的版本管理器推荐 Mise 或 asdf都可以安装这些工具。例如 fresh asdf 环境需要先安装对应插件asdf plugin add nodejs asdf install nodejs以仓库当前版本为例elixir/.tool-versionsnodejs 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 按组件选择开发入口ElixirWeb 应用 / 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 规范。RustGateway / Relay / 客户端库完整指南见 rust/README.md。仓库针对最新的 stable Rust并通过 rust/rust-toolchain.toml 固定版本若用rustup会自动处理否则需自行安装最新 stable。Ubuntu 下还需要安装 GTK、WebKitGTK、OpenSSL 等系统依赖以及 relay 所需的 eBPF 工具链nightly-2025-05-30rust-srcbpf-linker。Shell 脚本见 scripts/README.md。本地开发需安装shfmt与shellcheck提交前执行shfmt -i 4 **/*.sh与shellcheck --severitywarning **/*.sh脚本规范建议 dev/test 脚本使用#!/usr/bin/env bash加set -euox pipefailDocker 等最小环境则用#!/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_FILEdocker-compose.yml:rust/docker-compose-dev.yml五、报告 Bug任何 Bug 报告都受欢迎。报告前请先在 issues 追踪器中搜索包括已关闭的 issue。确认不存在后新建 issue 并包含以下要素问题描述预期行为复现步骤预估影响High / Medium / LowFirezone 版本平台架构amd64、aarch64 等Linux 发行版Linux 内核版本六、提交 Pull Request6.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_MSG6.3 确保静态分析通过静态检查会在git commit时自动执行若未触发可手动运行mise run lint七、日志与敏感信息仓库对日志级别与敏感信息有明确约定IP 地址和域名只允许在 DEBUG 级别记录不允许出现在 INFO 或其他生产构建默认开启的级别中。这意味着贡献者在新增日志时应避免在默认日志级别下泄露端点信息相关日志过滤逻辑可参考 elixir/lib/portal/logger_filters.ex。八、寻求帮助卡住时不要犹豫可以在 Firezone 社区论坛提问。此外docs/AGENT.md 与 rust/AGENT.md 为 AI Agent 和开发者提供了仓库结构与编码约定的快速索引可作为深入开发的补充资料。赞分享网络网络安全零信任后端【免费下载链接】firezoneBlazing-fast remote access项目地址https://gitcode.com/gh_mirrors/fi/firezone点击查看免费下载相关推荐Diem 项目贡献指南从开发环境搭建到 Pull Request 全流程实战Diem 项目贡献指南从开发环境搭建到 Pull Request 全流程实战 本篇指南以 Diem 开源仓库官方贡献文档为主体完整覆盖贡献者许可协议CLA区块链金融科技Hydra 项目贡献指南从开发环境搭建到 Pull Request 全流程实战Hydra 项目贡献指南从开发环境搭建到 Pull Request 全流程实战 导读 Hydra 是一个用于优雅配置复杂应用的 Python 框架A fr开发工具后端CLITaro 贡献者指南从环境搭建到 Pull Request 全流程实战Taro 贡献者指南从环境搭建到 Pull Request 全流程实战 TaroNervJS/taro是支持 React/Vue/Nerv 等框架、可同时前端小程序跨平台移动开发上一篇WezTerm Lua 配置中的 JSON 序列化wezterm.serde.json_encode 用法与底层实现解析下一篇Azure Cosmos DB NoSQL Modeling Session创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考