进阶 docs.pangolin.net 2026-11-21 15:06:37 · 2 阅读

第22章 贡献指南

第22章 Contribution Guide

贡献指南:为参与 Pangolin 开发配置本地开发环境

本指南介绍如何搭建本地开发环境,以便为 Pangolin 做出贡献。我们推荐使用 Docker Compose,以在不同环境中获得最一致的开发体验。

前置要求

- Node 24 - NPM 11 或类似版本 - Go 1.25 - Git - Docker 与 Docker Compose - Python(用于 NPM 构建) - Make - G++

如需管理多个 Go 版本,可以使用 gvm;如需管理多个 NodeJS 版本,可以使用 nvm。

配置你的仓库

以下以 Pangolin 仓库为例。

Fork 并克隆

将仓库 Fork 到你自己的 GitHub 账号,并克隆到本地:

``` git clone https://github.com/YOUR_USERNAME/pangolin.git cd pangolin/ ```

添加 upstream 远程仓库

``` git remote add upstream https://github.com/fosrl/pangolin.git ```

创建功能分支

``` git checkout -b BRANCH_NAME dev ```

建议给分支起一个与你要开发的功能或修复相关的、有意义的名字。

好的命名示例:

- docs-docker - feature-new-system - fix-title-cards

不好的命名示例:

- bug - docs - feature - fix - patch

提交 Pull Request

发起 Pull Request 时,请以原仓库的 dev 分支为目标分支。

PR 的重要最佳实践

- 保持 PR 小而专注:每个 PR 只包含一个功能、修复或改进,便于审查和测试。 - 优先改进而非新增功能:如果你想提出全新功能,请先通过邮件或 Discord 联系我们,确认其符合路线图,并一起界定范围。 - 前端保持一致性: - 复用现有的样式、组件和模式。 - 弹窗使用 Credenza,表单校验使用 Zod。 - Tailwind 类尽量精简,优先使用组件默认样式。 - 先找已有的类似实现并照搬其模式,只有当抽取小型可复用组件确实能提升复用性时才这么做。 - 遵循既定模式:未经事先沟通,不要引入新的架构或抽象。 - 认证相关改动需格外谨慎: - Pangolin 是多租户的。用户权限控制应在组织层面(视具体控制项而定)或通过服务器管理面板全局处理。 - 所有 API 路由必须用正确的中间件保护,并在执行操作前校验用户权限及其对相关实体的访问权。 - 数据库改动: - SQLite 与 Postgres 的 schema 必须完全同步并保持向后兼容。 - 只使用两种数据库都支持的数据类型。 - 无需编写版本化迁移,维护者会在发布时处理。 - 附上可视化材料:适用时提供截图或短视频,加快审查速度。

数据库

Pangolin 支持两种数据库:SQLite 和 Postgres。可以通过提供的脚本切换:

在运行之前,请先阅读下文的本地开发配置。

``` npm run set:sqlite # 或 npm run set:pg ```

切换后,请使用对应数据库的脚本重新生成并应用 schema。SQLite 和 Postgres 的 schema 必须完全同步并保持向后兼容。

私有文件与目录

Pangolin 同时包含 AGPLv3 代码和部分基于 Fossorial Commercial License 授权的专有代码。专有文件带有许可声明头,通常存放在名称以 private 开头的目录中。

只要你的 PR 包含所需的 CLA,就可以在 PR 中修改专有文件。

- 前端:不含专有代码。 - 后端:存在专有代码,主要位于 server/private/ 下,子目录结构与 server/ 下的结构一一对应。

为保证 AGPLv3 部分完全合规,导入时需特别注意:

- AGPLv3 文件绝不能从 private 目录导入。TypeScript 中的别名 #private/ 指向专有代码,只能在其他私有文件内部使用。 - 如果必须向 AGPLv3 代码暴露专有行为,请使用动态导入模式:在 server/private 和 server 之间创建一个相对路径与专有文件对应的镜像文件,并确保导出 API 的函数签名完全一致。动态导入别名以 #dynamic 开头。 - 构建时,根据构建标志,#dynamic 导入会被解析为相应的实现(AGPLv3 或专有版本)。

构建标志决定你正在开发哪个发行版:oss、enterprise 或 saas。Enterprise 和 SaaS 包含专有代码;OSS 必须 100% 符合 AGPLv3,不包含专有代码。使用现有的 npm 脚本切换:

``` npm run set:oss # 或 npm run set:enterprise # 或 npm run set:saas ```

切换发行版会更新 TypeScript 路径别名,使 #dynamic 解析到正确的位置。构建标志也会在代码中用于按发行版启用或禁用功能。

经验法则是:尽量多写 AGPLv3 代码,只把核心的、发行版特定的功能放在专有层(Enterprise/SaaS)。

数据库 schema 永远不属于专有代码,所有发行版共用同一套 schema。

如有任何疑问,请发邮件或到 Discord 联系我们。

Pangolin 开发环境搭建

选择你偏好的开发方式。我们强烈推荐 Docker Compose,以在所有平台上获得最一致的体验。

本地开发

安装依赖

``` npm install ```

配置环境

确保根目录下有 config/ 目录,且其中包含 config.yml。关于该文件应包含的内容,可参考 Pangolin 配置文档或仓库中的 config.example.yml 示例。

你可能需要做一些调整才能在开发模式下运行,例如将 dashboard_url 设置为 http://localhost:3002。

设置环境

选择基于 oss/enterprise/saas 代码库构建:

``` npm run set:oss # 或 npm run set:enterprise # 或 npm run set:saas ```

然后选择数据库:

``` npm run set:sqlite # 或 npm run set:pg ```

生成数据库 schema

``` npm run db:generate npm run db:push ```

启动开发服务器

使用 Docker Compose 启动:

``` docker compose up --build ```

或者直接启动开发服务器:

``` npm run dev ```

Gerbil 注册

首次运行 Pangolin 时没有任何出口节点(exit node),也就是说数据库中尚未注册任何 Gerbil 出口节点,因此无法创建 Newt 站点。Gerbil 首次启动并向 Pangolin 请求配置时,会被注册为一个出口节点。

最简单的解决办法是在开发环境中运行 Gerbil 并让它完成注册。下载 Gerbil 二进制文件并用 localhost 运行:

``` ./gerbil \ --reachableAt=http://localhost:3004 \ --generateAndSaveKeyTo=/var/config/key \ --remoteConfig=http://localhost:3001/api/v1/ ```

或者手动向数据库插入一条占位的出口节点记录:

``` INSERT INTO "exitNodes" ( "name", "address", "endpoint", "publicKey", "listenPort", "reachableAt", "type" ) VALUES ( 'exit-node-1', '10.0.0.1/24', 'gerbil.pangolin.net', 'abc123', 1234, 'gerbil.pangolin.net', 'gerbil' ); ```

Windows 开发注意事项

使用 Docker Desktop + WSL2 的 Windows 用户:当项目文件存放在 Windows 文件系统上时,文件变更检测可能无法正常工作。

最佳性能与兼容性

项目文件的存放位置:

- 为获得最佳性能,请始终把项目放在 Docker 或默认 WSL2 实例的 Linux 文件系统内,例如 /home//pangolin。 - 如果使用其他 WSL 实例,请确保该发行版已启用 Docker Desktop 的 WSL 集成。

更多信息见下方参考链接部分。

从 Windows 访问 WSL2 文件:

- 可以通过 UNC 路径 \\wsl$\\home\\pangolin 在 Windows 中访问你的 WSL2 主目录(将 替换为实际的 WSL 发行版名,如 Ubuntu-22.04)。 - 该路径在 Windows 资源管理器、VS Code 及其他 Windows 应用中均可使用,可以拖放文件、创建快捷方式或映射网络驱动器。 - 注意:此 UNC 路径仅供 Windows 工具使用,不要用于 Docker 容器挂载。

如何在 Docker 容器中挂载 WSL2 文件:

- Docker 卷始终使用 WSL2 内部的绝对 Linux 路径,这是唯一获得 Docker 完全支持并推荐的方式。

正确的 Docker Compose 示例:

``` services: app: volumes: - /home//pangolin:/app ```

正确的 docker run 示例:

``` docker run -v /home//pangolin:/app my-image ```

在 WSL2 后端下运行时,切勿在 Docker 卷中使用 \\wsl$ 或 Windows 路径(如 /mnt/c/...)。这不受支持,可能导致性能低下或报错。当项目位于 WSL2 文件系统内并使用 Linux 路径挂载时,文件监视和热重载可以原生正常工作。

建议使用 VS Code Remote - WSL 扩展或 VS Code Remote - SSH 扩展,从 WSL/远程文件系统直接在 VSCode 中打开项目文件夹,实现无缝开发。

参考链接:

- WSL Docker Best Practices - Use WSL for Development - WSL2 Setup

组件开发

Gerbil

- Go 1.25 - `make local`

Newt

- Go 1.25 - `make local`

Olm

- Go 1.25 - `make local`

此页面有帮助吗?

评论 (0)