第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/
更多信息见下方参考链接部分。
从 Windows 访问 WSL2 文件:
- 可以通过 UNC 路径 \\wsl$\
如何在 Docker 容器中挂载 WSL2 文件:
- Docker 卷始终使用 WSL2 内部的绝对 Linux 路径,这是唯一获得 Docker 完全支持并推荐的方式。
正确的 Docker Compose 示例:
```
services:
app:
volumes:
- /home/
正确的 docker run 示例:
```
docker run -v /home/
在 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`
此页面有帮助吗?